@agent-native/core 0.118.1 → 0.119.1

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -13,6 +13,11 @@ import {
   type H3Event,
 } from "h3";
 
+import {
+  applyA2AAgentActivityEvent,
+  buildA2AAgentActivityPart,
+  createA2AAgentActivityState,
+} from "../a2a/activity.js";
 import {
   appendA2AArtifactLinks,
   buildA2ARecoverableArtifactMessage,
@@ -400,6 +405,8 @@ export function createSerializedA2ATaskStatusWriter(
   };
 }
 
+const A2A_ACTIVITY_CHECKPOINT_MIN_INTERVAL_MS = 2_000;
+
 export async function resolveA2ARecoverableArtifactSecret(
   orgId: string | null | undefined = getRequestOrgId(),
 ): Promise<string | undefined> {
@@ -1656,10 +1663,36 @@ export function createAgentChatPlugin(
           const a2aEvents: AgentChatEvent[] = [];
           const a2aToolResults: A2AToolResultSummary[] = [];
           let lastRecoverableArtifactText = "";
+          let activityState = createA2AAgentActivityState();
+          let lastActivityCheckpointAt = 0;
           const recoverableArtifactSecret =
             await resolveA2ARecoverableArtifactSecret();
           const recoverableArtifactStatusWriter =
             createSerializedA2ATaskStatusWriter(context.taskId);
+          const activityStatusMessage = (): A2AMessage => ({
+            role: "agent",
+            ...(lastRecoverableArtifactText
+              ? { metadata: { agentNativeRecoverableArtifacts: true } }
+              : {}),
+            parts: [
+              buildA2AAgentActivityPart(activityState),
+              ...(lastRecoverableArtifactText
+                ? [{ type: "text" as const, text: lastRecoverableArtifactText }]
+                : []),
+            ],
+          });
+          const checkpointActivity = (force = false) => {
+            const now = Date.now();
+            if (
+              !force &&
+              now - lastActivityCheckpointAt <
+                A2A_ACTIVITY_CHECKPOINT_MIN_INTERVAL_MS
+            ) {
+              return;
+            }
+            lastActivityCheckpointAt = now;
+            recoverableArtifactStatusWriter.enqueue(activityStatusMessage());
+          };
           const controller = new AbortController();
           const correlation = sanitizeA2ACorrelationMetadata(context.metadata);
           const telemetryThreadId =
@@ -1697,6 +1730,12 @@ export function createAgentChatPlugin(
               turnId: context.taskId,
               send: (event) => {
                 a2aEvents.push(event);
+                const nextActivityState = applyA2AAgentActivityEvent(
+                  activityState,
+                  event,
+                );
+                const activityChanged = nextActivityState !== activityState;
+                activityState = nextActivityState;
                 if (event.type === "tool_start") {
                   console.log(`[A2A] Tool call: ${event.tool}`);
                 } else if (event.type === "tool_done") {
@@ -1727,22 +1766,20 @@ export function createAgentChatPlugin(
                     recoverableArtifactText !== lastRecoverableArtifactText
                   ) {
                     lastRecoverableArtifactText = recoverableArtifactText;
-                    recoverableArtifactStatusWriter.enqueue({
-                      role: "agent",
-                      metadata: { agentNativeRecoverableArtifacts: true },
-                      parts: [
-                        {
-                          type: "text",
-                          text: recoverableArtifactText,
-                        },
-                      ],
-                    });
                   }
                 } else if (event.type === "error") {
                   console.error(`[A2A] Error: ${event.error}`);
                 } else if (event.type === "done") {
                   console.log(`[A2A] Done. Events: ${a2aEvents.length}`);
                 }
+                if (activityChanged) {
+                  checkpointActivity(
+                    event.type === "tool_start" ||
+                      event.type === "tool_done" ||
+                      event.type === "error" ||
+                      event.type === "done",
+                  );
+                }
               },
               signal: controller.signal,
             },
@@ -1779,6 +1816,7 @@ export function createAgentChatPlugin(
 
           // The continuation can observe terminal output immediately, so make
           // its latest mutation checkpoint durable first.
+          checkpointActivity(true);
           await recoverableArtifactStatusWriter.flush();
 
           const approval = [...a2aEvents]
@@ -1817,6 +1855,7 @@ export function createAgentChatPlugin(
                 },
               },
               parts: [
+                buildA2AAgentActivityPart(activityState),
                 {
                   type: "text" as const,
                   text:
@@ -1851,6 +1890,7 @@ export function createAgentChatPlugin(
           yield {
             role: "agent" as const,
             parts: [
+              buildA2AAgentActivityPart(activityState),
               {
                 type: "text" as const,
                 text: finalText || "(no response)",

package/corpus/core/src/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -195,6 +195,22 @@ for await (const update of client.stream({
 }
 ```
 
+### Agent activity in delegated chat
+
+Agent Native peers attach a bounded `data` part with
+`kind: "agent-native/agent-activity"` to in-progress and terminal task status
+messages. It contains the same user-visible reasoning summaries shown in the
+receiving app, tool names and completion states, elapsed time, and progressive
+response text. It never includes tool inputs, tool results, credentials, or
+hidden provider reasoning.
+
+`call-agent` reads this optional part while it polls an asynchronous task and
+renders the remote work as a nested agent run. Unknown A2A peers do not need to
+implement the extension: their ordinary status and final text still render in
+the same nested block. Treat activity data as untrusted presentation content;
+never use it for identity, authorization, approval, routing, or artifact
+validation.
+
 ### Carrying explicit chat authorization
 
 When the authenticated caller has an exact consequential action that the user

package/corpus/templates/assets/app/routes/library.tsx

@@ -60,7 +60,6 @@ import {
 } from "react-router";
 import { toast } from "sonner";
 
-import { CreateLibraryDialog } from "@/components/library/CreateLibraryDialog";
 import { LibraryPresetGrid } from "@/components/library/LibraryPresetGrid";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -2087,7 +2086,7 @@ export function LibraryWorkspace({
   const t = useT();
   const navigate = useNavigate();
   const routeSelectedLibraryId = useLibraryRouteSelectedId(selectedLibraryId);
-  const [createOpen, setCreateOpen] = useState(false);
+  const createLibrary = useActionMutation("create-library");
   const { data, isLoading, isError, isFetching, refetch } = useActionQuery(
     "list-libraries",
     {
@@ -2131,6 +2130,20 @@ export function LibraryWorkspace({
     });
   }, [currentLibrary?.title, routeSelectedLibraryId]);
 
+  const handleCreateKit = useCallback(() => {
+    createLibrary.mutate(
+      { title: t("brandKits.newBrandKit") },
+      {
+        onSuccess: (library: any) => {
+          void navigate(`/brand-kits/${library.id}/settings`);
+        },
+        onError: (error: Error) => {
+          toast.error(error.message);
+        },
+      },
+    );
+  }, [createLibrary, navigate, t]);
+
   return (
     <div className="flex h-full min-h-0 flex-col bg-background text-foreground">
       <section className="min-h-0 min-w-0 flex-1 overflow-hidden">
@@ -2139,7 +2152,7 @@ export function LibraryWorkspace({
             selectedLibraryId={routeSelectedLibraryId}
             libraries={libraries}
             isLoading={isLoading}
-            onCreateKit={() => setCreateOpen(true)}
+            onCreateKit={handleCreateKit}
           />
           {isError ? (
             <div className="flex min-h-80 flex-col items-center justify-center gap-3 px-6 text-center">
@@ -2168,15 +2181,10 @@ export function LibraryWorkspace({
               )}
             </div>
           ) : (
-            <EmptyLibraryStarter onCreateBlank={() => setCreateOpen(true)} />
+            <EmptyLibraryStarter onCreateBlank={handleCreateKit} />
           )}
         </div>
       </section>
-      <CreateLibraryDialog
-        open={createOpen}
-        onOpenChange={setCreateOpen}
-        onCreated={(library) => navigate(`/library/${library.id}`)}
-      />
     </div>
   );
 }

package/corpus/templates/clips/changelog/2026-07-23-fixed-recordings-failing-to-save-with-a-cancelled-or-cleanup.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+Fixed recordings failing to save with a "cancelled" or "cleanup window" error during upload

package/corpus/templates/clips/server/plugins/db.ts

@@ -1333,8 +1333,16 @@ async function sweepOrphanedResumableSessions(): Promise<void> {
     if (!key.startsWith(prefix)) continue;
     const recordingId = key.slice(prefix.length);
     if (!recordingId) continue;
+    // `application_state.updated_at` is epoch-ms (a JS number on SQLite, a
+    // BIGINT string on Postgres), but the staleness cutoffs below are ISO-8601.
+    // Normalize to ISO before comparing — a raw epoch-ms value ("1753…") always
+    // sorts lexically below any "2…" ISO date, which would flag every live
+    // upload as stale and force-fail it.
+    const sessionUpdatedAtMs = Number(row.updated_at);
     const sessionUpdatedAt =
-      typeof row.updated_at === "string" ? row.updated_at : "";
+      Number.isFinite(sessionUpdatedAtMs) && sessionUpdatedAtMs > 0
+        ? new Date(sessionUpdatedAtMs).toISOString()
+        : "";
 
     let shouldSweep = false;
     try {

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,
+    };
+  },
+});