@agent-native/core 0.79.27 → 0.80.0

package/corpus/templates/clips/desktop/src/lib/voice-dictation.ts

@@ -1,3 +1,4 @@
+import type { VoiceContextPack } from "@agent-native/core/voice";
 import { invoke } from "@tauri-apps/api/core";
 import { emit, listen } from "@tauri-apps/api/event";
 
@@ -5,6 +6,7 @@ import { applyBacktrack } from "./backtrack";
 import {
   configureVocabularyClient,
   loadVocabulary,
+  loadVocabularyEntries,
   recordPasteForLearn,
 } from "./personal-vocabulary";
 import {
@@ -312,6 +314,7 @@ async function transcribe(
   providerPref: ServerVoiceProvider,
   controller: AbortController,
   instructions?: string,
+  contextPack?: VoiceContextPack,
 ): Promise<string> {
   const audioBlob = new Blob(chunks, { type: mimeType });
   const form = new FormData();
@@ -329,6 +332,7 @@ async function transcribe(
   if (trimmedInstructions) {
     form.append("instructions", trimmedInstructions);
   }
+  appendVoiceContext(form, contextPack);
   // Aggressive timeout — short clips should transcribe in well under
   // 2 seconds with Gemini Flash Lite or Whisper. If the server hasn't
   // come back in 8s it's hanging; abort and let the bar dismiss with an
@@ -367,6 +371,7 @@ async function cleanupTranscript(
   providerPref: ServerVoiceProvider,
   controller: AbortController,
   instructions?: string,
+  contextPack?: VoiceContextPack,
 ): Promise<string> {
   const form = new FormData();
   form.append("text", text);
@@ -375,6 +380,7 @@ async function cleanupTranscript(
   if (trimmedInstructions) {
     form.append("instructions", trimmedInstructions);
   }
+  appendVoiceContext(form, contextPack);
 
   const timeout = window.setTimeout(() => controller.abort(), 8_000);
   try {
@@ -400,6 +406,18 @@ async function cleanupTranscript(
   }
 }
 
+function appendVoiceContext(
+  form: FormData,
+  contextPack: VoiceContextPack | undefined,
+): void {
+  if (!contextPack) return;
+  try {
+    form.append("voiceContext", JSON.stringify(contextPack));
+  } catch {
+    /* best effort */
+  }
+}
+
 export function installDesktopVoiceDictation(
   options: DesktopVoiceDictationOptions,
 ): () => void {
@@ -640,6 +658,7 @@ export function installDesktopVoiceDictation(
       const controller = new AbortController();
       target.transcribeAbort = controller;
       try {
+        const contextPack = await buildDesktopVoiceContextPack();
         text =
           (await cleanupTranscript(
             serverUrl,
@@ -647,6 +666,7 @@ export function installDesktopVoiceDictation(
             target.cleanupProvider,
             controller,
             instructions,
+            contextPack,
           )) || original;
       } catch (err) {
         if ((err as { name?: string })?.name !== "AbortError") {
@@ -709,6 +729,42 @@ export function installDesktopVoiceDictation(
     micDeviceLabel: micDeviceLabel || null,
   });
 
+  const buildDesktopVoiceContextPack = async (): Promise<
+    VoiceContextPack | undefined
+  > => {
+    const vocabulary = await loadVocabularyEntries().catch(() => []);
+    const terms = vocabulary.map((entry) => ({
+      term: entry.term,
+      replacement: entry.replacement,
+      confidence: entry.confidence,
+      source: "learned-correction",
+      scope: "user",
+    }));
+    const snippets: NonNullable<VoiceContextPack["snippets"]> = [
+      { label: "Target surface", value: "Desktop dictation paste" },
+    ];
+    if (micDeviceLabel) {
+      snippets.push({ label: "Microphone", value: micDeviceLabel });
+    }
+    if (instructions.trim()) {
+      snippets.push({
+        label: "Saved voice instructions",
+        value: instructions.trim().slice(0, 1200),
+      });
+    }
+    return {
+      surface: "clips-desktop",
+      mode: "dictation",
+      snippets,
+      terms,
+      metadata: {
+        provider,
+        locale: navigator.language || "en-US",
+        micDeviceLabel: micDeviceLabel || null,
+      },
+    };
+  };
+
   /**
    * Server-path: capture audio with MediaRecorder, POST it to the
    * transcribe-voice endpoint on Fn-up, paste the response text. The
@@ -790,6 +846,7 @@ export function installDesktopVoiceDictation(
         const controller = new AbortController();
         next.transcribeAbort = controller;
         try {
+          const contextPack = await buildDesktopVoiceContextPack();
           const text = await transcribe(
             serverUrl,
             next.chunks,
@@ -797,6 +854,7 @@ export function installDesktopVoiceDictation(
             providerPref,
             controller,
             instructions,
+            contextPack,
           );
           if (next.cancelled) {
             cleanup(next);
@@ -920,7 +978,8 @@ export function installDesktopVoiceDictation(
         // metadata to `native_speech_start` without also carrying vocabulary.
         // Best-effort — if the load failed we just stage an empty list and
         // the recognizer behaves as before.
-        const contextualStrings = await loadVocabulary().catch(() => []);
+        const vocabularyEntries = await loadVocabularyEntries().catch(() => []);
+        const contextualStrings = vocabularyEntries.map((v) => v.replacement);
         await invoke("native_speech_set_vocabulary", {
           strings: contextualStrings,
         }).catch(() => {});

package/corpus/templates/content/app/components/editor/DocumentDatabase.tsx

@@ -7824,7 +7824,7 @@ function DatabaseTimelineView({
                   <div
                     key={`${dateKey}-header`}
                     className={cn(
-                      "sticky top-0 z-10 grid gap-0.5 border-r border-b border-border bg-background/95 px-2 py-2 backdrop-blur last:border-r-0",
+                      "sticky top-0 z-10 grid gap-0.5 border-r border-b border-border bg-background px-2 py-2 last:border-r-0",
                       !inMonth && "bg-muted/70",
                     )}
                     style={{ gridColumn: index + 1, gridRow: 1 }}

package/corpus/templates/content/app/components/editor/database/DatabaseView.tsx

@@ -7767,7 +7767,7 @@ function DatabaseTimelineView({
                   <div
                     key={`${dateKey}-header`}
                     className={cn(
-                      "sticky top-0 z-10 grid gap-0.5 border-r border-b border-border bg-background/95 px-2 py-2 backdrop-blur last:border-r-0",
+                      "sticky top-0 z-10 grid gap-0.5 border-r border-b border-border bg-background px-2 py-2 last:border-r-0",
                       !inMonth && "bg-muted/70",
                     )}
                     style={{ gridColumn: index + 1, gridRow: 1 }}

package/corpus/templates/content/app/components/sidebar/DocumentSidebar.tsx

@@ -701,7 +701,7 @@ export function DocumentSidebar({
 
   if (collapsed) {
     return (
-      <div className="flex flex-col h-full w-12 border-e border-border bg-muted/30 items-center py-3 gap-1">
+      <div className="flex h-full w-12 flex-col items-center gap-1 border-e border-border bg-muted/30 py-3 transition-[width] duration-200 ease-out">
         <Tooltip>
           <TooltipTrigger asChild>
             <button
@@ -763,7 +763,7 @@ export function DocumentSidebar({
   return (
     <div
       className={cn(
-        "agent-layout-left-drawer relative flex h-full min-h-0 flex-col border-e border-border bg-muted/30",
+        "agent-layout-left-drawer relative flex h-full min-h-0 flex-col border-e border-border bg-muted/30 transition-[width] duration-200 ease-out",
         width === undefined && "w-full",
       )}
       style={width === undefined ? undefined : { width, flexShrink: 0 }}
@@ -962,14 +962,14 @@ export function DocumentSidebar({
         </div>
       </ScrollArea>
 
-      <div className="shrink-0 border-t border-border px-3 py-2">
+      <div className="shrink-0 px-3 py-2">
         <div className="space-y-1">
           {renderLocalFilesNavButton()}
           {renderSettingsNavButton()}
         </div>
       </div>
 
-      <div className="shrink-0 border-t border-border">
+      <div className="shrink-0">
         <ExtensionSlot
           id="content.sidebar.bottom"
           context={{
@@ -985,7 +985,7 @@ export function DocumentSidebar({
       </div>
 
       {/* Footer */}
-      <div className="shrink-0 space-y-2 border-t border-border px-3 py-2">
+      <div className="shrink-0 space-y-2 px-3 py-2">
         <OrgSwitcher />
         {isCodeMode ? <DevDatabaseLink /> : null}
         <div className="flex items-center gap-1">

package/corpus/templates/content/changelog/2026-06-28-left-sidebar-collapse-motion-and-footer-chrome-are-quieter.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-06-28
+---
+
+Left sidebar collapse motion and footer controls now feel smoother and use less divider chrome.

package/corpus/templates/design/.agents/skills/visual-edit/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: visual-edit
+description: >-
+  Open a running local app in Design overview mode as URL-backed iframe screens
+  for visual editing, flow review, duplication, and route-state exploration.
+metadata:
+  visibility: exported
+---
+
+# Visual Edit
+
+Use `/visual-edit` when the user wants to inspect or edit a real local app
+visually instead of generating standalone Alpine HTML. The source of truth is
+the running localhost app plus its route URLs. Design shows those routes as
+iframe-backed screens on the infinite canvas.
+
+## Core Model
+
+- Each screen is a URL-backed iframe, not copied HTML.
+- Each screen keeps its own URL metadata: `connectionId`, `routeId`, `path`,
+  `url`, `bridgeUrl`, title, and viewport size.
+- Start in Design's screen overview mode. The user can edit/select/drop on any
+  visible screen from the overview canvas.
+- In overview, screens are static like Figma frames: no iframe scrolling or app
+  interaction. Full-screen focus is for scrolling and app interaction.
+- Alt-drag duplicates a screen. For localhost screens, duplication copies the
+  iframe frame and URL metadata; change the copy's path/query when you need a
+  new flow state.
+- Flow visualization is just multiple URL states: `/checkout?step=shipping`,
+  `/checkout?step=payment`, `/checkout?step=done`, etc.
+
+## Required Local Bridge
+
+From the target app repo, make sure its dev server is running, then run the
+Design bridge with `npx`:
+
+```bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
+```
+
+Use the app's real port. The command starts a local bridge on
+`http://127.0.0.1:7331` by default and exposes:
+
+- `GET /manifest.json` — dev server URL, bridge URL, discovered routes, root.
+- `GET /routes.json` — route manifest only.
+- `GET /health` — bridge liveness.
+
+For one-shot agent setup, ask for JSON and keep the long-running bridge open in
+a second terminal if the user needs live updates:
+
+```bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json
+```
+
+## Action Flow
+
+1. Register or refresh the bridge in Design:
+
+```bash
+pnpm action connect-localhost '{
+  "devServerUrl": "http://localhost:5173",
+  "bridgeUrl": "http://127.0.0.1:7331",
+  "rootPath": ".",
+  "routeManifest": { "version": 1, "sourceType": "localhost", "routes": [] }
+}'
+```
+
+Prefer passing the actual `/manifest.json` result as `routeManifest` and
+`capabilities`. Keep any local filesystem paths out of user-facing summaries
+unless the user asks.
+
+2. Create or reuse a Design project:
+
+```bash
+pnpm action create-design --title "Local app visual edit" --projectType prototype
+```
+
+3. Place URL-backed screens on the overview canvas:
+
+```bash
+pnpm action add-localhost-screens '{
+  "designId": "<design-id>",
+  "connectionId": "<connection-id>",
+  "routes": [
+    { "path": "/", "title": "Home", "width": 1280, "height": 900 },
+    { "path": "/pricing", "title": "Pricing", "width": 1280, "height": 900 },
+    { "path": "/checkout?step=payment", "title": "Checkout payment", "width": 1280, "height": 900 }
+  ],
+  "startX": 0,
+  "startY": 0,
+  "gap": 160
+}'
+```
+
+If no `routes` or `paths` are supplied, `add-localhost-screens` uses every route
+from the latest localhost manifest. Use `paths` for a concise flow:
+
+```bash
+pnpm action add-localhost-screens '{
+  "designId": "<design-id>",
+  "paths": ["/", "/pricing", "/checkout?step=payment"]
+}'
+```
+
+4. Navigate the user to overview mode:
+
+```bash
+pnpm action navigate --view editor --designId "<design-id>" --editorView overview
+```
+
+## Editing URLs
+
+To change a localhost screen's URL, update that screen through
+`add-localhost-screens` again using the same route-derived filename/path or use
+normal Design screen duplication followed by a route/path update. Keep the file
+content as the absolute URL and keep `screenMetadata[fileId]` aligned:
+
+```json
+{
+  "sourceType": "localhost",
+  "previewState": "live",
+  "url": "http://localhost:5173/checkout?step=done",
+  "previewUrl": "http://localhost:5173/checkout?step=done",
+  "path": "/checkout?step=done"
+}
+```
+
+Do not replace localhost screens with copied `srcdoc` HTML unless the user
+explicitly asks to freeze a snapshot.
+
+## Verification
+
+- `list-localhost-connections` returns the expected connection and routes.
+- The Design editor opens in overview mode.
+- Every requested screen renders the intended localhost URL.
+- Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.
+- A query/path edit changes only the target screen's URL metadata and iframe.

package/corpus/templates/design/AGENTS.md

@@ -50,6 +50,19 @@ patterns live in `.agents/skills/`.
   is backed by a CSS custom property the rendered file actually uses. If source
   edits are needed, use `get-design-snapshot` first and persist the complete
   updated tweak definition list through `generate-design`.
+- Design editor extensions render in the right inspector slot
+  `design.editor.inspector`. When creating an extension for that panel, call
+  `create-extension`, then `add-extension-slot-target` with that slot id, then
+  `install-extension` so it appears inline. Extensions receive
+  `window.slotContext` with the current design id, active screen, selected
+  element, zoom, mode, tool, and tweak values. For AI-driven style/artboard
+  changes, extension HTML should call `agentNative.chat.send(...)` with the
+  selected element selector/sourceId and request; the agent should call
+  `view-screen` first, prefer `apply-visual-edit` for element style/class/text
+  changes, and use `update-design` or `generate-design` with `canvasFrames` for
+  overview artboard placement changes. If creating the extension opens the
+  standalone extension editor, return to the same design with `navigate` and
+  `inspectorTab: "extensions"` after installing it.
 - Follow linked design-system tokens and `customInstructions` whenever present;
   explicit user instructions in the current turn still win.
 - Persist useful work early: create/update the design and files as soon as a
@@ -57,31 +70,108 @@ patterns live in `.agents/skills/`.
 - For non-trivial new design prompts, ask before generating: create/open the
   design shell, call `show-design-questions`, stop while the main canvas shows
   the questions, then continue from the user's answers.
+- For multiple screens/states, call `generate-screens` first. It opens the
+  infinite screen overview and returns target filenames plus `canvasFrame`
+  placements. Then call `generate-design` with those files and pass the matching
+  `canvasFrames` entries so screens appear in the overview instead of only in
+  the file list.
+- After generation or broad updates, leave the user in the screen overview when
+  the work involves multiple screens or artboard placement. Overview is the
+  primary editing surface: users can select screens, move/resize/drop static
+  frames and canvas primitives, edit layers in place, and use the frame's
+  full-view button to enter focused editing.
+- To move the user's editor, call `navigate` with `view: "editor"` and
+  `editorView: "overview"` for the screen overview, or `editorView: "single"`
+  plus `fileId`, `filename`, or `screen` to focus one screen.
+- Single-screen mode is for scrolling, interacting with prototype behavior, and
+  editing the DOM/code layers inside one screen. Do not use it as the default
+  landing mode for multi-screen generation unless the user asks to focus a
+  specific screen.
+- The layers panel shows screens as top-level frames and nests DOM/code layers
+  beneath the active screen. Rename DOM/code layers by safely editing source to
+  set `data-agent-native-layer-name`; this is the stable human-readable layer
+  name. `data-code-layer-id` and similar ids are for selection stability, not
+  display naming.
+- For inline/Alpine screens, stamp and preserve unique
+  `data-agent-native-node-id` attributes on selectable DOM nodes. Treat
+  generated CSS selectors as a compatibility fallback only. For localhost React
+  screens, resolve through build-time source/debug metadata (stable generated
+  ids, component name, file, and line) before falling back to selectors.
 - For multi-variant work, write candidates incrementally so the UI can preview
   progress. External MCP hosts should use `present-design-variants` so the same
   picker opens inline instead of writing `application_state` directly.
 - Use framework sharing actions for design and design-system visibility/grants.
 - When the user asks to download/export, use export actions or point to the
   editor download menu.
+- Design source modes are `inline`, `localhost`, and `fusion`. Inline is the
+  current SQL-backed prototype mode. Localhost connections come from
+  `npx @agent-native/core@latest design connect` and are persisted with
+  `connect-localhost`; list them with `list-localhost-connections` before
+  creating or resolving local-code artboards. Fusion is a future source type and
+  should be preserved when present but not invented for inline/local work.
+- Localhost route manifests are scaffolding for URL-backed Flow Canvas
+  artboards. Use `add-localhost-screens` to place routes or path/query states as
+  iframe screens in overview mode. Preserve route ids, paths, `sourceType`,
+  bridge URL, and snapshot/state references when moving between actions so later
+  flow-edge derivation has stable anchors.
 
 ## Application State
 
 - `navigation` tells you the current view, design id, file id, and related UI
   state.
 - `navigate` moves the UI and is auto-deleted after the client consumes it.
+- `design-selection` includes active screen, selected element, overview mode,
+  inspector tab, zoom, and screen list for the current tab.
+- `design-generation-session:<designId>` contains visible multi-screen
+  generation frames created by `generate-screens`.
 - `show-design-questions` opens focused pre-generation questions in the main
   design canvas (`show-questions` application state).
 - `design-variants` contains in-progress candidates for the variant picker.
 
+## Code Layers
+
+- `get-code-layer-projection` reads inline HTML/JSX and returns selectable layer
+  nodes, selectors, names, and edit intents for agent and UI workflows.
+- `apply-visual-edit` supports deterministic local edits for HTML-backed code
+  layers: text, classes, styles, attributes, source order, and small structural
+  changes. Use it for selected-element edits before falling back to full
+  `update-design` / `generate-design` rewrites.
+- Prefer `data-agent-native-layer-name="Readable name"` on meaningful elements.
+  The projection uses it before semantic/text fallbacks, and layer renames should
+  persist by updating that attribute.
+- Current limitation: visual code-layer edits are HTML-only. Localhost source
+  mode can list and resolve local routes now, but file reads/writes remain a
+  bridge contract until explicit permission controls are hardened.
+
+## Localhost Source Actions
+
+- `connect-localhost`: registers or refreshes a localhost source connection
+  emitted by `npx @agent-native/core@latest design connect`. Pass
+  `devServerUrl`, optional `bridgeUrl`, optional `rootPath`, and either `routes`
+  or a full `routeManifest`.
+- `list-localhost-connections`: lists the current user's saved localhost
+  connections and route manifests. Use this before referring to local-code
+  artboards.
+- `add-localhost-screens`: creates or refreshes URL-backed iframe screens from
+  the latest localhost connection or a specific `connectionId`. Pass `routes`
+  with `path`/`url` when visualizing a flow; pass `paths` for a concise route
+  list. Then call `navigate --view editor --designId <id> --editorView overview`.
+
 ## App-Backed Skill Distribution
 
 - The preferred hosted install path is
-  `npx @agent-native/core@latest skills add design-exploration` (or `design`).
-  It installs the exported Design exploration instructions and registers the
-  hosted Design MCP connector together.
+  `npx @agent-native/core@latest skills add design-exploration`,
+  `npx @agent-native/core@latest skills add visual-edit`, or `design` for the
+  full Design bundle. It installs the exported Design instructions and registers
+  the hosted Design MCP connector together.
 - The open Skills CLI path
-  `npx skills@latest add BuilderIO/agent-native --skill design-exploration` installs
-  the exported instructions only.
+  `npx skills@latest add BuilderIO/agent-native --skill visual-edit` installs
+  exported instructions only.
+- For local-code visual editing, `/visual-edit` should run the target app dev
+  server, run
+  `npx @agent-native/core@latest design connect --url http://localhost:<port> --root .`,
+  register that manifest with `connect-localhost`, call `add-localhost-screens`,
+  and open the editor in overview mode.
 - For human-in-the-loop UI exploration, create a design shell, call
   `present-design-variants` with 2-5 complete HTML directions (three by
   default), wait for the user to pick one, then use `get-design-snapshot` and

package/corpus/templates/design/DESIGN.md

@@ -0,0 +1,82 @@
+# Design System Contract
+
+This file is the source-control scaffold for Design projects that point at real
+code. The app can keep inline prototypes in SQL today, connect to localhost next,
+and later blend hosted/fusion sources without changing the artboard model.
+
+## Editor Contract
+
+Design is overview-first for multi-screen work. Generation and broad updates
+should land in the screen overview: an infinite canvas where each screen is a
+static frame that can be selected, moved, resized, dropped, or duplicated.
+Use the frame's full-view button when a screen needs focused scrolling or
+prototype interaction.
+
+Single-screen mode is the scroll/interact/edit surface for one rendered file. It
+is where prototype behavior runs, iframe scrolling happens, and local DOM/code
+layer edits are applied.
+
+The layers panel mirrors that model: screens are top-level frames, with nested
+DOM/code layers for the active screen. Stable human-readable layer names should
+be stored in `data-agent-native-layer-name`; selector ids such as
+`data-code-layer-id` remain implementation anchors.
+
+## Source Modes
+
+- `inline`: the current SQL-backed Design files and deterministic HTML swaps.
+- `localhost`: a running app dev server exposed through
+  `npx @agent-native/core@latest design connect`.
+- `fusion`: future hosted or hybrid sources that can provide snapshots and code
+  context through the same bridge contract.
+
+Every artboard should carry `sourceType`, a source descriptor, stable route/path
+identity, and a snapshot reference when available. Flow edges should be durable
+objects even when they are derived later from captured state.
+
+## Localhost Bridge
+
+Run this from the app/repo root while the app dev server is running:
+
+```bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
+```
+
+The command starts a local bridge and prints a manifest URL. It also creates
+`.agent-native/design-routes.json` only when that file does not already exist.
+That manifest is non-authoritative scaffolding; the live bridge response and the
+Design `connect-localhost` action are the durable app contract.
+
+For agent-launched visual editing, install or invoke `/visual-edit`. The skill
+registers the bridge with `connect-localhost`, uses `add-localhost-screens` to
+place each route or path/query state as a URL-backed iframe screen, then
+navigates the editor to overview mode. Keep these screens as URL sources; do not
+copy localhost HTML into inline files unless intentionally freezing a snapshot.
+
+Current bridge operations:
+
+- `select`
+- `resolveNodeToFile`
+- `readFile`
+- `applyEdit`
+- `writeFile`
+- `captureSnapshot`
+- `captureState`
+
+`select`, route listing, and capture contracts are foundations now. Local file
+reads/writes and LLM-backed instructions remain planned until the bridge has
+permission hardening and explicit user controls.
+
+## Code-Layer Editing
+
+Inline HTML supports local code-layer projection and deterministic visual edits:
+text, classes, styles, attributes, source order, and small structural changes.
+`data-agent-native-layer-name` is the preferred naming surface because renames
+can persist as safe source edits without changing selection ids.
+Use durable `data-agent-native-node-id` values for Alpine/inline HTML whenever a
+layer may be selected, reordered, duplicated, or patched; CSS selectors are only
+a fallback. React/localhost targets should prefer build-time source metadata
+(component/file/line and generated stable ids) over DOM path selectors.
+
+Current limitation: visual code-layer edits only support HTML files. Localhost
+artboards can be registered and resolved today, but local file reads/writes stay
+behind the bridge permission model until explicit user controls are in place.

package/corpus/templates/design/DEVELOPING.md

@@ -15,6 +15,12 @@ This guide is for development-mode agents editing this app's source code. For ap
 - **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
 - **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
 - **Start:** `node .output/server/index.mjs` (production)
+- **Design local bridge:** `npx @agent-native/core@latest design connect --url http://localhost:5173 --root .`
+  exposes a local manifest for Design's localhost source mode and scaffolds
+  `.agent-native/design-routes.json` without overwriting an existing file.
+- **Visual edit local apps:** `/visual-edit` registers that bridge with
+  `connect-localhost`, adds URL-backed iframe screens with
+  `add-localhost-screens`, and opens the editor in overview mode.
 
 ## Directory Structure
 
@@ -92,6 +98,43 @@ export default function MyPageRoute() {
 
 Normal app data starts as an action, not a custom route. Add `actions/<verb>-<resource>.ts` with `defineAction`, mark reads with `http: { method: "GET" }`, and call reads/writes from React with `useActionQuery` / `useActionMutation` from `@agent-native/core/client`. This keeps the UI and agent on one contract and lets mutating actions refresh action-backed queries automatically.
 
+## Design Source Modes
+
+The shared source model lives in `shared/source-mode.ts`. Use `inline` for
+SQL-backed prototype files, `localhost` for local dev-server artboards, and
+`fusion` only for future hybrid/hosted sources. Bridge operations are named
+`select`, `resolveNodeToFile`, `readFile`, `applyEdit`, `writeFile`,
+`captureSnapshot`, and `captureState`; current localhost writes are contract-only
+until the bridge adds explicit permission hardening.
+
+## Editor Model
+
+Design has two editor views:
+
+- **Overview** is the default multi-screen canvas after generation or broad
+  updates. It renders every screen as a static, movable frame on an infinite
+  surface. Users can select screens, move/resize/drop frames and primitives,
+  edit layers in place, and use a frame's full-view button to focus it.
+- **Single screen** renders one file in the iframe editor. Use it for scrolling,
+  interacting with prototype behavior, text/DOM selection, and local visual
+  edits inside that screen.
+
+The layers panel treats screens/files as top-level frames and nests projected
+DOM/code layers under the active screen. Layer display names come from
+`data-agent-native-layer-name` first, then semantic/text fallbacks. Persist user
+renames by editing that attribute in the source; ids such as
+`data-code-layer-id` are for stable selection targets.
+Inline/Alpine HTML should also carry durable `data-agent-native-node-id`
+attributes for any layer the editor can select, reorder, duplicate, or patch.
+Selectors are fallback aliases, not the primary identity. Localhost React mode
+should resolve through build-time source/debug metadata (generated stable id,
+component, file, and line) before using selector fallbacks.
+
+Inline source mode supports local code-layer projection and deterministic HTML
+edits through `get-code-layer-projection` and `apply-visual-edit`. Current
+limitations: visual code-layer edits are HTML-only, and localhost reads/writes
+are still bridge-contract scaffolding until permission controls are hardened.
+
 ## Adding a Route-Only Endpoint
 
 Use `server/routes/api/` only for protocols that cannot be modeled as JSON actions: multipart uploads, streaming/SSE/WebSocket, webhooks, OAuth callbacks/redirects, public SEO/OG endpoints, or binary/static asset serving. Do not add `/api/*` routes for normal CRUD, data queries, or pass-through wrappers around actions; the action endpoint already exists at `/_agent-native/actions/:name`.