@agent-native/core 0.119.0 → 0.119.1

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

@@ -568,7 +568,7 @@ const enUS = {
       figmaTokenDocs: "Get a token",
       figmaTokenPlaceholder: "Paste your Figma personal access token",
       figmaTokenDescription:
-        "Saved securely for Figma imports and agent chat. The token is never added to chat.",
+        'Needs "File content" and "Current user" scopes. Saved securely — never added to chat.',
       importFigmaUrl: "Import from Figma",
       saveKeyAndImport: "Save key and import",
       figmaUrlSuccess: "Imported from Figma.",
@@ -586,12 +586,53 @@ const enUS = {
         "Couldn't match this to specific Figma nodes. Paste a frame link instead for an exact import.",
       figmaPasteRestLabel: "Imported via Figma API",
       figmaPasteHtmlLabel: "Imported from clipboard preview",
+      figmaPasteLocalKiwiLabel:
+        "Imported without token — geometry and text only",
+      figmaPasteImagesNeedToken:
+        "{{count}} image{{plural}} need Figma access to load.",
+      figmaHydrationDialogTitle: "Fill in the missing images",
+      figmaHydrationDialogDescription:
+        "{{count}} image{{plural}} in the imported screen{{screensPlural}} couldn't come through the paste — Figma's clipboard leaves image data out. Fill from the original .fig, or fetch the exact images from the copied frame.",
+      figmaHydrationConnectAndLoad: "Connect & fetch images",
+      figmaHydrationSuccess: "Images loaded successfully",
+      figmaHydrationSuccessDescription:
+        "{{count}} image{{plural}} filled in from Figma.",
+      figmaHydrationRecommended: "Recommended",
+      figmaHydrationFigTitle: "Have the original .fig file?",
+      figmaHydrationFigOption:
+        "Fastest — pulls every image straight from the file. No token, no rate limits.",
+      figmaHydrationChooseFig: "Fill images from .fig",
+      figmaHydrationOrToken: "Or fetch from Figma",
+      figmaHydrationTokenDescription:
+        'Fetches the exact images from the copied frame\'s Figma file. Needs "File content" and "Current user" scopes; saved securely, never shown in chat.',
+      figmaHydrationRateLimit:
+        "Figma rate-limits its API by seat — Viewer/Collab seats get only a few requests, Dev/Full seats more. If it's cooling down, use the .fig above.",
+      figmaHydrationFigSuccessDescription:
+        "{{count}} image{{plural}} filled in from the .fig file.",
+      figmaHydrationInvalidFig: "Choose a .fig file exported from Figma.",
+      figmaHydrationFigError: "Couldn't read images from that .fig file.",
       figUploadTitle: "Upload .fig",
       figUploadDescription:
-        "Experimental: Figma's .fig format is proprietary and may change. Supported layers become editable screens; some features may differ. Maximum 50 MB.",
+        "Local import using Figma's .fig format — no API quota. Embedded images are included. Format may change between Figma versions. Maximum 50 MB.",
       chooseFigFile: "Choose .fig file",
       figUploadUploading: "Uploading {{progress}}%",
       figUploadProcessing: "Converting…",
+      figUploadDescriptionShort:
+        "Local import — no Figma API quota used. Embedded images included.",
+      figmaPasteBodyUnlimited:
+        "Works without a Figma token — geometry, layout, and text import immediately.",
+      figmaPasteBodyImages:
+        "Image fills may be missing without a token. Upload the .fig file to include embedded images.",
+      rateLimitTitle: "Figma paused this import",
+      rateLimitLowSeat:
+        "Your seat type (Viewer/Collab) has a limited Figma API quota for file imports — up to 6 requests per month per the official Figma docs.",
+      rateLimitGeneric:
+        "Figma rate-limited this import. The quota resets automatically.",
+      rateLimitRetryIn: "Try again in {{time}}.",
+      rateLimitAlternatives: "No-quota alternatives:",
+      rateLimitUsePaste: "Paste from Figma — unlimited",
+      rateLimitUseFig: "Upload .fig — unlimited",
+      rateLimitUpgrade: "View Figma plan options →",
       htmlTitle: "Import HTML",
       htmlDescription:
         "Paste or upload standalone HTML. Design stores it as a new screen without injecting it into this editor UI.",
@@ -11781,6 +11822,16 @@ const designImportOverrides = {
           "無法比對到特定的 Figma 節點。請改貼上畫框連結以進行精確匯入。",
         figmaPasteRestLabel: "透過 Figma API 匯入",
         figmaPasteHtmlLabel: "從剪貼簿預覽匯入",
+        figmaPasteLocalKiwiLabel: "已在未登入狀態下匯入 — 僅含幾何與文字",
+        figmaPasteImagesNeedToken:
+          "{{count}} 個圖片{{plural}}需要 Figma 存取權才能載入。",
+        figmaHydrationDialogTitle: "連結 Figma 以載入圖片",
+        figmaHydrationDialogDescription:
+          "輸入您的 Figma 存取權杖，以載入已匯入螢幕{{screensPlural}}中 {{count}} 個缺少的圖片{{plural}}。",
+        figmaHydrationConnectAndLoad: "連結並載入圖片",
+        figmaHydrationSuccess: "圖片載入成功",
+        figmaHydrationSuccessDescription:
+          "已從 Figma 填入 {{count}} 個圖片{{plural}}。",
         figUploadTitle: "上傳 .fig",
         figUploadDescription:
           "實驗性功能：Figma 的 .fig 格式為專有格式且可能變更。支援的圖層會轉為可編輯螢幕，部分功能可能不同。上限為 50 MB。",
@@ -11834,6 +11885,16 @@ const designImportOverrides = {
           "无法匹配到特定的 Figma 节点。请改为粘贴画框链接以进行精确导入。",
         figmaPasteRestLabel: "通过 Figma API 导入",
         figmaPasteHtmlLabel: "从剪贴板预览导入",
+        figmaPasteLocalKiwiLabel: "已在未登录状态下导入 — 仅包含几何与文字",
+        figmaPasteImagesNeedToken:
+          "{{count}} 张图片{{plural}}需要 Figma 访问权限才能加载。",
+        figmaHydrationDialogTitle: "连接 Figma 以加载图片",
+        figmaHydrationDialogDescription:
+          "输入您的 Figma 访问令牌，以加载已导入屏幕{{screensPlural}}中缺少的 {{count}} 张图片{{plural}}。",
+        figmaHydrationConnectAndLoad: "连接并加载图片",
+        figmaHydrationSuccess: "图片加载成功",
+        figmaHydrationSuccessDescription:
+          "已从 Figma 填入 {{count}} 张图片{{plural}}。",
         figUploadTitle: "上传 .fig",
         figUploadDescription:
           "实验性功能：Figma 的 .fig 格式为专有格式且可能变化。支持的图层会转换为可编辑屏幕，部分功能可能有所不同。最大 50 MB。",
@@ -11889,6 +11950,17 @@ const designImportOverrides = {
           "No se pudo hacer coincidir con nodos específicos de Figma. Pega un enlace de marco para una importación exacta.",
         figmaPasteRestLabel: "Importado mediante la API de Figma",
         figmaPasteHtmlLabel: "Importado desde la vista previa del portapapeles",
+        figmaPasteLocalKiwiLabel:
+          "Importado sin token — solo geometría y texto",
+        figmaPasteImagesNeedToken:
+          "{{count}} imagen{{plural}} necesita{{plural}} acceso a Figma para cargarse.",
+        figmaHydrationDialogTitle: "Conectar Figma para cargar imágenes",
+        figmaHydrationDialogDescription:
+          "Introduce tu token de acceso de Figma para cargar {{count}} imagen{{plural}} faltante{{plural}} en la pantalla{{screensPlural}} importada{{screensPlural}}.",
+        figmaHydrationConnectAndLoad: "Conectar y cargar imágenes",
+        figmaHydrationSuccess: "Imágenes cargadas correctamente",
+        figmaHydrationSuccessDescription:
+          "{{count}} imagen{{plural}} rellenada{{plural}} desde Figma.",
         figUploadTitle: "Subir .fig",
         figUploadDescription:
           "Experimental: el formato .fig de Figma es propietario y puede cambiar. Las capas compatibles se convierten en pantallas editables; algunas funciones pueden variar. Máximo 50 MB.",
@@ -11946,6 +12018,17 @@ const designImportOverrides = {
           "Impossible de faire correspondre à des nœuds Figma précis. Collez un lien de cadre pour un import exact.",
         figmaPasteRestLabel: "Importé via l'API Figma",
         figmaPasteHtmlLabel: "Importé depuis l'aperçu du presse-papiers",
+        figmaPasteLocalKiwiLabel:
+          "Importé sans token — géométrie et texte uniquement",
+        figmaPasteImagesNeedToken:
+          "{{count}} image{{plural}} nécessite{{plural}} un accès Figma pour être chargée{{plural}}.",
+        figmaHydrationDialogTitle: "Connecter Figma pour charger les images",
+        figmaHydrationDialogDescription:
+          "Saisissez votre token d'accès Figma pour charger {{count}} image{{plural}} manquante{{plural}} dans l'écran{{screensPlural}} importé{{screensPlural}}.",
+        figmaHydrationConnectAndLoad: "Connecter et charger les images",
+        figmaHydrationSuccess: "Images chargées avec succès",
+        figmaHydrationSuccessDescription:
+          "{{count}} image{{plural}} remplie{{plural}} depuis Figma.",
         figUploadTitle: "Téléverser .fig",
         figUploadDescription:
           "Expérimental : le format .fig de Figma est propriétaire et peut évoluer. Les calques pris en charge deviennent des écrans modifiables ; certaines fonctions peuvent différer. Maximum 50 Mo.",
@@ -12003,6 +12086,17 @@ const designImportOverrides = {
           "Konnte nicht mit bestimmten Figma-Nodes abgeglichen werden. Füge stattdessen einen Frame-Link für einen exakten Import ein.",
         figmaPasteRestLabel: "Über die Figma-API importiert",
         figmaPasteHtmlLabel: "Aus der Zwischenablage-Vorschau importiert",
+        figmaPasteLocalKiwiLabel:
+          "Ohne Token importiert — nur Geometrie und Text",
+        figmaPasteImagesNeedToken:
+          "{{count}} Bild{{plural}} benötigt{{plural}} Figma-Zugriff zum Laden.",
+        figmaHydrationDialogTitle: "Figma verbinden, um Bilder zu laden",
+        figmaHydrationDialogDescription:
+          "Gib deinen Figma-Zugriffstoken ein, um {{count}} fehlendes{{plural}} Bild{{plural}} in den importierten Screen{{screensPlural}} zu laden.",
+        figmaHydrationConnectAndLoad: "Verbinden und Bilder laden",
+        figmaHydrationSuccess: "Bilder erfolgreich geladen",
+        figmaHydrationSuccessDescription:
+          "{{count}} Bild{{plural}} aus Figma ausgefüllt.",
         figUploadTitle: ".fig hochladen",
         figUploadDescription:
           "Experimentell: Das .fig-Format von Figma ist proprietär und kann sich ändern. Unterstützte Ebenen werden zu bearbeitbaren Screens; einige Funktionen können abweichen. Maximal 50 MB.",
@@ -12059,6 +12153,17 @@ const designImportOverrides = {
           "特定の Figma ノードと一致しませんでした。正確にインポートするにはフレームのリンクを貼り付けてください。",
         figmaPasteRestLabel: "Figma API 経由でインポート",
         figmaPasteHtmlLabel: "クリップボードプレビューからインポート",
+        figmaPasteLocalKiwiLabel:
+          "トークンなしでインポート — ジオメトリとテキストのみ",
+        figmaPasteImagesNeedToken:
+          "{{count}} 枚の画像{{plural}}を読み込むには Figma へのアクセスが必要です。",
+        figmaHydrationDialogTitle: "Figma を接続して画像を読み込む",
+        figmaHydrationDialogDescription:
+          "Figma アクセストークンを入力して、インポートされた画面{{screensPlural}}の不足している {{count}} 枚の画像{{plural}}を読み込んでください。",
+        figmaHydrationConnectAndLoad: "接続して画像を読み込む",
+        figmaHydrationSuccess: "画像の読み込みが完了しました",
+        figmaHydrationSuccessDescription:
+          "Figma から {{count}} 枚の画像{{plural}}が入力されました。",
         figUploadTitle: ".fig をアップロード",
         figUploadDescription:
           "試験的機能：Figma の .fig 形式は独自仕様で、変更される可能性があります。対応レイヤーは編集可能な画面になりますが、一部の機能は異なる場合があります。最大 50 MB。",
@@ -12116,6 +12221,16 @@ const designImportOverrides = {
           "특정 Figma 노드와 일치시킬 수 없습니다. 정확한 가져오기를 위해 프레임 링크를 붙여넣으세요.",
         figmaPasteRestLabel: "Figma API로 가져옴",
         figmaPasteHtmlLabel: "클립보드 미리보기에서 가져옴",
+        figmaPasteLocalKiwiLabel: "토큰 없이 가져옴 — 기하학적 구조와 텍스트만",
+        figmaPasteImagesNeedToken:
+          "{{count}}개의 이미지{{plural}}를 로드하려면 Figma 접근이 필요합니다.",
+        figmaHydrationDialogTitle: "Figma를 연결하여 이미지 로드",
+        figmaHydrationDialogDescription:
+          "Figma 액세스 토큰을 입력하여 가져온 화면{{screensPlural}}의 누락된 이미지 {{count}}개{{plural}}를 로드하세요.",
+        figmaHydrationConnectAndLoad: "연결하고 이미지 로드",
+        figmaHydrationSuccess: "이미지가 성공적으로 로드되었습니다",
+        figmaHydrationSuccessDescription:
+          "Figma에서 {{count}}개의 이미지{{plural}}가 채워졌습니다.",
         figUploadTitle: ".fig 업로드",
         figUploadDescription:
           "실험적 기능: Figma의 .fig 형식은 독점 형식이며 변경될 수 있습니다. 지원되는 레이어는 편집 가능한 화면으로 변환되지만 일부 기능은 다를 수 있습니다. 최대 50MB.",
@@ -12174,6 +12289,17 @@ const designImportOverrides = {
         figmaPasteRestLabel: "Importado via API do Figma",
         figmaPasteHtmlLabel:
           "Importado da pré-visualização da área de transferência",
+        figmaPasteLocalKiwiLabel:
+          "Importado sem token — apenas geometria e texto",
+        figmaPasteImagesNeedToken:
+          "{{count}} imagem{{plural}} precisa{{plural}} de acesso ao Figma para carregar.",
+        figmaHydrationDialogTitle: "Conectar o Figma para carregar imagens",
+        figmaHydrationDialogDescription:
+          "Insira seu token de acesso do Figma para carregar {{count}} imagem{{plural}} ausente{{plural}} na tela{{screensPlural}} importada{{screensPlural}}.",
+        figmaHydrationConnectAndLoad: "Conectar e carregar imagens",
+        figmaHydrationSuccess: "Imagens carregadas com sucesso",
+        figmaHydrationSuccessDescription:
+          "{{count}} imagem{{plural}} preenchida{{plural}} do Figma.",
         figUploadTitle: "Enviar .fig",
         figUploadDescription:
           "Experimental: o formato .fig do Figma é proprietário e pode mudar. As camadas compatíveis viram telas editáveis; alguns recursos podem ser diferentes. Máximo de 50 MB.",
@@ -12231,6 +12357,17 @@ const designImportOverrides = {
           "विशिष्ट Figma नोड्स से मेल नहीं खाया। सटीक आयात के लिए इसके बजाय एक frame लिंक paste करें।",
         figmaPasteRestLabel: "Figma API के ज़रिए आयात किया गया",
         figmaPasteHtmlLabel: "क्लिपबोर्ड पूर्वावलोकन से आयात किया गया",
+        figmaPasteLocalKiwiLabel:
+          "बिना token के आयात किया गया — केवल geometry और text",
+        figmaPasteImagesNeedToken:
+          "{{count}} छवि{{plural}} को लोड करने के लिए Figma की पहुँच चाहिए।",
+        figmaHydrationDialogTitle: "छवियाँ लोड करने के लिए Figma जोड़ें",
+        figmaHydrationDialogDescription:
+          "आयातित screen{{screensPlural}} में {{count}} गायब छवि{{plural}} लोड करने के लिए अपना Figma access token दर्ज करें।",
+        figmaHydrationConnectAndLoad: "जोड़ें और छवियाँ लोड करें",
+        figmaHydrationSuccess: "छवियाँ सफलतापूर्वक लोड हुईं",
+        figmaHydrationSuccessDescription:
+          "Figma से {{count}} छवि{{plural}} भरी गई{{plural}}।",
         figUploadTitle: ".fig अपलोड करें",
         figUploadDescription:
           "प्रायोगिक: Figma का .fig format proprietary है और बदल सकता है। समर्थित layers editable screens बनती हैं; कुछ features अलग हो सकते हैं। अधिकतम 50 MB।",
@@ -12287,6 +12424,17 @@ const designImportOverrides = {
           "تعذّرت المطابقة مع عُقد Figma محددة. الصق رابط الإطار بدلاً من ذلك للحصول على استيراد دقيق.",
         figmaPasteRestLabel: "تم الاستيراد عبر واجهة Figma البرمجية",
         figmaPasteHtmlLabel: "تم الاستيراد من معاينة الحافظة",
+        figmaPasteLocalKiwiLabel:
+          "تم الاستيراد بدون رمز — الأشكال الهندسية والنص فقط",
+        figmaPasteImagesNeedToken:
+          "{{count}} صورة{{plural}} تحتاج إلى الوصول إلى Figma للتحميل.",
+        figmaHydrationDialogTitle: "ربط Figma لتحميل الصور",
+        figmaHydrationDialogDescription:
+          "أدخل رمز الوصول إلى Figma لتحميل {{count}} صورة{{plural}} مفقودة في الشاشة{{screensPlural}} المستوردة.",
+        figmaHydrationConnectAndLoad: "ربط وتحميل الصور",
+        figmaHydrationSuccess: "تم تحميل الصور بنجاح",
+        figmaHydrationSuccessDescription:
+          "تم ملء {{count}} صورة{{plural}} من Figma.",
         figUploadTitle: "رفع .fig",
         figUploadDescription:
           "ميزة تجريبية: تنسيق .fig في Figma مملوك وقد يتغير. تتحول الطبقات المدعومة إلى شاشات قابلة للتحرير، وقد تختلف بعض الميزات. الحد الأقصى 50 ميغابايت.",

package/corpus/templates/design/app/lib/design-file-upload.ts

@@ -85,3 +85,88 @@ export function uploadDesignFile({
     xhr.send(form);
   });
 }
+
+export interface FigHydrationResult extends ImportResult {
+  importKind?: "fig-hydrate";
+  results?: Array<{
+    fileId: string;
+    resolved: number;
+    missing: number;
+    skipped: number;
+  }>;
+  totalResolved?: number;
+  totalMissing?: number;
+}
+
+export interface HydrateImagesFromFigOptions {
+  designId: string;
+  file: File;
+  /** design_files ids from a no-token clipboard paste to fill images for. */
+  fileIds: string[];
+  fallbackErrorMessage: string;
+  onProgress?: (progress: DesignFileUploadProgress) => void;
+}
+
+/**
+ * Token-free image hydration: uploads the original `.fig` and fills the
+ * `about:blank` placeholders left by a no-token clipboard paste with the
+ * `.fig`'s embedded image bytes. Same authenticated multipart route as
+ * `uploadDesignFile`, plus a `hydrateFileIds` field that switches the server
+ * into hydrate mode instead of creating new screens.
+ */
+export function hydrateImagesFromFig({
+  designId,
+  file,
+  fileIds,
+  fallbackErrorMessage,
+  onProgress,
+}: HydrateImagesFromFigOptions): Promise<FigHydrationResult> {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const form = new FormData();
+    form.append("designId", designId);
+    form.append("hydrateFileIds", fileIds.join(","));
+    form.append("file", file, file.name);
+
+    xhr.open(
+      "POST",
+      `/api/import-design-file?designId=${encodeURIComponent(designId)}`,
+      true,
+    );
+    xhr.withCredentials = true;
+    xhr.timeout = 5 * 60 * 1000;
+
+    xhr.upload.addEventListener("progress", (event) => {
+      const total = event.lengthComputable ? event.total : 0;
+      onProgress?.({
+        loaded: event.loaded,
+        total,
+        percent:
+          total > 0
+            ? Math.min(100, Math.round((event.loaded / total) * 100))
+            : null,
+      });
+    });
+
+    xhr.addEventListener("load", () => {
+      void parseUploadResponse<FigHydrationResult>(
+        {
+          ok: xhr.status >= 200 && xhr.status < 300,
+          status: xhr.status,
+          text: async () => xhr.responseText,
+        },
+        fallbackErrorMessage,
+      ).then(resolve, reject);
+    });
+    xhr.addEventListener("error", () =>
+      reject(new Error(fallbackErrorMessage)),
+    );
+    xhr.addEventListener("timeout", () =>
+      reject(new Error(fallbackErrorMessage)),
+    );
+    xhr.addEventListener("abort", () =>
+      reject(new Error(fallbackErrorMessage)),
+    );
+    xhr.send(form);
+  });
+}

package/corpus/templates/design/app/lib/design-import.ts

@@ -27,11 +27,19 @@ export interface ImportResult {
   warnings?: string[];
   error?: string;
   /** Set by import-figma-clipboard: which path actually produced the screen(s). */
-  strategy?: "restNodes" | "htmlFallback";
+  strategy?: "restNodes" | "htmlFallback" | "localKiwi";
   /** Set by import-figma-clipboard when it fell back because no Figma token is configured. */
   figmaApiKeyMissing?: boolean;
+  /** Set by import-figma-clipboard when strategy is "localKiwi": number of IMAGE fills that couldn't be resolved without a Figma token. */
+  unresolvedImages?: number;
+  /** Set by .fig file upload: number of IMAGE fills not in the embedded blobs (need Figma API to resolve). */
+  unresolvedImageRefCount?: number;
   /** Set by import-figma-clipboard when it fell back: why the REST match didn't happen. */
   matchStatus?: "matched" | "ambiguous" | "none" | "error";
+  rateLimitRetryAfter?: number;
+  rateLimitPlanTier?: string;
+  rateLimitType?: string;
+  rateLimitUpgradeUrl?: string;
   fidelityReport?: FigmaFidelityReport;
   guidance?: string;
 }
@@ -42,6 +50,16 @@ export interface ImportResultNotification {
   description?: string;
 }
 
+export function isFigmaRateLimitImportError(
+  result: ImportResult | undefined,
+): boolean {
+  return (
+    (typeof result?.rateLimitRetryAfter === "number" &&
+      result.rateLimitRetryAfter > 0) ||
+    result?.rateLimitType === "low"
+  );
+}
+
 export const VISUAL_EDIT_CONNECT_COMMAND =
   "npx @agent-native/core@latest design connect --url 'http://localhost:<port>' --root . --daemon";
 

package/corpus/templates/design/app/lib/figma-clipboard.ts

@@ -36,6 +36,7 @@ const FIGMA_DATA_BUFFER_ELEMENT_RE =
 const FIGMA_BUFFER_COMMENT_RE = /<!--\s*\(figma\)[\s\S]*?\(\/figma\)\s*-->/gi;
 const ESCAPED_FIGMA_BUFFER_COMMENT_RE =
   /&lt;!--\s*\(figma\)[\s\S]*?\(\/figma\)\s*--&gt;/gi;
+const DATA_BUFFER_ATTR_RE = /\bdata-buffer\s*=\s*(["'])([\s\S]*?)\1/i;
 
 function decodeBase64Json(raw: string): unknown {
   const trimmed = raw.trim();
@@ -112,6 +113,39 @@ export function stripFigmaBinaryClipboardBuffer(html: string): string {
     .replace(ESCAPED_FIGMA_BUFFER_COMMENT_RE, "");
 }
 
+const FIGMA_BUFFER_BASE64_RE = /\(figma\)([A-Za-z0-9+/=\s]+?)\(\/figma\)/i;
+
+/**
+ * Extract the base64-encoded fig-kiwi binary from a Figma clipboard HTML
+ * payload. Returns null when no buffer is present (e.g. the clipboard came
+ * from an older Figma client, a plain-text copy, or the buffer was already
+ * stripped).
+ *
+ * The buffer lives inside a `data-buffer` attribute as an HTML comment:
+ *   `data-buffer="<!--(figma)BASE64(/figma)-->"`
+ * Some variants embed the comment directly in the HTML text instead. Both
+ * are handled defensively.
+ */
+export function extractFigmaBuffer(
+  html: string | null | undefined,
+): string | null {
+  if (!html) return null;
+
+  // Try the data-buffer attribute path first (current Figma clipboard format).
+  const attrMatch = html.match(DATA_BUFFER_ATTR_RE);
+  if (attrMatch?.[2]) {
+    const inner = attrMatch[2];
+    const bufMatch = inner.match(FIGMA_BUFFER_BASE64_RE);
+    if (bufMatch?.[1]) return bufMatch[1].replace(/\s/g, "");
+  }
+
+  // Fall back to a bare (figma) comment anywhere in the HTML.
+  const directMatch = html.match(FIGMA_BUFFER_BASE64_RE);
+  if (directMatch?.[1]) return directMatch[1].replace(/\s/g, "");
+
+  return null;
+}
+
 /**
  * Extracts and decodes the `figmeta` payload from a clipboard's raw HTML (or
  * plain text), if present. Returns `null` for anything that isn't a
@@ -140,31 +174,50 @@ export function extractFigmeta(
   return null;
 }
 
+// Sentinel URL scheme for unresolved Figma image fills in local-kiwi imports.
+// Must start with "about:" so fig-file-to-html's imageUrl() returns it as-is.
+// The fragment carries the hex hash so hydrate-figma-paste-images can replace
+// each occurrence individually.
+export const FIGMA_IMAGE_REF_SENTINEL_PREFIX = "about:blank#figma-image-ref=";
+
+export function figmaImageRefSentinel(hexHash: string): string {
+  return `${FIGMA_IMAGE_REF_SENTINEL_PREFIX}${hexHash}`;
+}
+
 export type FigmaApiKeyStatus = "configured" | "missing" | "unknown";
-export type FigmaPasteStrategy = "rest" | "html-fallback" | "not-figma";
+export type FigmaPasteStrategy =
+  | "rest"
+  | "local-kiwi"
+  | "html-fallback"
+  | "not-figma";
 
 /**
  * Pure decision matrix for what a paste should attempt, given whether it
  * decoded a `figmeta` payload and (if known) whether the Figma access token
  * is configured:
  *
- * - No `figmeta` -> not a Figma paste at all (`"not-figma"`).
- * - `figmeta` present but the key is known-missing -> skip the REST attempt
- *   entirely and go straight to the legacy HTML path (`"html-fallback"`).
- * - `figmeta` present and the key is configured, or its status isn't known
- *   client-side -> attempt the REST import (`"rest"`). The server is the
- *   authority on whether the key actually works; passing `"unknown"` here
- *   just means "try REST, let the server fall back for real if it can't."
+ * - No `figmeta` → not a Figma paste at all (`"not-figma"`).
+ * - `figmeta` present + key known-missing → try local kiwi decode of the
+ *   binary buffer (`"local-kiwi"`). This always produces something editable
+ *   (geometry, text, auto-layout) even without a token; images are left as
+ *   annotated placeholders for retroactive hydration.
+ * - `figmeta` present + key configured (or status unknown) → attempt the
+ *   REST import (`"rest"`). The server is the authority on whether the key
+ *   actually works; `"unknown"` means "try REST, let the server degrade."
  */
 export function decideFigmaPasteStrategy(
   figmeta: FigmetaPayload | null,
   apiKeyStatus: FigmaApiKeyStatus = "unknown",
 ): FigmaPasteStrategy {
   if (!figmeta) return "not-figma";
-  if (apiKeyStatus === "missing") return "html-fallback";
+  if (apiKeyStatus === "missing") return "local-kiwi";
   return "rest";
 }
 
+// 8 MB decoded binary hard cap for clipboard buffer transport. Buffers above
+// this threshold should use an upload handle instead (Phase 1 future work).
+const MAX_CLIPBOARD_BUFFER_DECODED_BYTES = 8 * 1024 * 1024;
+
 export type FigmaPasteImportCall =
   | {
       action: "import-figma-clipboard";
@@ -173,6 +226,8 @@ export type FigmaPasteImportCall =
         selectedNodeIds?: string[];
         selectedNodeIdsTruncated?: boolean;
         clipboardHtml: string;
+        /** Base64-encoded fig-kiwi buffer, present when strategy is local-kiwi. */
+        clipboardBuffer?: string;
         originalName?: string;
       };
     }
@@ -193,9 +248,10 @@ export type FigmaPasteImportCall =
 export function resolveFigmaPasteImportCall(
   content: string,
   originalName = "figma-paste.html",
+  apiKeyStatus: FigmaApiKeyStatus = "unknown",
 ): FigmaPasteImportCall {
   const figmeta = extractFigmeta(content);
-  const strategy = decideFigmaPasteStrategy(figmeta, "unknown");
+  const strategy = decideFigmaPasteStrategy(figmeta, apiKeyStatus);
 
   if (strategy === "not-figma") {
     return {
@@ -204,6 +260,49 @@ export function resolveFigmaPasteImportCall(
     };
   }
 
+  // For local-kiwi: include the binary buffer so the server can decode it
+  // without a Figma token. Strip the buffer from clipboardHtml to keep the
+  // action payload lean; the server reconstructs the full document from the
+  // buffer instead of the HTML.
+  if (strategy === "local-kiwi") {
+    const bufferBase64 = extractFigmaBuffer(content);
+    const bufferPayload: { clipboardBuffer?: string } = {};
+    if (bufferBase64) {
+      // Enforce the decoded-byte cap before base64 decoding on the server to
+      // prevent the action schema from accepting an oversized payload.
+      const decodedBytes = Math.floor((bufferBase64.length * 3) / 4);
+      if (decodedBytes <= MAX_CLIPBOARD_BUFFER_DECODED_BYTES) {
+        bufferPayload.clipboardBuffer = bufferBase64;
+      }
+    }
+    return {
+      action: "import-figma-clipboard",
+      payload: {
+        figmetaFileKey: figmeta!.fileKey,
+        ...(figmeta!.selectedNodeIds
+          ? { selectedNodeIds: figmeta!.selectedNodeIds }
+          : {}),
+        ...(figmeta!.selectedNodeIdsTruncated
+          ? { selectedNodeIdsTruncated: true }
+          : {}),
+        clipboardHtml: stripFigmaBinaryClipboardBuffer(content),
+        ...bufferPayload,
+        originalName,
+      },
+    };
+  }
+
+  // REST strategy: strip the buffer from clipboardHtml when exact node ids are
+  // available (they make the buffer redundant), but always include clipboardBuffer
+  // so the server can fall back to local-kiwi decode if the token is missing.
+  const restBufferPayload: { clipboardBuffer?: string } = {};
+  const restBufferBase64 = extractFigmaBuffer(content);
+  if (restBufferBase64) {
+    const restDecodedBytes = Math.floor((restBufferBase64.length * 3) / 4);
+    if (restDecodedBytes <= MAX_CLIPBOARD_BUFFER_DECODED_BYTES) {
+      restBufferPayload.clipboardBuffer = restBufferBase64;
+    }
+  }
   return {
     action: "import-figma-clipboard",
     payload: {
@@ -217,6 +316,7 @@ export function resolveFigmaPasteImportCall(
       clipboardHtml: figmeta!.selectedNodeIds?.length
         ? stripFigmaBinaryClipboardBuffer(content)
         : content,
+      ...restBufferPayload,
       originalName,
     },
   };

package/corpus/templates/design/changelog/2026-07-20-paste-figma-frames-directly-onto-the-canvas-no-token-needed.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-20
+---
+
+Paste Figma frames directly onto the canvas — no token needed; connect Figma anytime to fill in images.

package/corpus/templates/design/changelog/2026-07-21-fig-upload-frame-url-and-rate-limit-errors.md

@@ -0,0 +1,5 @@
+---
+type: improved
+---
+
+Upload a .fig file alongside a Figma frame link to import only that frame — no API quota needed, embedded images included. API rate-limit errors now suggest clipboard paste or .fig upload as no-quota alternatives.

package/corpus/templates/design/changelog/2026-07-22-connecting-a-figma-token-now-actually-fills-in-a-pasted-desi.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-22
+---
+
+Connecting a Figma token now actually fills in a pasted design's images (placeholders were previously left unresolved).

package/corpus/templates/design/changelog/2026-07-22-figma-line-arrow-vectors-and-stroked-icons-now-render-instea.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-22
+---
+
+Figma line/arrow vectors and stroked icons now render instead of vanishing — fixed clipping of strokes and zero-size line vectors.

package/corpus/templates/design/changelog/2026-07-22-fill-a-no-token-figma-paste-s-images-by-dropping-the-origina.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-22
+---
+
+Fill a no-token Figma paste's images by dropping the original .fig file — no Figma token or API quota needed.

package/corpus/templates/design/changelog/2026-07-22-imported-and-pasted-figma-frames-now-render-faithfully-fixed.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-22
+---
+
+Imported and pasted Figma frames now render faithfully — fixed off-canvas layers, collapsed groups, and over-clipping that could turn a frame into a black box.