@glw907/cairn-cms 0.56.1 → 0.57.0

package/dist/media/config.js

@@ -0,0 +1,69 @@
+/** The default delivery base path when the AssetConfig omits one. */
+const DEFAULT_PUBLIC_BASE = '/media';
+/** The default maximum upload size, 25 MB. */
+const DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+/** The default accepted upload MIME types: the common web image formats. */
+const DEFAULT_ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'image/gif', 'image/avif'];
+/** The built-in named transform presets. A site's `variants` merge over these, so a caller preset of
+ *  the same name overrides the built-in. */
+const BUILT_IN_PRESETS = {
+    thumb: { width: 320, height: 320, fit: 'cover' },
+    inline: { width: 800 },
+    card: { width: 640, height: 400, fit: 'cover' },
+    hero: { width: 1600, height: 900, fit: 'cover' },
+};
+/** The fit values Cloudflare Images accepts. A variant whose fit is set to anything else is rejected. */
+const FIT_VALUES = new Set(['scale-down', 'contain', 'cover', 'crop', 'pad']);
+/** The named gravity keywords Cloudflare Images accepts. A gravity is also valid as a coordinate
+ *  string; everything else is rejected. */
+const GRAVITY_KEYWORDS = new Set([
+    'auto',
+    'face',
+    'left',
+    'right',
+    'top',
+    'bottom',
+    'center',
+]);
+/** A gravity coordinate string, e.g. "0.5x0.5". */
+const GRAVITY_COORD_RE = /^\d+(\.\d+)?x\d+(\.\d+)?$/;
+/** Validate one variant's fit and gravity, throwing a cairn:-prefixed error naming the offending
+ *  preset and value. The type system collapses VariantSpec.gravity to string, so the gravity check
+ *  is the only guard against a bogus value reaching the transform URL. */
+function validateVariant(name, spec) {
+    if (spec.fit !== undefined && !FIT_VALUES.has(spec.fit)) {
+        throw new Error(`cairn: media variant "${name}" has an unknown fit "${spec.fit}"`);
+    }
+    if (spec.gravity !== undefined &&
+        !GRAVITY_KEYWORDS.has(spec.gravity) &&
+        !GRAVITY_COORD_RE.test(spec.gravity)) {
+        throw new Error(`cairn: media variant "${name}" has an unknown gravity "${spec.gravity}"`);
+    }
+}
+/** Validate a site's AssetConfig and resolve it into a ResolvedAssetConfig. An undefined block leaves
+ *  media off and returns `{ enabled: false }` rather than throwing. A declared block must name its R2
+ *  bucket and carry a known urlForm and valid variant fit and gravity values; each failure throws a
+ *  cairn:-prefixed error. The named variants merge over the built-in presets. */
+export function normalizeAssets(assets) {
+    if (assets === undefined)
+        return { enabled: false };
+    if (!assets.bucketBinding) {
+        throw new Error('cairn: a media assets block must name its R2 bucket binding');
+    }
+    if (assets.urlForm !== undefined && assets.urlForm !== 'slug' && assets.urlForm !== 'opaque') {
+        throw new Error(`cairn: media urlForm must be "slug" or "opaque", got "${assets.urlForm}"`);
+    }
+    for (const [name, spec] of Object.entries(assets.variants ?? {})) {
+        validateVariant(name, spec);
+    }
+    return {
+        enabled: true,
+        bucketBinding: assets.bucketBinding,
+        publicBase: assets.publicBase ?? DEFAULT_PUBLIC_BASE,
+        urlForm: assets.urlForm ?? 'slug',
+        maxUploadBytes: assets.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES,
+        allowedTypes: assets.allowedTypes ?? DEFAULT_ALLOWED_TYPES,
+        variants: { ...BUILT_IN_PRESETS, ...(assets.variants ?? {}) },
+        transformations: assets.transformations ?? false,
+    };
+}

package/dist/media/delivery-bucket.d.ts

@@ -0,0 +1,34 @@
+/** A stored object without its body: the shape an `If-None-Match` hit or a metadata read returns. */
+export interface DeliveryObject {
+    /** Writes the stored HTTP metadata (Content-Type, Cache-Control, and so on) onto `headers`. */
+    writeHttpMetadata(headers: Headers): void;
+    /** The strong validator R2 stored for the bytes, set as the response `ETag`. */
+    httpEtag: string;
+    /** The full object size in bytes, the denominator of a `Content-Range`. */
+    size: number;
+    /** Present only on a ranged read: the served window, used to build the `Content-Range`. R2 fills
+     *  both fields for a `bytes=start-end` request; each is typed optional so the route derives the
+     *  range bounds defensively against `size`. */
+    range?: {
+        offset?: number;
+        length?: number;
+    };
+}
+/** A stored object with its readable body, the shape a full or ranged read returns. */
+export interface DeliveryObjectBody extends DeliveryObject {
+    body: ReadableStream;
+}
+/** The bucket surface the delivery route reads: a single conditional, optionally ranged, get. */
+export interface DeliveryBucket {
+    get(key: string, opts?: {
+        /** R2 reads `If-None-Match`/`If-Match` from a passed `Headers`; the route forwards the request's. */
+        onlyIf?: {
+            etagDoesNotMatch?: string;
+        } | Headers;
+        /** The byte window to serve; the route parses it from the request `Range` header. */
+        range?: {
+            offset?: number;
+            length?: number;
+        } | Headers;
+    }): Promise<DeliveryObjectBody | DeliveryObject | null>;
+}

package/dist/media/delivery-bucket.js

@@ -0,0 +1,10 @@
+// A narrow structural seam over the R2 bucket, modelling only what the delivery route reads.
+//
+// The route needs conditional and ranged gets, which the narrow MediaStore seam cannot express, so
+// it talks to the raw bucket. It must not name any `@cloudflare/workers-types` type (`R2Bucket`,
+// `R2Object`, `R2ObjectBody`, `R2HTTPMetadata`): that package is a devDependency the engine builds
+// against but a consumer does not have, so any such name in a public `.d.ts` would break a consumer
+// build that lacks `skipLibCheck`. `Headers`, `ReadableStream`, and `Response` are web globals, not
+// workers-types, so they are safe on the public surface. `requireBucket` casts the real R2 binding
+// to `DeliveryBucket` through `unknown`; the shapes below are a structural subset of the real R2 API.
+export {};

package/dist/media/index.d.ts

@@ -0,0 +1,6 @@
+export { normalizeAssets, type ResolvedAssetConfig } from './config.js';
+export { parseMediaManifest, findByHash, upsertMediaEntry, removeMediaEntry, serializeMediaManifest, parseMediaEntries, type MediaEntry, type MediaManifest, } from './manifest.js';
+export { hashBytes, shortHash, slugifyFilename, r2Key, publicPath } from './naming.js';
+export { presetUrl, variantUrl, type VariantSpec } from './transform-url.js';
+export { parseMediaToken, mediaToken, type MediaRef } from './reference.js';
+export { makeMediaResolver, manifestMediaResolver, type MediaResolve } from '../render/resolve-media.js';

package/dist/media/index.js

@@ -0,0 +1,13 @@
+// cairn-cms: the node-safe `/media` public barrel. It re-exports only the pure media surface a site
+// reaches outside the SvelteKit runtime: the config normalizer, the manifest functions, the naming
+// and transform-URL helpers, the reference codec, and the render resolver. Nothing here pulls
+// `@sveltejs/kit` or `@cloudflare/workers-types` into the module graph, so a plain-Node tool or a
+// build step can import it. The R2-touching pieces (`store.ts`, `delivery-bucket.ts`) and the
+// delivery-route factory and `requireBucket` stay on `/sveltekit`, off this surface, so the public
+// `.d.ts` for `/media` names no kit or workers-types type.
+export { normalizeAssets } from './config.js';
+export { parseMediaManifest, findByHash, upsertMediaEntry, removeMediaEntry, serializeMediaManifest, parseMediaEntries, } from './manifest.js';
+export { hashBytes, shortHash, slugifyFilename, r2Key, publicPath } from './naming.js';
+export { presetUrl, variantUrl } from './transform-url.js';
+export { parseMediaToken, mediaToken } from './reference.js';
+export { makeMediaResolver, manifestMediaResolver } from '../render/resolve-media.js';

package/dist/media/library-entry.d.ts

@@ -0,0 +1,30 @@
+import type { MediaEntry } from './manifest.js';
+/** One stored asset in the picker's projected library, keyed elsewhere by the 16-hex content hash. */
+export interface MediaLibraryEntry {
+    /** The 16-hex content-hash prefix that names the bytes. */
+    hash: string;
+    /** The cosmetic display slug in the media: token and the delivery path. */
+    slug: string;
+    /** The bare file extension (no dot), for example `webp`. */
+    ext: string;
+    /** The stored MIME type, for example `image/webp`; its top-level part drives the type facet. */
+    contentType: string;
+    /** The editable human name shown on the row. */
+    displayName: string;
+    /** The manifest alt, prefilled into a new placement; empty is the needs-alt signal. */
+    alt: string;
+    /** The pixel width, or null when the manifest carries none. */
+    width: number | null;
+    /** The pixel height, or null when the manifest carries none. */
+    height: number | null;
+    /** The stored byte size. */
+    bytes: number;
+    /** The ISO timestamp the bytes were first stored, the Library's sortable "Added" column. */
+    createdAt: string;
+}
+/** The projected library keyed by the 16-hex content hash, exactly EditData's `mediaLibrary`. */
+export type MediaLibrary = Record<string, MediaLibraryEntry>;
+/** Project a stored MediaEntry to the picker's MediaLibraryEntry, copying every display field and
+ *  dropping the source-only sha256 and original filename. The single projection editLoad and
+ *  mediaLibraryLoad both call, so the popover and the Library never diverge on the shared shape. */
+export declare function mediaLibraryEntry(entry: MediaEntry): MediaLibraryEntry;

package/dist/media/library-entry.js

@@ -0,0 +1,17 @@
+/** Project a stored MediaEntry to the picker's MediaLibraryEntry, copying every display field and
+ *  dropping the source-only sha256 and original filename. The single projection editLoad and
+ *  mediaLibraryLoad both call, so the popover and the Library never diverge on the shared shape. */
+export function mediaLibraryEntry(entry) {
+    return {
+        hash: entry.hash,
+        slug: entry.slug,
+        ext: entry.ext,
+        contentType: entry.contentType,
+        displayName: entry.displayName,
+        alt: entry.alt,
+        width: entry.width,
+        height: entry.height,
+        bytes: entry.bytes,
+        createdAt: entry.createdAt,
+    };
+}

package/dist/media/manifest.d.ts

@@ -0,0 +1,44 @@
+/** One stored asset's row: its content hash, its human layer, and its byte and pixel facts. The
+ *  `contentType` is the stored MIME type, so the delivery route serves it verbatim rather than
+ *  guessing from the extension. `width` and `height` are null when no dimensions are known (the
+ *  client is the only dimension source and a Worker cannot re-derive them). */
+export interface MediaEntry {
+    hash: string;
+    sha256: string;
+    slug: string;
+    displayName: string;
+    originalFilename: string;
+    alt: string;
+    ext: string;
+    contentType: string;
+    bytes: number;
+    width: number | null;
+    height: number | null;
+    createdAt: string;
+}
+/** The whole stored-asset record, keyed by the 16-hex content-hash prefix. */
+export type MediaManifest = Record<string, MediaEntry>;
+/** Parse a committed media manifest. Tolerant: an empty, missing, null, or non-object input yields
+ *  an empty manifest, so a first ingest into a site with no manifest file reads a clean {}. A valid
+ *  object is returned as the manifest. */
+export declare function parseMediaManifest(json: unknown): MediaManifest;
+/** Parse the posted `media` field into a validated list of MediaEntry rows. The field arrives as a
+ *  JSON string (the usual form-post shape), an already-parsed array, or junk. A string is JSON-parsed
+ *  inside a try/catch that yields `[]` on a parse failure; a non-string array is taken directly;
+ *  anything else yields `[]`. Each element is validated and a failing element is dropped, so a partly
+ *  malformed post still lands its good rows. This is the trust boundary for the client's optimistic
+ *  records. */
+export declare function parseMediaEntries(value: unknown): MediaEntry[];
+/** The dedup lookup: the entry stored under the content-hash prefix, or undefined when no bytes with
+ *  that hash are stored yet. */
+export declare function findByHash(manifest: MediaManifest, hash: string): MediaEntry | undefined;
+/** Set the entry under its own hash, replacing any same-hash row. Returns a new manifest and leaves
+ *  the input untouched, so a caller's prior manifest reference stays valid. The ingest path's patch. */
+export declare function upsertMediaEntry(manifest: MediaManifest, entry: MediaEntry): MediaManifest;
+/** Drop the entry under the given hash, returning a new manifest and leaving the input untouched.
+ *  Removing an absent hash is a no-op that still returns an equivalent new manifest. The safe-delete
+ *  path's patch. */
+export declare function removeMediaEntry(manifest: MediaManifest, hash: string): MediaManifest;
+/** Serialize canonically: the top-level hash keys sorted ascending, two-space pretty, and a trailing
+ *  newline, so the committed file diffs cleanly in a PR and a re-serialization is byte-identical. */
+export declare function serializeMediaManifest(manifest: MediaManifest): string;

package/dist/media/manifest.js

@@ -0,0 +1,105 @@
+// cairn-cms: the media manifest, a small git-committed record with one row per stored asset. It
+// carries the human layer that the bytes cannot (display name, alt text, original filename) and is
+// the dedup lookup: an ingest checks the content-hash prefix here before storing, so the same bytes
+// are never stored twice. It mirrors the content manifest in ../content/manifest.ts, keyed by the
+// 16-hex content-hash prefix rather than concept and id.
+/** Parse a committed media manifest. Tolerant: an empty, missing, null, or non-object input yields
+ *  an empty manifest, so a first ingest into a site with no manifest file reads a clean {}. A valid
+ *  object is returned as the manifest. */
+export function parseMediaManifest(json) {
+    if (!json || typeof json !== 'object' || Array.isArray(json))
+        return {};
+    return json;
+}
+/** Validate one posted value as a MediaEntry, returning it narrowed or undefined. The trust boundary
+ *  for an optimistic record the client re-posts: the upload action server-owned each field at
+ *  creation, but a re-post is untrusted, so every field is re-checked. A `hash` must be the 16-hex
+ *  content-hash prefix; the string fields must be strings; `bytes` must be finite; `width`/`height`
+ *  must each be a number or null; `createdAt` must be a string. */
+function validateMediaEntry(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const e = value;
+    const isString = (v) => typeof v === 'string';
+    const isNumOrNull = (v) => v === null || typeof v === 'number';
+    if (typeof e.hash !== 'string' || !/^[0-9a-f]{16}$/.test(e.hash))
+        return undefined;
+    if (!isString(e.sha256))
+        return undefined;
+    if (!isString(e.slug) || !isString(e.displayName) || !isString(e.originalFilename))
+        return undefined;
+    if (!isString(e.alt) || !isString(e.ext) || !isString(e.contentType))
+        return undefined;
+    if (typeof e.bytes !== 'number' || !Number.isFinite(e.bytes))
+        return undefined;
+    if (!isNumOrNull(e.width) || !isNumOrNull(e.height))
+        return undefined;
+    if (!isString(e.createdAt))
+        return undefined;
+    return {
+        hash: e.hash,
+        sha256: e.sha256,
+        slug: e.slug,
+        displayName: e.displayName,
+        originalFilename: e.originalFilename,
+        alt: e.alt,
+        ext: e.ext,
+        contentType: e.contentType,
+        bytes: e.bytes,
+        width: e.width,
+        height: e.height,
+        createdAt: e.createdAt,
+    };
+}
+/** Parse the posted `media` field into a validated list of MediaEntry rows. The field arrives as a
+ *  JSON string (the usual form-post shape), an already-parsed array, or junk. A string is JSON-parsed
+ *  inside a try/catch that yields `[]` on a parse failure; a non-string array is taken directly;
+ *  anything else yields `[]`. Each element is validated and a failing element is dropped, so a partly
+ *  malformed post still lands its good rows. This is the trust boundary for the client's optimistic
+ *  records. */
+export function parseMediaEntries(value) {
+    let raw = value;
+    if (typeof value === 'string') {
+        try {
+            raw = JSON.parse(value);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(raw))
+        return [];
+    const entries = [];
+    for (const item of raw) {
+        const entry = validateMediaEntry(item);
+        if (entry)
+            entries.push(entry);
+    }
+    return entries;
+}
+/** The dedup lookup: the entry stored under the content-hash prefix, or undefined when no bytes with
+ *  that hash are stored yet. */
+export function findByHash(manifest, hash) {
+    return manifest[hash];
+}
+/** Set the entry under its own hash, replacing any same-hash row. Returns a new manifest and leaves
+ *  the input untouched, so a caller's prior manifest reference stays valid. The ingest path's patch. */
+export function upsertMediaEntry(manifest, entry) {
+    return { ...manifest, [entry.hash]: entry };
+}
+/** Drop the entry under the given hash, returning a new manifest and leaving the input untouched.
+ *  Removing an absent hash is a no-op that still returns an equivalent new manifest. The safe-delete
+ *  path's patch. */
+export function removeMediaEntry(manifest, hash) {
+    const { [hash]: _removed, ...rest } = manifest;
+    return rest;
+}
+/** Serialize canonically: the top-level hash keys sorted ascending, two-space pretty, and a trailing
+ *  newline, so the committed file diffs cleanly in a PR and a re-serialization is byte-identical. */
+export function serializeMediaManifest(manifest) {
+    const sorted = {};
+    for (const hash of Object.keys(manifest).sort()) {
+        sorted[hash] = manifest[hash];
+    }
+    return `${JSON.stringify(sorted, null, 2)}\n`;
+}

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;