@agent-native/core 0.92.9 → 0.92.11

package/corpus/templates/content/app/i18n-data.ts

@@ -2463,6 +2463,8 @@ const enUS = {
     couldNotSaveLocalFile: "Could not save local file",
     collabConnectingReadOnly:
       "Connecting live editor. Showing a read-only snapshot.",
+    liveDocumentSaveBeforeSyncFailed:
+      "The live document could not be saved before syncing.",
     documentTitle: "Document title",
     builderBodySyncing: "Content is still syncing from Builder",
     builderBodySyncingDescription:
@@ -4843,6 +4845,7 @@ const editorMessagesByLocale = {
   "zh-CN": {
     noDocumentSelected: "未选择文档",
     collabConnectingReadOnly: "正在连接实时编辑器。显示只读快照。",
+    liveDocumentSaveBeforeSyncFailed: "实时文档无法在同步前保存。",
     builderBodySyncing: "内容仍在从 Builder 同步",
     builderBodySyncingDescription:
       "同步 Builder 正文完成前会暂停编辑，避免覆盖现有文章内容。",
@@ -5169,6 +5172,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Ningún documento seleccionado",
     collabConnectingReadOnly:
       "Conectando el editor en vivo. Mostrando una instantánea de solo lectura.",
+    liveDocumentSaveBeforeSyncFailed:
+      "No se pudo guardar el documento activo antes de sincronizarlo.",
     builderBodySyncing: "El contenido aún se está sincronizando desde Builder",
     builderBodySyncingDescription:
       "La edición está en pausa hasta que el cuerpo de Builder termine de sincronizarse, para no sobrescribir el contenido existente del artículo.",
@@ -5506,6 +5511,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Aucun document sélectionné",
     collabConnectingReadOnly:
       "Connexion de l'éditeur en direct. Affichage d'un instantané en lecture seule.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Le document actif n’a pas pu être enregistré avant la synchronisation.",
     builderBodySyncing:
       "Le contenu est encore en cours de synchronisation depuis Builder",
     builderBodySyncingDescription:
@@ -5846,6 +5853,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Kein Dokument ausgewählt",
     collabConnectingReadOnly:
       "Live-Editor wird verbunden. Schreibgeschützte Momentaufnahme wird angezeigt.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Das aktive Dokument konnte vor der Synchronisierung nicht gespeichert werden.",
     builderBodySyncing: "Inhalte werden noch von Builder synchronisiert",
     builderBodySyncingDescription:
       "Die Bearbeitung ist pausiert, bis der Builder-Textkörper fertig synchronisiert ist, damit der bestehende Artikelinhalt nicht überschrieben wird.",
@@ -6190,6 +6199,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "ドキュメントが選択されていません",
     collabConnectingReadOnly:
       "ライブエディターに接続中。読み取り専用のスナップショットを表示しています。",
+    liveDocumentSaveBeforeSyncFailed:
+      "同期前にライブドキュメントを保存できませんでした。",
     builderBodySyncing: "コンテンツはまだ Builder から同期中です",
     builderBodySyncingDescription:
       "既存の記事内容を上書きしないよう、Builder 本文の同期が完了するまで編集は一時停止されます。",
@@ -6524,6 +6535,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "선택한 문서가 없습니다.",
     collabConnectingReadOnly:
       "라이브 편집기에 연결하는 중입니다. 읽기 전용 스냅샷을 표시합니다.",
+    liveDocumentSaveBeforeSyncFailed:
+      "동기화하기 전에 실시간 문서를 저장하지 못했습니다.",
     builderBodySyncing: "콘텐츠가 아직 Builder에서 동기화되는 중입니다",
     builderBodySyncingDescription:
       "기존 문서 내용을 덮어쓰지 않도록 Builder 본문 동기화가 완료될 때까지 편집이 일시 중지됩니다.",
@@ -6857,6 +6870,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Nenhum documento selecionado",
     collabConnectingReadOnly:
       "Conectando o editor ao vivo. Exibindo um instantâneo somente leitura.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Não foi possível salvar o documento ativo antes da sincronização.",
     builderBodySyncing: "O conteúdo ainda está sincronizando do Builder",
     builderBodySyncingDescription:
       "A edição fica pausada até o corpo do Builder terminar de sincronizar, para não sobrescrever o conteúdo existente do artigo.",
@@ -7196,6 +7211,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "कोई दस्तावेज़ चयनित नहीं",
     collabConnectingReadOnly:
       "लाइव संपादक कनेक्ट हो रहा है। केवल-पठन स्नैपशॉट दिखाया जा रहा है।",
+    liveDocumentSaveBeforeSyncFailed:
+      "सिंक करने से पहले लाइव दस्तावेज़ सहेजा नहीं जा सका।",
     builderBodySyncing: "सामग्री अभी भी Builder से सिंक हो रही है",
     builderBodySyncingDescription:
       "Builder का मुख्य भाग सिंक पूरा होने तक संपादन रोका गया है, ताकि मौजूदा लेख सामग्री अधिलेखित न हो।",
@@ -7525,6 +7542,7 @@ const editorMessagesByLocale = {
     noDocumentSelected: "لم يتم تحديد أي مستند",
     collabConnectingReadOnly:
       "جارٍ الاتصال بالمحرر المباشر. يتم عرض لقطة للقراءة فقط.",
+    liveDocumentSaveBeforeSyncFailed: "تعذّر حفظ المستند المباشر قبل المزامنة.",
     builderBodySyncing: "لا يزال المحتوى قيد المزامنة من Builder",
     builderBodySyncingDescription:
       "يتم إيقاف التحرير مؤقتًا حتى تكتمل مزامنة نص Builder، حتى لا يتم استبدال محتوى المقالة الحالي.",

package/corpus/templates/content/changelog/2026-07-09-notion-conflict-choices-and-version-restores-preserve-docume.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Notion conflict choices and version restores preserve document paragraphs and protect live edits.

package/corpus/templates/content/server/lib/notion-sync.ts

@@ -2,7 +2,6 @@
 // in pnpm's node_modules. Logic is correct; types just don't unify across instances.
 import crypto from "node:crypto";
 
-import { deleteCollabState, releaseDoc } from "@agent-native/core/collab";
 import { and, eq, inArray, isNull, lt, or } from "drizzle-orm";
 import type { InferSelectModel } from "drizzle-orm";
 
@@ -37,6 +36,56 @@ function nanoid(size = 12): string {
   return Array.from(bytes, (byte) => chars[byte % chars.length]).join("");
 }
 
+async function replaceDocumentFromExternal(args: {
+  document: DocumentRow;
+  expectedUpdatedAt: string;
+  title: string;
+  content: string;
+  icon: string | null;
+  updatedAt: string;
+}): Promise<boolean> {
+  const db = getDb();
+  return db.transaction(async (tx) => {
+    const applied = await tx
+      .update(schema.documents)
+      .set({
+        title: args.title,
+        content: args.content,
+        icon: args.icon,
+        updatedAt: args.updatedAt,
+      })
+      .where(
+        and(
+          eq(schema.documents.id, args.document.id),
+          eq(schema.documents.ownerEmail, args.document.ownerEmail),
+          eq(schema.documents.updatedAt, args.expectedUpdatedAt),
+        ),
+      )
+      .returning({ id: schema.documents.id });
+
+    if (!applied || applied.length === 0) return false;
+
+    if (
+      args.title !== args.document.title ||
+      args.content !== args.document.content
+    ) {
+      // Keep the recovery snapshot in the same transaction as the replacement:
+      // a lost CAS creates no phantom version, and a snapshot failure rolls the
+      // destructive replacement back instead of leaving it unrecoverable.
+      await tx.insert(schema.documentVersions).values({
+        id: nanoid(),
+        ownerEmail: args.document.ownerEmail,
+        documentId: args.document.id,
+        title: args.document.title,
+        content: args.document.content,
+        createdAt: nowIso(),
+      });
+    }
+
+    return true;
+  });
+}
+
 /**
  * Hash of the canonical content. Two documents with the same hash are
  * byte-identical once canonicalized, so this is the authoritative "did the
@@ -827,8 +876,6 @@ async function pullDocumentFromNotionInner(
     remotePageDocumentIdByPageId?: RemotePageDocumentLookup;
   },
 ): Promise<DocumentSyncStatus> {
-  const db = getDb();
-  const document = await getDocument(documentId, owner);
   const link = await getSyncLink(documentId, owner);
   if (!link) throw new Error("Document is not linked to a Notion page.");
   const connection = await getNotionConnectionForOwner(owner);
@@ -935,28 +982,18 @@ async function pullDocumentFromNotionInner(
   // check will mistake the unchanged document for a fresh local edit.
   const updatedAt = contentChanged ? nowIso() : freshDocument.updatedAt;
   if (contentChanged) {
-    // Compare-and-swap: only apply the pulled content if the row is still at
-    // the snapshot we just re-read. If a concurrent save landed in between,
-    // 0 rows match and we fall through to the conflict path instead of
-    // clobbering the newer local write.
-    const applied = await db
-      .update(schema.documents)
-      .set({
-        title: newTitle,
-        content: newContent,
-        icon: newIcon,
-        updatedAt,
-      })
-      .where(
-        and(
-          eq(schema.documents.id, documentId),
-          eq(schema.documents.ownerEmail, owner),
-          eq(schema.documents.updatedAt, freshDocument.updatedAt),
-        ),
-      )
-      .returning({ id: schema.documents.id });
+    // Snapshot + compare-and-swap are one transaction: only the winning
+    // replacement gets a recovery version, and snapshot failure rolls it back.
+    const applied = await replaceDocumentFromExternal({
+      document: freshDocument,
+      expectedUpdatedAt: freshDocument.updatedAt,
+      title: newTitle,
+      content: newContent,
+      icon: newIcon,
+      updatedAt,
+    });
 
-    if (!applied || applied.length === 0) {
+    if (!applied) {
       // A newer local save raced in after our re-read. Do not adopt the
       // pulled content or advance the hash baseline — surface a conflict so
       // the user resolves it explicitly instead of silently losing the edit.
@@ -986,16 +1023,10 @@ async function pullDocumentFromNotionInner(
       });
     }
 
-    // Reset the Yjs collaborative state so it no longer holds the pre-sync
-    // content. Connected clients re-seed their Y.XmlFragment from the new
-    // `documents.content` value via VisualEditor's content-sync effect, and
-    // a fresh page load starts from an empty server state and seeds from SQL.
-    try {
-      await deleteCollabState(documentId);
-      releaseDoc(documentId);
-    } catch {
-      // Non-fatal — the client-side sync will still reconcile via setContent.
-    }
+    // Keep the Y.Doc intact. The live editor's updatedAt-gated reconcile applies
+    // this authoritative SQL snapshot as a minimal Yjs transaction. Deleting
+    // collab state here races connected clients (which can re-persist the stale
+    // pre-pull state) and briefly makes later flush handshakes miss the editor.
   }
 
   await upsertSyncLink({
@@ -1193,7 +1224,6 @@ async function pushDocumentToNotionInner(
   // the rare case Notion normalizes a construct differently, immediately
   // converging instead of ping-ponging. Re-read the row first so a local save
   // that landed during the multi-round-trip push isn't clobbered below.
-  const db = getDb();
   const freshDocument = await getDocument(documentId, owner);
   const newContent = remote.content ?? document.content;
   const newTitle = remote.title || document.title;
@@ -1211,39 +1241,25 @@ async function pushDocumentToNotionInner(
   // exactly what we pushed, since contentChanged is false).
   let baselineContent = document.content;
   if (contentChanged) {
-    // Compare-and-swap against the pre-push snapshot: if a concurrent save
-    // changed the row since `document` was read, skip adopting Notion's
-    // normalized content so the newer local edit is never overwritten. The
-    // hash baseline is still advanced to the *pushed* content below so the
-    // concurrent edit continues to show as localChanged and gets re-pushed on
-    // the next sync cycle.
-    const applied = await db
-      .update(schema.documents)
-      .set({
-        title: newTitle,
-        content: newContent,
-        icon: newIcon,
-        updatedAt: pushedAt,
-      })
-      .where(
-        and(
-          eq(schema.documents.id, documentId),
-          eq(schema.documents.ownerEmail, owner),
-          eq(schema.documents.updatedAt, document.updatedAt),
-        ),
-      )
-      .returning({ id: schema.documents.id });
+    // Snapshot + compare-and-swap are atomic. If a concurrent save changed the
+    // row since `document` was read, skip both the provider readback adoption
+    // and its recovery version; the newer local edit remains localChanged.
+    const applied = await replaceDocumentFromExternal({
+      document: freshDocument,
+      expectedUpdatedAt: document.updatedAt,
+      title: newTitle,
+      content: newContent,
+      icon: newIcon,
+      updatedAt: pushedAt,
+    });
 
-    if (applied && applied.length > 0) {
+    if (applied) {
       // The CAS landed — the row now holds Notion's normalized readback, so
       // the baseline must match that, not the pre-push content we sent.
       baselineContent = newContent;
-      try {
-        await deleteCollabState(documentId);
-        releaseDoc(documentId);
-      } catch {
-        // Non-fatal — the client reconciles via setContent.
-      }
+      // Preserve the live Y.Doc and let the updatedAt-gated editor reconcile
+      // apply this provider-normalized snapshot. Clearing collab persistence
+      // here can race a connected client's stale update and resurrect it.
     }
     // else: CAS raced and lost — the row holds the concurrent edit's content,
     // not `newContent` and not `document.content`. Keep baselineContent as

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

@@ -173,7 +173,7 @@ defaults. The banned-defaults list above still applies, plus:
 
 ## Generation Workflow — the canonical 5-phase flow
 
-This flow mirrors Claude Design's UX: ask → show variants → user picks → refine. Don't skip phases for new designs.
+This flow mirrors Claude Design's UX: clarify only what's unclear → show variants → user picks → refine. Don't collapse phases into one shot for new, open-ended designs.
 
 ### Phase 1 — Create the project + ask before generating
 
@@ -187,7 +187,28 @@ application state. External MCP hosts should surface the `create-design`
 returned "Open design" link, then use `present-design-variants` to open the
 visual picker.
 
-Then, for any non-trivial first prompt, call `show-design-questions` BEFORE generating. The editor renders a full-canvas overlay; answers come back as a chat message. Skip the questions only when the prompt is unambiguous ("re-skin this with my brand colors") or the user said "decide for me".
+Then, for a brief or ambiguous first prompt to a **new** design, call
+`show-design-questions` BEFORE generating. The editor renders a full-canvas
+overlay; answers come back as a chat message. Size the question count to how
+much is actually unresolved — most prompts warrant 2-4 questions, not the full
+1-8 range — and never ask about something the prompt already specified (a
+stated color, audience, or layout is settled; don't re-ask it as a choice).
+
+Skip the questions entirely when:
+- the prompt is already specific enough to generate from (names the audience,
+  purpose, and a visual direction, e.g. "a dark, data-dense analytics
+  dashboard for ops engineers" or "re-skin this with my brand colors");
+- it's a tweak/edit/refinement to an existing design rather than a new one —
+  go straight to `edit-design` (see Phase 3 and "Making edits" below);
+- the user already answered a question set for this design and is now
+  iterating — don't re-ask settled ground on follow-up prompts for the same
+  design; or
+- the user says "decide for me," "surprise me," "just build it," or similar.
+
+Asking on every prompt is as much a failure mode as never asking: a detailed
+prompt that already answers the obvious questions should generate
+immediately, and a design already in flight should not be interrupted with a
+second questionnaire.
 
 ```bash
 pnpm action show-design-questions \
@@ -196,6 +217,12 @@ pnpm action show-design-questions \
   --questions '[{"id":"form_factor","type":"text-options","question":"What form factor?","options":[{"label":"Desktop web app","value":"desktop"},{"label":"Mobile app","value":"mobile"},{"label":"Both / responsive","value":"responsive"},{"label":"Decide for me","value":"decide"}],"allowOther":true}]'
 ```
 
+Favor choice-first questions (2-5 concrete options, `allowOther: true`, and a
+"Decide for me" option when any answer is acceptable) over open-ended
+`freeform` text, and avoid `multiSelect` unless the question genuinely allows
+combining multiple answers — stacking multi-select questions multiplies
+follow-up ambiguity instead of resolving it.
+
 **Carry the form-factor answer through to generation — do not just ask and discard it.** A "Desktop web app" answer means the generated screen's canvas frame must be desktop-sized (~1440×1024), not left at whatever a screen with no placement falls back to. Map the answer to real frame geometry: pass `deviceType` (`"mobile"` / `"tablet"` / `"desktop"`) per screen to `generate-screens`, explicit `width`/`height` per variant to `present-design-variants`, or an explicit `canvasFrames` entry to `generate-design` — see Phase 2 and Phase 3 below. For "Both / responsive," generate at desktop width and rely on the responsive breakpoint system (see `responsive-breakpoints` skill) rather than guessing a size.
 
 ### Phase 2 — Generate side-by-side variations (2-5, three by default)

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