New Bring your own storage. Keep your diagrams in your own private GitHub repository, on Pro and Team.Bring your own storage on GitHub, for Pro and Team. Learn more about bring your own storage

Layout Engine

Zindex ships with a built-in layout engine. Agents describe what the diagram contains - nodes, edges, the relationships between them - and the engine figures out where each element should sit, how each edge should route around obstacles, and where each label should land.

The engine is implemented from scratch with zero external layout dependencies. It uses a Sugiyama-style layered layout pipeline (the same family of algorithms behind tools like Graphviz and Mermaid) and runs deterministically: identical input always produces identical output.

Building an agent integration? The skill’s authoring guide covers writing scenes: element kinds, families, auto-layout, constraints, styles and icons. The Zindex skill covers the edit loop.

Why this exists

Most diagram tools assume the human knows where every box and line goes. That assumption breaks down for agents. An LLM generating an architecture diagram knows the services and the connections, but asking it to also produce pixel-perfect coordinates is asking for a worse diagram and a worse use of tokens.

The layout engine inverts the contract: agents describe the graph, the engine handles the geometry. Agents that want pixel control can still provide explicit layout on individual elements - the engine respects user-supplied positions and fills in the gaps; a later edit moves a positioned node only in the cases Positions are kept lists, such as making room for a node that grows. This mixed mode is the most common pattern in practice: pin the critical elements, let the engine arrange the rest.

What you get

What auto-layout handles and what it doesn’t

Auto-layout is powerful but has a specific scope. Understanding the boundary prevents frustration:

Auto-layout handles (no coordinates needed):

Auto-layout also handles frames and containers:

What still needs explicit coordinates:

The rule of thumb: omit coordinates from everything. The engine auto-positions nodes, edges, frames, activation bars, and fragments. Provide explicit layout only when you need pixel-precise control or a specific spatial arrangement the planner can’t infer from the graph structure.

Positions are kept

A saved diagram’s nodes stay where they are, unless:

The engine records each position it chooses in the node’s layout, and every later edit starts from those positions:

Making room

When a node is drawn bigger than the box its layout gives it, the engine moves the nodes in its way just far enough to keep the gap they had. A larger gap absorbs the push, so nodes past it stay where they are. The gap kept is at most the drawing’s spacing:

The engine stores every node it moves, and every node that grew to fit its content, at the size it is drawn, whether it pushed something or not. A growth of 1 px or less isn’t stored, and an autoSize height never is. The save’s changed lists the moved and grown nodes under updated.

A node whose edges dock on a smaller box than it draws (Element types: Node size and wrapped text lists these nodes) is the exception. It is stored only where the engine places or moves it, an edit measures it again, or its growth pushes a neighbor or a frame border.

A node grows when:

How the push works:

What doesn’t push:

NODE_OVERLAP_DETECTED still reports the overlaps the engine can’t make room for: coordinates an agent writes, overlaps already in the document, and a node with a relative layout in the way. Its fix names a node drawn bigger than its layout.

A saved version whose node layout is smaller than the node is drawn shows the stored size until an edit stores the drawn size, and lists the node under updated. That edit can move the node’s neighbors, even when it didn’t name them, and changed lists them. Stored images of earlier versions don’t change.

Laying out again

To lay out again, send autoLayout; the engine keeps the new positions too. { "op": "autoLayout" } lays out every node, as on a new diagram, and sizes the canvas to fit. In architecture, flowchart, workflow, entity-relationship and UI flow diagrams, and diagrams without a family, every frame but a pool, a lane or a fragment drops its own layout and is laid out with its members, fitted round them, as a frame written without a layout is. { "op": "autoLayout", "elements": ["cache"] } places only the named nodes again, around the others, and keeps every frame’s layout. elements names nodes only. A new layoutStrategy or diagramFamily set with updateScene, or removing one, lays out every node too, the same way.

The engine lays out every node only on a new diagram whose nodes have no positions, on autoLayout without elements, and after updateScene changes or removes layoutStrategy or diagramFamily. The last two move nodes an agent positioned as well, except the members of frames that keep their own layout: pools, lanes and fragments, and every frame in an org chart or network. Those members keep their positions, the engine places the other nodes around them, and the canvas keeps its size. Apart from frames an edit adds or deletes, an order constraint it adds, the column a new node’s edge label pushes (Positions are kept), the room a task an edit adds to a pool or moves to another lane takes (Pools and lanes), and the room an edit takes in an AWS or Google Cloud diagram’s rows and columns for what it adds (AWS architecture diagrams, Google Cloud architecture diagrams), every other save places only the nodes that have no position yet.

Pools and lanes

A process with lanes needs no coordinates. Write a frame with containerType: "pool" whose children are frames with containerType: "lane", list each task, event and gateway in its lane’s children, and leave layout off all of them. In the layered families (architecture, flowchart, workflow, entity-relationship and UI flow diagrams, and diagrams without a family) the engine lays them out as BPMN tools such as bpmn-js and yFiles do:

Rendering: Lane and pool rendering shows how they are drawn.

Edits keep the picture. Nodes already placed stay where they are, and the engine makes only the room a change needs:

The engine stores every node these moves place in its layout, and the edit’s changed lists them, as it lists the nodes making room moves.

Routing. A sequence flow crosses lane borders freely: a lane of the pool that holds an end of the flow isn’t an obstacle to it, and lane borders stay unbroken where flows cross them. A message flow crosses the lanes of the pools it connects and keeps clear of other pools. A pool’s or lane’s header strip counts as its title, so edges keep off it as they keep off other frames’ titles (Edge routing).

In org charts and network diagrams, whose layouts place nodes without regard to frames, the engine still draws pools and lanes round their members: each lane grows to hold its members and pushes the lanes after it, but columns aren’t shared and POOL_FLOW_DIRECTION isn’t reported.

What pools and lanes don’t do:

Layers

A stack of layers needs no coordinates. Write each layer as a frame with containerType: "layer". List its cards, and any plain frames that stand as sub-groups, in its children. List the layers top to bottom in one frame’s children; layers at the root stack in the order they appear in elements. Leave layout off the layers and their cards. In architecture diagrams and diagrams without a family, the engine stacks the layers as rows in the order listed and draws each one solid, so a dashed sub-group reads as nested in it.

What it doesn’t do:

A saved stack keeps every card where it is, so it draws the same each time. A saved stack whose top row’s first card stands nearer a layer’s left edge than the title needs is drawn with its layers wider to the left, on any draw. A saved stack with a line between two cards that passes through a layer is drawn with its layers wider on the right (the bottom in a stack of columns), on any draw, where no other layer already reaches that far (above). No card moves in either case. An edit moves a saved card only to make room:

A card an edit adds in no layer is placed by the diagram’s general rules, next to its neighbors, with the stack’s cards in place: it doesn’t stand above or below the stack as in a new layout. List it in a layer, or send autoLayout without elements, which moves every node.

AWS architecture diagrams

An AWS diagram needs no coordinates. Write diagramFamily: "architecture" (or no family), frames for AWS’s groups with their presets nested as AWS nests them, aws.cloud > aws.region > aws.vpc > aws.az > aws.subnet.public and aws.subnet.private, nodes with aws:* icons listed in the frame they run in, and leave layout off all of them. When an architecture diagram, or one without a family, has an AWS Cloud, Region, VPC, Availability Zone or subnet preset, the engine arranges it containment first, as AWS’s reference diagrams draw it and as Lucidscale and AWS’s diagram-as-code place cloud containers by type before drawing the edges:

A diagram can start at AWS Cloud, a Region or a VPC: a VPC with no Region or AWS Cloud around it is arranged the same way. A Region that lists Availability Zones or subnets directly arranges them as a VPC would, with no VPC frame drawn: the AZs as columns and the subnets as rows, below any VPCs it lists. With no VPC border, nothing docks on one: a gateway or load balancer the Region lists joins its column, so list those in a VPC. A subnet a Region lists directly also gets the warning AWS_GROUP_NESTING. An Availability Zone or a subnet that no VPC or Region lists, such as one in AWS Cloud or at the top, is laid out as any frame, so put AZs and subnets in a VPC. This scene draws two AZs with a public and a private subnet each, the internet gateway on the VPC’s border over the load balancer between the AZs, Route 53 above the Region and the uploads bucket beside the VPC:

{
  "schemaVersion": "0.1",
  "diagramFamily": "architecture",
  "scene": { "id": "bookings-aws", "title": "Bookings on AWS", "canvas": { "width": 1200, "height": 900 } },
  "elements": [
    { "id": "cloud", "kind": "frame", "containerType": "aws.cloud", "title": "AWS Cloud", "children": ["route53", "region"] },
    { "id": "region", "kind": "frame", "containerType": "aws.region", "title": "Region us-east-1", "children": ["vpc", "uploads"] },
    { "id": "vpc", "kind": "frame", "containerType": "aws.vpc", "title": "VPC 10.0.0.0/16", "children": ["igw", "alb", "az_a", "az_b"] },
    { "id": "az_a", "kind": "frame", "containerType": "aws.az", "title": "Availability Zone A", "children": ["pub_a", "app_a"] },
    { "id": "az_b", "kind": "frame", "containerType": "aws.az", "title": "Availability Zone B", "children": ["pub_b", "app_b"] },
    { "id": "pub_a", "kind": "frame", "containerType": "aws.subnet.public", "title": "Public subnet", "children": ["nat_a"] },
    { "id": "pub_b", "kind": "frame", "containerType": "aws.subnet.public", "title": "Public subnet", "children": ["nat_b"] },
    { "id": "app_a", "kind": "frame", "containerType": "aws.subnet.private", "title": "Private subnet", "children": ["task_a", "writer"] },
    { "id": "app_b", "kind": "frame", "containerType": "aws.subnet.private", "title": "Private subnet", "children": ["task_b", "reader"] },
    { "id": "users", "kind": "node", "nodeType": "actor", "label": "Customers", "icon": "aws:users" },
    { "id": "route53", "kind": "node", "nodeType": "service", "label": "Amazon Route 53", "icon": "aws:route53" },
    { "id": "igw", "kind": "node", "nodeType": "service", "label": "Internet gateway", "icon": "aws:internet-gateway" },
    { "id": "alb", "kind": "node", "nodeType": "service", "label": "Application Load Balancer", "icon": "aws:application-load-balancer" },
    { "id": "nat_a", "kind": "node", "nodeType": "service", "label": "NAT gateway", "icon": "aws:nat-gateway" },
    { "id": "nat_b", "kind": "node", "nodeType": "service", "label": "NAT gateway", "icon": "aws:nat-gateway" },
    { "id": "task_a", "kind": "node", "nodeType": "service", "label": "API task", "icon": "aws:ecs-task" },
    { "id": "task_b", "kind": "node", "nodeType": "service", "label": "API task", "icon": "aws:ecs-task" },
    { "id": "writer", "kind": "node", "nodeType": "database", "label": "Aurora writer", "icon": "aws:aurora" },
    { "id": "reader", "kind": "node", "nodeType": "database", "label": "Aurora reader", "icon": "aws:aurora" },
    { "id": "uploads", "kind": "node", "nodeType": "objectStorage", "label": "S3 uploads", "icon": "aws:s3" },
    { "id": "e_dns", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "route53" }, "label": "DNS" },
    { "id": "e_https", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "igw" }, "label": "HTTPS" },
    { "id": "e_igw", "kind": "edge", "from": { "elementId": "igw" }, "to": { "elementId": "alb" } },
    { "id": "e_alb_a", "kind": "edge", "from": { "elementId": "alb" }, "to": { "elementId": "task_a" } },
    { "id": "e_alb_b", "kind": "edge", "from": { "elementId": "alb" }, "to": { "elementId": "task_b" } },
    { "id": "e_sql_a", "kind": "edge", "from": { "elementId": "task_a" }, "to": { "elementId": "writer" } },
    { "id": "e_read_b", "kind": "edge", "from": { "elementId": "task_b" }, "to": { "elementId": "reader" } },
    { "id": "e_repl", "kind": "edge", "from": { "elementId": "writer" }, "to": { "elementId": "reader" }, "label": "replication", "style": { "dash": [6, 4] } },
    { "id": "e_upload", "kind": "edge", "from": { "elementId": "task_b" }, "to": { "elementId": "uploads" }, "label": "originals" }
  ]
}

Customers lie before AWS Cloud, on the left, but the internet gateway’s line inside runs to the load balancer between the AZs, so the gateway docks on the VPC’s top: from the left, that line would cross AZ A’s public subnet and its NAT gateway. With one AZ, or with the load balancer in a row above the AZs, the same gateway would dock on the left, facing Customers.

Every group’s box comes from its members on every layout, so the positions the engine stores redraw the same picture. A preset’s own layout is a minimum anchored at its corner: where its members need more room, such as a hand-placed diagram whose rows don’t fit the presets’ headers, the members move down or right, rows push the rows after them and wider AZs push what lies right of them, and the save’s changed lists what moved. order constraints order nodes within one row or column: leftOf and rightOf within a subnet’s row or AWS Cloud’s row, above and below within a Region’s column or an outside column. One between nodes of different rows or columns, and sameRank, is ignored. extensions.autoGroup draws no bands here.

Edges are routed after the layout. They cross a VPC’s Availability Zones as a sequence flow crosses a pool’s lanes: an edge with an end inside the VPC can run across an AZ that holds neither of its ends, such as the load balancer’s lines into each AZ, replication between AZs, or a write to another AZ’s database, and keeps 16 px off an AZ’s border it runs beside when a route with as many bends can. A subnet, or any other group that holds neither end, is kept off as any frame is (Edge routing). A fork’s branches, lines drawn alike, run on one trunk until they part, with a dot there. Lines drawn differently don’t share a trunk, except where noted below (Lines drawn differently). Lines of different edges that must run side by side keep 16 px apart where there is room. An edge between two members of one row that would pass another member between them runs in a lane under the row; when that edge ends in an arrowhead, it rises from the lane into the side of its target facing its source, so the arrowhead meets the icon. A line from a subnet’s member that would pass a row-mate on its way to the Region’s column, or to an item beside the VPC, runs in that lane too, where the lane and the way on are clear. Edges keep off the groups’ headers, and edge labels keep out of the band each header spans.

The rules below are for AWS diagrams. The passes behind Group borders, Crossed labels, End legs, Other ways apart, Clear of nodes and borders, Lines drawn differently and Labels also run in Google Cloud diagrams, with Google’s groups in place of AWS’s (Google Cloud architecture diagrams):

A border or first-turn move is kept only when it adds no crossing and keeps nodes, headers and labels their room. A move that parts two lines reading as one doesn’t land a line within 8 px of a frame’s border. An end-leg move is kept only when it adds no crossing, keeps off every node (see “Clear of nodes and borders” above), leaves fewer pairs of lines closer than 16 px and makes no new pair. It is also refused when it would lay a segment on another edge’s line, drawn as one line that forks, or leave a line seeming to run through an icon (below). Otherwise the line stays as routed. An end on an AWS icon’s west face level with an end on its east face reads as one line through the icon, so one of the two moves along its face toward its line’s turn; a straight line’s end has no turn, so when the other end can’t move, the straight line moves whole, both ends together. A chain of straight lines through an icon stays on one line. In any diagram, the ends on an AWS icon drawn alone are spread too: ends on one face keep 16 px apart, within the face’s middle half when it holds them, else along the rest of it; a top or bottom face that can’t hold them sends an end whose route comes from beside the icon round to that side; a short jog just before an end moves with the end, so its last leg runs straight; and an end on a round icon (a gateway, load balancer or endpoint) meets its circle (Rendering: AWS icons). An arrowhead into an icon from below meets a side of the icon, not the label under it, when a route one bend longer gets there; a straight line from below keeps the bottom. In any diagram with an AWS group or a node with an aws:* icon, in any family, an edge that sets no endArrow and whose edgeType is unset, default, or an er.*, network.* or org.* type ends in AWS’s open arrow, an open V; the workflow, sequence and UI flow edge types keep their own arrowheads (Element types: Edge types).

Edits keep every position, except those of the two nodes an order constraint they add finds the wrong way around (below), and grow rows and columns, as a table inserts a row or a column. The Region’s column also moves right, as one, when an edit places nodes in it or joined to it by an edge (nodes it adds, or the two an order constraint places again) and leaves a labeled line from a VPC into it too little clear run, as on a fresh layout (above); what lies right of the Region moves right with it:

The save’s changed lists every node these moves place, and a compare lists them as changed; the colored diff paints amber only what changed besides its place (Rendering: Visual diff rendering).

What the cloud layout doesn’t do:

Google Cloud architecture diagrams

A Google Cloud diagram needs no coordinates: leave layout off every frame and node. Write diagramFamily: "architecture" (or no family) and frames for Google’s groups with their presets, nested as Google nests them: gcp.cloud > gcp.project (optional) > gcp.region > gcp.subnet > gcp.tier or gcp.instanceGroup. Write the services as nodes with gcp:* icons, each listed in the frame it runs in, and the users outside gcp.cloud. Draw the VPC network round its subnets, and each zone round its cards, as spanning frames with spans.

When an architecture diagram, or one without a family, has a gcp.cloud, gcp.region or gcp.subnet frame, the engine arranges it top to bottom, as Google’s Architecture Center diagrams draw it:

A diagram can start at the boundary or at a Region: a Region with no boundary round it is arranged the same way. This scene draws two mirrored Regions, each subnet a web tier over a database tier in two zones, the load balancer over the gap between the Regions and the backups bucket below them:

{
  "schemaVersion": "0.1",
  "diagramFamily": "architecture",
  "scene": { "id": "orders-gcp", "title": "Orders on Google Cloud", "canvas": { "width": 1200, "height": 900 } },
  "elements": [
    { "id": "cloud", "kind": "frame", "containerType": "gcp.cloud", "title": "Google Cloud", "children": ["glb", "region_1", "region_2", "backups"] },
    { "id": "region_1", "kind": "frame", "containerType": "gcp.region", "title": "Region: us-central1", "children": ["subnet_1"] },
    { "id": "subnet_1", "kind": "frame", "containerType": "gcp.subnet", "title": "Subnet 10.10.0.0/20", "children": ["web_1", "db_1"] },
    { "id": "web_1", "kind": "frame", "containerType": "gcp.instanceGroup", "title": "Web tier", "children": ["web_1a", "web_1b"] },
    { "id": "db_1", "kind": "frame", "containerType": "gcp.tier", "title": "Database tier", "children": ["primary"] },
    { "id": "region_2", "kind": "frame", "containerType": "gcp.region", "title": "Region: us-east1", "children": ["subnet_2"] },
    { "id": "subnet_2", "kind": "frame", "containerType": "gcp.subnet", "title": "Subnet 10.20.0.0/20", "children": ["web_2", "db_2"] },
    { "id": "web_2", "kind": "frame", "containerType": "gcp.instanceGroup", "title": "Web tier", "children": ["web_2a", "web_2b"] },
    { "id": "db_2", "kind": "frame", "containerType": "gcp.tier", "title": "Database tier", "children": ["replica"] },
    { "id": "vpc", "kind": "frame", "containerType": "gcp.vpc", "title": "VPC", "spans": ["subnet_1", "subnet_2"] },
    { "id": "zone_1a", "kind": "frame", "containerType": "gcp.zone", "title": "us-central1-a", "spans": ["web_1a", "primary"] },
    { "id": "zone_1b", "kind": "frame", "containerType": "gcp.zone", "title": "us-central1-b", "spans": ["web_1b"] },
    { "id": "zone_2a", "kind": "frame", "containerType": "gcp.zone", "title": "us-east1-a", "spans": ["web_2a"] },
    { "id": "zone_2b", "kind": "frame", "containerType": "gcp.zone", "title": "us-east1-b", "spans": ["web_2b", "replica"] },
    { "id": "users", "kind": "node", "nodeType": "actor", "label": "Customers", "icon": "gcp:users" },
    { "id": "glb", "kind": "node", "nodeType": "service", "label": "Global load balancer", "icon": "gcp:cloud-load-balancing" },
    { "id": "web_1a", "kind": "node", "nodeType": "service", "label": "Web server 1", "icon": "gcp:compute-engine" },
    { "id": "web_1b", "kind": "node", "nodeType": "service", "label": "Web server 2", "icon": "gcp:compute-engine" },
    { "id": "web_2a", "kind": "node", "nodeType": "service", "label": "Web server 1", "icon": "gcp:compute-engine" },
    { "id": "web_2b", "kind": "node", "nodeType": "service", "label": "Web server 2", "icon": "gcp:compute-engine" },
    { "id": "primary", "kind": "node", "nodeType": "database", "label": "Orders primary", "icon": "gcp:cloud-sql" },
    { "id": "replica", "kind": "node", "nodeType": "database", "label": "Orders replica", "icon": "gcp:cloud-sql" },
    { "id": "backups", "kind": "node", "nodeType": "objectStorage", "label": "Backups", "icon": "gcp:cloud-storage" },
    { "id": "e_https", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "glb" }, "label": "HTTPS" },
    { "id": "e_glb_1", "kind": "edge", "from": { "elementId": "glb" }, "to": { "elementId": "web_1" } },
    { "id": "e_glb_2", "kind": "edge", "from": { "elementId": "glb" }, "to": { "elementId": "web_2" } },
    { "id": "e_sql_1", "kind": "edge", "from": { "elementId": "web_1" }, "to": { "elementId": "primary" } },
    { "id": "e_sql_2", "kind": "edge", "from": { "elementId": "web_2" }, "to": { "elementId": "replica" } },
    { "id": "e_repl", "kind": "edge", "from": { "elementId": "primary" }, "to": { "elementId": "replica" }, "label": "replication", "style": { "dash": [6, 4] } },
    { "id": "e_backup", "kind": "edge", "from": { "elementId": "primary" }, "to": { "elementId": "backups" }, "label": "backups" }
  ]
}

A Google group’s box comes from its members on every layout, and a save stores only the members’ places. A group’s own layout is a minimum anchored at its corner. The frames that share its span grow with it: a tier given a wider box widens every tier of its Region, and a taller one its row in every Region. extensions.autoGroup draws no bands here.

A saved Google Cloud diagram is drawn with the frames the layout gives its members. A Region saved with less than 24 px under what it holds is drawn lower, and the rows under the Regions move down with it. No node inside a Region moves, and the next edit saves the rows where they stand.

order constraints act within one row: leftOf and rightOf order the items of a global row, a Region’s row, a row of nodes in a subnet or the outside row. A tier’s cards keep their zones’ columns, and the other relations are ignored (Constraints: order).

Edges are routed after the layout, as Google draws its lines:

Draw an edge to a tier rather than to each of its cards, as Google’s diagrams do: an edge to each card draws an arrowhead into each one.

Edits keep every position and grow rows, zone columns, Regions and project boxes, as a table inserts a row or a column. What lies past a growth moves by exactly the growth. An edit also moves these saved nodes:

Each kind of edit places what it adds:

The save’s changed lists every node these moves place, and a compare lists them as changed.

What the arrangement doesn’t do:

Numbered steps

An edge’s step, a whole number from 1 to 99, draws a numbered badge at the start of its line, as AWS’s architecture diagrams number the path a request takes. Its stepText adds the edge’s line to a step list beside the drawing. Steps are drawn in every family, and a sequence diagram can also number every message itself (Numbered messages). Rendering: Step badges shows how they look.

{ "id": "e_upload", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "api" }, "label": "HTTPS", "step": 1, "stepText": "The customer uploads a photo to the API." }

In every family but sequence diagrams:

In every family:

What steps don’t do:

Numbered messages

A sequence diagram draws a message’s number as Mermaid does: a numbered badge centered on the start of its arrow, on the sender’s lifeline. An arrow that leaves an activation bar starts on the bar’s face, and its badge is centered on that bar’s axis, half a bar back from the face, as is a self-message’s on the bar its loop leaves. Of stacked bars, that is the one whose face the arrow leaves (Rendering: Lifeline rendering). An arrowhead at the start points at the badge (Rendering: Step badges).

To number every message, set autonumber in the document’s top-level extensions, beside showLifelineFeet:

{ "schemaVersion": "0.1", "diagramFamily": "sequence", "extensions": { "autonumber": { "start": 10, "increment": 10 } }, "scene": { "title": "Login" }, "elements": [] }

What numbering doesn’t do:

Spanning frames

A frame written with spans instead of children is drawn round the nodes and frames it names, outside the containment tree, as AWS draws an Auto Scaling group or a security group across Availability Zones. It holds nothing: each target keeps its own frame. Spanning frames are drawn in architecture diagrams and diagrams without a family.

{ "id": "asg", "kind": "frame", "containerType": "aws.autoScalingGroup", "title": "Auto Scaling group", "spans": ["app_a", "app_b"] }

The box is one rectangle, so a node inside it that it doesn’t span reads as spanned: the warning SPAN_COVERS_NODE names it. Add the node to spans when it belongs there, or span only targets that sit together. autoLayout places every node again with a margin round each target, which clears a node pressed against one but not one between two.

What spanning frames don’t do:

The pipeline

A layout of every node runs the scene through five phases. Each phase has well-defined inputs and outputs and can be inspected in isolation. When some nodes already have positions, phases 2 to 4 place only the others, next to their neighbors (moving placed nodes only in the cases Positions are kept lists); measurement, edge routing and label placement run on every save.

1. Measurement

Every node and every edge label is measured before any positioning happens. Node sizes come from intrinsic measurements (text width, padding, fixed shape constraints). Edge labels are measured to the pixel so the planner can leave room for them between ranks: the label as drawn, its backdrop’s padding, the arrowheads and ER glyphs at both ends at the widest theme stroke, both nodes’ outlines and, where the border of a frame laid out with its members (or, for a node placed later, any frame) lies between the ranks, 6 px of clear space either side of it. A label wider than 200 px is measured wrapped, narrower and taller: a flow left to right reserves its width between ranks, and one top to bottom its height.

The gap holds no room for a fan-out’s fork, so a label on a short branch past the fork can still sit near its sibling’s line or over its own arrowhead.

A layout of saved positions keeps its gaps, so there a label can still cross a frame’s border or cover its own arrowhead when the gap is too narrow: a new edge between two saved nodes, a longer label on a saved edge, a saved label wider than 200 px, or a label that only comes within 6 px of a border. A new node’s label that needs more room pushes the column it joins (Positions are kept).

An edge with a step also keeps room for its badge beside its label when the engine lays out every node (Numbered steps). autoLayout without elements lays every node out again with this room, moving the nodes you positioned (Laying out again).

2. Layer assignment

Nodes are assigned to ranks (rows for TB, columns for LR) based on the directional flow of the graph. Cycles are detected and broken using a feedback arc set heuristic, so the algorithm always produces a finite layering even on cyclic input.

3. Crossing reduction

Within each layer, nodes are reordered to minimize the number of edges that cross. The algorithm uses the median heuristic: each node’s preferred position is the median index of its neighbors in the adjacent layer. The down sweep aligns each layer with its predecessors, the up sweep aligns each layer with its successors, and a fixed number of iterations is enough to converge for any normal graph.

When two nodes have nearly the same median position, the algorithm tiebreaks by input order. This preserves natural reading order: if you declare api1 before api2, they’ll appear in that order even when the heuristic could swap them to save a single crossing. Substantial median differences still trust the heuristic, so this never produces a worse layout - it just prevents counter-intuitive reorderings.

4. Coordinate assignment

Once layer order is fixed, each node gets its position along its layer in three steps:

So a chain of single-parent / single-child nodes is one straight line, and a worker connected only to a job queue sits exactly under it. A node with several children lines up with one of them. When each child lines up with another node or would cross a pair already lined up, the node sits among them instead. Nodes in a rank keep the layout’s node spacing apart (Aesthetic scoring says which spacing that is). What it doesn’t line up:

A flowchart (diagramFamily: "flowchart") is placed by its decisions’ answers (Diagram families: Flowcharts):

A decision with no way on keeps the decision rules above. So do the checks of an else-if ladder, and every decision in a flowchart whose frames are laid out with their members; that flowchart’s loops still keep to the low side (Diagram families: Flowcharts).

The canvas-aware spread then scales every gap by one factor, so a straight chain stays straight and a target clear of a decision’s line stays clear.

In a diagram whose frames are laid out with their members, each frame is placed with them. In layer assignment its members are pulled into neighboring ranks, and in crossing reduction it moves as one block among its siblings. Here its two borders are positions of their own, solved with the nodes, so members keep the frame’s padding and other nodes stay out of it.

In such a diagram, chains line up too, across a frame’s border where an edge enters or leaves the frame along the flow. A member doesn’t line up with a node beside its frame in a rank the frame spans. Long edges don’t come first there, and a decision lines up with one of its branches as any node does, its targets left where they are placed.

In an AWS diagram the cloud layout arranges, some frames are each placed as one block, such as a generic frame outside the VPCs, or a serverless diagram’s AWS Cloud or Region (AWS architecture diagrams lists them). One that holds no frame of its own is laid out as a diagram without frames, so its chains line up as above, long edges first, and its decisions follow the rules above. One that holds frames lines up its chains as a diagram whose frames are laid out with their members does (above). The cloud layout places the rest by its own rules: a VPC’s rows and Availability Zones, a Region’s column and the items outside AWS Cloud.

5. Edge routing

After every node has a position, edges are routed. The router walks a ranked list of anchor candidates for each edge. When the source lines up with the target (its center inside the target side’s range), the same-axis pair of step 3 leads, so the edge runs straight; when it doesn’t but the two facing sides overlap, the router first tries a straight line through the overlap, and when a node in between blocks the straight line, a straight line beside that node (Where an edge enters its target):

  1. The visually preferred centered entry: leave the source perpendicular to the line connecting the centers, enter the target through a centered N/S or E/W face. The L’s terminal leg lands on the target’s center column / row.
  2. If the centered L collides with an obstacle, try a 5-point step path that routes through the gap between source and target while still entering the target perpendicular to a centered face.
  3. If both fail, fall back to the same-axis pair (E↔W or N↔S) so the bend hugs the target’s edge. Its target end runs straight across at the source’s coordinate when that lands clear of the target side’s corners (8 px, more past a rounded corner), and otherwise enters the side’s center; a BPMN sequence flow or UI-flow transition enters the center unless it is less than 16 px off (Where an edge enters its target). When no candidate is clear of obstacles, the router searches for a route round the nodes, and crosses a node only where none exists.

A frame, whatever its containerType, is a container for the edges that end inside it and an obstacle for the rest: an edge between two children of a swimlane is never reported as colliding with the lane itself, and an edge with neither end in a frame goes round it, as the list below says. Every lane of a pool that holds an end of an edge is a container for that edge too, so a flow between two lanes crosses the lanes between them (Pools and lanes). So is every Availability Zone of a VPC that holds an end of an edge, in a diagram the cloud layout arranges, so an edge crosses the AZ columns between its ends; the subnets in them are not (AWS architecture diagrams). Groups are neither. Frames and groups are also valid edge endpoints: when an edge’s from or to references a frame ID, the router computes anchors against the frame’s bounds and the arrow terminates at the frame’s border, exactly as it would for a node target. This is the platform mechanism behind the edges-to-a-group-as-a-whole authoring convention.

What the router keeps to around frames:

After routing, every path but a straight or curved edge’s (whose ends lie exactly on their outlines) is run through a simplification pass that snaps near-equal coordinates, drops consecutive duplicates, and removes colinear midpoints. This eliminates the sub-pixel wiggles that come from planner-driven width mismatches and keeps arrow markers oriented cleanly.

A channel routing refinement then detects interior edge segments that overlap or run in parallel within the same corridor (from different edges) and spreads them into distinct tracks. This prevents multiple edges from visually overlapping when they share the same horizontal or vertical segment. Edges that come the same way to one point, such as a bundle leaving one point of a node before it forks, are one track in every channel, as ELK routes the edges of one port as one hyperedge: they stay on one line and part only where their routes do. Different bundles, edges that share no end point, keep off one line where they would run end to end with their ends under 32 px apart and no node or frame border between, as Graphviz gives every segment in a channel its own track: they take tracks up to 24 px apart where the channel has room, at least 8 px. Where 24 px would leave an edge label less of its run than it needs (to a frame border or its end), when it had the room on the shared line, the tracks spread less, down to 16 px; a label that still doesn’t fit sits beside its own bend, its padding over the border if need be, rather than over its own line. A fork’s branches keep 9 px apart where the channel has room, so the dots at the fork never touch; in an AWS diagram those drawn alike run on one line until they part instead, and the tracks of different edges keep 16 px apart, not 8, where the channel has room. Two that are further apart, or parted by a node, may share a line; so may the legs that dock on a node. Track spacing is constrained by the available gap between nearby nodes.

A node’s exits that leave one face turn at one depth, so a fan-out reads as one trunk, but only when their risers then keep off one line. Exits that would run one over another keep their own tracks. So do exits that would run end to end with their ends under 32 px apart, except in an AWS diagram the cloud layout arranges.

Labeled exits that leave one face and turn the same way nest as a staircase, so each label sits beside its own line. Each turns past the one before by its label’s width and 12 px either side. They nest only where that crosses no more lines and keeps 16 px from other nodes, and not in an AWS diagram the cloud layout arranges; otherwise they keep the channel’s tracks.

In flowchart, workflow, UI flow, architecture and entity-relationship diagrams, and in a diagram with no family, labeled lines between the same two nodes in neighboring ranks are spread evenly along each node’s side. If that leaves two neighbors nearer than half of one label’s height plus half of the other’s, the lines keep at least that distance plus 8 px apart instead. On a top or bottom side the widths count.

These lines aren’t spaced this way:

The engine grows the two nodes to fit their labels in two cases: a layout of every node (Laying out again), and a node an edit adds. A node that keeps its saved size keeps its side. If that side is too short, every gap between the lines shrinks in the same proportion, and a label can land on another line (Label placement).

Canvas-aware spread

When scene.canvas is set and the laid-out content uses substantially less space than the canvas allows, the planner scales node positions and rank centers around their centroid so the layout fills the available area. Auto-spread only widens gaps, never narrows them. This means agents who set a larger canvas get a layout that uses the space, instead of content clustered into one corner. Spread is capped (3x maximum scale factor) to prevent absurd spacing on tiny graphs that happen to live in a generous canvas.

So a canvas much larger than the drawing needs leaves wide gaps between nodes. Leave scene.canvas out, or set it near the content’s size, for a compact drawing.

A diagram whose frames the planner lays out with their members (see frames above) is not spread: wider gaps would pull members away from their frame’s border and leave frames hollow. It keeps the node and rank spacing, centered in the canvas, and a canvas far too large for it is tightened (below). Pools and lanes count as such frames. A drawing with a pool that has its own layout isn’t centered either: the first such pool’s corner stays where its layout puts it (Pools and lanes). Set layoutStrategy.nodeSpacing and rankSpacing for more room.

Placing a text or an image yourself doesn’t stop the planner spreading nodes into a larger canvas. Neither does a frame with its own absolute layout (What auto-layout handles and what it doesn’t). A pool or a lane is the exception: the planner lays it out with its members, with or without a layout, so the rule above applies.

Spread happens when the engine lays out every node. After the first save the nodes keep their positions (Positions are kept), so a larger canvas set with updateScene adds room on the right and at the bottom; send autoLayout to spread the nodes into it.

Canvas size is a minimum, with per-axis tightening on over-declared canvases

Declared scene.canvas dimensions act as a lower bound: when content exceeds them the engine auto-extends the canvas to fit. When the declared canvas is larger than what node spacing requires, the engine auto-spreads (above) to fill the available area, except in a diagram whose frames are laid out with their members.

When the declared canvas on either axis exceeds the comfortable centered-content size by more than 30% AND the engine lays out every node, the engine tightens that axis to content x 1.4 to avoid shipping with excessive slack. Width and height are tightened independently and per-axis. This is the only path where the engine reduces a declared canvas dimension, and the canvas it picks is saved with the diagram.

A layout in which some nodes already have positions, given by an agent or kept from an earlier save, leaves the declared canvas untouched, and so does one with a text, an image or a frame that has an absolute layout (What auto-layout handles and what it doesn’t). The declared size counts as part of that positioning intent.

Summary:

Auto-spread only widens gaps.

Neither change comes back as a warning: the API returns no info-level drawing diagnostics. Rendering: Render diagnostics describes when each happens and what to change if you want a different size.

Bonus phase: label placement

For each labeled edge, the placer samples positions along every segment of the routed path, beside the line (above or below a horizontal segment, right or left of a vertical one) and on it, which scores below a place beside it on the same run. A slanted line’s label sits on it. A curve’s label prefers the curve’s middle by length: beside it where it runs level, else on it; when no such place is clear, beside it where it runs within 25 degrees of level. A candidate is clear when its knockout, the label’s backdrop, meets no node, previously-placed label, other edge’s line, arrowhead or ER glyph (sized for the widest theme stroke, or the edge’s own stroke when wider, so the place is clear in every theme). A frame’s inside is open to labels, so a label can sit inside a frame that holds an end of its edge instead of being pushed into the gaps between frames. A frame’s border (6 px either side of it, measured from the label’s knockout), its title (for an AWS group or a frame with an AWS icon, a band across the frame’s whole width, as deep as its header) and each node’s outline are obstacles, and so is the space 16 px round the label of a node that draws its label outside its shape (a BPMN event’s or gateway’s name, a UI flow entry or exit point’s, below or above its shape, or the label under an AWS icon drawn alone), a line’s height, so an edge label doesn’t read as that name’s second line. Such a node counts as its shape and that label, not the box round both, so an edge label can sit beside the shape where the label leaves room. So are a sequence fragment’s tab and guard, each operand’s divider and guard, a spanning frame’s header, and a step badge with 10 px round it; a self-message’s label keeps off its own loop. A label that only touches an obstacle is clear of it.

A clear place must also read as its own edge’s. The label sits 6 px from its own line. A node other than its edge’s ends keeps 16 px from the label’s knockout, the room the router keeps between a line and a node. An edge’s own end is exempt only beside the face its line leaves or enters. Nearer a node than that, the label reads as the node’s caption. The layered engines space an edge label from other nodes as they space a node: ELK lays edge labels out as nodes at spacing.nodeNode 20 (its spacing.labelNode 5 is a node’s own captions), dot keeps nodesep about 24 px, dagre 50.

Inside a frame, a label keeps 16 px from the frame’s title, and from the kind an instance group writes opposite it (“Regional MIG”), as from a node’s outside label. Nearer, a label under the title reads as the frame’s second title. A pool’s or lane’s header strip and a fragment’s divider keep 6 px. With no room, a label comes nearer; of two places by one node, the farther wins.

A label also stays out of a frame that holds neither end of its edge, where its line has a clear place outside such frames. Inside one, it reads as a note on what that frame holds. When a pool or a VPC holds an end, its lanes or Availability Zones don’t count: a line crosses them on purpose. Nor does a spanning frame round an end or round a frame that holds one. A sequence message’s label keeps its row instead of these rules (Message rows).

In a Google Cloud diagram, a label keeps off the boundary’s blue, as Google’s reference diagrams do. The blue is the part of gcp.cloud outside the filled groups it holds (projects, Regions, tiers). Where the line has a clear place on one of those groups or outside the boundary, the label goes there. Where it has none, as on Cloud Armor’s line into the load balancer beside it, the label stays on the blue, at the contrast Rendering: Google Cloud edges gives it.

Wrapping is the placer’s last step. A label with no clear place is tried in two lines, then three (or the lines it has, if more), and takes the widest wrap that has a clear place. A label with a clear place keeps it and its box, whatever another label does.

In a Google Cloud diagram the cloud layout arranges, a label also keeps a floor. Its knockout stays 10 px from every other edge’s line and from every card but its edge’s ends, and at least twice as near its own line as any other line. Other diagrams weigh labels without the floor.

Where no place at the measured box is clear, the placer checks the least faulty one. If that place breaks the floor, covers a line or a node, or crosses a border, the label takes the widest wrap whose place does none of these. That place needn’t be clear by the rules below. The wrap can be three lines, with the label sitting on its edge’s own line. A label with a clear place never changes.

A Google label also stays out of a frame’s title row, so it doesn’t read as part of the title. Inside a frame, its middle stands at least its own height (40 px at most) from the middle of the title, wherever along the frame’s width it is. A place in a title’s row isn’t clear.

The floor doesn’t make room. Where lines run closer together than the label is wide, or a drop is shorter than the label is tall, no wrap may fit. The label then takes its least faulty place, which can break the floor. The placer doesn’t move lines for a label.

Only the label’s box changes. The nodes, the rooms the layouts keep for labels (a tier’s lane under a labeled line, a message row) and the routes stay as laid out for the measured box, and the narrower box is placed clear of what stands there.

These labels aren’t narrowed:

A place where only the label’s padding reaches something its text clears isn’t narrowed either: the knockout is trimmed there (Rendering: Contrast). With no clear place at any width, the label takes the place its measured box has, as below.

Parallel lines can run closer together than a label is tall, as on a node’s side too short for them (Edge routing). Such a label has no clear place at any width. It lands on the least faulty place, and its text may cover another line. Shorten the label to give it a clear place.

A clear place keeps other edges’ lines 12 px or more from the label. Beside a vertical segment, no other edge’s horizontal line runs along half the label’s width or more within 30 px above or below it. The knockout covers no stretch of its own line other than the one it labels.

A fan-in whose repeated label is drawn once (EDGE_LABEL_SUPPRESSED_FANIN) is one label’s edges, and their lines don’t count against it. Any other edge with the same label draws its own, clear of the others’ lines like any label. On a segment it shares with other edges (a fan-out’s trunk, a fan-in’s), a label is centered on the stretch only its own edge draws, past the fork.

In every family but sequence diagrams, another edge’s line can also end a label’s own stretch on a horizontal or vertical segment. It does when it crosses that segment and its arrowhead or ER glyph lies within two label heights of the crossing. A label beside that line’s end would read as that line’s, so it is centered on the longest stretch between such crossings, as Esri’s Maplex keeps street labels off intersections. A line that only crosses the segment, its ends farther off, doesn’t end the stretch. On a short run with several such crossings, the label can still sit near one.

The clear candidates are scored by combining segment-centeredness (prefer mid-segment, or mid-stretch on a shared segment) with a longest-segment preference (prefer the most prominent visual run of the edge). A label on an edge out of a diamond (a decision’s or a BPMN gateway’s branch, not an er.relationship’s line) prefers instead the clear place nearest the diamond along its path, within 200 px, on the branch’s first run when it fits there, as flowchart guides write yes and no beside the decision. Branches that share a vertex and split each sit centered on their own arm past the split. The chosen position is then reserved as an obstacle for subsequent placements, so neighboring labels keep visible breathing room.

When no sampled place is clear, the placer tries more places. It tries the label centered in each gap between obstacles along a horizontal or vertical segment, and just past each frame border’s band. Then it tries each place between two samples, 1 px apart. A clean place at least 1 px wide is found wherever it lies; a narrower one isn’t promised.

When no place along an edge is clear (say, an edge that runs only through a gap narrower than its label), the label takes the place with the least serious faults, compared in this order:

  1. The least node and label area covered.
  2. The fewest other edges’ lines under it.
  3. The least arrowhead or ER glyph covered.
  4. The fewest frame borders its text crosses.
  5. The fewest stretches of its own line covered.
  6. The fewest frame borders under only its padding.
  7. In a Google Cloud diagram, the fewest lines and cards nearer than the floor (10 px), or lines less than twice as far as its own line.
  8. In a Google Cloud diagram, the fewest frame titles whose row it stands in, within its own height (40 px at most) of the title’s middle.
  9. In a Google Cloud diagram, the fewest other edges’ straight runs that carry on into it.
  10. The fewest other edges’ lines nearer than 12 px, and those farthest off.
  11. The fewest nodes nearer than 16 px, and those farthest off.
  12. The least frame border band.
  13. The fewest frames around it that hold neither end of its edge.
  14. The fewest Google Cloud boundaries whose blue is under it.

Where the least faulty place has another edge’s line under its knockout, the label takes a place with fewer lines under its text, if there is one. The knockout is trimmed short of the lines only its padding reaches (Rendering: Contrast), so they stay drawn whole. The text keeps 2 px clear of those lines and of its edge’s end nodes. This doesn’t apply to a sequence message’s label or to a label in a Google Cloud diagram the cloud layout arranges.

Where the least faulty place still crosses a frame’s border, two more places are tried. First, beside its line’s end, inside the frame the line enters or leaves, as dot’s headlabel and ELK’s head placement put a label. Its knockout sits 6 px past the arrowhead or the outline the line ends on. The head end is tried before the tail, and only a place clean by every rule above is taken. Then on its own line, slid across the border, while at least 8 px of the line stays under its text. A sequence message, a self-loop and a curve skip both. So a label can still cross a frame’s border, cover a frame’s title or overlap a node.

Labels that still crowd one row (parallel edges whose midpoints line up) then slide along their own edges or step above or below the row, by their own height. A step never leaves a label half over its own line, or more than 14 px from it. It never puts a label onto a Google boundary’s blue, or into a frame its line only passes through, that it wasn’t on already. A label that only crowds another stays beside its own line.

A label that covers another label steps off it even past 14 px from its line, because two texts over each other read as neither. A label moves only to a place clear of nodes, other labels, arrowheads and other edges’ lines, and no worse placed by the fallback’s order, or else stays put. A sequence message’s label keeps its place (Message rows), and two messages between the same lifelines aren’t parallel edges.

Aesthetic scoring

The engine doesn’t just run the pipeline once and hope for the best. It evaluates several layout candidates with different planner parameters and picks the one with the lowest aesthetic penalty score. This happens when the engine lays out every node: on a new diagram whose nodes have no positions, on autoLayout without elements, and after updateScene changes or removes layoutStrategy or diagramFamily, unless members of a pool, lane or fragment with its own layout, or of a frame in an org chart or network, keep their positions. When some nodes have positions, the engine places the others around them in one pass, and the positioned nodes stay where they are, except in the cases Positions are kept lists.

The candidates vary two parameters that have the biggest impact on layout quality: node/rank spacing (how dense or spacious the layout is) and crossing-reduction thoroughness (how many optimization passes the planner runs). One candidate always uses the scene’s own defaults, so the worst case is identical to a single-pass layout. The others use fixed spacings, tighter or wider than the defaults whatever the scene sets, or the scene’s spacing with more optimization passes, so the layout that wins can space nodes and ranks closer or further apart than nodeSpacing and rankSpacing say: they are the spacing the engine aims for, not minimums. In a flowchart, no candidate puts ranks closer than 50 px.

Each candidate is scored on:

The winner’s node positions are saved with the diagram, so later edits start from them instead of choosing again. The entire process is deterministic: same scene always produces the same layout.

For agents, this is invisible - you describe the graph, the engine does the rest. Scoring picks the cleanest of the candidates; the save’s warnings report what is still wrong.

Configuration

The layout engine reads scene.layoutStrategy:

{
  "layoutStrategy": {
    "direction": "TB",
    "nodeSpacing": 60,
    "rankSpacing": 100
  }
}
FieldTypeDefaultDescription
direction"TB" | "BT" | "LR" | "RL""LR", "TB" for flowchartsPrimary flow direction
nodeSpacingnumber30Target pixels between nodes in a rank
rankSpacingnumber80, 50 for flowchartsTarget pixels between ranks

The engine picks how to place nodes from diagramFamily, not from layoutStrategy. The hierarchical pipeline is used by architecture, flowchart, workflow, entityRelationship, uiflow, and diagrams without a family; it reads these three fields, and a field left out takes the default above. Org charts use a tidy-tree planner that runs top to bottom, network topologies use a force-directed layout (since they have no inherent direction), and sequence diagrams use a dedicated time-ordered resolver; none of them reads layoutStrategy. Changing layoutStrategy on a saved diagram with updateScene lays out every node again.

Mixed mode in practice

The most common production pattern is to fix some nodes and let the engine position the rest:

{
  "schemaVersion": "0.1",
  "scene": { "id": "mixed-arch", "canvas": { "width": 1000, "height": 600 } },
  "layoutStrategy": { "direction": "LR" },
  "elements": [
    {
      "id": "gateway",
      "kind": "node",
      "nodeType": "service",
      "label": "API Gateway",
      "layout": { "mode": "absolute", "x": 50, "y": 250, "width": 160, "height": 80 }
    },
    { "id": "auth", "kind": "node", "nodeType": "service", "label": "Auth" },
    { "id": "users", "kind": "node", "nodeType": "service", "label": "Users" },
    { "id": "billing", "kind": "node", "nodeType": "service", "label": "Billing" },
    { "id": "db", "kind": "node", "nodeType": "database", "label": "Postgres" },
    { "id": "e1", "kind": "edge", "from": { "elementId": "gateway" }, "to": { "elementId": "auth" } },
    { "id": "e2", "kind": "edge", "from": { "elementId": "gateway" }, "to": { "elementId": "users" } },
    { "id": "e3", "kind": "edge", "from": { "elementId": "gateway" }, "to": { "elementId": "billing" } },
    { "id": "e4", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "db" } },
    { "id": "e5", "kind": "edge", "from": { "elementId": "billing" }, "to": { "elementId": "db" } }
  ]
}

The gateway is pinned where the diagram’s user wants it. Auth, Users, Billing, and Postgres have no layout - the engine places each one next to its neighbors (a successor one rank after its predecessor, centered on it, as far from it as the drawing’s ranks are apart, or farther where its edge’s label needs the room, or in the next column, which moves along if its gap can’t hold the label) without moving the gateway, and routes the edges around it. Leaving layout out and giving it at exactly x: 0, y: 0 mean the same: not placed yet. The first save records where the engine put Auth, Users, Billing and Postgres in their layout, so later edits keep them there too. Only an edit that asks for a new layout moves them, or the gateway: autoLayout, or a new layoutStrategy or diagramFamily. A node that grows can also push them (Making room), and adding an order constraint they don’t meet places its two nodes again.

Hidden elements

An element with visible: false is laid out like any other and keeps its space; only drawing leaves it out. A hidden node still counts for NODE_OVERLAP_DETECTED. A hidden edge, or one with a hidden end, draws no step badge (Numbered steps).

Determinism guarantees

The engine is fully deterministic. Given the same scene document, the same layoutStrategy, and the same set of diagram-family rules, the output is bit-identical across runs. This means:

There is no random initialization, no time-based heuristic, and no external service call. Every algorithm in the pipeline is purely a function of the input.