@glw907/cairn-cms 0.56.2 → 0.57.1

package/src/lib/components/media-upload-outcome.ts

@@ -0,0 +1,83 @@
+// The pure upload-envelope to outcome mapper. The insert popover's optimistic loop posts the bytes
+// and reads back a SvelteKit form-action result (or a manual-redirect Response shape); this turns
+// that raw shape into the one decision the popover acts on: insert the reference, show a typed
+// failure card, or treat the session as expired. Keeping it pure lets the branch logic unit-test
+// without a browser or a real fetch.
+//
+// Node-safe (no @codemirror, no DOM): it imports only the MediaEntry and UploadResult types, which
+// are erased at build time.
+import type { MediaEntry } from '../media/manifest.js';
+import type { UploadResult } from '../sveltekit/content-routes.js';
+import type { IngestFailureKind } from './client-ingest.js';
+import { mediaToken } from '../media/reference.js';
+
+/** A failure the card surfaces. The ingest taxonomy plus a `generic` catch-all for a refuse reason
+ *  with no specific author-facing card (a binding-missing, a length-required, a parse miss). */
+export type UploadFailureKind = IngestFailureKind | 'generic';
+
+/** The outcome the popover acts on. `inserted` swaps the placeholder for the reference and records
+ *  the entry; `failed` cancels the placeholder and shows the typed card; `session-expired` cancels
+ *  the placeholder and tells the author to sign in again. */
+export type UploadOutcome =
+  | { kind: 'inserted'; reference: string; record: MediaEntry; reused: boolean }
+  | { kind: 'failed'; failure: UploadFailureKind }
+  | { kind: 'session-expired' };
+
+/** The shape the popover hands in: either a parsed SvelteKit action result (success or failure) or a
+ *  bare response signal for the redirect and network-error cases. The popover deserializes the body
+ *  for the success and failure cases and passes the raw `response.type`/`response.status` for the
+ *  redirect case, so this one mapper covers every branch. */
+export type UploadEnvelope =
+  | { type: 'success'; status?: number; data: UploadResult }
+  | { type: 'failure'; status?: number; data?: { error?: string } }
+  | { type: 'redirect'; status?: number }
+  | { type: 'error'; status?: number }
+  | { type: 'opaqueredirect'; status?: number };
+
+// The server refuse reasons mapped to a card kind. `too-large` keeps its own card; an unsupported
+// type reads as a decode failure to the author (the bytes the browser sent are a type the server
+// will not store); `session-expired` is its own outcome. Every other reason (binding-missing,
+// media-disabled, csrf, length-required, hash-collision) is an operational refusal with no
+// author-actionable specifics, so it collapses to the generic card.
+const REFUSE_TO_FAILURE: Record<string, UploadFailureKind | 'session-expired'> = {
+  'too-large': 'too-large',
+  'unsupported-type': 'decode-unsupported',
+  'session-expired': 'session-expired',
+};
+
+/**
+ * Map a parsed upload envelope to the single outcome the popover acts on. A success envelope yields
+ * an `inserted` outcome carrying the reference, the record, and the dedup flag. A failure envelope
+ * maps its refuse reason to a typed card, with `session-expired` lifted to its own outcome. An
+ * opaque or status-0 response (the guard's `redirect: 'manual'` 303) is a session-expired signal, as
+ * is any redirect-typed result. An error-typed result with a real status is a generic failure.
+ */
+export function uploadOutcome(envelope: UploadEnvelope): UploadOutcome {
+  switch (envelope.type) {
+    case 'success':
+      return {
+        kind: 'inserted',
+        // Re-derive the reference from the validated record fields rather than trusting the loose
+        // server `reference` string: the token is inserted unescaped into the markdown URL slot, so
+        // the insert depends only on grammar-constrained fields (a 16-hex hash, a slugified slug)
+        // instead of an arbitrary server string. Defense in depth, in case a future server path
+        // returns a reference that does not match the record.
+        reference: mediaToken({ slug: envelope.data.record.slug, hash: envelope.data.record.hash }),
+        record: envelope.data.record,
+        reused: envelope.data.reused,
+      };
+    case 'failure': {
+      const reason = envelope.data?.error ?? '';
+      const mapped = REFUSE_TO_FAILURE[reason];
+      if (mapped === 'session-expired') return { kind: 'session-expired' };
+      return { kind: 'failed', failure: mapped ?? 'generic' };
+    }
+    case 'redirect':
+    case 'opaqueredirect':
+      return { kind: 'session-expired' };
+    case 'error':
+      // A manual-redirect Response surfaces as type 'opaqueredirect' or status 0; a status-0 error
+      // is that same expired-session signal. A real error status is a genuine transport failure.
+      return (envelope.status ?? 0) === 0 ? { kind: 'session-expired' } : { kind: 'failed', failure: 'generic' };
+  }
+}

package/src/lib/content/compose.ts

@@ -5,6 +5,7 @@
 // is additive later.
 import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, FieldTypeDef } from './types.js';
 import { resolveConcepts } from './concepts.js';
+import { normalizeAssets } from '../media/config.js';
 import type { SiteConfig } from '../nav/site-config.js';
 
 /** The input to {@link composeRuntime}. `siteConfig` is required so the per-concept URL policy is
@@ -46,6 +47,8 @@ export function composeRuntime({ adapter, siteConfig, extensions = [] }: Compose
     navMenu: adapter.navMenu,
     preview: adapter.preview,
     assets: adapter.assets,
+    resolvedAssets: normalizeAssets(adapter.assets),
+    mediaManifestPath: adapter.mediaManifestPath ?? 'src/content/.cairn/media.json',
     adminPanels,
     fieldTypes,
   };

package/src/lib/content/frontmatter.ts

@@ -3,7 +3,7 @@
 // on-disk write/read pair. Kept as one seam so a site owns its serialization contract
 // (quoting, key order) without the save endpoint reaching for gray-matter directly.
 import matter from 'gray-matter';
-import type { FrontmatterField } from './types.js';
+import type { FrontmatterField, ImageValue } from './types.js';
 
 /** Decode submitted form data into raw frontmatter, one rule per field type. */
 export function frontmatterFromForm(
@@ -30,6 +30,25 @@ export function frontmatterFromForm(
           ),
         ];
         break;
+      case 'image': {
+        // The hero submits three sub-fields under one key. An empty src means no hero, so omit the
+        // whole key. Alt is stored verbatim (it is not markdown, so no escaping). A blank caption
+        // is dropped so committed frontmatter stays minimal.
+        const src = String(form.get(`${field.name}.src`) ?? '').trim();
+        if (src === '') break;
+        const value: ImageValue = {
+          src,
+          alt: String(form.get(`${field.name}.alt`) ?? ''),
+        };
+        const caption = String(form.get(`${field.name}.caption`) ?? '').trim();
+        if (caption !== '') value.caption = caption;
+        // An explicit decorative choice persists so a reload tells it apart from a left-blank alt.
+        // The key is dropped otherwise to keep committed frontmatter minimal.
+        const decorative = String(form.get(`${field.name}.decorative`) ?? '');
+        if (decorative === 'true') value.decorative = true;
+        data[field.name] = value;
+        break;
+      }
       default:
         // FormData.get returns null for an absent field; normalize to an empty string so
         // a caller reading a text value never gets null.

package/src/lib/content/manifest.ts

@@ -7,6 +7,7 @@ import { parseMarkdown } from './frontmatter.js';
 import { deriveExcerpt } from './excerpt.js';
 import { entryIdentity, asString } from './identity.js';
 import { extractCairnLinks, type CairnRef, type LinkResolve } from './links.js';
+import { extractMediaRefs } from './media-refs.js';
 import type { ConceptDescriptor } from './types.js';
 
 /** One entry's projection: its identity, routing, draft flag, and outbound cairn: edges. */
@@ -19,6 +20,10 @@ export interface ManifestEntry {
   summary?: string;
   draft: boolean;
   links: CairnRef[];
+  /** The content hashes of the media this entry references (its hero plus its body images). The
+   *  main side of the media where-used index. Additive and optional: an entry with no media omits
+   *  the key, and a manifest committed before this field still parses (absent reads as no refs). */
+  mediaRefs?: string[];
 }
 
 /** The whole corpus as one committed file. `version` guards a future shape migration. */
@@ -43,6 +48,9 @@ export interface LinkTarget {
 export function manifestEntryFromFile(descriptor: ConceptDescriptor, file: { path: string; raw: string }): ManifestEntry {
   const { frontmatter, body } = parseMarkdown(file.raw);
   const { id, date, permalink } = entryIdentity(descriptor, file.path, frontmatter);
+  // Set mediaRefs only when non-empty, so an image-free entry's row stays byte-identical to before
+  // (matching the optional-spread for date and summary).
+  const mediaRefs = extractMediaRefs(frontmatter, body, descriptor.fields);
   return {
     id,
     concept: descriptor.id,
@@ -54,6 +62,7 @@ export function manifestEntryFromFile(descriptor: ConceptDescriptor, file: { pat
     summary: deriveExcerpt(body, { description: asString(frontmatter.description) }) || undefined,
     draft: frontmatter.draft === true,
     links: extractCairnLinks(body),
+    ...(mediaRefs.length ? { mediaRefs } : {}),
   };
 }
 
@@ -78,6 +87,7 @@ export function serializeManifest(manifest: Manifest): string {
     ...(e.summary ? { summary: e.summary } : {}),
     draft: e.draft,
     links: [...e.links].sort(compareRef).map((r) => ({ concept: r.concept, id: r.id })),
+    ...(e.mediaRefs && e.mediaRefs.length ? { mediaRefs: [...e.mediaRefs].sort() } : {}),
   }));
   return `${JSON.stringify({ version: 1, entries }, null, 2)}\n`;
 }
@@ -109,10 +119,21 @@ export function parseManifest(raw: string): Manifest {
       typeof e.draft === 'boolean' &&
       (e.date === undefined || typeof e.date === 'string') &&
       (e.summary === undefined || typeof e.summary === 'string') &&
+      (e.mediaRefs === undefined || Array.isArray(e.mediaRefs)) &&
       Array.isArray(e.links);
     if (!ok) {
       throw new Error(`content manifest: malformed entry ${JSON.stringify(e)}`);
     }
+    // mediaRefs is additive and optional: an entry without it parses (the field reads as absent),
+    // so a manifest committed before this field still builds. When present, validate each element
+    // is a string, mirroring the link-element validation, so a hand-edited file fails loudly.
+    if (e.mediaRefs !== undefined) {
+      for (const hash of e.mediaRefs as unknown[]) {
+        if (typeof hash !== 'string') {
+          throw new Error(`content manifest: malformed mediaRefs element ${JSON.stringify(hash)} in entry ${JSON.stringify(e)}`);
+        }
+      }
+    }
     // Validate each link element's shape, not just that links is an array. inboundLinks and the
     // delete guard read l.concept and l.id, so a string, null, or id-less element would read as
     // undefined and silently drop a real inbound linker. Reject it here instead.
@@ -181,11 +202,33 @@ function formatDiff(d: ManifestDiff): string {
 export function verifyManifest(built: Manifest, committedRaw: string): void {
   const builtRaw = serializeManifest(built);
   if (committedRaw === builtRaw) return;
+  // mediaRefs is additive: a site whose committed manifest predates the field must still build,
+  // even when its content references media (open risk 3, the migration landmine). Before diffing,
+  // normalize the built manifest against the committed one: for any built entry whose committed
+  // counterpart carries no mediaRefs key, drop mediaRefs from the built entry. An un-regenerated
+  // site (committed omits mediaRefs) then matches; a regenerated site (committed carries mediaRefs)
+  // still detects real drift in that field. The normalization is per entry and per missing key, so
+  // it never masks drift in any other field or in an entry the committed manifest already tracks.
+  const committed = parseManifest(committedRaw);
+  const committedByKey = new Map(committed.entries.map((e) => [keyOf(e), e]));
+  const normalized: Manifest = {
+    version: 1,
+    entries: built.entries.map((b) => {
+      const c = committedByKey.get(keyOf(b));
+      if (b.mediaRefs && c && c.mediaRefs === undefined) {
+        const { mediaRefs: _dropped, ...rest } = b;
+        return rest;
+      }
+      return b;
+    }),
+  };
+  const normalizedRaw = serializeManifest(normalized);
+  if (committedRaw === normalizedRaw) return;
   // Diff the canonical built form, not the raw one. serializeManifest sorts each entry's links, so a
   // build whose links are in extraction order would otherwise report a false (links) drift for an
   // entry whose link set is identical and only the order differs. Reuse the serialized form so both
   // sides are canonical.
-  const diff = diffManifests(parseManifest(builtRaw), parseManifest(committedRaw));
+  const diff = diffManifests(parseManifest(normalizedRaw), committed);
   throw new Error(
     'content manifest is stale: the committed file does not match the corpus.\n' +
       formatDiff(diff) +

package/src/lib/content/media-refs.ts

@@ -0,0 +1,58 @@
+// cairn-cms: the media-reference extractor. Given one entry's parsed frontmatter and body, it
+// returns the deduped content hashes the entry references. This is the main side of the media
+// where-used index: manifestEntryFromFile records the result per entry, and the usage-index
+// builder runs it directly over each open branch's edited markdown. It mirrors extractCairnLinks
+// (the same remark pipeline, the same first-occurrence dedup) but visits image nodes and the
+// frontmatter hero rather than link nodes.
+//
+// A media reference lives in two places, and both are load-bearing. Body image nodes carry the
+// inline `![](media:...)` placements (a 3a :::figure also lands here, since the figure directive
+// wraps a real image node). The frontmatter hero is the other site: a hero is `image: { src }` in
+// frontmatter, outside the markdown body, so an extractor that visited only body nodes would read
+// every in-use hero as orphaned and let safe-delete remove an in-use image.
+//
+// Every match is keyed by the parsed hash, the immutable truth, never the cosmetic slug, so a bare
+// `media:<hash>` and a `media:<slug>.<hash>` for the same bytes collapse to one.
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import { parseMediaToken } from '../media/reference.js';
+import type { FrontmatterField, ImageValue } from './types.js';
+
+/** The content hashes one entry references, in first-occurrence order, deduped by hash. Reads the
+ *  frontmatter hero `image.src` for each `image`-typed field plus every body image node. A
+ *  non-media or malformed token is skipped, never thrown, so a stray `![](/x.png)` does not break
+ *  the manifest build. The body is parsed as mdast, so a `media:` token inside a code span or fence
+ *  is never matched. */
+export function extractMediaRefs(
+  frontmatter: Record<string, unknown>,
+  body: string,
+  fields: FrontmatterField[],
+): string[] {
+  const seen = new Set<string>();
+  const hashes: string[] = [];
+  const add = (href: string) => {
+    const ref = parseMediaToken(href);
+    if (!ref || seen.has(ref.hash)) return;
+    seen.add(ref.hash);
+    hashes.push(ref.hash);
+  };
+
+  // The frontmatter hero arm: each `image`-typed field stores an ImageValue, so read its `.src`.
+  for (const field of fields) {
+    if (field.type !== 'image') continue;
+    const value = frontmatter[field.name];
+    if (value && typeof value === 'object' && typeof (value as ImageValue).src === 'string') {
+      add((value as ImageValue).src);
+    }
+  }
+
+  // The body arm: every image node's url. A 3a figure's inner image is a real image node.
+  const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
+  visit(tree, 'image', (node: { url?: string }) => {
+    if (node.url) add(node.url);
+  });
+
+  return hashes;
+}

package/src/lib/content/schema.ts

@@ -2,7 +2,7 @@
 // declaration yields a plain-data field projection for the editor form, a generated validator,
 // and an inferred frontmatter type. Plan 1 builds the additive primitive; the adapter-contract
 // cutover and the typed reads are Plan 2.
-import type { FrontmatterField, ValidationResult } from './types.js';
+import type { FrontmatterField, ImageValue, ValidationResult } from './types.js';
 import { validateFields } from './validate.js';
 
 /** The validate input the cairn adapter takes: the raw frontmatter and the body. */
@@ -26,14 +26,17 @@ type StandardResult<Output> =
   | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray<PropertyKey> }> };
 
 /** Map one field descriptor to the TS type of its normalized value. text, textarea, and date
- *  normalize to a string; a closed-vocabulary `tags` field to the option-union array. */
+ *  normalize to a string; a closed-vocabulary `tags` field to the option-union array; an `image`
+ *  field to its nested object. */
 type FieldValue<K extends FrontmatterField> = K extends { type: 'boolean' }
   ? boolean
-  : K extends { type: 'tags'; options: readonly (infer O extends string)[] }
-    ? O[]
-    : K extends { type: 'tags' | 'freetags' }
-      ? string[]
-      : string;
+  : K extends { type: 'image' }
+    ? ImageValue
+    : K extends { type: 'tags'; options: readonly (infer O extends string)[] }
+      ? O[]
+      : K extends { type: 'tags' | 'freetags' }
+        ? string[]
+        : string;
 
 /** Flatten an intersection into a single readable object type. */
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
@@ -102,6 +105,26 @@ function compilePatterns(fields: FrontmatterField[]): Map<string, RegExp> {
   return compiled;
 }
 
+// True when an image field feeds the social card: an explicit `seo: true`, or the back-compat
+// default that the field named `image` is the SEO image. The SEO unify (Task 4) reads this flag.
+function isSeoImage(field: FrontmatterField): boolean {
+  return field.type === 'image' && (field.seo === true || (field.seo === undefined && field.name === 'image'));
+}
+
+// A concept declares at most one SEO image field, so the social card is unambiguous. More than one
+// is a site config error: a hero named `cover` plus an explicit `seo` on another, or two explicit
+// `seo` fields. Fail loudly at declaration rather than emit a silent or wrong og:image.
+function checkSeoImageFields(fields: FrontmatterField[]): void {
+  const seo = fields.filter(isSeoImage);
+  if (seo.length > 1) {
+    const names = seo.map((field) => `"${field.name}"`).join(', ');
+    throw new Error(
+      `cairn: a concept declares at most one SEO image field, but found ${seo.length} (${names}). ` +
+        'Set seo: false on all but one, or rename the extra image fields so only one feeds the social card.',
+    );
+  }
+}
+
 /** Declare a concept's fields once. Returns the schema's faces derived from that one declaration. */
 export function defineFields<const F extends readonly FrontmatterField[]>(
   fields: F,
@@ -109,6 +132,7 @@ export function defineFields<const F extends readonly FrontmatterField[]>(
 ): ConceptSchema<F> {
   const list = [...fields] as FrontmatterField[];
   const patterns = compilePatterns(list);
+  checkSeoImageFields(list);
   const validate = (frontmatter: Record<string, unknown>, body: string): ValidationResult => {
     const base = validateFields(list, frontmatter);
     if (!base.ok) return base;

package/src/lib/content/types.ts

@@ -12,6 +12,7 @@ import type { IconSet } from '../render/glyph.js';
 import type { DatePrefix } from './ids.js';
 import type { ConceptSchema } from './schema.js';
 import type { LinkResolve } from './links.js';
+import type { VariantSpec } from '../media/transform-url.js';
 
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
 interface FieldBase {
@@ -73,11 +74,25 @@ export interface FreeTagsField extends FieldBase {
   type: 'freetags';
   placeholder?: string;
 }
+/**
+ * A hero image set in frontmatter. The stored value is the nested object
+ * `{ src: string; alt: string; caption?: string }`, where `src` is a 2b `media:` reference, `alt`
+ * is the screen-reader description, and `caption` is an optional line the site template may show.
+ * One image serves two jobs: the template's lead image and the social-card image. The field feeding
+ * the social card is the `seo`-flagged one, defaulting to the field named `image`; a concept declares
+ * at most one SEO image field.
+ */
+export interface ImageField extends FieldBase {
+  type: 'image';
+  /** Whether this field feeds the social-card image. The field named `image` defaults to true. */
+  seo?: boolean;
+}
 
 /**
- * The discriminated union the per-concept frontmatter form is generated from. Adding a
- * field type is one variant here plus one decode arm in `frontmatterFromForm` and one in
- * `validateFields`.
+ * The discriminated union the per-concept frontmatter form is generated from. A scalar field type
+ * is one variant here plus one decode arm in `frontmatterFromForm` and one in `validateFields`. The
+ * structured `image` field additionally needs a read-back arm in `formValues` and a type-inference
+ * arm in `schema.ts`, since its value is a nested object rather than a single string.
  */
 export type FrontmatterField =
   | TextField
@@ -85,7 +100,18 @@ export type FrontmatterField =
   | DateField
   | BooleanField
   | TagsField
-  | FreeTagsField;
+  | FreeTagsField
+  | ImageField;
+
+/** The stored value of an `image` field: a `media:` reference, a screen-reader description, and an
+ *  optional caption. */
+export interface ImageValue {
+  src: string;
+  alt: string;
+  caption?: string;
+  /** An explicit decorative choice: an empty alt that is not debt. Omitted unless true. */
+  decorative?: boolean;
+}
 
 /**
  * A validator's verdict. On success it carries the normalized frontmatter to commit; on
@@ -183,12 +209,28 @@ export interface PreviewConfig {
  *  values with the entry's concept override applied, and no `byConcept` map. */
 export type ResolvedPreview = Omit<PreviewConfig, 'byConcept'>;
 
-/** Reserved asset slot (seam 4). Typed and unused in the rebuild; R7/R9 read it later with no contract change. */
+/** A site's media configuration (seam 4). A site sets this to turn on R2-backed media: uploads,
+ *  content-addressed storage, and Cloudflare Images variants. Omitting it leaves media off. The
+ *  engine normalizes this into a `ResolvedAssetConfig` and merges the named variants over the
+ *  built-in thumb, inline, card, and hero presets. */
 export interface AssetConfig {
-  /** Repo-relative asset roots, e.g. ["static/images"]. */
-  roots: string[];
-  /** Public URL base, e.g. "/images". */
-  publicBase: string;
+  /** The R2 bucket binding name on the Worker, e.g. "MEDIA_BUCKET". Required when a site declares media. */
+  bucketBinding: string;
+  /** The delivery base path. Defaults to "/media". */
+  publicBase?: string;
+  /** Whether the public URL carries the slug ("slug") or stays opaque ("opaque"). Defaults to "slug". */
+  urlForm?: 'slug' | 'opaque';
+  /** The maximum accepted upload size in bytes. Defaults to 25 MB. */
+  maxUploadBytes?: number;
+  /** The accepted upload MIME types. Defaults to the common web image types. */
+  allowedTypes?: string[];
+  /** Named transform presets, merged over the built-in thumb/inline/card/hero presets. */
+  variants?: Record<string, VariantSpec>;
+  /** Whether Cloudflare Image Transformations are enabled for the zone (default false). The feature
+   *  is a per-zone setting that the dashboard or API turns on; it cannot be flipped from a Worker. With
+   *  it off, the media resolver serves the bare full-size delivery path and ignores any preset, so
+   *  thumbnails stay correct (full-size-but-correct) rather than pointing at a dead /cdn-cgi/image URL. */
+  transformations?: boolean;
 }
 
 /** The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`. */
@@ -206,11 +248,22 @@ export interface CairnAdapter {
   sender: SenderConfig;
   /** The site's one renderer: the editor preview and every public page call it (design decision 4).
    *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-resolver-backed
-   *  one, the preview a manifest one. */
-  render(md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }): string | Promise<string>;
+   *  one, the preview a manifest one. The trailing `resolveMedia` is additive and optional: the build
+   *  passes a site-resolver-backed media resolver, the preview a manifest-backed one. */
+  render(
+    md: string,
+    opts?: {
+      stagger?: boolean;
+      resolve?: LinkResolve;
+      resolveMedia?: import('../render/resolve-media.js').MediaResolve;
+    },
+  ): string | Promise<string>;
   /** Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
    *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it. */
   manifestPath?: string;
+  /** Repo-relative path to the committed media manifest. Defaults to src/content/.cairn/media.json,
+   *  applied in composeRuntime. Sits outside any concept directory, like the content manifest. */
+  mediaManifestPath?: string;
   /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
   registry?: ComponentRegistry;
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
@@ -313,9 +366,23 @@ export interface CairnRuntime {
   concepts: ConceptDescriptor[];
   backend: BackendConfig;
   sender: SenderConfig;
-  /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
-  render(md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }): string | Promise<string>;
+  /** The site's one renderer: the editor preview and every public page call it (design decision 4).
+   *  The trailing `resolveMedia` is additive and optional: the build passes a site-resolver-backed
+   *  media resolver, the preview a manifest-backed one. */
+  render(
+    md: string,
+    opts?: {
+      stagger?: boolean;
+      resolve?: LinkResolve;
+      resolveMedia?: import('../render/resolve-media.js').MediaResolve;
+    },
+  ): string | Promise<string>;
   manifestPath: string;
+  /** The repo-relative path to the committed media manifest, defaulted in composeRuntime. */
+  mediaManifestPath: string;
+  /** The adapter's asset config resolved once at compose: `{ enabled: false }` for a no-media site,
+   *  otherwise the filled config the upload, storage, delivery, and resolver paths read. */
+  resolvedAssets: import('../media/config.js').ResolvedAssetConfig;
   registry?: ComponentRegistry;
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
   icons?: IconSet;

package/src/lib/content/validate.ts

@@ -2,7 +2,7 @@
 // required-and-coerce baseline, then layers any bespoke rules on top, so the per-site
 // validator stays thin (engine-fat rule). Saving runs the concept's validator on the
 // server before any commit; invalid input bounces to the form (spec §7.4).
-import type { FrontmatterField, ValidationResult } from './types.js';
+import type { FrontmatterField, ImageValue, ValidationResult } from './types.js';
 import { dateInputValue, isCalendarDate } from './frontmatter.js';
 
 /**
@@ -44,6 +44,34 @@ export function validateFields(
         if (list.length > 0) data[field.name] = list;
         break;
       }
+      case 'image': {
+        // A hero is the nested object { src, alt, caption }. Normalize a well-formed value (default
+        // a missing alt to empty, since alt is debt and never a save block), and drop the key when
+        // src is empty or absent. A malformed value (a string, or an object without a string src)
+        // drops the key rather than throwing, so a hand-edit never breaks a save.
+        let src = '';
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+          const obj = value as Record<string, unknown>;
+          src = typeof obj.src === 'string' ? obj.src.trim() : '';
+          if (src !== '') {
+            const normalized: ImageValue = {
+              src,
+              alt: typeof obj.alt === 'string' ? obj.alt : '',
+            };
+            const caption = typeof obj.caption === 'string' ? obj.caption.trim() : '';
+            if (caption !== '') normalized.caption = caption;
+            // An explicit decorative choice carries through; it is never required and never a save
+            // block. A missing or non-boolean value drops the key, like a blank caption.
+            if (obj.decorative === true) normalized.decorative = true;
+            data[field.name] = normalized;
+          }
+        }
+        // A required image needs a src (the presence check), like the other arms; alt is never
+        // required, since alt is debt. The inferred type makes a required image non-optional, so the
+        // validator must enforce it or a save could omit it against the type.
+        if (field.required && src === '') errors[field.name] = `${field.label} is required`;
+        break;
+      }
       case 'date': {
         const text = value instanceof Date ? dateInputValue(value) : typeof value === 'string' ? value.trim() : '';
         if (field.required && text === '') errors[field.name] = `${field.label} is required`;

package/src/lib/delivery/public-routes.ts

@@ -11,6 +11,8 @@ import type { SeoMeta } from './seo.js';
 import { readSeoFields, resolveImageUrl } from './seo-fields.js';
 import { buildLinkResolver } from './site-resolver.js';
 import type { LinkResolve } from '../content/links.js';
+import type { MediaResolve } from '../render/resolve-media.js';
+import { parseMediaToken } from '../media/reference.js';
 
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
@@ -26,6 +28,10 @@ export interface PublicRoutesDeps {
   /** A site-wide default OG image, used when an entry declares none. Resolved to absolute like the
    *  canonical URL, so a relative path such as "/og/default.png" works. */
   defaultImage?: string;
+  /** Resolve a frontmatter `media:` hero reference to its delivery path. The site builds this from its
+   *  committed `media.json` exactly as it builds the body resolver (`makeMediaResolver`). When absent,
+   *  media is off and no `heroImage` projection is derived. */
+  resolveMedia?: MediaResolve;
 }
 
 /** The archive and tag list data: summaries the template renders. */
@@ -52,11 +58,48 @@ export interface EntryData {
   seo: SeoMeta;
   newer?: ContentSummary;
   older?: ContentSummary;
+  /** The resolved hero image, a derived projection of the frontmatter `image` field. `url` is the
+   *  root-relative delivery path for an `<img>`, `absoluteUrl` the origin-anchored form for the
+   *  og:image, and `alt`/`caption` carry from the stored object. The canonical token is untouched:
+   *  `entry.frontmatter.image.src` stays the `media:` token. Undefined when no hero is set, media is
+   *  off, the reference does not parse, or the resolver finds no asset. */
+  heroImage?: { url: string; absoluteUrl?: string; alt: string; caption?: string };
 }
 
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps: PublicRoutesDeps) {
-  const { site, render, origin, siteName, description, feeds, defaultImage } = deps;
+  const { site, render, origin, siteName, description, feeds, defaultImage, resolveMedia } = deps;
+
+  /** Derive the hero projection from an entry's frontmatter, without mutating it (locked decision 5).
+   *  The hero lives at the conventional `image` key as the validated nested object `{ src, alt, caption }`;
+   *  only an image field's validate arm produces an object-with-string-`src` shape, so detecting that
+   *  structure is enough (a text field stores a string, a tags field an array). Returns undefined when
+   *  media is off, no hero is set, the token does not parse, or the resolver finds no asset.
+   *
+   *  Scope: this resolves the `image` key, which is the back-compat SEO default the schema's `seo`
+   *  flag also defaults to. A concept that renames its hero (e.g. `cover`) with `seo: true` validates
+   *  and renders in the editor, but its delivery resolution is not wired here yet, since the field
+   *  declarations are not reachable in the delivery read path. Honoring a renamed `seo`-flagged field
+   *  (and a second image field per concept) at delivery is a carried follow-up; every consumer today
+   *  uses `image`. */
+  function deriveHeroImage(frontmatter: Record<string, unknown>): EntryData['heroImage'] {
+    if (!resolveMedia) return undefined;
+    const value = frontmatter.image;
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const obj = value as { src?: unknown; alt?: unknown; caption?: unknown };
+    if (typeof obj.src !== 'string' || obj.src === '') return undefined;
+    const ref = parseMediaToken(obj.src);
+    if (!ref) return undefined;
+    const path = resolveMedia(ref);
+    if (!path) return undefined;
+    const hero: NonNullable<EntryData['heroImage']> = {
+      url: path,
+      absoluteUrl: resolveImageUrl(path, origin),
+      alt: typeof obj.alt === 'string' ? obj.alt : '',
+    };
+    if (typeof obj.caption === 'string' && obj.caption !== '') hero.caption = obj.caption;
+    return hero;
+  }
 
   /** Resolve one concept's index by id, or a 404 (the route names an unconfigured concept). */
   function indexOf(conceptId: string) {
@@ -72,8 +115,13 @@ export function createPublicRoutes(deps: PublicRoutesDeps) {
     const { newer, older } = site.adjacent(entry);
     const canonicalUrl = origin + entry.permalink;
     const fields = readSeoFields(entry.frontmatter);
+    const heroImage = deriveHeroImage(entry.frontmatter);
+    // The SEO unify (locked decision 3): a resolved structured hero is the social card and wins over
+    // the back-compat string `image` field and the site default. A bare-string `image` keeps its
+    // origin-anchored behavior. An empty hero alt emits no twitter:image:alt.
     const rawImage = fields.image ?? defaultImage;
-    const image = rawImage ? resolveImageUrl(rawImage, origin) : undefined;
+    const image = heroImage?.absoluteUrl ?? (rawImage ? resolveImageUrl(rawImage, origin) : undefined);
+    const imageAlt = heroImage?.alt && heroImage.alt.trim() !== '' ? heroImage.alt : undefined;
     // A dated entry is an article; an undated one (a page) is a website.
     const seo = buildSeoMeta({
       title: entry.title,
@@ -84,11 +132,12 @@ export function createPublicRoutes(deps: PublicRoutesDeps) {
       ...(entry.date ? { published: entry.date } : {}),
       ...(entry.updated ? { modified: entry.updated } : {}),
       ...(image ? { image } : {}),
+      ...(imageAlt ? { imageAlt } : {}),
       ...(fields.robots ? { robots: fields.robots } : {}),
       ...(fields.author ? { author: fields.author } : {}),
       ...(entry.date ? { feeds } : {}),
     });
-    return { concept: entry.concept, entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older };
+    return { concept: entry.concept, entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older, ...(heroImage ? { heroImage } : {}) };
   }
 
   /** The chronological archive for one concept: every non-draft summary, newest-first. */