@anvilkit/plugin-asset-manager 0.1.9 → 0.1.10

package/dist/utils/query-param-transform.d.cts

@@ -0,0 +1,46 @@
+/**
+ * @file Built-in query-param {@link TransformResolver} (PRD 0004 — review #9).
+ *
+ * Maps an {@link AssetTransform} onto query parameters appended to the asset's
+ * URL — the shape most image CDNs accept (imgix, Cloudinary's `f_`/`w_` via a
+ * mapper, Thumbor-ish gateways, etc.). Param names and the `fit`/`format`
+ * vocabularies are configurable so one helper covers many CDNs. Lives on its
+ * own `./transform` subpath so flat callers never pull it into the eager entry.
+ *
+ * @experimental Public surface may change before v1.0.
+ */
+import type { AssetTransform, TransformResolver } from "../types/transform.js";
+import type { UploadResult } from "../types/types.js";
+/**
+ * Resolve a derivative URL for an asset + transform using `resolver`, falling
+ * back to the asset's original URL when the resolver returns `undefined`. The
+ * live (non-IR) counterpart to what `createIRAssetResolver` does at export /
+ * render time — useful for a host rendering a variant directly.
+ */
+export declare function deriveVariantUrl(asset: UploadResult, transform: AssetTransform, resolver: TransformResolver): string;
+/** Configuration for {@link createQueryParamTransformResolver}. */
+export interface QueryParamTransformResolverOptions {
+    /**
+     * Override the query parameter names. Defaults to an imgix-style set:
+     * `w` / `h` / `fit` / `fm` / `q` / `dpr`.
+     */
+    readonly params?: {
+        readonly width?: string;
+        readonly height?: string;
+        readonly fit?: string;
+        readonly format?: string;
+        readonly quality?: string;
+        readonly dpr?: string;
+    };
+    /** Map the `fit` vocabulary onto the CDN's values (e.g. `cover` → `crop`). */
+    readonly fitMap?: Partial<Record<NonNullable<AssetTransform["fit"]>, string>>;
+    /** Map the `format` vocabulary onto the CDN's values. */
+    readonly formatMap?: Partial<Record<NonNullable<AssetTransform["format"]>, string>>;
+}
+/**
+ * Create a {@link TransformResolver} that appends transform query parameters to
+ * each asset's URL, preserving any existing query. Returns `undefined` (→ the
+ * original URL) when the transform is empty, so a no-op transform is a no-op.
+ */
+export declare function createQueryParamTransformResolver(options?: QueryParamTransformResolverOptions): TransformResolver;
+//# sourceMappingURL=query-param-transform.d.cts.map

package/dist/utils/query-param-transform.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-param-transform.d.cts","sourceRoot":"","sources":["../../src/utils/query-param-transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,cAAc,EACzB,QAAQ,EAAE,iBAAiB,GACzB,MAAM,CAER;AAED,mEAAmE;AACnE,MAAM,WAAW,kCAAkC;IAClD;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QACjB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9E,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAC3B,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CACrD,CAAC;CACF;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAChD,OAAO,GAAE,kCAAuC,GAC9C,iBAAiB,CAuCnB"}

package/dist/utils/query-param-transform.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file Built-in query-param {@link TransformResolver} (PRD 0004 — review #9).
+ *
+ * Maps an {@link AssetTransform} onto query parameters appended to the asset's
+ * URL — the shape most image CDNs accept (imgix, Cloudinary's `f_`/`w_` via a
+ * mapper, Thumbor-ish gateways, etc.). Param names and the `fit`/`format`
+ * vocabularies are configurable so one helper covers many CDNs. Lives on its
+ * own `./transform` subpath so flat callers never pull it into the eager entry.
+ *
+ * @experimental Public surface may change before v1.0.
+ */
+import type { AssetTransform, TransformResolver } from "../types/transform.js";
+import type { UploadResult } from "../types/types.js";
+/**
+ * Resolve a derivative URL for an asset + transform using `resolver`, falling
+ * back to the asset's original URL when the resolver returns `undefined`. The
+ * live (non-IR) counterpart to what `createIRAssetResolver` does at export /
+ * render time — useful for a host rendering a variant directly.
+ */
+export declare function deriveVariantUrl(asset: UploadResult, transform: AssetTransform, resolver: TransformResolver): string;
+/** Configuration for {@link createQueryParamTransformResolver}. */
+export interface QueryParamTransformResolverOptions {
+    /**
+     * Override the query parameter names. Defaults to an imgix-style set:
+     * `w` / `h` / `fit` / `fm` / `q` / `dpr`.
+     */
+    readonly params?: {
+        readonly width?: string;
+        readonly height?: string;
+        readonly fit?: string;
+        readonly format?: string;
+        readonly quality?: string;
+        readonly dpr?: string;
+    };
+    /** Map the `fit` vocabulary onto the CDN's values (e.g. `cover` → `crop`). */
+    readonly fitMap?: Partial<Record<NonNullable<AssetTransform["fit"]>, string>>;
+    /** Map the `format` vocabulary onto the CDN's values. */
+    readonly formatMap?: Partial<Record<NonNullable<AssetTransform["format"]>, string>>;
+}
+/**
+ * Create a {@link TransformResolver} that appends transform query parameters to
+ * each asset's URL, preserving any existing query. Returns `undefined` (→ the
+ * original URL) when the transform is empty, so a no-op transform is a no-op.
+ */
+export declare function createQueryParamTransformResolver(options?: QueryParamTransformResolverOptions): TransformResolver;
+//# sourceMappingURL=query-param-transform.d.ts.map

package/dist/utils/query-param-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-param-transform.d.ts","sourceRoot":"","sources":["../../src/utils/query-param-transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,cAAc,EACzB,QAAQ,EAAE,iBAAiB,GACzB,MAAM,CAER;AAED,mEAAmE;AACnE,MAAM,WAAW,kCAAkC;IAClD;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QACjB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9E,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAC3B,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CACrD,CAAC;CACF;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAChD,OAAO,GAAE,kCAAuC,GAC9C,iBAAiB,CAuCnB"}

package/dist/utils/query-param-transform.js

@@ -0,0 +1,60 @@
+function deriveVariantUrl(asset, transform, resolver) {
+    return resolver(asset, transform) ?? asset.url;
+}
+function createQueryParamTransformResolver(options = {}) {
+    const names = {
+        width: options.params?.width ?? "w",
+        height: options.params?.height ?? "h",
+        fit: options.params?.fit ?? "fit",
+        format: options.params?.format ?? "fm",
+        quality: options.params?.quality ?? "q",
+        dpr: options.params?.dpr ?? "dpr"
+    };
+    return (asset, transform)=>{
+        const params = [];
+        if (void 0 !== transform.width) params.push([
+            names.width,
+            String(transform.width)
+        ]);
+        if (void 0 !== transform.height) params.push([
+            names.height,
+            String(transform.height)
+        ]);
+        if (void 0 !== transform.fit) params.push([
+            names.fit,
+            options.fitMap?.[transform.fit] ?? transform.fit
+        ]);
+        if (void 0 !== transform.format) params.push([
+            names.format,
+            options.formatMap?.[transform.format] ?? transform.format
+        ]);
+        if (void 0 !== transform.quality) params.push([
+            names.quality,
+            String(transform.quality)
+        ]);
+        if (void 0 !== transform.dpr) params.push([
+            names.dpr,
+            String(transform.dpr)
+        ]);
+        if (0 === params.length) return;
+        return appendQueryParams(asset.url, params);
+    };
+}
+function appendQueryParams(rawUrl, params) {
+    try {
+        const url = new URL(rawUrl);
+        for (const [key, value] of params)url.searchParams.set(key, value);
+        return url.toString();
+    } catch  {
+        const hashIndex = rawUrl.indexOf("#");
+        const hash = -1 === hashIndex ? "" : rawUrl.slice(hashIndex);
+        const beforeHash = -1 === hashIndex ? rawUrl : rawUrl.slice(0, hashIndex);
+        const queryIndex = beforeHash.indexOf("?");
+        const path = -1 === queryIndex ? beforeHash : beforeHash.slice(0, queryIndex);
+        const search = new URLSearchParams(-1 === queryIndex ? "" : beforeHash.slice(queryIndex + 1));
+        for (const [key, value] of params)search.set(key, value);
+        const query = search.toString();
+        return `${path}${"" === query ? "" : `?${query}`}${hash}`;
+    }
+}
+export { createQueryParamTransformResolver, deriveVariantUrl };

package/dist/utils/registry.cjs

@@ -129,6 +129,9 @@ function freezeUploadResult(asset) {
                 ...void 0 !== asset.meta.height ? {
                     height: asset.meta.height
                 } : {},
+                ...void 0 !== asset.meta.hash ? {
+                    hash: asset.meta.hash
+                } : {},
                 ...void 0 !== asset.meta.attribution ? {
                     attribution: Object.freeze({
                         ...asset.meta.attribution

package/dist/utils/registry.d.cts

@@ -1,4 +1,12 @@
 import type { AssetKind, AssetRegistry, AssetSearchPage, UploadResult } from "../types/types.js";
+/**
+ * Create an in-memory asset registry.
+ *
+ * The registry stores immutable `UploadResult` records by id and exposes the
+ * local catalog operations used by the plugin runtime and Studio asset source:
+ * registration, lookup, listing, delete, rename, replace, tag mutation, search,
+ * pagination, and mutation subscriptions.
+ */
 export declare function createAssetRegistry(): AssetRegistry;
 /** Query / kind / tag filter shared by the registry and the data-source path. */
 export interface AssetMatchFilter {

package/dist/utils/registry.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.cts","sourceRoot":"","sources":["../../src/utils/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,SAAS,EACT,aAAa,EAGb,eAAe,EACf,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAK3B,wBAAgB,mBAAmB,IAAI,aAAa,CA6EnD;AAmDD,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,gBAAgB,GACvB,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAclC;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,eAAe,CAejB"}
+{"version":3,"file":"registry.d.cts","sourceRoot":"","sources":["../../src/utils/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,SAAS,EACT,aAAa,EAGb,eAAe,EACf,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CA6EnD;AAoDD,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,gBAAgB,GACvB,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAclC;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,eAAe,CAejB"}

package/dist/utils/registry.d.ts

@@ -1,4 +1,12 @@
 import type { AssetKind, AssetRegistry, AssetSearchPage, UploadResult } from "../types/types.js";
+/**
+ * Create an in-memory asset registry.
+ *
+ * The registry stores immutable `UploadResult` records by id and exposes the
+ * local catalog operations used by the plugin runtime and Studio asset source:
+ * registration, lookup, listing, delete, rename, replace, tag mutation, search,
+ * pagination, and mutation subscriptions.
+ */
 export declare function createAssetRegistry(): AssetRegistry;
 /** Query / kind / tag filter shared by the registry and the data-source path. */
 export interface AssetMatchFilter {

package/dist/utils/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/utils/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,SAAS,EACT,aAAa,EAGb,eAAe,EACf,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAK3B,wBAAgB,mBAAmB,IAAI,aAAa,CA6EnD;AAmDD,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,gBAAgB,GACvB,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAclC;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,eAAe,CAejB"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/utils/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,SAAS,EACT,aAAa,EAGb,eAAe,EACf,YAAY,EACZ,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CA6EnD;AAoDD,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,gBAAgB,GACvB,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAclC;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,eAAe,CAejB"}

package/dist/utils/registry.js

@@ -95,6 +95,9 @@ function freezeUploadResult(asset) {
                 ...void 0 !== asset.meta.height ? {
                     height: asset.meta.height
                 } : {},
+                ...void 0 !== asset.meta.hash ? {
+                    hash: asset.meta.hash
+                } : {},
                 ...void 0 !== asset.meta.attribution ? {
                     attribution: Object.freeze({
                         ...asset.meta.attribution

package/dist/utils/resolver.cjs

@@ -31,6 +31,7 @@ __webpack_require__.d(__webpack_exports__, {
     createIRAssetResolver: ()=>createIRAssetResolver,
     resolveAssets: ()=>resolveAssets
 });
+const external_asset_reference_cjs_namespaceObject = require("./asset-reference.cjs");
 const external_errors_cjs_namespaceObject = require("./errors.cjs");
 const external_validate_upload_result_cjs_namespaceObject = require("./validate-upload-result.cjs");
 const URL_REJECTION_VALIDATION_CODES = new Set([
@@ -41,7 +42,6 @@ const URL_REJECTION_VALIDATION_CODES = new Set([
     "PATH_TRAVERSAL_URL",
     "MIXED_SCRIPT_HOSTNAME"
 ]);
-const ASSET_REFERENCE_PREFIX = "asset://";
 const ASSET_PROP_KEYS = new Set([
     "src",
     "imageUrl",
@@ -59,14 +59,24 @@ const ASSET_PROP_KEYS = new Set([
 ]);
 function createIRAssetResolver(options) {
     return (url)=>{
-        const assetId = parseAssetReference(url);
-        if (null === assetId) return null;
+        const parsed = (0, external_asset_reference_cjs_namespaceObject.parseAssetReference)(url);
+        if (null === parsed) return null;
+        const assetId = parsed.id;
         const asset = options.registry.get(assetId);
         if (!asset) throw new external_errors_cjs_namespaceObject.AssetResolutionError(assetId, "ASSET_NOT_FOUND");
         try {
+            let effectiveUrl = asset.url;
+            let transformApplied = false;
+            if (void 0 !== parsed.transform && void 0 !== options.transformResolver) {
+                const derived = options.transformResolver(asset, parsed.transform);
+                if (void 0 !== derived) {
+                    effectiveUrl = derived;
+                    transformApplied = true;
+                }
+            }
             const validated = (0, external_validate_upload_result_cjs_namespaceObject.validateUploadResult)({
                 id: asset.id,
-                url: asset.url,
+                url: effectiveUrl,
                 ...asset.meta ? {
                     meta: asset.meta
                 } : {}
@@ -74,10 +84,13 @@ function createIRAssetResolver(options) {
                 dataUrlAllowlistOptIn: options.dataUrlAllowlistOptIn,
                 allowMixedScriptHostnames: options.allowMixedScriptHostnames
             });
+            const meta = transformApplied && validated.meta ? void 0 !== validated.meta.attribution ? {
+                attribution: validated.meta.attribution
+            } : void 0 : validated.meta;
             const resolution = {
                 url: validated.url,
-                ...validated.meta ? {
-                    meta: validated.meta
+                ...meta ? {
+                    meta: meta
                 } : {}
             };
             return resolution;
@@ -133,11 +146,6 @@ function collectValueAssetUrls(value, urls, key) {
     if (null === value || "object" != typeof value) return;
     for (const [entryKey, entryValue] of Object.entries(value))collectValueAssetUrls(entryValue, urls, entryKey);
 }
-function parseAssetReference(url) {
-    if (!url.startsWith(ASSET_REFERENCE_PREFIX)) return null;
-    const assetId = url.slice(ASSET_REFERENCE_PREFIX.length).trim();
-    return "" === assetId ? null : assetId;
-}
 function cloneNode(node, rewriteMap) {
     return {
         id: node.id,

package/dist/utils/resolver.d.cts

@@ -1,10 +1,34 @@
 import type { IRAssetResolver, PageIR } from "@anvilkit/core/types";
+import type { TransformResolver } from "../types/transform.js";
 import type { AssetRegistry } from "../types/types.js";
+/** Options for creating an IR asset-reference resolver. */
 export interface CreateIRAssetResolverOptions {
     readonly registry: AssetRegistry;
     readonly dataUrlAllowlistOptIn?: boolean;
     readonly allowMixedScriptHostnames?: boolean;
+    /**
+     * Maps an asset + transform (carried on the reference as `?w=…&fm=…`) to a
+     * derivative URL. When omitted, or when it returns `undefined`, the asset's
+     * original URL is used. The derivative URL is re-validated through the same
+     * trust boundary as any resolved asset URL.
+     */
+    readonly transformResolver?: TransformResolver;
 }
+/**
+ * Create an IR asset resolver for `asset://<id>` references.
+ *
+ * The resolver looks up references in the supplied registry, re-validates the
+ * stored URL at export/render time, and translates lookup or validation failures
+ * into `AssetResolutionError` codes for callers that need actionable export
+ * diagnostics.
+ */
 export declare function createIRAssetResolver(options: CreateIRAssetResolverOptions): IRAssetResolver;
+/**
+ * Resolve all asset references found in a Page IR tree.
+ *
+ * The function scans the IR asset table and asset-like node props, resolves each
+ * distinct URL concurrently with the supplied resolver, clones the IR with any
+ * resolved URLs/meta applied, and returns a deeply frozen result.
+ */
 export declare function resolveAssets(ir: PageIR, resolver: IRAssetResolver): Promise<PageIR>;
 //# sourceMappingURL=resolver.d.cts.map

package/dist/utils/resolver.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.cts","sourceRoot":"","sources":["../../src/utils/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,eAAe,EACf,MAAM,EAGN,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA8BvD,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CAC7C;AAED,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,4BAA4B,GACnC,eAAe,CAgDjB;AAED,wBAAsB,aAAa,CAClC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAwBjB"}
+{"version":3,"file":"resolver.d.cts","sourceRoot":"","sources":["../../src/utils/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,eAAe,EACf,MAAM,EAGN,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA8BvD,2DAA2D;AAC3D,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,4BAA4B,GACnC,eAAe,CAwEjB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAClC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/utils/resolver.d.ts

@@ -1,10 +1,34 @@
 import type { IRAssetResolver, PageIR } from "@anvilkit/core/types";
+import type { TransformResolver } from "../types/transform.js";
 import type { AssetRegistry } from "../types/types.js";
+/** Options for creating an IR asset-reference resolver. */
 export interface CreateIRAssetResolverOptions {
     readonly registry: AssetRegistry;
     readonly dataUrlAllowlistOptIn?: boolean;
     readonly allowMixedScriptHostnames?: boolean;
+    /**
+     * Maps an asset + transform (carried on the reference as `?w=…&fm=…`) to a
+     * derivative URL. When omitted, or when it returns `undefined`, the asset's
+     * original URL is used. The derivative URL is re-validated through the same
+     * trust boundary as any resolved asset URL.
+     */
+    readonly transformResolver?: TransformResolver;
 }
+/**
+ * Create an IR asset resolver for `asset://<id>` references.
+ *
+ * The resolver looks up references in the supplied registry, re-validates the
+ * stored URL at export/render time, and translates lookup or validation failures
+ * into `AssetResolutionError` codes for callers that need actionable export
+ * diagnostics.
+ */
 export declare function createIRAssetResolver(options: CreateIRAssetResolverOptions): IRAssetResolver;
+/**
+ * Resolve all asset references found in a Page IR tree.
+ *
+ * The function scans the IR asset table and asset-like node props, resolves each
+ * distinct URL concurrently with the supplied resolver, clones the IR with any
+ * resolved URLs/meta applied, and returns a deeply frozen result.
+ */
 export declare function resolveAssets(ir: PageIR, resolver: IRAssetResolver): Promise<PageIR>;
 //# sourceMappingURL=resolver.d.ts.map

package/dist/utils/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/utils/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,eAAe,EACf,MAAM,EAGN,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA8BvD,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CAC7C;AAED,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,4BAA4B,GACnC,eAAe,CAgDjB;AAED,wBAAsB,aAAa,CAClC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAwBjB"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/utils/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,eAAe,EACf,MAAM,EAGN,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA8BvD,2DAA2D;AAC3D,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,4BAA4B,GACnC,eAAe,CAwEjB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAClC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/utils/resolver.js

@@ -1,3 +1,4 @@
+import { parseAssetReference } from "./asset-reference.js";
 import { AssetResolutionError, AssetValidationError } from "./errors.js";
 import { validateUploadResult } from "./validate-upload-result.js";
 const URL_REJECTION_VALIDATION_CODES = new Set([
@@ -8,7 +9,6 @@ const URL_REJECTION_VALIDATION_CODES = new Set([
     "PATH_TRAVERSAL_URL",
     "MIXED_SCRIPT_HOSTNAME"
 ]);
-const ASSET_REFERENCE_PREFIX = "asset://";
 const ASSET_PROP_KEYS = new Set([
     "src",
     "imageUrl",
@@ -26,14 +26,24 @@ const ASSET_PROP_KEYS = new Set([
 ]);
 function createIRAssetResolver(options) {
     return (url)=>{
-        const assetId = parseAssetReference(url);
-        if (null === assetId) return null;
+        const parsed = parseAssetReference(url);
+        if (null === parsed) return null;
+        const assetId = parsed.id;
         const asset = options.registry.get(assetId);
         if (!asset) throw new AssetResolutionError(assetId, "ASSET_NOT_FOUND");
         try {
+            let effectiveUrl = asset.url;
+            let transformApplied = false;
+            if (void 0 !== parsed.transform && void 0 !== options.transformResolver) {
+                const derived = options.transformResolver(asset, parsed.transform);
+                if (void 0 !== derived) {
+                    effectiveUrl = derived;
+                    transformApplied = true;
+                }
+            }
             const validated = validateUploadResult({
                 id: asset.id,
-                url: asset.url,
+                url: effectiveUrl,
                 ...asset.meta ? {
                     meta: asset.meta
                 } : {}
@@ -41,10 +51,13 @@ function createIRAssetResolver(options) {
                 dataUrlAllowlistOptIn: options.dataUrlAllowlistOptIn,
                 allowMixedScriptHostnames: options.allowMixedScriptHostnames
             });
+            const meta = transformApplied && validated.meta ? void 0 !== validated.meta.attribution ? {
+                attribution: validated.meta.attribution
+            } : void 0 : validated.meta;
             const resolution = {
                 url: validated.url,
-                ...validated.meta ? {
-                    meta: validated.meta
+                ...meta ? {
+                    meta: meta
                 } : {}
             };
             return resolution;
@@ -100,11 +113,6 @@ function collectValueAssetUrls(value, urls, key) {
     if (null === value || "object" != typeof value) return;
     for (const [entryKey, entryValue] of Object.entries(value))collectValueAssetUrls(entryValue, urls, entryKey);
 }
-function parseAssetReference(url) {
-    if (!url.startsWith(ASSET_REFERENCE_PREFIX)) return null;
-    const assetId = url.slice(ASSET_REFERENCE_PREFIX.length).trim();
-    return "" === assetId ? null : assetId;
-}
 function cloneNode(node, rewriteMap) {
     return {
         id: node.id,

package/dist/utils/retry.d.cts

@@ -24,11 +24,13 @@
  */
 export declare class RetryableError extends Error {
     readonly retryAfterMs?: number;
+    /** Create a transient error that `withRetry()` may reschedule. */
     constructor(message: string, options?: {
         readonly cause?: unknown;
         readonly retryAfterMs?: number;
     });
 }
+/** Retry policy used by network-bound upload adapters. */
 export interface RetryOptions {
     /**
      * Maximum number of retry attempts after the initial call.

package/dist/utils/retry.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.cts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAG9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;CAYvE;AAED,MAAM,WAAW,YAAY;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAChC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,GAAE,YAAiB,GACxB,OAAO,CAAC,CAAC,CAAC,CAmCZ"}
+{"version":3,"file":"retry.d.cts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,kEAAkE;gBAEjE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;CAYvE;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAChC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,GAAE,YAAiB,GACxB,OAAO,CAAC,CAAC,CAAC,CAmCZ"}

package/dist/utils/retry.d.ts

@@ -24,11 +24,13 @@
  */
 export declare class RetryableError extends Error {
     readonly retryAfterMs?: number;
+    /** Create a transient error that `withRetry()` may reschedule. */
     constructor(message: string, options?: {
         readonly cause?: unknown;
         readonly retryAfterMs?: number;
     });
 }
+/** Retry policy used by network-bound upload adapters. */
 export interface RetryOptions {
     /**
      * Maximum number of retry attempts after the initial call.

package/dist/utils/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAG9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;CAYvE;AAED,MAAM,WAAW,YAAY;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAChC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,GAAE,YAAiB,GACxB,OAAO,CAAC,CAAC,CAAC,CAmCZ"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,kEAAkE;gBAEjE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;CAYvE;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAChC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,GAAE,YAAiB,GACxB,OAAO,CAAC,CAAC,CAAC,CAmCZ"}