@glw907/cairn-cms 0.56.2 → 0.57.0

package/dist/components/media-upload-outcome.d.ts

@@ -0,0 +1,52 @@
+import type { MediaEntry } from '../media/manifest.js';
+import type { UploadResult } from '../sveltekit/content-routes.js';
+import type { IngestFailureKind } from './client-ingest.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;
+};
+/**
+ * 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 declare function uploadOutcome(envelope: UploadEnvelope): UploadOutcome;

package/dist/components/media-upload-outcome.js

@@ -0,0 +1,48 @@
+import { mediaToken } from '../media/reference.js';
+// 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 = {
+    '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) {
+    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/dist/content/compose.js

@@ -1,4 +1,5 @@
 import { resolveConcepts } from './concepts.js';
+import { normalizeAssets } from '../media/config.js';
 /**
  * Fold an adapter and any extensions into the composed runtime (seam 2). The per-concept URL policy
  * is derived from the site config, the same source the delivery path uses, so the runtime and
@@ -33,6 +34,8 @@ export function composeRuntime({ adapter, siteConfig, extensions = [] }) {
         navMenu: adapter.navMenu,
         preview: adapter.preview,
         assets: adapter.assets,
+        resolvedAssets: normalizeAssets(adapter.assets),
+        mediaManifestPath: adapter.mediaManifestPath ?? 'src/content/.cairn/media.json',
         adminPanels,
         fieldTypes,
     };

package/dist/content/frontmatter.js

@@ -23,6 +23,23 @@ export function frontmatterFromForm(fields, form) {
                         .filter(Boolean)),
                 ];
                 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 = {
+                    src,
+                    alt: String(form.get(`${field.name}.alt`) ?? ''),
+                };
+                const caption = String(form.get(`${field.name}.caption`) ?? '').trim();
+                if (caption !== '')
+                    value.caption = caption;
+                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/dist/content/manifest.d.ts

@@ -10,6 +10,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. */
 export interface Manifest {

package/dist/content/manifest.js

@@ -7,12 +7,16 @@ import { parseMarkdown } from './frontmatter.js';
 import { deriveExcerpt } from './excerpt.js';
 import { entryIdentity, asString } from './identity.js';
 import { extractCairnLinks } from './links.js';
+import { extractMediaRefs } from './media-refs.js';
 /** Build one manifest entry from a content file. Drafts are included and flagged. The id, date, and
  *  permalink come from entryIdentity, the same source content-index uses, so a cairn: link resolves to
  *  one URL whether the admin preview reads the manifest or the public build reads the content index. */
 export function manifestEntryFromFile(descriptor, file) {
     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,
@@ -24,6 +28,7 @@ export function manifestEntryFromFile(descriptor, file) {
         summary: deriveExcerpt(body, { description: asString(frontmatter.description) }) || undefined,
         draft: frontmatter.draft === true,
         links: extractCairnLinks(body),
+        ...(mediaRefs.length ? { mediaRefs } : {}),
     };
 }
 /** An empty manifest, the starting point when no committed file exists yet. */
@@ -45,6 +50,7 @@ export function serializeManifest(manifest) {
         ...(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`;
 }
@@ -74,10 +80,21 @@ export function parseManifest(raw) {
             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) {
+                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.
@@ -132,11 +149,34 @@ export function verifyManifest(built, committedRaw) {
     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 = {
+        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) +
         '\nRegenerate it (npm run cairn:manifest) and commit the result.');

package/dist/content/media-refs.d.ts

@@ -0,0 +1,7 @@
+import type { FrontmatterField } 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 declare function extractMediaRefs(frontmatter: Record<string, unknown>, body: string, fields: FrontmatterField[]): string[];

package/dist/content/media-refs.js

@@ -0,0 +1,52 @@
+// 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';
+/** 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, body, fields) {
+    const seen = new Set();
+    const hashes = [];
+    const add = (href) => {
+        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.src === 'string') {
+            add(value.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) => {
+        if (node.url)
+            add(node.url);
+    });
+    return hashes;
+}

package/dist/content/schema.d.ts

@@ -1,4 +1,4 @@
-import type { FrontmatterField, ValidationResult } from './types.js';
+import type { FrontmatterField, ImageValue, ValidationResult } from './types.js';
 /** The validate input the cairn adapter takes: the raw frontmatter and the body. */
 export interface StandardInput {
     frontmatter: Record<string, unknown>;
@@ -27,10 +27,13 @@ type StandardResult<Output> = {
     }>;
 };
 /** 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: 'image';
+} ? ImageValue : K extends {
     type: 'tags';
     options: readonly (infer O extends string)[];
 } ? O[] : K extends {

package/dist/content/schema.js

@@ -41,10 +41,27 @@ function compilePatterns(fields) {
     }
     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) {
+    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) {
+    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(fields, options = {}) {
     const list = [...fields];
     const patterns = compilePatterns(list);
+    checkSeoImageFields(list);
     const validate = (frontmatter, body) => {
         const base = validateFields(list, frontmatter);
         if (!base.ok)

package/dist/content/types.d.ts

@@ -3,6 +3,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 {
     /** Frontmatter key and form input name. */
@@ -63,11 +64,32 @@ export interface FreeTagsField extends FieldBase {
     placeholder?: string;
 }
 /**
- * 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`.
+ * 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 type FrontmatterField = TextField | TextareaField | DateField | BooleanField | TagsField | FreeTagsField;
+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. 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 | TextareaField | DateField | BooleanField | TagsField | 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;
+}
 /**
  * A validator's verdict. On success it carries the normalized frontmatter to commit; on
  * failure it carries field-keyed error messages (the empty key is a form-level error).
@@ -163,12 +185,28 @@ export interface PreviewConfig {
 /** The flat preview shape `editLoad` ships to the edit page: the top-level `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`. */
 export interface CairnAdapter {
@@ -185,14 +223,19 @@ 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. */
+     *  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. */
@@ -289,12 +332,20 @@ 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). */
+    /** 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/dist/content/validate.js

@@ -39,6 +39,33 @@ export function validateFields(fields, frontmatter) {
                     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;
+                    src = typeof obj.src === 'string' ? obj.src.trim() : '';
+                    if (src !== '') {
+                        const normalized = {
+                            src,
+                            alt: typeof obj.alt === 'string' ? obj.alt : '',
+                        };
+                        const caption = typeof obj.caption === 'string' ? obj.caption.trim() : '';
+                        if (caption !== '')
+                            normalized.caption = caption;
+                        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 === '')

package/dist/delivery/public-routes.d.ts

@@ -2,6 +2,7 @@ import type { ContentSummary, ContentEntry } from './content-index.js';
 import type { SiteResolver } from './site-resolver.js';
 import type { SeoMeta } from './seo.js';
 import type { LinkResolve } from '../content/links.js';
+import type { MediaResolve } from '../render/resolve-media.js';
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
     site: SiteResolver;
@@ -22,6 +23,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. */
 export interface ListData {
@@ -47,6 +52,17 @@ 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 declare function createPublicRoutes(deps: PublicRoutesDeps): {

package/dist/delivery/public-routes.js

@@ -7,9 +7,46 @@ import { error } from '@sveltejs/kit';
 import { buildSeoMeta } from './seo.js';
 import { readSeoFields, resolveImageUrl } from './seo-fields.js';
 import { buildLinkResolver } from './site-resolver.js';
+import { parseMediaToken } from '../media/reference.js';
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps) {
-    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) {
+        if (!resolveMedia)
+            return undefined;
+        const value = frontmatter.image;
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const obj = value;
+        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 = {
+            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) {
         const index = site.concept(conceptId);
@@ -25,8 +62,13 @@ export function createPublicRoutes(deps) {
         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,
@@ -37,11 +79,12 @@ export function createPublicRoutes(deps) {
             ...(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. */
     function archiveLoad(conceptId) {

package/dist/delivery/seo-fields.js

@@ -24,7 +24,13 @@ export function readSeoFields(frontmatter) {
  *  that path, per the WHATWG URL rules. */
 export function resolveImageUrl(image, origin) {
     try {
-        return new URL(image, origin).href;
+        const url = new URL(image, origin);
+        // Guard the unresolved-`media:`-token failure mode: `media:photo.<hash>` is a valid URL scheme,
+        // so `new URL(...).href` returns the token verbatim and it would otherwise ship as the og:image.
+        // Only an http or https result is a real social-card URL; anything else degrades to no image.
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return undefined;
+        return url.href;
     }
     catch {
         return undefined;