@agent-native/core 0.85.7 → 0.86.1

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

@@ -92,13 +92,19 @@ patterns live in `.agents/skills/`.
   `inspectorTab: "extensions"` after installing it.
 - Follow linked design-system tokens and `customInstructions` whenever present;
   explicit user instructions in the current turn still win.
-- When a user wants tokens from design.md, CSS, theme/tokens JSON, Tailwind
-  config, local files, or the current design, call `import-design-tokens` and
-  preserve its `tokens`, `filesAnalyzed`, and provenance in your answer. Manual
-  `apply-design-token-edit` / one-by-one token entry is the fallback for a small
-  one-off token, not the primary import workflow. For Figma variables/styles or
-  raw `.fig` files, keep using Builder-backed design-system indexing instead of
-  local `.fig` parsing.
+- For reusable design-system setup from Figma, connected code/GitHub, local
+  code/design files, or optional `design.md`, use Builder-backed DSI indexing
+  through `index-design-system-with-builder` or `import-file --format fig`.
+  Pass readable `design.md` content as `designMd`, use the returned local design
+  system id in Design flows, and call `get-design-system` before generation to
+  hydrate Builder docs/tokens when available. Do not create a duplicate local
+  design system from raw Figma/code sources.
+- When a user wants one-off tokens from design.md, CSS, theme/tokens JSON,
+  Tailwind config, local files, or the current design, call
+  `import-design-tokens` and preserve its `tokens`, `filesAnalyzed`, and
+  provenance in your answer. Manual `apply-design-token-edit` / one-by-one
+  token entry is the fallback for a small one-off token, not the primary import
+  workflow.
 - Persist useful work early: create/update the design and files as soon as a
   coherent candidate exists, then iterate.
 - For non-trivial new design prompts, ask before generating: create/open the
@@ -156,8 +162,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 +206,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 +273,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 +339,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,

package/corpus/templates/design/actions/apply-component-prop-edit.ts

@@ -45,7 +45,12 @@ import {
   applyVisualEdit,
   buildCodeLayerProjection,
 } from "../shared/code-layer.js";
-import type { CodeLayerSource, ClassEditIntent } from "../shared/code-layer.js";
+import type {
+  CodeLayerSource,
+  ClassEditIntent,
+  StyleEditIntent,
+} from "../shared/code-layer.js";
+import { agentSelectionDescriptor } from "../shared/collab-selection.js";
 import {
   componentNameFor,
   componentNodeIdMatches,
@@ -387,7 +392,10 @@ export default defineAction({
       });
 
       agentUpdateSelection(file.id, {
-        selection: node.selector,
+        selection: agentSelectionDescriptor(
+          { nodeId, selector: node.selector },
+          "Editing component",
+        ),
         nodeId,
         editingFile: file.filename,
         designId: file.designId,

package/corpus/templates/design/actions/apply-fusion-edits.ts

@@ -0,0 +1,161 @@
+/**
+ * apply-fusion-edits — batch pending queued edits into one prompt and send it
+ * to the fusion app's in-container coding agent.
+ *
+ * Composes a single message from all pending edits (or a caller-specified
+ * subset, still pending) so the app agent gets full context in one turn
+ * instead of being spammed with one message per edit. Marks rows `sent` (with
+ * a shared `batchId`) on success, or `error` (with the failure message) on
+ * failure — so `list-fusion-edits` reflects the outcome without another call.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { sendFusionBranchMessage } from "@agent-native/core/server";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq, inArray } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  FULL_APP_BUILDING_ENABLED,
+  readFusionApp,
+} from "../shared/full-app.js";
+
+function parseTarget(raw: string | null): Record<string, unknown> | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function formatTargetContext(target: Record<string, unknown> | null): string {
+  if (!target) return "";
+  const parts: string[] = [];
+  if (typeof target.path === "string" && target.path) {
+    parts.push(`path: ${target.path}`);
+  }
+  if (typeof target.selector === "string" && target.selector) {
+    parts.push(`selector: ${target.selector}`);
+  }
+  if (typeof target.nodeName === "string" && target.nodeName) {
+    parts.push(`element: ${target.nodeName}`);
+  }
+  if (typeof target.url === "string" && target.url) {
+    parts.push(`url: ${target.url}`);
+  }
+  return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+
+export default defineAction({
+  description:
+    "Send all (or the given) pending queued fusion edits to the app's " +
+    "in-container coding agent in a single batched prompt. Use after " +
+    "queue-fusion-edit has accumulated one or more edits the user wants " +
+    "applied now. Marks sent edits with a shared batchId, or marks them " +
+    "'error' if the send failed. Returns sentCount=0 with a message if there " +
+    "were no pending edits to send.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+    editIds: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Specific design_fusion_edits ids to apply (must still be pending). " +
+          "Omit to apply all pending edits for this design.",
+      ),
+  }),
+  run: async ({ designId, editIds }) => {
+    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.",
+      );
+    }
+
+    const db = getDb();
+    const conditions = [
+      eq(schema.designFusionEdits.designId, designId),
+      eq(schema.designFusionEdits.status, "pending"),
+    ];
+    if (editIds && editIds.length > 0) {
+      conditions.push(inArray(schema.designFusionEdits.id, editIds));
+    }
+
+    const pending = await db
+      .select()
+      .from(schema.designFusionEdits)
+      .where(and(...conditions))
+      .orderBy(schema.designFusionEdits.createdAt);
+
+    if (pending.length === 0) {
+      return {
+        sentCount: 0,
+        message: "No pending fusion edits to apply.",
+      };
+    }
+
+    const lines = pending.map((edit, index) => {
+      const target = formatTargetContext(parseTarget(edit.target));
+      return `${index + 1}. ${edit.instruction}${target}`;
+    });
+    const prompt = [
+      "Apply the following queued visual edits to the app; keep changes minimal and scoped:",
+      "",
+      ...lines,
+    ].join("\n");
+
+    const ownerEmail = getRequestUserEmail();
+    const result = await sendFusionBranchMessage({
+      projectId: fusionApp.projectId,
+      branchName: fusionApp.branchName,
+      prompt,
+      userEmail: ownerEmail ?? undefined,
+    });
+
+    const now = new Date().toISOString();
+    const ids = pending.map((edit) => edit.id);
+
+    if (!result.sent) {
+      await db
+        .update(schema.designFusionEdits)
+        .set({
+          status: "error",
+          error: result.error ?? "Send failed",
+          updatedAt: now,
+        })
+        .where(inArray(schema.designFusionEdits.id, ids));
+      return {
+        sentCount: 0,
+        error: result.error ?? "Failed to send edits to the app agent",
+      };
+    }
+
+    const batchId = nanoid();
+    await db
+      .update(schema.designFusionEdits)
+      .set({ status: "sent", batchId, sentAt: now, updatedAt: now })
+      .where(inArray(schema.designFusionEdits.id, ids));
+
+    return {
+      sentCount: pending.length,
+      batchId,
+      message:
+        `Sent ${pending.length} queued edit(s) to the app agent as batch ` +
+        `"${batchId}".`,
+    };
+  },
+});

package/corpus/templates/design/actions/apply-visual-edit.ts

@@ -22,9 +22,36 @@ import {
   type UnwrapEditIntent,
   type WrapNodesEditIntent,
 } from "../shared/code-layer.js";
+import { agentSelectionDescriptor } from "../shared/collab-selection.js";
 import type { TailwindBreakpointPrefix } from "../shared/design-state.js";
 import { utilityStem, widthToPrefix } from "../shared/responsive-classes.js";
 
+/**
+ * Short human-readable label describing an edit intent, shown next to the
+ * agent's selection ring for live viewers (e.g. "AI — Editing text").
+ */
+function editIntentLabel(intent: EditIntent): string {
+  switch (intent.kind) {
+    case "textContent":
+      return "Editing text";
+    case "style":
+      return "Editing style";
+    case "class":
+    case "responsive-class":
+      return "Editing styles";
+    case "moveNode":
+      return "Moving element";
+    case "wrapNodes":
+      return "Grouping elements";
+    case "unwrap":
+      return "Ungrouping elements";
+    case "autoLayout":
+      return "Editing layout";
+    default:
+      return "Editing element";
+  }
+}
+
 type VisualEditActionSource = CodeLayerSource & { html?: string };
 
 /** Tailwind responsive prefix values accepted by the action. */
@@ -490,8 +517,14 @@ export default defineAction({
     });
 
     if (patch.result.target) {
+      // Publish a RESOLVABLE selection descriptor so live viewers can render a
+      // ring over the element being edited. Prefer the stable
+      // `data-agent-native-node-id` anchor over the projection CSS selector.
       agentUpdateSelection(file.id, {
-        selection: patch.result.target.selector,
+        selection: agentSelectionDescriptor(
+          patch.result.target,
+          editIntentLabel(editIntent),
+        ),
         nodeId: patch.result.target.nodeId,
         editingFile: file.filename,
         designId: file.designId,

package/corpus/templates/design/actions/create-component.ts

@@ -50,6 +50,7 @@ import "../server/db/index.js"; // ensure registerShareableResource runs
 import { resolveSourceCapabilities } from "../shared/capability-resolver.js";
 import { buildCodeLayerProjection } from "../shared/code-layer.js";
 import type { CodeLayerNode, CodeLayerSource } from "../shared/code-layer.js";
+import { agentSelectionDescriptor } from "../shared/collab-selection.js";
 import {
   COMPONENT_NAME_ATTR,
   COMPONENT_PROP_PREFIX,
@@ -416,7 +417,10 @@ export default defineAction({
       });
 
       agentUpdateSelection(file.id, {
-        selection: node.selector,
+        selection: agentSelectionDescriptor(
+          { nodeId: node.id, selector: node.selector },
+          "Creating component",
+        ),
         nodeId: node.id,
         editingFile: file.filename,
         designId: file.designId,