Spec Studio

The engine lays out every Studio diagram as static SVG when the page set is built

spec:decisions.studio-diagram-rendererDecision Record · storyready floor ready

Packs: pack:self-hosting-v1, pack:spec-studio-v1

Design: no design entries · no pinned declarations · no decisions

Findings: no errors, no warnings

specs/decisions/studio-diagram-renderer.sdp.md

No open questions and no blocking questions; implementation binding none, verifier binding none, and expected-outcome oracle none.

Intent
outcome
Give the Studio diagrams that a reader with only a link reads without script, that two builds of one graph draw byte for byte, and that need no layout code in the page.
Decision
context
The Studio's pages read in full without script and open from file://, two builds of one graph write the same bytes, and the custom-elements decision admits a framework runtime only through a decision that refines it. The architecture lens, a component's members, a Spec's relations and the code that realizes a Spec all need a drawing. A prototype over the Protocol's own components and the first adopter's, read through sdp q, measured how large those drawings are (reviews/assets/plan46-prototypes/studio-diagrams/).
decision
The engine lays out every Studio diagram at build time with its own deterministic layered layout and writes it into the page as inline SVG followed by a text equivalent. The custom element that holds a diagram adds only pan, zoom and pinch, by changing the SVG's view box. One diagram draws at most the bound spec:consumers.spec-studio.diagrams#design.bound names, and above it the diagram folds, by context and then by layer, as that Spec states.
rationale
  • Inline SVG reads without script, prints, survives the Pack export and opens from file://, so the page carries no layout code and the element stays small.
  • A layout computed from graph values, with no font, clock or random value, draws the same bytes from the same graph, which the Studio's reproducibility rule and --check-clean need.
  • The bound sits between what the two corpora need and what a page reads well: in the prototype the largest real drawing is the Protocol's thirty-five-box member diagram, and a synthetic sixty-two-component drawing spanned about two and a half screen widths unfolded; nothing between forty and sixty-two boxes was measured, and the edge bound is headroom over the thirty-nine edges the largest real diagram draws.
alternatives
  • Mermaid rendered in the page needs its script and a runtime of several hundred kilobytes, lays out differently per browser, and shows nothing without script; the shipped Mermaid projection stays frozen for its own readers.
  • A layout library such as ELK or Dagre run at build time adds a dependency whose version moves the bytes, while the Studio's diagrams need only labelled bands and a grid.
  • Drawing on a canvas from embedded data puts the diagram out of reach of a screen reader, of print and of a reader without script.
consequences
  • The engine owns a small layout module and its tests; the layout's look is judged in review, and its determinism and fold by test.
  • The text equivalent states every box and edge, so a diagram is never the only way to read what it shows.
  • A change to the layout moves the Studio's bytes like any other rendering change, and --check-clean catches one nobody intended.
Verification

Verifier bindings

No verifier binding recorded.

Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
  • Test or oracle bindings: no recorded binding.
Requirement drawing for spec:decisions.studio-diagram-renderer
The diagram as text
  • spec:decisions.studio-diagram-renderer: The engine lays out every Studio diagram as static SVG when the page set is built · declared Spec
  • spec:decisions.studio-web-components: The Studio is built from custom elements, not a framework · declared Spec
  • impl:protocol.studio-diagram-element: adds view-box pan, zoom and pinch to build-rendered SVG without changing its layout · anchored code · src/studio-elements/diagram.ts:23
  • impl:protocol.studio-diagrams: deterministic grid and band layouts with bounded folds and full text equivalents · anchored code · src/projections/studio/diagrams/svg.ts:73
  • spec:decisions.studio-diagram-renderer refines spec:decisions.studio-web-components · declared — narrows how an element that shows a diagram renders it; the element only enhances an SVG the build drew
  • impl:protocol.studio-diagram-element references spec:decisions.studio-diagram-renderer · anchored
  • impl:protocol.studio-diagrams references spec:decisions.studio-diagram-renderer · anchored
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: requirementDiagram. Chosen syntax: flowchart TB because references require exact labels unavailable in requirement syntax.

Decisions

No decision record named.

Runtime

No implementation neighborhood recorded.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact
Relations of spec:decisions.studio-diagram-renderer
The diagram as text
  • spec:consumers.spec-studio.components: The Studio's custom elements each hold one view the build renders
  • spec:consumers.spec-studio.diagram-kinds: The Studio chooses diagram kinds from graph values
  • spec:consumers.spec-studio.diagram-kinds.mermaid-source: A diagram offers Mermaid source as copyable text
  • spec:consumers.spec-studio.diagrams: A diagram is laid out from graph values into SVG with a text equivalent
  • spec:decisions.studio-diagram-renderer: The engine lays out every Studio diagram as static SVG when the page set is built
  • spec:decisions.studio-web-components: The Studio is built from custom elements, not a framework
  • spec:extraction.determinism: Committed source derives byte-identical output
  • spec:decisions.studio-diagram-renderer dependsOn spec:extraction.determinism · declared — a diagram laid out from graph values alone keeps one graph to one set of bytes
  • spec:decisions.studio-diagram-renderer refines spec:decisions.studio-web-components · declared — narrows how an element that shows a diagram renders it; the element only enhances an SVG the build drew
  • spec:consumers.spec-studio.components decidedBy spec:decisions.studio-diagram-renderer · declared
  • spec:consumers.spec-studio.diagram-kinds decidedBy spec:decisions.studio-diagram-renderer · declared — every new kind is laid out by the engine at build time as the renderer decision rules
  • spec:consumers.spec-studio.diagram-kinds.mermaid-source decidedBy spec:decisions.studio-diagram-renderer · declared
  • spec:consumers.spec-studio.diagrams decidedBy spec:decisions.studio-diagram-renderer · declared
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Rests on

Rested on by

Distance 1

  • spec:consumers.spec-studio.components

    Implementing units

    • component:protocol.studio-elements · src/studio-elements/index.ts:13
    • impl:protocol.studio-compose · src/studio-elements/compose.ts:13
    • impl:protocol.studio-diagram-element · src/studio-elements/diagram.ts:23
    • impl:protocol.studio-filter · src/studio-elements/filter.ts:25
    • impl:protocol.studio-intent-panel-element · src/studio-elements/intent-panel-element.ts:14
    • impl:protocol.studio-maturity-map · src/projections/studio/pages/maturity-map.ts:7
    • impl:protocol.studio-pack-page · src/projections/studio/pages/pack-page.ts:68
    • impl:protocol.studio-scenario-editor · src/studio-elements/scenario-editor.ts:17
    • impl:protocol.studio-search-results · src/studio-elements/search-results.ts:95
    • impl:protocol.studio-spec-structure · src/projections/studio/pages/spec-structure.ts:44
    • impl:protocol.studio-verification-panels · src/projections/studio/pages/spec-verification.ts:74

    Referencing units

    None.

    Enabled verifiers: test:protocol.studio-intent-handoff

    Packs: pack:self-hosting-v1, pack:spec-studio-v1

  • spec:consumers.spec-studio.diagram-kinds

    Implementing units

    • impl:protocol.studio-architecture-lens · src/projections/studio/pages/architecture-page.ts:50
    • impl:protocol.studio-capability-diagrams · src/projections/studio/diagrams/capability.ts:101
    • impl:protocol.studio-diagram-layout · src/projections/studio/diagrams/layout.ts:140
    • impl:protocol.studio-diagram-source · src/projections/studio/diagrams/mermaid.ts:13
    • impl:protocol.studio-diagrams · src/projections/studio/diagrams/svg.ts:73
    • impl:protocol.studio-maturity-map · src/projections/studio/pages/maturity-map.ts:7
    • impl:protocol.studio-requirement-diagram · src/projections/studio/diagrams/requirement.ts:12
    • impl:protocol.studio-slice-architecture · src/projections/studio/diagrams/slice.ts:219
    • impl:protocol.studio-slice-dependencies · src/projections/studio/diagrams/slice.ts:10

    Referencing units

    None.

    Enabled verifiers: test:protocol.studio-diagram-catalog

    Packs: pack:roadmaps-and-slices-v1, pack:self-hosting-v1

  • spec:consumers.spec-studio.diagram-kinds.mermaid-source

    Implementing units

    • impl:protocol.studio-diagram-source · src/projections/studio/diagrams/mermaid.ts:13
    • impl:protocol.studio-diagrams · src/projections/studio/diagrams/svg.ts:73

    Referencing units

    None.

    Enabled verifiers: test:protocol.studio-diagram-core

    Packs: pack:roadmaps-and-slices-v1, pack:self-hosting-v1

  • spec:consumers.spec-studio.diagrams

    Implementing units

    • impl:protocol.studio-architecture-diagrams · src/projections/studio/diagrams/architecture.ts:4
    • impl:protocol.studio-diagram-element · src/studio-elements/diagram.ts:23
    • impl:protocol.studio-diagram-model · src/projections/studio/diagrams/model.ts:1
    • impl:protocol.studio-diagrams · src/projections/studio/diagrams/svg.ts:73
    • impl:protocol.studio-relation-diagrams · src/projections/studio/diagrams/bands.ts:10

    Referencing units

    None.

    Enabled verifiers: spec:consumers.spec-studio.diagrams.folds-by-context, spec:consumers.spec-studio.diagrams.folds-by-layer, spec:consumers.spec-studio.diagrams.within-bound, test:protocol.studio-diagram-core

    Packs: pack:self-hosting-v1, pack:spec-studio-v1

Distance 2

Distance 3

Distance 4

Relations

Relation and directionOther endClaimReasonExercised keys
dependsOn · outgoingCommitted source derives byte-identical output
spec:extraction.determinism · resolves		declareda diagram laid out from graph values alone keeps one graph to one set of bytesNone
refines · outgoingThe Studio is built from custom elements, not a framework
spec:decisions.studio-web-components · resolves		declarednarrows how an element that shows a diagram renders it; the element only enhances an SVG the build drewNone
decidedBy · incomingThe Studio's custom elements each hold one view the build renders
spec:consumers.spec-studio.components · resolves		declaredNoneNone
decidedBy · incomingThe Studio chooses diagram kinds from graph values
spec:consumers.spec-studio.diagram-kinds · resolves		declaredevery new kind is laid out by the engine at build time as the renderer decision rulesNone
decidedBy · incomingA diagram offers Mermaid source as copyable text
spec:consumers.spec-studio.diagram-kinds.mermaid-source · resolves		declaredNoneNone
decidedBy · incomingA diagram is laid out from graph values into SVG with a text equivalent
spec:consumers.spec-studio.diagrams · resolves		declaredNoneNone

Bindings

Implementation binding: none

Design reference: present

  • impl:protocol.studio-diagram-element · adds view-box pan, zoom and pinch to build-rendered SVG without changing its layout · src/studio-elements/diagram.ts:23 · role interaction · component component:protocol.studio-elements · layer edge · context protocol
  • impl:protocol.studio-diagrams · deterministic grid and band layouts with bounded folds and full text equivalents · src/projections/studio/diagrams/svg.ts:73 · role projection · component component:protocol.projections · layer edge · context protocol

Verifier binding: none

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.