@glw907/cairn-cms 0.56.2 → 0.57.0

package/dist/media/naming.d.ts

@@ -0,0 +1,18 @@
+/** The full lowercase hex sha256 of the bytes, via Web Crypto, hand-formatted to 64 hex chars. */
+export declare function hashBytes(bytes: Uint8Array): Promise<string>;
+/** The first 16 characters of a full hex digest, the content-hash prefix media references commit to. */
+export declare function shortHash(full: string): string;
+/** The strict ingest transform from a raw filename to a slug that satisfies the media: slug grammar,
+ *  or the literal `file`. Drops the extension, lowercases, transliterates accents, collapses non-alphanumeric runs
+ *  to a single hyphen, trims, caps at 80 chars, screens Windows reserved names, and falls back to
+ *  `file` when nothing usable is left. */
+export declare function slugifyFilename(name: string): string;
+/** The content-addressed R2 object key `media/<aa>/<shortHash>.<ext>`, fanned out on the first two
+ *  hex chars of the short hash. No leading slash: this is an object key, not a URL. `ext` is bare
+ *  (no dot), for example `webp`. */
+export declare function r2Key(shortHash: string, ext: string): string;
+/** The public delivery URL path, with a leading slash, under the delivery base (`publicBase`,
+ *  default `/media`). The `slug` form is human-readable (`<base>/<slug>.<shortHash>.<ext>`, or
+ *  `<base>/<shortHash>.<ext>` when the slug is null); the `opaque` form mirrors the R2 fan-out
+ *  (`<base>/<aa>/<shortHash>.<ext>`) and ignores the slug. */
+export declare function publicPath(slug: string | null, shortHash: string, ext: string, urlForm: 'slug' | 'opaque', publicBase?: string): string;

package/dist/media/naming.js

@@ -0,0 +1,112 @@
+// cairn-cms: media naming. Media is content-addressed: the sha256 of the bytes names the object, so
+// the same bytes always land at the same key no matter the original filename. This module owns the
+// hash, the ingest slug transform, the R2 object key, and the public delivery path. The slug grammar
+// here matches the one parseMediaToken validates in ./reference.ts, so an ingested filename round
+// trips through the media: token unchanged.
+// slugifyFilename output always satisfies parseMediaToken's grammar (lowercase alphanumerics joined
+// by single internal hyphens, no leading or trailing hyphen), or is the literal `file`.
+/** Combining marks (Unicode block U+0300 to U+036F), left over after an NFD decompose, stripped to
+ *  fold an accented letter down to its ASCII base. Written as escapes because the literal marks are
+ *  invisible in source. */
+const COMBINING_MARKS = /[\u0300-\u036f]/g;
+/** Windows reserved device names. A bare match (case-insensitive) cannot survive as the slug, since
+ *  it names a device rather than a file on that platform. */
+const RESERVED = new Set([
+    'con',
+    'prn',
+    'aux',
+    'nul',
+    'com1',
+    'com2',
+    'com3',
+    'com4',
+    'com5',
+    'com6',
+    'com7',
+    'com8',
+    'com9',
+    'lpt1',
+    'lpt2',
+    'lpt3',
+    'lpt4',
+    'lpt5',
+    'lpt6',
+    'lpt7',
+    'lpt8',
+    'lpt9',
+]);
+/** The maximum slug length, applied before the reserved-name and empty fallbacks. */
+const MAX_SLUG = 80;
+/** A 16-character lowercase hex content-hash prefix, the bare-hash reference form. A slug that
+ *  matches this shape would collide with `media:<hash>`, so slugifyFilename screens it. */
+const HASH_RE = /^[0-9a-f]{16}$/;
+/** A short alphanumeric extension (no dot), the only shape r2Key accepts, for example `webp`. */
+const R2_EXT_RE = /^[a-z0-9]{1,5}$/;
+// A Uint8Array's generic buffer type no longer satisfies Web Crypto's BufferSource under strict lib
+// types, since the backing buffer may be a SharedArrayBuffer; slice the bytes into a plain
+// ArrayBuffer to hand digest. Mirrors the buf helper in ../github/signing.ts.
+function asArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+/** The full lowercase hex sha256 of the bytes, via Web Crypto, hand-formatted to 64 hex chars. */
+export async function hashBytes(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', asArrayBuffer(bytes));
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** The first 16 characters of a full hex digest, the content-hash prefix media references commit to. */
+export function shortHash(full) {
+    return full.slice(0, 16);
+}
+/** The strict ingest transform from a raw filename to a slug that satisfies the media: slug grammar,
+ *  or the literal `file`. Drops the extension, lowercases, transliterates accents, collapses non-alphanumeric runs
+ *  to a single hyphen, trims, caps at 80 chars, screens Windows reserved names, and falls back to
+ *  `file` when nothing usable is left. */
+export function slugifyFilename(name) {
+    const dot = name.lastIndexOf('.');
+    const stem = dot === -1 ? name : name.slice(0, dot);
+    let slug = stem
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(COMBINING_MARKS, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (slug.length > MAX_SLUG) {
+        slug = slug.slice(0, MAX_SLUG).replace(/-+$/, '');
+    }
+    if (RESERVED.has(slug))
+        return `${slug}-file`;
+    if (slug === '')
+        return 'file';
+    // A slug shaped like a bare 16-hex hash would collide with the `media:<hash>` reference form, so
+    // append -img (mirroring the reserved-name -file fallback) to keep the slug and bare-hash forms
+    // disjoint.
+    if (HASH_RE.test(slug))
+        return `${slug}-img`;
+    return slug;
+}
+/** The content-addressed R2 object key `media/<aa>/<shortHash>.<ext>`, fanned out on the first two
+ *  hex chars of the short hash. No leading slash: this is an object key, not a URL. `ext` is bare
+ *  (no dot), for example `webp`. */
+export function r2Key(shortHash, ext) {
+    if (!HASH_RE.test(shortHash)) {
+        throw new Error(`r2Key: hash must be 16 lowercase hex chars, got "${shortHash}"`);
+    }
+    if (!R2_EXT_RE.test(ext)) {
+        throw new Error(`r2Key: ext must be 1 to 5 lowercase alphanumerics, got "${ext}"`);
+    }
+    return `media/${shortHash.slice(0, 2)}/${shortHash}.${ext}`;
+}
+/** The public delivery URL path, with a leading slash, under the delivery base (`publicBase`,
+ *  default `/media`). The `slug` form is human-readable (`<base>/<slug>.<shortHash>.<ext>`, or
+ *  `<base>/<shortHash>.<ext>` when the slug is null); the `opaque` form mirrors the R2 fan-out
+ *  (`<base>/<aa>/<shortHash>.<ext>`) and ignores the slug. */
+export function publicPath(slug, shortHash, ext, urlForm, publicBase = '/media') {
+    if (urlForm === 'opaque') {
+        return `${publicBase}/${shortHash.slice(0, 2)}/${shortHash}.${ext}`;
+    }
+    return slug === null
+        ? `${publicBase}/${shortHash}.${ext}`
+        : `${publicBase}/${slug}.${shortHash}.${ext}`;
+}

package/dist/media/reconcile.d.ts

@@ -0,0 +1,36 @@
+import type { MediaManifest } from './manifest.js';
+/** What a reconcile read found in either direction. `orphanedObjects` are stored R2 keys whose hash
+ *  has no manifest row; `missingObjects` are manifest hashes with no stored object. */
+export interface ReconcileResult {
+    /** Stored keys (full R2 keys) whose content hash is absent from the manifest. */
+    orphanedObjects: string[];
+    /** Manifest content-hash keys with no matching stored object. */
+    missingObjects: string[];
+}
+/** The pure core: compare the stored R2 keys against the manifest's content-hash keys and report
+ *  both orphan directions. A stored key that does not match the media-key grammar is ignored, since
+ *  it is not a content-addressed media object this reconcile owns. */
+export declare function reconcileMedia(storedKeys: string[], manifest: MediaManifest): ReconcileResult;
+/** One page of an R2 list, the narrow subset the reconcile read consumes. */
+interface ReconcileListPage {
+    objects: {
+        key: string;
+    }[];
+    truncated: boolean;
+    cursor?: string;
+}
+/** The R2 bucket surface the reconcile read needs: a single prefixed, paginated list. A local
+ *  structural interface so no @cloudflare/workers-types name is imported (the module is internal and
+ *  on no public subpath, but the narrow seam keeps the build self-contained either way). */
+export interface ReconcileBucket {
+    list(opts?: {
+        prefix?: string;
+        cursor?: string;
+    }): Promise<ReconcileListPage>;
+}
+/** The glue runner: list every stored key under the media/ prefix (paginating through R2's
+ *  cursor/truncated), reconcile against the manifest, log the count summary, and return the result.
+ *  The log record carries counts only, never bytes or a key list; the keys are content hashes and so
+ *  carry no PII, but the count summary is all an operator needs to size the orphan state. */
+export declare function runReconcile(bucket: ReconcileBucket, manifest: MediaManifest): Promise<ReconcileResult>;
+export {};

package/dist/media/reconcile.js

@@ -0,0 +1,45 @@
+import { log } from '../log/index.js';
+/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. */
+const MEDIA_KEY_RE = /^media\/[0-9a-f]{2}\/([0-9a-f]{16})\.[a-z0-9]{1,5}$/;
+/** The pure core: compare the stored R2 keys against the manifest's content-hash keys and report
+ *  both orphan directions. A stored key that does not match the media-key grammar is ignored, since
+ *  it is not a content-addressed media object this reconcile owns. */
+export function reconcileMedia(storedKeys, manifest) {
+    const manifestHashes = new Set(Object.keys(manifest));
+    const storedHashes = new Set();
+    const orphanedObjects = [];
+    for (const key of storedKeys) {
+        const hash = MEDIA_KEY_RE.exec(key)?.[1];
+        if (hash === undefined)
+            continue;
+        storedHashes.add(hash);
+        if (!manifestHashes.has(hash))
+            orphanedObjects.push(key);
+    }
+    const missingObjects = [];
+    for (const hash of manifestHashes) {
+        if (!storedHashes.has(hash))
+            missingObjects.push(hash);
+    }
+    return { orphanedObjects, missingObjects };
+}
+/** The glue runner: list every stored key under the media/ prefix (paginating through R2's
+ *  cursor/truncated), reconcile against the manifest, log the count summary, and return the result.
+ *  The log record carries counts only, never bytes or a key list; the keys are content hashes and so
+ *  carry no PII, but the count summary is all an operator needs to size the orphan state. */
+export async function runReconcile(bucket, manifest) {
+    const storedKeys = [];
+    let cursor;
+    do {
+        const page = await bucket.list({ prefix: 'media/', cursor });
+        for (const object of page.objects)
+            storedKeys.push(object.key);
+        cursor = page.truncated ? page.cursor : undefined;
+    } while (cursor !== undefined);
+    const result = reconcileMedia(storedKeys, manifest);
+    log.info('media.orphan_reconcile', {
+        orphaned: result.orphanedObjects.length,
+        missing: result.missingObjects.length,
+    });
+    return result;
+}

package/dist/media/reference.d.ts

@@ -0,0 +1,12 @@
+/** A resolved reference to a media asset by its content-hash prefix, with an optional display slug. */
+export interface MediaRef {
+    slug: string | null;
+    hash: string;
+}
+/** Parse a `media:<slug>.<hash>` href (or the bare `media:<hash>` form), or null for any other
+ *  href or a malformed token. Splits on the last dot, so a slug that illegally contains a dot fails
+ *  the slug grammar and returns null. */
+export declare function parseMediaToken(href: string): MediaRef | null;
+/** Write the canonical media: token for a ref. The inverse of parseMediaToken, so a parse then
+ *  write round trip is stable: `media:<slug>.<hash>` when the slug is present, else `media:<hash>`. */
+export declare function mediaToken(ref: MediaRef): string;

package/dist/media/reference.js

@@ -0,0 +1,33 @@
+// cairn-cms: the media: reference token. A media reference is the logical handle that content
+// commits to git, keyed to a content-hash prefix so the same bytes resolve no matter where they
+// are stored or what they are named. The canonical form is `media:<slug>.<hash>`: the hash is a
+// 16-character lowercase hex content-hash prefix that identifies the bytes, and the slug is a
+// cosmetic display name. The bare `media:<hash>` form (no slug) is also valid. This module owns
+// the grammar; it mirrors the cairn: link codec in ../content/links.ts.
+/** A 16-character lowercase hex content-hash prefix. */
+const HASH_RE = /^[0-9a-f]{16}$/;
+/** The slug grammar from the Task 2 slugify transform: lowercase alphanumerics joined by single
+ *  internal hyphens, with no leading or trailing hyphen and no dot (the dot is the slug/hash
+ *  separator). */
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Parse a `media:<slug>.<hash>` href (or the bare `media:<hash>` form), or null for any other
+ *  href or a malformed token. Splits on the last dot, so a slug that illegally contains a dot fails
+ *  the slug grammar and returns null. */
+export function parseMediaToken(href) {
+    if (!href.startsWith('media:'))
+        return null;
+    const rest = href.slice('media:'.length);
+    const dot = rest.lastIndexOf('.');
+    if (dot === -1)
+        return HASH_RE.test(rest) ? { slug: null, hash: rest } : null;
+    const slug = rest.slice(0, dot);
+    const hash = rest.slice(dot + 1);
+    if (!HASH_RE.test(hash) || !SLUG_RE.test(slug))
+        return null;
+    return { slug, hash };
+}
+/** Write the canonical media: token for a ref. The inverse of parseMediaToken, so a parse then
+ *  write round trip is stable: `media:<slug>.<hash>` when the slug is present, else `media:<hash>`. */
+export function mediaToken(ref) {
+    return ref.slug === null ? `media:${ref.hash}` : `media:${ref.slug}.${ref.hash}`;
+}

package/dist/media/sniff.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Detect the MIME type of an image from its leading magic bytes. Reads only the first ~32 bytes and
+ * returns the recognized type, or null for an unrecognized magic or an input too short for a given
+ * check. This is the server's source of truth for an upload's type; the client-declared type is
+ * advisory. Recognizes JPEG, PNG, GIF, WebP, and the AVIF/HEIC ISO-BMFF brands.
+ */
+export declare function sniffMediaType(bytes: Uint8Array): string | null;
+/** The storage extension for a sniffed media type, or null for a type the upload path does not store
+ *  (HEIC, an unknown type). Driven by the sniffed type, so the key's ext is server-owned. */
+export declare function extForMediaType(type: string): string | null;
+/**
+ * The engine-level upload deny predicate. Returns true (reject) when the upload is markup a site can
+ * never override: a declared type of image/svg+xml, image/svg, text/html, or application/xml, OR a
+ * payload whose first non-whitespace byte is `<` (an 0x3C after skipping leading ASCII whitespace).
+ * This runs ahead of and independent of any site `allowedTypes`, since SVG and HTML carry active
+ * content. The byte check catches a markup payload sent under a permitted declared type.
+ */
+export declare function isDeniedUpload(bytes: Uint8Array, declaredType?: string): boolean;

package/dist/media/sniff.js

@@ -0,0 +1,106 @@
+// cairn-cms: content-type sniffing and the engine-level upload deny-list. The upload action trusts no
+// client-declared type: it sniffs the real type from the leading bytes and screens the payload against a
+// deny-list a site cannot override. Both functions are pure and Worker-clean (a plain Uint8Array, no
+// Node Buffer and no stream), so they run unchanged on Cloudflare Workers and under vitest.
+//
+// The sniff is necessary but not sufficient. A polyglot can carry a valid image magic and an HTML tail,
+// and this byte check sees only the magic. The delivery route's response headers (X-Content-Type-Options:
+// nosniff, Content-Disposition: inline, a restrictive Content-Security-Policy) are the real XSS control
+// for the served bytes; sniffing here is the ingest gate, not the served-bytes defense.
+/** The leading ASCII whitespace bytes skipped before the deny-list's first-byte-is-`<` check:
+ *  tab (0x09), newline (0x0A), carriage return (0x0D), and space (0x20). */
+const WHITESPACE = new Set([0x09, 0x0a, 0x0d, 0x20]);
+/** The single byte `<` (0x3C). A payload whose first non-whitespace byte is `<` is markup (SVG, HTML,
+ *  XML) and is denied regardless of its declared type or any site `allowedTypes`. */
+const LT = 0x3c;
+/** Declared content types denied at the engine level, independent of any site `allowedTypes`. SVG and
+ *  the markup types carry active content (script, foreignObject), so they never ingest as media. */
+const DENIED_TYPES = new Set(['image/svg+xml', 'image/svg', 'text/html', 'application/xml']);
+/** The ISO-BMFF major-brand codes (at bytes 8..11 of an `ftyp` box) that mean an AVIF image. */
+const AVIF_BRANDS = new Set(['avif', 'avis']);
+/** The ISO-BMFF major-brand codes that mean a HEIF/HEIC image. */
+const HEIC_BRANDS = new Set(['heic', 'heix', 'heif', 'hevc', 'hevx', 'mif1', 'msf1']);
+/** True when every byte of `magic` matches `bytes` starting at `offset`. False if `bytes` is too
+ *  short to hold the whole magic. */
+function matches(bytes, offset, magic) {
+    if (bytes.length < offset + magic.length)
+        return false;
+    for (let i = 0; i < magic.length; i++) {
+        if (bytes[offset + i] !== magic[i])
+            return false;
+    }
+    return true;
+}
+/** The four ASCII characters at bytes `offset..offset+3`, or null when the input is too short. Used to
+ *  read an ISO-BMFF brand code as a string. */
+function ascii4(bytes, offset) {
+    if (bytes.length < offset + 4)
+        return null;
+    return String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+}
+/**
+ * Detect the MIME type of an image from its leading magic bytes. Reads only the first ~32 bytes and
+ * returns the recognized type, or null for an unrecognized magic or an input too short for a given
+ * check. This is the server's source of truth for an upload's type; the client-declared type is
+ * advisory. Recognizes JPEG, PNG, GIF, WebP, and the AVIF/HEIC ISO-BMFF brands.
+ */
+export function sniffMediaType(bytes) {
+    // JPEG: starts FF D8 FF.
+    if (matches(bytes, 0, [0xff, 0xd8, 0xff]))
+        return 'image/jpeg';
+    // PNG: the 8-byte signature 89 50 4E 47 0D 0A 1A 0A; the leading 89 50 4E 47 ('.PNG') is enough.
+    if (matches(bytes, 0, [0x89, 0x50, 0x4e, 0x47]))
+        return 'image/png';
+    // GIF: 'GIF8' (the 87a and 89a versions share this prefix).
+    if (matches(bytes, 0, [0x47, 0x49, 0x46, 0x38]))
+        return 'image/gif';
+    // WebP: a RIFF container ('RIFF' at 0..3) whose form type is 'WEBP' at 8..11.
+    if (matches(bytes, 0, [0x52, 0x49, 0x46, 0x46]) && matches(bytes, 8, [0x57, 0x45, 0x42, 0x50])) {
+        return 'image/webp';
+    }
+    // AVIF and HEIC are ISO base media format files: an 'ftyp' box tag at bytes 4..7, then the 4-byte
+    // major brand at bytes 8..11. A truncated box (no brand bytes) or an unknown brand returns null.
+    if (matches(bytes, 4, [0x66, 0x74, 0x79, 0x70])) {
+        const brand = ascii4(bytes, 8);
+        if (brand !== null) {
+            if (AVIF_BRANDS.has(brand))
+                return 'image/avif';
+            if (HEIC_BRANDS.has(brand))
+                return 'image/heic';
+        }
+    }
+    return null;
+}
+/** The bare file extension (no dot) for each sniffed media type the upload path stores. The ext is
+ *  derived from the server-sniffed type, never the client filename, so the stored key and the
+ *  delivery extension allow-list always agree. An unmappable type returns null (the upload 415s). */
+const EXT_BY_TYPE = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/avif': 'avif',
+};
+/** The storage extension for a sniffed media type, or null for a type the upload path does not store
+ *  (HEIC, an unknown type). Driven by the sniffed type, so the key's ext is server-owned. */
+export function extForMediaType(type) {
+    return EXT_BY_TYPE[type] ?? null;
+}
+/**
+ * The engine-level upload deny predicate. Returns true (reject) when the upload is markup a site can
+ * never override: a declared type of image/svg+xml, image/svg, text/html, or application/xml, OR a
+ * payload whose first non-whitespace byte is `<` (an 0x3C after skipping leading ASCII whitespace).
+ * This runs ahead of and independent of any site `allowedTypes`, since SVG and HTML carry active
+ * content. The byte check catches a markup payload sent under a permitted declared type.
+ */
+export function isDeniedUpload(bytes, declaredType) {
+    if (declaredType !== undefined && DENIED_TYPES.has(declaredType.toLowerCase()))
+        return true;
+    for (let i = 0; i < bytes.length; i++) {
+        if (WHITESPACE.has(bytes[i]))
+            continue;
+        return bytes[i] === LT;
+    }
+    // An empty or all-whitespace payload has no opening byte to deny here; the type and size gates own it.
+    return false;
+}

package/dist/media/store.d.ts

@@ -0,0 +1,25 @@
+import type { R2Bucket, R2Conditional, R2HTTPMetadata, R2Object, R2ObjectBody, R2Range } from '@cloudflare/workers-types';
+/** The narrow R2 surface the media pipeline uses. The engine depends on this, not on R2Bucket, so the
+ *  multipart, list, and conditional-read surface R2 also carries never leaks into the media code. */
+export interface MediaStore {
+    /** Store bytes under a content-addressed key, with the response HTTP metadata (the content type)
+     *  and optional custom metadata (the upload stores the full sha256 here, so a short-hash collision
+     *  is detectable on a later dedup probe). */
+    put(key: string, bytes: ArrayBuffer | Uint8Array, httpMetadata?: R2HTTPMetadata, customMetadata?: Record<string, string>): Promise<void>;
+    /** The object's metadata, or null when no object lives at the key (the dedup probe). */
+    head(key: string): Promise<R2Object | null>;
+    /** The object body for streaming to a delivery response, or null when the key is absent. The
+     *  delivery route passes `onlyIf` and `range` through for conditional and partial reads: an
+     *  `onlyIf` etag match returns a body-less R2Object (the 304 shape), so the return widens to
+     *  `R2Object` alongside `R2ObjectBody`. */
+    get(key: string, opts?: {
+        range?: R2Range;
+        onlyIf?: R2Conditional;
+    }): Promise<R2ObjectBody | R2Object | null>;
+    /** Remove the object at the key. A delete of an absent key is a no-op, the R2 contract. */
+    delete(key: string): Promise<void>;
+}
+/** Wrap an R2 bucket binding as a MediaStore. Each method delegates to the binding; put folds the
+ *  HTTP and custom metadata into R2's options shape and drops the returned R2Object the pipeline does
+ *  not read. */
+export declare function r2Store(bucket: R2Bucket): MediaStore;

package/dist/media/store.js

@@ -0,0 +1,16 @@
+/** Wrap an R2 bucket binding as a MediaStore. Each method delegates to the binding; put folds the
+ *  HTTP and custom metadata into R2's options shape and drops the returned R2Object the pipeline does
+ *  not read. */
+export function r2Store(bucket) {
+    return {
+        async put(key, bytes, httpMetadata, customMetadata) {
+            const options = httpMetadata || customMetadata
+                ? { ...(httpMetadata ? { httpMetadata } : {}), ...(customMetadata ? { customMetadata } : {}) }
+                : undefined;
+            await bucket.put(key, bytes, options);
+        },
+        head: (key) => bucket.head(key),
+        get: (key, opts) => bucket.get(key, opts),
+        delete: (key) => bucket.delete(key),
+    };
+}

package/dist/media/transform-url.d.ts

@@ -0,0 +1,26 @@
+/** A single image variant: the resize and format directives Cloudflare Images applies to the
+ *  original bytes. Every field is optional. width, height, quality, and fit are emitted only when
+ *  set; format and gravity always appear, defaulting to auto. */
+export interface VariantSpec {
+    /** Target width in pixels. */
+    width?: number;
+    /** Target height in pixels. */
+    height?: number;
+    /** Output quality, 1 to 100. */
+    quality?: number;
+    /** How the image fits the target box. */
+    fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+    /** Crop focus, `auto` or `face` or a coordinate string. */
+    gravity?: 'auto' | 'face' | string;
+    /** Output format, `auto` to let Cloudflare negotiate, or a forced codec. */
+    format?: 'auto' | 'webp' | 'avif' | string;
+}
+/** Build the on-demand Cloudflare Images transform URL for a delivery path. The options are
+ *  comma-joined in the stable order width, height, quality, fit, format, gravity, with width through
+ *  fit emitted only when the spec sets them and format and gravity always present (defaulting to
+ *  auto). The publicPath is appended unaltered, so the result is `/cdn-cgi/image/<options><publicPath>`. */
+export declare function variantUrl(publicPath: string, spec: VariantSpec): string;
+/** Build a variant URL from a named preset. Looks up presetName in variants and builds its spec with
+ *  variantUrl. Throws a cairn:-prefixed error naming the unknown preset when the name is absent, so a
+ *  typo in a preset name fails loudly rather than silently rendering an unsized image. */
+export declare function presetUrl(publicPath: string, presetName: string, variants: Record<string, VariantSpec>): string;

package/dist/media/transform-url.js

@@ -0,0 +1,38 @@
+// cairn-cms: the Cloudflare Images transform URL. A delivery path names the original bytes; an
+// on-demand variant is that path prefixed with `/cdn-cgi/image/<options>/`, where the options are a
+// comma-joined list of resize and format directives Cloudflare reads at the edge. This module owns
+// the option encoding and the stable option order, so the same spec always builds the same URL and
+// a CDN cache keys on it cleanly. The delivery path is appended unaltered, since it already carries
+// its own leading slash.
+/** Build the on-demand Cloudflare Images transform URL for a delivery path. The options are
+ *  comma-joined in the stable order width, height, quality, fit, format, gravity, with width through
+ *  fit emitted only when the spec sets them and format and gravity always present (defaulting to
+ *  auto). The publicPath is appended unaltered, so the result is `/cdn-cgi/image/<options><publicPath>`. */
+export function variantUrl(publicPath, spec) {
+    const options = [];
+    if (spec.width !== undefined)
+        options.push(`width=${spec.width}`);
+    if (spec.height !== undefined)
+        options.push(`height=${spec.height}`);
+    if (spec.quality !== undefined)
+        options.push(`quality=${spec.quality}`);
+    if (spec.fit !== undefined)
+        options.push(`fit=${spec.fit}`);
+    options.push(`format=${spec.format ?? 'auto'}`);
+    options.push(`gravity=${spec.gravity ?? 'auto'}`);
+    // The source must be its own path segment after the options, so it needs a leading slash;
+    // Cloudflare reads a slashless join as a malformed options list. publicPath carries one, but this
+    // guards a caller that passes a relative path from fusing the options and the source.
+    const source = publicPath.startsWith('/') ? publicPath : `/${publicPath}`;
+    return `/cdn-cgi/image/${options.join(',')}${source}`;
+}
+/** Build a variant URL from a named preset. Looks up presetName in variants and builds its spec with
+ *  variantUrl. Throws a cairn:-prefixed error naming the unknown preset when the name is absent, so a
+ *  typo in a preset name fails loudly rather than silently rendering an unsized image. */
+export function presetUrl(publicPath, presetName, variants) {
+    const spec = variants[presetName];
+    if (spec === undefined) {
+        throw new Error(`cairn: unknown image variant preset "${presetName}"`);
+    }
+    return variantUrl(publicPath, spec);
+}

package/dist/media/usage.d.ts

@@ -0,0 +1,48 @@
+import type { ConceptDescriptor } from '../content/types.js';
+import type { RepoRef } from '../github/types.js';
+import type { Manifest } from '../content/manifest.js';
+/** Where a reference lives: the published corpus on main, or a named open edit branch. */
+export type UsageOrigin = {
+    kind: 'published';
+} | {
+    kind: 'branch';
+    branch: string;
+};
+/** One entry that references an asset, in a shape the screen links and groups by. */
+export interface UsageEntry {
+    /** The concept id, e.g. "posts". */
+    concept: string;
+    /** The entry id (its filename stem). */
+    id: string;
+    /** The entry title for display, from the manifest (published) or frontmatter (branch). */
+    title: string;
+    /** The public permalink, present for a published entry (carried from the manifest). */
+    permalink?: string;
+    /** Published vs the cairn/* branch the edit lives on. */
+    origin: UsageOrigin;
+}
+/** Content hash to the distinct entries that reference it. A hash with no row is "no references
+ *  found" (see the raw-HTML caveat above), never a proven orphan. */
+export type UsageIndex = Map<string, UsageEntry[]>;
+/** Build options. `branches` lets a caller that already listed the open cairn/* branches pass them
+ *  in so the index does not list them a second time (the load path lists once for the media-union).
+ *  `strict` flips the per-branch read from degrade-and-skip to fail-closed: a delete gate must not
+ *  treat a transient branch-read failure as an absent reference, so it rethrows instead. */
+export interface BuildUsageOptions {
+    /** The open cairn/* branch names, already listed. When present the index skips its own listing. */
+    branches?: string[];
+    /** When true a branch read that throws rejects the whole build, so the caller can fail closed. */
+    strict?: boolean;
+}
+/**
+ * Build the hash-keyed usage index over main (from the manifest's per-entry mediaRefs) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read, rather than sinking the whole screen. That tolerance is right
+ * for the Library DISPLAY, but wrong for the delete gate: a transient branch-read failure would make
+ * a still-referenced asset look orphaned. Pass `strict: true` (the delete path) to rethrow a branch
+ * failure so the caller fails closed. Pass `branches` to reuse a branch list the caller already has
+ * (the load path lists once for the media-union) rather than listing them a second time.
+ */
+export declare function buildUsageIndex(repo: RepoRef, token: string, concepts: ConceptDescriptor[], manifest: Manifest, opts?: BuildUsageOptions): Promise<UsageIndex>;

package/dist/media/usage.js

@@ -0,0 +1,90 @@
+import { listBranches } from '../github/branches.js';
+import { readRaw } from '../github/repo.js';
+import { PENDING_PREFIX, parsePendingBranch } from '../content/pending.js';
+import { findConcept } from '../content/concepts.js';
+import { isValidId, filenameFromId } from '../content/ids.js';
+import { parseMarkdown } from '../content/frontmatter.js';
+import { extractMediaRefs } from '../content/media-refs.js';
+/** Append a row under its hash, creating the bucket on first use. */
+function push(index, hash, entry) {
+    const rows = index.get(hash);
+    if (rows)
+        rows.push(entry);
+    else
+        index.set(hash, [entry]);
+}
+/**
+ * Build the hash-keyed usage index over main (from the manifest's per-entry mediaRefs) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read, rather than sinking the whole screen. That tolerance is right
+ * for the Library DISPLAY, but wrong for the delete gate: a transient branch-read failure would make
+ * a still-referenced asset look orphaned. Pass `strict: true` (the delete path) to rethrow a branch
+ * failure so the caller fails closed. Pass `branches` to reuse a branch list the caller already has
+ * (the load path lists once for the media-union) rather than listing them a second time.
+ */
+export async function buildUsageIndex(repo, token, concepts, manifest, opts = {}) {
+    const index = new Map();
+    // The main arm: the manifest already carries each entry's mediaRefs, so this is a pure reverse
+    // map with no per-file read.
+    for (const entry of manifest.entries) {
+        for (const hash of entry.mediaRefs ?? []) {
+            push(index, hash, {
+                concept: entry.concept,
+                id: entry.id,
+                title: entry.title,
+                permalink: entry.permalink,
+                origin: { kind: 'published' },
+            });
+        }
+    }
+    // The branch arm: read each open cairn/* branch's one edited file. The path is derivable from the
+    // branch name, so no tree-listing is needed. The branch list is reused when the caller passes it.
+    const names = opts.branches ?? (await listBranches(repo, PENDING_PREFIX, token));
+    // Read the branches in parallel rather than one at a time, so the latency floor is one round trip
+    // instead of N. workerd self-throttles to 6 simultaneous outbound connections, so this batch and
+    // the load path's media-union batch each stay under the limit; do NOT merge the two into one
+    // wider Promise.all, since the combined fan-out would queue behind that throttle.
+    const perBranch = await Promise.all(names.map(async (name) => {
+        // Resolve the branch name to a configured entry with the same guard the branch tooling uses: a
+        // malformed name, an id that fails the slug rule (entry paths are built from it, so this is the
+        // path confinement), or a concept this site does not configure is skipped, no read attempted.
+        const ref = parsePendingBranch(name);
+        if (!ref || !isValidId(ref.id))
+            return [];
+        const concept = findConcept(concepts, ref.concept);
+        if (!concept)
+            return [];
+        const path = `${concept.dir}/${filenameFromId(ref.id)}`;
+        try {
+            const raw = await readRaw({ ...repo, branch: name }, path, token);
+            if (raw === null)
+                return []; // The file is absent on the branch: nothing to extract.
+            const { frontmatter, body } = parseMarkdown(raw);
+            const fmTitle = frontmatter.title;
+            const title = typeof fmTitle === 'string' && fmTitle.trim() ? fmTitle : ref.id;
+            const rows = [];
+            for (const hash of extractMediaRefs(frontmatter, body, concept.fields)) {
+                rows.push({
+                    hash,
+                    entry: { concept: concept.id, id: ref.id, title, origin: { kind: 'branch', branch: name } },
+                });
+            }
+            return rows;
+        }
+        catch (err) {
+            // In strict mode a branch failure fails the whole build so the delete gate can fail closed;
+            // otherwise degrade this one branch rather than sinking the screen.
+            if (opts.strict)
+                throw err;
+            return [];
+        }
+    }));
+    // Fold the per-branch rows back in, preserving the branch order so the index reads stably.
+    for (const rows of perBranch) {
+        for (const { hash, entry } of rows)
+            push(index, hash, entry);
+    }
+    return index;
+}