@agent-native/core 0.118.1 → 0.119.1

package/corpus/templates/design/server/handlers/import-design-file.ts

@@ -20,6 +20,10 @@ const MAX_HTML_BYTES = 2 * 1024 * 1024;
 const MULTIPART_OVERHEAD_BYTES = 1024 * 1024;
 const TOTAL_BODY_LIMIT = MAX_FIG_FILE_BYTES + MULTIPART_OVERHEAD_BYTES;
 
+// Matches the local-kiwi clipboard frame cap so a token-free .fig hydration of
+// a multi-frame paste can fill every imported screen in one upload.
+const MAX_HYDRATE_FILES = 50;
+
 function fieldText(
   parts: Awaited<ReturnType<typeof readMultipartFormData>>,
   name: string,
@@ -129,6 +133,51 @@ export const importDesignFile = defineEventHandler(async (event) => {
           if (data.length > MAX_FIG_FILE_BYTES) {
             throw new Error(".fig file is too large (max 50 MB).");
           }
+
+          // Token-free hydration: fill the image placeholders left by a no-token
+          // clipboard paste using the SAME .fig's embedded image bytes. No Figma
+          // token, no REST call — the .fig `images/` entries are keyed by the
+          // same SHA-1 hash the paste stamped into data-figma-image-ref.
+          const hydrateFileIdsRaw = fieldText(parts, "hydrateFileIds");
+          if (hydrateFileIdsRaw) {
+            const fileIds = hydrateFileIdsRaw
+              .split(",")
+              .map((id) => id.trim())
+              .filter(Boolean);
+            if (fileIds.length === 0) {
+              throw new Error("No screen ids provided to hydrate.");
+            }
+            if (fileIds.length > MAX_HYDRATE_FILES) {
+              throw new Error(
+                `Too many screens to hydrate at once (max ${MAX_HYDRATE_FILES}).`,
+              );
+            }
+            const { hydrateFileImagesFromFig, indexFigImages } =
+              await import("../lib/figma-image-hydration.js");
+            // Decode + index the uploaded .fig once, then reuse across screens.
+            const figImages = indexFigImages(data);
+            const results = [];
+            let totalResolved = 0;
+            let totalMissing = 0;
+            for (const fileId of fileIds) {
+              const result = await hydrateFileImagesFromFig({
+                fileId,
+                figImages,
+                ownerEmail: session.email!,
+              });
+              results.push(result);
+              totalResolved += result.resolved;
+              totalMissing += result.missing;
+            }
+            return {
+              importKind: "fig-hydrate" as const,
+              designId,
+              results,
+              totalResolved,
+              totalMissing,
+            };
+          }
+
           // Keep Kiwi/Zstd and the sizeable editable renderer off the normal HTML
           // upload path. They are loaded only for an actual `.fig` request.
           const { importFigFileToEditableHtml } =
@@ -148,6 +197,7 @@ export const importDesignFile = defineEventHandler(async (event) => {
             importKind: "fig",
             ...saved,
             stats: converted.stats,
+            unresolvedImageRefCount: converted.stats.unresolvedImageRefCount,
           };
         }
 

package/corpus/templates/design/server/lib/fig-file-decoder.ts

@@ -21,16 +21,20 @@ const MAX_KIWI_CHUNKS = 4_096;
 const MAX_ZIP_ENTRIES = 2_048;
 const MAX_ZIP_NAME_BYTES = 512;
 const MAX_COMPRESSION_RATIO = 1_000;
-const MAX_DECODED_OBJECTS = 250_000;
 const MAX_DECODE_DEPTH = 256;
-const MAX_COLLECTION_LENGTH = 250_000;
-const MAX_COLLECTION_ITEMS = 1_000_000;
+// Sized with ~15x headroom over a real 11 MB corpus .fig (~530k objects,
+// ~1.5M items, longest single collection ~7.6k) so genuine files decode while a
+// crafted document still hits a finite total-work ceiling.
+const MAX_DECODED_OBJECTS = 8_000_000;
+const MAX_COLLECTION_LENGTH = 2_000_000;
+const MAX_COLLECTION_ITEMS = 24_000_000;
 const MAX_DECODE_READS = 64 * 1024 * 1024;
 const MAX_SANITIZED_BINARY_BYTES = 32 * 1024 * 1024;
 const MAX_DECODED_STRING_BYTES = 4 * 1024 * 1024;
 const MAX_TOTAL_STRING_BYTES = 32 * 1024 * 1024;
 const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
 const FIG_KIWI_MAGIC = Buffer.from("fig-kiwi", "utf8");
+const FIGJAM_KIWI_MAGIC = Buffer.from("fig-jam.", "utf8");
 const ZIP_MAGIC = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
@@ -53,6 +57,7 @@ export interface DecodedFig {
   format: "kiwi" | "zip";
   version?: number;
   document: unknown;
+  decodeError?: string;
   images: DecodedFigImage[];
   thumbnail: Buffer | null;
 }
@@ -193,7 +198,10 @@ export function decodeKiwiContainer(file: Buffer): DecodedFigKiwi {
   if (file.length > MAX_FIG_FILE_BYTES) {
     throw new Error(".fig file is too large (max 50 MB).");
   }
-  if (!file.subarray(0, 8).equals(FIG_KIWI_MAGIC)) {
+  if (
+    !file.subarray(0, 8).equals(FIG_KIWI_MAGIC) &&
+    !file.subarray(0, 8).equals(FIGJAM_KIWI_MAGIC)
+  ) {
     throw new Error("Not a fig-kiwi file (missing magic header)");
   }
   if (file.length < 12) {
@@ -476,7 +484,7 @@ function sanitizeForJson(
     const entries = Object.entries(value);
     budget.items += entries.length;
     if (budget.items > MAX_COLLECTION_ITEMS) {
-      throw new Error("Decoded .fig document has too many object fields.");
+      throw new Error("Decoded .fig document has too many fields.");
     }
     try {
       for (const [k, v] of entries) {
@@ -625,23 +633,26 @@ function compileBudgetedSchema(schema: Schema): CompiledDecoder {
 }
 
 // Returns null on any decode failure so callers can still surface the raw
-// document buffer.
+// document buffer. Also returns an optional decodeError string so callers can
+// surface the reason rather than falling back to a generic message.
 function decodeKiwiDocument(
   schemaBuf: Buffer,
   documentBuf: Buffer,
-): unknown | null {
+): { document: unknown | null; decodeError?: string } {
   let schema: Schema;
   try {
     assertSafeBinarySchemaShape(schemaBuf);
     schema = decodeBinarySchema(schemaBuf);
-  } catch {
-    return null;
+  } catch (e) {
+    return {
+      document: null,
+      decodeError: `Schema parsing failed: ${e instanceof Error ? e.message : String(e)}`,
+    };
   }
   // kiwi-schema compiles the schema with `new Function`, so never pass names
   // from an untrusted binary schema to it without strict identifier and size
   // validation. Real Figma schemas use ordinary identifiers and a `Message`
   // root; anything else is an unsupported/probably hostile variant.
-  if (schema.definitions.length > 1_024) return null;
   const definitionNames = new Set(schema.definitions.map((d) => d.name));
   const safeIdentifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
   const primitiveTypes = new Set([
@@ -654,40 +665,71 @@ function decodeKiwiDocument(
     "int64",
     "uint64",
   ]);
-  let fieldCount = 0;
   for (const definition of schema.definitions) {
-    if (!safeIdentifier.test(definition.name)) return null;
-    if (!Array.isArray(definition.fields) || definition.fields.length > 1_024) {
-      return null;
+    if (!safeIdentifier.test(definition.name)) {
+      return {
+        document: null,
+        decodeError: `Unsafe schema identifier: "${definition.name}"`,
+      };
+    }
+    if (!Array.isArray(definition.fields)) {
+      return {
+        document: null,
+        decodeError: `Definition "${definition.name}" has no fields array`,
+      };
     }
-    fieldCount += definition.fields.length;
-    if (fieldCount > 20_000) return null;
     for (const field of definition.fields) {
-      if (!safeIdentifier.test(field.name)) return null;
+      if (!safeIdentifier.test(field.name)) {
+        return {
+          document: null,
+          decodeError: `Unsafe field identifier: "${definition.name}.${field.name}"`,
+        };
+      }
       if (
         field.type !== null &&
         !primitiveTypes.has(field.type) &&
         !definitionNames.has(field.type)
       ) {
-        return null;
+        return {
+          document: null,
+          decodeError: `Unknown field type "${field.type}" in "${definition.name}.${field.name}"`,
+        };
       }
     }
   }
-  const rootMessage = schema.definitions.find(
-    (definition) =>
-      definition.name === "Message" && definition.kind === "MESSAGE",
-  );
-  if (!rootMessage) return null;
+  // Current Figma .fig files use "Message" as root; fall back to the first
+  // MESSAGE definition when the name differs (schema evolution resilience).
+  const rootMessage =
+    schema.definitions.find(
+      (d) => d.name === "Message" && d.kind === "MESSAGE",
+    ) ?? schema.definitions.find((d) => d.kind === "MESSAGE");
+  if (!rootMessage) {
+    return {
+      document: null,
+      decodeError: `No MESSAGE definition found in schema (${schema.definitions.length} definitions: ${schema.definitions
+        .map((d) => d.name)
+        .slice(0, 10)
+        .join(", ")})`,
+    };
+  }
 
   let compiled: CompiledDecoder;
   try {
     compiled = compileBudgetedSchema(schema);
-  } catch {
-    return null;
+  } catch (e) {
+    return {
+      document: null,
+      decodeError: `Schema compilation failed: ${e instanceof Error ? e.message : String(e)}`,
+    };
   }
   const decodeKey = `decode${rootMessage.name}`;
   const decoder = compiled[decodeKey];
-  if (typeof decoder !== "function") return null;
+  if (typeof decoder !== "function") {
+    return {
+      document: null,
+      decodeError: `Compiled decoder missing function "${decodeKey}"`,
+    };
+  }
 
   try {
     const view = new Uint8Array(
@@ -697,15 +739,20 @@ function decodeKiwiDocument(
     );
     const bb = new BudgetByteBuffer(view);
     const document = decoder.call(compiled, bb);
-    return sanitizeForJson(document, {
-      objects: 0,
-      items: 0,
-      binaryBytes: 0,
-      stringBytes: 0,
-      active: new WeakSet(),
-    });
-  } catch {
-    return null;
+    return {
+      document: sanitizeForJson(document, {
+        objects: 0,
+        items: 0,
+        binaryBytes: 0,
+        stringBytes: 0,
+        active: new WeakSet(),
+      }),
+    };
+  } catch (e) {
+    return {
+      document: null,
+      decodeError: `Document decoding failed: ${e instanceof Error ? e.message : String(e)}`,
+    };
   }
 }
 
@@ -746,23 +793,12 @@ function assertSafeBinarySchemaShape(schemaBuf: Buffer): void {
     ),
   );
   const definitionCount = bb.readVarUint();
-  if (definitionCount > 1_024) {
-    throw new Error(".fig schema has too many definitions.");
-  }
-  let totalFields = 0;
   for (let index = 0; index < definitionCount; index += 1) {
     bb.readString();
     const kind = bb.readByte();
     if (kind > 2)
       throw new Error(".fig schema has an invalid definition kind.");
     const fields = bb.readVarUint();
-    if (fields > 1_024) {
-      throw new Error(".fig schema definition has too many fields.");
-    }
-    totalFields += fields;
-    if (totalFields > 20_000) {
-      throw new Error(".fig schema has too many fields.");
-    }
     for (let fieldIndex = 0; fieldIndex < fields; fieldIndex += 1) {
       bb.readString();
       bb.readVarInt();
@@ -790,7 +826,8 @@ export function decodeFig(file: Buffer): DecodedFig {
     const inner = decodeKiwiContainer(canvasEntry.data);
     version = inner.version;
     extraBlobs = inner.blobs;
-    document = decodeKiwiDocument(inner.schema, inner.document);
+    const kiwiResult = decodeKiwiDocument(inner.schema, inner.document);
+    document = kiwiResult.document;
 
     const images: DecodedFigImage[] = [];
     const seen = new Set<string>();
@@ -813,19 +850,23 @@ export function decodeFig(file: Buffer): DecodedFig {
       format: "zip",
       version,
       document,
+      ...(kiwiResult.decodeError
+        ? { decodeError: kiwiResult.decodeError }
+        : {}),
       images,
       thumbnail: thumbnailEntry?.data ?? null,
     };
   }
 
   const decoded = decodeKiwiContainer(file);
-  const document = decodeKiwiDocument(decoded.schema, decoded.document);
+  const kiwiResult = decodeKiwiDocument(decoded.schema, decoded.document);
   const images = collectImagesFromBlobs(decoded.blobs);
   const thumbnail = findThumbnail(decoded.document, decoded.blobs);
   return {
     format: "kiwi",
     version: decoded.version,
-    document,
+    document: kiwiResult.document,
+    ...(kiwiResult.decodeError ? { decodeError: kiwiResult.decodeError } : {}),
     images,
     thumbnail,
   };

package/corpus/templates/design/server/lib/fig-file-import.ts

@@ -32,6 +32,8 @@ export interface FigFileImportResult {
     imageCount: number;
     uploadedImageCount: number;
     omittedImageCount: number;
+    approximatedNodeCount: number;
+    unresolvedImageRefCount: number;
   };
 }
 
@@ -45,16 +47,20 @@ function mimeTypeForImage(image: DecodedFigImage): string {
   return "application/octet-stream";
 }
 
-function nodeChangesFromDocument(document: unknown): unknown[] {
+function nodeChangesFromDocument(
+  document: unknown,
+  decodeError?: string,
+): unknown[] {
   if (!document || typeof document !== "object") {
+    const detail = decodeError ? ` Decode detail: ${decodeError}.` : "";
     throw new Error(
-      "This .fig variant could not be decoded. Try a Figma link/API import or export the frame as HTML/SVG instead.",
+      `This .fig file could not be decoded.${detail} The schema format may have changed since this file was saved, or the file may be a newer Figma version. Try: (1) copy the frame in Figma and paste directly onto the Design canvas — no API quota needed, or (2) use a Figma frame link to import via the API.`,
     );
   }
   const nodeChanges = (document as { nodeChanges?: unknown }).nodeChanges;
   if (!Array.isArray(nodeChanges)) {
     throw new Error(
-      "This .fig variant does not expose editable node data. Try a Figma link/API import instead.",
+      "This .fig file decoded but does not contain editable node data. Copy the frame in Figma and paste onto the canvas, or use a Figma frame link to import via the API.",
     );
   }
   if (nodeChanges.length > MAX_FIG_NODES) {
@@ -156,8 +162,12 @@ export async function convertDecodedFigToEditableHtml(
   },
 ): Promise<FigFileImportResult> {
   assertSafeDecodedFigDocument(decoded.document);
-  const nodeChanges = nodeChangesFromDocument(decoded.document);
+  const nodeChanges = nodeChangesFromDocument(
+    decoded.document,
+    decoded.decodeError,
+  );
   assertEmbeddedImageBudget(decoded.images);
+
   // Render and validate before uploading any extracted images so an invalid or
   // excessively complex document cannot leave orphaned storage objects behind.
   // The upload primitive has no cross-provider delete contract, so validate
@@ -171,6 +181,7 @@ export async function convertDecodedFigToEditableHtml(
   const preliminary = renderHtmlTemplates(decoded.document, {
     imageMap: worstCaseImageMap,
     missingImageUrl: "about:blank",
+    trackUnresolvedImageRefs: true,
   });
   validateRenderedFrames(preliminary);
   const images = await uploadEmbeddedImages(
@@ -186,6 +197,7 @@ export async function convertDecodedFigToEditableHtml(
           // Never persist a data URL or a broken relative link when an image
           // blob could not be uploaded. The warning makes the omission clear.
           missingImageUrl: "about:blank",
+          trackUnresolvedImageRefs: true,
         });
   validateRenderedFrames(rendered);
 
@@ -244,6 +256,8 @@ export async function convertDecodedFigToEditableHtml(
       imageCount: decoded.images.length,
       uploadedImageCount: images.uploaded,
       omittedImageCount: images.omitted,
+      approximatedNodeCount: rendered.approximatedNodes.length,
+      unresolvedImageRefCount: rendered.unresolvedImageRefs?.size ?? 0,
     },
   };
 }
@@ -253,7 +267,7 @@ function validateRenderedFrames(
 ): void {
   if (rendered.frames.length === 0) {
     throw new Error(
-      "No editable top-level frames were found in this .fig file. Try importing a Figma frame link instead.",
+      "No editable top-level frames were found in this .fig file.",
     );
   }
   if (rendered.frames.length > MAX_FIG_FRAMES) {