@agent-native/core 0.118.1 → 0.119.1

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,

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

@@ -27,6 +27,7 @@ import {
 } from "@/lib/design-file-upload";
 import {
   importResultNotification,
+  isFigmaRateLimitImportError,
   looksLikeStandaloneHtml,
   VISUAL_EDIT_CONNECT_COMMAND,
   VISUAL_EDIT_INSTALL_COMMAND,
@@ -42,6 +43,7 @@ import type { DesignExtensionSlotContext } from "./DesignExtensionsPanel";
 
 interface DesignImportPanelProps {
   context: Pick<DesignExtensionSlotContext, "designId" | "viewMode">;
+  onImport?: (result: ImportResult) => void;
 }
 
 type ImportMode =
@@ -51,7 +53,11 @@ type ImportMode =
   | "html"
   | "local-app";
 
-export function DesignImportPanel({ context }: DesignImportPanelProps) {
+export function DesignImportPanel(p: DesignImportPanelProps) {
+  const context = p.context;
+  const onImport = p.onImport;
+  const onImportRef = useRef(onImport);
+  onImportRef.current = onImport;
   const t = useT();
   const { formatNumber } = useFormatters();
   const navigate = useNavigate();
@@ -77,6 +83,8 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
   const [htmlText, setHtmlText] = useState("");
   const [activeMode, setActiveMode] = useState<ImportMode | null>(null);
   const [lastResult, setLastResult] = useState<ImportResult | null>(null);
+  const [figmaRateLimitError, setFigmaRateLimitError] =
+    useState<ImportResult | null>(null);
   const [figUploadName, setFigUploadName] = useState<string | null>(null);
   const [figUploadProgress, setFigUploadProgress] = useState<number | null>(
     null,
@@ -91,6 +99,7 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
         queryClient.invalidateQueries({ queryKey: ["action", "get-design"] }),
         queryClient.invalidateQueries({ queryKey: ["action"] }),
       ]);
+      if (result) onImportRef.current?.(result);
       const fidelityWarnings: string[] = [];
       const imageFallbackCount = result?.fidelityReport?.imageFallbacks.length;
       if (imageFallbackCount) {
@@ -190,6 +199,7 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
     figmaConnectionChecked && !figmaConnected && !figmaConnectionError;
 
   const handleFigmaUrlImport = useCallback(async () => {
+    setFigmaRateLimitError(null);
     const normalizedUrl = figmaUrl.trim();
     if (!normalizedUrl) {
       toast.error(t("designEditor.import.errors.figmaUrlRequired"));
@@ -218,9 +228,41 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
         asNewScreen: true,
       })) as ImportResult;
       await finishImport(result, t("designEditor.import.figmaUrlSuccess"));
+      setFigmaRateLimitError(null);
     } catch (error) {
       // A rejected credential should not linger in component state or the DOM.
       setFigmaAccessToken("");
+      const rateLimitDetails = error as Error & {
+        rateLimitRetryAfter?: number;
+        rateLimitPlanTier?: string;
+        figmaPlanTier?: string;
+        rateLimitType?: string;
+        figmaRateLimitType?: string;
+        rateLimitUpgradeUrl?: string;
+        figmaUpgradeUrl?: string;
+      };
+      const rateLimitResult: ImportResult = {
+        error:
+          typeof rateLimitDetails.message === "string"
+            ? rateLimitDetails.message
+            : t("common.genericError"),
+        rateLimitRetryAfter: rateLimitDetails.rateLimitRetryAfter,
+        rateLimitPlanTier:
+          rateLimitDetails.rateLimitPlanTier ?? rateLimitDetails.figmaPlanTier,
+        rateLimitType:
+          rateLimitDetails.rateLimitType ?? rateLimitDetails.figmaRateLimitType,
+        rateLimitUpgradeUrl:
+          rateLimitDetails.rateLimitUpgradeUrl ??
+          rateLimitDetails.figmaUpgradeUrl,
+      };
+      const isRateLimitError =
+        (error instanceof Error &&
+          /rate limit|429|quota/i.test(error.message)) ||
+        isFigmaRateLimitImportError(rateLimitResult);
+      if (isRateLimitError) {
+        setFigmaRateLimitError(rateLimitResult);
+        setActiveMode("fig-upload");
+      }
       toast.error(t("designEditor.import.errors.figmaImportFailed"), {
         description:
           error instanceof Error ? error.message : t("common.genericError"),
@@ -282,6 +324,7 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
           onProgress: ({ percent }) => setFigUploadProgress(percent),
         });
         await finishImport(result, t("designEditor.import.uploadSuccess"));
+        setFigmaRateLimitError(null);
       } catch (error) {
         toast.error(t("designEditor.import.errors.uploadFailed"), {
           description:
@@ -325,6 +368,64 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
 
       <div className="design-inspector-scroll min-h-0 flex-1 overflow-y-auto overscroll-contain px-3 pb-4 pt-3">
         <div className="space-y-0.5">
+          {figmaRateLimitError ? (
+            <div className="space-y-2 rounded-md border border-destructive/30 bg-destructive/5 p-2.5 text-[11px] leading-snug">
+              <p className="font-medium text-destructive">
+                {t("designEditor.import.rateLimitTitle")}
+              </p>
+              <p className="text-muted-foreground">
+                {figmaRateLimitError.rateLimitType === "low"
+                  ? t("designEditor.import.rateLimitLowSeat")
+                  : t("designEditor.import.rateLimitGeneric")}
+              </p>
+              {figmaRateLimitError.rateLimitRetryAfter ? (
+                <p className="text-muted-foreground">
+                  {t("designEditor.import.rateLimitRetryIn", {
+                    time:
+                      figmaRateLimitError.rateLimitRetryAfter >= 60
+                        ? `${Math.ceil(figmaRateLimitError.rateLimitRetryAfter / 60)} min`
+                        : `${figmaRateLimitError.rateLimitRetryAfter}s`,
+                  })}
+                </p>
+              ) : null}
+              <div className="flex flex-col gap-1.5">
+                <p className="text-[10px] font-medium text-muted-foreground">
+                  {t("designEditor.import.rateLimitAlternatives")}
+                </p>
+                <Button
+                  size="sm"
+                  variant="outline"
+                  className="h-7 w-full px-2 text-[11px]"
+                  onClick={() => {
+                    setFigmaRateLimitError(null);
+                    setActiveMode("figma-paste");
+                  }}
+                >
+                  {t("designEditor.import.rateLimitUsePaste")}
+                </Button>
+                <Button
+                  size="sm"
+                  variant="outline"
+                  className="h-7 w-full px-2 text-[11px]"
+                  onClick={() => {
+                    setActiveMode("fig-upload");
+                  }}
+                >
+                  {t("designEditor.import.rateLimitUseFig")}
+                </Button>
+              </div>
+              {figmaRateLimitError.rateLimitUpgradeUrl ? (
+                <a
+                  href={figmaRateLimitError.rateLimitUpgradeUrl}
+                  target="_blank"
+                  rel="noreferrer"
+                  className="block text-[10px] text-foreground underline-offset-2 hover:underline"
+                >
+                  {t("designEditor.import.rateLimitUpgrade")}
+                </a>
+              ) : null}
+            </div>
+          ) : null}
           <ImportSourceRow
             id="figma-url-import"
             icon={<IconBrandFigma className="size-3.5" />}
@@ -437,9 +538,7 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
             id="figma-paste-import"
             icon={<IconBrandFigma className="size-3.5" />}
             title={t("designEditor.import.figmaPasteTitle")}
-            description={
-              "Copy a frame in Figma, then paste into the canvas." /* i18n-ignore */
-            }
+            description={t("designEditor.import.figmaPasteDescription")}
             isOpen={activeMode === "figma-paste"}
             onToggle={() =>
               setActiveMode((mode) =>
@@ -448,12 +547,8 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
             }
           >
             <div className="space-y-1.5 p-2 text-[11px] leading-snug text-muted-foreground">
-              <p>{t("designEditor.import.figmaPasteDescription")}</p>
-              <p>
-                {
-                  "Click the canvas first, then paste with the same shortcut you use for copied Design content." /* i18n-ignore */
-                }
-              </p>
+              <p>{t("designEditor.import.figmaPasteBodyUnlimited")}</p>
+              <p>{t("designEditor.import.figmaPasteBodyImages")}</p>
             </div>
           </ImportSourceRow>
 
@@ -461,7 +556,7 @@ export function DesignImportPanel({ context }: DesignImportPanelProps) {
             id="fig-file-import"
             icon={<IconUpload className="size-3.5" />}
             title={t("designEditor.import.figUploadTitle")}
-            description={t("designEditor.import.figUploadDescription")}
+            description={t("designEditor.import.figUploadDescriptionShort")}
             isOpen={activeMode === "fig-upload"}
             onToggle={() =>
               setActiveMode((mode) =>