@glw907/cairn-cms 0.62.2 → 0.76.0

package/dist/content/reference-index.js

@@ -0,0 +1,95 @@
+import { PENDING_PREFIX, parsePendingBranch } from './pending.js';
+import { findConcept } from './concepts.js';
+import { isValidId, filenameFromId } from './ids.js';
+import { parseMarkdown } from './frontmatter.js';
+import { extractReferenceEdges } from './references.js';
+/** Append a row under its target pair key, creating the bucket on first use. */
+function push(index, key, entry) {
+    const rows = index.get(key);
+    if (rows)
+        rows.push(entry);
+    else
+        index.set(key, [entry]);
+}
+/**
+ * Build the pair-keyed reference index over main (from the manifest's per-entry references) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read. That tolerance is wrong for the rename and delete gates: a
+ * transient branch-read failure would make a still-referenced target look free. Pass `strict: true` to
+ * rethrow a branch failure so the caller fails closed. Pass `branches` to reuse a branch list the
+ * caller already has rather than listing them a second time.
+ */
+export async function buildReferenceIndex(backend, concepts, manifest, opts = {}) {
+    const index = new Map();
+    // The main arm: the manifest already carries each entry's reference edges, so this is a pure reverse
+    // map with no per-file read. The KEY is the edge's TARGET (concept, id); the ROW is the source entry.
+    for (const entry of manifest.entries) {
+        for (const edge of entry.references ?? []) {
+            push(index, `${edge.concept}/${edge.id}`, {
+                concept: entry.concept,
+                id: entry.id,
+                title: entry.title,
+                permalink: entry.permalink,
+                field: edge.field,
+                origin: { kind: 'published' },
+            });
+        }
+    }
+    // The branch arm: read each open cairn/* branch's one edited file. The path is derivable from the
+    // branch name, so no tree-listing is needed. The branch list is reused when the caller passes it.
+    const names = opts.branches ?? (await backend.listBranches(PENDING_PREFIX));
+    // Read the branches in parallel rather than one at a time, so the latency floor is one round trip
+    // instead of N. workerd self-throttles to 6 simultaneous outbound connections, so this batch and
+    // the load path's media-union and linker reads each stay under the limit; do NOT run this fan-out
+    // concurrently with those (a future combined safety gate must not wrap them in one Promise.all),
+    // since the merged fan-out would queue behind that throttle.
+    const perBranch = await Promise.all(names.map(async (name) => {
+        // Resolve the branch name to a configured entry with the same guard the branch tooling uses: a
+        // malformed name, an id that fails the slug rule (entry paths are built from it, so this is the
+        // path confinement), or a concept this site does not configure is skipped, no read attempted.
+        const ref = parsePendingBranch(name);
+        if (!ref || !isValidId(ref.id))
+            return [];
+        const concept = findConcept(concepts, ref.concept);
+        if (!concept)
+            return [];
+        const path = `${concept.dir}/${filenameFromId(ref.id)}`;
+        try {
+            const raw = await backend.readFile(path, name);
+            if (raw === null)
+                return []; // The file is absent on the branch: nothing to extract.
+            const { frontmatter } = parseMarkdown(raw);
+            const fmTitle = frontmatter.title;
+            const title = typeof fmTitle === 'string' && fmTitle.trim() ? fmTitle : ref.id;
+            const rows = [];
+            for (const edge of extractReferenceEdges(frontmatter, concept.fields)) {
+                rows.push({
+                    key: `${edge.concept}/${edge.id}`,
+                    entry: {
+                        concept: concept.id,
+                        id: ref.id,
+                        title,
+                        field: edge.field,
+                        origin: { kind: 'branch', branch: name },
+                    },
+                });
+            }
+            return rows;
+        }
+        catch (err) {
+            // In strict mode a branch failure fails the whole build so the gate can fail closed; otherwise
+            // degrade this one branch rather than sinking the screen.
+            if (opts.strict)
+                throw err;
+            return [];
+        }
+    }));
+    // Fold the per-branch rows back in, preserving the branch order so the index reads stably.
+    for (const rows of perBranch) {
+        for (const { key, entry } of rows)
+            push(index, key, entry);
+    }
+    return index;
+}

package/dist/content/references.d.ts

@@ -0,0 +1,40 @@
+import type { NamedField } from './types.js';
+/**
+ * One typed frontmatter edge from a content entry to a target entry: the `field` the edge was
+ *  declared on, the target's `concept`, and the target's permanent `id`. The manifest records these
+ *  per entry, the cross-branch index reverse-maps them, and the build verifies each one resolves.
+ */
+export interface ReferenceEdge {
+    /** The frontmatter key the edge was declared on. */
+    field: string;
+    /** The target's concept, taken from the field descriptor, never the value. */
+    concept: string;
+    /** The target's permanent id. */
+    id: string;
+}
+/**
+ * Read every reference edge a parsed entry declares against its concept's fields. A `reference` field
+ *  yields one edge from the shared canonicalizer; an `array` of `reference` yields one edge per
+ *  canonicalized element, with the target `concept` taken from the descriptor rather than the value so
+ *  a hand-edited file cannot misdirect an edge. Each id must pass `isValidId`, and edges are emitted in
+ *  field then array order with duplicates dropped. The value is coerced through `referenceIdsFromValue`,
+ *  never iterated directly: a lone scalar of an array field is one id, never a string walked
+ *  character by character into per-character garbage edges.
+ */
+export declare function extractReferenceEdges(frontmatter: Record<string, unknown>, fields: NamedField[]): ReferenceEdge[];
+/**
+ * Rewrite a token-bounded `oldId` to `newId` within one top-level frontmatter key's value, returning
+ * the source byte-for-byte identical apart from that substring. The key's line range is found with the
+ * colon-anchored `frontmatterKeyRange` (so `author` never matches `authored-by:`), and within each
+ * line only the value side, an inline `# comment` left intact, is scanned. The token boundary is
+ * `(?<![a-z0-9-])`/`(?![a-z0-9-])` rather than `\b`, since ids contain hyphens, so a substring id is
+ * not matched. A `newId` that would not reparse as a YAML string (`true`, `123`, a date-shaped
+ * `2026-01-02`) is written single-quoted, otherwise a raw substitution reparses as a boolean, number,
+ * or Date and `coerceToText`/`extractReferenceEdges` silently drop the edge. When the matched `oldId`
+ * is itself wrapped in an existing quote pair (the form serializeMarkdown commits a significant id in,
+ * `author: '123'`), the splice extends over both quote bytes so the self-quoting replacement does not
+ * nest a second pair into invalid `''true''`. A leading BOM, every
+ * `\r`, and a source with no frontmatter, an absent field, or a malformed `oldId`/`newId` are
+ * preserved unchanged. Pure and node-safe.
+ */
+export declare function rewriteFrontmatterReference(source: string, field: string, oldId: string, newId: string): string;

package/dist/content/standard-schema.d.ts

@@ -0,0 +1,30 @@
+/** The validate input the cairn adapter takes: the raw frontmatter and the body. */
+export interface StandardInput {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+/**
+ * A minimal local copy of the Standard Schema v1 interface (https://standardschema.dev), so the
+ *  schema is a drop-in where the ecosystem accepts a validator, with no runtime dependency.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey>;
+    }>;
+};
+export {};

package/dist/content/standard-schema.js

@@ -0,0 +1,4 @@
+// cairn-cms: the Standard Schema conformance types, shared by both the v1 schema and the v2
+// fieldset validators. They live here, apart from either validator, so the v2 `fieldset` keeps
+// importing them once the v1 `schema.ts` is removed at the Contract v2 cutover.
+export {};

package/dist/content/types.d.ts

@@ -1,95 +1,12 @@
 import type { ComponentRegistry } from '../render/registry.js';
 import type { IconSet } from '../render/glyph.js';
+import type { IslandRegistry } from '../islands/types.js';
+import type { BackendProvider } from '../github/backend.js';
 import type { DatePrefix } from './ids.js';
-import type { ConceptSchema } from './schema.js';
+import type { Fieldset } from './fieldset.js';
+import type { FieldDescriptor } from './fields.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. */
-    name: string;
-    /** Form label. */
-    label: string;
-    /** A required field fails validation when empty (spec §7.4). */
-    required?: boolean;
-    /**
-     * One author-facing sentence shown under the field in the editor, in plain end-user language.
-     * Optional; render nothing when absent. Not a validation rule.
-     */
-    description?: string;
-}
-/** A single-line text input. */
-export interface TextField extends FieldBase {
-    type: 'text';
-    /** Minimum character length of a non-empty value. */
-    min?: number;
-    /** Maximum character length. */
-    max?: number;
-    /** Exact required character length. */
-    length?: number;
-    /**
-     * A regular-expression source string the value must match. Stored as a string so the field
-     *  list stays plain serializable data; the validator compiles it.
-     */
-    pattern?: string;
-}
-/** A multi-line text input. */
-export interface TextareaField extends FieldBase {
-    type: 'textarea';
-    /** Visible rows; the editor picks a default when omitted. */
-    rows?: number;
-    /** Minimum character length of a non-empty value. */
-    min?: number;
-    /** Maximum character length. */
-    max?: number;
-    /** Exact required character length. */
-    length?: number;
-    /** A regular-expression source string the value must match. */
-    pattern?: string;
-}
-/** A `YYYY-MM-DD` date input. */
-export interface DateField extends FieldBase {
-    type: 'date';
-    /** Earliest allowed date, as `YYYY-MM-DD`. */
-    min?: string;
-    /** Latest allowed date, as `YYYY-MM-DD`. */
-    max?: string;
-}
-/** A checkbox; absent means false. */
-export interface BooleanField extends FieldBase {
-    type: 'boolean';
-}
-/** A closed-vocabulary tag set, rendered as checkboxes (ecnordic). */
-export interface TagsField extends FieldBase {
-    type: 'tags';
-    /** The controlled vocabulary. */
-    options: readonly string[];
-}
-/** Free-form tags, edited as one comma-separated input (907). */
-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. 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.
@@ -101,10 +18,18 @@ export interface ImageValue {
     /** An explicit decorative choice: an empty alt that is not debt. Omitted unless true. */
     decorative?: boolean;
 }
+/** One validation failure located by a path: a top-level key, then a row index and/or a leaf sub-key. */
+export interface ValidationIssue {
+    /** The path to the failing field, e.g. ['faq', 0, 'question'] or ['address', 'city'] or ['title']. */
+    path: (string | number)[];
+    /** The author-facing message, naming the field's label. */
+    message: 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).
- * Invalid input bounces to the form and never reaches git (spec §7.4).
+ * 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) and, additively, the
+ * located `issues` with multi-segment paths so the form can route a nested-container error to the
+ * right input. Invalid input bounces to the form and never reaches git (spec §7.4).
  */
 export type ValidationResult = {
     ok: true;
@@ -112,48 +37,58 @@ export type ValidationResult = {
 } | {
     ok: false;
     errors: Record<string, string>;
+    issues?: ValidationIssue[];
+};
+/**
+ * A field descriptor with its frontmatter key re-attached as `name`. This is the normalized form
+ *  `ConceptDescriptor.fields` carries: `normalizeConcepts` derives it from a concept's `fieldset`
+ *  record so every consumer (the editor form, the form decoder, the media extractor) iterates an
+ *  array and reads `name` rather than the keyed record.
+ */
+export type NamedField = FieldDescriptor & {
+    name: string;
 };
 /**
- * Per-site configuration for one content concept (spec §8). One `schema`, built with
- * `defineFields`, is the single source of truth for the editor form, the validator, and the
- * inferred frontmatter type. Generic over the schema so a concept's concrete type survives for
- * typed reads. Concept-fixed behavior such as routability is not here; it lives in the engine's
- * routing table (`CONCEPT_ROUTING`).
+ * Per-site configuration for one content concept (spec §8). One `fields` fieldset, built with
+ * `fieldset`, is the single source of truth for the editor form, the validator, and the
+ * inferred frontmatter type. Generic over the fieldset so a concept's concrete type survives for
+ * typed reads. A concept also declares its own routing and URL policy here (`routing`, `permalink`,
+ * `datePrefix`), resolved by `normalizeConcepts`.
  */
-export interface ConceptConfig<S extends ConceptSchema = ConceptSchema> {
+export interface ConceptConfig<S extends Fieldset = Fieldset> {
     /** Repo-relative content directory, e.g. "src/content/posts". */
     dir: string;
     /** Sidebar label; defaults from the concept id when omitted. */
     label?: string;
     /** The singular noun for the create affordances ("New post"); defaults to `label` when omitted. */
     singular?: string;
-    /** The concept's schema: the form projection, the generated validator, and the inferred type. */
-    schema: S;
+    /** The concept's fieldset: the form projection, the generated validator, and the inferred type. */
+    fields: S;
+    /**
+     * This concept's routing. A named shorthand (`'feed'` dated and in feeds, `'page'` a routable
+     *  static page, `'embedded'` not routable) or an explicit rule. Omitted means `'page'`.
+     */
+    routing?: 'feed' | 'page' | 'embedded' | RoutingRule;
+    /** The permalink pattern, root-relative, e.g. `/blog/:year/:slug`. Defaults by concept id. */
+    permalink?: string;
+    /** Date-prefix granularity for a dated concept's id-to-slug stripping. Defaults to `day`. */
+    datePrefix?: DatePrefix;
     /**
      * Frontmatter keys to surface on each `ContentSummary.fields`, so a list card reads an authored
-     *  field without a per-entry detail read. Each key should also be declared in `schema`.
+     *  field without a per-entry detail read. Each key should also be declared in `fields`.
      */
     summaryFields?: string[];
 }
 /**
- * A concept's URL policy, set per concept in the YAML site-config (not the adapter). `permalink` is
- * a `/`-prefixed pattern of literal segments and the tokens `:slug`, `:year`, `:month`, `:day`.
- * `datePrefix` is the filename date-prefix granularity for a dated concept. Both default in
- * `normalizeConcepts` when omitted.
+ * A concept's URL policy, declared on the adapter concept itself (`ConceptConfig.permalink` and
+ * `ConceptConfig.datePrefix`) since Contract v2. `permalink` is a `/`-prefixed pattern of literal
+ * segments and the tokens `:slug`, `:year`, `:month`, `:day`. `datePrefix` is the filename
+ * date-prefix granularity for a dated concept. Both default in `normalizeConcepts` when omitted.
  */
 export interface ConceptUrlPolicy {
     permalink?: string;
     datePrefix?: DatePrefix;
 }
-/** The GitHub App backend a site reads from and commits to (spec §8). Plain data the GitHub engine (Plan 03) consumes. */
-export interface BackendConfig {
-    owner: string;
-    repo: string;
-    /** Commit target, e.g. "main". */
-    branch: string;
-    appId: string;
-    installationId: string;
-}
 /** Magic-link sender identity for Cloudflare Email Sending. */
 export interface SenderConfig {
     from: string;
@@ -233,64 +168,72 @@ export interface AssetConfig {
      */
     transformations?: boolean;
 }
-/** The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`. */
+/**
+ * The site's one renderer (design decision 4): the editor preview and every public page call it.
+ *  Entry-aware so a custom renderer can vary output by concept or frontmatter; the default reads only
+ *  `body` plus the resolvers. `resolve` rewrites cairn: links to live permalinks (the build passes a
+ *  site-resolver-backed resolver, the preview a manifest-backed one); `resolveMedia` resolves media:
+ *  references the same way. `concept` and `frontmatter` carry the entry's context for an entry render
+ *  and are absent for the standalone component-insert preview.
+ */
+export type SiteRender = (input: {
+    body: string;
+    concept?: string;
+    frontmatter?: Record<string, unknown>;
+    resolve?: LinkResolve;
+    resolveMedia?: import('../render/resolve-media.js').MediaResolve;
+}) => Promise<string>;
+/**
+ * The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`, in six
+ * subsystem groups (spec §8): the content concepts, the commit backend, the magic-link sender, the
+ * render subsystem, the optional media stack, and the admin-experience knobs. The internal manifest
+ * and dictionary paths are not here; `composeRuntime` defaults them by convention.
+ */
 export interface CairnAdapter {
-    siteName: string;
-    /**
-     * Which content concepts this site enables. A future `fragments?` key attaches here with
-     * no reshape of the contract (seam 1). A site never has two of the same concept.
-     */
-    content: {
-        posts?: ConceptConfig;
-        pages?: ConceptConfig;
+    /** The site's concepts, keyed by id. Posts and pages are the documented defaults; a site may add more. */
+    content: Record<string, ConceptConfig>;
+    /** The commit backend provider, from `githubApp({ ... })` (the GitHub App today). */
+    backend: BackendProvider;
+    /** The magic-link sender. */
+    email: SenderConfig;
+    /** The render subsystem: the one renderer, its directive vocabulary, and its icons. */
+    rendering: {
+        /**
+         * The one renderer the editor preview and every public page call (design decision 4). `resolve`
+         *  rewrites cairn: links to live permalinks; the build passes a site-resolver-backed one, the
+         *  preview a manifest one. `resolveMedia` resolves media: references the same way.
+         */
+        render: SiteRender;
+        /** Directive component registry; the renderer and the insert palette derive from it (seam 3). */
+        components?: ComponentRegistry;
+        /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
+        icons?: IconSet;
+        /**
+         * The live Svelte components for hydrated directives, keyed by directive name (phase 4b islands).
+         *  Every component whose {@link ComponentDef.hydrate} is set needs an entry here, and every entry
+         *  needs a matching `hydrate` component; `defineAdapter` checks both. Absent leaves the site
+         *  static, and the island client runtime is never imported.
+         */
+        islands?: IslandRegistry;
+    };
+    /** R2-backed media (seam 4): the bucket binding and image variants. Absent leaves media off. */
+    media?: AssetConfig;
+    /** Admin-experience knobs: the preview frame, the nav menu, and the editor support contact. */
+    editor?: {
+        /**
+         * The live site's content styling for the preview frame. The admin's chrome isolation keeps
+         *  the site's CSS out of the admin document, so the preview frame links these instead.
+         */
+        preview?: PreviewConfig;
+        /** Which git-committed YAML menu the nav editor manages. */
+        nav?: NavMenuConfig;
+        /**
+         * Optional contact a stuck editor is pointed to from the in-admin help (an email address, a URL,
+         *  or a name and instruction). The help renders the hand-off only when this is set. Plain string,
+         *  passed through verbatim.
+         */
+        supportContact?: string;
     };
-    backend: BackendConfig;
-    sender: SenderConfig;
-    /**
-     * Optional contact a stuck editor is pointed to from the in-admin help (an email address, a URL,
-     *  or a name and instruction). The help renders the hand-off only when this is set. Plain string,
-     *  passed through verbatim.
-     */
-    supportContact?: string;
-    /**
-     * 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. 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;
-    /**
-     * Repo-relative path to the committed personal dictionary file. Defaults to
-     *  src/content/.cairn/dictionary.txt, applied in composeRuntime: the same `.cairn/` content root the
-     *  manifests use, so the spec's `content/.cairn/dictionary.txt` resolves the same configurable way the
-     *  manifest paths do. One word per line, sorted, comment lines allowed (see site-dictionary.ts).
-     */
-    dictionaryPath?: 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. */
-    icons?: IconSet;
-    navMenu?: NavMenuConfig;
-    /**
-     * The live site's content styling for the preview frame. The admin's chrome isolation keeps
-     *  the site's CSS out of the admin document, so the preview frame links these instead.
-     */
-    preview?: PreviewConfig;
-    assets?: AssetConfig;
 }
 /**
  * Concept-fixed routing for a normalized concept (spec §7.2). Posts are dated feed entries;
@@ -323,7 +266,17 @@ export interface ConceptDescriptor {
     permalink: string;
     /** Filename date-prefix granularity for a dated concept; resolved by `normalizeConcepts`. */
     datePrefix: DatePrefix;
-    fields: FrontmatterField[];
+    /**
+     * The concept's fields in normalized form: each descriptor with its record key re-attached as
+     *  `name`, derived by `normalizeConcepts` from the concept's `fieldset` record. Every consumer
+     *  (the editor form, the form decoder, the media extractor) iterates this array and reads `name`.
+     */
+    fields: NamedField[];
+    /**
+     * The concept's source fieldset, carried through so `editLoad` can resolve a create-form's
+     *  initial values (a `default: 'today'` date) against a request-time clock via `initialValues`.
+     */
+    schema: Fieldset;
     /**
      * Frontmatter keys the index copies onto each summary's `fields` record. `normalizeConcepts`
      *  resolves it to `[]` when a concept omits `summaryFields`.
@@ -380,20 +333,17 @@ export interface CairnExtension {
 export interface CairnRuntime {
     siteName: string;
     concepts: ConceptDescriptor[];
-    backend: BackendConfig;
+    /** The commit backend provider, carried through from the adapter by `composeRuntime`. */
+    backend: BackendProvider;
     sender: SenderConfig;
     /** The support contact passed through from the adapter; the in-admin help reads it. Optional. */
     supportContact?: 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.
+     *  The build passes a site-resolver-backed `resolve`/`resolveMedia` pair, the preview manifest-backed
+     *  ones.
      */
-    render(md: string, opts?: {
-        stagger?: boolean;
-        resolve?: LinkResolve;
-        resolveMedia?: import('../render/resolve-media.js').MediaResolve;
-    }): string | Promise<string>;
+    render: SiteRender;
     manifestPath: string;
     /** The repo-relative path to the committed media manifest, defaulted in composeRuntime. */
     mediaManifestPath: string;
@@ -440,4 +390,3 @@ export interface CairnRuntime {
     /** Field types contributed by extensions (Mode 2). Empty until Plan 09 wires the form dispatch. */
     fieldTypes?: FieldTypeDef[];
 }
-export {};

package/dist/delivery/data.d.ts

@@ -1,7 +1,7 @@
 export { createContentIndex, fromGlob } from './content-index.js';
 export type { RawFile, ContentSummary, ContentEntry, ContentIndex, ContentProblem } from './content-index.js';
-export { createSiteResolver, buildLinkResolver } from './site-resolver.js';
-export type { SiteResolver, ConceptIndex } from './site-resolver.js';
+export { createSiteResolver, buildLinkResolver, resolveReferences } from './site-resolver.js';
+export type { SiteResolver, ConceptIndex, ResolvedReference } from './site-resolver.js';
 export { createSiteIndexes } from './site-indexes.js';
 export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';

package/dist/delivery/data.js

@@ -2,7 +2,7 @@
 // projections a SvelteKit site or a plain-Node tool reads, with no @sveltejs/kit and no .svelte in
 // the graph. The full ./delivery barrel re-exports this and adds the route loaders.
 export { createContentIndex, fromGlob } from './content-index.js';
-export { createSiteResolver, buildLinkResolver } from './site-resolver.js';
+export { createSiteResolver, buildLinkResolver, resolveReferences } from './site-resolver.js';
 export { createSiteIndexes } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';
 export { deriveExcerpt, wordCount } from '../content/excerpt.js';

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

@@ -1,15 +1,12 @@
 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 { SiteRender } from '../content/types.js';
 import type { MediaResolve } from '../render/resolve-media.js';
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
     site: SiteResolver;
-    render: (md: string, opts?: {
-        stagger?: boolean;
-        resolve?: LinkResolve;
-    }) => string | Promise<string>;
+    render: SiteRender;
     origin: string;
     /** Site name for og:site_name and the SEO head. */
     siteName: string;
@@ -31,6 +28,14 @@ export interface PublicRoutesDeps {
      *  media is off and no `heroImage` projection is derived.
      */
     resolveMedia?: MediaResolve;
+    /**
+     * Whether the site configured media on, read from `runtime.resolvedAssets.enabled`. It exists only
+     *  to diagnose a forgotten wire-point: media on but no `resolveMedia` reached this factory, which
+     *  renders public hero and body images as bare `media:` tokens. When true and `resolveMedia` is
+     *  absent, the factory emits `media.resolver_absent` once at construction. It does not change
+     *  resolution; `resolveMedia` alone still gates the hero projection.
+     */
+    assetsEnabled?: boolean;
 }
 /** The archive and tag list data: summaries the template renders. */
 export interface ListData {

package/dist/delivery/public-routes.js

@@ -8,9 +8,18 @@ import { buildSeoMeta } from './seo.js';
 import { readSeoFields, resolveImageUrl } from './seo-fields.js';
 import { buildLinkResolver } from './site-resolver.js';
 import { parseMediaToken } from '../media/reference.js';
+import { log } from '../log/index.js';
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps) {
-    const { site, render, origin, siteName, description, feeds, defaultImage, resolveMedia } = deps;
+    const { site, render, origin, siteName, description, feeds, defaultImage, resolveMedia, assetsEnabled } = deps;
+    // Diagnose a forgotten wire-point: media is configured on but no resolver reached this factory, so
+    // every public hero and body `media:` token renders bare (the ecxc 0.57.0 finding). The condition
+    // is a property of the wiring, not of any one load, so it is checked once here at construction
+    // rather than per entryLoad or per image, which keeps the warning loud-once and out of the
+    // prerender hot path. Resolution is unchanged; resolveMedia alone still gates the hero projection.
+    if (assetsEnabled && !resolveMedia) {
+        log.warn('media.resolver_absent', { enabled: true });
+    }
     /**
      * 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 }`;
@@ -86,7 +95,21 @@ export function createPublicRoutes(deps) {
             ...(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, ...(heroImage ? { heroImage } : {}) };
+        return {
+            concept: entry.concept,
+            entry,
+            html: await render({
+                body: entry.body,
+                concept: entry.concept,
+                frontmatter: entry.frontmatter,
+                resolve: buildLinkResolver(site),
+            }),
+            canonicalUrl,
+            seo,
+            newer,
+            older,
+            ...(heroImage ? { heroImage } : {}),
+        };
     }
     /** The chronological archive for one concept: every non-draft summary, newest-first. */
     function archiveLoad(conceptId) {