@glw907/cairn-cms 0.56.2 → 0.57.0

package/dist/delivery/seo.d.ts

@@ -12,6 +12,8 @@ export interface SeoInput {
         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. */

package/dist/delivery/seo.js

@@ -16,6 +16,9 @@ export function buildSeoMeta(input) {
     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) {
         meta.push({ name: 'robots', content: input.robots });

package/dist/doctor/checks-local.d.ts

@@ -1,5 +1,6 @@
 import type { DoctorCheck } from './types.js';
 export declare const configBindings: DoctorCheck;
+export declare const configMediaBucket: DoctorCheck;
 export declare const configObservability: DoctorCheck;
 export declare const configCsrfDisable: DoctorCheck;
 export declare const configPublicOrigin: DoctorCheck;

package/dist/doctor/checks-local.js

@@ -26,6 +26,27 @@ export const configBindings = {
         return pass('EMAIL and AUTH_DB are declared');
     },
 };
+// 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 = {
+    id: 'config.media-bucket',
+    conditionId: 'config.bindings-missing',
+    title: 'Media bucket binding',
+    async run(ctx) {
+        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 = {
     id: 'config.observability',
     conditionId: 'config.observability-off',

package/dist/doctor/index.d.ts

@@ -22,11 +22,13 @@ export declare function contextFromEnv(env: Record<string, string | undefined>,
  *  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. */
+    /** 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>;

package/dist/doctor/index.js

@@ -1,4 +1,4 @@
-import { configBindings, configObservability, configCsrfDisable, configSiteConfig, configPublicOrigin, } from './checks-local.js';
+import { configBindings, configMediaBucket, configObservability, configCsrfDisable, configSiteConfig, configPublicOrigin, } from './checks-local.js';
 import { configDependencyFloors } from './check-floors.js';
 import { emailSenderOnboarded, edgeHttpsForced, edgeHsts, authStore } from './checks-cloudflare.js';
 import { githubApp } from './checks-github.js';
@@ -69,7 +69,12 @@ export function contextFromEnv(env, args, cwd) {
  */
 export async function deriveMissingInputs(ctx, sources) {
     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;
@@ -79,6 +84,9 @@ export async function deriveMissingInputs(ctx, sources) {
             typeof facts?.repo === 'string') {
             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);
@@ -95,6 +103,7 @@ export async function deriveMissingInputs(ctx, sources) {
 export function defaultChecks() {
     return [
         configBindings,
+        configMediaBucket,
         configObservability,
         configCsrfDisable,
         configSiteConfig,

package/dist/doctor/types.d.ts

@@ -30,6 +30,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;

package/dist/doctor/wrangler-config.d.ts

@@ -12,5 +12,8 @@ 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 declare function readWranglerConfig(readFile: DoctorContext['readFile']): Promise<WranglerFacts | null>;

package/dist/doctor/wrangler-config.js

@@ -64,10 +64,17 @@ function factsFromJsonc(text) {
     const databases = Array.isArray(config.d1_databases) ? config.d1_databases : [];
     const authDb = databases.find((entry) => typeof entry === 'object' && entry !== null && entry.binding === 'AUTH_DB');
     const observability = config.observability;
+    const r2 = Array.isArray(config.r2_buckets) ? config.r2_buckets : [];
+    const r2Buckets = r2
+        .map((entry) => typeof entry === 'object' && entry !== null && typeof entry.binding === 'string'
+        ? entry.binding
+        : undefined)
+        .filter((binding) => binding !== undefined);
     const facts = {
         hasEmailBinding,
         hasAuthDb: authDb !== undefined,
         observabilityEnabled: observability?.enabled === true,
+        r2Buckets,
     };
     if (typeof authDb?.database_id === 'string')
         facts.authDbId = authDb.database_id;
@@ -87,10 +94,12 @@ function factsFromToml(text) {
         hasEmailBinding: false,
         hasAuthDb: false,
         observabilityEnabled: false,
+        r2Buckets: [],
     };
     let section = '';
     let d1Binding;
     let d1Id;
+    let r2Binding;
     const flushD1 = () => {
         if (d1Binding === 'AUTH_DB') {
             facts.hasAuthDb = true;
@@ -100,10 +109,16 @@ function factsFromToml(text) {
         d1Binding = undefined;
         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;
         }
@@ -121,6 +136,10 @@ function factsFromToml(text) {
             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;
         }
@@ -132,5 +151,6 @@ function factsFromToml(text) {
         }
     }
     flushD1();
+    flushR2();
     return facts;
 }

package/dist/env.d.ts

@@ -1,4 +1,5 @@
 import type { D1Database } from '@cloudflare/workers-types';
+import type { DeliveryBucket } from './media/delivery-bucket.js';
 /**
  * Returns the site's public origin from configuration.
  *
@@ -22,3 +23,21 @@ export declare function requireOrigin(env: {
 export declare function requireDb(env: {
     AUTH_DB?: D1Database;
 }): D1Database;
+/**
+ * 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 declare function requireBucket(env: Record<string, unknown>, bindingName: string): DeliveryBucket;

package/dist/env.js

@@ -47,3 +47,29 @@ export function requireDb(env) {
     }
     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, bindingName) {
+    const bucket = env[bindingName];
+    if (!bucket || typeof bucket.get !== 'function') {
+        throw new CairnError('config.bindings-missing', {
+            message: `${bindingName} binding is not configured`,
+        });
+    }
+    return bucket;
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { requireOrigin } from './env.js';
 export type { Role, Editor, AuthEnv } from './auth/types.js';
 export type { AuthBranding, MagicLinkMessage, SendMagicLink } from './email.js';
 export { buildMagicLinkMessage, cloudflareSend } from './email.js';
-export type { CairnAdapter, ConceptConfig, FrontmatterField, TextField, TextareaField, DateField, BooleanField, TagsField, FreeTagsField, ValidationResult, BackendConfig, SenderConfig, NavMenuConfig, PreviewConfig, ResolvedPreview, AssetConfig, RoutingRule, ConceptDescriptor, ConceptUrlPolicy, CairnExtension, CairnRuntime, AdminPanel, FieldTypeDef, } from './content/types.js';
+export type { CairnAdapter, ConceptConfig, FrontmatterField, TextField, TextareaField, DateField, BooleanField, TagsField, FreeTagsField, ImageField, ImageValue, ValidationResult, BackendConfig, SenderConfig, NavMenuConfig, PreviewConfig, ResolvedPreview, AssetConfig, RoutingRule, ConceptDescriptor, ConceptUrlPolicy, CairnExtension, CairnRuntime, AdminPanel, FieldTypeDef, } from './content/types.js';
 export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
 export type { ComposeInput } from './content/compose.js';

package/dist/log/events.d.ts

@@ -1 +1 @@
-export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'github.unreachable' | 'guard.rejected';
+export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'github.unreachable' | 'guard.rejected' | 'media.uploaded' | 'media.upload_failed' | 'media.delivery_failed' | 'media.orphan_reconcile' | 'media.resolve_missing' | 'media.deleted' | 'media.delete_blocked';

package/dist/media/config.d.ts

@@ -0,0 +1,24 @@
+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;
+};
+/** 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 declare function normalizeAssets(assets: AssetConfig | undefined): ResolvedAssetConfig;

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`;
+}