@agent-native/core 0.119.0 → 0.119.1

package/corpus/templates/design/server/lib/figma-clipboard-local-decode.ts

@@ -0,0 +1,238 @@
+/**
+ * Local kiwi decode path for Figma clipboard pastes.
+ *
+ * When no Figma access token is configured, a clipboard paste still carries
+ * the full fig-kiwi binary buffer: geometry, auto-layout, text, fills, and
+ * effects are all present in the kiwi message. This module decodes that
+ * buffer locally using the same decoder as the .fig upload path, synthesizes
+ * an editable HTML screen per top-level frame, and annotates IMAGE fill
+ * elements with `data-figma-image-ref` attributes so that a later call to
+ * `hydrate-figma-paste-images` can fill them in once the user connects their
+ * Figma access token.
+ *
+ * Images are NOT available in the clipboard buffer — Figma stores image bytes
+ * server-side and only includes a 20-byte SHA-1 hash in the kiwi message.
+ * Elements with image fills render as `about:blank` placeholders until
+ * `hydrate-figma-paste-images` resolves and mirrors the real URLs.
+ */
+
+import { assertSafeDecodedFigDocument, decodeFig } from "./fig-file-decoder.js";
+import {
+  type FigNode,
+  type Guid,
+  guidKey,
+  renderHtmlTemplates,
+} from "./fig-file-to-html.js";
+import {
+  normalizeImportedHtmlDocument,
+  type ImportedDesignFile,
+} from "./import-design-files.js";
+
+// 8 MB binary cap. Above this the caller should use an upload handle; below
+// it the action payload carries the base64 directly.
+const MAX_CLIPBOARD_BUFFER_BYTES = 8 * 1024 * 1024;
+
+const MAX_CLIPBOARD_NODES = 75_000;
+const MAX_CLIPBOARD_FRAMES = 50;
+const MAX_FRAME_HTML_BYTES = 4 * 1024 * 1024;
+const MAX_TOTAL_HTML_BYTES = 24 * 1024 * 1024;
+
+export interface ClipboardLocalDecodeResult {
+  files: ImportedDesignFile[];
+  warnings: string[];
+  unresolvedImageRefs: string[];
+  stats: {
+    sourceKind: "figma-clipboard-local-kiwi";
+    format: "kiwi" | "zip";
+    version?: number;
+    frameCount: number;
+    nodeCount: number;
+    unresolvedImageCount: number;
+  };
+}
+
+/**
+ * Return the `guidKey` string for all nodes whose parentIndex.guid does not
+ * point to any other node in the flat nodeChanges list. These are the "roots"
+ * that need a synthetic CANVAS parent so `renderHtmlTemplates` can traverse
+ * the hierarchy starting from its expected DOCUMENT→CANVAS→FRAME structure.
+ */
+function findOrphanRoots(nodeChanges: FigNode[]): FigNode[] {
+  const ownKeys = new Set(nodeChanges.map((n) => guidKey(n.guid)));
+  return nodeChanges.filter((n) => {
+    const pk = guidKey(n.parentIndex?.guid);
+    return !pk || !ownKeys.has(pk);
+  });
+}
+
+/**
+ * Wrap an orphaned nodeChanges array (clipboard format: selected subtree
+ * without a DOCUMENT/CANVAS container) in synthetic DOCUMENT and CANVAS
+ * nodes so `renderHtmlTemplates` can find the top-level frame hierarchy.
+ *
+ * The synthetic node GUIDs use `sessionID = maxExisting + 1` to guarantee
+ * no collision with real clipboard node GUIDs.
+ */
+function normalizeClipboardDocument(document: unknown): unknown {
+  const doc = document as {
+    nodeChanges?: FigNode[];
+    blobs?: unknown[];
+  };
+  const nodeChanges = doc.nodeChanges;
+  if (!Array.isArray(nodeChanges)) return document;
+
+  // Already has a DOCUMENT node → renderer can handle it as-is.
+  if (nodeChanges.some((n) => n.type === "DOCUMENT")) return document;
+
+  const maxSession = nodeChanges.reduce(
+    (m, n) => Math.max(m, n.guid?.sessionID ?? 0),
+    0,
+  );
+  const synBase = maxSession + 1;
+  const docGuid: Guid = { sessionID: synBase, localID: 0 };
+  const pageGuid: Guid = { sessionID: synBase, localID: 1 };
+
+  const orphans = findOrphanRoots(nodeChanges);
+
+  const documentNode: FigNode = {
+    guid: docGuid,
+    type: "DOCUMENT",
+    name: "Document",
+  };
+  const canvasNode: FigNode = {
+    guid: pageGuid,
+    type: "CANVAS",
+    name: "Clipboard",
+    parentIndex: { guid: docGuid, position: "0.5" },
+  };
+
+  // Shallow-copy the orphan nodes, pointing their parentIndex to the
+  // synthetic CANVAS. Non-orphan nodes keep their original parentIndex.
+  const orphanKeys = new Set(orphans.map((n) => guidKey(n.guid)));
+  const patchedNodes = nodeChanges.map((n) => {
+    if (!orphanKeys.has(guidKey(n.guid))) return n;
+    return {
+      ...n,
+      parentIndex: {
+        guid: pageGuid,
+        position: n.parentIndex?.position ?? "0.5",
+      },
+    };
+  });
+
+  return {
+    ...doc,
+    nodeChanges: [documentNode, canvasNode, ...patchedNodes],
+  };
+}
+
+/**
+ * Decode a base64 fig-kiwi clipboard buffer into editable HTML screens.
+ *
+ * @param options.bufferBase64 - Base64 string of the raw fig-kiwi bytes.
+ * @param options.fileKey      - Figma file key from the clipboard's figmeta.
+ * @param options.originalName - Human-readable name for warnings/source metadata.
+ */
+export async function importFigmaClipboardFromBuffer(options: {
+  bufferBase64: string;
+  fileKey: string;
+  originalName?: string;
+}): Promise<ClipboardLocalDecodeResult> {
+  const { bufferBase64, fileKey, originalName = "figma-paste" } = options;
+
+  // Base64 → binary with cap check.
+  const bufferBytes = Buffer.from(bufferBase64, "base64");
+  if (bufferBytes.length > MAX_CLIPBOARD_BUFFER_BYTES) {
+    throw new Error(
+      `Figma clipboard buffer is too large for local decode (max 8 MB). Use a Figma access token for direct REST import instead.`,
+    );
+  }
+
+  const decoded = decodeFig(bufferBytes);
+  assertSafeDecodedFigDocument(decoded.document);
+
+  // Count nodes before synthesis to report against the cap.
+  const rawDoc = decoded.document as { nodeChanges?: FigNode[] };
+  const nodeCount = rawDoc.nodeChanges?.length ?? 0;
+  if (nodeCount > MAX_CLIPBOARD_NODES) {
+    throw new Error(
+      `Figma clipboard has too many nodes (${nodeCount}; max ${MAX_CLIPBOARD_NODES}). Import a smaller selection.`,
+    );
+  }
+
+  const normalizedDoc = normalizeClipboardDocument(decoded.document);
+
+  // Empty imageMap so all IMAGE fills are treated as unresolved. The renderer
+  // will stamp data-figma-image-ref on affected elements via trackUnresolvedImageRefs.
+  const rendered = renderHtmlTemplates(normalizedDoc, {
+    imageMap: new Map(),
+    missingImageUrl: "about:blank",
+    trackUnresolvedImageRefs: true,
+    maxFrames: MAX_CLIPBOARD_FRAMES,
+    maxFrameOutputBytes: MAX_FRAME_HTML_BYTES,
+    maxTotalOutputBytes: MAX_TOTAL_HTML_BYTES,
+  });
+
+  if (rendered.frames.length === 0) {
+    throw new Error(
+      "No editable frames were found in the Figma clipboard. Copy a top-level frame before pasting.",
+    );
+  }
+
+  const unresolvedRefs = Array.from(rendered.unresolvedImageRefs ?? []);
+
+  let totalHtmlBytes = 0;
+  const files: ImportedDesignFile[] = rendered.frames.map((frame) => {
+    const content = normalizeImportedHtmlDocument(
+      frame.html,
+      `figma clipboard local-kiwi decode ${originalName}`,
+    );
+    const htmlBytes = Buffer.byteLength(content, "utf8");
+    totalHtmlBytes += htmlBytes;
+    if (totalHtmlBytes > MAX_TOTAL_HTML_BYTES) {
+      throw new Error(
+        "Figma clipboard import generated too much HTML (max 24 MB). Import a smaller selection.",
+      );
+    }
+    return {
+      filename: frame.fileName,
+      fileType: "html" as const,
+      content,
+      source: {
+        sourceType: "figma-clipboard-local-kiwi",
+        figmaFileKey: fileKey,
+        figmaNodeName: frame.frameName,
+        figFormat: decoded.format,
+        figVersion: decoded.version,
+        unresolvedImageRefs:
+          unresolvedRefs.length > 0 ? unresolvedRefs : undefined,
+      },
+      preferredFrame: {
+        title: frame.frameName,
+        width: frame.width,
+        height: frame.height,
+      },
+    } satisfies ImportedDesignFile;
+  });
+
+  const warnings: string[] = [];
+  if (unresolvedRefs.length > 0) {
+    warnings.push(
+      `${unresolvedRefs.length} image${unresolvedRefs.length === 1 ? "" : "s"} could not be loaded without a Figma access token. Connect Figma to fill them in.`,
+    );
+  }
+
+  return {
+    files,
+    warnings,
+    unresolvedImageRefs: unresolvedRefs,
+    stats: {
+      sourceKind: "figma-clipboard-local-kiwi",
+      format: decoded.format,
+      version: decoded.version,
+      frameCount: rendered.frames.length,
+      nodeCount,
+      unresolvedImageCount: unresolvedRefs.length,
+    },
+  };
+}

package/corpus/templates/design/server/lib/figma-image-hydration.ts

@@ -0,0 +1,389 @@
+/**
+ * Resolves the `data-figma-image-ref` placeholders a no-token clipboard/`.fig`
+ * decode stamps onto unresolved IMAGE fills. Trap: the clipboard carries only
+ * hashes, never bytes; the `.fig`'s embedded `images/` bytes — keyed by the same
+ * SHA-1 the kiwi IMAGE fills reference — are what `resolveFigImageHashes` mirrors
+ * token-free. REST (`hydrate-figma-paste-images`) resolves the same hashes with a token.
+ */
+
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+} from "@agent-native/core/collab";
+import { uploadFile } from "@agent-native/core/file-upload";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../db/index.js";
+import {
+  readLiveSourceFile,
+  writeInlineSourceFile,
+  type SourceWorkspaceFile,
+} from "../source-workspace.js";
+import { mutateDesignData } from "./design-data-mutation.js";
+import { decodeFig, type DecodedFigImage } from "./fig-file-decoder.js";
+
+// ---------------------------------------------------------------------------
+// HTML helpers
+// ---------------------------------------------------------------------------
+
+const DATA_IMAGE_REF_ATTR_RE = /\sdata-figma-image-ref="([^"]*)"/;
+
+// Must match the renderer's real placeholder form `url('about:blank')` (single
+// quotes survive style-attr escaping); lenient to the `"` entity form for
+// older screens, with the back-reference keeping the quotes matched.
+const IMAGE_URL_PLACEHOLDER_RE = /url\(("|')about:blank\1\)/g;
+
+/**
+ * Wrap `url()` exactly as the renderer's escaped `style="…"` would, so hydrated
+ * fills are byte-identical to natively rendered image fills.
+ */
+function cssUrlInAttr(url: string): string {
+  const inner = url
+    .replace(/'/g, "%27")
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;");
+  return `url('${inner}')`;
+}
+
+export function collectImageRefHashes(html: string): string[] {
+  const hashes = new Set<string>();
+  for (const m of html.matchAll(/<[^>]+>/g)) {
+    const ref = m[0].match(DATA_IMAGE_REF_ATTR_RE);
+    if (ref?.[1]) {
+      for (const h of ref[1].trim().split(/\s+/)) {
+        if (h) hashes.add(h);
+      }
+    }
+  }
+  return Array.from(hashes);
+}
+
+/**
+ * Fill `url('about:blank')` placeholders on `data-figma-image-ref` elements: the
+ * Nth placeholder maps to the Nth hash in the space-separated attr value.
+ */
+export function hydrateImageRefsInHtml(
+  html: string,
+  resolvedUrls: Map<string, string>,
+): { html: string; resolved: number; missing: string[] } {
+  let resolvedCount = 0;
+  const missing: string[] = [];
+
+  const newHtml = html.replace(/<[^>]+>/g, (tag) => {
+    const refMatch = tag.match(DATA_IMAGE_REF_ATTR_RE);
+    if (!refMatch?.[1]) return tag;
+
+    const hashes = refMatch[1].trim().split(/\s+/).filter(Boolean);
+    if (hashes.length === 0) return tag;
+
+    const unresolvedHashes: string[] = [];
+    let hashIdx = 0;
+
+    let newTag = tag.replace(IMAGE_URL_PLACEHOLDER_RE, (match) => {
+      if (hashIdx >= hashes.length) return match;
+      const hash = hashes[hashIdx++]!;
+      const durableUrl = resolvedUrls.get(hash);
+      if (!durableUrl) {
+        unresolvedHashes.push(hash);
+        return match;
+      }
+      resolvedCount++;
+      return cssUrlInAttr(durableUrl);
+    });
+
+    // Hashes beyond url() occurrences (shouldn't happen with our renderer).
+    while (hashIdx < hashes.length) {
+      unresolvedHashes.push(hashes[hashIdx++]!);
+    }
+
+    missing.push(...unresolvedHashes);
+
+    if (unresolvedHashes.length === 0) {
+      newTag = newTag.replace(/\s+data-figma-image-ref="[^"]*"/, "");
+    } else if (unresolvedHashes.length < hashes.length) {
+      newTag = newTag.replace(
+        /data-figma-image-ref="[^"]*"/,
+        `data-figma-image-ref="${unresolvedHashes.join(" ")}"`,
+      );
+    }
+
+    return newTag;
+  });
+
+  return { html: newHtml, resolved: resolvedCount, missing };
+}
+
+// ---------------------------------------------------------------------------
+// Shared file load + persist
+// ---------------------------------------------------------------------------
+
+export interface HydratableFile {
+  workspaceFile: SourceWorkspaceFile;
+  designId: string;
+  /** Present only when the screen was imported via a REST clipboard path. */
+  figmaFileKey?: string;
+}
+
+/**
+ * Scoped, editor-access load of one HTML design file, plus the originating Figma
+ * file key when recorded. Throws identical not-found/non-HTML errors for both resolvers.
+ */
+export async function loadHydratableFile(
+  fileId: string,
+): Promise<HydratableFile> {
+  const db = getDb();
+  const [row] = await db
+    .select({
+      id: schema.designFiles.id,
+      designId: schema.designFiles.designId,
+      filename: schema.designFiles.filename,
+      fileType: schema.designFiles.fileType,
+      content: schema.designFiles.content,
+      designData: schema.designs.data,
+    })
+    .from(schema.designFiles)
+    .innerJoin(
+      schema.designs,
+      eq(schema.designFiles.designId, schema.designs.id),
+    )
+    .where(
+      and(
+        eq(schema.designFiles.id, fileId),
+        accessFilter(schema.designs, schema.designShares),
+      ),
+    )
+    .limit(1);
+
+  if (!row) throw new Error(`File not found: ${fileId}`);
+  if (row.fileType !== "html") {
+    throw new Error("hydrate-figma-paste-images only supports HTML files.");
+  }
+
+  await assertAccess("design", row.designId, "editor");
+
+  let figmaFileKey: string | undefined;
+  try {
+    const designData: unknown = row.designData
+      ? JSON.parse(row.designData)
+      : {};
+    const screenMeta = (designData as Record<string, unknown>)?.screenMetadata;
+    if (screenMeta && typeof screenMeta === "object") {
+      const fileMeta = (screenMeta as Record<string, unknown>)[fileId];
+      if (fileMeta && typeof fileMeta === "object") {
+        const key = (fileMeta as Record<string, unknown>).figmaFileKey;
+        if (typeof key === "string" && key) figmaFileKey = key;
+      }
+    }
+  } catch {
+    // JSON.parse failure — figmaFileKey stays undefined; the REST caller
+    // surfaces its own missing-key error, the .fig path does not need one.
+  }
+
+  const workspaceFile: SourceWorkspaceFile = {
+    id: row.id,
+    designId: row.designId,
+    filename: row.filename,
+    fileType: "html",
+    content: row.content ?? "",
+    createdAt: null,
+    updatedAt: null,
+  };
+
+  return { workspaceFile, designId: row.designId, figmaFileKey };
+}
+
+export interface ApplyHydrationResult {
+  resolved: number;
+  missing: number;
+  skipped: number;
+}
+
+/**
+ * Hydrate placeholders and persist (CAS + collab sync), pruning
+ * `screenMetadata.unresolvedImageRefs`. Never writes when nothing resolved.
+ */
+export async function applyHydration(opts: {
+  file: SourceWorkspaceFile;
+  designId: string;
+  fileId: string;
+  liveContent: string;
+  liveVersionHash: string;
+  requestedHashes: string[];
+  resolvedUrls: Map<string, string>;
+}): Promise<ApplyHydrationResult> {
+  const { file, designId, fileId, liveContent, liveVersionHash } = opts;
+  const {
+    html: hydratedHtml,
+    resolved,
+    missing,
+  } = hydrateImageRefsInHtml(liveContent, opts.resolvedUrls);
+
+  const uniqueMissing = Array.from(new Set(missing));
+  const skipped = opts.requestedHashes.length - opts.resolvedUrls.size;
+
+  if (resolved === 0) {
+    return { resolved: 0, missing: uniqueMissing.length, skipped };
+  }
+
+  agentEnterDocument(fileId);
+  try {
+    await writeInlineSourceFile({
+      designId,
+      file,
+      content: hydratedHtml,
+      expectedVersionHash: liveVersionHash,
+    });
+  } finally {
+    agentLeaveDocument(fileId);
+  }
+
+  await mutateDesignData({
+    designId,
+    mutate: (current) => {
+      const screenMeta = current.screenMetadata;
+      if (!screenMeta || typeof screenMeta !== "object") return current;
+      const fileMeta = (screenMeta as Record<string, unknown>)[fileId];
+      if (!fileMeta || typeof fileMeta !== "object") return current;
+      const updatedFileMeta: Record<string, unknown> = {
+        ...(fileMeta as Record<string, unknown>),
+      };
+      if (uniqueMissing.length > 0) {
+        updatedFileMeta.unresolvedImageRefs = uniqueMissing;
+      } else {
+        delete updatedFileMeta.unresolvedImageRefs;
+      }
+      return {
+        ...current,
+        screenMetadata: {
+          ...(screenMeta as Record<string, unknown>),
+          [fileId]: updatedFileMeta,
+        },
+      };
+    },
+    isApplied: (persisted) => {
+      const screenMeta = persisted.screenMetadata;
+      if (!screenMeta || typeof screenMeta !== "object") return false;
+      const fileMeta = (screenMeta as Record<string, unknown>)[fileId];
+      if (!fileMeta || typeof fileMeta !== "object") return false;
+      const refs = (fileMeta as Record<string, unknown>).unresolvedImageRefs;
+      return uniqueMissing.length === 0
+        ? refs === undefined || (Array.isArray(refs) && refs.length === 0)
+        : Array.isArray(refs) && refs.length === uniqueMissing.length;
+    },
+  });
+
+  return { resolved, missing: uniqueMissing.length, skipped };
+}
+
+// ---------------------------------------------------------------------------
+// Token-free `.fig` resolver
+// ---------------------------------------------------------------------------
+
+const FIG_HYDRATE_UPLOAD_CONCURRENCY = 4;
+
+function mimeTypeForExt(ext: string): string {
+  if (ext === "jpg" || ext === "jpeg") return "image/jpeg";
+  if (ext === "png") return "image/png";
+  if (ext === "webp") return "image/webp";
+  if (ext === "gif") return "image/gif";
+  return "application/octet-stream";
+}
+
+/**
+ * Decode a `.fig` and index its embedded images by SHA-1 hash. Decode once per
+ * upload and reuse the index across screens — a multi-screen hydration must not
+ * re-parse the whole (up to 50 MB) file per screen.
+ */
+export function indexFigImages(figBytes: Buffer): Map<string, DecodedFigImage> {
+  const byHash = new Map<string, DecodedFigImage>();
+  for (const image of decodeFig(figBytes).images) byHash.set(image.hash, image);
+  return byHash;
+}
+
+/**
+ * Match placeholder hashes against a `.fig`'s embedded `images/` bytes (keyed by
+ * the same SHA-1 the paste stamped) and mirror matches to durable storage. No
+ * Figma token or REST call.
+ */
+export async function resolveFigImageHashes(opts: {
+  figImages: Map<string, DecodedFigImage>;
+  hashes: string[];
+  ownerEmail: string;
+  uploader?: typeof uploadFile;
+}): Promise<Map<string, string>> {
+  const { figImages, hashes, ownerEmail } = opts;
+  const uploader = opts.uploader ?? uploadFile;
+
+  const wanted = hashes.filter((h) => figImages.has(h));
+  const resolved = new Map<string, string>();
+
+  for (
+    let offset = 0;
+    offset < wanted.length;
+    offset += FIG_HYDRATE_UPLOAD_CONCURRENCY
+  ) {
+    const batch = wanted.slice(offset, offset + FIG_HYDRATE_UPLOAD_CONCURRENCY);
+    await Promise.all(
+      batch.map(async (hash) => {
+        const image = figImages.get(hash)!;
+        try {
+          const uploaded = await uploader({
+            data: image.bytes,
+            filename: `figma-${image.hash}.${image.ext}`,
+            mimeType: mimeTypeForExt(image.ext),
+            ownerEmail,
+            recordAsset: false,
+            stableUrl: true,
+          });
+          if (uploaded?.url) resolved.set(hash, uploaded.url);
+        } catch {
+          // Skip; a partial resolve still helps and leaves placeholders for a retry.
+        }
+      }),
+    );
+  }
+
+  return resolved;
+}
+
+/**
+ * Token-free hydration of one screen's image placeholders from an uploaded
+ * `.fig`. Takes a pre-decoded image index (see `indexFigImages`) so a
+ * multi-screen hydration decodes the file once, not once per screen.
+ */
+export async function hydrateFileImagesFromFig(opts: {
+  fileId: string;
+  figImages: Map<string, DecodedFigImage>;
+  ownerEmail: string;
+  uploader?: typeof uploadFile;
+}): Promise<ApplyHydrationResult & { fileId: string }> {
+  const { fileId, figImages, ownerEmail } = opts;
+  const { workspaceFile, designId } = await loadHydratableFile(fileId);
+  const live = await readLiveSourceFile(workspaceFile);
+
+  const hashes = collectImageRefHashes(live.content);
+  if (hashes.length === 0) {
+    return { fileId, resolved: 0, missing: 0, skipped: 0 };
+  }
+
+  const resolvedUrls = await resolveFigImageHashes({
+    figImages,
+    hashes,
+    ownerEmail,
+    uploader: opts.uploader,
+  });
+
+  const result = await applyHydration({
+    file: workspaceFile,
+    designId,
+    fileId,
+    liveContent: live.content,
+    liveVersionHash: live.versionHash,
+    requestedHashes: hashes,
+    resolvedUrls,
+  });
+
+  return { fileId, ...result };
+}