@agent-native/core 0.92.10 → 0.92.12

package/corpus/templates/design/.agents/skills/design-systems/SKILL.md

@@ -248,6 +248,92 @@ design-system indexing just to insert a component. Use
 component/component set with provenance. Styles and variables still belong in
 the Builder-backed design-system path above.
 
+### Import from Figma (pixel-accurate frame import)
+
+**When the user pastes a Figma frame/screen link and wants a real, editable
+Design screen** (not a rendered image, not a component insert), use
+`import-figma-frame` instead of `list-figma-library-assets` +
+`insert-figma-library-asset`:
+
+```bash
+pnpm action import-figma-frame --figmaUrl "https://www.figma.com/design/<fileKey>/<name>?node-id=<id>"
+# or
+pnpm action import-figma-frame --fileKey "<fileKey>" --nodeId "12:34" --designId "<designId>"
+```
+
+- Accepts a full Figma URL (design/file/proto share links, including
+  `/branch/<key>/` branch URLs — the branch's own key is used automatically) or
+  an explicit `fileKey` + `nodeId`. If `nodeId` is omitted, the file's first
+  top-level frame is imported.
+- Maps the node tree to real HTML/CSS: exact position/size, auto-layout as
+  flexbox, text (font, line-height, letter-spacing, case, decoration, align),
+  fills (solid/gradient/image, correctly layered and gradient-angle-derived,
+  not a default angle), strokes (including the CENTER/INSIDE/OUTSIDE
+  distinction), per-corner radii, shadows/blur, opacity, and blend modes.
+  Vector networks, boolean operations, and other structurally unsupported node
+  types are rendered as an exact PNG at 2x scale instead of an approximated
+  shape guess.
+- Saves the result as a new screen via the same import path as other Design
+  imports (`saveImportedDesignFiles`), placed on the overview canvas.
+- Returns a `fidelityReport` — `exactCount`, `approximated` (properties CSS
+  can only approximate: rotation, per-side stroke weights, radial/angular/
+  diamond gradients, blur radius scale), and `imageFallbacks` (subtrees
+  rendered as PNG instead of structural HTML). Read this back to the user when
+  a design has non-trivial fallbacks so they know what to expect if they later
+  edit that subtree.
+- After import, treat the screen like any other: `view-screen`,
+  `get-design-snapshot`, `apply-visual-edit` / `edit-design` all work normally
+  on it.
+- For a file's published FILL/TEXT/EFFECT/GRID styles (name, description, node
+  id — not full token values), use `get-figma-styles` with `fileUrl`/`fileKey`.
+  This is the file's Styles panel, not the Enterprise Variables API; full
+  design-token extraction still routes through the Builder-backed
+  `index-design-system-with-builder` path above.
+
+#### Paste from Figma (Cmd+C/Cmd+V) vs. a copied frame link
+
+A plain clipboard paste (Cmd+C in Figma, Cmd+V on the Design canvas) is
+handled separately from `import-figma-frame`, because a clipboard paste and a
+copied frame **link** carry fundamentally different information:
+
+- **A copied frame link** (`?node-id=...`) names an exact node. Always exact —
+  use `import-figma-frame`.
+- **A plain clipboard paste** only carries Figma's `figmeta` marker, which is
+  `{fileKey, pasteID, dataType}` — **no node id at all**, and `pasteID` is an
+  ephemeral, server-side identifier that the public REST API can't resolve
+  back to a node. So a clipboard paste can only ever get an exact node import
+  on a **best-effort match**, never a guarantee.
+
+The canvas paste listener (`app/lib/figma-clipboard.ts` +
+`import-figma-clipboard`) handles this automatically:
+
+1. Decodes `figmeta` from the pasted HTML client-side
+   (`extractFigmeta`/`resolveFigmaPasteImportCall`) to decide whether to call
+   `import-figma-clipboard` (figmeta present) or the legacy
+   `import-design-source` HTML path (no figmeta — not a Figma paste, or an
+   older Figma client that doesn't emit the marker).
+2. `import-figma-clipboard` fetches the file's shallow structure (top-level
+   frames + their direct children, `server/lib/figma-node-import.ts`'s
+   `fetchFileStructure(fileKey, 3)`) and heuristically matches it against the
+   pasted content's visible text (`server/lib/figma-clipboard-match.ts`):
+   a frame is only imported when its **name** or at least **two distinct
+   text-layer contents** appear verbatim in the paste. Anything ambiguous or
+   unmatched imports **nothing structural** — it never guesses and never
+   imports the whole file uninvited.
+3. On a confident match, the matched node(s) are fetched and mapped through
+   the same `buildScreenFilesFromFigmaNodes` core `import-figma-frame` uses
+   (`strategy: "restNodes"` in the result, with a `fidelityReport`).
+4. Otherwise it falls back to the legacy visible-HTML paste
+   (`strategy: "htmlFallback"`), and reports why via `matchStatus`
+   (`"ambiguous"`, `"none"`, or `"error"`) and `figmaApiKeyMissing` (no
+   `FIGMA_ACCESS_TOKEN` configured). The canvas paste toast surfaces a hint in
+   both cases: connect the Figma access token, or paste a frame **link**
+   instead for a guaranteed-exact import.
+
+Tell users who want guaranteed pixel-exact imports to copy a frame **link**
+("Copy link to selection" in Figma), not just Cmd+C — a plain paste is
+convenient but only best-effort.
+
 ### Source: Brand Analysis (combines website + notes)
 
 ```bash

package/corpus/templates/design/.agents/skills/export-handoff/SKILL.md

@@ -17,6 +17,9 @@ How to export designs and generate handoff documentation for developers converti
   with the editor's Download SVG command. The editor's own Download SVG
   command captures the live browser DOM for the most faithful snapshot; use
   the action when you need agent-side SVG export without a live browser.
+  **This is not importable into Figma as editable vectors** — Figma cannot
+  parse `foreignObject` content, so it stays an opaque embedded HTML blob.
+  Use `export-design-as-figma-svg` (below) when the destination is Figma.
 - **PNG**: there is no PNG export action. Point the user to the editor's
   download menu (Download PNG) — PNG export is a client-side rasterization of
   the live canvas and is not exposed as an agent action.
@@ -88,6 +91,60 @@ pnpm action export-pdf --id <designId>
 
 Returns all design data and files needed for the client to render a PDF.
 
+## Export to Figma (SVG)
+
+`export-design-as-figma-svg` exports a design screen (or a selected
+element's subtree) as a genuinely VECTOR SVG document — real
+`<rect>`/`<path>`/`<text>`/`<image>` markup with
+`<linearGradient>`/`<radialGradient>`/`<filter>` defs. Figma's SVG importer
+parses this into normal, editable layers (rect/path/gradients/filters stay
+editable). This is a different artifact from `export-svg` above, whose
+`foreignObject` wrapper Figma cannot import as vectors at all.
+
+```bash
+pnpm action export-design-as-figma-svg --designId <designId>
+```
+
+Optional args:
+
+- `fileId` / `filename` — pick a specific screen (defaults to `index.html`).
+- `nodeId` — scope the export to one selected element's subtree via its
+  `data-agent-native-node-id`, instead of the whole screen.
+- `embedImages` (default `true`) — fetch and inline `http(s)` image sources
+  and background-images as `data:` URIs, so the SVG is self-contained for
+  clipboard paste. Set `false` to keep absolute URLs instead.
+
+Returns `{ svg, filename, report, filePath? }`. `report` classifies every
+element as `vectorized`, `approximated` (mapped with a documented caveat —
+e.g. a non-square gradient angle, a non-uniform border, a radial gradient's
+shape/position), `rasterized` (video/canvas/iframe content, and any element
+with `backdrop-filter`, which SVG cannot express — embedded as a cropped
+screenshot instead), or `omitted`. If no headless Chromium binary is
+available in the current environment (expected in hosted/serverless
+deploys), the action returns `{ ok: false, reason }` instead of throwing —
+fall back to `export-svg` or `export-html`.
+
+**Vectorized-text caveat**: Figma converts every imported SVG `<text>`
+element to outlined vector paths on paste/drag-import. The exported
+geometry is pixel-exact, but text pasted from this export is no longer
+live, editable type in Figma — it's outlines, the same way any other
+SVG-authoring tool's text becomes outlines on import. This is a Figma
+import limitation, not a defect in the export; the report's
+`vectorizedTextCaveat` field carries this note for the agent/user.
+
+**Getting it into Figma**: two supported paths —
+
+1. **Copy, then paste into Figma.** In the editor, right-click a selected
+   element or the canvas and choose **Copy as SVG** (Copy/Paste as ▸ Copy as
+   SVG). This writes the SVG markup to the system clipboard as `text/plain`
+   (the MIME Figma's own paste handler reads for "paste as vector shapes")
+   plus `image/svg+xml` as a secondary representation. Paste directly into a
+   Figma canvas.
+2. **Download, then drag-import.** Figma's file browser also accepts a
+   plain `.svg` file dropped/imported directly — save the `svg` string
+   returned by the action to a `.svg` file and drag it into a Figma page the
+   same way you'd import any other SVG asset.
+
 ## Coding Handoff
 
 When a user wants to convert an Alpine.js + Tailwind prototype into production

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

@@ -208,6 +208,17 @@ the connected app's text/code files through the bridge
 - 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.
+- React/TSX canvas edits use build/debug provenance to locate the responsible
+  source, but structural meaning belongs to the coding agent. Do not apply a
+  generic AST reparent/group/ungroup transform. Hand off the exact subject and
+  target source anchors plus their runtime relationship; repeated `.map()`
+  instances, shared components, dynamic expressions, and cross-file edits
+  always require semantic inspection.
+- For every semantic React write, read the file first, pass that exact
+  `versionHash` to `write-local-file` with `requireExpectedVersionHash: true`,
+  re-read and re-plan if it conflicts, and
+  verify the resulting HMR/runtime state before treating the preview as saved.
+  Human write consent remains mandatory and cannot be granted by an agent.
 
 ## Verification
 

package/corpus/templates/design/AGENTS.md

@@ -67,6 +67,17 @@ patterns live in `.agents/skills/`.
   or pass it as an action parameter. Figma styles and variables are design-system
   inputs, not draggable media assets; route full file/design-system extraction
   through Builder-backed indexing.
+- To import a Figma frame/screen as a real, editable Design screen (not a
+  rendered image), use `import-figma-frame` with a `figmaUrl` (or
+  `fileKey`/`nodeId`) — it maps position, auto-layout, text, fills/gradients,
+  strokes, corner radii, effects, opacity, and blend modes pixel-accurately,
+  falling back to an exact PNG only for vector networks/boolean ops/unsupported
+  node types, and saves the result as a new screen. Read the returned
+  `fidelityReport` (`approximated`, `imageFallbacks`) back to the user when
+  non-trivial. Use `get-figma-styles` for a file's published style names (not
+  the Enterprise Variables API; full token extraction still routes through
+  Builder-backed indexing). See the `design-systems` skill's "Import from
+  Figma" section.
 - Use Alpine.js and Tailwind CDN for interactive prototypes. Prefer Alpine
   directives over raw inline event handlers.
 - Navigate between prototype screens with Alpine state (`x-show`), a
@@ -112,9 +123,14 @@ patterns live in `.agents/skills/`.
   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
-  design shell, call `show-design-questions`, stop while the main canvas shows
-  the questions, then continue from the user's answers.
+- For a brief or ambiguous _new_ design prompt, ask before generating:
+  create/open the design shell, call `show-design-questions` with a small
+  tailored set, stop while the main canvas shows the questions, then continue
+  from the user's answers. Skip asking when the prompt is already specific,
+  it's a tweak/edit to an existing design, the user already answered a
+  question set for this design and is now iterating, or they say "decide for
+  me"/"surprise me"/"just build it" — see the `design-generation` skill for
+  how to size and word the questions.
 - 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
@@ -202,12 +218,27 @@ patterns live in `.agents/skills/`.
   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.
+- For localhost React/TSX screens, treat compiler/debug metadata (project-relative
+  source file, line, column, component, and runtime multiplicity) as evidence
+  for locating source, not as permission to run a generic AST transform.
+  Compiler tooling may verify an anchor, classify a literal edit, and validate
+  syntax. Reparenting, grouping/ungrouping, wrappers, dynamic expressions,
+  repeated `.map()` instances, shared components, and cross-file changes must
+  be handed to the coding agent with both runtime relationships and exact
+  source anchors so it can inspect the surrounding program semantics.
+- A localhost React handoff must read each source file first, write with the
+  exact returned `versionHash` as `expectedVersionHash` with
+  `requireExpectedVersionHash: true`, re-read and re-plan on conflict, and leave the
+  optimistic canvas preview in place until the dev server/HMR confirms the
+  runtime result. Never report a semantic canvas change as persisted merely
+  because it was submitted to the coding agent.
 - 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.
+- Inline/Alpine screens continue to use deterministic HTML code-layer edits.
+  Localhost React/TSX screens use the semantic coding-agent handoff above;
+  deterministic direct React writes remain intentionally limited to narrowly
+  proven literal edits and never include generic structural transforms.
 
 ## Code Workspace
 
@@ -282,12 +313,16 @@ patterns live in `.agents/skills/`.
   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`,
+  existing component annotations; `list-design-components` scans all HTML
+  screens for swap targets; `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.
+  component instance. Use `go-to-main-component` to select the earliest known
+  instance, `swap-component-instance` to replace an inline/Alpine instance
+  while preserving same-named prop overrides, and
+  `detach-component-instance` to turn an instance into plain editable markup.
+  See the `design-generation` skill's "Component reuse" section — promote a
+  3+ times repeated pattern instead of inventing another near-duplicate.
 
 ## Full App Building
 

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

@@ -25,6 +25,7 @@ import {
   type CanvasFrameGeometry,
   type CanvasFramePlacement,
 } from "../shared/canvas-frames.js";
+import { isUniqueConstraintViolation } from "../shared/db-conflict.js";
 import {
   makeLocalhostRouteId,
   titleFromRoutePath,
@@ -488,6 +489,18 @@ export default defineAction({
       height: number;
     }> = [];
     const placementIntents: PlacementIntent[] = [];
+    // Duplicate-route guard: `existingFiles`/`existingByFilename`/the
+    // route-candidate lookups below are all snapshotted ONCE above the loop
+    // and never refreshed as new files are inserted mid-loop, so two entries
+    // in the SAME `requestedRoutes` call that resolve to the same route
+    // (repeated `paths`, or a `routeId` and a `path` naming the same route)
+    // each independently see "no existing match" and each insert a fresh
+    // `design_files` row — two overlapping screens for one route. Track
+    // routeIds already processed THIS call (keyed with width/height so an
+    // intentional multi-viewport request for the same route still creates
+    // its distinct variants) and skip later duplicates outright.
+    const seenRouteRequestKeys = new Set<string>();
+    let placementIndex = 0;
 
     for (let index = 0; index < requestedRoutes.length; index += 1) {
       const input = requestedRoutes[index]!;
@@ -505,6 +518,9 @@ export default defineAction({
       );
       const routeId =
         input.routeId ?? manifestRoute?.id ?? makeLocalhostRouteId(path);
+      const routeRequestKey = `${routeId}::${input.width ?? ""}x${input.height ?? ""}`;
+      if (seenRouteRequestKeys.has(routeRequestKey)) continue;
+      seenRouteRequestKeys.add(routeRequestKey);
       const title =
         input.title ?? manifestRoute?.title ?? titleFromRoutePath(path);
       const sourceFile = input.sourceFile ?? manifestRoute?.sourceFile;
@@ -619,7 +635,9 @@ export default defineAction({
       const filename =
         existing?.filename ??
         uniqueFilename(path, usedFilenames, preferredFilename);
-      const fileId = existing?.id ?? nanoid();
+      // Reassigned below if a concurrent request wins the insert race for
+      // this exact (designId, filename) pair — see the `else` branch.
+      let fileId = existing?.id ?? nanoid();
       const existingScreenMetadata = existing
         ? metadataForFile(
             existing.id,
@@ -656,16 +674,50 @@ export default defineAction({
           await seedFromText(existing.id, url);
         }
       } else {
-        await db.insert(schema.designFiles).values({
-          id: fileId,
-          designId,
-          filename,
-          fileType: "html",
-          content: url,
-          createdAt: now,
-          updatedAt: now,
-        });
-        await seedFromText(fileId, url);
+        try {
+          await db.insert(schema.designFiles).values({
+            id: fileId,
+            designId,
+            filename,
+            fileType: "html",
+            content: url,
+            createdAt: now,
+            updatedAt: now,
+          });
+          await seedFromText(fileId, url);
+        } catch (err) {
+          if (!isUniqueConstraintViolation(err)) throw err;
+          // Cross-request race: this snapshot's `existingFiles` query ran
+          // before a concurrent add-localhost-screens call (for the same
+          // route) committed its own insert, so both requests independently
+          // computed the same deterministic filename and both tried to
+          // create it. The `design_files_design_filename_unique_idx` unique
+          // index (see server/plugins/db.ts) turns the loser's insert into
+          // this error instead of a silent duplicate screen. Recover by
+          // adopting whichever row actually won the race and updating its
+          // content, the same way the `existing` branch above does.
+          const [winner] = await db
+            .select()
+            .from(schema.designFiles)
+            .where(
+              and(
+                eq(schema.designFiles.designId, designId),
+                eq(schema.designFiles.filename, filename),
+              ),
+            )
+            .limit(1);
+          if (!winner) throw err;
+          fileId = winner.id;
+          await db
+            .update(schema.designFiles)
+            .set({ content: url, fileType: "html", updatedAt: now })
+            .where(eq(schema.designFiles.id, winner.id));
+          if (await hasCollabState(winner.id)) {
+            await applyText(winner.id, url, "content", "agent");
+          } else {
+            await seedFromText(winner.id, url);
+          }
+        }
       }
 
       savedScreens.push({
@@ -688,12 +740,13 @@ export default defineAction({
         x:
           input.x ??
           existingFrame?.x ??
-          layoutStartX + index * (width + layoutGap),
+          layoutStartX + placementIndex * (width + layoutGap),
         y: input.y ?? existingFrame?.y ?? layoutStartY,
         width,
         height,
-        z: input.z ?? existingFrame?.z ?? index,
+        z: input.z ?? existingFrame?.z ?? placementIndex,
       };
+      placementIndex += 1;
       placementIntents.push({
         fileId,
         filename,

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

@@ -12,11 +12,12 @@
  *                    HTML attribute on the component root.
  * - `classReplace` — replaces one Tailwind class with another on the root node.
  *
- * **Tier B (real-app, localhost / fusion):**  prop writes require the
- * `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.
+ * **Real-app sources (localhost / fusion):** deliberately fail closed. This
+ * action's patcher operates on SQL-backed HTML design files; it must never be
+ * reused for compiled JSX/TSX source. Real-app prop persistence needs a
+ * dedicated consented, version-guarded bridge transform. Until that exists,
+ * callers may preview but this action returns `ctaRequired: true` without
+ * reading or modifying a design file.
  *
  * See DESIGN-STUDIO-PLAN.md §6.1, §7 (preview/apply contract), §11 phase 2.
  */
@@ -38,10 +39,11 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 import {
+  prepareInlineSourceEdit,
+  SourceWorkspaceEditConflictError,
   writeInlineSourceFile,
   type SourceWorkspaceFile,
 } from "../server/source-workspace.js";
-import { resolveSourceCapabilities } from "../shared/capability-resolver.js";
 import {
   applyVisualEdit,
   buildCodeLayerProjection,
@@ -56,9 +58,7 @@ import {
   componentNameFor,
   componentNodeIdMatches,
 } from "../shared/component-model.js";
-import { hasCapability } from "../shared/design-source-capabilities.js";
 import { designSourceTypeFromData } from "../shared/source-mode.js";
-import { sourceContentHash } from "../shared/source-workspace.js";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -174,8 +174,8 @@ export default defineAction({
     "For inline/Alpine designs, edits the data-agent-native-prop-* attributes, " +
     "x-data expression, or class list of the component root via the deterministic " +
     "HTML-patch path (same seam as apply-visual-edit). " +
-    "For real-app sources, the applyEdit capability must be available; if not, " +
-    "returns ctaRequired=true without modifying any file.",
+    "For real-app sources, returns ctaRequired=true without modifying any file; " +
+    "compiled source requires a dedicated consented bridge transform.",
   schema: z.object({
     designId: z.string().describe("Design project ID"),
     nodeId: z
@@ -234,19 +234,21 @@ export default defineAction({
       .optional(),
   }),
   run: async ({ designId, nodeId, fileId, edit, source }) => {
-    const db = getDb();
-
     // ── Access check ────────────────────────────────────────────────────────
     const access = await resolveAccess("design", designId);
     if (!access) throw new Error("Design not found");
 
-    // ── Source type + capability gate ────────────────────────────────────────
+    // ── Source type gate ────────────────────────────────────────────────────
     const rawData = (access.resource as { data?: unknown }).data;
     const sourceType = designSourceTypeFromData(rawData);
-    const caps = resolveSourceCapabilities(sourceType);
 
-    // Real-app sources gate on `applyEdit` (bridge write hardening).
-    if (sourceType !== "inline" && !hasCapability(caps, "applyEdit")) {
+    // Fail closed for every real-app tier even if its generic capability map
+    // advertises applyEdit. This action only knows how to patch SQL-backed HTML;
+    // allowing localhost through here could report success for the mirror while
+    // leaving the real JSX/TSX file untouched. A future compiled-source action
+    // must perform consent, canonical path resolution, AST anchoring, and an
+    // expected-version bridge write as one dedicated transaction.
+    if (sourceType !== "inline") {
       return {
         designId,
         nodeId,
@@ -254,13 +256,14 @@ export default defineAction({
         persisted: false,
         ctaRequired: true,
         ctaMessage:
-          "Prop write-back to real app sources requires the bridge applyEdit " +
-          "capability, which lands with bridge write hardening. " +
+          "Prop write-back to real app sources requires a dedicated consented, " +
+          "version-guarded compiled-source transform. " +
           "Use preview-component-prop-edit to preview without persisting.",
       };
     }
 
     await assertAccess("design", designId, "editor");
+    const db = getDb();
 
     // ── Fetch file ───────────────────────────────────────────────────────────
     const conditions = [
@@ -289,12 +292,24 @@ export default defineAction({
 
     if (!file) throw new Error("Design HTML file not found.");
 
-    if (
-      source?.currentContent &&
-      source.revision &&
-      file.updatedAt &&
-      source.revision !== file.updatedAt
-    ) {
+    const workspaceFile: SourceWorkspaceFile = {
+      id: file.id,
+      designId: file.designId,
+      filename: file.filename,
+      fileType: "html",
+      content: file.content,
+      createdAt: null,
+      updatedAt: file.updatedAt,
+    };
+    let prepared: Awaited<ReturnType<typeof prepareInlineSourceEdit>>;
+    try {
+      prepared = await prepareInlineSourceEdit({
+        file: workspaceFile,
+        currentContent: source?.currentContent,
+        revision: source?.revision,
+      });
+    } catch (error) {
+      if (!(error instanceof SourceWorkspaceEditConflictError)) throw error;
       return {
         designId,
         nodeId,
@@ -307,18 +322,12 @@ export default defineAction({
       };
     }
 
-    // Prefer explicit editor content after the caller's revision check, and use
-    // the saved SQL content as the fallback. Collab/Yjs reads can be stale
-    // across local dev worker processes and make prop controls lag behind.
-    const html =
-      typeof source?.currentContent === "string"
-        ? source.currentContent
-        : (file.content ?? "");
-    // Capture the hash of this EXACT base — the same string the transform
-    // below reads from — so persistEdit can pass it through as
-    // expectedVersionHash. A re-read at persist time would hash whatever is
-    // live "then" instead of proving this base is still current.
-    const baseVersionHash = sourceContentHash(html);
+    // The transform runs against the caller's working copy (when supplied),
+    // while the persist CAS uses the live hash that working copy is allowed to
+    // replace. Keeping those identities separate preserves rapid unsaved prop
+    // edits without weakening concurrent-writer rejection.
+    const html = prepared.content;
+    const baseVersionHash = prepared.expectedVersionHash;
 
     // ── Resolve node ─────────────────────────────────────────────────────────
     const codeLayerSource: CodeLayerSource = {

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

@@ -32,7 +32,7 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 import {
-  readLiveSourceFile,
+  prepareInlineSourceEdit,
   writeInlineSourceFile,
   type SourceWorkspaceFile,
 } from "../server/source-workspace.js";
@@ -51,7 +51,6 @@ import {
   readTimelinePlaybackMode,
   withTimelinePlaybackMode,
 } from "../shared/motion-timeline.js";
-import { sourceContentHash } from "../shared/source-workspace.js";
 
 // ─── DoS-guard caps ──────────────────────────────────────────────────────────
 //
@@ -343,7 +342,15 @@ export default defineAction({
       .describe(
         "Current open editor HTML for the target file. When supplied, the " +
           "managed motion CSS is patched into this content instead of the " +
-          "last SQL snapshot so in-flight local edits are preserved.",
+          "last SQL snapshot so in-flight local edits are preserved. " +
+          "revision must also be supplied.",
+      ),
+    revision: z
+      .string()
+      .optional()
+      .describe(
+        "design_files.updatedAt value the currentContent is based on. " +
+          "Required when currentContent is supplied.",
       ),
   }),
   run: async ({
@@ -357,6 +364,7 @@ export default defineAction({
     defaultEase,
     includeContent,
     currentContent: currentContentInput,
+    revision,
   }) => {
     const access = await assertAccess("design", designId, "editor");
 
@@ -378,6 +386,7 @@ export default defineAction({
         filename: schema.designFiles.filename,
         fileType: schema.designFiles.fileType,
         content: schema.designFiles.content,
+        updatedAt: schema.designFiles.updatedAt,
       })
       .from(schema.designFiles)
       .innerJoin(
@@ -398,40 +407,25 @@ export default defineAction({
     const fileId = file.id;
     const resolvedSourceRef = sourceRef ?? fileId;
 
-    // The EDITABLE base for compiling/injecting CSS: prefer the caller's
-    // in-flight editor snapshot when supplied (currentContentInput), else the
-    // LIVE collab-authoritative content for this file (not the raw SQL row —
-    // a live editor's Y.Text may be ahead of the last SQL snapshot). Either
-    // way, `baseVersionHash` is computed from the EXACT string chosen as the
-    // base, at this same point in time, so it faithfully represents "what
-    // this transform's base was" for the persist's optimistic-concurrency
-    // check below — never a fresh re-hash of already-transformed content
-    // (that would trivially match itself and prove nothing raced).
-    let currentContent: string;
-    let baseVersionHash: string;
-    if (currentContentInput !== undefined) {
-      // Caller supplied their own editor snapshot as the patch base. It may
-      // already be stale relative to the live doc — that's fine.
-      // writeInlineSourceFile's own guard (via readLiveSourceFile at write
-      // time) correctly rejects the write if this base no longer matches
-      // live state, exactly as designed for every other caller-supplied-base
-      // action (see apply-component-prop-edit.ts / apply-shader-fill.ts).
-      currentContent = currentContentInput;
-      baseVersionHash = sourceContentHash(currentContent);
-    } else {
-      const workspaceFileForRead: SourceWorkspaceFile = {
+    // Keep the transform working copy separate from the live version it may
+    // replace. A caller snapshot can legitimately contain unsaved local edits
+    // beyond the matching SQL revision; the write CAS must guard the observed
+    // live base, not incorrectly hash those unsaved edits as if already live.
+    const prepared = await prepareInlineSourceEdit({
+      file: {
         id: file.id,
         designId: file.designId,
         filename: file.filename,
         fileType: file.fileType,
         content: file.content,
         createdAt: null,
-        updatedAt: null,
-      };
-      const live = await readLiveSourceFile(workspaceFileForRead);
-      currentContent = live.content;
-      baseVersionHash = live.versionHash;
-    }
+        updatedAt: file.updatedAt,
+      },
+      currentContent: currentContentInput,
+      revision,
+    });
+    const currentContent = prepared.content;
+    const baseVersionHash = prepared.expectedVersionHash;
 
     // ── 2. Compile tracks → CSS ─────────────────────────────────────────────
     const inputTracks = tracks as MotionTrack[];