@agent-native/core 0.92.9 → 0.92.11

package/corpus/templates/design/actions/generate-screens.ts

@@ -2,10 +2,11 @@ import { defineAction, embedApp } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
 import { buildDeepLink } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
 
-import "../server/db/index.js";
+import { getDb, schema } from "../server/db/index.js";
 import {
   type AssignedCanvasRegion,
   DEFAULT_ASSIGNED_REGION_GAP,
@@ -186,6 +187,28 @@ export default defineAction({
           .min(1)
           .max(8)
           .superRefine((screens, ctx) => {
+            // Two screens sharing an explicit frameId would produce two
+            // DesignGenerationFrame entries with the same frameId (and thus
+            // the same derived agentId `agent-${frameId}`) once frames get
+            // built below, colliding agent presence/status tracking for both
+            // screens on the overview canvas.
+            const frameIdsSeen = new Map<string, number>();
+            screens.forEach((screen, index) => {
+              if (!screen.frameId) return;
+              const firstIndex = frameIdsSeen.get(screen.frameId);
+              if (firstIndex !== undefined) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index, "frameId"],
+                  message:
+                    `duplicate frameId "${screen.frameId}" (already used at index ${firstIndex}); ` +
+                    "each screen needs a distinct frameId",
+                });
+                return;
+              }
+              frameIdsSeen.set(screen.frameId, index);
+            });
+
             const requestAnchors = new Map<
               string,
               { index: number; role: DesignGenerationFrame["role"] }
@@ -259,21 +282,43 @@ export default defineAction({
           : DEFAULT_ASSIGNED_REGION_MAX_COLUMNS,
     });
 
-    const seenFilenames = new Map<string, number>();
-    // Dedupe any filename (explicit or auto-generated) so two screens can never
-    // resolve to the same target file — otherwise generate-design silently
-    // overwrites the first screen's output with the second's.
+    // Seed the used-filename set with the design's EXISTING files, not just
+    // names requested in this call. Without this, a requested/auto-slugged
+    // target (e.g. a screen titled "Onboarding" slugging to "onboarding.html")
+    // can silently collide with an already-saved screen: generate-design's
+    // existing-file lookup is keyed by filename, so the later generate-design
+    // call for that "new" target would UPDATE (overwrite) the pre-existing
+    // file instead of creating the new screen the agent intended.
+    const db = getDb();
+    const existingFiles = await db
+      .select({ filename: schema.designFiles.filename })
+      .from(schema.designFiles)
+      .where(eq(schema.designFiles.designId, designId));
+    const usedFilenames = new Set(
+      existingFiles
+        .map((file) => file.filename)
+        .filter((filename): filename is string => Boolean(filename)),
+    );
+    // Dedupe any filename (explicit or auto-generated) so two screens can
+    // never resolve to the same target file, and so no target collides with
+    // an existing screen — otherwise generate-design silently overwrites the
+    // other screen's content.
     const dedupeFilename = (base: string): string => {
-      if (!seenFilenames.has(base)) {
-        seenFilenames.set(base, 1);
+      if (!usedFilenames.has(base)) {
+        usedFilenames.add(base);
         return base;
       }
-      const count = seenFilenames.get(base)! + 1;
-      seenFilenames.set(base, count);
       const dot = base.lastIndexOf(".");
-      return dot > 0
-        ? `${base.slice(0, dot)}-${count}${base.slice(dot)}`
-        : `${base}-${count}`;
+      const stem = dot > 0 ? base.slice(0, dot) : base;
+      const ext = dot > 0 ? base.slice(dot) : "";
+      let count = 2;
+      let candidate = `${stem}-${count}${ext}`;
+      while (usedFilenames.has(candidate)) {
+        count += 1;
+        candidate = `${stem}-${count}${ext}`;
+      }
+      usedFilenames.add(candidate);
+      return candidate;
     };
     const requestedTargets = screens.map((screen, index) => {
       if (screen.filename) return dedupeFilename(screen.filename);

package/corpus/templates/design/actions/get-figma-styles.ts

@@ -0,0 +1,115 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { executeProviderApiRequest } from "../server/lib/provider-api.js";
+import { parseFigmaFileKey } from "../shared/figma-url.js";
+
+const schemaInput = z
+  .object({
+    fileUrl: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma file URL, for example https://www.figma.com/design/<fileKey>/...",
+      ),
+    fileKey: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Figma file key. Used when fileUrl is omitted."),
+  })
+  .refine((value) => value.fileUrl || value.fileKey, {
+    message: "Pass fileUrl or fileKey.",
+    path: ["fileUrl"],
+  });
+
+type FigmaProviderEnvelope = {
+  response?: {
+    ok?: boolean;
+    status?: number;
+    statusText?: string;
+    json?: unknown;
+    text?: string;
+  };
+};
+
+type FigmaStyleRecord = {
+  key?: unknown;
+  node_id?: unknown;
+  style_type?: unknown;
+  name?: unknown;
+  description?: unknown;
+};
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function providerJson(envelope: unknown, label: string): unknown {
+  const response = (envelope as FigmaProviderEnvelope | null)?.response;
+  if (!response) throw new Error(`Figma ${label} response was empty.`);
+  if (response.ok === false) {
+    const detail =
+      stringValue(response.text) ||
+      response.statusText ||
+      `HTTP ${response.status ?? "error"}`;
+    throw new Error(`Figma ${label} request failed: ${detail}`);
+  }
+  return response.json;
+}
+
+export default defineAction({
+  description:
+    "Summarize a Figma file's published styles (fill/text/effect/grid) by name, description, and node id. This is the file's Styles panel, NOT the Enterprise Variables API — full design-token extraction (including variables/collections) routes through index-design-system-with-builder or import-file --format fig. Requires the saved FIGMA_ACCESS_TOKEN secret.",
+  schema: schemaInput,
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    const fileKey =
+      parseFigmaFileKey(args.fileKey) ?? parseFigmaFileKey(args.fileUrl);
+    if (!fileKey) {
+      throw new Error("Could not find a Figma file key in the provided URL.");
+    }
+
+    const envelope = await executeProviderApiRequest({
+      provider: "figma",
+      method: "GET",
+      path: `/files/${fileKey}/styles`,
+      maxBytes: 2 * 1024 * 1024,
+    });
+    const json = providerJson(envelope, "styles") as {
+      meta?: { styles?: unknown };
+    };
+    const records = Array.isArray(json.meta?.styles)
+      ? (json.meta!.styles as FigmaStyleRecord[])
+      : [];
+
+    const styles = records
+      .filter((record) => record && typeof record === "object")
+      .map((record) => ({
+        key: stringValue(record.key),
+        nodeId: stringValue(record.node_id),
+        styleType: stringValue(record.style_type),
+        name: stringValue(record.name) ?? "Untitled style",
+        description: stringValue(record.description),
+      }));
+
+    const byType = styles.reduce<Record<string, number>>((acc, style) => {
+      const type = style.styleType ?? "UNKNOWN";
+      acc[type] = (acc[type] ?? 0) + 1;
+      return acc;
+    }, {});
+
+    return {
+      source: "figma",
+      fileKey,
+      total: styles.length,
+      byType,
+      styles,
+      guidance:
+        "These are the file's published FILL/TEXT/EFFECT/GRID styles (name, description, node id), not the Enterprise Variables API. For full design-system token extraction (variables, collections, modes) use index-design-system-with-builder or import-file --format fig instead of hand-mapping these style records.",
+    };
+  },
+});

package/corpus/templates/design/actions/go-to-main-component.ts

@@ -0,0 +1,254 @@
+/**
+ * go-to-main-component — Figma's "Go to main component".
+ *
+ * DESIGN NOTE — mapping onto this codebase's data model: there is no
+ * persisted "main component" concept anywhere here. A component is just a
+ * name (`data-agent-native-component="Name"`) that happens to be stamped on
+ * more than one element; every instance is an independently-duplicated copy
+ * of HTML (see `shared/component-model.ts`, `component_index` schema — it
+ * stores props/variants/runtime-selectors metadata, never a canonical
+ * definition). A true "main component" would require a data-model addition
+ * (e.g. an `isMain`/definition pointer on `component_index`) — out of scope
+ * here; flagged for a follow-up if promoting a specific instance as
+ * authoritative becomes a real need.
+ *
+ * Closest tractable equivalent: treat the EARLIEST instance of the same
+ * component name — scanning every design file in `createdAt` order, document
+ * order within each file — as the "main" analogue, mirroring the common case
+ * where a component's original occurrence predates its copies. If the given
+ * instance already IS that earliest one, this returns `isMain: true` instead
+ * of navigating (nothing to jump to). Otherwise it writes a `navigate`
+ * app-state command (same mechanism as `navigate` / `open-component-source`)
+ * so the editor selects the target instance, including switching design
+ * files when the main instance lives on a different screen.
+ *
+ * Navigation-only + inline/Alpine designs only (real-app sources return a
+ * CTA). Because this writes the transient `navigate` application-state
+ * command, it is exposed as the default POST mutation rather than a GET.
+ */
+
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { accessFilter, resolveAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import { buildCodeLayerProjection } from "../shared/code-layer.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import {
+  entriesForComponent,
+  scanComponentLibrary,
+} from "../shared/component-library.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+} from "../shared/component-model.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+
+async function liveContent(
+  fileId: string,
+  storedContent: string,
+): Promise<string> {
+  try {
+    if (await hasCollabState(fileId)) {
+      const live = await getText(fileId, "content");
+      if (typeof live === "string") return live;
+    }
+  } catch {
+    // Collab reads are best-effort; SQL content is the fallback.
+  }
+  return storedContent;
+}
+
+export default defineAction({
+  description:
+    "Resolve the 'main' instance of a component (Figma's Go to main " +
+    "component). This codebase has no separate component-definition markup " +
+    "— components are structurally duplicated HTML matched by name — so the " +
+    "earliest instance found across the design's files stands in for the " +
+    "main component. Returns isMain=true when the given instance already IS " +
+    "that earliest one; otherwise navigates the editor to it (which may " +
+    "switch design files).",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    nodeId: z
+      .string()
+      .describe("data-agent-native-node-id of the component instance root"),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Design file id the instance currently lives in; defaults to index.html",
+      ),
+  }),
+  run: async ({ designId, nodeId, fileId }) => {
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    const rawData = (access.resource as { data?: unknown }).data;
+    const sourceType = designSourceTypeFromData(rawData);
+
+    if (sourceType !== "inline") {
+      return {
+        designId,
+        nodeId,
+        sourceType,
+        ctaRequired: true,
+        ctaMessage:
+          "Go to main component requires a connected Builder app for " +
+          "real-app sources. Not yet available.",
+        isMain: false,
+        navigated: false,
+      };
+    }
+
+    const db = getDb();
+
+    // ── Resolve the current node + component name ──────────────────────────
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+      fileId
+        ? eq(schema.designFiles.id, fileId)
+        : eq(schema.designFiles.filename, "index.html"),
+    ];
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(and(...conditions))
+      .limit(1);
+
+    if (!file) throw new Error("Design HTML file not found.");
+
+    const currentHtml = await liveContent(file.id, file.content ?? "");
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+    const currentProjection = buildCodeLayerProjection(currentHtml, {
+      source: codeLayerSource,
+    });
+
+    const node = currentProjection.nodes.find((n) =>
+      componentNodeIdMatches(n, nodeId),
+    );
+    if (!node) {
+      throw new Error(
+        `Node "${nodeId}" not found. Run get-code-layer-projection to list current ids.`,
+      );
+    }
+
+    const componentName = componentNameFor(node);
+    if (!componentName) {
+      throw new Error(
+        `Node "${nodeId}" is not a component root (no data-agent-native-component attribute).`,
+      );
+    }
+
+    // ── Scan every design file for instances of this component ─────────────
+    const allFiles = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designFiles.designId, designId),
+          eq(schema.designFiles.fileType, "html"),
+        ),
+      )
+      .orderBy(schema.designFiles.createdAt);
+
+    // Use the freshest content we already read for the current file so the
+    // instance we just resolved (possibly from a live collab doc) matches up
+    // with `node.id` exactly.
+    const filesForScan = allFiles.map((row) =>
+      row.id === file.id ? { ...row, content: currentHtml } : row,
+    );
+
+    const entries = scanComponentLibrary(filesForScan);
+    const matches = entriesForComponent(entries, componentName);
+
+    if (matches.length === 0) {
+      // Shouldn't happen (the current node itself matches), but guard anyway.
+      throw new Error(
+        `No instances of component "${componentName}" found across the design's files.`,
+      );
+    }
+
+    const main = matches[0];
+    // Compare against the caller's own stable `nodeId` param (a durable
+    // data-agent-native-node-id), not `node.id` (an ephemeral id scoped to
+    // this projection call) — `scanComponentLibrary` resolves the same
+    // durable id for every entry, so this is an apples-to-apples comparison.
+    const isMain = main.fileId === file.id && main.nodeId === nodeId;
+
+    if (isMain) {
+      return {
+        designId,
+        nodeId,
+        componentName,
+        sourceType,
+        ctaRequired: false,
+        isMain: true,
+        instanceCount: matches.length,
+        navigated: false,
+        note:
+          matches.length === 1
+            ? `"${componentName}" has only one instance — this is it.`
+            : `This is the earliest instance of "${componentName}" across the design.`,
+      };
+    }
+
+    await writeAppState("navigate", {
+      view: "editor",
+      designId,
+      editorView: "single",
+      fileId: main.fileId,
+      filename: main.filename,
+      selectedNodeId: main.nodeId,
+      inspectorTab: "design",
+      inspectorSection: "component",
+    });
+
+    return {
+      designId,
+      nodeId,
+      componentName,
+      sourceType,
+      ctaRequired: false,
+      isMain: false,
+      instanceCount: matches.length,
+      main: {
+        fileId: main.fileId,
+        filename: main.filename,
+        nodeId: main.nodeId,
+        selector: main.selector,
+      },
+      navigated: true,
+    };
+  },
+});

package/corpus/templates/design/actions/grant-localhost-write-consent.ts

@@ -19,7 +19,7 @@ export default defineAction({
     "for a specific design + localhost connection. The grant scopes writes to the " +
     "connection's rootPath and expires after 8 hours. Requires editor access on the design. " +
     "The LocalhostWriteConsentDialog calls this after the user clicks 'Allow writes'.",
-  // This action mints/returns the real bridgeToken that unlocks the local
+  // This action persists the real bridgeToken that unlocks the local
   // bridge's unrestricted /read-file, /write-file, and /apply-edit. It must
   // only ever be triggered by a human clicking "Allow writes" in
   // LocalhostWriteConsentDialog — never by the agent itself, or an agent
@@ -27,7 +27,9 @@ export default defineAction({
   // human consent model entirely. `agentTool: false` hides it from every
   // agent tool surface (in-app assistant, MCP, A2A) while keeping it
   // callable from the frontend via `callAction` / `useActionMutation` and
-  // the raw `/_agent-native/actions/grant-localhost-write-consent` route.
+  // the raw `/_agent-native/actions/grant-localhost-write-consent` route. The
+  // token intentionally stays server-side: browser callers only need grant
+  // metadata because write-local-file adds bridge authentication itself.
   agentTool: false,
   schema: z.object({
     designId: z.string().describe("Design ID."),
@@ -124,7 +126,6 @@ export default defineAction({
 
     return {
       grantId: existing?.id ?? grantId,
-      bridgeToken,
       rootPath,
       grantedUntil,
     };

package/corpus/templates/design/actions/import-design-source.ts

@@ -2,12 +2,12 @@ import { defineAction } from "@agent-native/core";
 import { assertAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
+import { saveFigmaPasteHtmlFallback } from "../server/lib/figma-paste-fallback.js";
 import {
   normalizeImportedHtmlDocument,
   resolveImportDesignId,
   saveImportedDesignFiles,
 } from "../server/lib/import-design-files.js";
-import { parseVisibleClipboardHtml } from "../server/lib/visible-clipboard-html.js";
 
 const MAX_HTML_IMPORT_BYTES = 2 * 1024 * 1024;
 
@@ -62,38 +62,11 @@ export default defineAction({
       };
     }
 
-    const parsed = parseVisibleClipboardHtml(content);
-    if (!parsed.fallbackHtml) {
-      throw new Error(
-        "No visible HTML was found in the clipboard. Copy a frame, then paste into the canvas.",
-      );
-    }
-    const saved = await saveImportedDesignFiles({
+    return saveFigmaPasteHtmlFallback({
       designId: resolvedDesignId,
-      sourceType: "figma-paste-html",
-      files: [
-        {
-          filename: baseFilename(originalName, "figma-paste"),
-          fileType: "html",
-          content: normalizeImportedHtmlDocument(
-            parsed.fallbackHtml,
-            "visible clipboard HTML",
-          ),
-          source: {
-            sourceType: "figma-paste-html",
-          },
-        },
-      ],
+      clipboardHtml: content,
+      originalName,
     });
-    return {
-      ...saved,
-      stats: {
-        sourceKind: "figma-paste",
-        format: "html",
-        frameCount: saved.files.length,
-        imageCount: 0,
-      },
-    };
   },
   link: ({ result }) => {
     if (!result || typeof result !== "object") return null;

package/corpus/templates/design/actions/import-figma-clipboard.ts

@@ -0,0 +1,134 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  buildFigmaNodeCandidates,
+  extractVisibleTexts,
+  matchFigmaClipboardNodes,
+} from "../server/lib/figma-clipboard-match.js";
+import {
+  buildScreenFilesFromFigmaNodes,
+  fetchFileStructure,
+  fetchFigmaNodes,
+  summarizeFidelity,
+} from "../server/lib/figma-node-import.js";
+import { saveFigmaPasteHtmlFallback } from "../server/lib/figma-paste-fallback.js";
+import { saveImportedDesignFiles } from "../server/lib/import-design-files.js";
+import { parseVisibleClipboardHtml } from "../server/lib/visible-clipboard-html.js";
+import { parseFigmaFileKey } from "../shared/figma-url.js";
+
+const NODE_STRUCTURE_DEPTH = 3;
+
+const CREDENTIAL_MISSING_RE = /credential not configured/i;
+
+const AMBIGUOUS_GUIDANCE =
+  'Couldn\'t confidently match this paste to specific Figma nodes, so nothing was imported from the API. Paste a frame LINK instead (copy the frame in Figma, then "Copy link to selection") for an exact node import — or continue with the clipboard preview below.';
+
+const KEY_MISSING_GUIDANCE =
+  "Connect your Figma access token (Settings > Secrets > Figma access token) to import this paste as exact, editable Figma nodes. Imported from the clipboard preview instead.";
+
+export default defineAction({
+  description:
+    "Import a plain clipboard paste copied from Figma (Cmd+C in Figma, Cmd+V here). Figma's clipboard marker only carries a file key, not node ids, so this heuristically matches the pasted content against the file's top-level frames by name/text and imports exact REST nodes only on a confident match; otherwise it falls back to the lossy visible-HTML preview and reports why. For a guaranteed exact import, use import-figma-frame with a copied frame LINK (which does carry a node id) instead.",
+  schema: z.object({
+    designId: z
+      .string()
+      .optional()
+      .describe("Design id. Defaults to the active editor navigation state."),
+    figmetaFileKey: z
+      .string()
+      .trim()
+      .min(1)
+      .describe(
+        "The fileKey decoded from the clipboard's figmeta marker (see app/lib/figma-clipboard.ts's extractFigmeta).",
+      ),
+    clipboardHtml: z
+      .string()
+      .describe(
+        "The raw clipboard HTML (still containing the hidden figmeta/figbuffer markers) — used both for the legacy visible-HTML fallback and for node-matching against visible text.",
+      ),
+    originalName: z.string().optional(),
+  }),
+  run: async ({ designId, figmetaFileKey, clipboardHtml, originalName }) => {
+    const fileKey = parseFigmaFileKey(figmetaFileKey);
+    if (!fileKey) {
+      throw new Error("The clipboard's Figma file key could not be parsed.");
+    }
+
+    // Legacy fallback text is needed either way: as the actual save payload
+    // when we fall back, and as the "visible text" signal the matcher scores
+    // candidate frames against.
+    const parsedClipboard = parseVisibleClipboardHtml(clipboardHtml);
+    if (!parsedClipboard.fallbackHtml) {
+      throw new Error(
+        "No visible HTML was found in the clipboard. Copy a frame, then paste into the canvas.",
+      );
+    }
+    const clipboardTexts = extractVisibleTexts(parsedClipboard.fallbackHtml);
+
+    let figmaApiKeyMissing = false;
+    let matchStatus: "matched" | "ambiguous" | "none" | "error" = "error";
+
+    try {
+      const document = await fetchFileStructure(fileKey, NODE_STRUCTURE_DEPTH);
+      const candidates = buildFigmaNodeCandidates(document);
+      const matchResult = matchFigmaClipboardNodes(candidates, clipboardTexts);
+      matchStatus = matchResult.status;
+
+      if (matchResult.status === "matched") {
+        const nodeIds = matchResult.matches.map((match) => match.id);
+        const nodesById = await fetchFigmaNodes(fileKey, nodeIds);
+        const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
+          fileKey,
+          nodesById,
+        );
+        const saved = await saveImportedDesignFiles({
+          designId,
+          sourceType: "figma-clipboard-rest",
+          files,
+        });
+        return {
+          ...saved,
+          strategy: "restNodes" as const,
+          figma: {
+            fileKey,
+            nodeIds,
+            matched: matchResult.matches,
+          },
+          fidelityReport: summarizeFidelity(fidelityEntries),
+          guidance:
+            "Review fidelityReport.imageFallbacks for subtrees rendered as PNG and fidelityReport.approximated for properties CSS cannot express exactly.",
+        };
+      }
+    } catch (error) {
+      figmaApiKeyMissing = CREDENTIAL_MISSING_RE.test(
+        error instanceof Error ? error.message : String(error),
+      );
+      if (!figmaApiKeyMissing) {
+        // A real (non-credential) REST failure — network error, revoked
+        // token, file access issue, etc. Still fall back to the honest
+        // clipboard preview rather than losing the paste entirely, but this
+        // isn't a "no confident match" case, so don't claim ambiguity.
+        matchStatus = "error";
+      }
+    }
+
+    const saved = await saveFigmaPasteHtmlFallback({
+      designId,
+      clipboardHtml,
+      originalName,
+    });
+    return {
+      ...saved,
+      strategy: "htmlFallback" as const,
+      figmaApiKeyMissing,
+      matchStatus,
+      figma: { fileKey },
+      guidance: figmaApiKeyMissing
+        ? KEY_MISSING_GUIDANCE
+        : matchStatus === "ambiguous" || matchStatus === "none"
+          ? AMBIGUOUS_GUIDANCE
+          : "Imported the clipboard's visible-HTML preview after a Figma API error. Paste a frame link for an exact import.",
+    };
+  },
+});