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

Lifecycle Renderer

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

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

The renderer validates input against archify/schemas/lifecycle.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

Lifecycle JSON files must set:

{
  "schema_version": 2,
  "diagram_type": "lifecycle",
  "meta": {
    "title": "Deployment Release Lifecycle",
    "output": "deployment-release-lifecycle.html"
  },
  "lanes": [],
  "states": [],
  "transitions": [],
  "cards": []
}

schema_version is 1 or 2; author new diagrams as 2. Lane ids main (required) and terminal are reserved in both versions.

• v2 renders one row per populated lane: main first, terminal last, other lanes in lanes[] order, each titled in the left gutter. A complete example lives at archify/examples/deployment-release.lifecycle.json.
• v1 keeps the fixed three bands: main is the top phase band, terminal the bottom outcome band, and every other lane shares the middle event band, whose header joins their labels with +. A complete example lives at archify/examples/agent-run.lifecycle.json.

The schema lives at:

archify/schemas/lifecycle.schema.json

Legend and state marks

State color follows states[].type: active and start are cyan, waiting amber, decision purple, success green, failure rose, neutral and external slate. Structure is drawn, not colored: every start state gets a UML initial marker (a dot and arrow into its left side), and a state with no outgoing transition gets a double border as a final state (in v1, a main state followed by another main column is not final, because the implied rail continues).

The default legend derives kinds from states[].type; the start entry shows the initial marker, and a non-interactive final entry appears when a final state exists. Supported meta.legend.entries keys, in stable order, are start, active, waiting, decision, success, failure, neutral, and external. Labels and visibility may be overridden through the shared legend contract; only kinds backed by rendered states receive Semantic Legend controls.

State decorations share one top rail: the type sigil and step on the left, the brand mark at the right corner, and the Viewer's runtime source badge just left of the brand. Label layout reserves the badge's width whenever the state has verified repository sources.

Layout budget (v2)

Item	Value
Columns	col 0–4, one x grid shared by every row
Default state	140×64 (text 11px label, 8px sublabel and tag)
Column gap	64px, widened until a labelled same-row neighbour transition fits beside its line; all gaps shrink toward 44px when the canvas would exceed the desktop readability budget of the smallest state text
Row gap	at least 120px, opened further for the horizontal tracks its routes need
Canvas	sized from the rows, columns, and measured legend when meta.viewBox is omitted; an authored viewBox is honored and validated

Transitions without via, a channel, or a non-auto route use the v2 grid router: neighbours in one row connect horizontally (a reciprocal pair runs as two parallel lines), rows connect through the facing top/bottom sides with one turn in a row gap, a state blocking a straight descent sends the route through the empty corridor between columns, and an unlabelled route blocked in an outer column loops around the outside of the grid. Each gap assigns tracks in the order that minimizes crossings. There is no implied rail; a forward transition between two main states without a variant renders as the emphasized primary path. Showcase labels are ranked beside their line, then on it, then outward past neighbouring parallels.

Explicit fromSide / toSide values remain authoritative. Pins that match the grid router's chosen sides keep its routes and adaptive row gaps. If an automatic transition pins a different side, the scene uses the shared side-aware obstacle planner, retaining the v2 state grid and shared port spreading.

Layout budget (v1)

Band	Lane id	Top y	Column centers	Default state
Phase	main (required)	126	col 0–4 → x = 94, 248, 402, 556, 710	118×62
Event	any other id	278	col 0–2 → x = 402, 556, 710	126×58
Outcome	terminal	450	col 0–2 → x = 402, 556, 710	118×58

Event and terminal columns are intentionally offset from the main rail: event/terminal col: N uses the same x coordinate as main col: N + 2. For example, lower-band columns 0, 1, and 2 align beneath main columns 2, 3, and 4 respectively.

Constant	Value
viewBox	default [980, 660]; schema minimum [420, 566]
State area	x within [32, width − 32]; state bottom at or above height − 122
State spacing	≥10px between any two states — checked across lanes, because all event lanes share one band; separate same-band states with col or yOffset
Transition length	≥32px between endpoints
Legend row	final baseline y = height − 36; extra measured rows wrap upward

The primary lifecycle rail runs along the phase band and extends to the furthest occupied phase column. Route presets for transitions: straight, drop (bend at channelY, defaulting to the vertical midpoint), bottom-channel, top-channel, right-channel, left-channel, explicit via points, or the default auto. Multi-segment transitions get rounded corners; tune them with cornerRadius (default 10, 0 for sharp bends).

Transition label and note are independently optional. A non-empty note renders even when label is omitted or empty, using its existing secondary text style on a single row and retaining the note's fine-detail visibility. With both fields present, the note stays below the label. Notes participate in automatic label placement, route-space reservation, and label collision checks; the existing labelAt, labelDx, labelDy, and labelSegment controls also position a note-only text block.

Design Rules

• Treat lifecycle diagrams as a phase map, not a dense state-transition graph.
• Put the primary lifecycle on one horizontal row using the main lane; in v2, author each step of it as a transition.
• In v2, place an interruption, recovery, or exit in the column of the state it leaves so its transition drops straight down.
• Use step labels for ordered phases, such as 01, 02, and 03.
• Use lower lanes only for interruptions, recovery, and terminal exits.
• Keep transition labels out of the main SVG unless the label is essential; prefer node labels, tags, legend entries, and summary cards.
• Prefer axis-aligned lines and avoid crossings. Terminal exits should drop vertically from their source event whenever possible. Explicit straight routes remain supported; see the authored routing contract.
• Use success for completion, failure for failure/terminal exits, waiting for pauses, and decision for quality gates.

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 a missing main lane, duplicate state IDs, unknown lanes, unknown transition endpoints, states outside the lifecycle area, overlapping states (including across lanes), labels colliding with states or other labels, labels wider than their state, unreadably short transitions, or transitions crossing unrelated states (2px Clean Flow clearance). Lifecycle bands remain intentional pass-through containers. Text width is estimated CJK-aware: fullwidth glyphs count as two units.

Set meta.quality_profile to showcase for polished delivery. Unrelated proper X crossings then fail with composition/proper-crossing; default standard keeps them as artifact-receipt warnings. The final artifact check samples rounded Q corners. Collinear corridors remain outside the proper-X rule, but a separate gate warns in standard and fails in showcase when unrelated transitions 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.