@agent-native/core 0.119.0 → 0.119.2

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

@@ -35,6 +35,34 @@ Then implement working code that is cohesive, accessible, responsive, and polish
 
 Default to Apple/Linear-level restraint: make the primary workflow obvious, then remove everything that does not help that workflow right now. A polished UI often has fewer visible controls, fewer borders, fewer labels, and fewer explanatory surfaces than the first reasonable implementation.
 
+### Progressive Disclosure Is A Design Requirement
+
+Treat an all-at-once interface as a defect to fix during design, not as a
+styling preference. Before coding, inventory every piece of content and action
+on the surface, then assign each one to the smallest useful visibility level:
+
+1. **Immediate** — the page title, current state, one primary action, and the
+   compact context needed to choose what to do next.
+2. **Expanded** — the details needed for the selected item or active workflow.
+3. **On demand** — advanced settings, diagnostics, credentials, metadata,
+   destructive actions, documentation, and rarely used tools.
+
+Use single-select accordions or simple disclosure rows for sibling panels when
+the user is choosing one item at a time. Inside an expanded panel, keep another
+layer for independent concerns instead of dumping every form, explanation, and
+secondary action into the first reveal. Prefer one flat panel with alignment,
+dividers, and whitespace over nested cards; provider or product icons should
+not receive decorative borders or containers unless the container communicates
+state or interaction. A collapsed row should still show the item name, status,
+and a concise summary so the user can scan the whole surface without opening
+everything.
+
+Before shipping, ask: “What can disappear until the user asks for it?” Then
+verify collapsed, expanded, loading, empty, error, and narrow-width states.
+If the first viewport contains multiple forms, repeated explanatory copy,
+documentation links, and controls for unrelated tasks, the surface has not
+passed this requirement yet.
+
 - **Start by subtracting**: Before adding a visible control, banner, toolbar row, card, or explanatory block, ask what can be removed, merged, renamed, or moved into an existing affordance.
 - **One primary action**: Each surface should have one dominant next action. Secondary actions belong in menus, popovers, command palettes, disclosure rows, or contextual hover/focus states unless they are used constantly.
 - **Progressively disclose rare work**: Advanced options, diagnostics, metadata, settings, import/export, destructive actions, and inspection tools should stay tucked away until requested. Prefer small icon triggers with tooltips, popovers, drawers, or detail panels over permanent chrome.

package/corpus/templates/design/AGENTS.md

@@ -109,8 +109,11 @@ ladder.
   `design-systems` skill's "Import from Figma" section.
 - Uploading a raw `.fig` file in the Design editor's Import panel decodes the
   container/Kiwi document locally into editable screens — no Builder
-  connection needed — and is scoped to screens only; it never creates or
-  updates a design system. This is separate from uploading `.fig` on the
+  connection needed — and accepts an optional Figma frame URL alongside the
+  file. When the URL contains a `node-id`, only that frame or its containing
+  top-level frame is imported; a mismatch falls back to all frames. This path
+  uses no Figma REST API quota and is scoped to screens only; it never creates
+  or updates a design system. This is separate from uploading `.fig` on the
   Design System Setup page, which still indexes tokens/brand-kit data through
   Builder and does not parse `.fig` locally. See the `design-systems` skill
   for both paths.
@@ -118,9 +121,19 @@ ladder.
   `figmeta.selectedNodeData`; `import-figma-clipboard` uses those before any
   heuristic matching and supports multi-selection. Clipboard metadata is not a
   public Figma contract, so a copied frame link remains the stable exact path
-  if Figma changes that field. Without a token, current Figma's binary-only
-  clipboard has no browser-readable HTML fallback; give setup guidance instead
-  of claiming a successful import.
+  if Figma changes that field. Without a token, `import-figma-clipboard` falls
+  back to a local Kiwi binary decode: geometry, auto-layout, text, solid fills,
+  and strokes are editable immediately; image fills become annotated
+  placeholders (`data-figma-image-ref="<sha1>"`) that can be filled in later two
+  ways. (1) Token-free: upload the original `.fig` — the paste-result dialog's
+  "Fill images from .fig" option, or `hydrateFileIds` on the `.fig` upload route
+  (`/api/import-design-file`) — which matches each placeholder's SHA-1 hash to
+  the `.fig`'s embedded `images/` bytes, mirrors them to durable storage, and
+  needs no Figma API. (2) With a token: `hydrate-figma-paste-images` resolves the
+  same placeholders through Figma's REST image endpoint. This is not a
+  full-fidelity import — report which image fills are still unresolved and offer
+  to hydrate them. Clipboard paste is the fast no-quota path; the original `.fig`
+  is what carries the real image bytes for both upload and paste-hydration.
 - For "what's in this Figma file/frame?" or "show me a screenshot of this
   frame" without importing anything, use `get-figma-design-context` — no
   `nodeId` lists pages/top-level frames (like the official Figma MCP's

package/corpus/templates/design/FIGMA_INTEROPERABILITY.md

@@ -15,18 +15,19 @@ product must report them instead of claiming success.
 
 ## Capability matrix
 
-| Workflow or feature          | Current behavior                                                                                                                                                                                                   | Fidelity                                                                                                                                                         | Required verification                                                                               |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| Figma frame URL / file key   | Reads the exact node through `file_content:read`, converts it to a new Design screen, mirrors expiring images into durable storage, and returns a per-node fidelity report.                                        | Mixed; see node matrix below.                                                                                                                                    | REST fixture, authenticated file, screenshot comparison.                                            |
-| Figma URL without a node id  | Imports the first top-level object on the first page. A specific frame URL is recommended for deterministic results.                                                                                               | Same as node import.                                                                                                                                             | Multi-page and empty-page fixtures.                                                                 |
-| Figma branch URL             | Uses the branch key and imports that branch's node.                                                                                                                                                                | Same as node import.                                                                                                                                             | Main/branch pair with divergent content.                                                            |
-| Figma clipboard to Design    | Uses private `figmeta.selectedNodeData` ids when present, then the same REST converter. Older visible HTML is only a fallback. Binary-only clipboard data without ids/token is not decoded.                        | Exact selection identity while Figma's private metadata shape remains compatible; node fidelity is mixed.                                                        | Real Chrome copy from single, multi, nested, and 100+ node selections.                              |
-| `.fig` upload                | Bounded best-effort decoding of known Kiwi/ZIP variants into editable HTML. Embedded images are moved to durable storage.                                                                                          | Experimental. The format is proprietary and has no compatibility guarantee.                                                                                      | Corpus of real files from multiple Figma versions; never only generated containers.                 |
-| Design to Figma clipboard    | Copies an SVG built from the live rendered DOM. Figma imports supported SVG primitives as editable layers.                                                                                                         | Visual/vector handoff, not a native semantic round trip. Auto layout, variables, components, prototypes, HTML state, and code identity are not recreated by SVG. | Paste into real Figma and inspect layer types, text, images, effects, clipping, and bounds.         |
-| Design SVG download          | Same conversion as clipboard, with a server-render fallback when a live DOM is unavailable.                                                                                                                        | Same SVG limits; the export report lists approximations and omissions.                                                                                           | Live and server paths, selected layer and whole screen.                                             |
-| Native Design to Figma write | Use Figma's official MCP `use_figma` write-to-canvas path when the connected client/account supports it.                                                                                                           | Native Figma structures, subject to Figma MCP beta limitations and permissions.                                                                                  | Full-seat/edit-permission account and a real destination file.                                      |
-| `.fig` download              | Not supported. There is no documented public `.fig` authoring contract.                                                                                                                                            | Unsupported.                                                                                                                                                     | Do not label SVG/ZIP as `.fig`.                                                                     |
-| Open-ended Figma chat        | Provider catalog/docs/request expose the REST surface allowed by the user's scoped token; non-read calls require approval. Native canvas authoring requires official Figma MCP, not a personal access token alone. | Endpoint-dependent.                                                                                                                                              | Read scopes, expired/revoked token, rate limiting, Enterprise-variable permissions, MCP connection. |
+| Workflow or feature          | Current behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Fidelity                                                                                                                                                                                                   | Required verification                                                                                                                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Figma frame URL / file key   | Reads the exact node through `file_content:read`, converts it to a new Design screen, mirrors expiring images into durable storage, and returns a per-node fidelity report.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Mixed; see node matrix below.                                                                                                                                                                              | REST fixture, authenticated file, screenshot comparison.                                                                                                                                 |
+| Figma URL without a node id  | Imports the first top-level object on the first page. A specific frame URL is recommended for deterministic results.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Same as node import.                                                                                                                                                                                       | Multi-page and empty-page fixtures.                                                                                                                                                      |
+| Figma branch URL             | Uses the branch key and imports that branch's node.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Same as node import.                                                                                                                                                                                       | Main/branch pair with divergent content.                                                                                                                                                 |
+| Figma clipboard to Design    | Uses private `figmeta.selectedNodeData` ids when present, then the same REST converter. With a token: full fidelity matching `import-figma-frame`. Without a token: local Kiwi binary decode — geometry, auto-layout, text, solid fills, and strokes are editable; image fills are stamped with `data-figma-image-ref="<sha1>"` placeholders and can be resolved retroactively two ways: token-free by uploading the original `.fig` (the paste dialog's "Fill images from .fig" / `hydrateFileIds` on the `.fig` upload route), which matches each placeholder hash to the `.fig`'s embedded image bytes; or with a token via `hydrate-figma-paste-images`. | Exact selection identity while Figma's private metadata shape remains compatible; node fidelity is mixed. No-token imports resolve images retroactively — from the `.fig` (no quota) or a connected token. | Real Chrome copy from single, multi, nested, and 100+ node selections; token-less copy followed by `.fig` hydration and by deferred token connect, verifying image resolution both ways. |
+| `.fig` upload                | Bounded best-effort decoding of known Kiwi/ZIP variants into editable HTML. Embedded images are moved to durable storage. Optionally accepts a Figma frame URL: when its `node-id` matches the decoded file, Design imports only that top-level frame (or its ancestor for a nested node); a mismatch imports all frames with a warning. No Figma REST API calls are made.                                                                                                                                                                                                                                                                                   | Experimental. The format is proprietary and has no compatibility guarantee.                                                                                                                                | Corpus of real files from multiple Figma versions; never only generated containers.                                                                                                      |
+| `.fig` upload + frame URL    | Accepts an optional Figma frame link. Normalizes the node-id and matches the decoded .fig GUID (`sessionID:localID`) to the matching top-level frame. Nested node IDs resolve to their top-level frame. On mismatch, all frames are imported. No Figma API quota is used.                                                                                                                                                                                                                                                                                                                                                                                    | Best-effort. The GUID mapping is reliable for frames in the same file but undocumented — test with real files before relying on it.                                                                        | Real .fig/frame-link pairs from Figma across file versions.                                                                                                                              |
+| Design to Figma clipboard    | Copies an SVG built from the live rendered DOM. Figma imports supported SVG primitives as editable layers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Visual/vector handoff, not a native semantic round trip. Auto layout, variables, components, prototypes, HTML state, and code identity are not recreated by SVG.                                           | Paste into real Figma and inspect layer types, text, images, effects, clipping, and bounds.                                                                                              |
+| Design SVG download          | Same conversion as clipboard, with a server-render fallback when a live DOM is unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Same SVG limits; the export report lists approximations and omissions.                                                                                                                                     | Live and server paths, selected layer and whole screen.                                                                                                                                  |
+| Native Design to Figma write | Use Figma's official MCP `use_figma` write-to-canvas path when the connected client/account supports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Native Figma structures, subject to Figma MCP beta limitations and permissions.                                                                                                                            | Full-seat/edit-permission account and a real destination file.                                                                                                                           |
+| `.fig` download              | Not supported. There is no documented public `.fig` authoring contract.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Unsupported.                                                                                                                                                                                               | Do not label SVG/ZIP as `.fig`.                                                                                                                                                          |
+| Open-ended Figma chat        | Provider catalog/docs/request expose the REST surface allowed by the user's scoped token; non-read calls require approval. Native canvas authoring requires official Figma MCP, not a personal access token alone.                                                                                                                                                                                                                                                                                                                                                                                                                                           | Endpoint-dependent.                                                                                                                                                                                        | Read scopes, expired/revoked token, rate limiting, Enterprise-variable permissions, MCP connection.                                                                                      |
 
 ## REST node conversion matrix
 
@@ -54,6 +55,18 @@ product must report them instead of claiming success.
 | Videos, emoji paints, FigJam-only and unknown node types                   | Rendered fallback when Figma can render the node.                                                                                                    | Visual fallback only.                                                                                                                                                                                                    |
 | Hidden or 0%-opacity subtrees                                              | Omitted without downloading their assets.                                                                                                            | Visually exact and avoids unnecessary work.                                                                                                                                                                              |
 
+## Figma REST rate limits
+
+- Viewer and Collab seats may receive up to 6 Tier 1 requests per month for
+  file, node, and image endpoints. The actual limit may be lower.
+- Dev and Full seats receive 10–20 Tier 1 requests per minute, depending on the
+  resource's plan.
+- On HTTP 429, Figma returns `Retry-After` in seconds plus
+  `X-Figma-Plan-Tier`, `X-Figma-Rate-Limit-Type`, and
+  `X-Figma-Upgrade-Link` metadata.
+- Figma does not expose a requests-remaining counter.
+- Clipboard paste and `.fig` upload are zero-quota local alternatives.
+
 ## Safety and scale limits
 
 - REST responses are capped at 4 MB. Multi-selection requests split

package/corpus/templates/design/actions/hydrate-figma-paste-images.ts

@@ -0,0 +1,115 @@
+/**
+ * Retroactively resolve unresolved Figma image fills for a screen that was
+ * imported via the local-kiwi clipboard path, using Figma's REST image
+ * endpoint (requires a saved FIGMA_ACCESS_TOKEN).
+ *
+ * When a Figma paste is imported without an access token, IMAGE fills render as
+ * `url("about:blank")` placeholders. The originating elements are annotated
+ * with `data-figma-image-ref="hash1 hash2 …"` so this action can find them
+ * without a full re-parse. Each Nth hash in the attribute maps to the Nth
+ * `url("about:blank")` occurrence in the element's style attribute.
+ *
+ * The read → collect → resolve → persist pipeline lives in
+ * `server/lib/figma-image-hydration.ts` and is shared with the token-free
+ * `.fig` hydration path (see `hydrateFileImagesFromFig`). This action only
+ * supplies the REST resolver.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  applyHydration,
+  collectImageRefHashes,
+  hydrateImageRefsInHtml,
+  loadHydratableFile,
+} from "../server/lib/figma-image-hydration.js";
+import { resolveImageFillRefs } from "../server/lib/figma-node-import.js";
+import { readLiveSourceFile } from "../server/source-workspace.js";
+
+// Re-exported for direct unit testing of the pure HTML helpers.
+export { collectImageRefHashes, hydrateImageRefsInHtml };
+
+export default defineAction({
+  description:
+    'Retroactively resolve unresolved Figma image fills for a screen imported via the no-token local-kiwi path (import-figma-clipboard returned strategy:"localKiwi"). Requires a saved FIGMA_ACCESS_TOKEN. Fetches CDN URLs from Figma\'s /files/:key/images endpoint, mirrors them to durable blob storage, and replaces every url("about:blank") placeholder stamped by the local-kiwi decoder with the real durable URL. Fully resolved elements have their data-figma-image-ref annotation removed; partially resolved elements retain it for a future retry. Returns resolved/missing/skipped counts. Call after connecting Figma in Settings to fill in images from a no-token paste. For a token-free path when the original .fig file is available, upload the .fig with hydrateFileIds via /api/import-design-file instead.',
+  schema: z.object({
+    fileId: z
+      .string()
+      .describe(
+        "ID of the design_files row to hydrate. Use the fileId returned by import-figma-clipboard.",
+      ),
+  }),
+  run: async ({ fileId }) => {
+    const { workspaceFile, designId, figmaFileKey } =
+      await loadHydratableFile(fileId);
+
+    if (!figmaFileKey) {
+      throw new Error(
+        `No Figma file key found for file ${fileId}. This file may not have been imported via a Figma clipboard paste.`,
+      );
+    }
+
+    const live = await readLiveSourceFile(workspaceFile);
+
+    const hashesToResolve = collectImageRefHashes(live.content);
+    if (hashesToResolve.length === 0) {
+      return {
+        fileId,
+        resolved: 0,
+        missing: 0,
+        skipped: 0,
+        message: "No unresolved image refs found in this file.",
+      };
+    }
+
+    let resolvedUrls: Map<string, string>;
+    try {
+      resolvedUrls = await resolveImageFillRefs(figmaFileKey, hashesToResolve);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/quota cooldown|provider.*quota/i.test(msg)) {
+        const retryAfterSeconds =
+          (err as { retryAfterSeconds?: number }).retryAfterSeconds ?? 0;
+        const waitHint =
+          retryAfterSeconds > 0
+            ? retryAfterSeconds >= 60
+              ? `${Math.ceil(retryAfterSeconds / 60)} min`
+              : `${retryAfterSeconds}s`
+            : "~1 min";
+        throw Object.assign(
+          new Error(`Figma API rate limited — try again in ${waitHint}.`),
+          { statusCode: 429 },
+        );
+      }
+      throw err;
+    }
+
+    if (resolvedUrls.size === 0) {
+      return {
+        fileId,
+        resolved: 0,
+        missing: hashesToResolve.length,
+        skipped: 0,
+        message: `Figma returned no image URLs for ${hashesToResolve.length} hash${hashesToResolve.length === 1 ? "" : "es"}. The images may have been deleted from the Figma file or the access token lacks file_content:read scope.`,
+      };
+    }
+
+    const result = await applyHydration({
+      file: workspaceFile,
+      designId,
+      fileId,
+      liveContent: live.content,
+      liveVersionHash: live.versionHash,
+      requestedHashes: hashesToResolve,
+      resolvedUrls,
+    });
+
+    return {
+      fileId,
+      resolved: result.resolved,
+      missing: result.missing,
+      skipped: result.skipped,
+    };
+  },
+});

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

@@ -1,6 +1,7 @@
 import { defineAction } from "@agent-native/core";
 import { z } from "zod";
 
+import { importFigmaClipboardFromBuffer } from "../server/lib/figma-clipboard-local-decode.js";
 import {
   buildFigmaNodeCandidates,
   extractVisibleTexts,
@@ -19,7 +20,13 @@ import { parseFigmaFileKey } from "../shared/figma-url.js";
 
 const NODE_STRUCTURE_DEPTH = 3;
 
-const CREDENTIAL_MISSING_RE = /credential not configured/i;
+// Also matches a Figma 403 that occurs when the token is saved but lacks
+// file_content:read scope — the validator only checks current_user:read.
+const CREDENTIAL_MISSING_RE =
+  /credential not configured|figma.*request failed:.*403|figma.*request failed:.*forbidden/i;
+// Transient errors should not block local-kiwi fallback when the buffer is present.
+const TRANSIENT_ERROR_RE =
+  /quota cooldown|provider.*quota|rate.?limit|fetch failed|network.*error|timeout|ECONNRESET|ENOTFOUND|ERR_NETWORK/i;
 const DURABLE_STORAGE_REQUIRED_RE =
   /authenticated user so assets can be stored durably|could not store a Figma image durably|needs durable file storage/i;
 
@@ -69,6 +76,13 @@ export default defineAction({
       .describe(
         "Figma clipboard HTML used for fallback matching. When exact node ids are present, the client removes the large private data-buffer while retaining figmeta and visible HTML.",
       ),
+    clipboardBuffer: z
+      .string()
+      .max(15_000_000)
+      .optional()
+      .describe(
+        "Base64-encoded fig-kiwi binary from the clipboard's data-buffer. Present when the client used the local-kiwi strategy (no Figma access token). The server decodes this to build editable HTML from geometry, text, and fills without a REST call.",
+      ),
     originalName: z.string().optional(),
   }),
   run: async ({
@@ -77,6 +91,7 @@ export default defineAction({
     selectedNodeIds,
     selectedNodeIdsTruncated,
     clipboardHtml,
+    clipboardBuffer,
     originalName,
   }) => {
     const fileKey = parseFigmaFileKey(figmetaFileKey);
@@ -98,10 +113,8 @@ export default defineAction({
     try {
       if (selectedNodeIds?.length) {
         const nodesById = await fetchFigmaNodes(fileKey, selectedNodeIds);
-        const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
-          fileKey,
-          nodesById,
-        );
+        const { files, fidelityEntries, missingImageFillCount } =
+          await buildScreenFilesFromFigmaNodes(fileKey, nodesById);
         const saved = await saveImportedDesignFiles({
           designId,
           sourceType: "figma-clipboard-rest",
@@ -110,9 +123,15 @@ export default defineAction({
         const selectionWarnings = selectedNodeIdsTruncated
           ? [SELECTION_TRUNCATED_GUIDANCE]
           : [];
+        const fillWarnings =
+          missingImageFillCount > 0
+            ? [
+                `${missingImageFillCount} image fill${missingImageFillCount === 1 ? "" : "s"} could not be fetched from Figma and were omitted. This can happen for deleted images or very large assets.`,
+              ]
+            : [];
         return {
           ...saved,
-          warnings: [...saved.warnings, ...selectionWarnings],
+          warnings: [...saved.warnings, ...selectionWarnings, ...fillWarnings],
           strategy: "restNodes" as const,
           figma: {
             fileKey,
@@ -142,17 +161,22 @@ export default defineAction({
       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 { files, fidelityEntries, missingImageFillCount } =
+          await buildScreenFilesFromFigmaNodes(fileKey, nodesById);
         const saved = await saveImportedDesignFiles({
           designId,
           sourceType: "figma-clipboard-rest",
           files,
         });
+        const fillWarnings =
+          missingImageFillCount > 0
+            ? [
+                `${missingImageFillCount} image fill${missingImageFillCount === 1 ? "" : "s"} could not be fetched from Figma and were omitted.`,
+              ]
+            : [];
         return {
           ...saved,
+          warnings: [...(saved.warnings ?? []), ...fillWarnings],
           strategy: "restNodes" as const,
           figma: {
             fileKey,
@@ -174,26 +198,67 @@ export default defineAction({
         throw error;
       }
       figmaApiKeyMissing = CREDENTIAL_MISSING_RE.test(errorMessage);
+      const isTransient = TRANSIENT_ERROR_RE.test(errorMessage);
       if (
         selectedNodeIds?.length &&
         !parsedClipboard.fallbackHtml &&
-        !figmaApiKeyMissing
+        !figmaApiKeyMissing &&
+        (!isTransient || !clipboardBuffer)
       ) {
         // Exact ids prove this was a current Figma clipboard. With no visible
-        // fallback, a real REST/import failure must remain truthful and
-        // actionable rather than being mislabeled as a clipboard format that
-        // omitted ids.
+        // fallback, a permanent REST failure must surface as a real error rather
+        // than silently degrading. Transient errors fall through to local-kiwi
+        // only when a buffer is present to decode; without a buffer there is
+        // nothing to fall back to, so even transient errors must propagate.
         throw 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";
       }
     }
 
+    // Local-kiwi fallback: decode the binary buffer when REST failed for any
+    // reason (missing token, 403, quota cooldown, network error) and the buffer
+    // is present. Always produces editable geometry, text, and auto-layout.
+    // IMAGE fills land as about:blank placeholders that hydrate-figma-paste-images
+    // resolves retroactively once the quota clears or the token is configured.
+    if ((figmaApiKeyMissing || matchStatus === "error") && clipboardBuffer) {
+      try {
+        const localResult = await importFigmaClipboardFromBuffer({
+          bufferBase64: clipboardBuffer,
+          fileKey,
+          originalName,
+        });
+        if (localResult.files.length > 0) {
+          const saved = await saveImportedDesignFiles({
+            designId,
+            sourceType: "figma-clipboard-local-kiwi",
+            files: localResult.files,
+          });
+          return {
+            ...saved,
+            warnings: [...saved.warnings, ...localResult.warnings],
+            strategy: "localKiwi" as const,
+            figmaApiKeyMissing,
+            figma: { fileKey, selectedNodeIds },
+            unresolvedImages: localResult.unresolvedImageRefs.length,
+            fidelityReport: {
+              exactCount: 0,
+              approximated: [],
+              imageFallbacks: [],
+              unresolvedImages: localResult.unresolvedImageRefs.length,
+            },
+            guidance:
+              localResult.unresolvedImageRefs.length > 0
+                ? `Imported from Figma using local decode — geometry, text, and styles are editable. ${localResult.unresolvedImageRefs.length} image${localResult.unresolvedImageRefs.length === 1 ? "" : "s"} need a Figma access token to load. Connect Figma in Settings to fill them in, or use "Copy as PNG" for individual images.`
+                : "Imported from Figma using local decode — geometry, text, and styles are fully editable. Connect Figma in Settings for highest-fidelity REST imports.",
+          };
+        }
+      } catch {
+        // Local decode failed — fall through to html-fallback below.
+      }
+    }
+
     if (!parsedClipboard.fallbackHtml) {
       return {
         designId,

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

@@ -5,6 +5,7 @@ import { z } from "zod";
 import {
   buildScreenFilesFromFigmaNodes,
   fetchFigmaNode,
+  isFigmaRateLimitError,
   resolveTargetNodeId,
   summarizeFidelity,
 } from "../server/lib/figma-node-import.js";
@@ -78,29 +79,41 @@ export default defineAction({
     const designId = await resolveImportDesignId(args.designId);
     await assertAccess("design", designId, "editor");
 
-    const nodeId = await resolveTargetNodeId(fileKey, requestedNodeId);
-    const rootNode = await fetchFigmaNode(fileKey, nodeId);
+    try {
+      const nodeId = await resolveTargetNodeId(fileKey, requestedNodeId);
+      const rootNode = await fetchFigmaNode(fileKey, nodeId);
 
-    const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
-      fileKey,
-      { [nodeId]: rootNode },
-      {
-        source: () => ({ figmaUrl: args.figmaUrl ?? null }),
-      },
-    );
+      const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
+        fileKey,
+        { [nodeId]: rootNode },
+        {
+          source: () => ({ figmaUrl: args.figmaUrl ?? null }),
+        },
+      );
 
-    const saved = await saveImportedDesignFiles({
-      designId,
-      sourceType: "figma-import",
-      files,
-    });
+      const saved = await saveImportedDesignFiles({
+        designId,
+        sourceType: "figma-import",
+        files,
+      });
 
-    return {
-      ...saved,
-      figma: { fileKey, nodeId, nodeName: rootNode.name ?? null },
-      fidelityReport: summarizeFidelity(fidelityEntries),
-      guidance:
-        "Review fidelityReport.imageFallbacks for subtrees rendered as PNG (masks, vector/boolean geometry, lines/arcs, advanced strokes/text, transformed image crops, and unsupported node types) and fidelityReport.approximated for properties CSS cannot express exactly (rotation, per-side stroke alignment, radial/angular/diamond gradients, blur radius scale, and live component/variable/prototype semantics).",
-    };
+      return {
+        ...saved,
+        figma: { fileKey, nodeId, nodeName: rootNode.name ?? null },
+        fidelityReport: summarizeFidelity(fidelityEntries),
+        guidance:
+          "Review fidelityReport.imageFallbacks for subtrees rendered as PNG (masks, vector/boolean geometry, lines/arcs, advanced strokes/text, transformed image crops, and unsupported node types) and fidelityReport.approximated for properties CSS cannot express exactly (rotation, per-side stroke alignment, radial/angular/diamond gradients, blur radius scale, and live component/variable/prototype semantics).",
+      };
+    } catch (err) {
+      if (isFigmaRateLimitError(err)) {
+        throw Object.assign(err, {
+          rateLimitRetryAfter: err.retryAfterSeconds,
+          rateLimitPlanTier: err.figmaPlanTier,
+          rateLimitType: err.figmaRateLimitType,
+          rateLimitUpgradeUrl: err.figmaUpgradeUrl,
+        });
+      }
+      throw err;
+    }
   },
 });

package/corpus/templates/design/app/components/design/DesignCanvas.tsx

@@ -97,6 +97,7 @@ import type {
   IframeContextMenuPayload,
   IframeFigmaClipboardPastePayload,
   IframeHotkeyPayload,
+  IframeImagePastePayload,
 } from "./design-canvas/iframe-events";
 import {
   forwardEmbeddedCanvasPanMessage,
@@ -473,6 +474,7 @@ interface DesignCanvasProps {
   onElementDblClickText?: (info: ElementInfo) => void;
   onIframeHotkey?: (event: IframeHotkeyPayload) => void;
   onFigmaClipboardPaste?: (event: IframeFigmaClipboardPastePayload) => void;
+  onImagePaste?: (event: IframeImagePastePayload) => void;
   onIframeContextMenu?: (event: IframeContextMenuPayload) => void;
   onEditorDragStateChange?: (active: boolean) => void;
   onVisualStructureChange?: (
@@ -1045,6 +1047,7 @@ export function DesignCanvas({
   onElementDblClickText,
   onIframeHotkey,
   onFigmaClipboardPaste,
+  onImagePaste,
   onIframeContextMenu,
   onEditorDragStateChange,
   onVisualStructureChange,
@@ -2135,6 +2138,7 @@ export function DesignCanvas({
     // static-fallback board thumbnails that call appendHitTestResponder.
     // Without this, a drop onto a live/active screen has no responder and
     // always falls through to the 50ms request timeout.
+    const imageDiagBridge = "";
     const bridgeToInject =
       MOTION_PREVIEW_BRIDGE_SCRIPT +
       SHADER_FILL_PREVIEW_BRIDGE_SCRIPT +
@@ -2143,7 +2147,8 @@ export function DesignCanvas({
       NAV_BRIDGE_SCRIPT +
       LIGHTWEIGHT_HIT_TEST_BRIDGE_SCRIPT +
       embeddedGestureBridgeForCurrentState +
-      editorChromeBridge;
+      editorChromeBridge +
+      imageDiagBridge;
     const frameContent = getEmbeddedFrameDocumentContent({
       content: iframeRenderContent,
       embeddedFrameBackground,
@@ -2687,6 +2692,27 @@ export function DesignCanvas({
         if (content) onFigmaClipboardPaste?.({ content });
         return;
       }
+      if (e.data.type === "canvas-image-paste") {
+        const raw = Array.isArray(e.data.files) ? e.data.files : [];
+        const MAX_IMAGE_PASTE_FILES = 20;
+        const MAX_DATA_URL_BYTES = 20 * 1024 * 1024; // 20 MB per file
+        const files = raw
+          .slice(0, MAX_IMAGE_PASTE_FILES)
+          .filter(
+            (
+              f: unknown,
+            ): f is { dataUrl: string; type: string; name: string } => {
+              if (!f || typeof f !== "object") return false;
+              const dataUrl = (f as { dataUrl?: unknown }).dataUrl;
+              if (typeof dataUrl !== "string") return false;
+              if (!dataUrl.startsWith("data:image/")) return false;
+              if (dataUrl.length > MAX_DATA_URL_BYTES) return false;
+              return true;
+            },
+          );
+        if (files.length > 0) onImagePaste?.({ files });
+        return;
+      }
       if (e.data.type === "element-contextmenu") {
         const clientX = Number(e.data.clientX);
         const clientY = Number(e.data.clientY);
@@ -2879,6 +2905,7 @@ export function DesignCanvas({
     onElementDblClickText,
     onIframeHotkey,
     onFigmaClipboardPaste,
+    onImagePaste,
     onIframeContextMenu,
     onEditorDragStateChange,
     onVisualStructureChange,