@agent-native/core 0.85.7 → 0.86.0

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

@@ -1,8 +1,12 @@
 import {
   createSharedEditorExtensions,
   useCollabReconcile,
+  usePresence,
+  useRecentEdits,
+  RecentEditHighlights,
   RegistryBlockDataProvider,
   useT,
+  type AttributedRecentEdit,
   type RegistryBlockSideMapBlock,
   type UseCollabReconcileResult,
 } from "@agent-native/core/client";
@@ -745,7 +749,7 @@ interface VisualEditorProps {
   /** Shared awareness instance for collaborative cursors/presence. */
   awareness?: Awareness | null;
   /** Current user info for cursor labels. */
-  user?: { name: string; color: string; email?: string };
+  user?: { name: string; color: string; email?: string; avatarUrl?: string };
   editable?: boolean;
   /** Local-file docs should not persist mount-time/schema normalization echoes. */
   localFileMode?: boolean;
@@ -894,7 +898,12 @@ interface VisualEditorExtensionOptions {
   documentId?: string;
   ydoc?: YDoc | null;
   localAwareness?: Awareness | null;
-  user?: { name: string; color: string; email?: string } | null;
+  user?: {
+    name: string;
+    color: string;
+    email?: string;
+    avatarUrl?: string;
+  } | null;
   onImageComment?: (quotedText: string, offsetTop: number) => void;
   onJoinTitle?: (text: string) => void;
   resolveNotionPageLink?: (notionPageId: string) => NotionPageLink | null;
@@ -1599,6 +1608,7 @@ export function VisualEditor({
 }: VisualEditorProps) {
   const t = useT();
   const [isDraggingMedia, setIsDraggingMedia] = useState(false);
+  const wrapperRef = useRef<HTMLDivElement>(null);
   const onChangeRef = useRef(onChange);
   onChangeRef.current = onChange;
   const onSaveContentRef = useRef(onSaveContent);
@@ -1885,7 +1895,15 @@ export function VisualEditor({
     contentUpdatedAt,
     editable,
     getMarkdown: (e) => docToNfm(e.getJSON() as any),
+    // Read-only viewers join the shared Y.Doc purely to RECEIVE live edits and
+    // cursors; their editor content comes from the server state fetch + peer Yjs
+    // updates, never from SQL reconcile. Any local Y.Doc write from a viewer
+    // would be POSTed to the editor-only `/update` route (→ 403) and could
+    // publish an author-less snapshot, so both write paths are neutered when
+    // `!editable`: this `setContent` (used by both the seed and the reconcile
+    // apply) no-ops, and `shouldSeed` returns false so the seed never runs.
     setContent: (e, value, options) => {
+      if (!editable) return;
       const doc = nfmToDoc(value);
       if (options.addToHistory === false) {
         e.chain()
@@ -1903,6 +1921,7 @@ export function VisualEditor({
     },
     normalizeValue: canonicalizeNfm,
     shouldSeed: ({ value, currentMarkdown, fragmentLength }) =>
+      editable &&
       shouldSeedCollaborativeContent({
         content: value,
         currentMarkdown,
@@ -1912,6 +1931,76 @@ export function VisualEditor({
   });
   guardsRef.current = collabState;
 
+  // ─── Recent-edit highlights (Google-Docs / Figma "just edited this") ─────────
+  //
+  // Other participants — including the AI agent — publish a short ring of recent
+  // edits into their awareness state. `usePresence` surfaces the remote entries,
+  // `useRecentEdits` filters to the non-expired ones, and `RecentEditHighlights`
+  // paints a lingering, fading glow with the editor's name/color flag. For the
+  // agent, `edit-document` / `update-document` publish a `{ kind: "text", quote }`
+  // descriptor, which we resolve to a viewport rect by locating the quote in the
+  // live ProseMirror doc and measuring the span with `coordsAtPos`.
+  const localClientId = ydoc?.clientID ?? null;
+  const { others } = usePresence(localAwareness, localClientId);
+  const recentEdits = useRecentEdits(others);
+
+  const resolveRecentEditRect = useCallback(
+    (edit: AttributedRecentEdit): DOMRect | null => {
+      if (!editor || editor.isDestroyed) return null;
+      if (edit.descriptor.kind !== "text") return null;
+      const quote =
+        typeof edit.descriptor.quote === "string"
+          ? edit.descriptor.quote.trim()
+          : "";
+      if (!quote) return null;
+
+      // Clamp very long quotes — matching a long exact string across the doc is
+      // brittle (whitespace/markdown differences); the leading slice is enough to
+      // anchor the highlight to the right region.
+      const needle = quote.slice(0, 60);
+
+      // Walk the doc's text, tracking absolute positions, to find the needle.
+      const doc = editor.state.doc;
+      let found: { from: number; to: number } | null = null;
+      let acc = "";
+      let accStart = -1;
+      doc.descendants((node, pos) => {
+        if (found) return false;
+        if (!node.isText || typeof node.text !== "string") return true;
+        if (accStart === -1) accStart = pos;
+        acc += node.text;
+        const idx = acc.indexOf(needle);
+        if (idx !== -1) {
+          const from = accStart + idx;
+          found = { from, to: from + needle.length };
+          return false;
+        }
+        // Keep only a tail long enough to catch a needle spanning two text nodes.
+        if (acc.length > needle.length * 2) {
+          const drop = acc.length - needle.length;
+          acc = acc.slice(drop);
+          accStart += drop;
+        }
+        return true;
+      });
+      if (!found) return null;
+
+      try {
+        const { from, to } = found;
+        const start = editor.view.coordsAtPos(from);
+        const end = editor.view.coordsAtPos(Math.max(from, to - 1), 1);
+        const left = Math.min(start.left, end.left);
+        const right = Math.max(start.right, end.right);
+        const top = Math.min(start.top, end.top);
+        const bottom = Math.max(start.bottom, end.bottom);
+        return new DOMRect(left, top, Math.max(1, right - left), bottom - top);
+      } catch {
+        return null;
+      }
+    },
+    [editor],
+  );
+
   // Side-map that feeds the shared registry-block NodeView its typed `data`,
   // lazily parsed from each node's verbatim `__raw` NFM. Edits write the
   // re-serialized MDX back onto the node so the existing NFM save path persists
@@ -2086,8 +2175,14 @@ export function VisualEditor({
 
   return (
     <div
+      ref={wrapperRef}
       className={`visual-editor-wrapper${isDraggingMedia ? " visual-editor-wrapper--dragging" : ""}`}
     >
+      <RecentEditHighlights
+        edits={recentEdits}
+        resolveRect={resolveRecentEditRect}
+        containerRef={wrapperRef}
+      />
       {editable ? (
         <BubbleToolbar editor={editor} onComment={onComment} />
       ) : null}

package/corpus/templates/content/changelog/2026-07-03-agent-document-edits-now-appear-as-a-live-collaborator-prese.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-03
+---
+
+Agent document edits now appear as a live collaborator — presence avatar, editing indicator, and a brief highlight on the changed text

package/corpus/templates/content/changelog/2026-07-03-document-search-and-list-views-load-faster-on-large-workspac.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-03
+---
+
+Document search and list views load faster on large workspaces

package/corpus/templates/content/package.json

@@ -75,8 +75,8 @@
     "@radix-ui/react-toast": "^1.2.14",
     "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-tooltip": "^1.2.7",
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@swc/core": "^1.13.3",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "catalog:",
@@ -93,7 +93,7 @@
     "oxfmt": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
-    "react-router": "^8.0.1",
+    "react-router": "^8.1.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "catalog:",

package/corpus/templates/content/server/plugins/db.ts

@@ -1,6 +1,29 @@
-import { runMigrations } from "@agent-native/core/db";
+import {
+  ensureAdditiveColumns,
+  getDbExec,
+  runMigrations,
+} from "@agent-native/core/db";
 
 import { repairUnseededBlocksFields } from "../../actions/_property-utils.js";
+import * as schema from "../db/schema.js";
+
+/**
+ * Every Drizzle table exported from schema.ts. Filters out type-only and
+ * helper exports the same way db.spec.ts's `isDrizzleTable` regression guard
+ * does: a real table carries a Symbol-keyed drizzle metadata bag, plain
+ * exports don't.
+ */
+function isDrizzleTable(value: unknown): value is object {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    Object.getOwnPropertySymbols(value).some((s) =>
+      s.toString().includes("drizzle"),
+    )
+  );
+}
+
+const schemaTables = Object.values(schema).filter(isDrizzleTable);
 
 function scheduleBlocksRepairRetry(attempt = 1): void {
   const delayMs = Math.min(30_000 * attempt, 5 * 60_000);
@@ -14,6 +37,11 @@ function scheduleBlocksRepairRetry(attempt = 1): void {
   }
 }
 
+// Convention: every new migration below MUST set a unique `name:` slug (see
+// packages/core/src/db/migrations.ts for the full rationale). Version numbers
+// alone are not a safe identity across parallel branches that each extend
+// this list independently — see the analytics db.ts v75-v83 incident this
+// convention was introduced to prevent.
 const runContentMigrations = runMigrations(
   [
     {
@@ -598,11 +626,39 @@ const runContentSourceMigrations = runMigrations(
   { table: "content_source_migrations" },
 );
 
+/**
+ * The migration lists above are the authoritative source for tables, indexes,
+ * and data transforms. `ensureAdditiveColumns` runs after they complete as a
+ * belt-and-braces safety net for the failure mode where a column is added to
+ * schema.ts without a matching hand-written ALTER migration, which silently
+ * 500s every query touching a pre-existing production table. It only ever
+ * adds missing columns — never drops, renames, or retypes anything — and any
+ * failure here is logged and swallowed so it can never fail boot.
+ */
 export default async function contentDatabasePlugin(
   nitroApp: Parameters<typeof runContentMigrations>[0],
 ) {
   await runContentMigrations(nitroApp);
   await runContentSourceMigrations(nitroApp);
+  try {
+    const summary = await ensureAdditiveColumns({
+      db: getDbExec(),
+      tables: schemaTables,
+    });
+    if (summary.errors.length > 0) {
+      console.warn(
+        "[db] ensureAdditiveColumns completed with errors:",
+        summary.errors,
+      );
+    }
+  } catch (err) {
+    // Never fail boot over the safety net itself — the authoritative
+    // migrations above already ran.
+    console.warn(
+      "[db] ensureAdditiveColumns failed (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
   // One-time, boot-time repair: seed the primary "Content" Blocks field for any
   // legacy database that has never been seeded (blocks_seeded = 0). Idempotent —
   // the atomic claim in seedDefaultBlocksField makes re-runs no-ops, and it

package/corpus/templates/design/.agents/skills/full-app-build/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: full-app-build
+description: >-
+  Build and iterate on a full real app from Design, backed by a running
+  Builder Fusion cloud container instead of an inline HTML prototype. Use
+  when the user wants a real/full app end-to-end through publishing, and
+  only when FULL_APP_BUILDING_ENABLED is true.
+metadata:
+  visibility: exported
+---
+
+# Full App Building
+
+Full app building turns a Design project into a real, running app instead of
+an inline Alpine/HTML prototype. The source of truth is a live dev server
+inside a Builder Fusion cloud container — one Builder project branch per
+design. Screens are URL-backed iframes of that container's dev server, the
+same model as `/visual-edit` localhost screens (`sourceType: "fusion"`), but
+the container runs remotely instead of on the user's machine.
+
+## Flag Gate
+
+This feature is gated by the code boolean `FULL_APP_BUILDING_ENABLED` in
+`templates/design/shared/full-app.ts`, currently `false`. Check it (or trust
+that the fusion actions are unavailable/erroring) before proposing this flow.
+If the flag is off, tell the user full app building isn't enabled yet instead
+of attempting the actions.
+
+Even when the flag is on, the fusion actions require Builder credentials and
+a configured branch project ID. When those aren't set up, actions return a
+`not-configured` CTA instead of throwing — see **Not Configured** below.
+
+## When To Use
+
+Reach for full app building only when the user wants a real, working app —
+not a prototype — and wants to go end-to-end through publishing: real
+routing, real backend behavior, a deployable URL. For UI exploration, visual
+review, and iteration on look/feel, stay in the normal inline design flow
+(`design-generation`) or `/visual-edit` for connecting an existing local app.
+Do not switch a normal design into fusion mode unless the user explicitly
+asks for a full/real app.
+
+## Lifecycle
+
+1. **Create the design shell** the normal way (`create-design`), or continue
+   from an existing design.
+2. **`create-fusion-app`** `{designId, prompt, branchName?}` creates the app
+   branch via the Builder cloud agent. Returns
+   `{status: "building", projectId, branchName, editorUrl}` once started, or
+   the not-configured CTA. One branch per design — calling it again on an
+   already-linked design returns the existing linkage instead of creating a
+   second branch.
+3. **Poll `sync-fusion-app`** `{designId, paths?}` while the container boots.
+   It attaches to the container and reports `status: building|ready|error`.
+   Tell the user the app is building and keep polling — don't block on a
+   single call. Once `ready`, it updates `previewUrl` and upserts URL-backed
+   screens (default path `"/"` when `paths` is omitted).
+4. **Screens appear as URL-backed artboards** in the overview canvas, same
+   as localhost screens: iframe of `previewUrl` + route, not copied HTML.
+5. **Iterate** using the editing rules below, then push and publish when
+   ready.
+
+## Editing Rules — the critical distinction
+
+Fusion screens are NOT inline HTML files. **Never** edit a fusion screen's
+markup directly and never use `generate-design`, `edit-design`, or
+`apply-visual-edit` on it — those tools rewrite inline `design_files` rows,
+which fusion screens don't have. Writing to the wrong layer silently does
+nothing to the running app.
+
+Instead:
+
+- **`queue-fusion-edit`** `{designId, instruction, screenFileId?, target?}` —
+  queue one edit intent. Use `target` (`selector`, `path`, `url`, `nodeName`)
+  to point at the specific element/screen the user means, the same way you'd
+  describe a selection for `apply-visual-edit`. Queuing does not touch the
+  running app yet — it only records intent in `design_fusion_edits`.
+- **`list-fusion-edits`** `{designId, status?}` — inspect the queue before
+  dispatching, e.g. to confirm what's pending or to show the user a summary.
+- **`apply-fusion-edits`** `{designId, editIds?}` — batches all pending edits
+  (or the given `editIds`) into one prompt and dispatches it to the app's
+  in-container coding agent. This is fire-and-forget: it marks the edits
+  "sent" and returns immediately, it does not wait for the app agent to
+  finish.
+- **`send-fusion-message`** `{designId, prompt}` — for larger freeform
+  requests that don't fit the "queue small edits, batch them" model (new
+  features, structural changes, "wire up the backend for X"), relay a
+  message straight to the app's coding agent instead of queuing edits.
+
+After dispatching (`apply-fusion-edits` or `send-fusion-message`), tell the
+user the change was sent to the app's agent and is being applied
+asynchronously — it is not applied synchronously like an inline `edit-design`
+call. Screens reflect the change once the in-container agent finishes and the
+dev server updates; call `sync-fusion-app` again or have the user reload the
+screen to see it land.
+
+## Adding More Routes As Screens
+
+Once `previewUrl` is known (after `sync-fusion-app` reports `ready`), use
+**`add-fusion-screens`** `{designId, paths, width?, height?}` to place
+additional routes as screens on the overview canvas — the fusion equivalent
+of `add-localhost-screens`.
+
+## Push And Publish Flow
+
+1. **`push-fusion-app`** `{designId}` — pushes the branch's code to its git
+   remote. Do this before or as part of publishing so the code is durably
+   saved, not just running in the container.
+2. **`deploy-fusion-app`** `{designId, slug?}` — reserves
+   `<slug>.builder.cloud` (derived from the design title when `slug` is
+   omitted) and triggers a deploy.
+3. **`get-fusion-deploy-status`** `{designId}` — poll until the deploy status
+   is `live`, `failed`, or `canceled`. Report the live `deployedUrl` once it
+   resolves; report the failure reason if it doesn't.
+
+## Not Configured
+
+When Builder credentials or the branch project ID aren't set up, the fusion
+actions return a `not-configured` status with a `cta` object instead of
+throwing — mirror the guidance `migrate-inline-design-to-app` already gives:
+surface the CTA's `label`/`description` and point the user at
+`connect-builder-app` or the given `connectUrl` to connect Builder, then
+retry the same fusion action. Don't silently fall back to an inline design in
+this case — tell the user full app building needs Builder connected first.
+
+## Timing Expectations
+
+Set expectations up front so polling doesn't read as broken:
+
+- Creating the app branch and booting the container can take a few minutes —
+  this is a real cloud container starting a real dev server, not an inline
+  HTML render. Keep polling `sync-fusion-app` and give the user a short
+  status update rather than going silent.
+- Edits are asynchronous. `apply-fusion-edits` and `send-fusion-message`
+  return as soon as the prompt is dispatched, not when the app agent finishes
+  making the change. Don't promise the screen updated instantly — remind the
+  user the app's agent is working on it and the screen will reflect the
+  change once it's done and the dev server picks it up.
+- Deploys also take real time; poll `get-fusion-deploy-status` rather than
+  assuming `deploy-fusion-app` finished the deploy synchronously.

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

@@ -163,6 +163,25 @@ content as the absolute URL and keep `screenMetadata[fileId]` aligned:
 Do not replace localhost screens with copied `srcdoc` HTML unless the user
 explicitly asks to freeze a snapshot.
 
+## Local Files in the Code Tab
+
+Once a connection is registered, the design editor's Code panel (left rail →
+Code, or `navigate --view editor --designId <id> --leftPanel code`) shows a
+local-files workspace root for that connection next to the design's own files.
+It lists the connected app's text/code files through the bridge
+(`list-local-files` / `read-local-file`); build output, `node_modules`,
+`.git`, and secret-looking paths (`.env*`, key files) are always excluded.
+
+- Browsing and reading need only editor access on the design plus the running
+  bridge.
+- Saving goes through `write-local-file`: the first save opens the
+  write-consent dialog (an 8-hour, folder-scoped grant) and retries
+  automatically once granted. Only text/code files are writable; secret paths
+  are always blocked.
+- Saves are conflict-checked against the file's on-disk version — a file that
+  changed since it was read fails with a version conflict instead of being
+  overwritten.
+
 ## Verification
 
 - `list-localhost-connections` returns the expected connection and routes.
@@ -170,3 +189,4 @@ explicitly asks to freeze a snapshot.
 - 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.
+- The Code tab shows a local-files root for the connection and opens its files.

package/corpus/templates/design/AGENTS.md

@@ -156,8 +156,10 @@ patterns live in `.agents/skills/`.
   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.
+  creating or resolving local-code artboards. Fusion designs are full-app
+  designs backed by a running Builder Fusion container, created via
+  `create-fusion-app` when `FULL_APP_BUILDING_ENABLED` is on; preserve the
+  design's `fusionApp` linkage data whenever present and never invent it.
 - 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`,
@@ -198,21 +200,31 @@ patterns live in `.agents/skills/`.
 
 ## Code Workspace
 
-- The editor left rail has a wide `code` workspace panel. Open it with
-  `navigate --view editor --designId <id> --leftPanel code` and optionally pass
-  `fileId`, `filename`, or `screen` to focus a file.
-- Use `list-source-files` to inspect the source workspace. For the MVP the
-  backend is `virtual-inline` over SQL-backed `design_files`, exposed as
-  `designfs://<designId>/`.
-- Use `read-source-file` for file contents and preserve its `versionHash` before
+- The editor left rail has a wide `code` panel: a VS Code-style workbench
+  (`app/components/design/code-workbench/`) with an explorer, workspace search,
+  editor tabs, quick open (⌘P), a command palette (⇧⌘P), and a status bar. Open
+  it with `navigate --view editor --designId <id> --leftPanel code` and
+  optionally pass `fileId`, `filename`, or `screen` to focus a file.
+- The explorer shows one root per workspace source: the design's SQL-backed
+  files (`designfs://<designId>/`, backend `virtual-inline`) always, plus one
+  root per localhost connection referenced by the design's screens
+  (`list-local-files` / `read-local-file` proxy the `design connect` bridge;
+  writes go through `write-local-file` and its user-approved consent grant).
+- Inline design files are auto-formatted with Prettier the first time they are
+  opened in the workbench and the formatted result is persisted; local files
+  are never auto-formatted.
+- Use `list-source-files` to inspect the inline source workspace and
+  `read-source-file` for file contents; preserve its `versionHash` before
   writing. Do not return full file content from `view-screen`; it reports only
   active code file metadata and dirty state.
 - Use `preview-source-edit` to show a diff without saving, then
   `apply-source-edit` with the prior `versionHash` to save either a full replace
-  or exact replace. These actions update the same inline file state as the UI.
+  or exact replace. These actions update the same inline file state as the UI;
+  agent edits show up live in open workbench buffers.
 - Use `resolve-selection-source` when the user has a canvas element selected and
-  you need the best matching inline file location/snippet. Localhost/container
-  source reads and writes remain future backend work.
+  you need the best matching inline file location/snippet.
+- The workbench session (open tabs, active file, sidebar layout) persists per
+  design in application state under `code-workbench:<designId>`.
 
 ## Localhost Source Actions
 
@@ -255,6 +267,31 @@ patterns live in `.agents/skills/`.
   section — promote a 3+ times repeated pattern instead of inventing another
   near-duplicate.
 
+## Full App Building
+
+Flag-gated (`FULL_APP_BUILDING_ENABLED` in `shared/full-app.ts`, default off)
+and requires Builder connected. See `full-app-build` skill for the full flow.
+
+- `create-fusion-app`: creates the app branch via the Builder cloud agent; one
+  branch per design; returns existing linkage if already created.
+- `sync-fusion-app`: boots/attaches the container; poll while building; on
+  ready, updates `previewUrl` and upserts URL-backed screens.
+- `add-fusion-screens`: places more routes as screens once `previewUrl` is
+  known.
+- `queue-fusion-edit`: queues one edit intent against a fusion screen.
+- `list-fusion-edits`: inspects the queued edits.
+- `apply-fusion-edits`: batches pending edits into one prompt for the app's
+  in-container agent (fire-and-forget); marks them "sent".
+- `send-fusion-message`: relays a freeform request to the app's coding agent.
+- `push-fusion-app`: pushes the branch's code to its git remote.
+- `deploy-fusion-app`: reserves `<slug>.builder.cloud` and triggers a deploy.
+- `get-fusion-deploy-status`: polls deploy status until live/failed/canceled.
+- Fusion screens are URL-backed iframes, same model as localhost screens.
+  Never inline-edit a fusion screen's HTML or use `generate-design` /
+  `edit-design` / `apply-visual-edit` on it — queue and dispatch edits
+  instead. When not configured, actions return a connect CTA like
+  `migrate-inline-design-to-app`; never throw or invent `fusionApp` data.
+
 ## App-Backed Skill Distribution
 
 - The preferred hosted install path is
@@ -296,6 +333,7 @@ Read the relevant skill before deeper work:
 - `design-generation` for creating/editing prototype HTML and variant flows.
 - `design-systems` for tokens, brand extraction, and linked systems.
 - `export-handoff` for HTML/PNG/SVG/ZIP/code handoff.
+- `full-app-build` for flag-gated fusion-backed full app building.
 - `frontend-design` and `shadcn-ui` for app UI changes.
 - `actions`, `delegate-to-agent`, `security`, and `self-modifying-code` for
   framework patterns.

package/corpus/templates/design/actions/add-fusion-screens.ts

@@ -0,0 +1,91 @@
+/**
+ * add-fusion-screens — place additional URL-backed screens for an already
+ * synced fusion app.
+ *
+ * Use this to add more routes/screens to the canvas once the container is
+ * ready (i.e. after sync-fusion-app has resolved a previewUrl). If the app
+ * has not been synced yet, this throws with guidance to call sync-fusion-app.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { assertAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import { schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  DEFAULT_FUSION_SCREEN_HEIGHT,
+  DEFAULT_FUSION_SCREEN_WIDTH,
+  upsertFusionScreens,
+} from "../server/lib/fusion-screens.js";
+import {
+  FULL_APP_BUILDING_ENABLED,
+  readFusionApp,
+} from "../shared/full-app.js";
+
+export default defineAction({
+  description:
+    "Add or refresh URL-backed screens on a fusion (full-app) design's " +
+    "canvas, pointing at the container's live preview URL. Requires the " +
+    "fusion app to already have a previewUrl (call sync-fusion-app first if " +
+    "not). Use this to place additional routes the app agent has built " +
+    "(e.g. '/settings', '/dashboard') as new overview screens.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+    paths: z
+      .array(z.string())
+      .min(1)
+      .describe(
+        "Route paths to place as screens, e.g. ['/settings', '/dashboard'].",
+      ),
+    width: z
+      .number()
+      .positive()
+      .optional()
+      .describe("Iframe viewport width. Defaults to 1280."),
+    height: z
+      .number()
+      .positive()
+      .optional()
+      .describe("Iframe viewport height. Defaults to 900."),
+  }),
+  run: async ({ designId, paths, width, height }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const access = await assertAccess("design", designId, "editor");
+    const design = access.resource as typeof schema.designs.$inferSelect;
+    const fusionApp = readFusionApp(design.data);
+    if (!fusionApp) {
+      throw new Error(
+        "This design has no fusion app linkage. Call create-fusion-app first.",
+      );
+    }
+    if (!fusionApp.previewUrl) {
+      throw new Error(
+        "The fusion app has no preview URL yet. Call sync-fusion-app first " +
+          "to boot the container and resolve its preview URL.",
+      );
+    }
+
+    const { screens } = await upsertFusionScreens({
+      designId,
+      previewUrl: fusionApp.previewUrl,
+      paths,
+      width: width ?? DEFAULT_FUSION_SCREEN_WIDTH,
+      height: height ?? DEFAULT_FUSION_SCREEN_HEIGHT,
+    });
+
+    return {
+      screens: screens.map((screen) => ({
+        fileId: screen.fileId,
+        path: screen.path,
+        url: screen.url,
+        title: screen.title,
+        width: screen.width,
+        height: screen.height,
+      })),
+    };
+  },
+});

package/corpus/templates/design/actions/apply-a11y-fix.ts

@@ -35,6 +35,7 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import { applyVisualEdit, type EditIntent } from "../shared/code-layer.js";
+import { agentSelectionDescriptor } from "../shared/collab-selection.js";
 import {
   A11Y_FINDING_CATEGORIES,
   A11Y_FINDING_SEVERITIES,
@@ -282,7 +283,10 @@ export default defineAction({
 
     if (patch.result.target) {
       agentUpdateSelection(file.id, {
-        selection: patch.result.target.selector,
+        selection: agentSelectionDescriptor(
+          patch.result.target,
+          "Fixing accessibility",
+        ),
         nodeId: patch.result.target.nodeId,
         editingFile: file.filename,
         designId: file.designId,