canopycms 0.0.67 → 0.0.68-int.101

package/dist/api/reference-options.js

@@ -70,7 +70,7 @@ const getReferenceOptionsHandler = async (gc, ctx, req, _params) => {
     // for an option the caller isn't allowed to see.
     const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
     const resolver = new ReferenceResolver(store, idIndex);
-    const options = await resolver.loadReferenceOptions(collections, displayField, search, entryTypes, (relativePath) => checkAccess(relativePath, 'read').allowed);
+    const options = await resolver.loadReferenceOptions(collections, displayField, search, entryTypes, (logicalPath) => checkAccess(logicalPath, 'read').allowed);
     return {
         ok: true,
         status: 200,

package/dist/api/resolve-references.js

@@ -1,9 +1,6 @@
 import { z } from 'zod';
 import { ContentStore } from '../content-store.js';
 import { defineEndpoint } from './route-builder.js';
-import { ReferenceResolver } from '../reference-resolver.js';
-import { buildResolvedReference } from '../entry-schema.js';
-import { computeEntryUrl } from '../utils/entry-url.js';
 import { branchNameSchema, contentIdSchema } from './validators.js';
 /**
  * Resolution does sequential per-ID file I/O, so the request body caps how much filesystem work
@@ -20,49 +17,25 @@ const resolveReferencesBodySchema = z.object({
 const resolveReferencesHandler = async (gc, ctx, req, params, body) => {
     const { branchContext } = gc;
     const { ids } = body;
-    const flatSchema = branchContext.flatSchema;
-    const contentRootName = ctx.services.config.contentRoot || 'content';
-    const store = new ContentStore(branchContext.branchRoot, flatSchema, {
-        contentRootName,
+    const store = new ContentStore(branchContext.branchRoot, branchContext.flatSchema, {
+        contentRootName: ctx.services.config.contentRoot || 'content',
     });
-    // Get ID index (automatically loads if needed)
-    const idIndex = await store.idIndex();
-    // Resolve each ID to full document
-    const resolver = new ReferenceResolver(store, idIndex);
-    // Build the access checker once, reused for every id instead of re-loading per id in the loop.
-    // A failure here (e.g. settings workspace unavailable) surfaces as a handler error, not
-    // swallowed silently per id.
+    // Built once for every id. A failure here (e.g. settings workspace unavailable) surfaces as a
+    // handler error rather than being swallowed per id.
     const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
+    const access = (logicalPath) => checkAccess(logicalPath, 'read').allowed;
+    // The resolution `read()` applies to a reference field, so live preview shows this user what
+    // `read()` would: the target's data, or a `RestrictedReference` for a target they may not
+    // read. The target's own references stay ids, as in `read()`.
     const resolved = {};
     for (const id of ids) {
         try {
-            const result = await resolver.resolve(id);
-            if (result && result.exists && result.collection && result.slug) {
-                // Check path-level read permission before returning content
-                const resolvedPath = await store.resolveDocumentPath(result.collection, result.slug);
-                const access = checkAccess(resolvedPath.relativePath, 'read');
-                if (!access.allowed)
-                    continue;
-                // `resolveReferences: false` matches the server-side resolver (content-store.ts's
-                // resolveSingleReferenceOnce), so a nested reference inside a target renders the same way
-                // in live preview as on the published site, instead of resolving one level deeper.
-                const doc = await store.read(result.collection, result.slug, { resolveReferences: false });
-                if (doc && doc.data) {
-                    // Same shape as the server-side resolver: target data first, then the reserved keys.
-                    // Order is the corruption guard (a target modelling `id` as content must not shadow the
-                    // real content ID); the extra keys (incl. `urlPath`) keep live preview and production
-                    // in sync for consumers like client-reference-resolver.ts.
-                    resolved[id] = buildResolvedReference(doc.data, {
-                        id,
-                        slug: result.slug,
-                        collection: result.collection,
-                        urlPath: computeEntryUrl(result.collection, result.slug, contentRootName),
-                    });
-                }
-            }
+            const value = await store.resolveReferenceTarget(id, access);
+            if (value)
+                resolved[id] = value;
         }
         catch (error) {
-            // Skip failed resolutions, don't block entire request
+            // An id that fails to resolve is omitted rather than failing the whole request.
             console.error(`Failed to resolve reference ID ${id}:`, error);
         }
     }
@@ -73,7 +46,8 @@ const resolveReferencesHandler = async (gc, ctx, req, params, body) => {
     };
 };
 /**
- * Resolve reference IDs to full document objects
+ * Resolve reference IDs as a reference field would: full target data, or title + URL tagged
+ * `unavailable` for a target the user may not read. An id naming no entry is omitted.
  * POST /:branch/resolve-references
  * Body: { ids: string[] }
  */

package/dist/api/settings-helpers.d.ts

@@ -30,7 +30,7 @@ export interface CommitSettingsResult {
 /**
  * Commit and push settings changes based on the mode.
  * Both prod and dev use commitToSettingsBranch.
- * In dev mode, commits to the settings branch but does not create a PR.
+ * Settings changes are never reviewed through a PR (see commitToSettingsBranch).
  */
 export declare function commitSettings(ctx: ApiContext, options: {
     context: {

package/dist/api/settings-helpers.js

@@ -23,7 +23,7 @@ export async function getSettingsBranchContext(ctx) {
 /**
  * Commit and push settings changes based on the mode.
  * Both prod and dev use commitToSettingsBranch.
- * In dev mode, commits to the settings branch but does not create a PR.
+ * Settings changes are never reviewed through a PR (see commitToSettingsBranch).
  */
 export async function commitSettings(ctx, options) {
     const strategy = operatingStrategy(options.mode);
@@ -38,9 +38,6 @@ export async function commitSettings(ctx, options) {
             branchRoot: options.branchRoot,
             files: options.fileName,
             message: options.message,
-            createPR: strategy.shouldCreateSettingsPR({
-                autoCreateSettingsPR: ctx.services.config.autoCreateSettingsPR,
-            }),
         });
         if (!result.pushed) {
             console.warn(`${options.message} committed but not pushed:`, result.error);

package/dist/api/user.d.ts

@@ -1,7 +1,10 @@
 import type { ApiResponse } from './types.js';
+import type { BuildIdentity } from '../types.js';
 export type UserInfoResponse = ApiResponse<{
     userId: string;
     groups: string[];
+    /** Admins only: the deployed version is reconnaissance for anyone else. */
+    build?: BuildIdentity;
 }>;
 export declare const USER_ROUTES: {
     readonly whoami: import("./route-builder.js").RouteDefinition<undefined, undefined, UserInfoResponse>;

package/dist/api/user.js

@@ -1,4 +1,6 @@
 import { defineEndpoint } from './route-builder.js';
+import { isAdmin } from '../authorization/helpers.js';
+import { getBuildIdentity } from '../build-identity.js';
 /**
  * This is a PUBLIC endpoint - no special permissions required
  */
@@ -10,6 +12,7 @@ const getUserInfoHandler = async (ctx, req) => {
         data: {
             userId: req.user.userId,
             groups: req.user.groups,
+            ...(isAdmin(req.user.groups) ? { build: getBuildIdentity() } : {}),
         },
     };
 };

package/dist/assets/asset-url.d.ts

@@ -1,14 +1,17 @@
 /**
  * Build/adjust transform URLs for `<img>`/srcset without pulling in the
- * server-only transform engine. Isomorphic - depends only on
- * transform-directives.ts, the plain `ASSET_PREFIXES` constant, and
- * utils/url-prefix.ts, none of which import node builtins, so this is safe to
- * import from client (editor) code as well as during static builds.
+ * server-only transform engine. Isomorphic - none of its imports reach a node
+ * builtin, so this is safe to import from client (editor) code as well as during
+ * static builds.
  */
 import { type CropRect, type OutputFormat } from './transform-directives.js';
-/** The minimal shape `assetUrl`/`assetSrcSet` need from a stored asset reference. */
+/**
+ * The minimal shape `assetUrl`/`assetSrcSet` need from a stored asset reference. An
+ * `ImageFieldValue` is one, so passing a field value renders the crop the editor stored.
+ */
 export interface AssetRef {
     src: string;
+    crop?: CropRect;
 }
 export interface AssetUrlOptions {
     width?: number;
@@ -23,16 +26,14 @@ export interface AssetUrlOptions {
      * option beside it. Two shapes are legitimate, and they are alternatives, never composed:
      *
      * - An absolute origin (`https://assets.example.com`) — assets served from another origin.
-     *   `media.publicBaseUrl` is one source of this, and is the source the editor uses; it is
-     *   validated as an absolute URL, so it structurally cannot carry the second shape.
      * - A same-origin path prefix (`/preview-123`) — the site is deployed under a Next `basePath`
      *   AND its assets are served by Next (`withCanopy`'s `/assets/:path*` rewrite, which Next
      *   auto-prefixes). NOT the right value on a CloudFront/CDK deployment, where the asset
      *   behaviors are anchored at the distribution root and a `basePath` does not move them —
      *   there the correct value is none at all. See the README's asset-mount table.
      *
-     * It is a per-render option rather than a config field precisely because the editor and the
-     * public site can legitimately have different answers.
+     * It is a per-render option rather than a config field because different renderers see the
+     * `/assets` space at different places.
      *
      * **Render-time only — never stored.** A stored `src` is always root-relative (see
      * `assets/asset-src.ts`), because content moves between branches and environments. Nothing
@@ -41,16 +42,21 @@ export interface AssetUrlOptions {
     baseUrl?: string;
 }
 /**
- * Build a transform URL, merging `opts` over the directives already present
- * in `ref.src` (opts win). For static srcs (svg/pdf under `/assets/{hash}/...`,
- * or any src that isn't one of our own transform URLs) the src is returned
- * unchanged and `opts` are ignored - there is nothing to transform.
+ * Build a transform URL, merging `opts` and `ref.crop` over the directives already present
+ * in `ref.src` (see `mergeDirectives` for precedence). For static srcs (svg/pdf under
+ * `/assets/{hash}/...`, or any src that isn't one of our own transform URLs) the src is
+ * returned unchanged and every directive is ignored - there is nothing to transform.
+ *
+ * In a live preview, a transform URL goes behind the editor's authenticated route
+ * (`editor/preview-asset-base.ts`) instead of `opts.baseUrl`: a draft's crop or width may exist
+ * nowhere a build put it. Static srcs keep `opts.baseUrl`, since finalize wrote them.
  */
 export declare function assetUrl(ref: AssetRef, opts?: AssetUrlOptions): string;
 /**
  * Build a comma-joined `url w` srcset descriptor list. `widths` must all be
- * on the transform width allowlist (multiples of 160 in [160, 4096]) - this
- * is developer-facing (a host app's own responsive-image markup), so an
- * invalid width throws rather than silently dropping it.
+ * integers in [1, 8192] (the `any` width policy) - this is developer-facing (a
+ * host app's own responsive-image markup), so an invalid width throws rather
+ * than silently dropping it. A site serving the opt-in lazy public path, which
+ * transforms only allowlisted widths, must pick widths from that allowlist.
  */
 export declare function assetSrcSet(ref: AssetRef, widths: readonly number[], opts?: Omit<AssetUrlOptions, 'width'>): string;

package/dist/assets/asset-url.js

@@ -1,36 +1,51 @@
 /**
  * Build/adjust transform URLs for `<img>`/srcset without pulling in the
- * server-only transform engine. Isomorphic - depends only on
- * transform-directives.ts, the plain `ASSET_PREFIXES` constant, and
- * utils/url-prefix.ts, none of which import node builtins, so this is safe to
- * import from client (editor) code as well as during static builds.
+ * server-only transform engine. Isomorphic - none of its imports reach a node
+ * builtin, so this is safe to import from client (editor) code as well as during
+ * static builds.
  */
 import { isUnprefixablePath, joinUrlPrefix, sanitizeUnprefixedPath, stripTrailingSlashes, } from '../utils/url-prefix.js';
+import { getPreviewAssetBase } from '../editor/preview-asset-base.js';
 import { ASSET_PREFIXES } from './asset-prefixes.js';
 import { formatDirectives, isAllowedTransformWidth, parseTransformPath, } from './transform-directives.js';
 const TRANSFORM_URL_PREFIX = `/${ASSET_PREFIXES.transform}/`;
 /**
- * Merge `opts` over an already-parsed directive set - opts win when given,
- * otherwise the existing value (if any) carries over. Returns `undefined`
- * fields as "unset" (there is no way to explicitly clear a directive via
- * opts - only to override it).
+ * Test-only. A function stored on `globalThis` under this symbol is called with every URL
+ * `assetUrl` returns; the dual-build fixture installs one during a static export to prove
+ * `collect-asset-refs` finds every URL its pages emitted.
  */
-function mergeDirectives(current, opts) {
+const EMITTED_URL_LISTENER = Symbol.for('canopycms.assetUrl.emitted');
+function emitted(url) {
+    const listener = globalThis[EMITTED_URL_LISTENER];
+    if (typeof listener === 'function')
+        listener(url);
+    return url;
+}
+/**
+ * Merge `opts` and the ref's crop over the directives already in its src. Precedence per
+ * directive: `opts`, then `ref.crop` (crop only), then the src. There is no way to clear a
+ * directive, only to override it.
+ */
+function mergeDirectives(current, refCrop, opts) {
     const existing = current.identity ? undefined : current;
     const width = opts.width ?? existing?.width;
     const format = opts.format ?? existing?.format;
     const quality = opts.quality ?? existing?.quality;
-    const crop = opts.crop ?? existing?.crop;
+    const crop = opts.crop ?? refCrop ?? existing?.crop;
     if (width === undefined && format === undefined && quality === undefined && crop === undefined) {
         return { identity: true };
     }
     return { identity: false, width, format, quality, crop };
 }
 /**
- * Build a transform URL, merging `opts` over the directives already present
- * in `ref.src` (opts win). For static srcs (svg/pdf under `/assets/{hash}/...`,
- * or any src that isn't one of our own transform URLs) the src is returned
- * unchanged and `opts` are ignored - there is nothing to transform.
+ * Build a transform URL, merging `opts` and `ref.crop` over the directives already present
+ * in `ref.src` (see `mergeDirectives` for precedence). For static srcs (svg/pdf under
+ * `/assets/{hash}/...`, or any src that isn't one of our own transform URLs) the src is
+ * returned unchanged and every directive is ignored - there is nothing to transform.
+ *
+ * In a live preview, a transform URL goes behind the editor's authenticated route
+ * (`editor/preview-asset-base.ts`) instead of `opts.baseUrl`: a draft's crop or width may exist
+ * nowhere a build put it. Static srcs keep `opts.baseUrl`, since finalize wrote them.
  */
 export function assetUrl(ref, opts = {}) {
     const { src } = ref;
@@ -46,35 +61,37 @@ export function assetUrl(ref, opts = {}) {
         // `joinUrlPrefix`'s own contract. Plain `!opts.baseUrl` made '' and '/' disagree.
         const mount = opts.baseUrl ? stripTrailingSlashes(opts.baseUrl) : '';
         if (!mount || isUnprefixablePath(src))
-            return sanitizeUnprefixedPath(src);
-        return joinUrlPrefix(opts.baseUrl, src);
+            return emitted(sanitizeUnprefixedPath(src));
+        return emitted(joinUrlPrefix(opts.baseUrl, src));
     }
+    const base = getPreviewAssetBase() ?? opts.baseUrl;
     const rest = src.slice(TRANSFORM_URL_PREFIX.length);
-    const parsed = parseTransformPath(rest.split('/'));
+    const parsed = parseTransformPath(rest.split('/'), 'any');
     if (!parsed.ok) {
         // Malformed src (shouldn't happen for a src canopycms itself wrote) -
         // nothing sensible to merge onto, so return it unchanged rather than throw.
-        return joinUrlPrefix(opts.baseUrl, src);
+        return emitted(joinUrlPrefix(base, src));
     }
-    const merged = mergeDirectives(parsed.directives, opts);
+    const merged = mergeDirectives(parsed.directives, ref.crop, opts);
     // Ext follows the format: an explicit format (new or carried over) always
     // wins; with no format at all, the ext must keep preserving the source's
     // real extension, which is exactly what `parsed.ext` already is here.
     const ext = !merged.identity && merged.format !== undefined ? merged.format : parsed.ext;
     const newSrc = `${TRANSFORM_URL_PREFIX}${formatDirectives(merged)}/${parsed.hash32}/${parsed.slug}.${ext}`;
-    return joinUrlPrefix(opts.baseUrl, newSrc);
+    return emitted(joinUrlPrefix(base, newSrc));
 }
 /**
  * Build a comma-joined `url w` srcset descriptor list. `widths` must all be
- * on the transform width allowlist (multiples of 160 in [160, 4096]) - this
- * is developer-facing (a host app's own responsive-image markup), so an
- * invalid width throws rather than silently dropping it.
+ * integers in [1, 8192] (the `any` width policy) - this is developer-facing (a
+ * host app's own responsive-image markup), so an invalid width throws rather
+ * than silently dropping it. A site serving the opt-in lazy public path, which
+ * transforms only allowlisted widths, must pick widths from that allowlist.
  */
 export function assetSrcSet(ref, widths, opts = {}) {
     return widths
         .map((width) => {
-        if (!isAllowedTransformWidth(width)) {
-            throw new Error(`assetSrcSet: width ${width} is not allowed (must be a multiple of 160 between 160 and 4096)`);
+        if (!isAllowedTransformWidth(width, 'any')) {
+            throw new Error(`assetSrcSet: width ${width} is not allowed (must be an integer between 1 and 8192)`);
         }
         return `${assetUrl(ref, { ...opts, width })} ${width}w`;
     })

package/dist/assets/factory.d.ts

@@ -3,6 +3,11 @@
  *
  * This is the one place that turns the (currently-unconsumed) `media` config
  * into a real store — see .claude/future-tasks/resolved/assets-media-system.md.
+ *
+ * The store is branch-agnostic: a local one is rooted at the dev workspace's
+ * `assets/` or at `media.directory` resolved against the process's working
+ * directory, never inside a branch clone. So asset writes take no [SYNC-C1]
+ * content-write lock — the worker's rebase never touches them.
  */
 import type { MediaConfig } from '../config/types.js';
 import type { AssetStore } from './types.js';

package/dist/assets/factory.js

@@ -3,6 +3,11 @@
  *
  * This is the one place that turns the (currently-unconsumed) `media` config
  * into a real store — see .claude/future-tasks/resolved/assets-media-system.md.
+ *
+ * The store is branch-agnostic: a local one is rooted at the dev workspace's
+ * `assets/` or at `media.directory` resolved against the process's working
+ * directory, never inside a branch clone. So asset writes take no [SYNC-C1]
+ * content-write lock — the worker's rebase never touches them.
  */
 import { LocalAssetStore } from './store-local.js';
 import { S3AssetStore } from './store-s3.js';

package/dist/assets/finalize.js

@@ -39,6 +39,9 @@ export async function finalizeAsset(store, input) {
     const existing = await store.getMeta(meta.hash32);
     if (existing)
         return { ok: true, meta: existing };
+    // Either put may find its key taken (`already-exists`): by an earlier attempt that stopped
+    // before the meta commit, or by a concurrent identical upload. The object kept there is this
+    // content's, so finalize goes on to commit the meta either way.
     await store.putOriginal({ hash32: meta.hash32, ext: meta.ext, data, contentType: meta.mime });
     if (publicObject) {
         await store.putPublicObject(publicObject);

package/dist/assets/index.d.ts

@@ -14,6 +14,6 @@ export { ALLOWED_UPLOAD_CONTENT_TYPES, runFinalizePipeline, type FinalizeInput,
 export { finalizeAsset, finalizeStagedUpload, type FinalizeAssetResult } from './finalize.js';
 export { sanitizeSvg } from './svg-sanitizer.js';
 export { assetSrc } from './asset-src.js';
-export { formatDirectives, isAllowedTransformWidth, isValidCropRect, parseTransformPath, type CropRect, type OutputFormat, type ParsedTransformPath, type ParseTransformPathResult, type TransformDirectives, } from './transform-directives.js';
+export { formatDirectives, isAllowedTransformWidth, isValidCropRect, parseTransformPath, type CropRect, type OutputFormat, type ParsedTransformPath, type ParseTransformPathResult, type TransformDirectives, type TransformWidthPolicy, } from './transform-directives.js';
 export { applyTransform, type ApplyTransformInput, type TransformResult } from './transform.js';
 export { assetUrl, assetSrcSet, type AssetRef, type AssetUrlOptions } from './asset-url.js';

package/dist/assets/materialize.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Writing transform outputs into the store. Server-only.
+ *
+ * `storeTransform` computes one key and is shared by the authenticated raw route
+ * (api/assets.ts), `materializeAssets` (the batch run that writes every key a build references
+ * before that build is released) and canopycms-cdk's lazy transform Lambda.
+ */
+import { type ParsedTransformPath } from './transform-directives.js';
+import type { AssetStore, CreateOnlyResult } from './types.js';
+/** Every transform output is stored under a content-addressed key, so it never changes. */
+export declare const TRANSFORM_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/**
+ * The object tag on every derivative the lazy transform Lambda writes. Its bucket's `assets/t/`
+ * expiry filters on it, so what `materializeAssets` writes, which the Lambda's allowlist may refuse
+ * to recompute, is never expired. canopycms-cdk's `AssetSupport` copies these two strings as
+ * literals.
+ */
+export declare const LAZY_TRANSFORM_TAG: {
+    readonly key: "canopy-transform";
+    readonly value: "lazy";
+};
+/**
+ * `data` is the computed output whether or not it was stored: `stored: 'already-exists'` means
+ * another writer stored the key first, and the store kept that object.
+ */
+export type StoreTransformResult = {
+    ok: true;
+    data: Uint8Array;
+    contentType: string;
+    stored: CreateOnlyResult;
+} | {
+    ok: false;
+    status: 400 | 404 | 413 | 422;
+    error: string;
+};
+/**
+ * Compute the transform `parsed` names from the asset's original and write it under `key`: the
+ * canonical key, or that key beneath an output prefix. `parsed` must come from
+ * `canonicalizeTransformPath`, so the stored pixels always match their key. A rejection is a fact
+ * about the asset or the URL and is never worth retrying; a thrown error belongs to the store or
+ * the environment. A 404's `error` names what was missing, so a caller answering a browser
+ * replaces it.
+ */
+export declare function storeTransform(store: AssetStore, parsed: ParsedTransformPath, key: string, options?: {
+    tags?: Readonly<Record<string, string>>;
+}): Promise<StoreTransformResult>;
+/** One key a build references, and where it was referenced, for the failure report. */
+export interface MaterializeTarget {
+    /** `assets/t/{directives}/{hash32}/{slug}.{ext}`. */
+    key: string;
+    routes: readonly string[];
+    files: readonly string[];
+}
+/**
+ * `content`: the key cannot be produced from what the store holds (asset deleted, wrong slug,
+ * undecodable input, malformed key), so a retry would fail the same way and the page must change.
+ * `store`: the store kept failing, or refused the request outright; rerunning may succeed.
+ */
+type MaterializeFailureKind = 'content' | 'store';
+export type MaterializeResult = {
+    key: string;
+    routes: string[];
+    files: string[];
+} & ({
+    status: 'existed' | 'created' | 'copied';
+} | {
+    status: 'failed';
+    failure: MaterializeFailureKind;
+    error: string;
+});
+/** The `schemaVersion` of every `MaterializeReport`; a consumer gating on the JSON checks it. */
+export declare const MATERIALIZE_REPORT_SCHEMA_VERSION = 1;
+export interface MaterializeReport {
+    schemaVersion: typeof MATERIALIZE_REPORT_SCHEMA_VERSION;
+    /** `MaterializeOptions.outputPrefix`, present only when one was given. */
+    outputPrefix?: string;
+    summary: {
+        total: number;
+        existed: number;
+        created: number;
+        /** Keys copied from the canonical prefix into an output prefix; 0 until one is configured. */
+        copied: number;
+        failed: number;
+        contentFailures: number;
+        storeFailures: number;
+    };
+    /** Sorted by key. */
+    results: MaterializeResult[];
+}
+export interface MaterializeOptions {
+    store: AssetStore;
+    targets: readonly MaterializeTarget[];
+    /**
+     * `assets/{hash32}/{slug}.{ext}` keys (svg, pdf) a build references. These are never produced
+     * here (finalize writes them at upload), only checked, or copied under an `outputPrefix`, so a
+     * missing one is a content failure, unless the bucket itself is missing: a store failure.
+     */
+    statics?: readonly MaterializeTarget[];
+    /**
+     * Write every key `k` at `outputPrefix + k` instead, for a build whose writes must never land
+     * where production reads (a PR preview). A key production already stores is copied from there;
+     * the rest are transformed from the canonical originals. Production's own run, with no prefix,
+     * never reads beneath it. See `assertValidOutputPrefix` for what is accepted.
+     */
+    outputPrefix?: string;
+    /** Store requests in flight at once. Default 8. */
+    concurrency?: number;
+    /**
+     * Transforms in flight at once. Each holds a decoded image, up to about 1.2 GiB at
+     * `MAX_INPUT_PIXELS`, so this stays small whatever `concurrency` is. Default 2.
+     */
+    transformConcurrency?: number;
+    /**
+     * A directive string referenced by at least this many keys has its whole `assets/t/{directives}/`
+     * prefix listed once instead of a HEAD per key, when the store can list. Default 100.
+     */
+    listThreshold?: number;
+    /** Attempts per store operation, including the first. Default 3. */
+    attempts?: number;
+    /** First retry delay; each later one doubles. Default 500. */
+    baseDelayMs?: number;
+    /** @internal Test seam for the retry delay. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** sharp cannot load in this process, so nothing missing can be produced here. */
+export declare class SharpUnavailableError extends Error {
+    constructor(cause: unknown);
+}
+/** `MaterializeOptions.outputPrefix` broke a rule of `assertValidOutputPrefix`; nothing was read or written. */
+export declare class InvalidOutputPrefixError extends Error {
+    constructor(prefix: string, reason: string);
+}
+/**
+ * Throws `InvalidOutputPrefixError` unless `prefix` is relative, ends in `/`, and is a run of
+ * `[A-Za-z0-9._-]` segments, none empty, `.` or `..`, whose first segments are not a canopy
+ * prefix. Production trusts whatever is under its own prefixes, so a write beneath one is a write
+ * production serves. Compared by segment: `assets-x/` is accepted, `assets/x/` is not.
+ */
+export declare function assertValidOutputPrefix(prefix: string): void;
+/**
+ * @internal Exported for tests. Throttling, 5xx and dropped connections are transient. Any other
+ * 4xx (AccessDenied, NoSuchBucket) is a configuration fault that a retry only delays.
+ */
+export declare function isTransientStoreError(err: unknown): boolean;
+/**
+ * Make every referenced transform key exist in `store`, and check every static key does. A key
+ * already stored is left alone:
+ * keys are content-addressed, so an existing object is the right one. sharp is loaded only when
+ * something must be transformed, and a sharp that cannot load throws `SharpUnavailableError` rather
+ * than failing each key. An invalid `outputPrefix` throws `InvalidOutputPrefixError` first.
+ */
+export declare function materializeAssets(options: MaterializeOptions): Promise<MaterializeReport>;
+export {};