Spec Studio

The Studio renders HTML, and the HTML stays derived

spec:decisions.studio-html-surfaceDecision Record · featureready 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-html-surface.sdp.md

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

Intent
outcome
Give reviewers a Studio with search, filters and collapsible views while git diffs stay over canonical Spec source.
Decision
context
When a model writes the Specs, a person's main act is review, and review reads tables, diagrams, code, comparisons and examples across many Specs. The first adopter's reviewers need search, filters, navigation and progressive disclosure across a Pack, which the generated Markdown pages do not give: the Pack page's member table is too wide for those readers, and they open the carrier files instead.
decision
The Studio renders generated HTML as its surface. The HTML is derived and never committed: git diffs stay over the canonical Spec source, and the Studio's files are regenerated from the graph.
rationale
  • HTML conveys more per screen: collapsible sections, wide tables that scroll in place, SVG diagrams, highlighted code and side-by-side comparisons are native to it.
  • HTML is shareable: a page set uploaded to any static host is a link a reviewer opens without installing anything.
  • HTML is interactive: search, filters and navigation run in the page over values the build wrote, which Markdown cannot do.
  • The Studio's code renders its HTML from the graph, so the original's argument from generation time and token cost, which priced a page a model writes, does not apply.
alternatives
  • Markdown renders in Markdown viewers and agents read it as text; the generated Markdown Design Review lacks the Studio's search, filters and collapsible views, so it stays beside the Studio.
consequences
  • The principal trade-off of HTML, diffs that are noisier in git, is sidestepped because the HTML is derived and never committed.
  • The Studio stands beside the Markdown Design Review. The Studio is an interactive workbench, the frozen Markdown Design Review is a generated view for agents and Markdown readers, and git review stays over canonical Spec source; neither view ranks above the other.
  • The case for derived HTML holds for any canonical carrier, because it rests on the HTML being derived and never committed, not on the Specs being written in TypeScript.
  • The richer interactions the original design lists, such as moving a target on a slider, running a scenario harness or reordering members by drag and drop, wait for later phases and their own Specs; the Studio's first build is read-only.
Verification

Verifier bindings

No verifier binding recorded.

Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
  • Satisfying or referencing units: no recorded binding.
  • Test or oracle bindings: no recorded binding.
Requirement drawing for spec:decisions.studio-html-surface

Arrows: refines (declared).

The diagram as text
  • spec:decisions.studio-html-surface: The Studio renders HTML, and the HTML stays derived · declared Spec
  • spec:consumers.spec-studio: The Spec Studio is a static HTML workbench over the one graph · declared Spec
  • spec:decisions.studio-html-surface refines spec:consumers.spec-studio · declared
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred and chosen syntax: requirementDiagram; exact refines, satisfies and verifies, with claim words in nodes and per-edge comments.

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-html-surface
The diagram as text
  • spec:consumers.spec-studio: The Spec Studio is a static HTML workbench over the one graph
  • spec:decisions.studio-html-surface: The Studio renders HTML, and the HTML stays derived
  • spec:extraction.regenerability: Generated artifacts are disposable projections
  • spec:decisions.studio-html-surface dependsOn spec:extraction.regenerability · declared — disposable HTML can be regenerated from the graph instead of committed as authored source
  • spec:decisions.studio-html-surface refines spec:consumers.spec-studio · declared
  • spec:consumers.spec-studio decidedBy spec:decisions.studio-html-surface · 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

    Implementing units

    • impl:protocol.studio-command · src/cli/studio-command.ts:106
    • impl:protocol.studio-data · src/projections/studio/data.ts:279
    • impl:protocol.studio-frame · src/projections/studio/pages/frame.ts:6

    Referencing units

    None.

    Enabled verifiers: test:protocol.studio-publisher

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

Distance 2

Distance 3

Distance 4

Distance 5

Relations

Relation and directionOther endClaimReasonExercised keys
dependsOn · outgoingGenerated artifacts are disposable projections
spec:extraction.regenerability · resolves		declareddisposable HTML can be regenerated from the graph instead of committed as authored sourceNone
refines · outgoingThe Spec Studio is a static HTML workbench over the one graph
spec:consumers.spec-studio · resolves		declaredNoneNone
decidedBy · incomingThe Spec Studio is a static HTML workbench over the one graph
spec:consumers.spec-studio · resolves		declaredNoneNone

Bindings

Implementation binding: none

Design reference: none

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.