@agent-native/core 0.80.9 → 0.80.11

package/corpus/templates/design/DESIGN-STUDIO-PLAN.md

@@ -0,0 +1,717 @@
+# Code-Native Design Studio — Canonical Implementation Plan
+
+> Converged plan, merged from two independent passes (Claude + Codex) and their
+> cross-reviews. This is the single source of truth; implement from this doc.
+>
+> - **Product / runtime-tier spine** (the organizing principle).
+> - **Capability matrix + preview/apply actions + application-state shape +
+>   atomic-motion guardrail + screenshot acceptance criteria** (the contract).
+> - **Builder-hosted branch + `fusion` first; our own durable container later.**
+> - **First cheap win: Tokens on the existing Tweaks loop + CSS-first motion on
+>   inline designs.**
+>
+> Visual source of truth: the published visual plan
+> <https://plan.agent-native.com/plans/plan-88dc4a09fb0c46bc> (workbench, motion
+> dock, tokens, states, review, extensions). Its artboards are the acceptance
+> references for the panels below.
+
+---
+
+## 0. Goal & thesis
+
+Turn the Design template into a Figma-class editor where the canvas and the
+codebase are two views of the same product. The thesis: **when a source can
+safely support it, a visual edit writes real code, and a source edit shows up on
+the canvas.** Keep the editor minimal and Figma-esque — left pages/layers,
+central canvas, right inspector, and a bottom dock only when motion or review
+needs it — and add code-backed components, tokens, motion, states/captures,
+accessibility review, visual diffs, assets/shaders/plugins, and a real-app path.
+
+---
+
+## 1. Runtime tiers (the organizing principle)
+
+The editor already has a `sourceType` contract — `inline | localhost | fusion`
+(`templates/design/shared/source-mode.ts`). Treat those as **two capability
+tiers**:
+
+### Tier A — Inline (HTML + Alpine), zero-setup
+
+A design is a sandboxed iframe of semantic HTML + Tailwind + a little Alpine,
+stored in SQL (`designs.data`, `design_files`, rendered via `srcdoc`). No build,
+no module graph, no TypeScript, no real routes/server. This is the instant,
+shareable, "open a URL and design" on-ramp and the default.
+
+### Tier B — Real app (localhost **or** fusion / Builder)
+
+A design is backed by a real React/TS codebase.
+
+- **`localhost`** — the bridge talks to a dev server on the user's machine
+  (`designLocalhostConnections`, `connect-localhost.ts`).
+- **`fusion`** _(the new hosted tier)_ — connect Builder.io and run the app as a
+  Builder-hosted branch (today) or, later, our own durable container. Same
+  capabilities as localhost but hosted, collaborative, and deployable.
+
+> `localhost` and `fusion` are the **same "real app" capability tier** seen
+> through two transports. Everything gated to "real apps" works in both; the only
+> difference is where the code lives.
+
+### 1.1 Tiers are coarse; capabilities are the real gate
+
+The UI must **never infer write ability from `sourceType` alone.** Each source
+advertises an explicit capability set, and every control reads it. A control is
+**enabled**, **preview-only / read-only**, or a **migration CTA** purely as a
+function of capabilities. This is what stops the agent or UI from ever promising
+a write the bridge can't perform (localhost can read but not write _yet_; `fusion`
+starts preview-only until its bridge is real). The tier table in §2 is the
+_consequence_ of these capability sets, not a parallel switch. The capability
+matrix is defined in §5.
+
+---
+
+## 2. Feature tiering — Alpine vs. real app
+
+| Capability                                                                                                                                                                | Inline / Alpine                  | Real app (localhost / fusion) | Why                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------------- | ------------------------------------------------ |
+| Reusable blocks / Alpine "components" — annotate a DOM subtree or `Alpine.data()` island; simple `x-data` variants                                                        | ✅ (kept deliberately **light**) | ✅ (superset)                 | Pure markup                                      |
+| **Full code components** — prop tables from TS / `cva` / `tailwind-variants`, Storybook variants, instance outlines, **jump to source**, edit canonical component, detach | **Real app** → CTA               | ✅                            | Needs module graph + TS types + multi-file edits |
+| Tokens — live CSS-var editing (friendly swatches for the design's own `:root` vars)                                                                                       | ✅                               | ✅                            | Design owns its CSS vars                         |
+| **Tokens-as-code** — parse `globals.css` / `tailwind.config` and **write back to source**                                                                                 | **Real app** → CTA               | ✅                            | Auto-parse + source write-back needs real files  |
+| **Motion** — multi-layer keyframe timeline → managed `<style data-agent-native-motion>` block                                                                             | ✅                               | ✅                            | CSS is the runtime truth; works on any HTML      |
+| Motion source export — write to real CSS modules / `motion`-react two-way / Dev Mode export                                                                               | **Real app** → CTA               | ✅                            | Two-way code round-trip needs real files         |
+| Responsive / breakpoints                                                                                                                                                  | ✅                               | ✅                            | CSS media queries                                |
+| Simple design states (logged out, empty, loading, error) as alternate `x-data` / DOM                                                                                      | ✅                               | ✅                            | Markup snapshots                                 |
+| **Data fixtures & live captures** (real running-app data, route, props, API)                                                                                              | **Real app** → CTA               | ✅                            | No live data on a static design                  |
+| Accessibility audit (contrast, tap targets, roles, alt)                                                                                                                   | ✅                               | ✅                            | Reads the rendered DOM                           |
+| Version diff (`design_versions`)                                                                                                                                          | ✅                               | ✅                            | SQL versions already exist                       |
+| **Real branches + PRs + deploy**                                                                                                                                          | **Real app** → CTA               | ✅                            | Needs git + branch + deploy                      |
+| Extensions / shaders / asset library                                                                                                                                      | ✅                               | ✅                            | Extensions are the Alpine substrate              |
+| Semantic a11y fixes in code; plugins needing the app's own APIs/build                                                                                                     | **Real app** → CTA               | ✅                            | Needs real source / build                        |
+
+**The one-line rule:** if a feature only needs the **rendered DOM or the design's
+own HTML/CSS+SQL**, it ships in Alpine. If it needs the **module graph, TS types,
+a real build, real routes, server data, or git/deploy**, it's a **real-app**
+feature behind a Connect-Builder CTA. _Motion crosses into Alpine because we make
+it CSS-first._
+
+---
+
+## 3. The "Make it real" upgrade flow (Connect Builder)
+
+Advanced panels are never dead ends; they are CTAs. On an inline design, the
+gated controls render an inline upgrade card (progressive disclosure — only when
+the user reaches for a real-app feature):
+
+> **Make this a real app** — connect Builder.io to unlock components, props, data
+> states, branches, and deploys.
+
+### 3.1 What already exists vs. what's new
+
+Most of the backend exists. The genuinely-new pieces are small:
+
+1. **Connect** _(exists)_ — the `connect-builder` card
+   (`packages/core/src/server/agent-chat-plugin.ts`, `kind:
+"connect-builder-card"`, `{ configured, builderEnabled, connectUrl }`) runs the
+   Builder OAuth / `cli-auth` flow and stores a scoped credential
+   (`credential-provider.ts`). `builderEnabled` flips true once a branch project is
+   configured (`resolveBuilderBranchProjectId()`). Vault owns the secret; the app
+   owns a scoped reader.
+2. **Migrate** _(NEW)_ — there is no inline→React migration today. Feed the
+   design's semantic HTML **plus** its `:root` CSS vars / Brand Kit tokens as the
+   seed to the existing Builder cloud agent (`runBuilderAgent()` via
+   `startWorkspaceAppCreation()`, `packages/dispatch/.../app-creation-store.ts`),
+   producing a real React + Tailwind app. Tokens carry over 1:1 by seeding the
+   app's token config from the Brand Kit; annotated Alpine "components" map to real
+   components where possible (`implementWithDesignSystem` / `planWithDesignSystem`
+   from builder-mcp assist).
+3. **Provision** _(exists; today = Builder-hosted branch)_ —
+   `startWorkspaceAppCreation()` returns `{ branchName, url, status }`: a GitHub
+   branch in Builder's hosting running as a full React app, tracked pending until
+   merged. **No per-user container is required for v1.** _Our own isolated dev
+   containers are the `SandboxAdapter` Docker adapter — a blueprint
+   (`packages/core/blueprints/sandbox/docker.md`); only the local child-process
+   adapter is built. Treat self-hosted containers as an optional, heavier
+   follow-on._
+4. **Reconnect** _(NEW — implement `fusion`)_ — flip the design's `sourceType`
+   from `inline` to `fusion` (the enum + i18n exist; the bridge/rendering is the
+   stub to fill in). `fusion` points the editor at the Builder-hosted app's dev URL
+   and uses the bridge for snapshot + code context. Gated panels light up.
+5. **Deploy** _(exists)_ — merge the Builder branch → the existing template deploy
+   path (`packages/core/src/deploy/build.ts`, Netlify / CF Pages).
+
+### 3.2 The three genuinely-new pieces (everything else is reuse)
+
+1. **Migration**: inline HTML/Alpine + tokens → a real React seed for the Builder
+   cloud agent.
+2. **`fusion` source mode**: bridge + rendering so the editor drives a
+   Builder-hosted app the same way it drives an inline iframe.
+3. **Bridge write hardening**: promote `readFile` / `applyEdit` / `writeFile` from
+   `planned` → `available` behind the bridge permission model.
+
+### 3.3 Reversibility
+
+Migration is additive and non-destructive: the original inline design is kept as a
+`design_version` snapshot so "make it real" can be previewed/rolled back. The user
+approves the generated app before cutover.
+
+---
+
+## 4. Architecture
+
+### 4.1 Foundations we reuse (do not rebuild)
+
+- **Source modes & bridge** — `source-mode.ts` defines `inline | localhost |
+fusion` plus the `DesignBridgeRequest` op set: `select`, `resolveNodeToFile`,
+  `readFile`, `applyEdit`, `writeFile`, `captureSnapshot`, `captureState`.
+  `select` / `resolveNodeToFile` / `captureSnapshot` / `captureState` are
+  **`available`**; `readFile` / `applyEdit` / `writeFile` are **`planned`**
+  (`connect-localhost.ts` — _"Local file writes require the next bridge hardening
+  pass"_). The iframe postMessage bridge in `DesignCanvas.tsx` already carries
+  parent→iframe (`tweak-values`, `style-change`, `replace-document-content`,
+  `select-element`, `layer-states`, `delete-element`) and iframe→parent
+  (`element-select`, `visual-style-change`, `visual-structure-change`,
+  `text-content-change`, …). New writes add **named** messages (e.g.
+  `motion-preview`), never ad-hoc ones.
+- **Code-layer projection** — `code-layer.ts` (+ `get-code-layer-projection.ts`)
+  models nodes, selectors, and `CodeLayerSourceSpan` byte offsets, mapping
+  elements to source via `data-agent-native-node-id` (stamped by
+  `ensureCodeLayerNodeIdsInHtml`; rename target `data-agent-native-layer-name`).
+- **Deterministic edit path** — `apply-visual-edit.ts` + the
+  `replace-document-content` bridge message already do inline HTML writes
+  (preview + persist via the Yjs/collab path, `applyLocalContentUpdate`).
+- **Tweaks (CSS-var write path)** — a `TweakDefinition` (`shared/api.ts`) carries a
+  `cssVar`; `resolveTweaksToCssVars` (`resolve-tweaks.ts`, byte-identical
+  client/server) → `{ "--var": value }`; `apply-tweaks` persists to
+  `designs.data.tweakSelections`; the injected `TWEAK_BRIDGE_SCRIPT` applies
+  `tweak-values` live via `documentElement.style.setProperty`. **This is the
+  Tier-A Tokens write path.**
+- **Brand Kit & token parsing** — `packages/core/src/brand-kit/types.ts`
+  (`BrandKitData`) is the shared shape; `DesignSystemData` extends it.
+  `design-token-utils.ts` parses CSS vars (`extractCssVars`), Tailwind
+  (`parseTailwindConfig`), CSS/SCSS (`parseCss`), JSON/theme files, HTML URLs,
+  GitHub (≤10 files), uploads — **import/read-only today** (no write-back).
+  `import-code.ts` is the import entry. `design_systems` rows store a `data` JSON
+  blob; the current UI edits metadata + shows a read-only token preview.
+- **Versions** — `design_versions` exists; reused for diff + migration snapshots.
+- **Canvas frames** — `canvas-frames.ts` + `MultiScreenCanvas.tsx` for overview
+  geometry; reused by states/responsive.
+- **Extensions** — the sandboxed Alpine mini-app substrate +
+  `DesignExtensionsPanel.tsx` inspector slot; shaders/plugins are extensions.
+- **Builder & app-creation** — `connect-builder` card, `runBuilderAgent()`,
+  `startWorkspaceAppCreation()`, `create_workspace_app` (scaffold), `build.ts`
+  (deploy) all exist; the real-app tier wires these, it does not invent them.
+
+### 4.2 Design Surface Index — a lazy read-model, not an up-front cache
+
+Normalize what already exists (nodes, components, tokens, motion, states, review,
+extension contributions) into **one queryable surface** that both UI panels and
+agent actions read. **Grow it lazily from the existing `code-layer.ts` projection
+and per-feature needs; do not build a normalized cache table up front.** Add a
+cache (`design_surface_indexes`) only if/when re-parsing proves to be a real
+performance problem, with incremental rebuilds keyed by file/source hash and an
+initial scope limited to the active route/screen. Shared types live under
+`templates/design/shared/`: `design-surface-index.ts`,
+`design-source-capabilities.ts`, `motion-timeline.ts`, `design-state.ts`,
+`design-review.ts`.
+
+### 4.3 New durable data (additive only)
+
+Additive — never drop/rename/retype. All tables use `ownableColumns()` and are
+read/written through `accessFilter` / `assertAccess`.
+
+```
+component_index            # real-app component metadata
+  id (pk); design_id -> designs.id; source_ref
+  name; file_path; export_name
+  props jsonb              # parsed prop types / cva variants
+  variants jsonb; stories jsonb
+  runtime_selectors jsonb; created_at; updated_at
+
+motion_timeline            # scoped to design + source + screen/file (MANY per design)
+  id (pk); design_id -> designs.id; source_ref
+  file_path                # null for inline (lives in the managed <style> block)
+  tracks jsonb             # [{ target_node_id, property, keyframes:[{t,value,ease}] }]
+                           #   -- multiple target layers, each with property tracks
+  duration_ms; default_ease
+  compiled_hash            # keep timeline JSON and compiled CSS in lockstep
+  created_at; updated_at
+
+design_state               # states, fixtures, captures
+  id (pk); design_id -> designs.id; source_ref
+  name; kind               # 'state' | 'fixture' | 'capture'
+  breakpoint               # 'auto' | 'desktop' | 'tablet' | 'mobile'
+  route; fixture_data jsonb; capture_data jsonb; preview_ref
+  created_at; updated_at
+
+design_review_snapshot     # cache a11y + visual-diff results (add when needed)
+  id (pk); design_id -> designs.id
+  base_version_id; compare_version_id; source_ref
+  a11y_findings jsonb; visual_diff jsonb; status
+  created_at; updated_at
+```
+
+`designs.source_type` already exists; migration flips `inline` → `fusion`.
+`design_versions` is reused for diff + snapshots.
+
+---
+
+## 5. Source capabilities (the contract)
+
+Every source advertises what it can safely do; the UI gates on this, never on
+`sourceType`.
+
+```
+readFile  writeFile  applyEdit  resolveNodeToFile  previewPatch  diffPatch
+captureSnapshot  captureState  indexComponents  indexTokens  writeTokens
+previewMotion  writeMotion  branch  deployPreview  deploy
+```
+
+Behavior:
+
+- **Inline / design-file** — HTML/CSS preview + controlled writes through the
+  existing deterministic path (`replace-document-content` / `apply-tweaks`);
+  `previewMotion` + Tier-A `writeMotion` (managed `<style>` block) and CSS-var
+  token edits are available without the file-write bridge.
+- **localhost** — starts read-only/preview-only; `readFile` / `applyEdit` /
+  `writeFile` become available only after bridge hardening.
+- **fusion (Builder)** — starts preview-only; unlocks the full set
+  (`indexComponents`, `writeTokens`, `writeMotion`, `branch`, `deploy`) once the
+  bridge proves capabilities.
+- A control reads the matrix and renders **enabled**, **preview-only**, or
+  **migration CTA**. The agent reads the same matrix and never claims an
+  unsupported write.
+
+---
+
+## 6. Feature workstreams
+
+Each workstream touches the four required areas — **UI, actions,
+skills/instructions, application state** — and names its Alpine vs. real-app
+behavior. UI binds through `useActionQuery` / `useActionMutation`; never raw fetch.
+
+### 6.1 Editor workbench & components
+
+**UI (matches the workbench artboard):** quiet top toolbar (title, segmented
+`Edit / Interact / Annotate`, device dropdown, zoom dropdown, avatar, Share); left
+rail (search → Screens → Layers, component rows marked with an accent diamond,
+selected instance in a soft accent row); canvas (central frame, selected-instance
+accent outline, a source-aware tag like `PrimaryButton →`, a small bottom local
+toolbar, a compact Motion disclosure); right inspector keeps `Design / Tweaks /
+Extensions` compact, with component details shown **contextually inside Design**
+(no permanent Components tab unless real usage proves the need).
+
+**Alpine:** annotate a DOM subtree with `data-agent-native-component="Name"` (or an
+`Alpine.data()` island); code-layer marks instances; canvas outlines them; the
+Design tab shows the simple `x-data` variants. **Deliberately light — a bridge to
+real apps, not a fake component system.**
+
+**Real app:** `index-components` runs a build-time index (TS prop types, `cva` /
+`tailwind-variants`, Storybook stories) and injects dev metadata
+(`data-agent-native-component`, `data-agent-native-prop-*`, source span) via a
+Vite/Babel transform; canvas outlines real instances; jump-to-source reuses the
+bridge `resolveNodeToFile` op keyed off `data-agent-native-node-id`; the inspector
+renders prop controls from the prop types; detach/instance edits write through the
+bridge. Indexing modes: static AST parse on connect first, dev transform later for
+runtime-variant fidelity; config/annotation escape hatches (`agent-native.design.ts`).
+
+**Acceptance:** selecting a component instance outlines it in the accent color; in
+a real app the inspector shows name, source file, variant/size/state controls,
+token usage, and an **Edit component** action; in Alpine the user gets lightweight
+region hints + the real-app CTA; the agent sees selected-component context via
+`view-screen`.
+
+### 6.2 Tokens / design systems
+
+**UI (matches the tokens artboard):** friendly token names + swatches, CSS-var
+name on the right, type-scale section, radius input, a source chip (e.g.
+`globals.css`), a **New token** action; grouped by color / type / spacing-radius /
+shadows-effects.
+
+**Alpine:** the panel is a first-class face on the **Tweaks** loop — edits go
+through `apply-tweaks` (live `tweak-values` preview, persisted in
+`designs.data.tweakSelections`).
+
+**Real app:** additionally auto-parses `globals.css` / `tailwind.config` / theme
+JSON (`design-token-utils.ts`) and **writes back to source** via `apply-design-token-edit`
+through the hardened write bridge; tokens become tokens-as-code; the Brand Kit is
+the shared shape across Design / Slides / Assets.
+
+**Acceptance:** editing a token previews immediately; writing patches the source
+only through a capability-gated action.
+
+### 6.3 Motion dock (CSS-first; the headline)
+
+**Both tiers.** A `MotionTimeline` compiles into a managed `<style
+data-agent-native-motion>` block targeting layers by `data-agent-native-node-id`.
+The CSS is the runtime truth; the JSON `tracks` only aid editing.
+
+- **UI (matches the motion artboard):** a full-width, collapsible **Motion dock**
+  at the bottom of `DesignEditor.tsx` (animated layer rows, property tracks, time
+  ruler, diamond keyframes, play/scrub, auto-keyframe toggle, **Write to CSS**),
+  with the canvas still visible above; a compact **Motion section** in the
+  inspector for the selected keyframe (numeric + easing + transform/opacity).
+- **Preview:** scrubbing sends preview-only bridge messages (`motion-preview` /
+  playhead); it **never** writes to DB / Yjs / source.
+- **Apply (atomic, non-negotiable):** `apply-motion-edit` updates timeline
+  metadata, compiled CSS, Yjs/collab state, revision check, diff + rollback proof,
+  and iframe refresh **together**; `compiled_hash` guards drift. Include a
+  reduced-motion strategy in both preview and output.
+
+**Real-app superset:** write keyframes into real CSS modules, optional
+`motion`-react round-trip, Dev Mode export.
+
+**Acceptance:** scrubbing never writes; **Write to CSS** is one atomic action with
+diff/rollback proof; multiple layers and tracks animate.
+
+### 6.4 States, responsive & captures
+
+#### Responsive — multi-breakpoint editing (Framer / Figma-Sites style)
+
+Show one screen at several breakpoints **side by side** in the overview and edit
+each independently. Researched models we borrow from:
+
+- **Framer** — Desktop (the parent) + Tablet **810** + Phone **390** as
+  side-by-side frames; added via a **Breakpoint button** on the page selection
+  (infinite, resizable). Desktop-first: a frame drawn on Desktop propagates down to
+  smaller breakpoints; a smaller-breakpoint edit overrides only that frame.
+- **Figma Sites** — Desktop **1280** / Tablet **800** / Mobile **375**; a **`+` in
+  the webpage header on the canvas** adds a predefined or custom width; primary →
+  secondary cascade (default primary = Desktop ⇒ desktop-first); **"Set as primary
+  breakpoint"** flips to mobile-first; per-property, per-breakpoint overrides;
+  **"Reset all changes"** reverts a layer to the inherited (primary) value;
+  responsive components auto-match variants by breakpoint name.
+
+**Our model — mobile-first by default, because the output is Tailwind.** Unlike
+Framer/Figma (desktop-first), we make the **base = mobile** and let larger
+breakpoints layer overrides upward — which is exactly Tailwind's min-width cascade
+(`base` → `md:` → `lg:`). This matches the requested preference and makes "edit on
+screen → responsive class" deterministic.
+
+- **Overview:** a screen carries a **breakpoint set**; `MultiScreenCanvas` renders
+  one iframe **per breakpoint at its width**, laid left→right (Mobile → Tablet →
+  Desktop), all bound to the **same source** (same `srcdoc` for inline, same URL for
+  localhost/fusion). A **`+` at the right edge** adds the next device size
+  (Mobile 390 / Tablet 768 / Desktop 1280, or a custom width). Store the set by
+  extending `canvas-frames.ts` geometry to a per-breakpoint frame list (not a fixed
+  single geometry per file). Frames **snap to Tailwind breakpoint min-widths**
+  (`md` 768, `lg` 1024, `xl` 1280) so each frame maps 1:1 to a prefix.
+- **Per-breakpoint editing = the active frame is the edit scope.** Editing a layer in
+  the **Mobile** frame writes the **unprefixed** class (the base); the same edit in
+  **Tablet** writes `md:…`; in **Desktop** writes `lg:`/`xl:…`. Inherited values
+  cascade up from base unless a prefixed override exists. For non-Tailwind / inline
+  CSS, the edit writes into a `@media (min-width: …)` block in the managed style.
+- **This is the main new code-layer work.** Today the projection **detects but
+  strips** Tailwind `sm:`/`md:`/`lg:` prefixes and all class edits are global
+  (`code-layer.ts`; `EditCapability` has no responsive kind). Add a
+  **responsive-aware class model**: parse class tokens grouped by breakpoint
+  (base, `sm:`, `md:`, `lg:`, `xl:`, `2xl:`), expose each property's value _per
+  breakpoint_, and add an `EditCapability` of `kind: "responsive-class"` whose
+  add/replace targets the active breakpoint's prefix. Surface **override indicators**
+  (which properties differ from base at this breakpoint) with a **Reset to base**
+  affordance (cf. Figma's "Reset all changes").
+- **Tiering:** the multi-frame overview + base/Tailwind-prefix editing works in
+  **Alpine today** — inline designs already load Tailwind CDN + use `sm:/md:/lg:`,
+  the device frame already sets the iframe width, and class edits already flow
+  through the deterministic `replace-document-content` path (no bridge write). For
+  **real apps**, the same per-breakpoint edit writes prefixed classes / media rules
+  to the real source (needs the bridge write hardening, phase 5).
+
+#### States
+
+Design states (Default / Logged out / Empty / Loading / Error and pseudo-states) as
+alternate `x-data` / DOM snapshots in `design_state`. Breakpoint and state are
+**orthogonal axes** — any state can be viewed at any breakpoint.
+
+#### Captures (real app)
+
+`capture-design-state` snaps the running app's route + props + data into a
+`design_state` row (the bridge `captureState` op is **already `available`**).
+
+Selected **breakpoint + state** persist in application state (`breakpoint` already
+in the §8 shape; add `breakpointSetId` / `activeBreakpointId`) and are agent-visible
+via `view-screen`. New actions (§7): `add-breakpoint`, `remove-breakpoint`,
+`set-active-breakpoint`, `reset-breakpoint-overrides`.
+
+#### `visual-edit` skill upgrade
+
+Today `/visual-edit` opens one URL at one size. Upgrade a screen from a single
+URL+size to a **route × breakpoint matrix** — the same URL (or inline design)
+rendered at Mobile/Tablet/Desktop side by side, editing only the frame that needs
+fixing. Identical mechanism for inline (Alpine) and real (React) apps: same source,
+N widths. Flow states (`?step=…`) and breakpoints compose as two axes.
+
+**Acceptance:** a screen shows Mobile/Tablet/Desktop side by side with a `+` to add a
+width; editing a layer in one frame writes a breakpoint-scoped class and the other
+frames reflect the cascade; overridden properties show a reset-to-base control; real
+apps additionally capture running state; the agent sees the selected
+breakpoint/state/route via `view-screen`.
+
+### 6.5 Accessibility & review (read-only first)
+
+`run-design-audit` over the rendered DOM (contrast, tap targets, focus
+visibility, missing names/labels, reduced-motion). The **Review** panel (matches
+the review artboard) shows severity-dot findings with optional **Fix** + a visual
+diff over `design_versions` (base/compare selector, changed-surface rows, before/
+after). Findings navigate to the affected canvas/source node. Fix actions are
+**capability-gated** (semantic code fixes are real-app only).
+
+### 6.6 Branches, Builder & deploy
+
+**Alpine:** version diff between two `design_versions`.
+**Real app:** `connect-builder-app` / `migrate-inline-design-to-app` /
+`create-design-branch` (Builder-hosted branch today via `runBuilderAgent`) /
+`get-design-branch-diff` / `deploy-design-preview`, with rollback. (Our own durable
+container is the later `SandboxAdapter` path.)
+
+### 6.7 Extensions, shaders & assets
+
+Extensions are the substrate (both tiers), inline via `DesignExtensionsPanel`.
+First-party: **asset library** (selection-aware insertion — can ship early),
+**shader fills**, **token auditor**, **motion presets**. **Shaders: preview-first;
+`apply-shader-fill` stays disabled until runtime rendering + a real source-write
+path + a generated fallback + diff proof all exist.** No permanent chrome.
+
+---
+
+## 7. Action surface
+
+Actions are the shared UI/agent contract; every editable surface splits into a
+cheap ephemeral **preview** and a deliberate atomic **apply**.
+
+- **Foundation:** `get-design-surface-index` (read), `refresh-design-surface-index`,
+  `list-design-source-capabilities` (read).
+- **Components:** `index-components`, `get-component-details` (read),
+  `preview-component-prop-edit`, `apply-component-prop-edit`, `open-component-source`.
+- **Tokens:** `index-design-tokens`, `preview-design-token-edit`,
+  `apply-design-token-edit`, `create-design-token`.
+- **Motion:** `get-motion-timeline` (read), `preview-motion-frame`,
+  `apply-motion-edit` (atomic), `remove-motion-timeline`.
+- **States/captures:** `list-design-states` (read), `create-design-state`,
+  `capture-design-state`, `apply-design-state`, `delete-design-state`.
+- **Responsive/breakpoints:** `add-breakpoint`, `remove-breakpoint`,
+  `set-active-breakpoint`, `reset-breakpoint-overrides`. Per-breakpoint style edits
+  reuse `preview-component-prop-edit` / `apply-visual-edit` with an `EditCapability`
+  of `kind: "responsive-class"` scoped to the active breakpoint's Tailwind prefix.
+- **Review:** `run-design-audit`, `get-design-review` (read), `preview-a11y-fix`,
+  `apply-a11y-fix` (gated), `create-design-review-snapshot`.
+- **Builder/branch:** `connect-builder-app`, `migrate-inline-design-to-app`,
+  `create-design-branch`, `get-design-branch-diff`, `deploy-design-preview`.
+- **Extensions/assets/shaders:** `list-design-extensions`,
+  `run-design-extension-action`, `insert-design-asset`, `preview-shader-fill`,
+  `apply-shader-fill` _(stays disabled until contracts are real)_.
+
+Every write action declares its `accessTarget` for the audit log and re-checks
+source capabilities server-side.
+
+---
+
+## 8. Application state
+
+Publish the exact design context so the agent sees what the user sees. `view-screen`
+returns selected component/source metadata, current capabilities, selected token/
+state/motion context, current panel/dock, recent audit/diff summary, and CTA
+availability.
+
+```ts
+type DesignNavigationState = {
+  view: "design-editor" | "design-overview" | "design-review";
+  designId: string;
+  sourceType: "inline" | "localhost" | "fusion"; // Builder is a flavor of fusion
+  screenId?: string;
+  fileId?: string;
+  route?: string;
+  mode: "edit" | "interact" | "annotate";
+  selectedNodeIds: string[];
+  selectedComponentId?: string;
+  selectedTokenId?: string;
+  selectedStateId?: string;
+  inspectorTab: "design" | "tweaks" | "extensions";
+  inspectorSection?:
+    | "component"
+    | "tokens"
+    | "motion"
+    | "states"
+    | "review"
+    | "extension";
+  dock?: { kind: "motion" | "review" | null; open: boolean };
+  motion?: {
+    timelineId?: string;
+    playheadMs: number;
+    selectedTrackId?: string;
+    selectedKeyframeId?: string;
+    previewing: boolean;
+  };
+  breakpoint?: "auto" | "desktop" | "tablet" | "mobile"; // active breakpoint
+  breakpointSetId?: string; // the screen's side-by-side breakpoint set
+  activeBreakpointId?: string; // which frame is the current edit scope
+  sourceCapabilities: string[];
+};
+```
+
+Wire writes through `navigate` / `view-screen` plus selection, motion-dock,
+state, and review state writes.
+
+---
+
+## 9. Agent instructions & skills
+
+Update `templates/design/AGENTS.md`:
+
+- **Mode boundary** — Alpine is lightweight; full components, data states, branches,
+  deploys, and deep token writes are real-app features.
+- **Capability gate rule** — never claim a write unless capabilities advertise it.
+- **Action map** — index/read, component, token, motion, state/capture, review,
+  Builder/branch/deploy.
+- **Motion rule** — preview-only scrubbing; atomic `apply-motion-edit` to commit.
+- **Shader rule** — keep writes gated until runtime/write seams are real.
+- **Visual rule** — preserve the minimal Figma-esque shell and the screenshot
+  acceptance criteria.
+
+Add `.agents/skills/design-studio/SKILL.md`: how to inspect capabilities, index a
+surface before editing, choose Alpine vs real-app behavior, apply token/component/
+motion edits safely, use review outputs, and offer Builder migration CTAs.
+
+---
+
+## 10. Cross-cutting
+
+- **Four areas** — every feature touches UI + actions + skills/instructions + app
+  state.
+- **Preview vs apply** — cheap ephemeral preview (bridge message) vs deliberate,
+  atomic, revision-checked, diffable apply. Scrub/drag/nudge previews; commit writes.
+- **Security** — Builder credentials via Vault + scoped reader (never copied into
+  app rows); all new tables `ownableColumns()` + access-checked; source writes only
+  in capability-advertising modes behind bridge auth.
+- **Reliability** — writes are single atomic actions, never per-frame loops;
+  migration reports proof-of-done.
+
+---
+
+## 11. Rollout phases
+
+0. **Capability gates + CTA skeleton (thin honesty layer).** Sources advertise
+   capabilities; controls gate to enabled / preview-only / migration-CTA; the "Make
+   it real" CTA renders wherever a control is gated. No new _feature_ yet. Cheap;
+   unblocks everything. **Not blocked on bridge write-hardening** — inline writes
+   already work through `replace-document-content` / `apply-tweaks`; hardening lands
+   with the real-app lane (phase 5). Add screenshot visual-regression coverage of
+   the editor shell + panel primitives.
+1. **Tokens + CSS-keyframe Motion on inline (first user-visible win).** Tokens panel
+   on the Tweaks loop; Motion dock with managed-keyframes `apply-motion-edit`. Zero
+   new infra; proves "visual edit → code" at small scale. Ship the cheap half of
+   responsive here too: the **multi-breakpoint preview** — render the same inline
+   source at Mobile/Tablet/Desktop side by side with a `+` to add a width (the device
+   frame already width-controls the iframe; this is just N iframes + a button).
+2. **Components.** Light annotated Alpine components + the real-app component index +
+   prop controls behind the CTA.
+3. **States, responsive & captures.** Design states; the **responsive-aware
+   code-layer** (per-breakpoint Tailwind-prefix editing with override / reset-to-base,
+   the new `kind: "responsive-class"` edit capability) so editing one frame writes a
+   scoped class; then real-app data captures.
+4. **Accessibility + version diff (read-only Review panel).**
+5. **Connect Builder / real-app tier.** Harden bridge writes, implement `fusion`,
+   wire migration; unlock full components / tokens-as-code / branches / deploy.
+6. **Shaders & plugins (gated, last).** Preview-first; apply/export only after
+   runtime + source-write + fallback + diff proof.
+
+**First user-visible milestone:** on an inline design, edit a token (live, persisted)
+and add a keyframe animation that **Write to CSS** commits with a visible diff —
+"visual edit becomes persisted code/CSS" without the whole real-app stack.
+
+---
+
+## 12. Parallel workstreams (clear ownership)
+
+1. Capability gates + surface index (shared types, source-mode contract, index
+   actions, app-state/`view-screen`).
+2. UI shell + visual primitives (chrome, compact rows, swatches, segmented
+   controls, severity rows, property groups, CTA rows; screenshot-matching states).
+3. Components + real-app CTA.
+4. Tokens (parser/indexer, panel, preview/apply).
+5. Motion (timeline model, compiler/parser, dock UI, preview messages, atomic apply).
+6. States/captures.
+7. Review/diff/a11y.
+8. Builder/branches/deploy.
+9. Extensions/assets/shaders.
+
+---
+
+## 13. Verification
+
+- **Unit/action:** surface index builds for inline files; capability gates disable
+  unsupported writes; token parser handles CSS vars + Tailwind; motion compiler
+  emits deterministic CSS and the parser reads the managed block back;
+  `apply-motion-edit` is atomic + revision-checked; component index handles
+  representative React/`cva`; state/capture actions persist + are app-state-visible;
+  audit returns stable findings.
+- **UI (screenshot-driven Playwright):** component-selected workbench, motion dock
+  open, tokens panel, states panel, review panel, extensions panel, the Alpine
+  real-app CTA.
+- **Agent parity:** agent can inspect the selected component via `view-screen`,
+  refresh the index, preview+apply a token edit where supported, add motion
+  keyframes via the action path, create/select a state, run review, and navigate to
+  an affected surface.
+- **Real-app smoke (Builder/React fixture):** select a React component → props +
+  variants → preview a prop edit → apply a safe source edit → parse tokens → apply a
+  token change → capture a route state → run review → produce a branch/visual diff.
+- **Responsive smoke:** a screen renders at Mobile/Tablet/Desktop side by side; a `+`
+  adds a width; editing a layer in the Tablet frame writes a `md:` class while base
+  (Mobile) is untouched; the Desktop frame reflects the cascade; reset-to-base clears
+  the override; the same flow works on an inline design and a real-app URL.
+- **Alpine smoke:** edit layout/styles; preview + persist a CSS-var token change;
+  add simple keyframes and Write to CSS; run a basic a11y scan; see the real-app CTA
+  for full component controls.
+
+---
+
+## 14. Risks & mitigations
+
+- **Split motion source of truth** — CSS is truth, JSON is metadata,
+  `apply-motion-edit` updates both atomically, store `compiled_hash` + revision,
+  provide rollback/diff proof.
+- **Overclaiming localhost/React writes** — strict capability matrix; read-only /
+  preview-only fallback; CTA when the source lacks fidelity. (`readFile` /
+  `applyEdit` / `writeFile` are `planned` today.)
+- **Inspector sprawl** — contextual sections inside the existing inspector; one
+  bottom dock for motion/review; extension-contributed panels; no new top-level tab
+  without usage proof.
+- **Building-the-framework-first** — grow the Surface Index lazily; add cache tables
+  only when re-parsing is a measured problem; first cheap win (Tokens) ships before
+  any framework phase completes.
+- **Over-investing in Alpine components** — keep them annotated regions, not a fake
+  component system; they are a bridge to real apps.
+- **Shader prematurity** — preview-first; apply disabled until runtime + fallback +
+  source write + diff exist.
+- **Component index accuracy** — static AST + config/annotation overrides first;
+  Vite/Babel dev transform later; tie controls to confidence/capability metadata.
+- **Performance** — cache indexes when needed; incremental rebuilds by file/source
+  hash; initial scope = active route/screen; show freshness in UI + actions.
+- **Container assumption** — the real-app tier is a Builder-hosted branch today, not
+  our own container; the Docker `SandboxAdapter` is a later, optional path.
+
+---
+
+## 15. Open decisions
+
+1. **Component indexing transport (real apps)** — Vite/Babel dev transform injecting
+   `data-agent-native-*` metadata (most accurate; needs the dev server wired through
+   the bridge) **[recommended]** vs. static TS/AST parse on connect (no runtime hook,
+   misses runtime-only variants). _Mitigation: ship static first, add the transform
+   for fidelity._
+2. **Motion source format (real apps)** — managed CSS keyframes block **[recommended;
+   one mental model with Alpine]** vs. a `motion`-react representation (richer
+   springs, ties output to the library).
+3. **Real-app hosting** — Builder-hosted branch **[recommended for v1; exists]** vs.
+   our own durable container (`SandboxAdapter` Docker; not built). Affects deploy +
+   data residency.
+4. **Migration fidelity** — pixel-match gate vs. "good enough + agent cleanup"
+   before cutover. Affects how aggressive the Connect-Builder CTA can be.
+5. **Breakpoint defaults & cascade** — mobile-first base + Tailwind min-width prefixes
+   **[recommended; deterministic with our output]** vs. also offering a per-design
+   desktop-first / "set as primary breakpoint" flip like Figma Sites. Default frame
+   widths (390 / 768 / 1280, snapped to Tailwind `md` / `lg` / `xl`) and whether to
+   allow fully custom widths.
+
+```
+
+```