Codebase tour

Start with packages/engine/src/layout.ts. It is the architectural spine: preparation, measurement, placement, routing, materialization, and framing are visible without knowing their internals.

flowchart LR
  Prepare["registry.prepare()"] --> P["PreparedFamily"]
  P --> Measure["measureIR()"] --> M["MeasuredGraph"]
  M --> Place["placeGraph()"] --> L["Placement"]
  L --> Route["routePlacement()"] --> R["RoutedGraph"]
  R --> Mat["materializeGraph()"] --> MG["MaterializedGraph"]
  MG --> Frame["frameDocument()"] --> NGD["NGD"]

Functions are actions; the boxes between them are the typed representations passed forward.

Keep one input beside the code

Use fixtures/architecture/easy.json. It exercises a schema, a family plugin, measured nodes, clustered placement, shared routing, notation, and framing without being visually overwhelming.

Follow the calls

1. Prepare the family. FamilyRegistry.prepare() finds the definition by kind, validates the program, lowers it to GraphIR, and resolves its placement and notation choices. 2. Measure the content. measureIR() dispatches each shape to its measurer and records exact node and edge-label extents. Wrapping becomes final here. 3. Choose coordinates. placeGraph() dispatches the family’s PlacementSpec. Every strategy returns the same Placement contract. 4. Finalize routes and labels. routePlacement() honors shared, authored, or hybrid route ownership, then places edge labels against final lines. 5. Create neutral elements. materializeGraph() joins content, geometry, notation, colour roles, and icon catalogue ids. It does not move anything. 6. Frame the document. frameDocument() translates copies into one coordinate space, adds title and legend geometry, and emits NGD. 7. Observe the boundary. Harness renderSvg() switches on NGD element kind, assigns layers, and serializes. It never measures or lays out.

What each representation guarantees

Representation	Newly guaranteed	Still absent
SemanticProgram	Strict, reference-safe user input	Geometry
GraphIR	Shared semantic vocabulary	Sizes and coordinates
MeasuredGraph	Exact content extents	Coordinates
Placement	Nodes/groups placed; route ownership explicit	Final notation
RoutedGraph	Connector and edge-label geometry final	Renderer markup
MaterializedGraph	Neutral NGD elements and semantic paint	Canvas translation
NGD	Complete resolved scene graph	Nothing a renderer should infer

Next: understand the pipeline’s ownership rules.