@glw907/cairn-cms 0.62.2 → 0.68.0

package/src/lib/content/field-rules.ts

@@ -0,0 +1,40 @@
+// cairn-cms: the shared field constraint rules. Both the v1 `defineFields` validator and the v2
+// `fieldset` validator call these pure helpers, so the two validators cannot drift on the
+// constraint wording or the first-failing-rule-wins order. No I/O and no clock reads, so the
+// rules stay deterministic on Workers.
+
+/** Compile a field pattern once, throwing a labeled error when the source is not a valid regex. */
+export function compilePattern(source: string, label: string): RegExp {
+  try {
+    return new RegExp(source);
+  } catch (cause) {
+    throw new Error(`cairn: field "${label}" has an invalid pattern: ${source}`, { cause });
+  }
+}
+
+/** Return the first string-length violation message, or null when the value satisfies the bounds. */
+export function stringLengthError(
+  value: string,
+  constraints: { min?: number; max?: number; length?: number },
+  label: string,
+): string | null {
+  const { min, max, length } = constraints;
+  if (min != null && value.length < min) return `${label} must be at least ${min} characters`;
+  if (max != null && value.length > max) return `${label} must be at most ${max} characters`;
+  if (length != null && value.length !== length) return `${label} must be exactly ${length} characters`;
+  return null;
+}
+
+/** Return the format violation message when a compiled pattern rejects the value, else null. */
+export function patternError(value: string, compiled: RegExp | undefined, label: string): string | null {
+  if (compiled && !compiled.test(value)) return `${label} is not in the expected format`;
+  return null;
+}
+
+/** Return the first date-bounds violation message, or null when the value is within the bounds. */
+export function dateBoundsError(value: string, constraints: { min?: string; max?: string }, label: string): string | null {
+  const { min, max } = constraints;
+  if (min != null && value < min) return `${label} must be on or after ${min}`;
+  if (max != null && value > max) return `${label} must be on or before ${max}`;
+  return null;
+}

package/src/lib/content/fields.ts

@@ -0,0 +1,127 @@
+/** The stored value of an image field; re-exported so this module owns the image shape too. */
+export type { ImageValue } from './types.js';
+
+/** Common to every field descriptor: the form label and the universal options. */
+export interface FieldBase {
+  /** Form label. */
+  label: string;
+  /** One author-facing sentence shown under the field. */
+  help?: string;
+  /** A required field fails validation when empty. */
+  required?: boolean;
+  /** Form-render-time initial value; a sentinel like "today" resolves at render (Task 9). */
+  default?: string | boolean;
+}
+/** A single-line text input. */
+export interface TextField extends FieldBase {
+  type: 'text';
+  min?: number; max?: number; length?: number;
+  /** A regular-expression source string the value must match. */
+  pattern?: string;
+}
+/** A multi-line text input. */
+export interface TextareaField extends FieldBase {
+  type: 'textarea';
+  rows?: number; min?: number; max?: number; length?: number; pattern?: string;
+}
+/** A numeric input. */
+export interface NumberField extends FieldBase {
+  type: 'number';
+  min?: number; max?: number;
+  /** Constrain the value to whole numbers. */
+  integer?: boolean;
+}
+/** A single-choice input over a closed option list. */
+export interface SelectField extends FieldBase {
+  type: 'select';
+  /** The closed set of allowed values. */
+  options: readonly string[];
+}
+/** A multiple-choice input. */
+export interface MultiselectField extends FieldBase {
+  type: 'multiselect';
+  /** The allowed values; omitted leaves the set open. */
+  options?: readonly string[];
+  /** Allow the author to add values not in the list. */
+  creatable?: boolean;
+  /** Mark the field as a site-wide taxonomy whose values pool across entries. */
+  taxonomy?: boolean;
+}
+/** A URL input whose format the validator enforces. */
+export interface UrlField extends FieldBase {
+  type: 'url';
+}
+/** An email-address input whose format the validator enforces. */
+export interface EmailField extends FieldBase {
+  type: 'email';
+}
+/** A calendar-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 date-and-time input. */
+export interface DatetimeField extends FieldBase {
+  type: 'datetime';
+  /** Earliest allowed moment as an ISO string. */
+  min?: string;
+  /** Latest allowed moment as an ISO string. */
+  max?: string;
+}
+/** A checkbox; absent means false. */
+export interface BooleanField extends FieldBase {
+  type: 'boolean';
+}
+/** A hero image whose stored value is the nested ImageValue object. */
+export interface ImageField extends FieldBase {
+  type: 'image';
+  /** Whether this field feeds the social-card image. */
+  seo?: boolean;
+}
+/** The plain-data descriptor union the form, validator, and inference all read. Grows per task. */
+export type FieldDescriptor =
+  | TextField
+  | TextareaField
+  | NumberField
+  | SelectField
+  | MultiselectField
+  | UrlField
+  | EmailField
+  | DateField
+  | DatetimeField
+  | BooleanField
+  | ImageField;
+
+/**
+ * The constructor namespace a concept declares its fields with. Each constructor captures its
+ * argument with a `const` type parameter and intersects it onto the descriptor, so the call-site
+ * literals (`required: true`, a `select`/`multiselect` `options` union) survive into the descriptor
+ * type for `Infer` to read. The runtime value is unchanged: still `{ type, ...o }`.
+ */
+export const fields = {
+  /** A single-line text field. */
+  text: <const O extends Omit<TextField, 'type'>>(o: O): TextField & O => ({ type: 'text', ...o }),
+  /** A multi-line text field. */
+  textarea: <const O extends Omit<TextareaField, 'type'>>(o: O): TextareaField & O => ({ type: 'textarea', ...o }),
+  /** A numeric field. */
+  number: <const O extends Omit<NumberField, 'type'>>(o: O): NumberField & O => ({ type: 'number', ...o }),
+  /** A single-choice field over a closed option list, preserving the literal option union. */
+  select: <const O extends Omit<SelectField, 'type'>>(o: O): SelectField & O => ({ type: 'select', ...o }),
+  /** A multiple-choice field, preserving the literal option union when one is given. */
+  multiselect: <const O extends Omit<MultiselectField, 'type'>>(o: O): MultiselectField & O => ({ type: 'multiselect', ...o }),
+  /** A URL field. */
+  url: <const O extends Omit<UrlField, 'type'>>(o: O): UrlField & O => ({ type: 'url', ...o }),
+  /** An email-address field. */
+  email: <const O extends Omit<EmailField, 'type'>>(o: O): EmailField & O => ({ type: 'email', ...o }),
+  /** A calendar-date field. */
+  date: <const O extends Omit<DateField, 'type'>>(o: O): DateField & O => ({ type: 'date', ...o }),
+  /** A date-and-time field. */
+  datetime: <const O extends Omit<DatetimeField, 'type'>>(o: O): DatetimeField & O => ({ type: 'datetime', ...o }),
+  /** A boolean checkbox field. */
+  boolean: <const O extends Omit<BooleanField, 'type'>>(o: O): BooleanField & O => ({ type: 'boolean', ...o }),
+  /** An image field whose value is the nested ImageValue object. */
+  image: <const O extends Omit<ImageField, 'type'>>(o: O): ImageField & O => ({ type: 'image', ...o }),
+};

package/src/lib/content/fieldset.ts

@@ -0,0 +1,307 @@
+// cairn-cms: the fieldset primitive (Contract v2). A key-to-descriptor record becomes a schema
+// carrying the descriptors as plain data, a server-derived validator, and the Standard Schema
+// conformance property. The validator coerces per type, drops an empty optional field, and returns
+// field-keyed errors or normalized data. This is the additive v2 path alongside `defineFields`; the
+// inferred-type and default-resolution arms land in later tasks, and the cutover is a later plan.
+import type { FieldDescriptor, ImageValue } from './fields.js';
+import type { ValidationResult } from './types.js';
+import type { StandardInput, StandardSchemaV1 } from './schema.js';
+import { dateInputValue, isCalendarDate } from './frontmatter.js';
+import { compilePattern, dateBoundsError, patternError, stringLengthError } from './field-rules.js';
+
+/** Accept any URL using http or https with a non-empty rest, mirroring the conservative form check. */
+const URL_RE = /^https?:\/\/\S+$/;
+/** Accept a single address conservatively: exactly one at-sign and a dotted domain, nothing more. */
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+/**
+ * The behavior table co-bundled with a fieldset, keyed by field name. It holds function-valued
+ *  behavior a descriptor cannot carry as plain data (a cross-field validator, an array itemLabel).
+ *  Scalars have no behavior, so the table is empty for now and reserved for later co-bundled functions.
+ */
+export type BehaviorTable = Record<string, never>;
+
+/**
+ * Options for `fieldset`. `refine` runs after the per-field coercion and constraints pass, for
+ *  cross-field and body-dependent checks. It is validation-only: it returns field-keyed errors to
+ *  merge, or nothing, and never transforms the data. Server-only, since it may carry closures.
+ */
+export interface FieldsetOptions {
+  refine?: (data: Record<string, unknown>, body: string) => Record<string, string> | undefined;
+}
+
+/**
+ * A concept's fieldset: the plain-data descriptors, the co-bundled behavior table, the server-derived
+ *  validator, and the Standard Schema conformance property.
+ */
+export interface Fieldset<R extends Record<string, FieldDescriptor> = Record<string, FieldDescriptor>> {
+  /** The declared descriptors as plain serializable data, for the editor form. */
+  readonly fields: R;
+  /** Function-valued behavior keyed by field name; empty for a scalar-only fieldset. */
+  readonly behavior: BehaviorTable;
+  /** Validate raw frontmatter, returning field-keyed errors or the normalized data. */
+  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+  /** Standard Schema v1 conformance, for ecosystem interop. A thin adapter over `validate`. */
+  readonly '~standard': StandardSchemaV1<StandardInput, Record<string, unknown>>['~standard'];
+}
+
+/**
+ * Map one field descriptor to the TS type of its normalized value. number is number, boolean is
+ *  boolean, image is the nested ImageValue object; a select with a literal option list is that
+ *  option union, a multiselect with one is that union array (else string[]); everything else is a
+ *  string.
+ */
+type ValueOf<D extends FieldDescriptor> = D extends { type: 'number' }
+  ? number
+  : D extends { type: 'boolean' }
+    ? boolean
+    : D extends { type: 'image' }
+      ? ImageValue
+      : D extends { type: 'select'; options: readonly (infer O extends string)[] }
+        ? O
+        : D extends { type: 'multiselect'; options: readonly (infer O extends string)[] }
+          ? O[]
+          : D extends { type: 'multiselect' }
+            ? string[]
+            : string;
+
+/** Flatten an intersection into a single readable object type. */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * The normalized frontmatter type inferred from a fieldset's descriptor record. A descriptor
+ *  declared `required: true` is a required key; every other descriptor is optional.
+ */
+type Infer<R extends Record<string, FieldDescriptor>> = Prettify<
+  { -readonly [K in keyof R as R[K] extends { required: true } ? K : never]: ValueOf<R[K]> } & {
+    -readonly [K in keyof R as R[K] extends { required: true } ? never : K]?: ValueOf<R[K]>;
+  }
+>;
+
+/** Extract the inferred frontmatter type from a `Fieldset`. */
+export type InferFieldset<S> = S extends Fieldset<infer R> ? Infer<R> : never;
+
+// Coerce one image value to the stored `{ src, alt, caption?, decorative? }` shape, ported from
+// validate.ts. Default a missing alt to empty (alt is debt, never a save block), trim and drop a
+// blank caption, keep decorative only when an explicit true, and drop the whole key when src is empty.
+// A required image with an empty src is the one error this arm raises.
+function coerceImage(
+  field: Extract<FieldDescriptor, { type: 'image' }>,
+  key: string,
+  value: unknown,
+  data: Record<string, unknown>,
+  errors: Record<string, string>,
+): void {
+  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;
+      if (obj.decorative === true) normalized.decorative = true;
+      data[key] = normalized;
+    }
+  }
+  if (field.required && src === '') errors[key] = `${field.label} is required`;
+}
+
+// Coerce a raw value to the trimmed string the empty check and constraints run on. A parsed value may
+// arrive from parseMarkdown, not only a form string: a Date on a date or datetime field, a JS number on
+// a number field. A finite 0 coerces to '0', never read as empty, since 0 is a real number a YAML scalar
+// carries; a NaN or non-finite number stays '' and routes to the number error in validateField.
+function coerceToText(type: FieldDescriptor['type'], value: unknown): string {
+  if (type === 'date' && value instanceof Date) return dateInputValue(value);
+  if (type === 'datetime' && value instanceof Date) return value.toISOString();
+  if (type === 'number' && typeof value === 'number' && Number.isFinite(value)) return String(value);
+  if (typeof value === 'string') return value.trim();
+  return '';
+}
+
+// Validate one descriptor against its raw value, writing into `data` or `errors`. Empty or absent is
+// "not provided" and is read BEFORE type coercion, uniformly: a required field errors, an optional
+// field drops (no key, no error). Only a non-empty value is coerced. boolean is the exception: true
+// stores true, anything else omits the key. number relies on the empty-first drop so an empty optional
+// number never becomes Number('') === 0.
+function validateField(
+  key: string,
+  field: FieldDescriptor,
+  value: unknown,
+  data: Record<string, unknown>,
+  errors: Record<string, string>,
+  patterns: Map<string, RegExp>,
+): void {
+  // boolean: presence is the value; an unchecked or absent box omits the key (no draft: false noise).
+  if (field.type === 'boolean') {
+    if (value === true) data[key] = true;
+    return;
+  }
+
+  // multiselect: a string array; drop empties, reject an unknown value when options is closed. An empty
+  // list omits the key (a required empty errors); the array path is the one non-string coercion. A lone
+  // non-empty scalar (a single tag a YAML scalar carries) coerces to a single-element list, rather than
+  // dropping to [] and reading as "required" while present. An empty string or a non-string-non-array
+  // stays the empty list.
+  if (field.type === 'multiselect') {
+    let raw: string[];
+    if (Array.isArray(value)) raw = value.map(String);
+    else if (typeof value === 'string' && value.trim() !== '') raw = [value.trim()];
+    else raw = [];
+    const list = raw.map((v) => v.trim()).filter((v) => v !== '');
+    if (field.required && list.length === 0) {
+      errors[key] = `${field.label} is required`;
+      return;
+    }
+    const { options } = field;
+    if (options) {
+      const unknown = list.find((v) => !options.includes(v));
+      if (unknown !== undefined) {
+        errors[key] = `${field.label} contains an unknown value: ${unknown}`;
+        return;
+      }
+    }
+    if (list.length > 0) data[key] = list;
+    return;
+  }
+
+  // image: the nested object arm, dropping the key on empty src.
+  if (field.type === 'image') {
+    coerceImage(field, key, value, data, errors);
+    return;
+  }
+
+  // Every other type is "not provided when empty" first, then coerced. `coerceToText` turns a parsed
+  // value into its string form BEFORE the empty check, so a real parsed value (a Date on a date or
+  // datetime field, a number on a number field) is not read as empty.
+  const text = coerceToText(field.type, value);
+  if (text === '') {
+    if (field.required) errors[key] = `${field.label} is required`;
+    return;
+  }
+
+  switch (field.type) {
+    case 'number': {
+      const n = Number(text);
+      // Reject NaN and the non-finite values Number() yields for "Infinity"/"1e400", which an
+      // isNaN check alone would pass through and commit as a YAML .inf scalar.
+      if (!Number.isFinite(n)) errors[key] = `${field.label} must be a number`;
+      else if (field.integer && !Number.isInteger(n)) errors[key] = `${field.label} must be a whole number`;
+      else if (field.min != null && n < field.min) errors[key] = `${field.label} must be at least ${field.min}`;
+      else if (field.max != null && n > field.max) errors[key] = `${field.label} must be at most ${field.max}`;
+      else data[key] = n;
+      break;
+    }
+    case 'select': {
+      if (!field.options.includes(text)) errors[key] = `${field.label} contains an unknown value: ${text}`;
+      else data[key] = text;
+      break;
+    }
+    case 'url': {
+      if (!URL_RE.test(text)) errors[key] = `${field.label} is not a valid URL`;
+      else data[key] = text;
+      break;
+    }
+    case 'email': {
+      if (!EMAIL_RE.test(text)) errors[key] = `${field.label} is not a valid email address`;
+      else data[key] = text;
+      break;
+    }
+    case 'date': {
+      if (!isCalendarDate(text)) {
+        errors[key] = `${field.label} must be a valid date (YYYY-MM-DD)`;
+        break;
+      }
+      const boundsError = dateBoundsError(text, field, field.label);
+      if (boundsError != null) {
+        errors[key] = boundsError;
+        break;
+      }
+      data[key] = text;
+      break;
+    }
+    default: {
+      // text, textarea, datetime: a trimmed non-empty string. text and textarea also enforce the
+      // string-length and pattern constraints (v1 parity); datetime stays a plain string for now,
+      // since its bounds are out of scope this pass and v1 has no datetime equivalent to match.
+      if (field.type === 'text' || field.type === 'textarea') {
+        const lengthError = stringLengthError(text, field, field.label);
+        if (lengthError != null) {
+          errors[key] = lengthError;
+          break;
+        }
+        const formatError = patternError(text, patterns.get(key), field.label);
+        if (formatError != null) {
+          errors[key] = formatError;
+          break;
+        }
+      }
+      data[key] = text;
+    }
+  }
+}
+
+/**
+ * Build a fieldset from a key-to-descriptor record. The returned schema carries the descriptors, a
+ *  server-derived validator that coerces per type and returns field-keyed errors or normalized data,
+ *  and the Standard Schema conformance property whose issues map each error to a single-segment path.
+ */
+export function fieldset<const R extends Record<string, FieldDescriptor>>(
+  record: R,
+  options: FieldsetOptions = {},
+): Fieldset<R> {
+  // Compile each text/textarea pattern once at construction, so a malformed pattern fails loudly here
+  // (mirroring v1's compilePatterns) rather than on every save. Keyed by field name for validateField.
+  const patterns = new Map<string, RegExp>();
+  for (const [key, field] of Object.entries(record)) {
+    if ((field.type === 'text' || field.type === 'textarea') && field.pattern != null) {
+      patterns.set(key, compilePattern(field.pattern, field.label));
+    }
+  }
+  const validate = (frontmatter: Record<string, unknown>, body: string): ValidationResult => {
+    const data: Record<string, unknown> = {};
+    const errors: Record<string, string> = {};
+    for (const [key, field] of Object.entries(record)) {
+      validateField(key, field, frontmatter[key], data, errors, patterns);
+    }
+    if (Object.keys(errors).length > 0) return { ok: false, errors };
+    const refined = options.refine?.(data, body);
+    return refined && Object.keys(refined).length > 0 ? { ok: false, errors: refined } : { ok: true, data };
+  };
+  const standard: StandardSchemaV1<StandardInput, Record<string, unknown>>['~standard'] = {
+    version: 1,
+    vendor: 'cairn',
+    validate: (value) => {
+      const { frontmatter = {}, body = '' } = (value ?? {}) as Partial<StandardInput>;
+      const result = validate(frontmatter ?? {}, body ?? '');
+      return result.ok
+        ? { value: result.data }
+        : { issues: Object.entries(result.errors).map(([key, message]) => ({ message, path: [key] })) };
+    },
+  };
+  return { fields: record, behavior: {}, validate, '~standard': standard };
+}
+
+/**
+ * Resolve each descriptor's `default` to a form-initial value, so a fresh entry opens prefilled. The
+ *  `'today'` sentinel on a date field resolves through the passed `now` to its `YYYY-MM-DD` form; an
+ *  empty-string or `false` default is omitted, so an untouched field commits no key (the
+ *  minimal-frontmatter invariant). With no `now`, a `'today'` default is omitted rather than read off
+ *  a real clock, since library code must stay deterministic and Workers-safe.
+ */
+export function initialValues(fieldset: Fieldset, now?: Date): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(fieldset.fields)) {
+    const value = field.default;
+    if (value === undefined || value === '' || value === false) continue;
+    if (field.type === 'date' && value === 'today') {
+      if (now) values[key] = now.toISOString().slice(0, 10);
+      continue;
+    }
+    values[key] = value;
+  }
+  return values;
+}

package/src/lib/content/schema.ts

@@ -2,6 +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 { compilePattern, dateBoundsError, patternError, stringLengthError } from './field-rules.js';
 import type { FrontmatterField, ImageValue, ValidationResult } from './types.js';
 import { validateFields } from './validate.js';
 
@@ -77,16 +78,15 @@ export type Infer<S> = S extends ConceptSchema<infer F> ? InferFields<F> : never
 function applyRules(field: FrontmatterField, value: unknown, errors: Record<string, string>, patterns: Map<string, RegExp>): void {
   if (typeof value !== 'string' || value === '') return;
   if (field.type === 'text' || field.type === 'textarea') {
-    if (field.min != null && value.length < field.min) errors[field.name] = `${field.label} must be at least ${field.min} characters`;
-    else if (field.max != null && value.length > field.max) errors[field.name] = `${field.label} must be at most ${field.max} characters`;
-    else if (field.length != null && value.length !== field.length) errors[field.name] = `${field.label} must be exactly ${field.length} characters`;
-    else if (field.pattern != null) {
-      const re = patterns.get(field.name);
-      if (re && !re.test(value)) errors[field.name] = `${field.label} is not in the expected format`;
+    const lengthError = stringLengthError(value, field, field.label);
+    if (lengthError != null) errors[field.name] = lengthError;
+    else {
+      const formatError = patternError(value, patterns.get(field.name), field.label);
+      if (formatError != null) errors[field.name] = formatError;
     }
   } else if (field.type === 'date') {
-    if (field.min != null && value < field.min) errors[field.name] = `${field.label} must be on or after ${field.min}`;
-    else if (field.max != null && value > field.max) errors[field.name] = `${field.label} must be on or before ${field.max}`;
+    const boundsError = dateBoundsError(value, field, field.label);
+    if (boundsError != null) errors[field.name] = boundsError;
   }
 }
 
@@ -105,11 +105,7 @@ function compilePatterns(fields: FrontmatterField[]): Map<string, RegExp> {
   const compiled = new Map<string, RegExp>();
   for (const field of fields) {
     if ((field.type === 'text' || field.type === 'textarea') && field.pattern != null) {
-      try {
-        compiled.set(field.name, new RegExp(field.pattern));
-      } catch (cause) {
-        throw new Error(`cairn: field "${field.name}" has an invalid pattern: ${field.pattern}`, { cause });
-      }
+      compiled.set(field.name, compilePattern(field.pattern, field.name));
     }
   }
   return compiled;

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

@@ -13,6 +13,7 @@ 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';
+import { log } from '../log/index.js';
 
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
@@ -36,6 +37,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. */
@@ -74,7 +83,16 @@ export interface EntryData {
 
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps: PublicRoutesDeps) {
-  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).

package/src/lib/index.ts

@@ -45,6 +45,13 @@ export {
 export { defineFields } from './content/schema.js';
 export { defineAdapter } from './content/adapter.js';
 export type { ConceptSchema, Infer, InferFields, DefineFieldsOptions, StandardInput, StandardSchemaV1 } from './content/schema.js';
+// The Contract v2 field vocabulary, additive beside `defineFields`. The individual *Field
+// interfaces and the bare `Infer` stay module-local: the old `FrontmatterField` model above
+// already exports those names, and the cutover plan frees them.
+export { fields } from './content/fields.js';
+export type { FieldDescriptor } from './content/fields.js';
+export { fieldset, initialValues } from './content/fieldset.js';
+export type { Fieldset, InferFieldset, FieldsetOptions, BehaviorTable } from './content/fieldset.js';
 export {
   isValidId,
   idFromFilename,

package/src/lib/log/events.ts

@@ -22,6 +22,7 @@ export type CairnLogEvent =
   | 'media.delivery_failed'
   | 'media.orphan_reconcile'
   | 'media.resolve_missing'
+  | 'media.resolver_absent'
   | 'media.deleted'
   | 'media.delete_blocked'
   | 'media.bulk_deleted'

package/src/lib/media/index.ts

@@ -8,6 +8,7 @@
 export { normalizeAssets, type ResolvedAssetConfig } from './config.js';
 export {
   parseMediaManifest,
+  readCommittedManifest,
   findByHash,
   upsertMediaEntry,
   removeMediaEntry,

package/src/lib/media/manifest.ts

@@ -38,6 +38,20 @@ export function parseMediaManifest(json: unknown): MediaManifest {
   return json as MediaManifest;
 }
 
+/**
+ * Read the committed media manifest from an `import.meta.glob` eager result, degrading a missing
+ *  file to an empty manifest. A static import of an absent `media.json` fails the Vite build before
+ *  any runtime degrade can run, so a fresh site with no manifest cannot build. A glob result is the
+ *  build-safe read: `import.meta.glob` returns `{}` when nothing matches rather than throwing, and
+ *  this helper extracts the single matched value and parses it, so a missing file reads a clean `{}`.
+ * @param globResult - The eager glob result for the committed manifest, an empty object when the
+ *  file is absent. The consumer passes
+ *  `import.meta.glob('<path-to-media.json>', { eager: true, import: 'default' })`.
+ */
+export function readCommittedManifest(globResult: Record<string, unknown>): MediaManifest {
+  return parseMediaManifest(Object.values(globResult)[0]);
+}
+
 /**
  * Validate one posted value as a MediaEntry, returning it narrowed or undefined. The trust boundary
  *  for an optimistic record the client re-posts: the upload action server-owned each field at