|
| 1 | +# ADR-0037: Live Canvas — draft-overlay live preview while you build |
| 2 | + |
| 3 | +**Status**: Proposed (2026-06-10) |
| 4 | +**Deciders**: ObjectStack Protocol Architects |
| 5 | +**Builds on**: [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (AI authors metadata as DRAFTS; publish is the human gate), [ADR-0021](./0021-analytics-dataset-semantic-layer.md) (datasets as the single analytics form — what dashboards render from), [ADR-0005](./0005-metadata-customization-overlay.md) (the overlay model the draft state lives in) |
| 6 | +**Consumers**: `@objectstack/runtime` + `@objectstack/objectql` (preview data plane — mostly already present), `@objectstack/service-analytics` (Phase 3 draft-data queries), `../objectui` (`data-objectstack` preview client, `app-shell` Live Canvas + assistant bus, view/dashboard renderers), `../cloud` (Build-with-AI entry surface) |
| 7 | + |
| 8 | +**Premise**: pre-launch, no back-compat debt — specify the target end-state directly. |
| 9 | + |
| 10 | +**Design center**: **the magic moment should not be a progress bar that ends in an app — it should be the app itself, taking shape on screen while you talk.** Airtable/Lovable-class builders win on feedback-loop latency: say a thing, *see* the thing. ObjectStack can match that loop **without giving up the ADR-0033 governance gate**, because the thing the user watches is the *draft overlay* rendered live — what you see is exactly what Publish will make real. Their live preview mutates production; ours previews the staged truth. That is a strictly stronger story for the enterprise buyer ("WYSIWYG of the pending change") and an equally strong demo. |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +## TL;DR |
| 15 | + |
| 16 | +Everything hard about live preview already exists in the platform; it has simply never been wired together for the builder: |
| 17 | + |
| 18 | +1. The server can already render the world **as-if-published**: `GET /meta/:type[/:name]?preview=draft` overlays pending drafts on the active registry (list **and** item level, `protocol.getMetaItems/getMetaItem({ previewDrafts })`). The SPA uses this **nowhere** today. |
| 19 | +2. The chat already knows, in real time, **which artifact just changed**: the streaming build tree (`data-build-progress` parts) and every authoring tool's `drafted` envelope name the exact `(type, name)`. |
| 20 | +3. The chat and the host app already share an **event bus** (`assistantBus` in objectui app-shell) with an editor-context primitive. |
| 21 | + |
| 22 | +**Decision.** Ship a split-view **Live Canvas**: chat on the left, the user's app rendered from the **draft overlay** on the right, refreshed per-artifact by the existing stream events. Four phases: (1) static draft preview behind a `?preview=draft` mode + watermark; (2) event-driven live refresh during builds and edits; (3) draft **data** preview (seed rows visible pre-publish — the only genuinely new mechanism); (4) canvas→chat back-channel ("change *this*" while pointing). Publish remains the only commit point; the canvas is a read-only window onto the draft layer. |
| 23 | + |
| 24 | +**Open-core boundary**: the preview data plane (`preview=draft` reads, draft-data query overlay) is **open mechanism** (framework). The Live Canvas surface, the chat wiring, and the build intelligence stay in objectui/cloud. |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## Context |
| 29 | + |
| 30 | +### What already exists (verified 2026-06-10, file-level) |
| 31 | + |
| 32 | +| Capability | Where | Status | |
| 33 | +|---|---|---| |
| 34 | +| Draft-overlay reads, list level | `runtime/src/http-dispatcher.ts` (`query.preview === 'draft'` → `getMetaItems({ previewDrafts })`) | ✅ shipped | |
| 35 | +| Draft-overlay reads, item level | same dispatcher → `getMetaItem({ previewDrafts })`; protocol implements both (`objectql/src/protocol.ts`) | ✅ shipped | |
| 36 | +| Per-artifact change signal, mid-build | `data-build-progress` stream parts (reconciled snapshots; items carry `{type, name}`) | ✅ shipped | |
| 37 | +| Per-artifact change signal, per edit | every authoring tool returns the `drafted` envelope with `(type, name)`; chat already lifts it (`draftReview`) | ✅ shipped | |
| 38 | +| Chat ↔ host event bus | `app-shell/src/assistant/assistantBus.ts` (`requestAssistantReview`, `AssistantEditorContext`) | ✅ shipped | |
| 39 | +| Single metadata entry point in renderers | `DashboardView` / `ObjectView` → `useMetadataClient()` | ✅ shipped | |
| 40 | +| Single governed data entry point | `dataSource.queryDataset` (ADR-0021 path used by `DatasetWidget`) | ✅ shipped | |
| 41 | +| Seed rows materialize on publish | `protocol.publishMetaItem`/`publishPackageDrafts` apply seeds, report `seedApplied` | ✅ shipped (2026-06-10) | |
| 42 | +| SPA usage of `preview=draft` | — | ❌ none (the gap) | |
| 43 | +| Draft **data** (seed rows before publish) | — | ❌ does not exist (Phase 3) | |
| 44 | + |
| 45 | +### Why now |
| 46 | + |
| 47 | +The 2026-06-10 reliability batch closed the failure modes a live canvas would have amplified: dangling dataset references auto-heal, seed data reliably lands on publish (loudly when it can't), the build streams artifact-level progress, and reloaded conversations render honestly. The canvas is now an additive surface over trustworthy primitives, not a magnifier for bugs. |
| 48 | + |
| 49 | +### Non-goals |
| 50 | + |
| 51 | +- **Not** a collaborative multiplayer editor. ADR-0033's single-draft read-modify-write model stays; the canvas only reads. |
| 52 | +- **Not** a bypass of the publish gate. Nothing the canvas shows is live until Publish. |
| 53 | +- **Not** a new renderer. The canvas mounts the *existing* ObjectView/DashboardView/app-shell renderers in preview mode. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## Decision |
| 58 | + |
| 59 | +### Phase 1 — static draft preview (objectui, ~2–3 days) |
| 60 | + |
| 61 | +- `data-objectstack/metadata-client.ts`: `MetadataClientConfig.previewDrafts?: boolean` → `list()`/`get()` append `?preview=draft`. (~30 lines + tests; both endpoints already honor it.) |
| 62 | +- `app-shell`: a `PreviewModeContext` keyed off the URL (`?preview=draft`); `useMetadataClient()` reads it. A persistent **"Draft preview"** watermark bar with one-click exit and one-click Publish. |
| 63 | +- Entry: a **Preview** button next to the chat's existing Review affordance, navigating to the drafted artifact's route with `?preview=draft`. |
| 64 | +- Data plane untouched in this phase: an unpublished object renders with an empty table — structure-WYSIWYG only. |
| 65 | + |
| 66 | +**Acceptance**: an unpublished dashboard/view/app renders fully in the canvas; the watermark is present; after Publish the same route renders identically without it. |
| 67 | + |
| 68 | +### Phase 2 — event-driven live canvas (objectui, ~3–4 days) |
| 69 | + |
| 70 | +- `assistantBus`: `emitCanvasInvalidate({ type, name })` / `subscribeCanvasInvalidate` (mirrors the existing review-request pattern). |
| 71 | +- Both chat hosts (`ConsoleFloatingChatbot`, `AiChatPage`) emit invalidations from (a) `buildProgress.items` diffs and (b) `drafted` envelopes — the data is already in hand; this is wiring. |
| 72 | +- A `LiveCanvas` split-view host: opens automatically for Build-with-AI sessions; re-keys/refetches the affected renderer per `(type, name)`; a ~200 ms coalescing window prevents invalidation storms during whole-app builds. |
| 73 | +- Renderers accept an external refresh key (most already expose a reload hook). |
| 74 | + |
| 75 | +**Acceptance**: during `apply_blueprint` the right pane grows artifact-by-artifact in step with the build tree; an incremental "add a field" edit reflects in the rendered form/kanban in < 1 s. |
| 76 | + |
| 77 | +### Phase 3 — draft data preview (framework, ~1–2 weeks; the only new mechanism) |
| 78 | + |
| 79 | +Options considered: |
| 80 | + |
| 81 | +| Option | Idea | Verdict | |
| 82 | +|---|---|---| |
| 83 | +| A. Client-side sample rows | canvas fabricates rows for draft objects | 1 day, but diverges from the real seed → two sources of truth; rejected | |
| 84 | +| **B-min. In-memory seed overlay (chosen)** | `queryDataset({ previewDrafts })` resolves the object's pending `seed` draft and overlays its parsed rows as the data source, without touching physical tables; reuses `SeedLoaderService` (now in objectql) in a resolve-only mode | smallest honest mechanism; numbers are continuous across Publish because publish materializes the *same* seed | |
| 85 | +| C. Per-session sandbox environment | clone the env for preview | cleanest isolation, heaviest cost; deferred until multiplayer preview matters | |
| 86 | + |
| 87 | +- `service-analytics` dataset executor: when `previewDrafts` is set and the dataset's base object has a pending `seed` draft, evaluate the query over the seed's resolved rows (reference resolution via the existing loader logic, dry-run — no writes). |
| 88 | +- Row reads for plain object views (`/data/{object}` list) get the same overlay behind the same flag, bounded to preview-sized LIMITs. |
| 89 | +- Security: preview queries run under the same org/RLS context as any other read; the flag only changes the *source*, never the principal. |
| 90 | + |
| 91 | +**Acceptance**: mid-build, the drafted dashboard charts real numbers from the drafted seed; after Publish the same widgets show the same numbers from real tables. |
| 92 | + |
| 93 | +### Phase 4 — canvas → chat back-channel (objectui, ~3–4 days) |
| 94 | + |
| 95 | +- The `AssistantEditorContext` primitive already exists; the canvas sets it on hover/selection (`{ type, name, field? }`), the chat injects "the user is pointing at X" into the agent's context. |
| 96 | +- End-to-end: click a kanban column, say "make this red", the right artifact is edited without naming it. |
| 97 | + |
| 98 | +**Acceptance**: context-sensitive edit commands work without the user naming the object/view. |
| 99 | + |
| 100 | +--- |
| 101 | + |
| 102 | +## Risks |
| 103 | + |
| 104 | +| Risk | Mitigation | |
| 105 | +|---|---| |
| 106 | +| Half-formed drafts crash the canvas | per-widget ErrorBoundary (partially present in plugin-dashboard) + canvas-level fallback ("this part of the draft isn't renderable yet") | |
| 107 | +| `preview=draft` exposure | confirm/add a builder/admin role gate on the dispatcher reads; the canvas entry itself is builder-only | |
| 108 | +| Invalidation storms during whole-app builds | coalescing window + only refresh artifacts currently visible | |
| 109 | +| Cache staleness | preview reads are already `cache: no-store` in `MetadataClient` | |
| 110 | +| Concurrent editors | out of scope; single-draft model serializes writers, canvas is a reader | |
| 111 | + |
| 112 | +## Rollout & sequencing |
| 113 | + |
| 114 | +Phase 1+2 land together (one objectui PR + a cloud pin bump) ≈ one week → 80 % of the Airtable feel (structure-level WYSIWYG). Phase 3 is one framework PR ≈ cumulative 2–3 weeks → the full "living app" feel. Phase 4 follows independently. Each phase is separately shippable and separately revertible (the canvas is additive; no existing surface changes behavior when it is closed). |
| 115 | + |
| 116 | +--- |
| 117 | + |
| 118 | +## Amendment (2026-06-10) — product boundaries: one truth, four altitudes |
| 119 | + |
| 120 | +Discussion after the proposal surfaced the integration question: the AI's designs already land in the metadata repository, Studio already exists as the metadata workbench, and the floating AI chat is already everywhere — where does the canvas END and everything else BEGIN? The answer that keeps this from becoming a fourth competing product: **these are not four products; they are one truth (the metadata repository) viewed at four altitudes.** |
| 121 | + |
| 122 | +| Altitude | Surface | Persona | Access | |
| 123 | +|---|---|---|---| |
| 124 | +| L0 — intent | AI chat (floating / Build-with-AI) | anyone | writes drafts via tools | |
| 125 | +| L1 — outcome | **Live Canvas** (this ADR) | app owner / business builder | read-only, `?preview=draft` | |
| 126 | +| L2 — artifact | Studio workbench | developer / implementer | full-fidelity edit (still drafts) | |
| 127 | +| L3 — truth | `sys_metadata` draft+active overlay (ADR-0033) | — | the single store | |
| 128 | + |
| 129 | +All write paths converge on the same draft rows; **Publish remains the single commit gate** shared by every surface. |
| 130 | + |
| 131 | +**Boundary rules (each one is a "we will NOT build"):** |
| 132 | + |
| 133 | +1. **One truth.** The canvas has NO store of its own — no "AI workspace" parallel repository. It renders the same `sys_metadata` rows Studio edits. |
| 134 | +2. **The canvas never edits in place.** It renders and *selects* (point at a widget/field); changing anything goes through exactly two doors — say it (chat → authoring tools → draft) or **"Open in Studio"** (the existing review/designer deep-link). This rule is what guarantees the canvas can never grow into a second Studio. |
| 135 | +3. **There is one chat.** The canvas ships no chat of its own; in build sessions the existing `ChatbotEnhanced` (same conversation, same component) becomes the left pane and the canvas is its result pane. The floating button keeps its role as the everywhere intent-entry; the canvas appears only in building contexts. |
| 136 | +4. **No new lifecycle semantics.** The canvas's Publish calls the existing endpoints; Review deep-links to Studio's diff. Nothing new to govern. |
| 137 | + |
| 138 | +**Relationship to Studio's existing previews**: Studio's dataset-designer live preview (ADR-0021) is *artifact-level* preview; the canvas is *app-level* preview. Both consume the same primitives (`preview=draft` reads; `queryDataset` already accepts inline draft definitions — the hook originally added for Studio preview), so the mechanism is shared, not duplicated. Canvas selection and Studio deep-links ride the same `assistantBus` — three surfaces, one context bus. |
| 139 | + |
| 140 | +This framing also slots ADR-0036 (every app is an API + MCP server) into the same L1 outcome surface — the build-complete state shows "your app + its API + its agent tools" without inventing another surface. |
0 commit comments