@anvilkit/plugin-asset-manager 0.1.6 → 0.1.8

package/dist/plugin.cjs

@@ -47,6 +47,8 @@ const external_lucide_react_namespaceObject = require("lucide-react");
 const external_react_namespaceObject = require("react");
 const config_json_namespaceObject = require("../meta/config.json");
 var config_json_default = /*#__PURE__*/ __webpack_require__.n(config_json_namespaceObject);
+const in_memory_cjs_namespaceObject = require("./adapters/in-memory.cjs");
+const entry_cjs_namespaceObject = require("./i18n/entry.cjs");
 const asset_reference_cjs_namespaceObject = require("./utils/asset-reference.cjs");
 const errors_cjs_namespaceObject = require("./utils/errors.cjs");
 const header_action_cjs_namespaceObject = require("./utils/header-action.cjs");
@@ -63,7 +65,7 @@ const META = {
 };
 const stateByToken = new WeakMap();
 const tokenByContext = new WeakMap();
-function createAssetManagerPlugin(options) {
+function createAssetManagerPlugin(options = {}) {
     const token = {};
     const registry = (0, registry_cjs_namespaceObject.createAssetRegistry)();
     const normalizedOptions = normalizeOptions(options);
@@ -74,7 +76,8 @@ function createAssetManagerPlugin(options) {
     });
     return {
         meta: META,
-        register (_ctx) {
+        register (ctx) {
+            ctx.registerMessages(entry_cjs_namespaceObject.ASSET_MANAGER_ENTRY);
             const registration = {
                 meta: META,
                 headerActions: [
@@ -90,15 +93,34 @@ function createAssetManagerPlugin(options) {
                         });
                         tokenByContext.set(initCtx, token);
                         initCtx.registerAssetResolver(assetResolver);
+                        const upload = (file, opts)=>uploadAsset(initCtx, file, opts?.signal);
                         const studioAssetSource = (0, studio_asset_source_cjs_namespaceObject.createStudioAssetSource)({
                             registry,
-                            upload: (file, opts)=>uploadAsset(initCtx, file, opts?.signal),
+                            upload,
                             ...normalizedOptions.getThumbnail ? {
                                 getThumbnail: normalizedOptions.getThumbnail
                             } : {}
                         });
-                        const unregisterAssetSource = initCtx.registerAssetSource?.(studioAssetSource);
-                        if (void 0 !== unregisterAssetSource) cleanups.push(unregisterAssetSource);
+                        let unregisterAssetSource = initCtx.registerAssetSource?.(studioAssetSource);
+                        cleanups.push(()=>unregisterAssetSource?.());
+                        if (needsRichSource(normalizedOptions)) {
+                            let disposed = false;
+                            cleanups.push(()=>{
+                                disposed = true;
+                            });
+                            loadRichSource(initCtx, registry, upload, normalizedOptions).then((composite)=>{
+                                if (disposed) return;
+                                unregisterAssetSource?.();
+                                unregisterAssetSource = void 0;
+                                const unregisterComposite = initCtx.registerAssetSource?.(composite);
+                                if (disposed) return void unregisterComposite?.();
+                                cleanups.push(()=>unregisterComposite?.());
+                            }).catch((error)=>{
+                                initCtx.log("error", "asset-manager: failed to load the data source.", {
+                                    error
+                                });
+                            });
+                        }
                     },
                     onDestroy (destroyCtx) {
                         const state = stateByToken.get(token);
@@ -162,9 +184,52 @@ function getRuntimeState(ctx) {
     if (!state) throw new Error("createAssetManagerPlugin: uploadAsset called before the plugin runtime was initialized.");
     return state;
 }
+function needsRichSource(options) {
+    return false !== options.folders || void 0 !== options.dataSource || void 0 !== options.providers && options.providers.length > 0 || void 0 !== options.unsplash;
+}
+async function loadRichSource(ctx, registry, upload, options) {
+    const [{ resolveDataSource }, { createCompositeAssetSource }] = await Promise.all([
+        import("./utils/data-source.cjs"),
+        import("./sources/composite-source.cjs")
+    ]);
+    const maxDepth = "object" == typeof options.folders ? options.folders.maxDepth : void 0;
+    const resolved = resolveDataSource({
+        registry,
+        upload,
+        ...options.dataSource ? {
+            hostDataSource: options.dataSource
+        } : {},
+        ...void 0 !== maxDepth ? {
+            maxDepth
+        } : {},
+        warn: (message)=>ctx.log("warn", message)
+    });
+    const providers = [
+        ...options.providers ?? []
+    ];
+    if (void 0 !== options.unsplash) {
+        const { createUnsplashProvider, unsplashEnabled } = await import("./sources/unsplash/index.cjs");
+        if (unsplashEnabled(options.unsplash)) {
+            if (void 0 !== options.unsplash.accessKey && void 0 === options.unsplash.proxyEndpoint) ctx.log("warn", "asset-manager: the Unsplash accessKey is public in the browser — use a server proxy (proxyEndpoint) in production.");
+            providers.push(createUnsplashProvider(options.unsplash));
+        }
+    }
+    return createCompositeAssetSource({
+        source: resolved,
+        registry,
+        upload,
+        ...providers.length > 0 ? {
+            providers
+        } : {},
+        ...options.getThumbnail ? {
+            getThumbnail: options.getThumbnail
+        } : {}
+    });
+}
 function normalizeOptions(options) {
     return {
         ...options,
+        uploader: options.uploader ?? (0, in_memory_cjs_namespaceObject.inMemoryUploader)(),
         ...options.acceptedMimeTypes ? {
             acceptedMimeTypes: Object.freeze([
                 ...options.acceptedMimeTypes

package/dist/plugin.d.cts

@@ -1,9 +1,10 @@
 import type { StudioPlugin, StudioPluginContext } from "@anvilkit/core/types";
 import type { Config as PuckConfig } from "@puckeditor/core";
-import type { AssetManagerOptions, AssetRegistry, UploadResult } from "./types/types.js";
+import type { AssetManagerOptions } from "./types/options.js";
+import type { AssetRegistry, UploadResult } from "./types/types.js";
 import { createAssetReference } from "./utils/asset-reference.js";
 export { createAssetReference };
-export declare function createAssetManagerPlugin<UserConfig extends PuckConfig = PuckConfig>(options: AssetManagerOptions): StudioPlugin<UserConfig>;
+export declare function createAssetManagerPlugin<UserConfig extends PuckConfig = PuckConfig>(options?: AssetManagerOptions): StudioPlugin<UserConfig>;
 export declare function getAssetRegistry<UserConfig extends PuckConfig = PuckConfig>(ctx: StudioPluginContext<UserConfig>): AssetRegistry | undefined;
 export declare function uploadAsset<UserConfig extends PuckConfig = PuckConfig>(ctx: StudioPluginContext<UserConfig>, file: File, signal?: AbortSignal): Promise<UploadResult>;
 export declare function validateSelectedFile(file: File, options: Pick<AssetManagerOptions, "acceptedMimeTypes" | "maxFileSize">): void;

package/dist/plugin.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.cts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,YAAY,EACZ,mBAAmB,EAEnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK7D,OAAO,KAAK,EACX,mBAAmB,EAEnB,aAAa,EACb,YAAY,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAUlE,OAAO,EAAE,oBAAoB,EAAE,CAAC;AA2BhC,wBAAgB,wBAAwB,CACvC,UAAU,SAAS,UAAU,GAAG,UAAU,EACzC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAAC,UAAU,CAAC,CAwDxD;AAED,wBAAgB,gBAAgB,CAAC,UAAU,SAAS,UAAU,GAAG,UAAU,EAC1E,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,GAClC,aAAa,GAAG,SAAS,CAG3B;AAED,wBAAsB,WAAW,CAAC,UAAU,SAAS,UAAU,GAAG,UAAU,EAC3E,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,EACpC,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,CAAC,CAwDvB;AAED,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,aAAa,CAAC,GACrE,IAAI,CAmBN"}
+{"version":3,"file":"plugin.d.cts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,YAAY,EACZ,mBAAmB,EAEnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAU7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAEX,aAAa,EAEb,YAAY,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAWlE,OAAO,EAAE,oBAAoB,EAAE,CAAC;AA6BhC,wBAAgB,wBAAwB,CACvC,UAAU,SAAS,UAAU,GAAG,UAAU,EACzC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAAC,UAAU,CAAC,CA4F7D;AAED,wBAAgB,gBAAgB,CAAC,UAAU,SAAS,UAAU,GAAG,UAAU,EAC1E,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,GAClC,aAAa,GAAG,SAAS,CAG3B;AAED,wBAAsB,WAAW,CAAC,UAAU,SAAS,UAAU,GAAG,UAAU,EAC3E,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,EACpC,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,CAAC,CAwDvB;AAED,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,aAAa,CAAC,GACrE,IAAI,CAmBN"}

package/dist/plugin.d.ts

@@ -1,9 +1,10 @@
 import type { StudioPlugin, StudioPluginContext } from "@anvilkit/core/types";
 import type { Config as PuckConfig } from "@puckeditor/core";
-import type { AssetManagerOptions, AssetRegistry, UploadResult } from "./types/types.js";
+import type { AssetManagerOptions } from "./types/options.js";
+import type { AssetRegistry, UploadResult } from "./types/types.js";
 import { createAssetReference } from "./utils/asset-reference.js";
 export { createAssetReference };
-export declare function createAssetManagerPlugin<UserConfig extends PuckConfig = PuckConfig>(options: AssetManagerOptions): StudioPlugin<UserConfig>;
+export declare function createAssetManagerPlugin<UserConfig extends PuckConfig = PuckConfig>(options?: AssetManagerOptions): StudioPlugin<UserConfig>;
 export declare function getAssetRegistry<UserConfig extends PuckConfig = PuckConfig>(ctx: StudioPluginContext<UserConfig>): AssetRegistry | undefined;
 export declare function uploadAsset<UserConfig extends PuckConfig = PuckConfig>(ctx: StudioPluginContext<UserConfig>, file: File, signal?: AbortSignal): Promise<UploadResult>;
 export declare function validateSelectedFile(file: File, options: Pick<AssetManagerOptions, "acceptedMimeTypes" | "maxFileSize">): void;

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,YAAY,EACZ,mBAAmB,EAEnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK7D,OAAO,KAAK,EACX,mBAAmB,EAEnB,aAAa,EACb,YAAY,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAUlE,OAAO,EAAE,oBAAoB,EAAE,CAAC;AA2BhC,wBAAgB,wBAAwB,CACvC,UAAU,SAAS,UAAU,GAAG,UAAU,EACzC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAAC,UAAU,CAAC,CAwDxD;AAED,wBAAgB,gBAAgB,CAAC,UAAU,SAAS,UAAU,GAAG,UAAU,EAC1E,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,GAClC,aAAa,GAAG,SAAS,CAG3B;AAED,wBAAsB,WAAW,CAAC,UAAU,SAAS,UAAU,GAAG,UAAU,EAC3E,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,EACpC,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,CAAC,CAwDvB;AAED,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,aAAa,CAAC,GACrE,IAAI,CAmBN"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,YAAY,EACZ,mBAAmB,EAEnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAU7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAEX,aAAa,EAEb,YAAY,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAWlE,OAAO,EAAE,oBAAoB,EAAE,CAAC;AA6BhC,wBAAgB,wBAAwB,CACvC,UAAU,SAAS,UAAU,GAAG,UAAU,EACzC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAAC,UAAU,CAAC,CA4F7D;AAED,wBAAgB,gBAAgB,CAAC,UAAU,SAAS,UAAU,GAAG,UAAU,EAC1E,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,GAClC,aAAa,GAAG,SAAS,CAG3B;AAED,wBAAsB,WAAW,CAAC,UAAU,SAAS,UAAU,GAAG,UAAU,EAC3E,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,EACpC,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,CAAC,CAwDvB;AAED,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,aAAa,CAAC,GACrE,IAAI,CAmBN"}

package/dist/plugin.js

@@ -3,6 +3,8 @@ import { createElement } from "react";
 import config from "../meta/config.json" with {
     type: "json"
 };
+import { inMemoryUploader } from "./adapters/in-memory.js";
+import { ASSET_MANAGER_ENTRY } from "./i18n/entry.js";
 import { createAssetReference } from "./utils/asset-reference.js";
 import { AssetValidationError } from "./utils/errors.js";
 import { uploadAssetAction } from "./utils/header-action.js";
@@ -19,7 +21,7 @@ const META = {
 };
 const stateByToken = new WeakMap();
 const tokenByContext = new WeakMap();
-function createAssetManagerPlugin(options) {
+function createAssetManagerPlugin(options = {}) {
     const token = {};
     const registry = createAssetRegistry();
     const normalizedOptions = normalizeOptions(options);
@@ -30,7 +32,8 @@ function createAssetManagerPlugin(options) {
     });
     return {
         meta: META,
-        register (_ctx) {
+        register (ctx) {
+            ctx.registerMessages(ASSET_MANAGER_ENTRY);
             const registration = {
                 meta: META,
                 headerActions: [
@@ -46,15 +49,34 @@ function createAssetManagerPlugin(options) {
                         });
                         tokenByContext.set(initCtx, token);
                         initCtx.registerAssetResolver(assetResolver);
+                        const upload = (file, opts)=>uploadAsset(initCtx, file, opts?.signal);
                         const studioAssetSource = createStudioAssetSource({
                             registry,
-                            upload: (file, opts)=>uploadAsset(initCtx, file, opts?.signal),
+                            upload,
                             ...normalizedOptions.getThumbnail ? {
                                 getThumbnail: normalizedOptions.getThumbnail
                             } : {}
                         });
-                        const unregisterAssetSource = initCtx.registerAssetSource?.(studioAssetSource);
-                        if (void 0 !== unregisterAssetSource) cleanups.push(unregisterAssetSource);
+                        let unregisterAssetSource = initCtx.registerAssetSource?.(studioAssetSource);
+                        cleanups.push(()=>unregisterAssetSource?.());
+                        if (needsRichSource(normalizedOptions)) {
+                            let disposed = false;
+                            cleanups.push(()=>{
+                                disposed = true;
+                            });
+                            loadRichSource(initCtx, registry, upload, normalizedOptions).then((composite)=>{
+                                if (disposed) return;
+                                unregisterAssetSource?.();
+                                unregisterAssetSource = void 0;
+                                const unregisterComposite = initCtx.registerAssetSource?.(composite);
+                                if (disposed) return void unregisterComposite?.();
+                                cleanups.push(()=>unregisterComposite?.());
+                            }).catch((error)=>{
+                                initCtx.log("error", "asset-manager: failed to load the data source.", {
+                                    error
+                                });
+                            });
+                        }
                     },
                     onDestroy (destroyCtx) {
                         const state = stateByToken.get(token);
@@ -118,9 +140,52 @@ function getRuntimeState(ctx) {
     if (!state) throw new Error("createAssetManagerPlugin: uploadAsset called before the plugin runtime was initialized.");
     return state;
 }
+function needsRichSource(options) {
+    return false !== options.folders || void 0 !== options.dataSource || void 0 !== options.providers && options.providers.length > 0 || void 0 !== options.unsplash;
+}
+async function loadRichSource(ctx, registry, upload, options) {
+    const [{ resolveDataSource }, { createCompositeAssetSource }] = await Promise.all([
+        import("./utils/data-source.js"),
+        import("./sources/composite-source.js")
+    ]);
+    const maxDepth = "object" == typeof options.folders ? options.folders.maxDepth : void 0;
+    const resolved = resolveDataSource({
+        registry,
+        upload,
+        ...options.dataSource ? {
+            hostDataSource: options.dataSource
+        } : {},
+        ...void 0 !== maxDepth ? {
+            maxDepth
+        } : {},
+        warn: (message)=>ctx.log("warn", message)
+    });
+    const providers = [
+        ...options.providers ?? []
+    ];
+    if (void 0 !== options.unsplash) {
+        const { createUnsplashProvider, unsplashEnabled } = await import("./sources/unsplash/index.js");
+        if (unsplashEnabled(options.unsplash)) {
+            if (void 0 !== options.unsplash.accessKey && void 0 === options.unsplash.proxyEndpoint) ctx.log("warn", "asset-manager: the Unsplash accessKey is public in the browser — use a server proxy (proxyEndpoint) in production.");
+            providers.push(createUnsplashProvider(options.unsplash));
+        }
+    }
+    return createCompositeAssetSource({
+        source: resolved,
+        registry,
+        upload,
+        ...providers.length > 0 ? {
+            providers
+        } : {},
+        ...options.getThumbnail ? {
+            getThumbnail: options.getThumbnail
+        } : {}
+    });
+}
 function normalizeOptions(options) {
     return {
         ...options,
+        uploader: options.uploader ?? inMemoryUploader(),
         ...options.acceptedMimeTypes ? {
             acceptedMimeTypes: Object.freeze([
                 ...options.acceptedMimeTypes

package/dist/sources/composite-source.cjs

@@ -0,0 +1,138 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    createCompositeAssetSource: ()=>createCompositeAssetSource
+});
+const asset_reference_cjs_namespaceObject = require("../utils/asset-reference.cjs");
+const studio_asset_source_cjs_namespaceObject = require("../utils/studio-asset-source.cjs");
+const external_federated_search_cjs_namespaceObject = require("./federated-search.cjs");
+function createCompositeAssetSource(options) {
+    const { source, registry, upload, getThumbnail } = options;
+    const base = (0, studio_asset_source_cjs_namespaceObject.createStudioAssetSource)({
+        registry,
+        upload,
+        ...getThumbnail ? {
+            getThumbnail
+        } : {}
+    });
+    const project = (entry)=>{
+        const attribution = entry.meta?.attribution;
+        const isExternal = entry.id.startsWith("unsplash:");
+        return {
+            ...(0, studio_asset_source_cjs_namespaceObject.toStudioAsset)(entry, getThumbnail),
+            ...isExternal ? {
+                url: entry.url
+            } : {},
+            folderId: source.folders.folderOf(entry.id),
+            source: isExternal ? "unsplash" : "local",
+            ...attribution ? {
+                attribution: {
+                    photographerName: attribution.photographerName,
+                    photographerUrl: attribution.photographerUrl,
+                    sourceUrl: attribution.unsplashUrl
+                }
+            } : {}
+        };
+    };
+    const providers = [
+        (0, external_federated_search_cjs_namespaceObject.createLocalProvider)(source, registry),
+        ...options.providers ?? []
+    ];
+    const runList = (filter, signal)=>1 === providers.length ? source.list(filter, signal) : (0, external_federated_search_cjs_namespaceObject.federatedSearch)({
+            providers,
+            filter,
+            signal
+        });
+    return {
+        async list () {
+            const page = await runList({});
+            return Object.freeze(page.items.map(project));
+        },
+        async listPaginated (query) {
+            const page = await runList({
+                ...query
+            });
+            return {
+                items: Object.freeze(page.items.map(project)),
+                total: page.total,
+                nextCursor: page.nextCursor,
+                ...page.folders ? {
+                    folders: page.folders
+                } : {},
+                ...page.folderPath ? {
+                    folderPath: page.folderPath
+                } : {},
+                ...page.sourceCursors ? {
+                    sourceCursors: page.sourceCursors
+                } : {}
+            };
+        },
+        upload: base.upload,
+        setTags: base.setTags,
+        subscribeUploads: base.subscribeUploads,
+        getUrl: (assetId)=>(0, asset_reference_cjs_namespaceObject.createAssetReference)(assetId),
+        async delete (assetId) {
+            await source.remove(assetId);
+        },
+        async rename (assetId, nextName) {
+            await source.rename(assetId, nextName);
+        },
+        async replace (assetId, file) {
+            return project(await source.replace(assetId, file));
+        },
+        subscribe: (listener)=>source.subscribe(listener),
+        createFolder: (parentId, name)=>source.createFolder(parentId, name),
+        renameFolder: (id, name)=>source.renameFolder(id, name),
+        removeFolder: (id, opts)=>source.removeFolder(id, opts),
+        moveFolder: (id, parentId)=>source.moveFolder(id, parentId),
+        moveAsset: (assetId, folderId)=>source.move(assetId, folderId),
+        async pickResult (asset) {
+            const provider = providers.find((p)=>p.id === asset.source);
+            if (void 0 === provider || "local" === provider.id) return asset;
+            const result = await provider.pickResult(asset);
+            registry.register(result);
+            return project(result);
+        },
+        subscribeStatus: (listener)=>source.subscribeStatus(listener),
+        async listThemes () {
+            const themeLists = await Promise.all(providers.flatMap((provider)=>"local" === provider.id ? [] : [
+                    provider.listThemes()
+                ]));
+            return themeLists.flat();
+        }
+    };
+}
+exports.createCompositeAssetSource = __webpack_exports__.createCompositeAssetSource;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createCompositeAssetSource"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

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

@@ -0,0 +1,39 @@
+/**
+ * @file `CompositeAssetSource` (PRD 0002 §6.1, §8.1). Implements core's
+ * `StudioAssetSource` by routing reads + catalog mutations through the resolved
+ * `AssetDataSource` (so host backends and folder scoping work), while reusing
+ * the proven upload pipeline + projection from `createStudioAssetSource`.
+ *
+ * Lazy-loaded by the factory only when a host opts into a richer surface
+ * (`dataSource`/`providers`/`unsplash`), so flat callers never pull this — or
+ * the folder/data-source code it imports — into the headless entry chunk.
+ */
+import type { StudioAssetSource } from "@anvilkit/core/types";
+import type { AssetFolder, FolderId } from "../types/folders.js";
+import type { AssetRegistry, UploadResult } from "../types/types.js";
+import type { ResolvedAssetDataSource, UploadFn } from "../utils/data-source.js";
+import type { AssetSourceProvider } from "./provider.js";
+export interface CreateCompositeAssetSourceOptions {
+    readonly source: ResolvedAssetDataSource;
+    readonly registry: AssetRegistry;
+    readonly upload: UploadFn;
+    readonly getThumbnail?: (entry: UploadResult) => string | undefined;
+    /** External read-only sources (e.g. Unsplash) federated alongside the local library. */
+    readonly providers?: readonly AssetSourceProvider[];
+}
+/**
+ * The core `StudioAssetSource` plus the folder methods the plugin's `./ui` and
+ * (Phase 2) core `ImageModule` consume. The folder methods are additive — core
+ * ignores what it doesn't know until its sidebar types adopt them.
+ */
+export interface CompositeAssetSource extends StudioAssetSource {
+    createFolder(parentId: FolderId | null, name: string): Promise<AssetFolder>;
+    renameFolder(id: FolderId, name: string): Promise<AssetFolder>;
+    removeFolder(id: FolderId, opts?: {
+        readonly cascade?: boolean;
+    }): Promise<void>;
+    moveFolder(id: FolderId, parentId: FolderId | null): Promise<AssetFolder>;
+    moveAsset(assetId: string, folderId: FolderId | null): Promise<void>;
+}
+export declare function createCompositeAssetSource(options: CreateCompositeAssetSourceOptions): CompositeAssetSource;
+//# sourceMappingURL=composite-source.d.cts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,39 @@
+/**
+ * @file `CompositeAssetSource` (PRD 0002 §6.1, §8.1). Implements core's
+ * `StudioAssetSource` by routing reads + catalog mutations through the resolved
+ * `AssetDataSource` (so host backends and folder scoping work), while reusing
+ * the proven upload pipeline + projection from `createStudioAssetSource`.
+ *
+ * Lazy-loaded by the factory only when a host opts into a richer surface
+ * (`dataSource`/`providers`/`unsplash`), so flat callers never pull this — or
+ * the folder/data-source code it imports — into the headless entry chunk.
+ */
+import type { StudioAssetSource } from "@anvilkit/core/types";
+import type { AssetFolder, FolderId } from "../types/folders.js";
+import type { AssetRegistry, UploadResult } from "../types/types.js";
+import type { ResolvedAssetDataSource, UploadFn } from "../utils/data-source.js";
+import type { AssetSourceProvider } from "./provider.js";
+export interface CreateCompositeAssetSourceOptions {
+    readonly source: ResolvedAssetDataSource;
+    readonly registry: AssetRegistry;
+    readonly upload: UploadFn;
+    readonly getThumbnail?: (entry: UploadResult) => string | undefined;
+    /** External read-only sources (e.g. Unsplash) federated alongside the local library. */
+    readonly providers?: readonly AssetSourceProvider[];
+}
+/**
+ * The core `StudioAssetSource` plus the folder methods the plugin's `./ui` and
+ * (Phase 2) core `ImageModule` consume. The folder methods are additive — core
+ * ignores what it doesn't know until its sidebar types adopt them.
+ */
+export interface CompositeAssetSource extends StudioAssetSource {
+    createFolder(parentId: FolderId | null, name: string): Promise<AssetFolder>;
+    renameFolder(id: FolderId, name: string): Promise<AssetFolder>;
+    removeFolder(id: FolderId, opts?: {
+        readonly cascade?: boolean;
+    }): Promise<void>;
+    moveFolder(id: FolderId, parentId: FolderId | null): Promise<AssetFolder>;
+    moveAsset(assetId: string, folderId: FolderId | null): Promise<void>;
+}
+export declare function createCompositeAssetSource(options: CreateCompositeAssetSourceOptions): CompositeAssetSource;
+//# sourceMappingURL=composite-source.d.ts.map

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

@@ -0,0 +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"}

package/dist/sources/composite-source.js

@@ -0,0 +1,100 @@
+import { createAssetReference } from "../utils/asset-reference.js";
+import { createStudioAssetSource, toStudioAsset } from "../utils/studio-asset-source.js";
+import { createLocalProvider, federatedSearch } from "./federated-search.js";
+function createCompositeAssetSource(options) {
+    const { source, registry, upload, getThumbnail } = options;
+    const base = createStudioAssetSource({
+        registry,
+        upload,
+        ...getThumbnail ? {
+            getThumbnail
+        } : {}
+    });
+    const project = (entry)=>{
+        const attribution = entry.meta?.attribution;
+        const isExternal = entry.id.startsWith("unsplash:");
+        return {
+            ...toStudioAsset(entry, getThumbnail),
+            ...isExternal ? {
+                url: entry.url
+            } : {},
+            folderId: source.folders.folderOf(entry.id),
+            source: isExternal ? "unsplash" : "local",
+            ...attribution ? {
+                attribution: {
+                    photographerName: attribution.photographerName,
+                    photographerUrl: attribution.photographerUrl,
+                    sourceUrl: attribution.unsplashUrl
+                }
+            } : {}
+        };
+    };
+    const providers = [
+        createLocalProvider(source, registry),
+        ...options.providers ?? []
+    ];
+    const runList = (filter, signal)=>1 === providers.length ? source.list(filter, signal) : federatedSearch({
+            providers,
+            filter,
+            signal
+        });
+    return {
+        async list () {
+            const page = await runList({});
+            return Object.freeze(page.items.map(project));
+        },
+        async listPaginated (query) {
+            const page = await runList({
+                ...query
+            });
+            return {
+                items: Object.freeze(page.items.map(project)),
+                total: page.total,
+                nextCursor: page.nextCursor,
+                ...page.folders ? {
+                    folders: page.folders
+                } : {},
+                ...page.folderPath ? {
+                    folderPath: page.folderPath
+                } : {},
+                ...page.sourceCursors ? {
+                    sourceCursors: page.sourceCursors
+                } : {}
+            };
+        },
+        upload: base.upload,
+        setTags: base.setTags,
+        subscribeUploads: base.subscribeUploads,
+        getUrl: (assetId)=>createAssetReference(assetId),
+        async delete (assetId) {
+            await source.remove(assetId);
+        },
+        async rename (assetId, nextName) {
+            await source.rename(assetId, nextName);
+        },
+        async replace (assetId, file) {
+            return project(await source.replace(assetId, file));
+        },
+        subscribe: (listener)=>source.subscribe(listener),
+        createFolder: (parentId, name)=>source.createFolder(parentId, name),
+        renameFolder: (id, name)=>source.renameFolder(id, name),
+        removeFolder: (id, opts)=>source.removeFolder(id, opts),
+        moveFolder: (id, parentId)=>source.moveFolder(id, parentId),
+        moveAsset: (assetId, folderId)=>source.move(assetId, folderId),
+        async pickResult (asset) {
+            const provider = providers.find((p)=>p.id === asset.source);
+            if (void 0 === provider || "local" === provider.id) return asset;
+            const result = await provider.pickResult(asset);
+            registry.register(result);
+            return project(result);
+        },
+        subscribeStatus: (listener)=>source.subscribeStatus(listener),
+        async listThemes () {
+            const themeLists = await Promise.all(providers.flatMap((provider)=>"local" === provider.id ? [] : [
+                    provider.listThemes()
+                ]));
+            return themeLists.flat();
+        }
+    };
+}
+export { createCompositeAssetSource };