@agent-native/core 0.85.6 → 0.86.0

package/corpus/templates/design/AGENTS.md

@@ -39,7 +39,12 @@ patterns live in `.agents/skills/`.
   supports our own primitives.
 - For raster image generation, restyling, or editing existing screenshots/photos,
   use the available first-party Assets MCP tool such as `generate-asset` instead
-  of placeholders or generic stock imagery. When the Assets picker returns a
+  of placeholders or generic stock imagery. Default to `tier: "fast"` (the cheap
+  Gemini flash "nanobanana"-class model) unless the user explicitly asks for
+  best quality; pass `aspectRatio` matching the layout slot (e.g. `21:9` hero,
+  `4:3` card, `1:1` avatar); include the linked design system's
+  `imageStyle.styleDescription` in the prompt when one is linked; and always
+  pass `callerAppId: "design"`. When the Assets picker returns a
   selected asset, preserve `assetId`, `runId`, and URLs verbatim; if a design is
   open, call `insert-asset` with the chosen URL/id, then refine placement with
   `get-design-snapshot` and `edit-design` as needed. If no Assets MCP tool is
@@ -151,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`,
@@ -193,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
 
@@ -223,6 +240,58 @@ patterns live in `.agents/skills/`.
   with `path`/`url` when visualizing a flow; pass `paths` for a concise route
   list. Then call `navigate --view editor --designId <id> --editorView overview`.
 
+## Review, Breakpoints, Screen States & Components
+
+- **Review**: `run-design-audit` runs a read-only accessibility audit over a
+  design's rendered HTML (missing alt/labels, tap-target size,
+  focus-visibility, reduced-motion coverage, a contrast hint) and returns
+  `A11yFinding[]`. `apply-a11y-fix` applies one deterministic inline fix for a
+  finding (contrast, tap-target size, focus ring) when `fixAvailable: true`.
+  `get-design-review` compares two design snapshots/branches and returns a
+  file-level visual diff (added/removed/modified). See the `design-generation`
+  skill's Phase 5 for when to run these.
+- **Breakpoints**: `add-breakpoint`, `remove-breakpoint`, and
+  `set-active-breakpoint` manage the design's device-width frame set and which
+  frame new edits target. See the `design-generation` skill's "Breakpoints &
+  screen states" section.
+- **Design states**: `create-design-state`, `apply-design-state`,
+  `capture-design-state`, `list-design-states`, and `delete-design-state`
+  manage named DOM/Alpine states (Loading/Empty/Error), static data fixtures,
+  and live app captures. See the same skill section.
+- **Components**: `create-component` promotes a selected element into a
+  recognised reusable component; `index-components` scans a design's HTML for
+  existing component annotations; `get-component-details`,
+  `preview-component-prop-edit`, `apply-component-prop-edit`, and
+  `open-component-source` inspect, preview, persist, and navigate to a
+  component instance. See the `design-generation` skill's "Component reuse"
+  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
@@ -264,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,

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

@@ -13,8 +13,10 @@
  * - `classReplace` — replaces one Tailwind class with another on the root node.
  *
  * **Tier B (real-app, localhost / fusion):**  prop writes require the
- * `applyEdit` source capability (bridge write hardening).  Until that lands the
- * action returns a `ctaRequired: true` response and does not modify any source.
+ * `applyEdit` source capability.  Localhost sources have it (design bridge +
+ * user write consent); fusion sources gain it after bridge hardening.  For
+ * sources without it the action returns a `ctaRequired: true` response and
+ * does not modify any source.
  *
  * See DESIGN-STUDIO-PLAN.md §6.1, §7 (preview/apply contract), §11 phase 2.
  */
@@ -48,6 +50,7 @@ import type {
   ClassEditIntent,
   StyleEditIntent,
 } from "../shared/code-layer.js";
+import { agentSelectionDescriptor } from "../shared/collab-selection.js";
 import {
   componentNameFor,
   componentNodeIdMatches,
@@ -342,70 +345,12 @@ export default defineAction({
       );
     }
 
-    // ── Build edit intent ────────────────────────────────────────────────────
-    // Map the component prop edit kind to an EditIntent that apply-visual-edit
-    // understands.  We use the same deterministic patch path for all kinds.
-
-    const target = { nodeId };
-
-    let intent: ClassEditIntent | StyleEditIntent;
-
-    if (edit.kind === "alpineData") {
-      // x-data is not a standard CSS property or Tailwind class — we write it
-      // as a style-like "attribute" edit by embedding it in the class edit path
-      // via the `set` operation on a synthetic class string.  Because the HTML
-      // patcher writes raw attribute values we use the attribute-set approach
-      // that `apply-visual-edit` already supports through the `style` path
-      // (targeting `x-data` as a custom property in an inline `style`
-      // attribute would corrupt the DOM, so instead we encode the value in a
-      // `data-agent-native-alpine-data` attribute and let the bridge pick it
-      // up).  For maximum compatibility with the existing apply-visual-edit
-      // path we use a class operation to manipulate the x-data value through a
-      // well-known pattern the bridge understands.
-      //
-      // The cleanest path is to write `data-agent-native-alpine-data` as an
-      // attribute so the iframe bridge can relay it to Alpine as the effective
-      // x-data — but since the bridge postMessage layer handles x-data edits
-      // on preview, for the persist path we do a direct HTML attribute patch.
-      // We accomplish this by treating it as a `style` edit on a sentinel
-      // property that the patcher will place as an attribute.  However the
-      // current patcher only handles CSS properties, so we write the x-data
-      // value through the attribute approach: stamp `data-agent-native-prop-x-data`.
-      intent = {
-        kind: "class",
-        target,
-        // Use the `set` operation with a minimal token list to mark the node's
-        // Alpine data without touching real layout classes.  The actual x-data
-        // attribute is written below via a direct HTML splice.
-        operation: "add",
-        className: `data-[x-data=${JSON.stringify(edit.value)}]:hidden`, // sentinel (will not apply visually)
-      } as ClassEditIntent;
-      // Fall through to the direct HTML splice below.
-    } else if (edit.kind === "classReplace") {
-      intent = {
-        kind: "class",
-        target,
-        operation: "replace",
-        from: edit.from,
-        to: edit.to,
-      } as ClassEditIntent;
-    } else {
-      // attribute kind — write as a class add of a data-attribute sentinel so
-      // the existing patcher path handles it, then fall through to the direct
-      // splice for the actual attribute patch.
-      intent = {
-        kind: "class",
-        target,
-        operation: "add",
-        className: `data-[prop-${edit.attribute}]:hidden`, // sentinel
-      } as ClassEditIntent;
-    }
-
-    // ── Direct HTML splice for attribute edits (alpineData + attribute) ──────
-    // The existing apply-visual-edit patcher is class/style/text focused.  For
-    // attribute mutations on the component root we splice the raw HTML directly
-    // using the node's source span (the same technique the patcher uses for
-    // attribute stamping).
+    // ── Apply the edit ───────────────────────────────────────────────────────
+    // - alpineData / attribute: attribute mutations on the component root are
+    //   applied with a direct HTML splice using the node's source span — the
+    //   deterministic patcher is class/style/text focused.
+    // - classReplace: routed through the deterministic apply-visual-edit
+    //   patcher (same seam as all other class edits).
 
     let patchedContent = html;
     let changed = false;
@@ -420,8 +365,15 @@ export default defineAction({
       );
       patchedContent = result.content;
       changed = result.changed;
-    } else if (edit.kind === "classReplace") {
-      // Use the deterministic patcher for class edits.
+    } else {
+      // classReplace — use the deterministic patcher for class edits.
+      const intent: ClassEditIntent = {
+        kind: "class",
+        target: { nodeId },
+        operation: "replace",
+        from: edit.from,
+        to: edit.to,
+      };
       const patch = applyVisualEdit(html, intent, { source: codeLayerSource });
       if (patch.result.status === "applied" && patch.result.changed) {
         patchedContent = patch.content;
@@ -440,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-motion-edit.ts

@@ -97,6 +97,18 @@ export function canPatchManagedMotionCss(content: string): boolean {
   return /<\s*(?:!doctype|[a-z][a-z0-9:-]*(?:\s|>|\/>))/i.test(content);
 }
 
+// Composite key for detecting duplicate (targetNodeId, property) track pairs.
+// Uses the ASCII Unit Separator (U+001F) — an escape in source, so the file
+// stays plain text (a literal NUL made tooling treat it as binary). U+001F
+// cannot appear in a valid data-agent-native-node-id or CSS property name
+// (both are validated to CSS-safe identifiers), so it can never collide with
+// real content and remains an unambiguous field delimiter.
+const MOTION_TRACK_KEY_SEPARATOR = "\x1f";
+
+export function motionTrackKey(targetNodeId: string, property: string): string {
+  return `${targetNodeId}${MOTION_TRACK_KEY_SEPARATOR}${property}`;
+}
+
 async function persistFileContent(
   fileId: string,
   designId: string,
@@ -168,7 +180,10 @@ export default defineAction({
       .number()
       .int()
       .positive()
-      .default(300)
+      // Keep in sync with the MotionDock default (DesignEditor
+      // motionDurationMs) and get-motion-timeline's CSS-recovery fallback so
+      // an omitted duration means the same thing on every surface.
+      .default(1000)
       .describe("Total animation duration in milliseconds."),
     defaultEase: z
       .string()
@@ -254,9 +269,21 @@ export default defineAction({
 
     // Reject CSS-injection vectors in caller-supplied track properties,
     // keyframe values, and easing strings before they are compiled into the
-    // managed <style> block.
+    // managed <style> block. Also reject duplicate (targetNodeId, property)
+    // pairs: the compiler derives the animation name from that pair, so a
+    // duplicate would silently overwrite the earlier track's keyframes.
+    const seenTrackKeys = new Set<string>();
     for (const track of typedTracks) {
       assertSafeMotionCssProperty(track.property, "track.property");
+      const trackKey = motionTrackKey(track.targetNodeId, track.property);
+      if (seenTrackKeys.has(trackKey)) {
+        throw new Error(
+          `Duplicate motion track for targetNodeId "${track.targetNodeId}" ` +
+            `and property "${track.property}". Each (targetNodeId, property) ` +
+            "pair may appear at most once — merge the keyframes into a single track.",
+        );
+      }
+      seenTrackKeys.add(trackKey);
       for (const kf of track.keyframes) {
         assertSafeMotionCssToken(kf.value, "keyframe value");
         if (kf.ease !== undefined) {

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. */
@@ -106,6 +133,7 @@ function scopeClassIntentToBreakpoint(
       prefix,
       operation: "replace",
       utility: intent.to,
+      from: intent.from,
     };
   }
 
@@ -474,11 +502,12 @@ export default defineAction({
       const patch = applyVisualEdit("", editIntent, {
         source: codeLayerSource,
       });
+      // local-file / remote-url sources are not editable here (the engine
+      // reports "unsupported"), so no byte counts are returned — a 0/0 pair
+      // would misleadingly suggest an empty file was measured.
       return {
         result: patch.result,
         projection: patch.projection,
-        bytesBefore: 0,
-        bytesAfter: 0,
       };
     }
 
@@ -488,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,