# Zindex authoring guide

How to write DSP scenes that render well. It is the reference behind https://zindex.ai/skill/SKILL.md. The machine-readable contract is the JSON Schema: https://zindex.ai/schemas/scene.schema.json and https://zindex.ai/schemas/ops.schema.json.

## Auto-layout: omit coordinates from nodes
DEFAULT TO AUTO-LAYOUT for nodes and edges. Set layoutStrategy at the scene-document root (alongside schemaVersion, scene, and elements - NOT nested inside scene.scene), and OMIT layout from nodes. Same convention for diagramFamily and palette - all three are document-root fields. Nested under scene.scene they are moved to the root before the scene is checked, and stored there; a field set in both places keeps the root's value. The layout engine positions nodes, routes edges, and places labels automatically.

  layoutStrategy: { direction: "LR" | "TB" | "BT" | "RL", nodeSpacing?: 30, rankSpacing?: 80 (50 in a flowchart) }

Canvas dimensions affect layout density: when scene.canvas is larger than the minimum required by node spacing, the planner auto-spreads nodes around their centroid to fill the available area (auto-spread only widens gaps). Bigger canvas = more breathing room; smaller canvas = tighter layout. Auto-spread never causes overflow. It happens when the engine lays out every node; after the first save a larger canvas set with updateScene adds room on the right and at the bottom, and autoLayout spreads the nodes into it.

Mixed mode: nodes WITH explicit layout are pinned. Nodes WITHOUT (or at exactly x 0, y 0) are placed next to their neighbors, around the pinned ones, which stay where they are until you ask for a new layout (below), unless:
- a node that grows pushes them
- a node a later edit adds needs more room for its edge label (below)
- a new task in a pool needs room in its lane or a column of its own
- a node a later edit inserts in a flowchart needs room along the flow
- a node a later edit adds to a frame without a layout has no room there
- an AWS diagram's row or column grows (for a node or a spanning frame's header an edit adds, or for the room round a tier frame)
- an edit moves an AWS diagram's Region's column right to keep a labeled line into the column clear
- a Google Cloud diagram's row, zone column, Region or project's box grows, a gap between two Regions, two projects or two zone columns opens, or a line crosses an item in a row, for what an edit adds
- sibling projects' boxes in a Google Cloud diagram saved overlapping are cleared (the later project, and what lies right of it, move right)
- a layer in a stack of layers grows for a card an edit adds to it or moves into it, or an edit adds a layer, and what lies after it moves along by the growth (a card an edit adds or moves into a layer stands in that layer's row; Layers, below)
- an edit moves one to another lane
- a frame added or deleted around it would leave frames overlapping
- an `order` constraint an edit adds finds its two nodes the wrong way around

Positions are kept: after the first save the engine records each node's position in its layout, and later edits keep it, unless one of these happens. The engine then places the nodes it affects, and the edit's changed lists them (and each node whose drawn size the edit saves):
- a node that grows needs the room
- a node the edit adds needs more room for its edge label than the column it joins (that column and everything past it along the flow move just far enough)
- a task the edit adds to a lane needs the lane to grow or a column of its own (what lies past it moves)
- a node the edit inserts in a flowchart, between two placed nodes, needs room along the flow (what lies past it moves)
- a node the edit adds to a frame without a layout has no room there (the frame grows, and what lies past it moves across the flow)
- an AWS diagram's row or column grows (for a node or a spanning frame's header the edit adds, or for the room round a tier frame) or the edit moves its Region's column right to keep a labeled line into the column clear, and what lies past it moves
- a Google Cloud diagram's row, zone column, Region or project's box grows for what the edit adds or a group's title it widens, a gap between two Regions, two projects or two zone columns opens, or a line crosses an item in a row, and what lies past it moves
- a line the edit adds past a tier ends in an item and moves it under the line
- sibling projects' boxes saved overlapping are cleared (the later project, and what lies right of it, move right)
- a layer in a stack of layers grows for a card the edit adds to it or moves into it, or the edit adds a layer, and what lies after it moves along by the growth (a card the edit adds or moves into a layer stands in that layer's row)
- the edit moves a task to another lane (it is placed again there)
- an edit adds or deletes a frame around placed nodes and keeping them would leave frames overlapping or a frame holding a node that isn't its member
- an `order` constraint the edit adds finds its two nodes the wrong way around

New nodes are placed next to their neighbors, except a card in a layer (Layers, below). Edges, labels and frames are redrawn each time. Sequence diagrams follow message order, so their nodes stay at x 0, y 0. An edit puts a lifeline or message in its place with after or before (Operations, below).

A node that grows (a longer label, more columns, resizeElement, or a layout smaller than its content needs) pushes the nodes in its way just far enough to keep the gap they had, at most the node spacing (the rank spacing along the flow), and a frame with its own layout grows where a member that grew or was pushed would cross its border, as a pool or lane always does. Sequence diagrams don't push.

A layout size you write is a minimum. A node whose label or icon needs more is drawn bigger, and a create or an edit saves the size it is drawn at, so the layout you read back is what is drawn. A growth of 1 px or less isn't saved, and a version saved earlier shows the size it was written at until an edit saves it again. A label set to wrap "word" or "character" keeps its width. autoSize "none", the default, doesn't make a size exact: it is a floor, so for a box of one size keep the label short enough to fit (a wrapped label that overflows gets TEXT_OVERFLOW, which gives the height it needs).

A save stores no size for growth alone on a node whose edges dock on a smaller box than it draws: a BPMN event or gateway, a UI flow entry or exit point, a node that draws its icon alone, or a Google Cloud card a zone spans. Its size is saved only where the engine places or moves the node, an edit measures it again, or its growth pushes a neighbor or a frame border. An autoSize "content" height stays the minimum, and a Google Cloud card with multiple: true keeps its saved size. A sequence node or a node placed relative to another stores no size.

A later label edit sizes a node again on each axis where its size was what its old content needed, so a card you made bigger than its label keeps its size when the label gets shorter. A BPMN event or gateway and a UI flow entry or exit point follow their label on both axes. To have the engine choose a node's size again, send autoLayout with elements naming it: it places the node again, so it can move, and a label set to wrap is measured on one line unless autoSize is "content".

Coordinates you write are kept as written: a node you put on another one stays there, and NODE_OVERLAP_DETECTED names the fix.

To make a placed node bigger where it stands, give resizeElement the side its flow enters: "top" when the flow runs top to bottom (the flowchart and org chart default), "left" when it runs left to right (the default elsewhere), "bottom" or "right" for the reverses, as in { "op": "resizeElement", "id": "decide", "size": { "width": 290, "height": 170 }, "anchor": "top" }. It keeps its center across the flow, so straight edges into it stay straight; without anchor it grows from its top-left corner, its center moves by half the growth, and an edge into a diamond's corner or a BPMN sequence flow can take a step.

To lay out again, send autoLayout: { "op": "autoLayout" } lays out every node, as on a new diagram; { "op": "autoLayout", "elements": ["cache"] } places only the listed nodes again, around the others. A new layoutStrategy or diagramFamily set with updateScene lays out every node too, and so does removing one. These move nodes you positioned as well.

In architecture, flowchart, workflow, entity-relationship and UI flow diagrams and diagrams without a family, every frame but a pool, lane or fragment also drops its own layout and is laid out with its members. A frame that keeps its layout (a pool, lane or fragment, or any frame in an org chart or network) keeps its members where they are unless elements names them, and then they are placed again inside it. One that doesn't fit lands outside, and NODE_OUTSIDE_FRAME says so; a pool or lane grows to hold it instead.

ANTI-PATTERN: do NOT combine layoutStrategy with per-element layout.mode="absolute" coordinates on EVERY node. The two are contradictory at the all-elements level - layoutStrategy can only auto-position nodes that have no explicit coords. The most common failure mode is generating placeholder layout blocks like { mode: "absolute", x: 0, y: 0 } on every entity alongside a layoutStrategy declaration: x 0 and y 0 mean the node isn't placed yet, so the engine lays those nodes out and the blocks only add noise. The all-non-zero variant (every element pinned + layoutStrategy declared) pins every node, so the strategy places nothing. The clean pattern is: declare layoutStrategy at the document root, OMIT the layout block on every node you want auto-positioned, set explicit layout only on the specific nodes you want pinned. A diagram read back with view "dsp" has every position filled in: that is the engine's record of where it placed the nodes, so keep those blocks to keep the picture.

Frames (pools, lanes, containers) also auto-size from their children - omit layout from frames too. The engine computes frame bounds on every save. It lays pools and lanes out around their members (see Swimlanes below), and lays out sequence fragments and activation bars from the messages they hold or name. Provide explicit layout only when you need pixel-precise control. How frames and layout interact:

- A frame with its own layout keeps that box, growing only on a side a grown or pushed member would cross. NODE_OUTSIDE_FRAME reports a member outside it.
- On a new diagram the engine keeps nodes clear of a frame with its own layout, except that frame's members. It doesn't keep nodes clear of a pool, a lane or a fragment, or of a cloud group in an AWS or Google Cloud diagram. It places the frame's members by the graph, not inside the frame, so give the members positions inside it. A member added later goes inside the frame where there is room.
- A pool's or lane's layout is only a minimum: they always grow to hold their members, so their members need no positions and never get NODE_OUTSIDE_FRAME. An AWS or Google Cloud group's layout is a minimum too, in an AWS or Google Cloud diagram (see AWS architecture, below).
- In org charts and networks, laying out every node can make a fitted frame overlap another frame (FRAME_OVERLAP_DETECTED) or take in a node that isn't its member (NODE_IN_WRONG_FRAME). autoLayout with those nodes in elements places them again clear of the other frame.
- A frame with its own layout that is narrower than its title returns TEXT_OVERFLOW with the width it needs; widen it with resizeElement.

## Scene structure
{ schemaVersion: "0.1", scene: { id, canvas: { width, height } }, layoutStrategy?, elements: [...], styles?, constraints? }

Elements have a kind: "node" | "edge" | "frame" | "group" | "text" | "image" | "guide".

Nodes: { id, kind: "node", nodeType, shape?, label, layout?, textStyle?, icon? }
- nodeType: "service" | "database" | "objectStorage" | "queue" | "actor" | "generic" | "process" | "decision" | etc, plus family-specific types
- shape is OPTIONAL and defaults per nodeType. The normalizer fills the canonical glyph automatically: er.entity → rect, service → roundedRect, database → cylinder, objectStorage → bucket, workflow.start/end → ellipse, workflow.gateway* / workflow.decision → diamond, workflow.task / workflow.subprocess → roundedRect, er.attribute → ellipse, er.relationship → diamond, network.cloud → cloud, iconNode → iconBox, decision → diamond, document → document. Pass shape explicitly ONLY when you want a non-canonical glyph. A node with an aws:* icon draws its icon alone whatever its shape (no cylinder or bucket under it) unless its style sets a fill other than white or its nodeType is externalSystem (a dashed box). Full enum: "rect" | "roundedRect" | "ellipse" | "diamond" | "cylinder" | "bucket" | "pill" | "hexagon" | "parallelogram" | "cloud" | "box3d" | "textBox" | "iconBox" | "document" | "subroutine"
- document draws a box with a wavy bottom, and subroutine a predefined process: a box with a line inside each side. Every shape is valid in every family.
- layout is OPTIONAL: without it the engine places the node (layoutStrategy at the document root picks how)

**Storage convention.** In diagrams without cloud icons, two storage classes, two shapes (AWS and Google Cloud reference architectures draw each service as its icon or card instead: give a database node its aws:* or gcp:* icon and no shape):
- `nodeType: "database"` + `shape: "cylinder"` for row / key / document / search-indexed stores: Postgres, MySQL, Oracle, MongoDB, DynamoDB, Cassandra, Redis, Memcached, Elasticsearch, OpenSearch, InfluxDB, Timescale.
- `nodeType: "objectStorage"` + `shape: "bucket"` for blob-addressable storage: S3, GCS, Azure Blob, MinIO, R2, Backblaze B2.
Using cylinder for object storage (or bucket for a database) produces diagrams that look wrong to a human reviewer - the visual language is load-bearing semantic information, not decoration.

Edges: { id, kind: "edge", from: { elementId }, to: { elementId }, router?: "orthogonal" | "straight" | "curved", label?, textStyle?, edgeType?, step?, stepText? }
- Default to router "orthogonal" - the engine's router enters the side facing the source, at its center or straight across where the nodes line up, with obstacle-aware step-path fallbacks.
- "straight" is one line between the nodes' centers and "curved" one bowed arc, each ending on the nodes' outlines. Neither is routed round other nodes, and one that runs through a node gets the warning EDGE_CROSSES_NODE. Use "curved" for a loop back, which bows round the nodes between where it can, and "straight" only for a direct link with nothing between; not for a diagram's main flow.
- To pick where an edge meets a node, give the endpoint an anchor: from: { elementId, anchor: { side: "left", offset: 0.25 } }. side alone fixes the side and leaves the place to the engine. Where the two sides face each other and their faces overlap it lines the ends up (a straight line); it also spreads ends that share a side and slides a straight line past the title of a frame it enters. Sides that don't face, or faces that don't overlap, take a bend.
  - An edge with edgeType workflow.sequenceFlow, uiflow.navigate, uiflow.back or uiflow.action enters a node at its center, so a side alone fixes only the face, and its line is straight only where the ends are less than 16 px off center.
- An anchor's offset places the end: 0 to 1, from the side's top on left and right sides, its left on top and bottom ones. The engine doesn't move it to line up with another end, so two ends given places that don't line up take a step. Two ends at one place are kept 12 px apart.
- For a straight line, give sides and no offsets. An offset is a fraction of the side as drawn, and a card whose label needs more than the layout.width you wrote is drawn wider, so the place moves with it. A save stores the size it is drawn at and warns with EDGE_OFFSET_ON_GROWN_NODE: work the offset from that saved size, or give sides.
- Anchored edges never share a trunk, so anchors separate two edges that leave one side. Nodes don't move for anchors. A sequence message, a self-loop and an end with a column ignore their anchor (EDGE_ANCHOR_IGNORED). updateEdge replaces from and to whole: send the anchor again.
- Numbered steps: step (1 to 99) draws a numbered badge at the start of the line, as AWS diagrams number a request's path, and stepText (which needs step) is the edge's line in a step list right of the drawing. Edges with one step and one source share a badge. The engine draws the numbers you give; it doesn't number edges, except a sequence diagram's messages under autonumber (below). Steps draw in every family. updateEdge with step: null removes both fields. Flowchart and erDiagram Mermaid views leave steps out, and Mermaid edits keep them; a sequenceDiagram view writes a message's step as autonumber lines.

Long labels wrap on their own: a node's textStyle.wrap defaults to "auto", which keeps the label on one line up to 250 px (400 px for a diamond) and wraps a longer one there in even lines, the node growing taller, and wider only to fit a word wider than that; wrap: "none" keeps one line however long. Lines break at spaces, after hyphens and slashes, and between Chinese or Japanese characters, never inside a word, number or date, except wrap: "character" with one wider than the node. Nodes saved before "auto" store "none": set "auto" with updateNode to wrap them.

An edge's label wraps at 200 px, its text plus 4 px each side. Lines break where a node's label breaks, each taking every word that fits, and each line you write with \n wraps by itself. A word wider than a line stays whole; wrap: "character" breaks it. In flowchart, workflow, uiflow and sequence diagrams, a label written as EVENT [guard] / action breaks between its parts first. A label with no clean place beside its line also wraps narrower on its own, in up to three lines (the lines you wrote, if more). wrap: "none", a sequence message's label and a label that can't break (one long identifier) keep their lines.

An edge's textStyle takes wrap alone (createEdge, updateEdge, setText); align and verticalAlign are refused, and setText ignores them. wrap: "none" keeps each line as written, which can run over lifelines or nodes. The 200 px can't be changed. A saved diagram's label wider than 200 px wraps the next time the diagram is drawn; set "none" to keep it on one line.

Lifelines don't move apart for a message label, so one wider than the gap between its lifelines is drawn over them: shorten it or break it with \n.

Where two or more labeled edges join the same two nodes, keep each label to one line, 192 px of text at most. A node already in the diagram keeps its size, so a wrapped label can land on another edge's line. `autoLayout` without `elements` grows the two nodes for their labels and moves every node. It does that in flowchart, workflow, UI flow, architecture and entity-relationship diagrams and in a diagram with no family. It doesn't in a sequence diagram, an org chart, an AWS or Google Cloud architecture with its groups, or for edges across several ranks.

Multi-line text at a width you choose: set textStyle: { wrap: "word", align?, verticalAlign? } on a node with a layout width and layout.autoSize: "content"; the node keeps the width and the engine gives it the height the wrapped text and its icon need, growing down from its top edge; nodes it grows into move down to keep the spacing (the node spacing in a left-to-right flow, the rank spacing in a top-to-bottom one). The grown height isn't stored: it follows the text. wrap: "character" also breaks long identifiers and URLs.

Without autoSize the node keeps its layout height, and TEXT_OVERFLOW gives the height text needs that doesn't fit. Or break lines with \n and let the engine size the node. Don't use node + text overlay workarounds.

Text is drawn in Inter, fontFamily "sans", the default. fontFamily "mono" draws in a monospace font, for paths, endpoints and types. Any other fontFamily draws in Inter with FONT_FAMILY_UNKNOWN: set sans or mono, or remove it.

Inter and its fallback fonts draw:

- Latin, Cyrillic, Greek, Armenian and Georgian letters with their accents.
- Chinese, Japanese and Korean.
- Digits, punctuation, arrows, math and logic signs (∧, ∀, ∈), currency signs, symbols and box drawing.
- Every emoji of Unicode 18.0, in its own colors (✅, 🚀, 👍🏽, 🇯🇵).

A sign Unicode shows as text by default (⚠, ♥) is drawn as text. Followed by U+FE0F, the emoji selector (⚠️), it is drawn as an emoji.

Other scripts are drawn as empty boxes, among them Arabic, Hebrew, Thai and the Indic scripts. So are most rare Chinese characters and a few rare signs. Both lists: https://zindex.ai/docs/reference/rendering/#text-and-scripts

In sans, -> and => are drawn as arrows; in mono they stay as typed.

For Chinese, Japanese or Korean text, set scene.lang to a BCP 47 tag (ja, ko, zh-Hans, zh-Hant or zh-HK): it picks the letterforms Chinese characters are drawn in. Without it, or with another language such as en, the diagram's whole text decides. A diagram whose Chinese characters Simplified Chinese, Traditional Chinese and Japanese all share reads as Simplified Chinese. Japanese written without kana can read as Traditional Chinese. A diagram made from Mermaid text gets it with updateScene after the create.

A check, save or edit whose drawn text holds a box returns one CHARACTER_NOT_DRAWN warning, with no element. Its fix lists up to five of the characters and names up to three elements that hold one: a label or title, an ER table's columns, an edge's stepText or a fragment's guards. Fix those, then read the next write's warnings for the rest. The op for each: https://zindex.ai/docs/reference/rendering/#character_not_drawn

Where a label must be readable, write it in a script the list above draws. Or keep the text: the diagram is saved as written either way.

## When to reach for which element kind
Before declaring "Zindex can't do X", check this list. Most "limitations" are actually unfamiliar primitives:

- **Standalone text label** (titles, captions, callouts, legends, descriptive paragraphs OUTSIDE a node): use `{ kind: "text", text: "Section heading", layout: { mode: "absolute", x, y, width, height } }` in a scene, or `createText` (the same fields) in an edit. Text elements support `textStyle.wrap: "word"` for line-wrapped paragraphs and accept \n for explicit line breaks.
- **A text or an image you place yourself**: with an absolute layout (coordinates from 0 on) it stays where you write it, autoLayout included. Below 0 the engine shifts the whole drawing to make room.
- **A frame with its own layout** is different. In flowchart, workflow, UI flow, architecture and entity-relationship diagrams and in diagrams without a family, autoLayout without elements removes the layout from every frame but a pool, a lane and a fragment.
- **Nodes the engine places go clear of your text or image.** On a new diagram and on autoLayout without elements, the engine moves the whole drawing right or down, by the least distance that clears it. A node an edit adds goes clear of it too.
- **Where it doesn't:** a sequence diagram, a diagram with a pool or lane that has a layout of its own, and nodes you gave positions. There a text or image can land over the nodes.
  - With a pool, a lane or nodes you positioned, read the positions with diagram_get view "dsp", then add it with createText or createImage in the space they leave.
  - A sequence diagram's nodes stay at x 0, y 0, so view "dsp" shows no positions. Read where they are drawn in the SVG that diagram_render links to, where each element is a group named by its id, then write the text right of the last lifeline: the image grows to hold it. A text written below the last message makes every lifeline run down to it.
- **Bullet lists in text**: just put unicode bullets in the text content, e.g. `text: "Features:\n• Fast\n• Reliable\n• Cheap"`. Combine with `textStyle: { wrap: "word" }` to wrap long bullets.
- **Horizontal or vertical separator line spanning the canvas**: use `{ kind: "guide", orientation: "horizontal" | "vertical", position: 250 }`. Guides always render as dashed full-width/height lines - perfect for dividing a diagram into sections.
- **Dashed line on an edge or shape stroke**: set `style: { dash: [4, 4] }` (or any number array). Works on edges (`{ ..., style: { dash: [4, 4], stroke: "#cc0000" } }` for a red dashed arrow) and on element strokes.
- **Custom fill/stroke colors**: inline `style: { fill: "#cccccc", stroke: "#cc0000", strokeWidth: 2 }` works on every element kind. Or define a named token in scene.styles.
- **Image embed** (logos, screenshots): use `{ kind: "image", assetRef: "...", layout, fit? }`, its file a `data:` URI in the scene's `assets`. In an edit, `updateScene` with `assets`, then `createImage`.
- **Hide without deleting**: `visible: false`. The element keeps its space but isn't drawn, nor any edge at it; a hidden frame hides only its box and title.
- **A group round elements that have frames of their own** (an Auto Scaling group or security group across Availability Zones): a frame with `spans` instead of `children`, drawn round what it names, in architecture diagrams and diagrams without a family. Its targets keep their frames, and it takes no `children`, no `layout` and no place in another frame. Its box is one rectangle round its targets, so span things that sit together: a node inside it that it doesn't span gets `SPAN_COVERS_NODE`.
- **Grouping for selection / movement only** (no visible container): use `{ kind: "group", children: [...] }`. For a visible bordered container, use `{ kind: "frame", containerType: "generic", children: [...] }`.

If your design needs something not covered here, prefer composing it from the above primitives over concluding the platform can't do it.

## Operations

Send these in `ops` on `diagram_edit` (or `POST /v1/diagrams/{id}/revisions`). The full shapes are in https://zindex.ai/schemas/ops.schema.json and https://zindex.ai/docs/reference/operations/.
createNode, updateNode, deleteElement, createEdge, updateEdge, moveElement, resizeElement, setStyle, setText (accepts textStyle), groupElements, ungroupElements, createFrame (children, or spans for a spanning frame), updateFrame (a frame's title, style, icon, containerType or laneDirection, or a spanning frame's spans; null removes the style, icon, containerType or laneDirection; positions are kept, except that a longer title that widens a Google Cloud group moves what lies past the growth; not its box: moveElement moves a frame with its cards, and resizeElement gives it a fixed size), createText, createImage, addConstraint, removeConstraint, autoLayout, updateScene, restoreRevision.

In a sequence diagram a new participant is added on the right and a new message or note at the bottom. To put one between two others, give createNode or createEdge `after` or `before`: the ID of the element it goes next to (a participant beside a participant, a message or note beside a message, a note, a fragment or a highlight band, joining that message's fragment or band). updateNode and updateEdge take the same to move one. The element named must exist when the op runs (ORDER_TARGET_NOT_FOUND); other elements refuse both (ORDER_NOT_SUPPORTED). To add a message after a fragment rather than as its last row, name the fragment. The outline lists messages and notes in drawn order, each fragment and band before its rows. A fragment is laid out with its rows (its layout is ignored), and each operand starts at a row (operands[].startsAt), so its divider moves with it; a row placed `before` an operand's first row becomes its first. Deleting or moving an operand's first row starts it at its next (FRAGMENT_OPERAND_REMOVED when none is left). `{ "op": "createEdge", "id": "m_cache_get", "edgeType": "sequence.message", "from": { "elementId": "checkout" }, "to": { "elementId": "cache" }, "label": "GET cart", "after": "m_verify_ok" }`

An edit with an error saves nothing and returns `VALIDATION_FAILED` with `errors`. That includes an op on something it can't change, such as `moveElement` on an edge or `resizeElement` on a node the engine hasn't placed yet. Fix what each error names and resend with the same `baseRevision`. Within one edit, an op may name an element a later op creates, except the element `after` or `before` names and the frame a createNode or updateNode `frame` names, which must exist when the op runs.

updateScene modifies scene-level metadata on an existing scene without recreating it - use it to change title, brief, lang, palette, styles, assets, layoutStrategy, diagramFamily, or canvas: `{ "op": "updateScene", "title": "New Title", "palette": { "nodeFill": "#003366" } }`. A new layoutStrategy or diagramFamily lays out every node again, as autoLayout without elements does. Pass null for brief, lang, palette, layoutStrategy or diagramFamily to remove them, or for an entry of assets; removing layoutStrategy or diagramFamily also lays out every node again.

autoLayout has the engine place nodes again and keeps the new positions: `{ "op": "autoLayout" }` lays out every node, as on a new diagram; with `"elements"` (node IDs only) it places just those nodes again, clear of the others. It doesn't move nodes with a relative layout or sequence diagrams. Without `"elements"`, in architecture, flowchart, workflow, entity-relationship and UI flow diagrams and diagrams without a family, every frame but a pool, lane or fragment drops its own layout and is laid out with its members; members of a frame that keeps its layout stay where they are; named, they are placed again inside the frame, and one that doesn't fit lands outside (NODE_OUTSIDE_FRAME), except in a pool or lane, which grows to hold it.

restoreRevision makes the next revision equal to an earlier one and must be the only op in its edit: `{ "op": "restoreRevision", "revision": 3 }`. `diagram_edit` also takes it directly as `restoreRevision`.

## Diagram families
ALWAYS declare diagramFamily at the scene-document root on every scene you create (alongside schemaVersion, scene, elements - NOT nested inside scene.scene). The field is technically optional in the schema, but it is effectively load-bearing: it gates family-specific behavior the engine and downstream tooling rely on (flowchart branch sides and tint, which families draw same-label fan-in as one flow, workflow BPMN conventions, etc.). Omitting it draws the scene as an architecture diagram and leaves downstream tooling unable to segment by diagram type. Nothing warns you when it's absent, so declare it every time. Allowed values: architecture, flowchart, workflow, entityRelationship, sequence, network, orgchart, uiflow.

For steps with yes/no decisions and loops, use flowchart. For BPMN events and gateways, use workflow. For parallel processing paths or perimeter actors, prefer workflow + pool/lane over architecture + generic frames - splitting work into swimlanes renders cleaner than fanning edges out of one oversized central node.

- architecture: service / database / queue / storage / externalSystem nodes (service for gateways, database for caches). Default LR auto-layout; an AWS or Google Cloud architecture with its groups is arranged by them instead (AWS architecture and Google Cloud architecture, below). **For architecture diagrams without explicit frames, set autoGroup: "byNodeType" in the document's top-level extensions to emit subtle background bands grouping nodes by their nodeType ("Services", "Databases", "External Systems", etc.)** - lifts the diagram from a flat blob of boxes into a scanable layered architecture. Architecture diagrams and diagrams without a family only; skipped silently for other families. Skipped when (a) the scene already has user-authored frames containing the candidate nodes (no double-wrap), (b) every node shares a single nodeType (single band is pointless chrome), (c) the nodes of one type are scattered (a node of another type sits between two of them in a column), or (d) a band would overlap a frame or another band. The response doesn't say when banding was skipped.
  - Layers: to stack frames as rows, write each as a frame with containerType "layer", list the layers top to bottom in one frame's children (at the root they stack in the order they appear in elements), and leave layout off the layers and their cards. No anchors are needed.
    - A layer holds cards and plain frames (sub-groups that stay whole). In a new layout, cards in no layer stand above the stack when more of their lines run into it than out, else below.
    - Every layer is as wide as the widest, a layer wider than 1,400 px wraps into rows, and lines run through the layers. A stack runs top to bottom unless layoutStrategy.direction says otherwise, whatever the family's default; LR, RL or BT turns it.
    - In a stack of rows a layer keeps room left of its top row's first card so the line into it clears the title. A long title can widen every layer. In a stack of columns the layers keep no room. 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. No card moves.
    - A line between two cards of a stack stays between its left and right borders (top and bottom in a stack of columns), and a layer it passes through gets room, so the stack can grow wider. A line with a card outside the stack at either end isn't held between its borders.
    - Boundaries: the order comes from your listing, never from the lines, so a stack listed bottom to top draws bottom to top. Only the scene's first stack is arranged (the one whose first layer comes first in elements).
    - A layer the engine doesn't arrange is placed as a generic frame. A layer with a layout of its own keeps that box and gets no warning. To arrange it, write it without a layout, or send autoLayout without elements (it moves every node and takes the layout off every frame but a pool, lane or fragment). diagram_get with view "dsp" shows a layer's layout.
    - In a pool, lane or fragment, or in another family, it gets LAYER_NOT_ARRANGED: move the stack out, or set diagramFamily to architecture. In an AWS or Google Cloud diagram a stack is arranged only inside a generic frame of its own, or a cloud boundary that holds no Region.
    - A stack none of whose cards has a layout (a first save, or an edit that creates its cards) is arranged as a new layout arranges it, and a pinned card, one with a layout of its own, stays where it is.
    - That stack stands 56 px clear of the pinned cards (`layoutStrategy.nodeSpacing` when that is larger). It stands after the pinned cards that lead into it, those with more lines into it than out of it. With none of those, it stands before the other pinned cards it has lines with, and otherwise past them all.
    - It slides along the flow past a pinned card in its way. A frame round pinned cards counts as one pinned card.
    - When pinned cards stand on both sides, it stands after those that lead into it and doesn't move toward the others. A line from it to one of those runs the whole way across the space between the stack and that card.
    - A layer with a layout of its own divides a stack none of whose cards has a layout. The layers listed before it stand before it, and the ones listed after it stand after it.
    - An edit keeps the stack. A card added to a layer, or moved into one, stands in that layer's row. A layer that grows moves the layers after it along, and a card that grows wider moves the cards after it in its row over, and so does a sub-group that grows wider for a card added to it. A card in no layer that stands after the stack moves along with them, and the other saved cards keep their places among themselves.
    - A card an edit adds with no layer is placed next to its neighbors by the general rules: list it in a layer, or send autoLayout without elements (it moves every node).
    - A layer added with createFrame goes after the others (pass frame when a frame lists the stack's layers). autoLayout with elements places those cards in their layers' rows; without elements it arranges the stack again.
    - To put a layer between two others, send one edit: deleteElement each of the stack's layers, then createFrame each again in the new order with containerType "layer", its title, its cards and sub-groups in children, and frame set to the frame that lists the layers (leave frame off when the layers are at the root), then autoLayout without elements (it moves every node). Without that autoLayout the saved cards keep their places and the layers draw in the old order. A line that ends on a layer is deleted with the layer: create the line again.
- flowchart: process, decision, document and database nodes; a generic node with shape pill or ellipse for the start and each end. A decision is any node drawn as a diamond. Label each decision exit with the answer it stands for. Top to bottom unless layoutStrategy.direction says otherwise.
  - Branch sides: an exit labeled yes, y, true, ok, pass, passed, success or valid runs straight on; one labeled no, n, false, fail, failed, failure, error or invalid leaves to the right (below in LR and RL). Whole labels only, ignoring case and trailing punctuation ("No errors" isn't a no). Of two exits where one is a no, the other runs on. Apart from loop tests, other labels keep the general decision rules.
  - Loop tests: of two exits where one loops back ("More items?" yes back to the loop's first step), the other runs on, whatever its label.
  - The main path runs straight. Loops back across two or more ranks run round the left (above in LR and RL) unless the other side crosses fewer nodes or lines. Every entry into a step has its own arrowhead (entries into one side of a decision join), and same-label edges keep their labels.
  - In the default style every node draws light blue, except external systems, notes and nodes with an aws:* or gcp:* icon, unless style or palette sets the node's fill or stroke.
  - Warnings, which don't block the save: FAMILY_FLOWCHART_DECISION_FEW_EXITS, a decision with fewer than two exits (add an exit for each answer, or make it a process); FAMILY_FLOWCHART_EXIT_UNLABELED, an exit of a branching decision with no label (set its label to the answer with updateEdge).
  - Boundaries: a decision with three or more exits whose yes loops back keeps the general rules, so its no isn't moved right. An else-if ladder (decisions whose yes enters one node) draws as a column of checks, each no straight down, each yes to the side. With a frame that has no layout, the main path isn't lined up, no isn't moved right, and an edit's inserted steps are placed by the general rules. No BPMN events, gateway markers or message flows: use workflow.
- workflow: Full BPMN. workflow.start / end for basic, messageStart / messageEnd for message-triggered. intermediateTimer / Message / Error for catch events, intermediateThrowMessage for throw. terminate ends entire process. subprocess renders with [+] marker. 4 gateways: gateway (exclusive), gatewayParallel, gatewayInclusive, gatewayEvent. For decision diamonds without a BPMN-spec marker (x, +, circle, pentagon) use workflow.decision - its label renders INSIDE the diamond per the broader flowchart convention; the four gateway types use the BPMN-spec external-label convention. **For sequence flows between workflow steps, set edgeType: "workflow.sequenceFlow"** - it gets the BPMN-spec triangle arrowheads. workflow.messageFlow gets open circle / open arrow for cross-pool messages. Generic edges (no edgeType) default to a target-end triangle arrowhead too, in a scene or from createEdge - direction is the dominant semantic in every diagram family, so the engine arrows by default; opt out with `endpoints: { endArrow: "none" }` for the rare undirected case. A type's own arrowheads aren't stored, so changing an edge's edgeType with updateEdge changes them; view "dsp" shows only the arrowheads you set (an older version can still list its type's; they draw the same). **For state-transition / conditional-flow edge labels, use the UML / SCXML / BPMN convention `EVENT [guard] / action`** - the renderer splits the segments into typographically-distinct tspans automatically (event 12px standard, guard `[...]` 10px muted, action `/ ...` 10px muted italic), so the eye locks onto the event name first. Detection is content-based (any label containing balanced `[...]` OR a ` / ` separator); a plain label that fits renders unchanged.
- entityRelationship: er.entity / er.weakEntity nodes. Relationship lines (er.relationship, er.identifying) draw solid; add style.dash [6, 4] for a non-identifying one. Set extensions.columns: [{ name, type?, pk?, fk?, unique?, nullable?, comment? }] on an er.entity for compartmented rendering with PK/FK badges. (The shape { name, type, key: "PK"|"FK", unique?, nullable? } is also accepted and normalized to the canonical form; a column that is both needs pk and fk.) **To add / remove / modify columns on an existing er.entity, use updateNode with the FULL replacement extensions.columns array - the array is replaced wholesale, not merged. There is NO addColumn / removeColumn / updateColumn op; the valid ops are listed under "Operations" above.** Crow's-foot cardinality glyphs are auto-inferred from column metadata: the only PK column → "one", one of several PK columns → "many"; an FK column, including one that is also pk, → "many" by default, narrowing to "one" (unique, or the entity's only PK column), "zero-or-many" (nullable), or "zero-or-one" (both). So a join table keyed by its FKs is many-to-one with each parent when each of its edges names its column (endpoint.column, or a label matching the column), and a table whose PK is also its FK is one-to-one; such a column shows both badges. To override, set cardinality on the endpoint: "one" | "many" | "zero-or-one" | "zero-or-many" | "one-or-many" - author-set values are always preserved. Inferred values aren't saved: every save infers them again, so they follow later column changes, and view dsp shows only what you wrote. To anchor an edge at a specific column row inside an entity, as database diagram tools draw it, set endpoint.column to the column name; when only the FK side has the column name, the engine falls back to the target's sole PK row automatically so most FK edges need only label="<fk_column>" or column on the source side. Such a label anchors the edge and isn't drawn; set style.forceLabel: true to draw it too, still anchored at the column. Self-FK loops (parent_id-style) draw a U-bracket between the FK row and the PK row inside the same entity. Entity rects auto-grow to fit the longest column row + header + rows; explicit layout.width/height are treated as a minimum, so you don't need to hand-tune dimensions to avoid column overflow. LR auto-layout works well.
- sequence: sequence.actor / sequence.lifeline for participants - the sequence resolver auto-positions lifelines and orders messages by their position in the elements array (definition order = visual order). Lifeline headers auto-size to fit their labels (declared 100 px width is a floor, not a cap). Each lifeline renders a head bar at the top AND a matching foot bar at the bottom by default (the UML convention) - do NOT author duplicate node shapes for the bottom row, the platform draws them. Set showLifelineFeet: false in the document's top-level extensions (not scene.extensions) to suppress foot bars. 5 edge types: sequence.message (sync, filled arrow), sequence.async (open arrow), sequence.reply (dashed open arrow), sequence.create (dashed filled arrow), sequence.destroy (filled arrow + X terminator). For activation bars, add a sequence.activation node with extensions.startsAt (the message that starts it; the bar is on the lifeline it arrives at) and extensions.endsAt (the message that ends it), and no layout. For combined fragments, use a frame with containerType "fragment", the messages and notes it holds as children, extensions.operator ("alt" | "opt" | "loop" | "par" and so on), and the title for the first operand's guard, with its brackets ("[charge succeeded]"); for each further operand add extensions.operands: [{ startsAt: "<message or note id>", guard: "else" }], guard without brackets (they are added), which draws a divider above that row. Leave layout out of fragments: the engine lays them out with their rows. Fragments nest or follow each other: list each row in one fragment. For UML notes / annotations between messages (e.g. "Postgres crashes"), use sequence.note with extensions.anchor: "<id>" where <id> is a participant in the scene - the note centers "over" that participant (the UML 2.5 §17.4 convention). For notes that span multiple lifelines, use extensions.anchor: ["<idA>", "<idB>", ...] - the note's bounding box spans from the leftmost to the rightmost named lifeline, also centered-over semantics. Notes interleave vertically with messages by their position in the elements array - in a scene, place the note element BETWEEN the two messages it should appear between; in an edit, createNode with `after` naming the message it follows (or the fragment, to go below it). Notes render as a rounded rect with a folded top-right corner (UML convention).
  - Participant types: eight node types head a column. sequence.lifeline draws a box and sequence.actor a stick figure. sequence.boundary, sequence.control, sequence.entity and sequence.database draw an icon with the name under it. sequence.collections and sequence.queue draw a box with the name inside. Use any of the eight wherever these notes say lifeline: a message's ends, a note's anchor, a participant box's children, `after` and `before`. The type changes only the head and foot drawn.
  - Notes beside a lifeline: to put a note beside one lifeline instead (Mermaid's and PlantUML's note right of), give it a string anchor and extensions.side: "left" or "right". A note with an array anchor is always drawn over its lifelines (FAMILY_SEQ_NOTE_SIDE_IGNORED).
  - A message needs no edgeType, except create and destroy. In a diagram whose diagramFamily is "sequence", an edge between two participants with no sequence.* edgeType (none, default or another family's) is a message. Its line sets the kind:
    - style.dash set to a pattern: a reply, whatever its arrowheads.
    - A solid line with endpoints.endArrow "openTriangle" and no startArrow: async.
    - Any other solid line: sequence.message.
  - Only style.dash and endpoints count, not an edgeType's own dash or arrowheads. Set sequence.create or sequence.destroy yourself: they are never inferred.
  - An edge with an end that isn't a participant is no message and is drawn outside the rows (FAMILY_SEQ_ORPHAN_MESSAGE): join it to two participants, or remove it.
  - A note with no anchor is drawn over the lifelines of the message above it in elements, and FAMILY_SEQ_NOTE_INVALID_ANCHOR warns: set extensions.anchor to the lifeline ID or IDs it belongs to.
    - A note above every message goes over the first message below it, and in a diagram with no message it goes across every lifeline.
    - With side and no anchor, "left" puts it left of that message's leftmost lifeline and "right" right of its rightmost. With no message, it goes beside the diagram's leftmost or rightmost lifeline.
    - The engine doesn't save the lifelines it draws an unanchored note on: diagram_get shows the note as you wrote it, so it follows whichever message is above it.
  - A note whose anchor names no lifeline that exists isn't drawn (FAMILY_SEQ_NOTE_ANCHOR_NOT_FOUND): anchor it to one that does.
  - Created and destroyed lifelines: a sequence.create message that is a lifeline's first row puts the lifeline's head on that row, and a sequence.destroy message ends the lifeline it arrives at, with no foot. Only the message's target is created or destroyed, so to end a lifeline that sends, add a destroy message to it.
  - Bars that overlap on one lifeline stack; give them no layout.
  - Participant boxes and highlight bands: any frame that isn't a fragment is drawn by its children, and needs no containerType. Participants draw a box round them, with the title above their heads (Mermaid's and PlantUML's box). Messages and notes draw a filled band behind those rows (Mermaid's rect): give it style.fill, or it takes a faint tint. Leave layout out of both. A frame that holds both isn't drawn (FAMILY_SEQ_FRAME_MIXED). Boxes don't nest or overlap (FAMILY_SEQ_BOX_NESTED), and a box holds every lifeline between its first and last: one placed there with `after` is drawn inside it without joining it (FAMILY_SEQ_BOX_SPLIT), so give createNode or updateNode the box as `frame` too. Bands nest with fragments either way.
  - Numbering: set autonumber: true, or { "start": 10, "increment": 10 }, in the document's top-level extensions (updateScene's extensions in an edit). Messages are numbered from the top each time the diagram is drawn, so inserting one renumbers the rest without changing them. A message's own step restarts the count, and notes and hidden messages take none. Numbers are whole: write 1.1-style numbering in the label.
  - endArrow: "cross" draws an X just short of the lifeline, as Mermaid's -x does.
- network: network.server / router / switch / firewall / cloud / client nodes. Force-directed layout (no inherent direction).
- state graphs: draw states and transitions in a flowchart (or workflow) diagram; there a label such as submit [valid] / save draws its guard and action smaller and muted. In other families, and with no family, labels are plain text.
- orgchart: org.person / org.role with label "Name\nTitle". Add accentColor for department stripe. org.directReport (solid) / org.dottedLine (dashed) edges. Auto-layout is a tidy tree, top to bottom; it doesn't read layoutStrategy.
- uiflow: uiflow.screen / modal with label "Title\nDescription" (first line title bar, rest body). uiflow.entry / exit for start/end circles. uiflow.navigate / back (dashed) / action edges.

Swimlanes (workflow): a pool is a frame with containerType "pool" whose children are lane frames (containerType "lane"), in the order they stack; each lane's children are its tasks, events and gateways. Leave layout off the pool, the lanes and their nodes: the engine lays them out as BPMN tools do (in org charts and networks it only keeps each node inside its lane; columns aren't shared). Lanes run along the flow and stack across it; every node a lane lists is placed inside it; each lane is as deep as its contents need (at least 60 px, or its title's length plus 16 px); columns are shared across lanes and pools, so the flow reads as time. laneDirection "vertical" stacks the lanes top to bottom (BPMN's horizontal pool) and the flow runs left to right; "horizontal" puts them side by side (a vertical pool) and the flow runs top to bottom. When layoutStrategy.direction runs along the lanes' stacking, laneDirection wins. Several pools stack across the flow in document order, 40 px apart; a pool with no nodes (a black-box participant for message flows) is drawn at its least depth. createFrame needs at least one child, so write a pool with no nodes in the scene sent to diagram_create. A pool's layout is a minimum anchored at its corner. To add a task to a lane later, createNode with frame set to the lane's ID: it takes a free place in its column inside the lane, or the lane grows and what lies past it moves across the flow; a task between two placed columns opens a column. updateNode with frame moves a task to another lane, where the engine places it again. To add a lane to a saved pool, createFrame the lane with frame set to the pool's ID and its first task in children: it goes after the pool's other lanes. No op reorders a saved pool's lanes: in one edit, deleteElement the pool, which leaves its lanes and tasks in place, and createFrame it again with the same id, title and laneDirection and its lanes in children in their new order. Edges with an end at the pool itself go with it, so create them again in that edit. createFrame needs at least one child, so create a new lane with its first task in children. Lanes are pushed, never pulled back, so send autoLayout afterwards for a compact picture. Lanes along the flow (phases), and reordering lanes or pools to reduce crossings, aren't supported; a frame inside a lane (a subprocess) is fitted round its members, not laid out with them. Nodes a pool lists beside its lanes go in an untitled band after them (POOL_NODE_OUTSIDE_LANE).

## AWS architecture
An AWS diagram (VPCs, Availability Zones, subnets) needs no coordinates: write AWS's groups as frames with their presets, the services as nodes with aws:* icons, and leave layout off all of them. The engine draws the groups and arranges them as AWS's reference diagrams do.

What to write:
- diagramFamily "architecture" (or none; the arrangement applies to no other family).
- Frames for AWS's groups, containerType set, nested as AWS nests them: "aws.cloud" > "aws.region" > "aws.vpc" > "aws.az" > "aws.subnet.public" and "aws.subnet.private"; titles such as "VPC 10.0.0.0/16" or "Public subnet". List each VPC's AZs, and each AZ's subnets, in the order they should read. Also "aws.securityGroup" and "aws.autoScalingGroup" inside a subnet or AZ, or across AZs as a spanning frame (below), "aws.account" inside AWS Cloud, "aws.corporateDataCenter" outside every AWS group; these four only draw (an account holding Regions is arranged as AWS Cloud is).
- Nodes with aws:* icons and short labels, and no shape, fill or layout, each listed in the frame it runs in: instances, tasks, NAT gateways and databases in subnets; the load balancer and the gateways ("aws:internet-gateway", "aws:vpn-gateway", "aws:vpc-endpoints", "aws:transit-gateway-attachment") in the VPC itself; regional services (S3, SQS, Lambda, DynamoDB, Cognito, CloudWatch) in the Region; global services (Route 53, CloudFront, WAF, IAM) in AWS Cloud; users, clients and on-premises systems outside AWS Cloud.
- Edges as usual, with style.dash (such as [6, 4]) for replication. Leave endArrow out: an AWS diagram (AWS groups, or nodes with aws:* icons without them) draws AWS's open arrow, an open V, by default on an edge whose edgeType is unset, default, er.*, network.* or org.*; set endArrow only to draw another ("triangle" for a filled one). workflow.sequenceFlow, sequence.message, sequence.create, sequence.destroy and uiflow.* edges keep their filled triangle; set endArrow "openTriangle" on them for the open V.

What the engine does:
- AZs become columns in the VPC's order, equally wide and evenly spaced.
- Subnets become rows shared by every AZ, evenly spaced: each AZ's first public subnet in the first row, and so on, public rows above private.
- A node alone in its subnet stands over the middle of the nodes it connects to in the next row down, which sit centered in their subnet (a task over its cache and database, its lines forking to both). One that connects to nothing below is centered.
- A gateway in the VPC docks on the VPC's border facing what it connects to outside: the left for users or a data center before AWS Cloud, the right for the Region's services or what comes after the cloud. It docks there when its lines inside stay in the AZ nearest that side, or reach a load balancer in the row above the AZs or beside a lone AZ on that side. Otherwise it docks on the top over the nodes it serves (an internet gateway serving two AZs). On the left or right its label straddles the border.
- A load balancer, or any other node the VPC lists directly, sits between two AZ columns, or beside a lone AZ's column on the side its traffic comes from, when its edges reach only the second row or below. With three or more AZs, an edge into the first row, none into the subnets, or a frame round the AZs, it gets a row above the AZs.
- Regional services form a column right of the VPCs (two columns when one would be over 1.5 times the VPCs' height), and global services a row above the Regions. Outside nodes form a column left of AWS Cloud (users and other sources) or right of it (services the cloud calls). Outside nodes an edge joins share one side: the left when any of them has more edges into the cloud than out, else the right.
- Each group draws in AWS's color, line and corner icon, no fill, fitted to its members; a preset's layout is only a minimum.
- Routes cross AZ columns as flows cross swimlanes. Lines keep 16 px from group titles and 32 px off group borders where the channel has room. Ends on one icon face keep 16 px apart, and an arrowhead from below meets a side of the icon rather than its label where one more bend gets there.
- A generic frame round all of a VPC's AZs (an EKS cluster), round whole VPCs of a Region, or round subnets next to each other in one AZ's rows (a tier) is read through: the presets inside keep the arrangement, and a tier's frame is fitted round its subnets. Full behavior: https://zindex.ai/docs/reference/layout-engine/#aws-architecture-diagrams

After the first save positions are kept, and the edit's changed lists what moved:
- A node an edit adds takes a free place in its row or column. A full row widens every AZ and moves what lies right of it, and a full Region column opens and moves the items below it down.
- createFrame with frame set to the VPC adds an AZ as a new column right of the last.
- An order constraint an edit adds swaps its two nodes when they stand the wrong way around in one row or column. When they can't simply trade places, as in the two halves of a split Region column, it places both again as added nodes, which can grow the row or column.
- The Region's column moves right as one when a labeled line into it needs room, also after an edit that only adds edges.
- A spanning frame an edit adds deepens its rows for its header, moving what lies below.

What it doesn't do, and what to do instead:
- Guess groups from titles: a frame without containerType is laid out as any frame, whatever its title. It gets AWS_GROUP_UNTYPED only when it holds aws:* icons and its title is an AWS group's own name, alone or with one identifier (a letter, or a word with a digit): "VPC", "Private subnet 2", "us-west-2". "VPC endpoint services" gets nothing. Set the preset, or leave the frame generic if it isn't that group (updateFrame with containerType on a saved diagram, then autoLayout for the arrangement).
- Reorder AZs or rows to cut crossings: list them in the order you want.
- Pick a gateway's side: no field does. The engine docks it facing its outside neighbors, and on the top when its lines inside reach several AZs or a load balancer between two (a VPN gateway serving both AZs runs its line over the top). A gateway already placed keeps its side until autoLayout.
- Hold groups across AZs as members: membership is one frame per element. Write a security group or Auto Scaling group across AZs, round subnets or what they hold, with spans instead of children, naming what it surrounds: { id: "asg", kind: "frame", containerType: "aws.autoScalingGroup", title: "Auto Scaling group", spans: ["private_a", "private_b"] }. It is drawn round them with no fill, the VPC's rows keep room for its header in every AZ, and lines cross its border. Its box is one rectangle, so span things that sit together: a node inside it that it doesn't span gets SPAN_COVERS_NODE. No room is kept for one round AZs or VPCs, or in a Region's column, AWS Cloud's row or the outside columns.
- Arrange presets nested where AWS doesn't nest them: such a frame is laid out as any frame, with AWS_GROUP_NESTING. AZs or subnets a Region lists directly are arranged as a VPC with no border drawn (no gateway docks there; put gateways and the load balancer in a VPC); an AZ or subnet outside a VPC or Region is laid out as any frame. A diagram can start at AWS Cloud, a Region or a VPC.
- Arrange through most frames between presets: a generic frame round all of a VPC's AZs, round whole VPCs, or round subnets next to each other in one AZ's rows, is read through, but any other frame between a Region and its VPC, or a VPC and its AZs (round some AZs, or an account or security group there), is laid out as any frame with everything in it (no AZ columns or subnet rows), and one between an AZ and its subnets puts everything in it on one row after the subnets. A generic one gets AWS_FRAME_HIDES_GROUPS, naming the groups it hides and where to list them. List them directly, or put the frame around the whole Region or VPC (a frame holding Regions or VPCs at the top or in AWS Cloud is arranged as AWS Cloud is). A group across AZs round subnets, or what they hold, can be written with spans instead; a spanning frame round AZs or VPCs gets no room for its header.
- Order across groups: an order constraint acts only within one row or column (a subnet's row, AWS Cloud's row, a Region's column, the outside column); one between different rows or columns, and sameRank, is ignored.
- Azure: no presets or icons. Use generic frames, and give icons as data: URIs. Google Cloud has its own (below).
- Stack an icon for several instances: style.multiple does nothing on an aws:* node. Use AWS's own icons, such as "aws:ec2-instances" and "aws:ebs-multiple-volumes".
- Center a node alone in its subnet that connects to only part of the row below: it stands over those nodes, off center.
- Rearrange after edits: a diagram that grew unevenly keeps its shape; send autoLayout to arrange it again (it moves every node).
- Bring saved outside nodes together. A node an edit adds outside AWS Cloud goes on the side of the saved outside nodes it's joined to. A line an edit adds between two saved ones on opposite sides moves neither: send autoLayout to put them on one side (it moves every node).

Don't tint VPCs or subnets (AWS draws groups with no fill) or style the presets: a frame's style overrides its preset. A frame can take an icon too ("aws:lambda" for a group of functions): its border takes the service's color unless style sets a stroke or an accentColor. Don't wrap AWS diagrams in extensions.autoGroup bands; they are skipped here.

## Google Cloud architecture
A Google Cloud diagram needs no coordinates: write Google's groups as frames with their presets, the services as nodes with gcp:* icons, and leave layout off all of them. The engine draws each node as Google's product card and each group as Google's Architecture Center diagrams do, and arranges them the same way.

What to write:
- diagramFamily "architecture" (or none; the arrangement applies to no other family).
- Frames for Google's groups, containerType set, nested as Google nests them: "gcp.cloud" > "gcp.project" (optional) > "gcp.region" > "gcp.subnet" > "gcp.tier" or "gcp.instanceGroup" (a managed instance group); "gcp.onPremises" outside "gcp.cloud". Titles such as "Region: us-central1", "Subnet 10.10.0.0/20" or "Web tier". Keep tier titles short. A "gcp.cloud" with no title, or titled "Google Cloud", draws Google's wordmark; another title is plain text, so name an environment with a "gcp.project" inside it.
- A "gcp.vpc" frame with spans listing its subnets, and a "gcp.zone" frame for each zone of each Region, with spans listing the cards in that zone: { id: "zone_a", kind: "frame", containerType: "gcp.zone", title: "us-central1-a", spans: ["web_1", "primary"] }.
- Nodes with gcp:* icons and short labels that say what they do ("Orders API"; the card adds the product's name), with no shape or layout, and no fill except on a standby (below). List each in the frame it runs in:
  - instances and databases in tiers; an internal load balancer or a Memorystore instance in the subnet, outside the tiers;
  - Cloud Run, Pub/Sub and functions in the Region;
  - the global load balancer, Cloud Armor, Cloud CDN, Cloud DNS, storage and BigQuery in gcp.cloud;
  - users outside gcp.cloud.
- Edges to a tier rather than to each of its cards, as Google draws them. Leave endArrow out: a Google diagram draws Google's chevron by default.

What the engine does:
- Each zone is a column through every tier of its Region, in the order the scene lists the Region's zones, and every zoned card takes one width, so the zone strips line up.
- A subnet's tiers, and the nodes it lists directly, form rows, top to bottom, in the order their edges run:
  - Nodes between two tiers share a row, such as an internal load balancer.
  - A node at a tier's place in the flow goes above it, wherever the subnet lists it. So a cache the app tier feeds goes between the app and database tiers.
  - A node that a line past its row would cross, such as a cache, stands aside from it, right of the tiers when they leave no room.
- Regions stand side by side with their matching rows level, so replication runs straight where no card stands between its ends, and the VPC is one band across them. Where a card does, such as a standby between a primary and its replica, the replication runs under the tier's cards if a labeled line joins two cards of that tier, such as the failover to the standby. Otherwise the router draws it.
- A label on a line that runs straight between matching rows of two neighboring Regions gets room. The gap between the Regions opens to the label's width plus at least 24 px. It stays as it is when the label already fits on a stretch of the line, such as a replication line's run across empty zone columns inside both tiers.
  - The gap doesn't open for a line between different rows, past a card, past a Region, or into a Region with no subnet.
  - There the engine puts the label on a clear stretch of the line, and when it finds none the label can cover a border.
- A line from a tier past another tier drops down a gap between zone columns to a lower tier, a node of a subnet's own row, or one the Region lists below its subnets. This needs two or more zone columns with every card in a zone. The gap opens and the node stands under the line.
- A line past a tier that no zone gap takes, to a node the Region lists above or below its subnets, runs beside the tiers, inside the subnet. It leaves a tier or a node of a subnet's own row, or a card of a tier when the node is below. The node stands under it, or over it when the node is above. The subnet's inset and the gap between the tiers open for it.
  - A side serves one node, the first a line lists. The router draws any other line past a tier, such as one up from a card, to a second node or to a node of a subnet's own row, and can cross the tier.
- A line from an item outside the boundary, above it, into a tier past another tier takes a lane through the Region when the item qualifies (below). The lane is a gap between zone columns, else down the right of the tiers, and the item stands over it. The rest, and the distances: https://zindex.ai/docs/reference/layout-engine/#google-cloud-architecture-diagrams
  - The lane serves a line to a tier or a node of a subnet's own row, and through a gap to a card too. A line to a card where no gap takes it is the router's, and can cross a tier.
  - An item qualifies when all its lines lead into one Region. Each goes into a tier, a card or a node of a subnet's own row past another tier, and none is "curved". A line to another item outside the boundary doesn't count, and a frame counts node by node.
  - Any other line leaves the item no lane, such as one into the first tier, to a global item or a second Region, or up from a tier. The router draws its lines. A global item gets the lane for a tier only, and a line to or from an item outside the boundary doesn't count against it.
  - Items compete for the lane: each takes one gap in the order its first line is listed, and beside the tiers the lane serves one item.
  - Leave `layoutStrategy.direction` off or `TB` for the lane. A left-to-right or right-to-left flow gives none, and a bottom-to-top flow only to an item a top-to-bottom flow would put below the boundary.
  - Leave `router` off, or set it to `orthogonal`: a "curved" edge takes no lane, and a "straight" one crosses any card in its way (EDGE_CROSSES_NODE).
- A line into a card from a row above it, inside the boundary, lands clear of its tier's title. A title about as wide as the card under it, or wider, makes every tier of its Region reach out on the title's side for such a line. A line from outside the boundary keeps off a wide title where a route round it exists and crosses it where none does, so keep such a tier's title short.
- The boundary's other items with more edges leading into the Regions than coming from them form a row above the Regions (load balancer, DNS). Others joined to the Regions form a row below (storage, BigQuery, a bucket the Regions write and read).
  - An item a party outside the boundary calls counts those calls with its lines into the Regions. A sign-in service the users and a Region both call goes above. It goes below when the Regions send it more lines than it sends them and the outside calls together.
  - A dashboard service (a node with the `gcp:looker`, `gcp:looker-studio` or `gcp:looker-studio-pro` icon, or the alias `gcp:data-studio`) goes below the Regions, so the line from its warehouse runs down, when both hold:
    - The lines the Regions send it equal its lines into the Regions plus the outside calls.
    - Every card of the Regions that feeds it ends its Region's flow. In a Region with subnets, that is a card in the row below the subnets. In a Region with none, it is a card with no line to another card of the Region.

    Otherwise the rule above decides. With calls from outside, it puts a tie above, whatever the service. The dashboard rule covers items the boundary or a project lists. A dashboard a Region lists keeps the Region's own rule (below).
  - One joined only to items of its row takes their side (Cloud Armor beside the load balancer). One joined to nothing goes below (observability). Where lines from outside the boundary drop through the row of a load balancer over the gap between two Regions, an item of that row can stand on the other side of it (below).
  - A Region's other items go above or below its subnets by the same rule, without the outside calls. Users stand above the boundary, except those who only use a dashboard service below the Regions (below). A chain that loops back through the subnets, such as a pipeline, a gate, a serving subnet and monitoring that restarts the pipeline, has one line that runs up. The engine places each item by its own lines.
  - A Region with a subnet stands its other items above or below its subnets, each side in one row up to 1,400 px (a frame it lists, such as a cluster, stands as one block). Past 1,400 px, they stand in rows by flow: callers first, the datastore they write to last. A row by flow wider than 1,400 px wraps onto a further row. A Region with no subnet is laid out as any frame, so its items stand in no rows by flow.
- A project, or a generic frame round whole Regions, is one box round its Regions and the items it lists itself. Its items stand in a row over its own Regions, or under them by the rule above.
  - A line that drops through a project's row, or the row `gcp.cloud` lists, makes the row stand aside. The items in the line's way move past it, 16 px clear, and keep their order. The box grows when the row then runs past it. This holds for a line from an item outside the boundary, or a global item over the row, to a card under it. It holds too for a line from a Region's card to an item under the project. A load balancer over the gap between two Regions is the exception (next).
  - A load balancer over the gap between two Regions keeps its place. It feeds the first tier of each of two neighboring Regions, and `gcp.cloud` lists it or the project that lists it holds both Regions. An item of its row that a line from outside the boundary crosses moves to the free place nearest to where it stood, beside the load balancer. Where none is free, it stands over the load balancer.
  - A line that runs level across a card between two projects' rows can't stand a row aside. The router draws an orthogonal line round the cards, and it runs through a card only where no route round the cards exists. The API returns no note for that, so check the image. A "straight" or "curved" edge is never routed round cards: where it crosses one, the save returns EDGE_CROSSES_NODE. Set its `router` to `orthogonal`, or leave `router` off.
- A project's title stands at its top center. It moves to its top left when a line between an item above it and a card under it would run down closer than 16 px to it. It stays at the center when a line would be in the way at the top left too. A project with an `icon`, or no wider than its title needs, keeps its title where it is. Write nothing to place it. The engine moves no card in a Region's row to clear a title.
- On a new layout the boxes of sibling projects don't overlap. A saved diagram keeps its places, except where an edit needs room. If sibling projects' boxes were saved overlapping, the next edit moves the later project, and what lies right of it, right. Send autoLayout to arrange everything again (it moves every node).
- A load balancer listed in a shared network project draws in that project's box, beside the service projects'. To draw one over the projects it feeds, list it in gcp.cloud.
- Items outside the boundary that an edge joins go on one side of it together, so the line between them doesn't wrap around it. They go above it when any of them has more edges into it than out, as users do, else below.
  - A party whose every line with the boundary reaches the row below the Regions goes below the boundary, near the item it calls, so its line is a short rise. A carrier that only delivers files to a landing bucket the Regions write more often than outside parties call it is one. The user-icon rule below can still keep a party above.
    - Parties an edge joins that would stand above go below only when every line any of them has with the boundary reaches that row. They would stand above when any of them has more edges into the boundary than out.
  - A user icon keeps a party above when it has more edges into the boundary than out, even if they all reach that row. A node outside has one when its `icon` is `gcp:user`, `gcp:users`, `aws:user`, `aws:users`, `lucide:user` or `lucide:users`; no other icon counts. A system drawn with one is a user too. A frame outside has one when a node inside it does.
    - A user whose every line with the boundary reaches a dashboard service in that row stands below the boundary with it.
    - One who also has a line with any other item of the boundary stays above, and its line to a dashboard service below the Regions runs around the Region. A user of a dashboard service that stands above the Regions stays above too.
    - Analysts who only read the landing bucket stand above and keep a long line down the boundary's side.
- Each group is fitted to its members; a group's layout is only a minimum. Full behavior: https://zindex.ai/docs/reference/layout-engine/#google-cloud-architecture-diagrams

After the first save positions are kept. An edit moves only what lies past a growth and the nodes named below; the edit's changed lists them, and deleting closes no gap:
- A card: createNode with frame set to its tier, and updateFrame with its zone's whole spans, the card included. It stands in its zone's column. A card placed between the ends of a replication line sends the line under the tier's cards when the failover is labeled; the tier deepens in every Region and the rows under it move down.
- A new zone becomes the Region's last column.
- A new tier, or a node in a subnet such as a cache, goes in at its place in the flow; a new row moves later rows down in every Region.
- A new Region goes right of the last.
- If sibling projects' boxes were saved overlapping, the edit moves the project listed later, and what lies right of it, to the right, until the boxes are as far apart as on a new layout.
- 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.
- A new item of a project takes the free place in the project's row, nearest the nodes it connects to. When the row has no room, the box grows and the project after it moves right by the growth. A project that holds every Region widens on the side the item needs. An item under the Regions grows the box down, and the boundary's items below move down by that.
- A line you add through a saved project's row moves no saved card, and a new item of the row stands 16 px clear of it. The router draws the line round the row's cards where a route round them exists. Where none exists the line crosses a card. The API returns no note for that, so check the image. To stand the row aside from it, send autoLayout (it moves every node).
- A new card of a Region whose cards stand in rows by flow joins the row after the lowest card with an edge into it (the last row, when none follows). With no such edge it joins the row before the highest card it has an edge into (the first row, when none precedes), and with neither, the last row. An edit never adds a row, reorders saved cards or arranges the cards by flow again; send autoLayout for that (it moves every node).
- A new item of the boundary, a Region or the outside takes the free place in its row. New items below a Region's subnets stand clear of a line falling past their row, such as a database's line to its backups, and the Region widens for them when it must. A saved item there moves aside from such a line only where its row has room; else send autoLayout.
- A new item outside the boundary goes on the side of the saved items outside it's joined to.
  - Joined to none, it goes below when its lines reach only dashboard services below the Regions, or only the row below the Regions and it has no user icon.
  - Saved items outside keep their sides. A line an edit adds between two on opposite sides runs around the boundary, and a saved party given lines only into that row stays where it is.
  - To put them on one side, or to stand such a party below, send autoLayout (it moves every node).
- A saved item of the boundary or a Region keeps its row, above or below, when lines you add would give it the other. To move it, send autoLayout (it moves every node).
- A load balancer's new line into a second Region opens the gap between the two Regions, and the load balancer moves to stay over it, when `gcp.cloud` lists it, or the project that lists it holds both Regions. A load balancer one project lists, with the second Region in another project, opens no gap: list it in `gcp.cloud`. Items joined only to the load balancer, in its row or outside the boundary, such as Cloud Armor and the users, move with it where their row has room. Where an item of its row stays, the load balancer stands under it, `layoutStrategy.nodeSpacing` clear (30 px by default); send autoLayout to arrange the row again (it moves every node).
- An item alone in its subnet row and joined only to tiers, such as an internal load balancer between two, moves to stay centered on them when an edit widens them.
- A line you add that the engine runs through a gap between zone columns (above) opens the gap, and what lies right of it moves right by the opening. A line it runs beside the tiers opens the subnet's inset and the gap between two tiers. The rows under the gap move down by its opening, and what lies right of the subnet moves right by the inset's growth. The node the line feeds, in a subnet's own row or below the subnets, moves under it.
- An item outside that you add with its line into a tier stands over the lane where its row has a free place there. Its line is then straight down a gap between zone columns. Where saved items hold that place, the item takes the nearest free place and its line bends to reach the lane. A new item with a line into a card or a node stands over that card or node, and its line bends. Beside the tiers the line turns along the gap over the tier's row.
- A saved item outside doesn't move to the lane. It moves only as far as what lies right of the opening moves.
- A saved item outside loses its lanes when you add a line the lane doesn't serve, such as one into the first tier. The router redraws all its lines, the saved ones too. A line the lane serves that you add from a saved item that already has a line it doesn't serve takes no lane.
- An order constraint you add swaps its two nodes in their row when they stand the wrong way around and their places fit; else both are placed in order as new nodes are. A load balancer over the Region gap keeps its place. New nodes it joins in a row go in the order asked.
- A whole boundary, or a Region with no boundary, that you add to a saved diagram is laid out as on a new one, next to the saved nodes it connects to, which keep their places.

What it doesn't do, and what to do instead:
- Guess groups from titles: a frame without containerType is laid out as any frame, whatever its title. It gets GCP_GROUP_UNTYPED only when it holds gcp:* icons and its title is a Google group's own name, alone or with one identifier (a letter, or a word with a digit): "VPC network", "Region: us-east1", "Subnet 10.0.0.0/20". "VPC Service Controls perimeter" and "Data landing zone" get nothing. Set the preset, or leave the frame generic if it isn't that group. A VPC or zone takes spans: delete the frame and create it again as gcp.vpc or gcp.zone with spans (GCP_GROUP_NESTING says how). Any other group takes updateFrame with containerType on a saved diagram, then autoLayout for the arrangement.
- Arrange presets nested where Google doesn't nest them: such a frame, or a VPC or zone written with children, is laid out as any frame, what it holds loses the arrangement, and it gets GCP_GROUP_NESTING. Nest them as above, and write the VPC and zones with spans.
- Reorder to cut crossings: Regions keep the order gcp.cloud lists them in and zones the order the scene lists them in, so list those as they should read. A subnet's rows follow its edges; listing order breaks ties only among tiers, or among nodes, at one place in the flow. A Region's items in rows by flow stand in an order chosen to cut the crossings between rows, not always to the fewest, and a row that wraps is ordered whole. Items whose lines don't decide their order stand as the Region lists them, so list those as they should read.
- Put cards a tier doesn't hold in zone columns: a node a subnet or Region lists directly stands in a row near its neighbors, or in a row by flow, and a tier a Region lists directly is one block above or below its subnets. Put cards in tiers, and tiers in subnets.
- Arrange through frames between the groups: a project, or a generic frame round whole Regions, is read through for its Regions, and its box is fitted round its Regions and the items it lists itself. Any other frame between them is laid out as one block, and what it holds loses the arrangement. A frame round subnets in a Region, or round tiers in a subnet, gets GCP_FRAME_HIDES_GROUPS; one round cards gets no warning.
- Order across rows: leftOf and rightOf order items within one row; above, below, sameRank and a constraint between two rows are ignored, and a tier's cards keep their zones' columns. To order rows or zone columns, order the edges and list the zones as they should read (Reorder, above).
- Arrange what updateFrame makes Google's: frames it turns into Google groups stay as placed, and new nodes go inside their frames but outside Google's rows and columns, until autoLayout. Send one in the same edit.
- GKE clusters, node pools and folders: Google defines no group for them, so draw them as generic frames. Such a frame is laid out as one block in its row, so the cards in it stand in no zone column. A frame inside another frame has no lane of its own.
  - In a top-to-bottom diagram, a line from a card of such a frame to a card outside it, with another card of the frame in the way, runs in a lane the frame keeps beside or under its cards. Two such lines that would cross in one lane take the lane under the cards and the lane over them. The frame's top grows until the line over the cards runs 16 px under its title. The lanes open in a new layout and after `autoLayout` without `elements`, not when an edit adds the line.
  - In a top-to-bottom Google Cloud diagram, a line that ends on a generic frame laid out as a block, from an item above it, lands on the frame's top 16 px clear of its title, straight under the item. When the title leaves no such place, or the item has another line down, it lands where the router puts it, which can be just above the title.
- Rearrange after edits: a diagram that grew unevenly keeps its shape; send autoLayout to arrange it again (it moves every node).
- Edge labels on a tier's line: the engine wraps a label at 200 px (narrower only where it has no clean place), not at the line's length. A label wider than a line between two cards of one tier hangs out past its ends, so keep it no wider than the line, or break it with \n.

Don't style the presets or give the cards a fill: Google draws its groups and cards in its own colors on every canvas. The exception is a standby resource, such as a Cloud SQL standby, which Google draws on gray. Set its style.fill to "#DADCE0". A read replica keeps the white card.

When one node stands for several instances of one product, such as a set of buckets or one zone's pool of VMs, set style.multiple: true on it. The card draws as a stack, as Google draws one: one gray copy behind the card. A stack is one node, and a node takes at most one zone's strip, so instances spread over zones stay one card per zone. It works with a standby's fill, and a named style can carry it.

What a stack doesn't do (full behavior: https://zindex.ai/docs/reference/rendering/#google-cloud-cards):
- Show a count: it draws one copy however many there are. Put the number in the label when it matters ("Web servers (3)").
- Stack other nodes: only a gcp:* card draws it. A node with another icon or none, an externalSystem node, and BPMN, sequence, ER, org chart and UI flow nodes ignore the key. On those, say it in the label; AWS has its own icons (AWS architecture, above).

## Refining auto-layout results
Use align constraints (addConstraint with type "align") to align nodes within containers on a shared axis. Use order constraints to control spatial relationships between nodes (e.g. source leftOf target). When the engine places the children of a generic frame, it also aligns them on the layout axis, centering the group so nodes appear professionally aligned without manual intervention.

## Hard ordering constraints
Use type: "order" constraints to control node placement when the engine lays out every node. Example: { type: "order", source: "db", target: "api", relation: "rightOf" } ensures the database is placed to the right of the API. Relations: leftOf, rightOf, above, below, sameRank. On a saved diagram, adding an order constraint places its two nodes again, in order, when they aren't already in that order. Every other node keeps its position, except in an AWS or Google Cloud diagram, where the row or column can grow, or an AWS Region's column move right as one for a label's room; the edit's changed lists them. Conflicting constraints are gracefully dropped.

## Styles
The `style` field on every element accepts EITHER a named-style string OR an inline style object - both forms validate.

Inline (put directly on the element): `style: { fill, stroke, strokeWidth, dash, textColor, fontSize, cornerRadius, opacity, accentColor }`. `dash` takes a number array like [4,4] for dashed strokes.
Named (define once in scene.styles, reference by key): `styles: { brand: { fill: "#003366" } }` then `style: "brand"` on each element.

`accentColor` draws on four things:

- an `er.entity` or `er.weakEntity` with `extensions.columns`: its header
- an `org.person` or `org.role`: its stripe
- a `uiflow.screen` or `uiflow.modal`: its title bar
- a frame: its border and title. `stroke` and `textColor` override them, and `fill` tints the frame.

These frames keep their own title color, and their borders take the accent:

- a pool and a fragment
- an aws.* group and a gcp.* group other than a zone
- a frame with an aws:* icon and no preset

A Google Cloud zone and every other kind of element draw nothing for accentColor. A check, save or edit returns ACCENT_COLOR_NOT_DRAWN: remove it from a zone, color a node with `fill` and `stroke`, a line with `stroke`, text with `textColor`.

Text color auto-adjusts for contrast against custom fills if you don't set textColor explicitly. Set textColor to override; an edge label, or a label drawn outside its shape (BPMN events and gateways), is still made lighter or darker if it would be unreadable on what it lands on.

Scene-level palette: set `palette` at the scene root (e.g. `palette: { nodeFill: "#003366", edgeStroke: "#004488" }`) to override theme defaults for all unstyled elements - element explicit styles still win.

Pick colors for a light canvas. A dark preview (`POST /v1/diagrams/preview` with `theme` set to `dark`, `blueprint` or `sketch`, or the playground's theme menu) adapts them, keeping each hue; a dark `palette.background`, or a dark `canvas.background` with none, makes the scene a dark design, drawn as written. MCP's `diagram_render` takes no theme: it draws as saved versions are drawn, in the default style (or `dark` for a dark `canvas.background`), with the scene's colors as written.

## Icons
Set icon to a semantic key. Three packs:
- Lucide (~52): "lucide:database", "lucide:server", "lucide:cloud", "lucide:shield", etc. Match the node's text color.
- AWS (~780, the official AWS Architecture Icons, drawn as AWS ships them): services such as "aws:lambda", "aws:s3", "aws:ec2", "aws:rds", "aws:aurora", "aws:dynamodb", "aws:sqs", "aws:cloudfront", "aws:route53"; resources such as "aws:internet-gateway", "aws:nat-gateway", "aws:application-load-balancer" (alias "aws:alb"), "aws:ecs-task", "aws:ec2-instance"; general icons "aws:users", "aws:client", "aws:internet". Every key: https://zindex.ai/docs/reference/aws-icons/. Every aws:* key that worked before still works, as a key or an alias. A service icon draws at 70 px, a resource or general icon at 42, whatever the node's box; leave the node's size to the engine.
- Google Cloud (~250 keys, Google's product icons, drawn as Google ships them; every key: https://zindex.ai/docs/reference/gcp-icons/). A node with one draws Google's product card, its label over the product's name, whatever its shape.
  - Core products have icons of their own, such as "gcp:compute-engine", "gcp:gke", "gcp:cloud-run", "gcp:cloud-sql", "gcp:bigquery", "gcp:cloud-storage", "gcp:pubsub" and "gcp:cloud-load-balancing".
  - Other products, such as "gcp:firestore", have keys that draw their category's icon. For a product the list lacks, use its category's key, such as "gcp:category-databases", and name the product in the label.
  - People and places: "gcp:users", "gcp:user", "gcp:mobile", "gcp:on-premises".

Your own icon: give it as a data: URI and it is drawn wherever the image is. A URL such as "https://example.com/custom.svg" stays a link in the SVG: images Zindex serves don't load it, nor do most viewers, and PNG output leaves it out; a check or save returns ASSET_URI_POLICY_VIOLATION for it. Built-in icons embed as base64, so the image needs no other request.

AWS icons (aws:*) render icon-only by default - no bounding rectangle - so they sit cleanly inside AWS's groups; an externalSystem node keeps its dashed box with the icon inside, and a non-white fill draws the shape (below). Only the lucide, aws and gcp packs exist. An unknown key, such as an azure:* key, a gcp:* key the set doesn't have or a Lucide name outside the built-in set, renders no icon: an azure:* node keeps its box, and a gcp:* node its card with an empty icon place. The save returns ICON_NOT_FOUND with the keys spelled like it or named for its words. Give any other icon as a data: URI; icon: null on updateNode removes an icon.

AWS Architecture Icons, Release 24 (2026-07-31), © Amazon Web Services, Inc. or its affiliates. Drawn unmodified in architecture diagrams, as AWS allows: https://aws.amazon.com/architecture/icons/. Zindex is not affiliated with or endorsed by AWS.

Google Cloud product icons (Updated May 2026), from https://cloud.google.com/icons. Google Cloud and Google's product names and icons are trademarks of Google LLC. Zindex is not affiliated with or endorsed by Google. People, devices and places draw Google's Material Symbols (Apache License 2.0, https://github.com/google/material-design-icons).

AWS GROUPS (VPCs, Availability Zones, subnets): frames with the aws.* presets, which the engine draws and arranges as AWS does; see AWS architecture above. GOOGLE CLOUD GROUPS (Regions, subnets, tiers, zones): frames with the gcp.* presets; see Google Cloud architecture above.

DO NOT emit defensive 'fill: "#ffffff"' on aws:* nodes - the platform treats explicit "#ffffff" / "#fff" / "white" / "rgba(255, 255, 255, 1)" / "rgba(255, 255, 255, 0)" as default-equivalent (a translucent white such as "rgba(255, 255, 255, 0.85)" is kept, so it draws the shape) and applies the icon-only override anyway, since a white knockout under an AWS icon is essentially never the deliberate choice. To opt into a bounded look, set style.fill to a non-white color ("#ffeeaa", "#dde9fb", "#fefefe") or to "transparent" / "none" for a bordered transparent-fill icon.

The same default-equivalent rule applies to module/group frames inside colored containers, BUT only for binary endpoint values: a frame with fill="#ffffff" or "rgba(255, 255, 255, 1)" inside a colored ancestor frame is overridden to "none" so the ancestor color shows through. Translucent values are PRESERVED, a deliberate card tint. None of this applies to the aws.* presets, which have no fill.

For module/group frames inside colored containers, the recommended alpha is rgba(255, 255, 255, 0.5). This produces a visible-but-subtle white card that lets the parent's color show through clearly. Higher alphas (0.7-0.85) look mostly opaque and obscure the parent color; lower alphas (0.2-0.3) lose the card grouping. 0.5 is the sweet spot. Use no fill (or "none") if you want fully transparent dashed boundaries with no card effect.

EDGES TO A GROUP AS A WHOLE. Edges may target a frame ID directly (not just nodes). The arrow then terminates at the frame's border, on the side facing the source, straight across where the source lines up and otherwise at the side's center. Use this when the connection is semantically abstract - "this thing depends on Regional Services" or "uses the Customer Managed Resources cluster" - rather than a specific service inside. AWS Reference Architecture diagrams draw it the same way: a sidebar group gets one arrow to the group, not one to each service inside.

Two cases for using a frame as the target:

1. Fan-out consolidation. When a source has multiple edges to siblings of a single parent frame and the connection is "this thing connects to the pool as a whole," prefer ONE edge to the parent frame.
   - Consolidate: one edge efs_shared -> file_systems. NOT three edges efs_shared -> fsx_ontap / efs_customer / fsx_lustre.
   - Keep individual: three edges internet_gateway -> alb / nat_gateway / nlb (each load balancer serves different traffic).

2. Abstract group dependency. When a single edge represents "this thing uses the X grouping" without specifying which member, target the frame directly.
   - web_application -> regional_services (the cluster as a whole). NOT web_application -> s3_regional (a specific service that happens to live inside it).
   - api_proxy_lambda -> regional_services. NOT api_proxy_lambda -> dynamodb.

Why it matters for both cases: an edge whose target is inside a frame routes through the frame's border to reach the specific node, which visually reads as "the arrow trails off into the frame interior" - especially when the inner node is a borderless cloud-provider icon. Targeting the frame keeps the arrow tip on the frame's border, matching reference-quality cloud architecture diagrams.
