Koder Kad — visual KVG project editor: product architecture & shared editing layers

Status: draft (proposal). Defines the product Koder Kad (kad, products/horizontal/kad) — the visual editor for KVG projects in the class of Visio + draw.io + SketchUp + AutoCAD + Blender — and, more importantly, the three shared editing layers it stands on so the machinery is reused by Dok and Craft rather than trapped in one product (reuse-first, ≥3 consumers). Name ratified by owner 2026-06-07; registered in component-names.md.

1. Summary

kvg-RFC-001 adds the Interact profile (interactive simulation, parametric lighting, walkable 2D→3D) to the KVG format; specs/kvg/stencils.kmd defines the Stack-level themed object banks. This RFC defines the product that authors such documents — Koder Kad — and factors its non-trivial machinery into three layers with shared homes:

1. KVG editing-core — document model + selectiontransformhit-test/undo over

   the KVG graph. Home: engines/sdk/koder_kit/lib/src/kvg/editor/ (Dart).

2. Stencil-registry client — discoverinstallinsert stencil packs (R8 of

   stencils.kmd). Home: engines/sdk/koder_kit/lib/src/kvg/stencils/ (Dart) + a Go client in the backend.

3. 2D→3D pipeline — the floorplan-extrude (and sibling) kgen packs +

   Interact runtime. Home: engines/lang/kvg/kgen/ (engine-side, authoritative).

Kad is the first/primary consumer; Dok (textual KVG editing) and Craft (graphic design, migrating SVG→KVG) are the 2nd and 3rd consumers that make the shared homes mandatory under policies/reuse-first.kmd (question 2: ≥3 modules).

2. Why a product, and why these layers (recap of kvg-RFC-001 §1 deliberation)

The /k-arch deliberation (option c) concluded: a Visio+SketchUp+Blender surface is a distinct altitude from Dok (text/code editor) and Craft (static graphic design), so it is its own product — but the editing machinery, stencil system, and 2D→3D transform are reusable and must not be trapped inside it. This RFC is the realization of that conclusion. Dimensions in play: D1 (correct contracts), D2 (boundaries: Doktext, Craftdesign, Kad=CAD/3D), D3 (extensible), D10 (reuse).

3. The three shared layers

3.1 KVG editing-core (koder_kit/lib/src/kvg/editor/)

Builds on the existing Dart renderer/parser already in engines/sdk/koder_kit/lib/src/kvg/ (parser, render, kgen, widget).

• Document model — a mutable, observable in-memory tree over the parsed KVG

  graph (nodes, groups, kdef instances, state, rules). Serializes back to canonical .kvg (kvg fmt).

• Selection & transform — hit-test over the rendered scene (2D and projected

  3D), multi-select, transform handles (translaterotatescale/skew in 2D; gizmos in 3D), snapping, alignment, grouping.

• Undo/redo — command stack over document mutations; the unit of collab

  (§5).

• Property surfacing — exposes a node's params and @param knobs

  (kvg-RFC-001 §3.4) as an editable property model the UI binds to.

Contract, not UI. The editing-core is headless (policies/headless-first.kmd): it manipulates the document and emits a render scene; widgets live in the product. This is what lets Dok embed textual editing and Craft embed a design canvas over the same core.

3.2 Stencil-registry client (koder_kit/lib/src/kvg/stencils/ + Go)

Implements stencils.kmd §6/§8 client-side:

• Discover packs from the Hub registry (registries/kvg-stencils.md → Hub

  bundles); cache locally; respect profile_max vs renderer capability.

• Insert (R8): copy the stencil's kdef (transitively) into the document under

  the namespaced name, add the instance, surface its @param knobs.

• User stencils (R7): save a selection as a tenant-scoped stencil via the backend.

3.3 2D→3D pipeline (engines/lang/kvg/kgen/)

• floorplan-extrude kgen pack: 2D plan (walls/openings stencils, Core) →

  Solid geometry (extruded walls, framed openings, floor bounds).

• Interact wiring helpers: bind a first-person camera to bounds, expose sun

  @param azimuth/elevation driving a directional light, generate on tap #switch -> toggle rules per placed fixture.

• Authoritative engine-side (Go + the kgen runtime) so the transform is

  identical whether invoked from Kad, Dok, a CLI, or a server batch.

4. Product structure (products/horizontal/kad/, per RFC-006)

products/horizontal/kad/
├── backend/        # Go API: documents, stencil sync, collab, multi-tenant store
├── app/
│   ├── desktop/    # Flutter (primary surface — large canvas, gizmos)
│   ├── web/        # Flutter Web (kad.koder.dev)
│   └── mobile/     # Flutter (view + light edit; full edit is desktop/web-first)
├── landing/        # kad.koder.dev product landing (specs/landing-pages/products.kmd)
└── backlog/

• App consumes the editing-core + stencil client from koder_kit; renders

  via the existing KVG Flutter widget. Desktop/web are the primary edit surfaces (CAD needs screen real estate); mobile is view + light-edit first.

• Backend (Go) owns: document CRUD, stencil pack sync, user-stencil storage,

  real-time collaboration fan-out, export jobs (PNGSVGglTF/PDF).

• CLI (kad) — headless openvalidateexport/extrude (binary derives from

  slug kad, binaries-and-cli/naming.kmd).

5. Cross-cutting (reuse-first — no new mechanisms)

• Multi-tenancy (policies/multi-tenant-by-default.kmd,

  specs/multi-tenancy/contract.kmd): documents + user stencils keyed by koder_user_id/workspace_id, tenant resolved by auth (never client-supplied), RLS / key-prefix at storage, cross-tenant → 404. From commit 1.

• Storage (stack-RFC-001-kdb-as-unified-data-plane): document metadata +

  state in kdb; large Solid meshes / image assets in the object-storage plane (stack-RFC-006); no bespoke store.

• Collaboration: reuse Koder CRDT (infra/data/crdt) for real-time

  multi-author editing — same primitive Board uses — over the editing-core's command stack. No new sync engine.

• Auth / app behaviors (specs/koder-app/behaviors.kmd): Koder ID sign-in,

  user badge, updates, telemetry per the standard app contract.

• Theme / tokens / i18n / errors: standard cross-cutting specs (verge.kmd,

  light-dark.kmd, i18n/contract.kmd, errors/user-facing-messages.kmd).

• Observability (policies/observability-first.kmd): RED metrics on

  backend, structured logs, traces by trace_id; no PII in telemetry.

6. Consumers & migration (why the layers are shared, not local)

Three concrete consumers of the editing-core ⇒ reuse-first question 2 is satisfied; the shared home is mandatory, not optional (D10).

7. Relation to existing components

• services/ai/scene3d — asset source (text/image→mesh) Kad imports into a

  Solid scene; optional accelerator for floorplan-extrude. No overlap.

• products/horizontal/board — whiteboard; shares the CRDT collab primitive

  but not the KVG editing-core (Board is freehand, not structured KVG). Distinct.

• products/horizontal/craft — graphic design; 3rd consumer of editing-core

  post-migration; stays a distinct product (static design altitude).

• ai-RFC-001 (Generative UI via KVG) — an LLM emitting KVG could target

  Kad's document model + @param surfacing; converge on one host-parameter contract with kvg-RFC-001 §3.4.

8. Open questions

• Q1 Editing-core language: Dart-only (Flutter surfaces) vs a Go core with a

  Dart binding (so the CLI/server share it). Leaning Dart-first (the editor is Flutter-shaped); the engine-side 2D→3D/validation stays Go. Revisit if the server needs interactive editing.

• Q2 Connection semantics for diagrams (BPMN flows, circuit nets): anchors on

  stencils (stencils.kmd Q1) + a thin "connection-rules" module in the editing-core, or a separate diagram-logic layer? Affects where BPMNUMLcircuit validation lives.

• Q3 Mobile edit ceiling — how much structured editing is usable on a phone

  before it's view-only? Sets the mobile surface scope.

9. Next steps

1. /k-new-product kad — create products/horizontal/kad/ skeleton

   (backend + app surfaces + landing + backlog), koder.toml, README, icon master. (invoked alongside this RFC.)

2. Seed kad/backlog/pending/ with the build sequence: editing-core scaffold →

   stencil client → first stencil packs (geometry-2d, flowchart, floorplan) → floorplan-extrude kgen → Interact runtime in the renderer → collab → export.

3. Ratify kvg-RFC-001 (Interact) — gates the simulation/3D-walk tickets.
4. Open the Dok-adoption + Craft-migration follow-up tickets (consumers 2 & 3).
5. Register kad.koder.dev (landing + web app) per

   specs/landing-pages/products.kmd URL pattern.