@anvilkit/plugin-asset-manager 0.1.8 → 0.1.10

package/dist/plugin.js

@@ -14,6 +14,8 @@ import { createIRAssetResolver } from "./utils/resolver.js";
 import { createStudioAssetSource } from "./utils/studio-asset-source.js";
 import { validateUploadResult } from "./utils/validate-upload-result.js";
 import { ASSET_MANAGER_VERSION } from "./version.js";
+const ASSET_MANAGER_UPLOADED_EVENT = "asset-manager:uploaded";
+const ASSET_MANAGER_ERROR_EVENT = "asset-manager:error";
 const META = {
     ...config,
     version: ASSET_MANAGER_VERSION,
@@ -28,7 +30,10 @@ function createAssetManagerPlugin(options = {}) {
     const assetResolver = createIRAssetResolver({
         registry,
         dataUrlAllowlistOptIn: normalizedOptions.dataUrlAllowlistOptIn,
-        allowMixedScriptHostnames: normalizedOptions.allowMixedScriptHostnames
+        allowMixedScriptHostnames: normalizedOptions.allowMixedScriptHostnames,
+        ...normalizedOptions.transformResolver ? {
+            transformResolver: normalizedOptions.transformResolver
+        } : {}
     });
     return {
         meta: META,
@@ -50,9 +55,11 @@ function createAssetManagerPlugin(options = {}) {
                         tokenByContext.set(initCtx, token);
                         initCtx.registerAssetResolver(assetResolver);
                         const upload = (file, opts)=>uploadAsset(initCtx, file, opts?.signal);
+                        const onDelete = createAssetDeletedHandler(normalizedOptions, !hostOwnsAssetPlane(normalizedOptions));
                         const studioAssetSource = createStudioAssetSource({
                             registry,
                             upload,
+                            onDelete,
                             ...normalizedOptions.getThumbnail ? {
                                 getThumbnail: normalizedOptions.getThumbnail
                             } : {}
@@ -99,39 +106,146 @@ async function uploadAsset(ctx, file, signal) {
     const { options, registry } = state;
     try {
         validateSelectedFile(file, options);
-        const uploadResult = await options.uploader(file, signal ? {
-            signal
-        } : void 0);
+        await assertSniffedContentType(file, options, signal);
+        let contentHash;
+        if (true === options.dedupe) {
+            if (signal?.aborted) throw makePluginAbortError();
+            contentHash = await computeFileHash(file);
+            if (signal?.aborted) throw makePluginAbortError();
+            if (void 0 !== contentHash) {
+                const existing = registry.list().find((entry)=>entry.meta?.hash === contentHash);
+                if (void 0 !== existing) {
+                    dispatchAssetReference(ctx, existing);
+                    ctx.emit(ASSET_MANAGER_UPLOADED_EVENT, {
+                        asset: existing,
+                        reference: createAssetReference(existing.id)
+                    });
+                    return existing;
+                }
+            }
+        }
+        if (signal?.aborted) throw makePluginAbortError();
+        const uploadResult = await performUpload(options, file, signal);
         if (signal?.aborted) throw makePluginAbortError();
         const validated = validateUploadResult(mergeUploadMeta(uploadResult, file), options);
-        const tagged = withDerivedTags(validated, file);
+        const hashed = void 0 !== contentHash ? {
+            ...validated,
+            meta: {
+                ...validated.meta ?? {},
+                hash: contentHash
+            }
+        } : validated;
+        const tagged = withDerivedTags(hashed, file);
         const stored = registry.register(tagged);
         dispatchAssetReference(ctx, stored);
-        ctx.emit("asset-manager:uploaded", {
+        const payload = {
             asset: stored,
             reference: createAssetReference(stored.id)
-        });
+        };
+        ctx.emit(ASSET_MANAGER_UPLOADED_EVENT, payload);
         return stored;
     } catch (error) {
         if (isAbortLikeError(error) || signal?.aborted) throw error;
         const normalizedError = error instanceof AssetValidationError ? error : new AssetValidationError("UPLOAD_FAILED", error instanceof Error ? error.message : String(error), {
             cause: error
         });
-        ctx.emit("asset-manager:error", {
+        const payload = {
             code: normalizedError.code,
             message: normalizedError.message
-        });
+        };
+        ctx.emit(ASSET_MANAGER_ERROR_EVENT, payload);
         ctx.log("error", normalizedError.message, {
             code: normalizedError.code
         });
         throw normalizedError;
     }
 }
+const DEFAULT_RESUMABLE_THRESHOLD = 8388608;
+async function performUpload(options, file, signal) {
+    const { resumable } = options;
+    if (void 0 !== resumable && shouldUseResumable(resumable, file)) {
+        if (signal?.aborted) throw makePluginAbortError();
+        const { runResumableUpload } = await import("./utils/run-resumable-upload.js");
+        return runResumableUpload(resumable.adapter, file, {
+            ...void 0 !== resumable.partSize ? {
+                partSize: resumable.partSize
+            } : {},
+            ...resumable.sessionStore ? {
+                sessionStore: resumable.sessionStore
+            } : {},
+            ...signal ? {
+                signal
+            } : {}
+        });
+    }
+    return options.uploader(file, signal ? {
+        signal
+    } : void 0);
+}
+function shouldUseResumable(resumable, file) {
+    const threshold = resumable.threshold ?? resumable.partSize ?? DEFAULT_RESUMABLE_THRESHOLD;
+    return file.size >= threshold;
+}
+function createAssetDeletedHandler(options, callHostHook) {
+    return async (asset)=>{
+        revokeBlobUrl(asset.url);
+        if (callHostHook) await options.onAssetDeleted?.(asset);
+    };
+}
+const HOST_ASSET_PLANE_METHODS = [
+    "list",
+    "remove",
+    "replace",
+    "rename",
+    "move"
+];
+function hostOwnsAssetPlane(options) {
+    const ds = options.dataSource;
+    if (void 0 === ds) return false;
+    return HOST_ASSET_PLANE_METHODS.every((method)=>"function" == typeof ds[method]);
+}
+function revokeBlobUrl(url) {
+    if (url.startsWith("blob:") && "u" > typeof URL && "function" == typeof URL.revokeObjectURL) URL.revokeObjectURL(url);
+}
+async function computeFileHash(file) {
+    const subtle = globalThis.crypto?.subtle;
+    if (void 0 === subtle || "function" != typeof file.arrayBuffer) return;
+    try {
+        const digest = await subtle.digest("SHA-256", await file.arrayBuffer());
+        const bytes = new Uint8Array(digest);
+        let hex = "";
+        for (const byte of bytes)hex += byte.toString(16).padStart(2, "0");
+        return hex;
+    } catch  {
+        return;
+    }
+}
+async function assertSniffedContentType(file, options, signal) {
+    if (true !== options.sniffContent) return;
+    const declared = normalizeMime(file.type);
+    if ("" === declared || "application/octet-stream" === declared) return;
+    if (signal?.aborted) throw makePluginAbortError();
+    const { sniffFileMime } = await import("./utils/sniff-file-type.js");
+    const sniffed = await sniffFileMime(file);
+    if (signal?.aborted) throw makePluginAbortError();
+    if (void 0 === sniffed) return;
+    if (normalizeMime(sniffed) !== declared) throw new AssetValidationError("CONTENT_TYPE_MISMATCH", `File content was detected as "${sniffed}" but its declared type is "${file.type}".`);
+}
+function normalizeMime(mime) {
+    const lower = mime.trim().toLowerCase();
+    return "image/jpg" === lower ? "image/jpeg" : lower;
+}
 function validateSelectedFile(file, options) {
     if (void 0 !== options.maxFileSize && file.size > options.maxFileSize) throw new AssetValidationError("FILE_TOO_LARGE", `File size ${file.size} bytes exceeds the configured maxFileSize of ${options.maxFileSize} bytes.`);
-    if (options.acceptedMimeTypes && options.acceptedMimeTypes.length > 0 && !mimeTypeMatches(file.type, options.acceptedMimeTypes)) {
-        const mimeType = file.type || "unknown";
-        throw new AssetValidationError("UNSUPPORTED_MIME_TYPE", `File MIME type "${mimeType}" is not in acceptedMimeTypes.`);
+    const acceptedMimeTypes = options.acceptedMimeTypes ?? [];
+    const acceptedFileExtensions = options.acceptedFileExtensions ?? [];
+    const hasMimeAllowlist = acceptedMimeTypes.length > 0;
+    const hasExtensionAllowlist = acceptedFileExtensions.length > 0;
+    if (hasMimeAllowlist && "" !== file.type && !mimeTypeMatches(file.type, acceptedMimeTypes)) throw new AssetValidationError("UNSUPPORTED_MIME_TYPE", `File MIME type "${file.type}" is not in acceptedMimeTypes.`);
+    if (hasMimeAllowlist && "" === file.type && !hasExtensionAllowlist) throw new AssetValidationError("UNSUPPORTED_MIME_TYPE", 'File MIME type "unknown" is not in acceptedMimeTypes.');
+    if (hasExtensionAllowlist && !fileExtensionMatches(file.name, acceptedFileExtensions)) {
+        const extension = file.name.includes(".") ? file.name.slice(file.name.lastIndexOf(".")).toLowerCase() : "unknown";
+        throw new AssetValidationError("UNSUPPORTED_FILE_EXTENSION", `File extension "${extension}" is not in acceptedFileExtensions.`);
     }
 }
 function getRuntimeState(ctx) {
@@ -149,15 +263,20 @@ async function loadRichSource(ctx, registry, upload, options) {
         import("./sources/composite-source.js")
     ]);
     const maxDepth = "object" == typeof options.folders ? options.folders.maxDepth : void 0;
+    const allowMove = "object" == typeof options.folders ? options.folders.allowMove : void 0;
     const resolved = resolveDataSource({
         registry,
         upload,
+        onDelete: createAssetDeletedHandler(options, !hostOwnsAssetPlane(options)),
         ...options.dataSource ? {
             hostDataSource: options.dataSource
         } : {},
         ...void 0 !== maxDepth ? {
             maxDepth
         } : {},
+        ...void 0 !== allowMove ? {
+            allowMove
+        } : {},
         warn: (message)=>ctx.log("warn", message)
     });
     const providers = [
@@ -190,6 +309,11 @@ function normalizeOptions(options) {
             acceptedMimeTypes: Object.freeze([
                 ...options.acceptedMimeTypes
             ])
+        } : {},
+        ...options.acceptedFileExtensions ? {
+            acceptedFileExtensions: Object.freeze([
+                ...options.acceptedFileExtensions
+            ])
         } : {}
     };
 }
@@ -241,6 +365,16 @@ function mimeTypeMatches(input, acceptedMimeTypes) {
         return input === accepted;
     });
 }
+function fileExtensionMatches(name, acceptedFileExtensions) {
+    const lowerName = name.toLowerCase();
+    if ("" === lowerName) return false;
+    return acceptedFileExtensions.some((accepted)=>{
+        const trimmed = accepted.trim().toLowerCase();
+        if ("" === trimmed) return false;
+        const extension = trimmed.startsWith(".") ? trimmed : `.${trimmed}`;
+        return lowerName.endsWith(extension);
+    });
+}
 function dispatchAssetReference(ctx, asset) {
     const currentData = ctx.getData();
     const assetsView = currentData.assets;
@@ -294,4 +428,4 @@ function isAbortLikeError(error) {
     const name = error.name;
     return "AbortError" === name;
 }
-export { createAssetManagerPlugin, createAssetReference, getAssetRegistry, uploadAsset, validateSelectedFile };
+export { ASSET_MANAGER_ERROR_EVENT, ASSET_MANAGER_UPLOADED_EVENT, createAssetManagerPlugin, createAssetReference, getAssetRegistry, uploadAsset, validateSelectedFile };

package/dist/sources/composite-source.cjs

@@ -91,6 +91,9 @@ function createCompositeAssetSource(options) {
                 } : {},
                 ...page.sourceCursors ? {
                     sourceCursors: page.sourceCursors
+                } : {},
+                ...page.sourceErrors ? {
+                    sourceErrors: page.sourceErrors
                 } : {}
             };
         },

package/dist/sources/composite-source.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-source.d.cts","sourceRoot":"","sources":["../../src/sources/composite-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAIX,iBAAiB,EAEjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EACX,uBAAuB,EACvB,QAAQ,EACR,MAAM,yBAAyB,CAAC;AAMjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,WAAW,iCAAiC;IACjD,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;IACpE,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC9D,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5E,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/D,YAAY,CACX,EAAE,EAAE,QAAQ,EACZ,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1E,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,iCAAiC,GACxC,oBAAoB,CAiItB"}
+{"version":3,"file":"composite-source.d.cts","sourceRoot":"","sources":["../../src/sources/composite-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAIX,iBAAiB,EAEjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EACX,uBAAuB,EACvB,QAAQ,EACR,MAAM,yBAAyB,CAAC;AAMjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,WAAW,iCAAiC;IACjD,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;IACpE,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC9D,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5E,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/D,YAAY,CACX,EAAE,EAAE,QAAQ,EACZ,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1E,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,iCAAiC,GACxC,oBAAoB,CAkItB"}

package/dist/sources/composite-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-source.d.ts","sourceRoot":"","sources":["../../src/sources/composite-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAIX,iBAAiB,EAEjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EACX,uBAAuB,EACvB,QAAQ,EACR,MAAM,yBAAyB,CAAC;AAMjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,WAAW,iCAAiC;IACjD,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;IACpE,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC9D,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5E,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/D,YAAY,CACX,EAAE,EAAE,QAAQ,EACZ,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1E,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,iCAAiC,GACxC,oBAAoB,CAiItB"}
+{"version":3,"file":"composite-source.d.ts","sourceRoot":"","sources":["../../src/sources/composite-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAIX,iBAAiB,EAEjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EACX,uBAAuB,EACvB,QAAQ,EACR,MAAM,yBAAyB,CAAC;AAMjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,WAAW,iCAAiC;IACjD,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;IACpE,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC9D,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5E,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/D,YAAY,CACX,EAAE,EAAE,QAAQ,EACZ,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1E,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,iCAAiC,GACxC,oBAAoB,CAkItB"}

package/dist/sources/composite-source.js

@@ -59,6 +59,9 @@ function createCompositeAssetSource(options) {
                 } : {},
                 ...page.sourceCursors ? {
                     sourceCursors: page.sourceCursors
+                } : {},
+                ...page.sourceErrors ? {
+                    sourceErrors: page.sourceErrors
                 } : {}
             };
         },

package/dist/sources/federated-search.cjs

@@ -70,10 +70,10 @@ function createLocalProvider(source, registry, label = "assetManager.source.libr
             folders: true
         },
         listThemes: ()=>[],
-        search: (filter, page, signal)=>source.list(void 0 !== page ? {
+        search: (filter, page, signal)=>source.list({
                 ...filter,
                 cursor: page
-            } : filter, signal),
+            }, signal),
         pickResult: async (asset)=>registry.get(asset.id) ?? {
                 id: asset.id,
                 url: asset.url
@@ -96,7 +96,7 @@ function compareEntries(a, b, field) {
     if ("number" == typeof ka && "number" == typeof kb) return ka - kb;
     return String(ka).localeCompare(String(kb));
 }
-function mergePages(pages, filter, carryForward = {}) {
+function mergePages(pages, filter, carryForward = {}, sourceErrors = {}) {
     const field = filter.sort?.field ?? "recent";
     const comparable = "name" === field || "size" === field || "kind" === field;
     const items = pages.flatMap((p)=>[
@@ -126,22 +126,59 @@ function mergePages(pages, filter, carryForward = {}) {
         items: Object.freeze(items),
         total,
         nextCursor: hasNext ? encodeCompositeCursor(next) : void 0,
-        sourceCursors
+        sourceCursors,
+        ...Object.keys(sourceErrors).length > 0 ? {
+            sourceErrors: Object.freeze(sourceErrors)
+        } : {}
     };
 }
+function describeReason(reason) {
+    if (reason instanceof Error) {
+        const code = reason.code;
+        return {
+            message: reason.message || reason.name,
+            ..."string" == typeof code ? {
+                code
+            } : {}
+        };
+    }
+    if (null !== reason && "object" == typeof reason) {
+        const message = reason.message;
+        const code = reason.code;
+        if ("string" == typeof message) return {
+            message,
+            ..."string" == typeof code ? {
+                code
+            } : {}
+        };
+    }
+    return {
+        message: safeString(reason)
+    };
+}
+function safeString(value) {
+    try {
+        return String(value);
+    } catch  {
+        return "Unknown error";
+    }
+}
 async function federatedSearch(input) {
     const { providers, filter, signal } = input;
+    const cursors = decodeCompositeCursor(filter.cursor);
+    const isContinuation = void 0 !== filter.cursor && Object.keys(cursors).length > 0;
     const eligible = providers.filter((p)=>providerCanSatisfy(p, filter));
-    const targets = filter.sources && filter.sources.length > 0 ? eligible.filter((p)=>filter.sources?.includes(p.id)) : eligible;
+    const sourceScoped = filter.sources && filter.sources.length > 0 ? eligible.filter((p)=>filter.sources?.includes(p.id)) : eligible;
+    const targets = isContinuation ? sourceScoped.filter((p)=>void 0 !== cursors[p.id]) : sourceScoped;
     if (0 === targets.length) return {
         items: Object.freeze([]),
         total: 0,
         nextCursor: void 0
     };
-    const cursors = decodeCompositeCursor(filter.cursor);
     const settled = await Promise.allSettled(targets.map((p)=>p.search(filter, cursors[p.id], signal)));
     const ok = [];
     const carryForward = {};
+    const sourceErrors = {};
     settled.forEach((result, index)=>{
         const provider = targets[index];
         if (void 0 === provider) return;
@@ -152,9 +189,10 @@ async function federatedSearch(input) {
         else {
             const incoming = cursors[provider.id];
             if (void 0 !== incoming) carryForward[provider.id] = incoming;
+            sourceErrors[provider.id] = describeReason(result.reason);
         }
     });
-    return mergePages(ok, filter, carryForward);
+    return mergePages(ok, filter, carryForward, sourceErrors);
 }
 exports.createLocalProvider = __webpack_exports__.createLocalProvider;
 exports.decodeCompositeCursor = __webpack_exports__.decodeCompositeCursor;

package/dist/sources/federated-search.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"federated-search.d.cts","sourceRoot":"","sources":["../../src/sources/federated-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAY1D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAErE;AAED,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,MAAM,GAAG,SAAS,GACvB,eAAe,CAUjB;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,WAAW,GACjB,OAAO,CAKT;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,aAAa,EACvB,KAAK,SAAgC,GACnC,mBAAmB,CAqBrB;AAmED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACpC,KAAK,EAAE,oBAAoB,GACzB,OAAO,CAAC,aAAa,CAAC,CAqCxB"}
+{"version":3,"file":"federated-search.d.cts","sourceRoot":"","sources":["../../src/sources/federated-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAY1D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAErE;AAED,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,MAAM,GAAG,SAAS,GACvB,eAAe,CAUjB;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,WAAW,GACjB,OAAO,CAKT;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,aAAa,EACvB,KAAK,SAAgC,GACnC,mBAAmB,CAqBrB;AAyGD,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACpC,KAAK,EAAE,oBAAoB,GACzB,OAAO,CAAC,aAAa,CAAC,CAkDxB"}

package/dist/sources/federated-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"federated-search.d.ts","sourceRoot":"","sources":["../../src/sources/federated-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAY1D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAErE;AAED,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,MAAM,GAAG,SAAS,GACvB,eAAe,CAUjB;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,WAAW,GACjB,OAAO,CAKT;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,aAAa,EACvB,KAAK,SAAgC,GACnC,mBAAmB,CAqBrB;AAmED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACpC,KAAK,EAAE,oBAAoB,GACzB,OAAO,CAAC,aAAa,CAAC,CAqCxB"}
+{"version":3,"file":"federated-search.d.ts","sourceRoot":"","sources":["../../src/sources/federated-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAY1D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAErE;AAED,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,MAAM,GAAG,SAAS,GACvB,eAAe,CAUjB;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,WAAW,GACjB,OAAO,CAKT;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,aAAa,EACvB,KAAK,SAAgC,GACnC,mBAAmB,CAqBrB;AAyGD,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACpC,KAAK,EAAE,oBAAoB,GACzB,OAAO,CAAC,aAAa,CAAC,CAkDxB"}

package/dist/sources/federated-search.js

@@ -34,10 +34,10 @@ function createLocalProvider(source, registry, label = "assetManager.source.libr
             folders: true
         },
         listThemes: ()=>[],
-        search: (filter, page, signal)=>source.list(void 0 !== page ? {
+        search: (filter, page, signal)=>source.list({
                 ...filter,
                 cursor: page
-            } : filter, signal),
+            }, signal),
         pickResult: async (asset)=>registry.get(asset.id) ?? {
                 id: asset.id,
                 url: asset.url
@@ -60,7 +60,7 @@ function compareEntries(a, b, field) {
     if ("number" == typeof ka && "number" == typeof kb) return ka - kb;
     return String(ka).localeCompare(String(kb));
 }
-function mergePages(pages, filter, carryForward = {}) {
+function mergePages(pages, filter, carryForward = {}, sourceErrors = {}) {
     const field = filter.sort?.field ?? "recent";
     const comparable = "name" === field || "size" === field || "kind" === field;
     const items = pages.flatMap((p)=>[
@@ -90,22 +90,59 @@ function mergePages(pages, filter, carryForward = {}) {
         items: Object.freeze(items),
         total,
         nextCursor: hasNext ? encodeCompositeCursor(next) : void 0,
-        sourceCursors
+        sourceCursors,
+        ...Object.keys(sourceErrors).length > 0 ? {
+            sourceErrors: Object.freeze(sourceErrors)
+        } : {}
     };
 }
+function describeReason(reason) {
+    if (reason instanceof Error) {
+        const code = reason.code;
+        return {
+            message: reason.message || reason.name,
+            ..."string" == typeof code ? {
+                code
+            } : {}
+        };
+    }
+    if (null !== reason && "object" == typeof reason) {
+        const message = reason.message;
+        const code = reason.code;
+        if ("string" == typeof message) return {
+            message,
+            ..."string" == typeof code ? {
+                code
+            } : {}
+        };
+    }
+    return {
+        message: safeString(reason)
+    };
+}
+function safeString(value) {
+    try {
+        return String(value);
+    } catch  {
+        return "Unknown error";
+    }
+}
 async function federatedSearch(input) {
     const { providers, filter, signal } = input;
+    const cursors = decodeCompositeCursor(filter.cursor);
+    const isContinuation = void 0 !== filter.cursor && Object.keys(cursors).length > 0;
     const eligible = providers.filter((p)=>providerCanSatisfy(p, filter));
-    const targets = filter.sources && filter.sources.length > 0 ? eligible.filter((p)=>filter.sources?.includes(p.id)) : eligible;
+    const sourceScoped = filter.sources && filter.sources.length > 0 ? eligible.filter((p)=>filter.sources?.includes(p.id)) : eligible;
+    const targets = isContinuation ? sourceScoped.filter((p)=>void 0 !== cursors[p.id]) : sourceScoped;
     if (0 === targets.length) return {
         items: Object.freeze([]),
         total: 0,
         nextCursor: void 0
     };
-    const cursors = decodeCompositeCursor(filter.cursor);
     const settled = await Promise.allSettled(targets.map((p)=>p.search(filter, cursors[p.id], signal)));
     const ok = [];
     const carryForward = {};
+    const sourceErrors = {};
     settled.forEach((result, index)=>{
         const provider = targets[index];
         if (void 0 === provider) return;
@@ -116,8 +153,9 @@ async function federatedSearch(input) {
         else {
             const incoming = cursors[provider.id];
             if (void 0 !== incoming) carryForward[provider.id] = incoming;
+            sourceErrors[provider.id] = describeReason(result.reason);
         }
     });
-    return mergePages(ok, filter, carryForward);
+    return mergePages(ok, filter, carryForward, sourceErrors);
 }
 export { createLocalProvider, decodeCompositeCursor, encodeCompositeCursor, federatedSearch, providerCanSatisfy };

package/dist/sources/provider.d.cts

@@ -9,6 +9,7 @@
 import type { StudioAsset } from "@anvilkit/core/types";
 import type { AssetFilter, AssetListPage, AssetSourceId } from "../types/filter.js";
 import type { UploadResult } from "../types/types.js";
+/** Capability flags advertised by an asset source provider. */
 export interface AssetSourceCapabilities {
     readonly searchable: boolean;
     readonly themed: boolean;
@@ -23,12 +24,14 @@ export interface AssetSourceCapabilities {
      */
     readonly folders?: boolean;
 }
+/** Browse theme exposed by an external asset source provider. */
 export interface AssetTheme {
     readonly id: string;
     /** i18n message key (not inline copy). */
     readonly label: string;
     readonly description?: string;
 }
+/** Read-only external provider contract for searchable asset sources. */
 export interface AssetSourceProvider {
     /** `"unsplash"` | host id. The built-in `"local"` provider wraps the data source. */
     readonly id: AssetSourceId;
@@ -39,7 +42,9 @@ export interface AssetSourceProvider {
         readonly connectSrc?: readonly string[];
         readonly imgSrc?: readonly string[];
     };
+    /** Return browse themes or categories this provider exposes. */
     listThemes(): readonly AssetTheme[] | Promise<readonly AssetTheme[]>;
+    /** Search or browse the provider and return one page of normalized assets. */
     search(query: AssetFilter, page: string | undefined, signal?: AbortSignal): Promise<AssetListPage>;
     /**
      * Convert a browsed result into a real asset (fires the source's

package/dist/sources/provider.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.cts","sourceRoot":"","sources":["../../src/sources/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uBAAuB;IACvB,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IACnC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAC;IAC/C,yFAAyF;IACzF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM;QAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;IACF,UAAU,IAAI,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACrE,MAAM,CACL,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5E"}
+{"version":3,"file":"provider.d.cts","sourceRoot":"","sources":["../../src/sources/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uBAAuB;IACvB,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IACnC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAC;IAC/C,yFAAyF;IACzF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM;QAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;IACF,gEAAgE;IAChE,UAAU,IAAI,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACrE,8EAA8E;IAC9E,MAAM,CACL,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5E"}

package/dist/sources/provider.d.ts

@@ -9,6 +9,7 @@
 import type { StudioAsset } from "@anvilkit/core/types";
 import type { AssetFilter, AssetListPage, AssetSourceId } from "../types/filter.js";
 import type { UploadResult } from "../types/types.js";
+/** Capability flags advertised by an asset source provider. */
 export interface AssetSourceCapabilities {
     readonly searchable: boolean;
     readonly themed: boolean;
@@ -23,12 +24,14 @@ export interface AssetSourceCapabilities {
      */
     readonly folders?: boolean;
 }
+/** Browse theme exposed by an external asset source provider. */
 export interface AssetTheme {
     readonly id: string;
     /** i18n message key (not inline copy). */
     readonly label: string;
     readonly description?: string;
 }
+/** Read-only external provider contract for searchable asset sources. */
 export interface AssetSourceProvider {
     /** `"unsplash"` | host id. The built-in `"local"` provider wraps the data source. */
     readonly id: AssetSourceId;
@@ -39,7 +42,9 @@ export interface AssetSourceProvider {
         readonly connectSrc?: readonly string[];
         readonly imgSrc?: readonly string[];
     };
+    /** Return browse themes or categories this provider exposes. */
     listThemes(): readonly AssetTheme[] | Promise<readonly AssetTheme[]>;
+    /** Search or browse the provider and return one page of normalized assets. */
     search(query: AssetFilter, page: string | undefined, signal?: AbortSignal): Promise<AssetListPage>;
     /**
      * Convert a browsed result into a real asset (fires the source's

package/dist/sources/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/sources/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uBAAuB;IACvB,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IACnC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAC;IAC/C,yFAAyF;IACzF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM;QAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;IACF,UAAU,IAAI,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACrE,MAAM,CACL,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5E"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/sources/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uBAAuB;IACvB,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IACnC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAC;IAC/C,yFAAyF;IACzF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM;QAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;IACF,gEAAgE;IAChE,UAAU,IAAI,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACrE,8EAA8E;IAC9E,MAAM,CACL,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5E"}

package/dist/sources/unsplash/index.d.cts

@@ -12,5 +12,6 @@ import type { AssetSourceProvider } from "../provider.js";
 export declare const UNSPLASH_THEME_FACET = "unsplash:theme";
 /** Enabled when a proxy endpoint or access key is present (or forced via `enabled`). */
 export declare function unsplashEnabled(options: UnsplashSourceOptions): boolean;
+/** Create the Unsplash-backed read-only asset source provider. */
 export declare function createUnsplashProvider(options: UnsplashSourceOptions): AssetSourceProvider;
 //# sourceMappingURL=index.d.cts.map

package/dist/sources/unsplash/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../../src/sources/unsplash/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAc,MAAM,gBAAgB,CAAC;AAYtE,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AASrD,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAKvE;AAMD,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,qBAAqB,GAC5B,mBAAmB,CA0LrB"}
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../../src/sources/unsplash/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAc,MAAM,gBAAgB,CAAC;AAYtE,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AASrD,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAKvE;AAMD,kEAAkE;AAClE,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,qBAAqB,GAC5B,mBAAmB,CA0LrB"}

package/dist/sources/unsplash/index.d.ts

@@ -12,5 +12,6 @@ import type { AssetSourceProvider } from "../provider.js";
 export declare const UNSPLASH_THEME_FACET = "unsplash:theme";
 /** Enabled when a proxy endpoint or access key is present (or forced via `enabled`). */
 export declare function unsplashEnabled(options: UnsplashSourceOptions): boolean;
+/** Create the Unsplash-backed read-only asset source provider. */
 export declare function createUnsplashProvider(options: UnsplashSourceOptions): AssetSourceProvider;
 //# sourceMappingURL=index.d.ts.map

package/dist/sources/unsplash/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sources/unsplash/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAc,MAAM,gBAAgB,CAAC;AAYtE,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AASrD,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAKvE;AAMD,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,qBAAqB,GAC5B,mBAAmB,CA0LrB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sources/unsplash/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAc,MAAM,gBAAgB,CAAC;AAYtE,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AASrD,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAKvE;AAMD,kEAAkE;AAClE,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,qBAAqB,GAC5B,mBAAmB,CA0LrB"}

package/dist/testing/index.d.cts

@@ -7,10 +7,13 @@
  * on the registry + uploader contracts owned by this package.
  */
 import type { AssetRegistry, UploadAdapter, UploadResult } from "../types/types.js";
+/** Options for constructing a registry fixture in tests. */
 export interface CreateTestRegistryOptions {
     readonly initial?: readonly UploadResult[];
 }
+/** Create an in-memory registry preloaded with optional upload rows. */
 export declare function createTestRegistry(options?: CreateTestRegistryOptions): AssetRegistry;
+/** Options for the deterministic fake uploader helper. */
 export interface FakeUploaderOptions {
     /**
      * Optional map keyed by `File.name`. When a file is uploaded whose
@@ -20,5 +23,6 @@ export interface FakeUploaderOptions {
      */
     readonly responses?: Record<string, UploadResult>;
 }
+/** Create a deterministic fake upload adapter for plugin and host tests. */
 export declare function fakeUploader(options?: FakeUploaderOptions): UploadAdapter;
 //# sourceMappingURL=index.d.cts.map

package/dist/testing/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEX,aAAa,EACb,aAAa,EACb,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,wBAAgB,kBAAkB,CACjC,OAAO,GAAE,yBAA8B,GACrC,aAAa,CAMf;AAED,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAClD;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa,CAkB7E"}
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEX,aAAa,EACb,aAAa,EACb,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAG3B,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CACjC,OAAO,GAAE,yBAA8B,GACrC,aAAa,CAMf;AAED,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAClD;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa,CAkB7E"}