fundus 0.28.1 → 0.29.1

package/dist/server/importers/figma.js

@@ -1,7 +1,7 @@
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
 import sharp from 'sharp';
-import { isInstanceSublayerId, isValidAssetId } from '../../core/index.js';
+import { figmaLinksFromRest, figmaTagEntries, fundusTagLink, isValidAssetId } from '../../core/index.js';
 import { SourceImportError, invalidInput } from './contract.js';
 import { requestPinnedHttps } from './pinned-https.js';
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
@@ -9,6 +9,9 @@ const MAX_PIXELS = 32_000_000;
 const MAX_REDIRECTS = 3;
 const REQUEST_TIMEOUT_MS = 30_000;
 const PNG_SIGNATURE = Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]);
+/** Worst case per API call: 3 attempts × 30 s timeout + 2 waits × 10 s = 110 s. */
+const FIGMA_RATE_LIMIT_ATTEMPTS = 3;
+const FIGMA_RATE_LIMIT_MAX_WAIT_SECONDS = 10;
 function record(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value)
         ? value
@@ -130,17 +133,19 @@ function retryAfter(response) {
     const seconds = Number(raw);
     return Number.isSafeInteger(seconds) ? seconds : undefined;
 }
-function upstreamStatusError(response) {
+function upstreamStatusError(response, scope) {
     if (response.status === 401)
         return new SourceImportError('unauthorized', 'Figma authentication failed.');
     if (response.status === 403)
-        return new SourceImportError('forbidden', 'Figma authentication or access failed. The token may be invalid or expired, or it may not have access to this file.');
+        return new SourceImportError('forbidden', scope
+            ? `Figma authentication or access failed. The token may be invalid or expired, may lack the ${scope} scope, or may not have access to this file.`
+            : 'Figma authentication or access failed. The token may be invalid or expired, or it may not have access to this file.');
     if (response.status === 404)
         return new SourceImportError('not-found', 'The Figma file or node was not found.');
     if (response.status === 429) {
         return new SourceImportError('rate-limited', 'Figma rate-limited this request.', retryAfter(response));
     }
-    return new SourceImportError('upstream-failed', `Figma export failed with status ${response.status}.`);
+    return new SourceImportError('upstream-failed', `Figma request failed with status ${response.status}.`);
 }
 function isForbiddenIpv4(address) {
     const parts = address.split('.').map(Number);
@@ -248,22 +253,22 @@ export async function resolveSafeDownloadTarget(value) {
 export async function assertSafeDownloadUrl(value) {
     return (await resolveSafeDownloadTarget(value)).url;
 }
-async function fetchWithDeadline(fetcher, url, init, consume) {
+async function fetchWithDeadline(fetcher, url, init, scope) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
     try {
         const response = await fetcher(url, { ...init, signal: controller.signal });
         if (!response.ok)
-            throw upstreamStatusError(response);
-        return await consume(response);
+            throw upstreamStatusError(response, scope);
+        return new Uint8Array(await response.arrayBuffer());
     }
     catch (cause) {
         if (controller.signal.aborted || (cause instanceof Error && cause.name === 'AbortError')) {
-            throw new SourceImportError('download-timeout', 'Figma export timed out.');
+            throw new SourceImportError('download-timeout', 'Figma request timed out.');
         }
         if (cause instanceof SourceImportError)
             throw cause;
-        throw new SourceImportError('upstream-failed', 'Figma export request failed.');
+        throw new SourceImportError('upstream-failed', 'Figma request failed.');
     }
     finally {
         clearTimeout(timeout);
@@ -383,50 +388,40 @@ async function validatePng(bytes) {
         throw new SourceImportError('image-too-large', 'Figma export exceeds the 32 megapixel limit.');
     }
 }
-/**
- * Every taggable node in a REST document tree (`plugin_data=shared`), in
- * document order. Nodes inside instances are skipped: they echo the main
- * component node's tag, and Fundus imports only plain `12:34` node ids.
- */
-export function figmaDocumentNodes(document) {
-    const nodes = [];
-    const visit = (value, page) => {
-        const current = record(value);
-        if (!current)
-            return;
-        const name = typeof current.name === 'string' ? current.name : '';
-        const pageName = current.type === 'CANVAS' ? name : page;
-        if (typeof current.id === 'string' &&
-            current.type !== 'DOCUMENT' &&
-            current.type !== 'CANVAS' &&
-            !isInstanceSublayerId(current.id)) {
-            const shared = record(current.sharedPluginData);
-            const fundus = shared ? record(shared.fundus) : null;
-            const tag = fundus && typeof fundus.assetId === 'string' ? fundus.assetId : '';
-            nodes.push({
-                nodeId: current.id,
-                nodeName: name,
-                page: pageName,
-                tag: tag === '' ? null : tag
-            });
+async function fetchFigmaApiBytes(endpoint, init, scope, context) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await fetchWithDeadline(context.fetch, endpoint, init, scope);
         }
-        if (Array.isArray(current.children)) {
-            for (const child of current.children)
-                visit(child, pageName);
+        catch (cause) {
+            const wait = cause instanceof SourceImportError && cause.code === 'rate-limited'
+                ? cause.retryAfterSeconds
+                : undefined;
+            if (wait === undefined ||
+                wait > FIGMA_RATE_LIMIT_MAX_WAIT_SECONDS ||
+                attempt >= FIGMA_RATE_LIMIT_ATTEMPTS) {
+                throw cause;
+            }
+            await new Promise((resolve) => setTimeout(resolve, wait * 1000));
         }
-    };
-    visit(record(document), '');
-    return nodes;
+    }
 }
-/** The whole document tree of a Figma file, including every node's shared plugin data. */
-export async function fetchFigmaDocument(fileKey, context) {
+async function requestFigmaApi(endpoint, context, request) {
     const token = context.config.import.figma.token;
     if (!token) {
         throw new SourceImportError('not-configured', 'Figma access is not configured.');
     }
-    const endpoint = new URL(`https://api.figma.com/v1/files/${encodeURIComponent(fileKey)}`);
-    endpoint.searchParams.set('plugin_data', 'shared');
-    const jsonBytes = await fetchWithDeadline(context.fetch, endpoint, { redirect: 'error', headers: { 'X-Figma-Token': token } }, async (response) => new Uint8Array(await response.arrayBuffer()));
+    const jsonBytes = await fetchFigmaApiBytes(endpoint, {
+        method: request.method ?? 'GET',
+        redirect: 'error',
+        headers: {
+            'X-Figma-Token': token,
+            ...(request.body !== undefined ? { 'Content-Type': 'application/json' } : {})
+        },
+        ...(request.body !== undefined ? { body: JSON.stringify(request.body) } : {})
+    }, request.scope, context);
+    if (jsonBytes.byteLength === 0)
+        return {};
     let payload;
     try {
         payload = JSON.parse(new TextDecoder().decode(jsonBytes));
@@ -435,56 +430,144 @@ export async function fetchFigmaDocument(fileKey, context) {
         throw new SourceImportError('invalid-response', 'Figma returned an invalid response.');
     }
     const body = record(payload);
-    if (!body || body.err || (typeof body.status === 'number' && body.status >= 400)) {
+    if (!body ||
+        body.err ||
+        body.error === true ||
+        (typeof body.status === 'number' && body.status >= 400)) {
+        throw new SourceImportError('invalid-response', request.errorMessage);
+    }
+    // Figma reports rejected batch entries (e.g. "Url already exists") in `errors` with HTTP 200.
+    if (Array.isArray(body.errors) && body.errors.length > 0) {
+        const reasons = body.errors.map((entry) => {
+            const reason = record(entry)?.error;
+            return typeof reason === 'string' ? reason : 'unknown error';
+        });
+        throw new SourceImportError('upstream-failed', `Figma rejected the request: ${reasons.join('; ')}`);
+    }
+    return body;
+}
+function figmaFileEndpoint(fileKey, path) {
+    return new URL(`https://api.figma.com/v1/files/${encodeURIComponent(fileKey)}${path}`);
+}
+/** Every Fundus tag link in the file (orphaned ones included); each entry has its `linkId`. */
+export async function listFigmaTagEntries(fileKey, context) {
+    const body = await requestFigmaApi(figmaFileEndpoint(fileKey, '/dev_resources'), context, {
+        scope: 'file_dev_resources:read',
+        errorMessage: 'Figma returned an invalid response.'
+    });
+    const links = figmaLinksFromRest(body);
+    if (!links) {
+        throw new SourceImportError('invalid-response', 'Figma returned an invalid Dev Resources list.');
+    }
+    return figmaTagEntries(links).filter((entry) => entry.linkId !== undefined);
+}
+/** The requested nodes that exist; Figma answers deleted or unknown ids with `null` (dropped). */
+export async function fetchFigmaNodeSummaries(fileKey, nodeIds, context) {
+    if (nodeIds.length === 0)
+        return [];
+    const endpoint = figmaFileEndpoint(fileKey, '/nodes');
+    endpoint.searchParams.set('ids', nodeIds.join(','));
+    endpoint.searchParams.set('depth', '1');
+    const body = await requestFigmaApi(endpoint, context, {
+        scope: 'file_content:read',
+        errorMessage: 'Figma returned an invalid response.'
+    });
+    const nodes = record(body.nodes);
+    if (!nodes)
         throw new SourceImportError('invalid-response', 'Figma returned an invalid response.');
+    const summaries = [];
+    for (const nodeId of nodeIds) {
+        if (nodes[nodeId] === null)
+            continue;
+        const document = record(record(nodes[nodeId])?.document);
+        if (!document || typeof document.name !== 'string' || typeof document.type !== 'string') {
+            throw new SourceImportError('invalid-response', 'Figma did not return the requested node.');
+        }
+        summaries.push({ nodeId, nodeName: document.name, nodeType: document.type });
     }
-    return body.document;
+    return summaries;
 }
-export async function resolveTagToNode(fileKey, tag, context) {
-    const document = await fetchFigmaDocument(fileKey, context);
-    const matches = figmaDocumentNodes(document).filter((node) => node.tag === tag);
-    if (matches.length === 0) {
-        throw new SourceImportError('not-found', `No Figma node is tagged "${tag}" in this file.`);
-    }
-    if (matches.length > 1) {
-        throw new SourceImportError('ambiguous-tag', `More than one Figma node is tagged "${tag}" in this file.`);
-    }
-    return matches[0].nodeId;
+export async function createFigmaTagLink(fileKey, nodeId, tag, context) {
+    await requestFigmaApi(new URL('https://api.figma.com/v1/dev_resources'), context, {
+        scope: 'file_dev_resources:write',
+        errorMessage: 'Figma could not create the tag link.',
+        method: 'POST',
+        body: { dev_resources: [{ ...fundusTagLink(tag), file_key: fileKey, node_id: nodeId }] }
+    });
 }
-async function materialize(source, context) {
-    const token = context.config.import.figma.token;
-    if (!token) {
-        throw new SourceImportError('not-configured', 'Figma access is not configured.');
-    }
-    const endpoint = new URL(`https://api.figma.com/v1/images/${encodeURIComponent(source.fileKey)}`);
-    endpoint.searchParams.set('ids', source.nodeId);
-    endpoint.searchParams.set('format', source.format);
-    endpoint.searchParams.set('scale', String(source.scale));
-    const jsonBytes = await fetchWithDeadline(context.fetch, endpoint, { redirect: 'error', headers: { 'X-Figma-Token': token } }, async (response) => new Uint8Array(await response.arrayBuffer()));
-    let payload;
-    try {
-        payload = JSON.parse(new TextDecoder().decode(jsonBytes));
-    }
-    catch {
-        throw new SourceImportError('invalid-response', 'Figma returned an invalid response.');
+export async function deleteFigmaDevResource(fileKey, linkId, context) {
+    await requestFigmaApi(figmaFileEndpoint(fileKey, `/dev_resources/${encodeURIComponent(linkId)}`), context, {
+        scope: 'file_dev_resources:write',
+        errorMessage: 'Figma could not delete the tag link.',
+        method: 'DELETE'
+    });
+}
+/** Export URLs for the nodes in one `/images` call; `null` for a node Figma cannot render. */
+async function exportImageUrls(fileKey, nodeIds, scale, context) {
+    const endpoint = new URL(`https://api.figma.com/v1/images/${encodeURIComponent(fileKey)}`);
+    endpoint.searchParams.set('ids', nodeIds.join(','));
+    endpoint.searchParams.set('format', 'png');
+    endpoint.searchParams.set('scale', String(scale));
+    const body = await requestFigmaApi(endpoint, context, {
+        scope: 'file_content:read',
+        errorMessage: 'Figma could not render this node.'
+    });
+    const images = record(body.images);
+    const urls = {};
+    for (const nodeId of nodeIds) {
+        if (!images || !Object.hasOwn(images, nodeId)) {
+            throw new SourceImportError('invalid-response', 'Figma did not return the requested node.');
+        }
+        const imageUrl = images[nodeId];
+        urls[nodeId] = typeof imageUrl === 'string' && imageUrl.length > 0 ? imageUrl : null;
     }
-    const body = record(payload);
-    if (!body || body.err || (typeof body.status === 'number' && body.status >= 400)) {
-        throw new SourceImportError('invalid-response', 'Figma could not render this node.');
+    return urls;
+}
+/**
+ * The one renderable node carrying `tag`. All candidates go into a single
+ * `/images` call, which answers deleted nodes with `null`; a live but
+ * unrenderable second candidate therefore goes unnoticed.
+ */
+export async function resolveTaggedNode(fileKey, tag, scale, context) {
+    const candidates = [
+        ...new Set((await listFigmaTagEntries(fileKey, context))
+            .filter((entry) => entry.tag === tag)
+            .map((entry) => entry.nodeId))
+    ];
+    if (candidates.length === 0) {
+        throw new SourceImportError('not-found', `No Figma node is tagged "${tag}" in this file.`);
     }
-    const images = record(body.images);
-    if (!images || !Object.hasOwn(images, source.nodeId)) {
-        throw new SourceImportError('invalid-response', 'Figma did not return the requested node.');
+    const urls = await exportImageUrls(fileKey, candidates, scale, context);
+    const live = candidates.flatMap((nodeId) => {
+        const imageUrl = urls[nodeId];
+        return imageUrl ? [{ nodeId, imageUrl }] : [];
+    });
+    if (live.length === 0) {
+        throw new SourceImportError('not-found', `Every Figma node tagged "${tag}" (${candidates.join(', ')}) is deleted or cannot be rendered.`);
     }
-    const imageUrl = images[source.nodeId];
-    if (typeof imageUrl !== 'string' || imageUrl.length === 0) {
-        throw new SourceImportError('invalid-response', 'Figma could not render the requested node.');
+    if (live.length > 1) {
+        throw new SourceImportError('ambiguous-tag', `More than one Figma node is tagged "${tag}" in this file (${live.map((node) => node.nodeId).join(', ')}).`);
     }
+    return live[0];
+}
+async function downloadRaw(source, imageUrl, context) {
     const bytes = await downloadExport(context.httpsTransport ?? requestPinnedHttps, imageUrl);
     await validatePng(bytes);
     const importSource = { importer: 'figma', parameters: source };
     return { bytes, extension: 'png', importSource };
 }
+async function importNode(source, context) {
+    const urls = await exportImageUrls(source.fileKey, [source.nodeId], source.scale, context);
+    const imageUrl = urls[source.nodeId];
+    if (!imageUrl) {
+        throw new SourceImportError('invalid-response', 'Figma could not render the requested node.');
+    }
+    return downloadRaw(source, imageUrl, context);
+}
+async function importTag(source, context) {
+    const { nodeId, imageUrl } = await resolveTaggedNode(source.fileKey, source.fundusTag, source.scale, context);
+    return downloadRaw({ ...source, nodeId }, imageUrl, context);
+}
 export const figmaSourceImporter = {
     kind: 'figma',
     label: 'Figma',
@@ -495,18 +578,16 @@ export const figmaSourceImporter = {
             if (!fileKey) {
                 throw new SourceImportError('not-configured', 'Figma tag import needs a fileKey or import.figma.defaultFileKey in fundus.config.');
             }
-            const nodeId = await resolveTagToNode(fileKey, input.tag, context);
-            return materialize({
+            return importTag({
                 mode: 'tag',
                 fileKey,
                 fundusTag: input.tag,
-                nodeId,
                 format: 'png',
                 scale: input.scale ?? context.config.import.figma.defaults.scale
             }, context);
         }
         const parsed = parseFigmaSelectionUrl(input.url);
-        return materialize({
+        return importNode({
             fileKey: parsed.fileKey,
             nodeId: parsed.nodeId,
             format: 'png',
@@ -515,10 +596,9 @@ export const figmaSourceImporter = {
     },
     validateSourceParameters: validateFigmaSourceParameters,
     async reimportRaw(source, context) {
-        if (source.mode === 'tag') {
-            const nodeId = await resolveTagToNode(source.fileKey, source.fundusTag, context);
-            return materialize({ ...source, nodeId }, context);
-        }
-        return materialize(source, context);
+        // The stored nodeId is not consulted: the tag link decides where the tag lives now.
+        if (source.mode === 'tag')
+            return importTag(source, context);
+        return importNode(source, context);
     }
 };

package/dist/server/operations.d.ts

@@ -42,6 +42,13 @@ export declare class FundusOperations {
     openUsageLocation(token: unknown): Promise<void>;
     /** Read-only state snapshot, serialized with mutations but never processing or writing. */
     state(): Promise<FundusStateDto>;
+    /**
+     * Fill the image-fingerprint and proxy-probe caches without scanning raws or
+     * joining the operation queue, so an early editor reconcile shares this
+     * in-flight work instead of waiting behind it. Both caches are keyed by
+     * content, so a concurrent mutation can only make an entry unused.
+     */
+    warmCaches(): Promise<void>;
     /** Reconcile only changes that are safe without a user decision: unique moves and deletions. */
     reconcileRawState(): Promise<FundusStateDto>;
     /** Adopt an already-existing raw file without copying, renaming, or deleting it. */

package/dist/server/operations.js

@@ -11,7 +11,7 @@ import { assetIdError, allDeliveredAssetIds, canonicalizeParameters, collectAllR
 import { LibraryStore } from './library-store.js';
 import { generateManifestModules, locateGeneratedAssetDeclaration, manifestModuleFileName } from './codegen.js';
 import { descriptorsByType, serverPluginForType, serverPluginsByType } from './plugins.js';
-import { processAssets, readCurrentProxy } from './processing/processor.js';
+import { processAssets, ProxyInfoCache, readCurrentProxy } from './processing/processor.js';
 import { encodeRelativePathForUrl } from './folder-filesystem.js';
 import { classifyRawDirectory, verifyStableRawFile } from './raw-reconciliation.js';
 import { rawSafetyIssues } from './raw-safety.js';
@@ -19,6 +19,7 @@ import { serverImporters } from './importers.js';
 import { SourceImportError } from './importers/contract.js';
 import { validateFigmaSourceParameters } from './importers/figma.js';
 import { currentGitBranch, gitAssetChanges } from './git.js';
+import { IO_CONCURRENCY, mapConcurrent } from './concurrency.js';
 import { FundusUsageAnalyzer, usageSnapshotRevision } from './usage.js';
 import { ImageDuplicateDetector } from './image-duplicates.js';
 /**
@@ -71,6 +72,7 @@ export class FundusOperations {
     #importers;
     #usageAnalyzer;
     #duplicateDetector = new ImageDuplicateDetector();
+    #proxyInfoCache = new ProxyInfoCache();
     #operationQueue = Promise.resolve();
     #pipelineQueue = Promise.resolve();
     constructor(config, registry = serverPluginsByType, importerRegistry = serverImporters) {
@@ -180,6 +182,20 @@ export class FundusOperations {
         const classification = await this.#classifyRawDirectory(library);
         return this.#snapshotState(library, classification);
     }
+    /**
+     * Fill the image-fingerprint and proxy-probe caches without scanning raws or
+     * joining the operation queue, so an early editor reconcile shares this
+     * in-flight work instead of waiting behind it. Both caches are keyed by
+     * content, so a concurrent mutation can only make an entry unused.
+     */
+    async warmCaches() {
+        const library = await this.#store.read();
+        const delivered = allDeliveredAssetIds(computeLibraryMembership(library, collectAllReferences(library, descriptorsByType(this.#registry))));
+        await Promise.all([
+            this.#duplicateDetector.find(library, this.#config.rawDir),
+            mapConcurrent([...delivered].sort(compareCodeUnits), IO_CONCURRENCY, (assetId) => this.#proxyState(assetId, library.assets[assetId], delivered))
+        ]);
+    }
     /** Reconcile only changes that are safe without a user decision: unique moves and deletions. */
     reconcileRawState() {
         return this.#enqueueOperation(async () => {
@@ -921,15 +937,42 @@ export class FundusOperations {
             state: await this.#snapshotState(latestLibrary, latestClassification, pipelineIssues)
         };
     }
+    async #proxyState(assetId, record, delivered) {
+        if (!delivered.has(assetId))
+            return { proxy: null };
+        try {
+            const currentProxy = await readCurrentProxy(assetId, record, this.#config, this.#registry, this.#proxyInfoCache);
+            if (!currentProxy) {
+                return {
+                    proxy: null,
+                    warning: 'Proxy is stale or missing — it will be (re)processed on the next save.'
+                };
+            }
+            return {
+                proxy: {
+                    url: `/files/proxy/${encodeRelativePathForUrl(currentProxy.relativePath)}`,
+                    upToDate: true,
+                    ...currentProxy
+                }
+            };
+        }
+        catch (cause) {
+            return { proxy: null, warning: cause instanceof Error ? cause.message : String(cause) };
+        }
+    }
     async #buildState(library, issues, classification) {
-        const [gitBranch, changedGitAssets] = await Promise.all([
-            currentGitBranch(this.#config.projectRoot),
-            gitAssetChanges(this.#config.projectRoot, this.#config.library, library)
-        ]);
         const referencesByAsset = collectAllReferences(library, descriptorsByType(this.#registry));
-        const duplicatesByAsset = await this.#duplicateDetector.find(library, this.#config.rawDir);
         const membershipByManifest = computeLibraryMembership(library, referencesByAsset);
         const delivered = allDeliveredAssetIds(membershipByManifest);
+        const assetIds = Object.keys(library.assets).sort(compareCodeUnits);
+        // Independent I/O-bound reads; run together so large libraries load in parallel.
+        const [gitBranch, changedGitAssets, duplicatesByAsset, proxies] = await Promise.all([
+            currentGitBranch(this.#config.projectRoot),
+            gitAssetChanges(this.#config.projectRoot, this.#config.library, library),
+            this.#duplicateDetector.find(library, this.#config.rawDir),
+            mapConcurrent(assetIds, IO_CONCURRENCY, (assetId) => this.#proxyState(assetId, library.assets[assetId], delivered))
+        ]);
+        this.#proxyInfoCache.retain(delivered);
         // Per asset: the manifests it is a passive member of, with attribution.
         const passiveManifestsByAsset = new Map();
         for (const manifestName of Object.keys(library.manifests).sort(compareCodeUnits)) {
@@ -954,7 +997,7 @@ export class FundusOperations {
             requiredByAsset.set(dependency.id, [...dependency.sources]);
         }
         const assets = [];
-        for (const assetId of Object.keys(library.assets).sort(compareCodeUnits)) {
+        for (const [index, assetId] of assetIds.entries()) {
             const record = library.assets[assetId];
             const warnings = [];
             for (const issue of issues) {
@@ -971,25 +1014,9 @@ export class FundusOperations {
             if (record.importSource && !this.#importers.has(record.importSource.importer)) {
                 warnings.push(`Importer "${record.importSource.importer}" is unavailable; the local raw file remains usable.`);
             }
-            let proxy = null;
-            if (delivered.has(assetId)) {
-                try {
-                    const currentProxy = await readCurrentProxy(assetId, record, this.#config, this.#registry);
-                    if (currentProxy) {
-                        proxy = {
-                            url: `/files/proxy/${encodeRelativePathForUrl(currentProxy.relativePath)}`,
-                            upToDate: true,
-                            ...currentProxy
-                        };
-                    }
-                    else {
-                        warnings.push('Proxy is stale or missing — it will be (re)processed on the next save.');
-                    }
-                }
-                catch (cause) {
-                    warnings.push(cause instanceof Error ? cause.message : String(cause));
-                }
-            }
+            const { proxy, warning: proxyWarning } = proxies[index];
+            if (proxyWarning)
+                warnings.push(proxyWarning);
             assets.push({
                 id: assetId,
                 type: record.type,

package/dist/server/processing/processor.d.ts

@@ -1,3 +1,19 @@
+/**
+ * The processing pipeline: every delivered asset gets exactly one
+ * proxy named `<assetId>.<jobHash>.<extension>`. Delivered = explicit or
+ * passive member of ≥ 1 manifest (codegen inlines referenced
+ * entries, so a passive member's proxy must exist even when the asset is in
+ * no manifest itself). Because the name is computable without running the job,
+ * staleness is a name check: expected name exists → up to date, else →
+ * process. Afterwards, files in the proxy directory that no asset expects are
+ * pruned.
+ *
+ * Type-agnostic: every per-type decision (preset resolution, extension, the
+ * sharp/ffmpeg step, proxy probing) lives on the server plugins; this module
+ * only consults the registry — which it takes as a parameter, so tests can
+ * drive the pipeline with fixture asset types.
+ */
+import { type Stats } from 'node:fs';
 import { type AssetId, type AssetRecord, type Library } from '../../core/index.js';
 import type { ResolvedFundusConfig } from '../config-loader.js';
 import type { AssetProxyInfo, ProxyOutputInfo, ServerPluginRegistry } from '../plugins/contract.js';
@@ -35,8 +51,20 @@ export declare function expectedProxyRelativePath(assetId: string, record: Asset
  * strategy: image-backed proxies via sharp, media proxies via ffprobe.
  */
 export declare function readProxyOutputInfo(record: AssetRecord, proxyPath: string, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): Promise<ProxyOutputInfo>;
+/**
+ * Probed proxy output info, reused across editor snapshots so unchanged proxies
+ * skip sharp and ffprobe. Proxy names are content-addressed, so an entry stays
+ * valid while the proxy and the raw source handed to the probe keep their stat
+ * identity. In-flight probes are shared, so concurrent readers never probe twice.
+ */
+export declare class ProxyInfoCache {
+    #private;
+    read(assetId: AssetId, proxyPath: string, proxyStat: Stats, rawPath: string, probe: () => Promise<ProxyOutputInfo>): Promise<ProxyOutputInfo>;
+    /** Forget assets that no longer exist or are no longer delivered. */
+    retain(assetIds: ReadonlySet<AssetId>): void;
+}
 /** Read one asset's current proxy projection, or null when its expected file is absent. */
-export declare function readCurrentProxy(assetId: string, record: AssetRecord, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): Promise<AssetProxyInfo | null>;
+export declare function readCurrentProxy(assetId: string, record: AssetRecord, config: ResolvedFundusConfig, registry?: ServerPluginRegistry, cache?: ProxyInfoCache): Promise<AssetProxyInfo | null>;
 /**
  * The delivered set: every explicit or passive member of ≥ 1 manifest —
  * derived by the shared membership computation. Assets outside

package/dist/server/processing/processor.js

@@ -65,17 +65,54 @@ export function expectedProxyRelativePath(assetId, record, config, registry = se
 export async function readProxyOutputInfo(record, proxyPath, config, registry = serverPluginsByType) {
     return serverPluginForType(record.type, registry).readProxyInfo(proxyPath, config, join(config.rawDir, record.raw));
 }
+function statIdentity(value) {
+    return `${value.dev}:${value.ino}:${value.size}:${value.mtimeMs}:${value.ctimeMs}`;
+}
+/**
+ * Probed proxy output info, reused across editor snapshots so unchanged proxies
+ * skip sharp and ffprobe. Proxy names are content-addressed, so an entry stays
+ * valid while the proxy and the raw source handed to the probe keep their stat
+ * identity. In-flight probes are shared, so concurrent readers never probe twice.
+ */
+export class ProxyInfoCache {
+    #entries = new Map();
+    async read(assetId, proxyPath, proxyStat, rawPath, probe) {
+        const rawIdentity = await stat(rawPath).then(statIdentity, () => 'missing');
+        const identity = `${proxyPath}|${statIdentity(proxyStat)}|${rawIdentity}`;
+        const cached = this.#entries.get(assetId);
+        if (cached?.identity === identity)
+            return cached.info;
+        const entry = { identity, info: probe() };
+        this.#entries.set(assetId, entry);
+        try {
+            return await entry.info;
+        }
+        catch (cause) {
+            if (this.#entries.get(assetId) === entry)
+                this.#entries.delete(assetId);
+            throw cause;
+        }
+    }
+    /** Forget assets that no longer exist or are no longer delivered. */
+    retain(assetIds) {
+        for (const assetId of this.#entries.keys()) {
+            if (!assetIds.has(assetId))
+                this.#entries.delete(assetId);
+        }
+    }
+}
 /** Read one asset's current proxy projection, or null when its expected file is absent. */
-export async function readCurrentProxy(assetId, record, config, registry = serverPluginsByType) {
+export async function readCurrentProxy(assetId, record, config, registry = serverPluginsByType, cache) {
     const fileName = expectedProxyFileName(assetId, record, config, registry);
     const relativePath = expectedProxyRelativePath(assetId, record, config, registry);
     const proxyPath = join(config.proxyDir, relativePath);
     if (!existsSync(proxyPath))
         return null;
-    const [outputInfo, proxyStat] = await Promise.all([
-        readProxyOutputInfo(record, proxyPath, config, registry),
-        stat(proxyPath)
-    ]);
+    const proxyStat = await stat(proxyPath);
+    const probe = () => readProxyOutputInfo(record, proxyPath, config, registry);
+    const outputInfo = cache
+        ? await cache.read(assetId, proxyPath, proxyStat, join(config.rawDir, record.raw), probe)
+        : await probe();
     return { assetId, fileName, relativePath, ...outputInfo, fileSize: proxyStat.size };
 }
 /**