archify-vscode-ext/vendor/archify/renderers/sequence/README.md

Sequence Renderer

Render diagram_type: "sequence" JSON files into the standard Archify HTML template.

node archify/renderers/sequence/render-sequence.mjs input.sequence.json output.html

The renderer validates input against archify/schemas/sequence.schema.json with the bundled standalone validator. No dependency installation is required.

If output.html is omitted, the renderer uses the required meta.output value from the JSON file.

Input

Sequence JSON files must set:

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": {
    "title": "Cache Miss Request Sequence",
    "output": "cache-miss-request.html",
    "viewBox": [920, 760]
  },
  "participants": [],
  "segments": [],
  "messages": [],
  "activations": [],
  "cards": []
}

The timeline scales with the viewBox height: a taller meta.viewBox buys more message room, a shorter one shrinks the readable band instead of clipping. A complete worked example lives at archify/examples/cache-miss-request.sequence.json.

The schema lives at:

archify/schemas/sequence.schema.json

Legend

The default visual legend derives kinds from messages[].variant (omitting variant means default). Supported meta.legend.entries keys, in stable order, are emphasis, return, security, dashed, and default. These are visual message keys, not Semantic Lens controls; label/visibility overrides do not create edge facts.

The legend sits below all timeline content: the last message and its note, activation bars, and segment frames, with a 12px gap. Without meta.viewBox the canvas grows to keep that gap. With an authored viewBox that is too short, showcase fails with the exact height to set, and standard hides the implicit legend rather than drawing it over content. Lifelines stop above the legend. Message labels use their line's color; gray default and return lines keep the muted text color.

Layout budget

Constant	Value
viewBox	default [920, 760], taller when late content needs legend room; schema minimum [480, 480]
Participant boxes	fixed (default): 86×54 at y 72; spread: viewBox-relative width from 86px up to 190px
Participant columns	fixed: centers at x = 62 + index×108; spread: columns distribute across the available viewBox width
Participant count	the last box must end at or before width − 40; layouts that cannot fit fail closed
Lifelines	from y 142 down to height − 65 (drawn to just above the legend); band must be ≥120px tall
Message y range	[160, height − 83]
Message spacing	≥28px vertical between messages that share horizontal space
Arrow span	≥60px horizontal between the two participants
Segments	y pixel ranges with to > from, inside [72, lifeline bottom + 20]
Legend	last row baseline at height − 54; extra rows wrap upward and stay 12px below the timeline content

segments[].from/to and activations[].from/to are y pixel coordinates, not participant ids; activations also require to > from.

Column fit

Sequence diagrams use meta.column_fit: "fixed" by default so existing documents keep their historical coordinates. Use "spread" when a wide viewBox would otherwise leave empty space on the right or when meaningful participant labels do not fit the fixed 86px boxes. Spread derives box width and column distance from the viewBox while preserving participant order, lifelines, and message semantics.

The artifact checker reports composition.sequenceColumnSpace from the rendered participants, routes and text. A large unused right-hand region in a fixed layout can produce an inspect-sequence-width recommendation in finalize; it is advice, not a new warning or failure. See Sequence width review for the bounded authoring repair and explicit-fixed/legacy preservation rules.

Design Rules

• Put participants across the top, ordered by the story the reader should follow.
• Time moves downward.
• Use emphasis for the main request path.
• Use security for auth, consent, permission, and policy calls.
• Use return for quiet response messages.
• Use dashed for async trace, event, logging, and non-blocking work.
• Use segments as light background guides; keep segment labels short.
• Keep labels concise, but try meta.column_fit: "spread" before shortening a meaningful participant label just to fit the fixed boxes.

Schema violations exit non-zero with path-prefixed messages annotated with the element's id or label. The renderer additionally fails when it can detect layout problems, including missing participants, duplicate participant IDs, participant labels wider than their box, unknown message endpoints, messages outside the readable timeline, overly tight vertical spacing between messages that overlap horizontally, invalid segment or activation ranges, or participants that exceed the viewBox. The shared Clean Flow contract treats participant headers as semantic boxes while explicitly allowing messages to cross intermediate lifelines, activation bars, and segment frames. Text width is estimated CJK-aware: fullwidth glyphs count as two units.

Set meta.quality_profile to showcase for polished delivery. Unrelated proper message X crossings then fail with composition/proper-crossing; default standard keeps them as artifact-receipt warnings. Messages may still cross intermediate lifelines. Collinear corridors remain outside the proper-X rule, but a separate gate warns in standard and fails in showcase when unrelated messages overlap for at least 8px. Shared semantic endpoints, point touches, and shorter overlaps remain valid. Showcase also rejects any route segment below 8px and any interior turn segment below 16px; ordinary 8–15px endpoint stubs remain valid.