@glw907/cairn-cms 0.56.2 → 0.57.0

package/src/lib/delivery/seo.ts

@@ -13,6 +13,8 @@ export interface SeoInput {
   modified?: string;
   feeds?: { rss?: string; json?: string };
   image?: string;
+  /** The social image's alt text, emitted as twitter:image:alt. Used only when image is also set. */
+  imageAlt?: string;
   /** A robots meta directive, e.g. "noindex, nofollow". Omitted from the head when absent. */
   robots?: string;
   /** Author name, emitted as article:author for the article type. */
@@ -42,6 +44,9 @@ export function buildSeoMeta(input: SeoInput): SeoMeta {
   if (input.image) {
     meta.push({ property: 'og:image', content: input.image });
     meta.push({ name: 'twitter:image', content: input.image });
+    if (input.imageAlt) {
+      meta.push({ name: 'twitter:image:alt', content: input.imageAlt });
+    }
   }
 
   if (input.robots) {

package/src/lib/doctor/checks-local.ts

@@ -27,6 +27,28 @@ export const configBindings: DoctorCheck = {
 	},
 };
 
+// The R2 media bucket is never added to the hard config.bindings check, so a no-media site never
+// fails on a missing media binding (decision 9). This conditional runs only when the adapter
+// declares assets, matching the adapter's bucketBinding against wrangler's r2_buckets. It reuses the
+// config.bindings-missing condition rather than registering a new one, so the readiness count holds.
+export const configMediaBucket: DoctorCheck = {
+	id: 'config.media-bucket',
+	conditionId: 'config.bindings-missing',
+	title: 'Media bucket binding',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		const binding = ctx.mediaBucketBinding;
+		if (binding === undefined) return skip('no media assets configured');
+		const facts = await readWranglerConfig(ctx.readFile);
+		if (facts === null) return NO_WRANGLER;
+		if (!facts.r2Buckets.includes(binding)) {
+			return fail(
+				`adapter declares media bucket ${binding} but no matching r2_buckets binding is in wrangler`
+			);
+		}
+		return pass(`media bucket ${binding} is declared`);
+	},
+};
+
 export const configObservability: DoctorCheck = {
 	id: 'config.observability',
 	conditionId: 'config.observability-off',

package/src/lib/doctor/index.ts

@@ -4,6 +4,7 @@
 import type { DoctorCheck, DoctorContext } from './types.js';
 import {
 	configBindings,
+	configMediaBucket,
 	configObservability,
 	configCsrfDisable,
 	configSiteConfig,
@@ -93,8 +94,14 @@ export function contextFromEnv(
  *  Vite resolution and the wrangler config's account_id. Each runs only when an input it feeds
  *  is still missing, so a doctor run with full flags touches neither. */
 export interface DerivationSources {
-	/** Returns { owner, repo, from } off the adapter, or null when nothing is derivable. */
-	adapterFacts: () => Promise<{ owner?: string; repo?: string; from?: string } | null>;
+	/** Returns { owner, repo, from, mediaBucketBinding } off the adapter, or null when nothing is
+	 *  derivable. */
+	adapterFacts: () => Promise<{
+		owner?: string;
+		repo?: string;
+		from?: string;
+		mediaBucketBinding?: string;
+	} | null>;
 	/** Returns the wrangler config's account_id, or undefined when none is declared. */
 	wranglerAccountId: () => Promise<string | undefined>;
 }
@@ -112,7 +119,14 @@ export async function deriveMissingInputs(
 	sources: DerivationSources
 ): Promise<Omit<DoctorContext, 'fetch' | 'readFile'>> {
 	const out = { ...ctx };
-	if (out.from === undefined || out.repo === undefined) {
+	// The adapter read also carries the media bucket binding, which has no env source, so it runs
+	// when from, repo, or the media binding is still missing. A failure leaves each input absent so
+	// its check skips with the usual remediation rather than the doctor crashing.
+	if (
+		out.from === undefined ||
+		out.repo === undefined ||
+		out.mediaBucketBinding === undefined
+	) {
 		const facts = await sources.adapterFacts().catch(() => null);
 		if (out.from === undefined && typeof facts?.from === 'string') {
 			out.from = facts.from;
@@ -124,6 +138,9 @@ export async function deriveMissingInputs(
 		) {
 			out.repo = `${facts.owner}/${facts.repo}`;
 		}
+		if (out.mediaBucketBinding === undefined && typeof facts?.mediaBucketBinding === 'string') {
+			out.mediaBucketBinding = facts.mediaBucketBinding;
+		}
 	}
 	if (out.cfAccountId === undefined) {
 		const accountId = await sources.wranglerAccountId().catch(() => undefined);
@@ -140,6 +157,7 @@ export async function deriveMissingInputs(
 export function defaultChecks(): DoctorCheck[] {
 	return [
 		configBindings,
+		configMediaBucket,
 		configObservability,
 		configCsrfDisable,
 		configSiteConfig,

package/src/lib/doctor/types.ts

@@ -45,6 +45,9 @@ export interface DoctorContext {
 	cfAccountId?: string;
 	/** PUBLIC_ORIGIN, the env fallback when the wrangler vars carry none. */
 	publicOrigin?: string;
+	/** The adapter's media bucket binding (cairn.assets.bucketBinding), derived off the adapter.
+	 *  Undefined when the site declares no media assets; the media-bucket check skips in that case. */
+	mediaBucketBinding?: string;
 	/** GITHUB_APP_ID / GITHUB_APP_INSTALLATION_ID / GITHUB_APP_PRIVATE_KEY_B64. */
 	github?: { appId: string; installationId: string; privateKeyB64: string };
 	/** Injected fetch for tests; defaults to global fetch. */

package/src/lib/doctor/wrangler-config.ts

@@ -16,6 +16,9 @@ export interface WranglerFacts {
 	publicOrigin?: string;
 	/** The top-level account_id, when declared; a fallback for CLOUDFLARE_ACCOUNT_ID. */
 	accountId?: string;
+	/** The declared r2_buckets binding names; the conditional media check matches the adapter's
+	 *  bucketBinding against this. Not part of the hard config.bindings check (decision 9). */
+	r2Buckets: string[];
 }
 
 export async function readWranglerConfig(
@@ -89,10 +92,19 @@ function factsFromJsonc(text: string): WranglerFacts {
 			typeof entry === 'object' && entry !== null && (entry as { binding?: unknown }).binding === 'AUTH_DB'
 	);
 	const observability = config.observability as { enabled?: unknown } | undefined;
+	const r2 = Array.isArray(config.r2_buckets) ? config.r2_buckets : [];
+	const r2Buckets = r2
+		.map((entry) =>
+			typeof entry === 'object' && entry !== null && typeof (entry as { binding?: unknown }).binding === 'string'
+				? (entry as { binding: string }).binding
+				: undefined
+		)
+		.filter((binding): binding is string => binding !== undefined);
 	const facts: WranglerFacts = {
 		hasEmailBinding,
 		hasAuthDb: authDb !== undefined,
 		observabilityEnabled: observability?.enabled === true,
+		r2Buckets,
 	};
 	if (typeof authDb?.database_id === 'string') facts.authDbId = authDb.database_id;
 	const vars = config.vars as { PUBLIC_ORIGIN?: unknown } | undefined;
@@ -110,10 +122,12 @@ function factsFromToml(text: string): WranglerFacts {
 		hasEmailBinding: false,
 		hasAuthDb: false,
 		observabilityEnabled: false,
+		r2Buckets: [],
 	};
 	let section = '';
 	let d1Binding: string | undefined;
 	let d1Id: string | undefined;
+	let r2Binding: string | undefined;
 
 	const flushD1 = () => {
 		if (d1Binding === 'AUTH_DB') {
@@ -124,10 +138,16 @@ function factsFromToml(text: string): WranglerFacts {
 		d1Id = undefined;
 	};
 
+	const flushR2 = () => {
+		if (r2Binding !== undefined) facts.r2Buckets.push(r2Binding);
+		r2Binding = undefined;
+	};
+
 	for (const line of text.split('\n')) {
 		const header = line.match(/^\s*(\[\[?[\w.]+\]?\])\s*(?:#.*)?$/);
 		if (header) {
 			flushD1();
+			flushR2();
 			section = header[1];
 			continue;
 		}
@@ -140,6 +160,8 @@ function factsFromToml(text: string): WranglerFacts {
 		} else if (section === '[[d1_databases]]') {
 			if (key === 'binding') d1Binding = str;
 			if (key === 'database_id') d1Id = str;
+		} else if (section === '[[r2_buckets]]') {
+			if (key === 'binding' && str !== undefined) r2Binding = str;
 		} else if (section === '[observability]' && key === 'enabled' && value.startsWith('true')) {
 			facts.observabilityEnabled = true;
 		} else if (section === '[vars]' && key === 'PUBLIC_ORIGIN' && str !== undefined) {
@@ -149,5 +171,6 @@ function factsFromToml(text: string): WranglerFacts {
 		}
 	}
 	flushD1();
+	flushR2();
 	return facts;
 }

package/src/lib/env.ts

@@ -1,5 +1,6 @@
 import type { D1Database } from '@cloudflare/workers-types';
 import { CairnError } from './diagnostics/index.js';
+import type { DeliveryBucket } from './media/delivery-bucket.js';
 
 /**
  * Returns the site's public origin from configuration.
@@ -49,3 +50,30 @@ export function requireDb(env: { AUTH_DB?: D1Database }): D1Database {
   }
   return env.AUTH_DB;
 }
+
+/**
+ * Returns the media R2 bucket named by `bindingName`, or throws a clear error when a site has not
+ * wired it. The binding name is config-derived (the adapter's `bucketBinding`), so it is read off
+ * `env` dynamically rather than as a fixed key.
+ *
+ * The return type is the narrow structural `DeliveryBucket` seam, never the `@cloudflare/workers-types`
+ * `R2Bucket`, so no workers-types name reaches the public `.d.ts` (the delivery route is a public
+ * export and that package is only a devDependency). The cast through `unknown` is sound because the
+ * seam models a subset of the real R2 bucket API.
+ *
+ * The guard rejects a value wired to the wrong kind of binding too (a KV namespace, a string var),
+ * which is truthy but carries no callable `get`. Without that check the cast would succeed and the
+ * first `bucket.get(...)` would throw an uncaught 500 rather than the drained 503 a missing binding
+ * earns.
+ *
+ * @throws CairnError (`config.bindings-missing`) when the named binding is absent or not an R2 bucket.
+ */
+export function requireBucket(env: Record<string, unknown>, bindingName: string): DeliveryBucket {
+  const bucket = env[bindingName];
+  if (!bucket || typeof (bucket as { get?: unknown }).get !== 'function') {
+    throw new CairnError('config.bindings-missing', {
+      message: `${bindingName} binding is not configured`,
+    });
+  }
+  return bucket as unknown as DeliveryBucket;
+}

package/src/lib/index.ts

@@ -16,6 +16,8 @@ export type {
   BooleanField,
   TagsField,
   FreeTagsField,
+  ImageField,
+  ImageValue,
   ValidationResult,
   BackendConfig,
   SenderConfig,

package/src/lib/log/events.ts

@@ -15,4 +15,11 @@ export type CairnLogEvent =
   | 'entry.discarded'
   | 'publish.failed'
   | 'github.unreachable'
-  | 'guard.rejected';
+  | 'guard.rejected'
+  | 'media.uploaded'
+  | 'media.upload_failed'
+  | 'media.delivery_failed'
+  | 'media.orphan_reconcile'
+  | 'media.resolve_missing'
+  | 'media.deleted'
+  | 'media.delete_blocked';

package/src/lib/media/config.ts

@@ -0,0 +1,103 @@
+// cairn-cms: media config normalization. A site declares its media setup as an AssetConfig on the
+// adapter; this module validates that block and resolves it into the engine-internal
+// ResolvedAssetConfig the upload, storage, and delivery paths read. An absent block means media is
+// off, so the resolved value carries an `enabled` discriminant rather than throwing. The named
+// variants merge over the built-in presets, so a caller preset of the same name wins. This module
+// is engine-internal; later phases call normalizeAssets, but the contract surface stays AssetConfig.
+import type { AssetConfig } from '../content/types.js';
+import type { VariantSpec } from './transform-url.js';
+
+/** The resolved media config the engine serves from. When a site declares no assets block, media is
+ *  off and the value is `{ enabled: false }`; otherwise every field is filled from the AssetConfig
+ *  or its default. */
+export type ResolvedAssetConfig =
+  | { enabled: false }
+  | {
+      enabled: true;
+      bucketBinding: string;
+      publicBase: string;
+      urlForm: 'slug' | 'opaque';
+      maxUploadBytes: number;
+      allowedTypes: string[];
+      variants: Record<string, VariantSpec>;
+      /** Whether Cloudflare Image Transformations are enabled for the zone. With it false, the media
+       *  resolver serves the bare full-size delivery path and ignores any preset. */
+      transformations: boolean;
+    };
+
+/** 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: Record<string, VariantSpec> = {
+  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: ReadonlySet<string> = 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: ReadonlySet<string> = 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: string, spec: VariantSpec): void {
+  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: AssetConfig | undefined): ResolvedAssetConfig {
+  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/src/lib/media/delivery-bucket.ts

@@ -0,0 +1,41 @@
+// 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.
+
+/** 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/src/lib/media/index.ts

@@ -0,0 +1,22 @@
+// 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, 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/src/lib/media/library-entry.ts

@@ -0,0 +1,58 @@
+// cairn-cms: the picker's human layer for one stored asset, the projection EditData carries on
+// `mediaLibrary`. It is the media manifest's display facts (no sha256, no original filename) keyed by
+// the 16-hex content hash, the shape the insert popover, the combobox picker, the editor's source
+// decoration, and the Library screen all read.
+//
+// It lives in its own node-safe module (no @codemirror, no DOM, no @sveltejs/kit) so the consumers
+// share one declaration: editLoad and mediaLibraryLoad both project it through `mediaLibraryEntry`,
+// MediaPicker and the insert popover type their library prop with it, and the editor-media
+// decoration resolves a token against it. The editor-boundary test bars a static import from
+// editor-media.ts (it pulls @codemirror), so the shared type cannot be sourced from there; this
+// module is its neutral home. It is internal, exported from no package subpath, so it carries no
+// reference page.
+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 function mediaLibraryEntry(entry: MediaEntry): MediaLibraryEntry {
+  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/src/lib/media/manifest.ts

@@ -0,0 +1,122 @@
+// 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.
+
+/** 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 function parseMediaManifest(json: unknown): MediaManifest {
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return {};
+  return json as MediaManifest;
+}
+
+/** 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: unknown): MediaEntry | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const e = value as Record<string, unknown>;
+  const isString = (v: unknown): v is string => typeof v === 'string';
+  const isNumOrNull = (v: unknown): v is number | null => 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: unknown): MediaEntry[] {
+  let raw: unknown = value;
+  if (typeof value === 'string') {
+    try {
+      raw = JSON.parse(value);
+    } catch {
+      return [];
+    }
+  }
+  if (!Array.isArray(raw)) return [];
+  const entries: MediaEntry[] = [];
+  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: MediaManifest, hash: string): MediaEntry | undefined {
+  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: MediaManifest, entry: MediaEntry): MediaManifest {
+  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: MediaManifest, hash: string): MediaManifest {
+  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: MediaManifest): string {
+  const sorted: MediaManifest = {};
+  for (const hash of Object.keys(manifest).sort()) {
+    sorted[hash] = manifest[hash];
+  }
+  return `${JSON.stringify(sorted, null, 2)}\n`;
+}