canopycms 0.0.67 → 0.0.68-int.100

package/dist/assets/materialize.js

@@ -0,0 +1,305 @@
+/**
+ * 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 { getErrorMessage, isNodeError } from '../utils/error.js';
+import { ASSET_PREFIXES } from './asset-prefixes.js';
+import { loadSharp } from './sharp-loader.js';
+import { applyTransform } from './transform.js';
+import { canonicalizeTransformPath } from './transform-directives.js';
+/** Every transform output is stored under a content-addressed key, so it never changes. */
+export 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 const LAZY_TRANSFORM_TAG = { key: 'canopy-transform', value: 'lazy' };
+/**
+ * Compute the transform `parsed` names from the asset's original and write it under
+ * `canonicalKey`. `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 async function storeTransform(store, parsed, canonicalKey, options = {}) {
+    const meta = await store.getMeta(parsed.hash32);
+    if (!meta) {
+        return { ok: false, status: 404, error: `Asset ${parsed.hash32} has no meta in the store` };
+    }
+    if (meta.kind !== 'raster') {
+        return { ok: false, status: 400, error: 'Not a raster asset - svg/pdf are served statically' };
+    }
+    // The slug is decorative in the URL but load-bearing in the stored key, so it must equal the
+    // asset's real slug — the parser only enforces `[a-z0-9-]+`, and any other string that passes
+    // it aliases the same image into a new cache key.
+    if (parsed.slug !== meta.slug) {
+        return {
+            ok: false,
+            status: 404,
+            error: `Slug '${parsed.slug}' is not asset ${parsed.hash32}'s slug '${meta.slug}'`,
+        };
+    }
+    // Without an explicit `f=`, the transform keeps the source format, so the URL's `{ext}` must be
+    // the source's real ext. The parser cannot check this: it does not know the source format.
+    const requestedFormat = parsed.directives.identity ? undefined : parsed.directives.format;
+    if (requestedFormat === undefined && parsed.ext !== meta.ext) {
+        return { ok: false, status: 400, error: 'Extension does not match the source format' };
+    }
+    const original = await store.readOriginal(parsed.hash32, meta.ext);
+    if (!original) {
+        return { ok: false, status: 404, error: `Asset ${parsed.hash32} has no original in the store` };
+    }
+    const transformed = await applyTransform({ data: original.data, ext: original.ext }, parsed.directives);
+    if (!transformed.ok) {
+        return { ok: false, status: transformed.status, error: transformed.error };
+    }
+    await store.putPublicObject({
+        key: canonicalKey,
+        data: transformed.data,
+        contentType: transformed.contentType,
+        cacheControl: TRANSFORM_CACHE_CONTROL,
+        tags: options.tags,
+    });
+    return { ok: true, data: transformed.data, contentType: transformed.contentType };
+}
+/** sharp cannot load in this process, so nothing missing can be produced here. */
+export class SharpUnavailableError extends Error {
+    constructor(cause) {
+        super(`sharp failed to load, so the missing transform outputs cannot be produced in this ` +
+            `environment: ${getErrorMessage(cause)}. Install sharp for this platform and rerun.`);
+        this.name = 'SharpUnavailableError';
+    }
+}
+const DEFAULT_CONCURRENCY = 8;
+const DEFAULT_TRANSFORM_CONCURRENCY = 2;
+// eslint-disable-next-line security/detect-non-literal-regexp -- built from a constant
+const STATIC_KEY_RE = new RegExp(`^${ASSET_PREFIXES.public}/[a-f0-9]{32}/[a-z0-9-]+\\.[a-z0-9]{1,10}$`);
+const DEFAULT_LIST_THRESHOLD = 100;
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 500;
+const TRANSIENT_NODE_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EPIPE',
+    'EAI_AGAIN',
+    'EBUSY',
+    'EMFILE',
+]);
+const TRANSIENT_ERROR_NAMES = new Set([
+    'TimeoutError',
+    'RequestTimeout',
+    'RequestTimeoutException',
+    'SlowDown',
+    'Throttling',
+    'ThrottlingException',
+    'ServiceUnavailable',
+    'InternalError',
+]);
+/**
+ * @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 function isTransientStoreError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (isNodeError(err) && err.code && TRANSIENT_NODE_CODES.has(err.code))
+        return true;
+    const shaped = err;
+    if (shaped.$retryable)
+        return true;
+    if (TRANSIENT_ERROR_NAMES.has(err.name))
+        return true;
+    const status = shaped.$metadata?.httpStatusCode;
+    return status !== undefined && (status === 429 || status >= 500);
+}
+/** Run `fn` over `items` with at most `limit` in flight. `fn` must not reject. */
+async function forEachBounded(items, limit, fn) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const item = items[next++];
+            await fn(item);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+/**
+ * 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 is missing, and a sharp that cannot load throws `SharpUnavailableError` rather than
+ * failing each key.
+ */
+export async function materializeAssets(options) {
+    const { store } = options;
+    const concurrency = Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY);
+    const transformConcurrency = Math.max(1, options.transformConcurrency ?? DEFAULT_TRANSFORM_CONCURRENCY);
+    const listThreshold = options.listThreshold ?? DEFAULT_LIST_THRESHOLD;
+    const attempts = Math.max(1, options.attempts ?? DEFAULT_ATTEMPTS);
+    const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const withRetry = async (operation) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (err) {
+                if (attempt >= attempts || !isTransientStoreError(err))
+                    throw err;
+                await sleep(baseDelayMs * 2 ** (attempt - 1) * (1 + Math.random()));
+            }
+        }
+    };
+    const references = new Map();
+    const staticKeys = new Set((options.statics ?? []).map((target) => target.key));
+    for (const target of [...options.targets, ...(options.statics ?? [])]) {
+        const entry = references.get(target.key) ?? { routes: new Set(), files: new Set() };
+        target.routes.forEach((route) => entry.routes.add(route));
+        target.files.forEach((file) => entry.files.add(file));
+        references.set(target.key, entry);
+    }
+    const outcomes = new Map();
+    const fail = (key, failure, error) => outcomes.set(key, { status: 'failed', failure, error });
+    // The refs file is an editable file on disk, so every key is re-validated here.
+    const transformPrefix = `${ASSET_PREFIXES.transform}/`;
+    const valid = [];
+    const validStatics = [];
+    for (const key of references.keys()) {
+        if (staticKeys.has(key)) {
+            if (STATIC_KEY_RE.test(key))
+                validStatics.push(key);
+            else
+                fail(key, 'content', 'Not a static asset key (expected assets/{hash32}/{slug}.{ext})');
+            continue;
+        }
+        if (!key.startsWith(transformPrefix)) {
+            fail(key, 'content', `Not a transform key (expected a ${transformPrefix} prefix)`);
+            continue;
+        }
+        const segments = key.slice(transformPrefix.length).split('/');
+        const canonical = canonicalizeTransformPath(segments, 'any');
+        if (!canonical.ok) {
+            fail(key, 'content', `Invalid transform key: ${canonical.error}`);
+        }
+        else if (!canonical.isCanonical) {
+            fail(key, 'content', `Not canonical; the stored key would be ${transformPrefix}${canonical.canonicalPath}`);
+        }
+        else {
+            valid.push({ key, directives: segments[0], parsed: canonical });
+        }
+    }
+    const byDirectives = new Map();
+    for (const target of valid) {
+        const group = byDirectives.get(target.directives) ?? [];
+        group.push(target);
+        byDirectives.set(target.directives, group);
+    }
+    const toHead = [];
+    for (const [directives, group] of byDirectives) {
+        if (store.listPublicObjectKeys && group.length >= listThreshold) {
+            const listPrefix = `${transformPrefix}${directives}/`;
+            const listKeys = store.listPublicObjectKeys.bind(store);
+            try {
+                const found = await withRetry(async () => {
+                    const keys = [];
+                    for await (const key of listKeys(listPrefix))
+                        keys.push(key);
+                    return keys;
+                });
+                const listed = new Set(found);
+                for (const target of group) {
+                    if (listed.has(target.key))
+                        outcomes.set(target.key, { status: 'existed' });
+                }
+                continue;
+            }
+            catch {
+                // A listing that keeps failing costs only speed: HEAD the group instead, and let each
+                // HEAD report its own failure.
+            }
+        }
+        toHead.push(...group);
+    }
+    await forEachBounded(toHead, concurrency, async (target) => {
+        try {
+            if (await withRetry(() => store.hasPublicObject(target.key))) {
+                outcomes.set(target.key, { status: 'existed' });
+            }
+        }
+        catch (err) {
+            fail(target.key, 'store', `Existence check failed: ${getErrorMessage(err)}`);
+        }
+    });
+    await forEachBounded(validStatics, concurrency, async (key) => {
+        try {
+            // A HEAD cannot tell a missing key from a missing bucket, and a static key has no
+            // transform's meta read to tell them apart afterwards; a GET names which.
+            const exists = (await withRetry(() => store.hasPublicObject(key))) ||
+                (await withRetry(() => store.readPublicObject(key))) !== null;
+            if (exists) {
+                outcomes.set(key, { status: 'existed' });
+            }
+            else {
+                fail(key, 'content', 'No stored object; an svg or pdf is written at upload only');
+            }
+        }
+        catch (err) {
+            fail(key, 'store', `Existence check failed: ${getErrorMessage(err)}`);
+        }
+    });
+    const missing = valid.filter((target) => !outcomes.has(target.key));
+    if (missing.length > 0) {
+        try {
+            await loadSharp();
+        }
+        catch (err) {
+            throw new SharpUnavailableError(err);
+        }
+    }
+    await forEachBounded(missing, transformConcurrency, async (target) => {
+        try {
+            const result = await withRetry(() => storeTransform(store, target.parsed, target.key));
+            if (result.ok) {
+                outcomes.set(target.key, { status: 'created' });
+            }
+            else {
+                fail(target.key, 'content', `${result.status}: ${result.error}`);
+            }
+        }
+        catch (err) {
+            fail(target.key, 'store', getErrorMessage(err));
+        }
+    });
+    const results = [...references.keys()].sort().map((key) => {
+        const refs = references.get(key);
+        const outcome = outcomes.get(key) ?? {
+            status: 'failed',
+            failure: 'store',
+            error: 'No outcome recorded',
+        };
+        return {
+            key,
+            routes: [...(refs?.routes ?? [])].sort(),
+            files: [...(refs?.files ?? [])].sort(),
+            ...outcome,
+        };
+    });
+    const count = (predicate) => results.filter(predicate).length;
+    return {
+        summary: {
+            total: results.length,
+            existed: count((r) => r.status === 'existed'),
+            created: count((r) => r.status === 'created'),
+            failed: count((r) => r.status === 'failed'),
+            contentFailures: count((r) => r.status === 'failed' && r.failure === 'content'),
+            storeFailures: count((r) => r.status === 'failed' && r.failure === 'store'),
+        },
+        results,
+    };
+}

package/dist/assets/store-local.d.ts

@@ -48,6 +48,7 @@ export declare class LocalAssetStore implements AssetStore {
         data: Uint8Array;
         contentType: string;
     }): Promise<void>;
+    /** Ignores the `ext` hint: a directory read costs nothing here and needs no permission. */
     readOriginal(hash32: string): Promise<{
         data: Uint8Array;
         ext: string;
@@ -59,8 +60,11 @@ export declare class LocalAssetStore implements AssetStore {
         contentType: string;
         contentDisposition?: string;
         cacheControl?: string;
+        /** Ignored: tags exist for bucket lifecycle rules, and a local store has none. */
+        tags?: Readonly<Record<string, string>>;
     }): Promise<void>;
     readPublicObject(key: string): Promise<PublicObject | null>;
+    hasPublicObject(key: string): Promise<boolean>;
     /**
      * Atomic-exclusive create: opens with the `wx` flag so two concurrent
      * writers racing on the same hash32 have exactly one winner ('created')

package/dist/assets/store-local.js

@@ -113,6 +113,7 @@ export class LocalAssetStore {
         await this.writeFile(filePath, input.data);
         await this.writeHeadersSidecar(filePath, { contentType: input.contentType });
     }
+    /** Ignores the `ext` hint: a directory read costs nothing here and needs no permission. */
     async readOriginal(hash32) {
         const dir = this.resolveKey(ASSET_PREFIXES.originals);
         let entries;
@@ -157,6 +158,16 @@ export class LocalAssetStore {
             cacheControl: headers.cacheControl,
         };
     }
+    async hasPublicObject(key) {
+        try {
+            return (await fs.stat(this.resolveKey(key))).isFile();
+        }
+        catch (err) {
+            if (isNotFoundError(err))
+                return false;
+            throw err;
+        }
+    }
     /**
      * Atomic-exclusive create: opens with the `wx` flag so two concurrent
      * writers racing on the same hash32 have exactly one winner ('created')

package/dist/assets/store-s3.d.ts

@@ -60,7 +60,7 @@ export declare class S3AssetStore implements AssetStore {
         data: Uint8Array;
         contentType: string;
     }): Promise<void>;
-    readOriginal(hash32: string): Promise<{
+    readOriginal(hash32: string, ext?: string): Promise<{
         data: Uint8Array;
         ext: string;
         contentType?: string;
@@ -71,8 +71,17 @@ export declare class S3AssetStore implements AssetStore {
         contentType: string;
         contentDisposition?: string;
         cacheControl?: string;
+        tags?: Readonly<Record<string, string>>;
     }): Promise<void>;
     readPublicObject(key: string): Promise<PublicObject | null>;
+    /**
+     * A HEAD. S3 answers a missing key with 403, not 404, unless the caller may `s3:ListBucket`,
+     * so a role without it sees an error here rather than `false`.
+     */
+    hasPublicObject(key: string): Promise<boolean>;
+    listPublicObjectKeys(prefix: string): AsyncIterable<string>;
+    /** HEADs first: signing is local and succeeds for a missing key too. */
+    presignPublicObjectRead(key: string): Promise<string | null>;
     putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<'created' | 'already-exists'>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
     listMeta(input?: {

package/dist/assets/store-s3.js

@@ -5,12 +5,15 @@
  * and writes objects under the five asset prefixes.
  */
 import { randomUUID } from 'node:crypto';
-import { DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, paginateListObjectsV2, } from '@aws-sdk/client-s3';
 import { createPresignedPost } from '@aws-sdk/s3-presigned-post';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { isHttpUrlOrSameOriginPath } from '../utils/sanitize-href.js';
 import { ASSET_PREFIXES, createKeyBuilders } from './keys.js';
 const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 const PRESIGN_EXPIRY_SECONDS = 15 * 60;
+/** A presigned read is followed by the browser at once; it is never stored or cached. */
+const PRESIGNED_READ_EXPIRY_SECONDS = 5 * 60;
 function matchesAwsError(err, name, httpStatusCode) {
     if (!(err instanceof Error))
         return false;
@@ -18,7 +21,12 @@ function matchesAwsError(err, name, httpStatusCode) {
     return shaped.name === name || shaped.$metadata?.httpStatusCode === httpStatusCode;
 }
 const isPreconditionFailed = (err) => matchesAwsError(err, 'PreconditionFailed', 412);
-const isNoSuchKey = (err) => matchesAwsError(err, 'NoSuchKey', 404);
+/**
+ * A missing key, never a missing bucket: S3 answers both with 404, and only a GET's error code names
+ * which. A HEAD's 404 has no body, so `hasPublicObject` reads either as absent; a caller that must
+ * tell them apart follows with a GET (assets/materialize.ts does).
+ */
+const isNoSuchKey = (err) => matchesAwsError(err, 'NoSuchKey', 404) && err.name !== 'NoSuchBucket';
 export class S3AssetStore {
     constructor(options) {
         this.capabilities = { directUpload: true };
@@ -97,7 +105,13 @@ export class S3AssetStore {
             ContentType: input.contentType,
         }));
     }
-    async readOriginal(hash32) {
+    async readOriginal(hash32, ext) {
+        if (ext !== undefined) {
+            const direct = await this.getObject(this.keys.originalKey(hash32, ext));
+            const data = await direct?.Body?.transformToByteArray();
+            if (data)
+                return { data, ext, contentType: direct?.ContentType };
+        }
         const prefix = this.keys.originalPrefix(hash32);
         const listed = await this.client.send(new ListObjectsV2Command({ Bucket: this.bucket, Prefix: prefix, MaxKeys: 1 }));
         const foundKey = listed.Contents?.[0]?.Key;
@@ -112,6 +126,11 @@ export class S3AssetStore {
         return { data, ext: foundKey.slice(prefix.length), contentType: result.ContentType };
     }
     async putPublicObject(input) {
+        // `encodeURIComponent` writes a space as `%20`, which reads the same to any decoder;
+        // URLSearchParams writes `+`.
+        const tagging = Object.entries(input.tags ?? {})
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+            .join('&');
         await this.client.send(new PutObjectCommand({
             Bucket: this.bucket,
             Key: input.key,
@@ -119,6 +138,7 @@ export class S3AssetStore {
             ContentType: input.contentType,
             ContentDisposition: input.contentDisposition,
             CacheControl: input.cacheControl,
+            Tagging: tagging || undefined,
         }));
     }
     async readPublicObject(key) {
@@ -135,6 +155,38 @@ export class S3AssetStore {
             cacheControl: result.CacheControl,
         };
     }
+    /**
+     * A HEAD. S3 answers a missing key with 403, not 404, unless the caller may `s3:ListBucket`,
+     * so a role without it sees an error here rather than `false`.
+     */
+    async hasPublicObject(key) {
+        try {
+            await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+            return true;
+        }
+        catch (err) {
+            if (isNoSuchKey(err))
+                return false;
+            throw err;
+        }
+    }
+    async *listPublicObjectKeys(prefix) {
+        const pages = paginateListObjectsV2({ client: this.client }, { Bucket: this.bucket, Prefix: prefix });
+        for await (const page of pages) {
+            for (const object of page.Contents ?? []) {
+                if (object.Key)
+                    yield object.Key;
+            }
+        }
+    }
+    /** HEADs first: signing is local and succeeds for a missing key too. */
+    async presignPublicObjectRead(key) {
+        if (!(await this.hasPublicObject(key)))
+            return null;
+        return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), {
+            expiresIn: PRESIGNED_READ_EXPIRY_SECONDS,
+        });
+    }
     async putMetaIfAbsent(hash32, meta) {
         try {
             await this.client.send(new PutObjectCommand({

package/dist/assets/transform-directives.d.ts

@@ -4,17 +4,16 @@
  * NO imports (not even other files in this directory) so it can be imported
  * from client bundles (via `assetUrl`/`assetSrcSet` in asset-url.ts, exported
  * off the package's main entry) as well as from the server-only transform
- * engine (transform.ts) and the prod transform Lambda, without
+ * engine (transform.ts) and the lazy transform Lambda, without
  * ever pulling in node:crypto, sharp, or any other server-only dependency.
  *
  * `{directives}` is either the literal identity token (`orig`) or a
  * comma-separated list of `key=value` pairs drawn from:
- *   w={int}   output width - allowlisted to multiples of 160 in [160, 4096]
- *             (bounds cache-stuffing; upscaling is rejected at transform
- *             time via `withoutEnlargement`, not here)
+ *   w={int}   output width, accepted per `TransformWidthPolicy` (upscaling
+ *             is rejected at transform time via `withoutEnlargement`, not here)
  *   f={fmt}   output format: webp | jpeg | png - when present, the URL's
  *             `{ext}` must equal it exactly
- *   q={int}   quality 1..100 (encoder-dependent)
+ *   q={int}   quality, a multiple of 5 in [30, 95] under either policy
  *   c={rect}  normalized crop rect `x:y:w:h`, four floats in [0,1] with
  *             x+w<=1 and y+h<=1, w>0 and h>0 (colon-separated - commas are
  *             the directive separator)
@@ -56,6 +55,18 @@ export type ParseTransformPathResult = ({
     readonly ok: false;
     readonly error: string;
 };
+/**
+ * Which widths a transform path accepts. The policy only narrows what parses; a width that parses
+ * under both has the same canonical spelling under both.
+ *
+ * - `allowlist`: multiples of 160 in [160, 4096], plus the small rungs 32, 48, 64, 96 and 128. For
+ *   the opt-in anonymous on-demand path, where every accepted width is a new stored object an
+ *   anonymous caller can mint.
+ * - `any`: any integer in [1, 8192]. For every path where the URLs come from site code or a
+ *   signed-in editor: the authenticated route, `assetUrl`/`assetSrcSet`, the collector and the
+ *   materializer.
+ */
+export type TransformWidthPolicy = 'allowlist' | 'any';
 /**
  * Decompression-bomb cap: the max `width * height` (post-decode pixel count)
  * any raster the pipeline handles may have - checked both at upload finalize
@@ -63,10 +74,12 @@ export type ParseTransformPathResult = ({
  * time (transform.ts, via sharp's `limitInputPixels`). Shared here (rather
  * than duplicated in each server-only module) so it stays a single number,
  * and because this file is dependency-free/isomorphic it can be imported by
- * both without pulling sharp or file-type into anything. 4096x4096 (16.7 MP)
- * comfortably covers the largest output this system ever serves (MAX_WIDTH)
- * while still bounding decode-time memory for a small/compressible-but-huge
- * source (e.g. a 30000x30000 solid-color PNG).
+ * both without pulling sharp or file-type into anything. 24 MP (a 6000x4000
+ * camera frame) is sized by measured peak memory: the worst case, a full-size
+ * WebP encode of an RGBA WebP source, peaks at 1246 MiB here and grows about
+ * 37 MiB per MP, so this is the largest cap that fits the 2048 MB CMS and
+ * transform Lambdas with allocator headroom. For an animation the cap bounds
+ * all decoded frames together.
  */
 export declare const MAX_INPUT_PIXELS: number;
 /**
@@ -87,8 +100,8 @@ export declare const MAX_INPUT_PIXELS: number;
  * ignore) rather than by two constants that happen to match today.
  */
 export declare const MAX_ANIMATED_FRAMES = 60;
-/** True if `width` is on the allowlist: a multiple of 160 in [160, 4096]. */
-export declare function isAllowedTransformWidth(width: number): boolean;
+/** True if `policy` accepts `width`; see `TransformWidthPolicy`. */
+export declare function isAllowedTransformWidth(width: number, policy: TransformWidthPolicy): boolean;
 /**
  * True when x, y, w, h describe a valid normalized crop rect: all four values
  * finite and in [0,1], w and h strictly positive, and the rect fits within
@@ -98,16 +111,42 @@ export declare function isAllowedTransformWidth(width: number): boolean;
  * identical constraints.
  */
 export declare function isValidCropRect(x: number, y: number, w: number, h: number): boolean;
+/**
+ * Round a crop rect to `CROP_PRECISION` decimals, shrinking `w`/`h` to the
+ * space left when rounding pushes `x+w` or `y+h` past 1 (0.66665 + 0.33335
+ * rounds to 0.6667 + 0.3334). The result can still be degenerate (a `w` or `h`
+ * that rounds to 0), which `isValidCropRect` rejects.
+ */
+export declare function roundCropRect(rect: CropRect): CropRect;
 /**
  * Parse the three path segments after the `assets/t/` prefix:
  * `[directivesRaw, hash32, "{slug}.{ext}"]`. The raw route strips the
  * `assets/t/` prefix and splits the remaining key by `/` before calling this.
  */
-export declare function parseTransformPath(segments: readonly string[]): ParseTransformPathResult;
+export declare function parseTransformPath(segments: readonly string[], policy: TransformWidthPolicy): ParseTransformPathResult;
 /**
  * Canonical string form of a directive set, so equivalent directive sets
  * (different key order, different float formatting) always map to the same
- * cache key. Order is fixed alphabetically by key: c, f, q, w.
+ * cache key. Order is fixed alphabetically by key: c, f, q, w, and crop is
+ * rounded by `roundCropRect`.
  */
 export declare function formatDirectives(directives: TransformDirectives): string;
+export type CanonicalTransformPathResult = ({
+    readonly ok: true;
+    /** `{directives}/{hash32}/{slug}.{ext}` in canonical form, without the `assets/t/` prefix. */
+    readonly canonicalPath: string;
+    /** True when the requested segments already were `canonicalPath`, byte for byte. */
+    readonly isCanonical: boolean;
+} & ParsedTransformPath) | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Parse transform-path segments and resolve them to the one spelling their
+ * output is stored under. The returned `directives` are parsed back from that
+ * canonical spelling, never taken from the request, so a transform computed
+ * from them always matches its key. A crop that rounds to zero extent has no
+ * canonical spelling and is rejected.
+ */
+export declare function canonicalizeTransformPath(segments: readonly string[], policy: TransformWidthPolicy): CanonicalTransformPathResult;
 export {};