Spec Studio

The Studio is built from custom elements, not a framework

spec:decisions.studio-web-componentsDecision 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-web-components.sdp.md

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

Intent
outcome
Let each Studio view work in an HTML page that can load its element script and supply graph data without imposing a framework on that page.
Decision
context
The Studio's views must work inside the Studio and in HTML pages that can load the element script and supply its graph data, such as an exported report, and its assets should stay small and cache well.
decision
The Studio is built from Web Components, custom elements written without React, Vue, Svelte or another framework.
rationale
  • Custom elements avoid a matching framework runtime in every embedding page; the host loads the Studio's element script and supplies the graph data.
  • Element names and attributes are a public embedding contract that is costly to replace; in exchange for framework-independent embedding, the Studio supplies rendering and state handling within its elements.
alternatives
  • Components of React, Vue or Svelte would impose that framework on every page that embeds one of them.
consequences
  • The few elements that need richer state, the harness and the scenario editor, may use a small reactive primitive inside themselves, such as @lit/reactive-element or a signals-style atom, without imposing a framework on the page that embeds them.
  • A host that strips scripts, such as a pull request description, shows a static link to a Studio page, never an element.
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-web-components

Scroll horizontally to read the whole drawing.

Requirement drawing for spec:decisions.studio-web-componentsreferences · anchoredreferences · anchoredreferences · anchoredreferences · anchoredreferences · anchoredreferences · anchoredreferences · anchoredreferences · anchoredrefines · declaredrefines · declaredrefines · declaredIntended Specsspec:decisions.studio-build-rendersThe build renders everyStudio view, and an elementonly enhances it…decisions.studio-build-rendersdeclared Specspec:decisions.studio-diagram-rendererThe engine lays out everyStudio diagram as staticSVG when the page set isbuilt…decisions.studio-diagram-rendererdeclared Specspec:decisions.studio-web-componentsThe Studio is built fromcustom elements, not aframework…decisions.studio-web-componentsdeclared SpecSatisfying or referencingunitsimpl:protocol.studio-architecture-lensrenders recipe componentrows and planned designs asarchitecture and memberdiagrams…protocol.studio-architecture-lensanchored codeimpl:protocol.studio-diagram-elementadds view-box pan, zoom andpinch to build-rendered SVGwithout changing its layout…protocol.studio-diagram-elementanchored codeimpl:protocol.studio-diagramsdeterministic grid and bandlayouts with bounded foldsand full text equivalents…protocol.studio-diagramsanchored codeimpl:protocol.studio-evidence-lensnames the four evidencesources and what wouldbring each into the Studio…protocol.studio-evidence-lensanchored codeimpl:protocol.studio-recipesevaluates shipped recipebodies once and sharesanswers between Studio pages…protocol.studio-recipesanchored codeimpl:protocol.studio-tests-lensrenders shared rule andexample-space coverage withfilters and verifierbindings…protocol.studio-tests-lensanchored codeOutside the selected setspec:consumers.spec-studioThe Spec Studio is a staticHTML workbench over the onegraph…consumers.spec-studiodeclared Spec
The diagram as text
  • spec:decisions.studio-web-components: The Studio is built from custom elements, not a framework · declared Spec
  • spec:decisions.studio-build-renders: The build renders every Studio view, and an element only enhances it · declared Spec
  • spec:decisions.studio-diagram-renderer: The engine lays out every Studio diagram as static SVG when the page set is built · declared Spec
  • spec:consumers.spec-studio: The Spec Studio is a static HTML workbench over the one graph · declared Spec
  • impl:protocol.studio-architecture-lens: renders recipe component rows and planned designs as architecture and member diagrams · anchored code · src/projections/studio/pages/architecture-page.ts:50
  • 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
  • impl:protocol.studio-evidence-lens: names the four evidence sources and what would bring each into the Studio · anchored code · src/projections/studio/pages/evidence-page.ts:3
  • impl:protocol.studio-recipes: evaluates shipped recipe bodies once and shares answers between Studio pages · anchored code · src/projections/studio/recipes.ts:34
  • impl:protocol.studio-tests-lens: renders shared rule and example-space coverage with filters and verifier bindings · anchored code · src/projections/studio/pages/tests-page.ts:34
  • spec:decisions.studio-build-renders refines spec:decisions.studio-web-components · declared — narrows where a view's values come from; the build writes them into the markup, so a host carries that markup and supplies no graph data
  • 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:decisions.studio-web-components refines spec:consumers.spec-studio · declared
  • impl:protocol.studio-architecture-lens references spec:decisions.studio-build-renders · anchored
  • impl:protocol.studio-diagram-element references spec:decisions.studio-diagram-renderer · anchored
  • impl:protocol.studio-diagram-element references spec:decisions.studio-build-renders · anchored
  • impl:protocol.studio-diagrams references spec:decisions.studio-diagram-renderer · anchored
  • impl:protocol.studio-diagrams references spec:decisions.studio-build-renders · anchored
  • impl:protocol.studio-evidence-lens references spec:decisions.studio-build-renders · anchored
  • impl:protocol.studio-recipes references spec:decisions.studio-build-renders · anchored
  • impl:protocol.studio-tests-lens references spec:decisions.studio-build-renders · 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-web-components
The diagram as text
  • spec:consumers.spec-studio: The Spec Studio is a static HTML workbench over the one graph
  • spec:consumers.spec-studio.components: The Studio's custom elements each hold one view the build renders
  • spec:consumers.spec-studio.page-elements: A few custom elements filter, search, open and copy on a rendered page
  • spec:decisions.studio-build-renders: The build renders every Studio view, and an element only enhances it
  • 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:decisions.studio-web-components refines spec:consumers.spec-studio · declared
  • spec:consumers.spec-studio decidedBy spec:decisions.studio-web-components · declared
  • spec:consumers.spec-studio.components decidedBy spec:decisions.studio-web-components · declared
  • spec:consumers.spec-studio.page-elements decidedBy spec:decisions.studio-web-components · declared
  • spec:decisions.studio-build-renders refines spec:decisions.studio-web-components · declared — narrows where a view's values come from; the build writes them into the markup, so a host carries that markup and supplies no graph data
  • 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
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

  • 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.page-elements

    Implementing units

    • component:protocol.studio-elements · src/studio-elements/index.ts:13
    • impl:protocol.studio-copy · src/studio-elements/copy.ts:22
    • impl:protocol.studio-expander · src/studio-elements/expander.ts:16
    • impl:protocol.studio-filter · src/studio-elements/filter.ts:25
    • impl:protocol.studio-search-form · src/studio-elements/search.ts:18
    • impl:protocol.studio-search-results · src/studio-elements/search-results.ts:95
    • impl:protocol.studio-stamp · src/studio-elements/stamp.ts:30

    Referencing units

    None.

    Enabled verifiers: test:protocol.studio-copy-source, test:protocol.studio-page-elements

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

  • spec:decisions.studio-build-renders

    Implementing units

    None.

    Referencing units

    • impl:protocol.studio-architecture-lens · src/projections/studio/pages/architecture-page.ts:50
    • impl:protocol.studio-diagram-element · src/studio-elements/diagram.ts:23
    • impl:protocol.studio-diagrams · src/projections/studio/diagrams/svg.ts:73
    • impl:protocol.studio-evidence-lens · src/projections/studio/pages/evidence-page.ts:3
    • impl:protocol.studio-recipes · src/projections/studio/recipes.ts:34
    • impl:protocol.studio-tests-lens · src/projections/studio/pages/tests-page.ts:34

    Enabled verifiers: None

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

  • spec:decisions.studio-diagram-renderer

    Implementing units

    None.

    Referencing units

    • impl:protocol.studio-diagram-element · src/studio-elements/diagram.ts:23
    • impl:protocol.studio-diagrams · src/projections/studio/diagrams/svg.ts:73

    Enabled verifiers: None

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

Distance 2

Distance 3

Distance 4

Relations

Relation and directionOther endClaimReasonExercised keys
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
decidedBy · incomingThe Studio's custom elements each hold one view the build renders
spec:consumers.spec-studio.components · resolves		declaredNoneNone
decidedBy · incomingA few custom elements filter, search, open and copy on a rendered page
spec:consumers.spec-studio.page-elements · resolves		declaredNoneNone
refines · incomingThe build renders every Studio view, and an element only enhances it
spec:decisions.studio-build-renders · resolves		declarednarrows where a view's values come from; the build writes them into the markup, so a host carries that markup and supplies no graph dataNone
refines · incomingThe engine lays out every Studio diagram as static SVG when the page set is built
spec:decisions.studio-diagram-renderer · resolves		declarednarrows how an element that shows a diagram renders it; the element only enhances an SVG the build drewNone

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.