agentic-dev/docs/decisions/adr-029-designdoc-v1-and-editor-rebuild.md

ADR-029 — DesignDoc v1 as the committed schema; editor rebuilt to conventions

Status: Accepted

Date: 2026-07-12

Context

Two related inheritance questions from the .proto bundle needed resolution before PRDs could be written.

The schema schism. The bundle contains two different design-document models: the tech spec's DesignDoc v1 (§8 — Frame/Element/Text nodes; lit | token | expr prop values where expr renders as a chip and emits verbatim with a review marker; Element nodes referencing arbitrary discovered components; unknown-component error states) and the prototype's VeectNode (13 hardcoded demo-kit types with one flat props bag). This choice is contract-level: design.veect.json is committed on the project's branch and reviewed by engineers in every Veect PR — the single hardest artifact to migrate later.

The inheritance question. The bundle loudly locks "inherit the editor, do not rebuild — the codebase seeds packages/editor". But analysis showed the bundle holds three generations of the editor (React codebase < written design spec < Veect.dc.html interactive prototype), with the codebase missing table-stakes surfaces (history panel, preview overlay, tool pill, ⌘K, toasts, AI ghost rendering, node deletion). The lock's premises also predate the 2026-07-12 decisions: the iframe canvas (ADR-028) retires NodeRenderer — the codebase's biggest organism — from the board path; DesignDoc v1 replaces the store's node model; and the hosted topology (ADR-027) moves the editor into apps/web-next on React 19, ending its Vite standalone-ness. What the lock protected has mostly been invalidated by newer decisions.

Decision

1. DesignDoc v1 (tech spec §8) is the canonical schema for design.veect.json. Zod schemas live in the design-doc feature (entities layer). Element nodes reference discovered components by registry id; prop values are lit | token | expr; expr is never evaluated — it renders as a chip and emits verbatim with a // veect:expr review marker. The Playground's base kit is just another registry, so Playground documents use the same schema.

2. The editor's in-memory model is a view-model with an explicit mapping layer. Whatever shape the editor store needs for interaction performance, it maps to/from DesignDoc v1 at the persistence and codegen boundaries. The prototype's VeectNode shape is at most an internal detail of the Playground — never the committed contract.

3. Code-panel edit mode ships honestly. The bidirectional grammar is proven for the generated shape of registry components; it is not proven for arbitrary hand-written TSX. Edit mode is therefore enabled exactly where the grammar provably round-trips (golden tests emit → parse → emit byte-identical, per spec §12), and the panel downgrades to read-only with an explanatory banner elsewhere (server-component subtrees, expr-bearing nodes, code-owned files). Honesty over false parity — the same voice as the parity-failure state.

4. The editor UI is rebuilt under template conventions, not vendored. This deliberately reverses the bundle's "do not rebuild" lock, for the reasons in Context. The rebuild is conformance-native from day one: components in packages/editor (+ the ink design language in core-ui) with stories and tests as the ESLint rules expect, React 19, store designed around DesignDoc v1 and the iframe canvas.

5. What "inherit the editor" still means — the engine logic and the design. The prototype's pure logic ports as tested libraries: the codegen/parser grammar (generalized per §12), the view-cluster math (views.ts), the Polish rule engine, the AI whitelist sanitizer, color/token math. The interaction design, copy, and visual language port from the design artifacts with this ground-truth order: Veect.dc.html (newest — interaction + copy) > veect-design-spec-current.md > prototype codebase (reference only, never vendored). This amends the bundle's authority table, which had no row for the HTML.

Alternatives considered

• VeectNode as the committed schema, extended with a custom type. Fastest vendoring, no mapping layer. Rejected: bakes demo-kit assumptions into the reviewed contract; migrating design partners' committed JSON later is the migration you never want.
• Vendor the codebase + "editor completion" epic to HTML parity. The pre-grill recommendation. Rejected by the founder in light of ADR-027/028: the completion epic would rebuild the canvas, store, and React version anyway while dragging along un-storied, un-tested vendored files behind a lint-exemption zone.
• Adopt DesignDoc v1 but cut edit mode from v1. Safest. Rejected: the bidirectional grammar is one of the prototype's two headline innovations and the tech spec explicitly adopted it; the honest-downgrade rule contains the risk without cutting the feature.

Consequences

• An editor-foundation PRD (board shell, panels, store on DesignDoc v1, keyboard model, canvas protocol client) precedes the subsystem PRDs that add panels; there is no "editor completion" epic.
• component-must-have-story / component-must-have-test apply to the editor from the first commit — no exemption zone, no tightening debt.
• The grammar's generalization to arbitrary registry components (imports via registry metadata, prop serialization rules, escaping — the prototype never escaped text content) is in scope for the codegen PRD, with the round-trip golden suite as its gate.
• The prototype codebase and .dc.html files are committed as reference material (location decided in the platform-retrofit PRD) so dispatch agents can read them; packages/editor starts empty.
• Node identity across code edits (the prototype minted fresh ids on parse-back, breaking anchor claims) must be solved in the design-doc PRD — stable-id preservation is a schema-level concern.

Related

• ADR-027 (hosted topology — React 19 / web-next placement), ADR-028 (iframe canvas — what the rebuilt board targets)
• Tech spec §8 (DesignDoc v1), §12 (codegen + golden tests); design spec §5 (prototype node model), §9 (grammar)
• Glossary: Design doc, Registry, Iframe canvas, Playground