@glw907/cairn-cms 0.11.0 → 0.17.0

package/src/lib/components/EditPage.svelte

@@ -12,14 +12,13 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
   import type { IconSet } from '../render/glyph.js';
   import type { EditData } from '../sveltekit/content-routes.js';
   import type { TextareaField, TagsField, FreeTagsField } from '../content/types.js';
-  import { sanitizePreviewHtml } from '../render/sanitize.js';
 
   interface Props {
     /** The edit load's data, plus the site name for the heading. */
     data: EditData & { siteName: string };
     /** The site's component registry, for the insert palette. */
     registry?: ComponentRegistry;
-    /** The site's design-accurate render pipeline; the preview pane sanitizes its output. */
+    /** The site's design-accurate render pipeline; the preview pane renders its output, which the floored pipeline already sanitized. */
     render?: (md: string, opts?: { stagger?: boolean }) => string | Promise<string>;
     /** The site's icon set, for the guided form's icon fields. */
     icons?: IconSet;
@@ -46,8 +45,8 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
     localStorage.setItem(PREVIEW_KEY, showPreview ? '1' : '0');
   }
 
-  // Render the design-accurate preview as the body changes, debounced, and sanitize before the DOM.
-  // The sanitize is the one barrier between editor-authored markdown and the page (the editor is unsanitized).
+  // Render the design-accurate preview as the body changes, debounced. The site's render is the
+  // floored engine pipeline, so its output is already sanitized; the preview mirrors the page.
   // previewRun is a plain counter (not reactive state) used as a latest-wins guard: if a slow earlier
   // async render call resolves after a newer one has started, the stale result is discarded.
   let previewRun = 0;
@@ -58,8 +57,7 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
     const handle = setTimeout(async () => {
       try {
         const html = await render(md);
-        const safe = await sanitizePreviewHtml(html);
-        if (run === previewRun) previewHtml = safe;
+        if (run === previewRun) previewHtml = html;
       } catch {
         if (run === previewRun) previewHtml = '';
       }

package/src/lib/components/IconPicker.svelte

@@ -1,10 +1,13 @@
 <!--
 @component
-A visual icon choice over the site's IconSet. Each glyph is a toggle button; the selected one carries
-aria-pressed. When the field is optional, a None button clears the value. The glyph renders inline from
-the IconSet path data, matching the renderer's 256-unit viewBox.
+A visual icon choice over the site's IconSet. The choices form a radiogroup; each glyph is a radio
+button carrying aria-checked, and the selected one carries btn-primary for the visible state. When the
+field is optional, a None radio clears the value. A roving tabindex keeps a single tab stop and arrow
+keys move the selection, the standard radiogroup keyboard model. The glyph renders inline from the
+IconSet path data, matching the renderer's 256-unit viewBox.
 -->
 <script lang="ts">
+  import { tick } from 'svelte';
   import type { IconSet } from '../render/glyph.js';
 
   interface Props {
@@ -16,20 +19,60 @@ the IconSet path data, matching the renderer's 256-unit viewBox.
     required: boolean;
     /** Called with the new glyph name (or '' for none). */
     onChange: (name: string) => void;
+    /** The group's accessible name, threaded from the field label. Defaults to Icon. */
+    label?: string;
   }
 
-  let { icons, value, required, onChange }: Props = $props();
+  let { icons, value, required, onChange, label = 'Icon' }: Props = $props();
+
+  // The radiogroup container, used to move focus with the selection per the ARIA radiogroup pattern.
+  let group: HTMLDivElement;
 
   const names = $derived(Object.keys(icons));
+  // The selectable keys in DOM order: the optional None choice ('') first, then each glyph name.
+  // Arrow-key navigation walks this list, and the roving tabindex marks the selected key (or the
+  // first key when nothing is selected) as the single tab stop.
+  const choices = $derived(required ? names : ['', ...names]);
+  const tabStop = $derived(choices.includes(value) ? value : choices[0]);
+
+  function move(delta: number): void {
+    // Navigate relative to the focused element (the current tab stop), not the bound value. In a
+    // required group with no value, tabStop is the first radio while value is '', so a value-based
+    // origin would skip the first step.
+    const from = Math.max(0, choices.indexOf(tabStop));
+    const next = (from + delta + choices.length) % choices.length;
+    onChange(choices[next]);
+    // The roving tabindex updates reactively, so wait for the DOM then move focus onto the new tab
+    // stop. The keydown handler runs only when focus is already inside the group, so this never
+    // steals focus on mount.
+    void tick().then(() => {
+      const target = group?.querySelector<HTMLElement>('[tabindex="0"]');
+      target?.focus();
+    });
+  }
+
+  function onKeydown(e: KeyboardEvent): void {
+    if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
+      e.preventDefault();
+      move(1);
+    } else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
+      e.preventDefault();
+      move(-1);
+    }
+  }
 </script>
 
-<div class="flex flex-wrap gap-2" role="group" aria-label="Icon">
+<div class="flex flex-wrap gap-2" role="radiogroup" aria-label={label} bind:this={group}>
   {#if !required}
     <button
       type="button"
       class="btn btn-sm"
       class:btn-primary={value === ''}
-      aria-pressed={value === ''}
+      role="radio"
+      aria-checked={value === ''}
+      aria-label="None"
+      tabindex={tabStop === '' ? 0 : -1}
+      onkeydown={onKeydown}
       onclick={() => onChange('')}
     >None</button>
   {/if}
@@ -38,8 +81,11 @@ the IconSet path data, matching the renderer's 256-unit viewBox.
       type="button"
       class="btn btn-sm gap-1"
       class:btn-primary={value === name}
-      aria-pressed={value === name}
+      role="radio"
+      aria-checked={value === name}
       aria-label={name}
+      tabindex={tabStop === name ? 0 : -1}
+      onkeydown={onKeydown}
       onclick={() => onChange(name)}
     >
       <svg class="ec-glyph" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true" width="16" height="16">

package/src/lib/content/adapter.ts

@@ -0,0 +1,10 @@
+// cairn-cms: the adapter-authoring helper. A plain `const adapter: CairnAdapter = {...}` annotation
+// widens each concept's schema type away and breaks typed reads. defineAdapter captures the adapter
+// through a `const` type parameter, so each concept's concrete ConceptSchema<F> survives for the
+// full-auto typed reads in createSiteIndexes, while still checking the adapter against the contract.
+import type { CairnAdapter } from './types.js';
+
+/** Declare a site's adapter while preserving each concept's concrete schema type for typed reads. */
+export function defineAdapter<const A extends CairnAdapter>(adapter: A): A {
+  return adapter;
+}

package/src/lib/content/concepts.ts

@@ -51,8 +51,8 @@ export function normalizeConcepts(
       routing: routing[id] ?? DEFAULT_ROUTING,
       permalink: policy.permalink ?? defaultPermalink(id),
       datePrefix: policy.datePrefix ?? 'day',
-      fields: config.fields,
-      validate: config.validate,
+      fields: config.schema.fields,
+      validate: config.schema.validate,
     });
   }
   return descriptors;

package/src/lib/content/schema.ts

@@ -0,0 +1,133 @@
+// cairn-cms: the concept schema primitive (schema-source-of-truth design). One field
+// declaration yields a plain-data field projection for the editor form, a generated validator,
+// and an inferred frontmatter type. Plan 1 builds the additive primitive; the adapter-contract
+// cutover and the typed reads are Plan 2.
+import type { FrontmatterField, ValidationResult } from './types.js';
+import { validateFields } from './validate.js';
+
+/** 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> }> };
+
+/** 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. */
+type FieldValue<K extends FrontmatterField> = K extends { type: 'boolean' }
+  ? boolean
+  : K extends { type: 'tags'; options: readonly (infer O extends string)[] }
+    ? O[]
+    : K extends { type: 'tags' | 'freetags' }
+      ? string[]
+      : string;
+
+/** 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 field tuple. A field declared
+ *  `required: true` is a required key; every other field is optional. */
+export type InferFields<F extends readonly FrontmatterField[]> = Prettify<
+  { [K in F[number] as K extends { required: true } ? K['name'] : never]: FieldValue<K> } & {
+    [K in F[number] as K extends { required: true } ? never : K['name']]?: FieldValue<K>;
+  }
+>;
+
+/** A concept's schema: the plain-data field projection, the generated validator, and the
+ *  Standard Schema conformance property. */
+export interface ConceptSchema<F extends readonly FrontmatterField[] = readonly FrontmatterField[]> {
+  /** The declared fields as plain serializable data, for the editor form. */
+  readonly fields: FrontmatterField[];
+  /** 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, InferFields<F>>['~standard'];
+}
+
+/** Extract the inferred frontmatter type from a `ConceptSchema`. */
+export type Infer<S> = S extends ConceptSchema<infer F> ? InferFields<F> : never;
+
+// Enforce the declarative per-field rules on an already-coerced value. Rules run only on a
+// present, non-empty string value, so an absent optional field is never flagged. The first
+// failing rule per field wins, so the author sees one clear message at a time.
+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`;
+    }
+  } 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}`;
+  }
+}
+
+/** Options for `defineFields`. `refine` runs after the per-field rules 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. */
+export interface DefineFieldsOptions<F extends readonly FrontmatterField[]> {
+  refine?: (data: InferFields<F>, body: string) => Record<string, string> | undefined;
+}
+
+// Compile each declared text/textarea pattern once, so a malformed pattern fails loudly at
+// declaration (a site config error) instead of throwing from inside validate() on every save.
+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 });
+      }
+    }
+  }
+  return compiled;
+}
+
+/** Declare a concept's fields once. Returns the schema's faces derived from that one declaration. */
+export function defineFields<const F extends readonly FrontmatterField[]>(
+  fields: F,
+  options: DefineFieldsOptions<F> = {},
+): ConceptSchema<F> {
+  const list = [...fields] as FrontmatterField[];
+  const patterns = compilePatterns(list);
+  const validate = (frontmatter: Record<string, unknown>, body: string): ValidationResult => {
+    const base = validateFields(list, frontmatter);
+    if (!base.ok) return base;
+    const errors: Record<string, string> = {};
+    for (const field of list) applyRules(field, base.data[field.name], errors, patterns);
+    if (Object.keys(errors).length > 0) return { ok: false, errors };
+    const refined = options.refine?.(base.data as InferFields<F>, body);
+    return refined && Object.keys(refined).length > 0 ? { ok: false, errors: refined } : base;
+  };
+  const standard: StandardSchemaV1<StandardInput, InferFields<F>>['~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 as InferFields<F> }
+        : { issues: Object.entries(result.errors).map(([field, message]) => ({ message, path: [field] })) };
+    },
+  };
+  return { fields: list, validate, '~standard': standard };
+}

package/src/lib/content/types.ts

@@ -10,6 +10,7 @@
 import type { ComponentRegistry } from '../render/registry.js';
 import type { IconSet } from '../render/glyph.js';
 import type { DatePrefix } from './ids.js';
+import type { ConceptSchema } from './schema.js';
 
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
 interface FieldBase {
@@ -24,16 +25,37 @@ interface FieldBase {
 /** 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 {
@@ -74,18 +96,19 @@ export type ValidationResult =
   | { ok: false; errors: Record<string, string> };
 
 /**
- * Per-site configuration for one content concept (spec §8). 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 `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`).
  */
-export interface ConceptConfig {
+export interface ConceptConfig<S extends ConceptSchema = ConceptSchema> {
   /** Repo-relative content directory, e.g. "src/content/posts". */
   dir: string;
   /** Sidebar label; defaults from the concept id when omitted. */
   label?: string;
-  /** Drives the per-concept frontmatter form, in order. */
-  fields: FrontmatterField[];
-  /** Validate submitted frontmatter before any commit. */
-  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+  /** The concept's schema: the form projection, the generated validator, and the inferred type. */
+  schema: S;
 }
 
 /**

package/src/lib/content/validate.ts

@@ -7,9 +7,11 @@ import { dateInputValue } from './frontmatter.js';
 
 /**
  * Validate raw frontmatter against a field list. Required text and date fields must be
- * non-empty; required tag fields must be non-empty lists. Booleans coerce to `true`/`false`
- * and tag fields to string arrays. Returns the normalized data, or field-keyed errors when
- * any required field is empty.
+ * non-empty; required tag fields must be non-empty lists. A present boolean coerces to `true`
+ * and an unchecked one is omitted; a present tag field coerces to a string array and an empty
+ * one is omitted; an empty optional text or date field is omitted, so the normalized data
+ * carries only meaningful values and committed frontmatter stays minimal. Returns the
+ * normalized data, or field-keyed errors when any required field is empty.
  *
  * Frontmatter may arrive from the edit form (all string values) or from `parseMarkdown`,
  * where gray-matter turns an unquoted YAML date into a JS `Date`. The `date` case coerces a
@@ -25,25 +27,26 @@ export function validateFields(
     const value = frontmatter[field.name];
     switch (field.type) {
       case 'boolean':
-        data[field.name] = value === true;
+        // Absent or unchecked means false; omit it so a published file carries no draft: false noise.
+        if (value === true) data[field.name] = true;
         break;
       case 'tags':
       case 'freetags': {
         const list = Array.isArray(value) ? value.map(String) : [];
         if (field.required && list.length === 0) errors[field.name] = `${field.label} is required`;
-        data[field.name] = list;
+        if (list.length > 0) data[field.name] = list;
         break;
       }
       case 'date': {
         const text = value instanceof Date ? dateInputValue(value) : typeof value === 'string' ? value.trim() : '';
         if (field.required && text === '') errors[field.name] = `${field.label} is required`;
-        data[field.name] = text;
+        if (text !== '') data[field.name] = text;
         break;
       }
       default: {
         const text = typeof value === 'string' ? value.trim() : '';
         if (field.required && text === '') errors[field.name] = `${field.label} is required`;
-        data[field.name] = text;
+        if (text !== '') data[field.name] = text;
       }
     }
   }

package/src/lib/delivery/content-index.ts

@@ -36,6 +36,13 @@ export interface ContentEntry<F = Record<string, unknown>> extends ContentSummar
   body: string;
 }
 
+/** One entry's validation failure, recorded at build for the site aggregator's gate. */
+export interface ContentProblem {
+  id: string;
+  draft: boolean;
+  errors: Record<string, string>;
+}
+
 /** The per-concept query surface. */
 export interface ContentIndex<F = Record<string, unknown>> {
   all(opts?: { includeDrafts?: boolean }): ContentSummary[];
@@ -43,6 +50,8 @@ export interface ContentIndex<F = Record<string, unknown>> {
   byTag(tag: string, opts?: { includeDrafts?: boolean }): ContentSummary[];
   allTags(): { tag: string; count: number }[];
   adjacent(id: string): { newer?: ContentSummary; older?: ContentSummary };
+  /** Per-entry validation failures recorded at build, for the site-level build gate. */
+  problems(): ContentProblem[];
 }
 
 /** Map a Vite eager `?raw` glob record (`{ path: raw }`) to `RawFile[]`. */
@@ -74,26 +83,36 @@ export function createContentIndex<F = Record<string, unknown>>(
   files: RawFile[],
   descriptor: ConceptDescriptor,
 ): ContentIndex<F> {
-  const entries: ContentEntry<F>[] = files.map((file) => {
+  const problems: ContentProblem[] = [];
+  const entries: ContentEntry<F>[] = [];
+  for (const file of files) {
     const id = idFromFilename(basename(file.path));
     const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
-    const { frontmatter, body } = parseMarkdown(file.raw);
-    const date = asDate(frontmatter.date);
-    return {
+    const { frontmatter: raw, body } = parseMarkdown(file.raw);
+    const date = asDate(raw.date);
+    const draft = raw.draft === true;
+    // Validate once at build. A failure is recorded for the site gate and excluded from the typed
+    // read, so every readable entry's frontmatter is the validator's normalized output, never raw.
+    const result = descriptor.validate(raw, body);
+    if (!result.ok) {
+      problems.push({ id, draft, errors: result.errors });
+      continue;
+    }
+    entries.push({
       id,
       slug,
       permalink: permalink(descriptor, { id, slug, date }),
-      title: asString(frontmatter.title) ?? id,
+      title: asString(raw.title) ?? id,
       date,
-      updated: asDate(frontmatter.updated),
-      tags: asTags(frontmatter.tags),
-      excerpt: deriveExcerpt(body, { description: asString(frontmatter.description) }),
+      updated: asDate(raw.updated),
+      tags: asTags(raw.tags),
+      excerpt: deriveExcerpt(body, { description: asString(raw.description) }),
       wordCount: wordCount(body),
-      draft: frontmatter.draft === true,
-      frontmatter: frontmatter as F,
+      draft,
+      frontmatter: result.data as F,
       body,
-    };
-  });
+    });
+  }
 
   // Dated concepts sort newest-first; undated concepts (Pages) sort by title.
   const sorted = [...entries].sort((a, b) =>
@@ -131,5 +150,6 @@ export function createContentIndex<F = Record<string, unknown>>(
         older: i < list.length - 1 ? summarize(list[i + 1]) : undefined,
       };
     },
+    problems: () => problems,
   };
 }

package/src/lib/delivery/feeds.ts

@@ -17,7 +17,7 @@ export interface FeedChannel {
 export interface FeedItem {
   title: string;
   url: string;
-  date: string;
+  date?: string;
   updated?: string;
   summary: string;
   contentHtml?: string;
@@ -37,14 +37,22 @@ function cdataSafe(value: string): string {
   return value.replace(/]]>/g, ']]]]><![CDATA[>');
 }
 
-/** Format a YYYY-MM-DD (or ISO) string as an RFC-822 date in UTC, as RSS wants. */
-function rfc822(date: string): string {
-  return new Date(`${date.slice(0, 10)}T00:00:00.000Z`).toUTCString();
+/** Parse a YYYY-MM-DD (or ISO) string as a UTC instant. Returns undefined for an absent or
+ *  unparseable date, so a feed omits the date field rather than emit Invalid Date or throw. */
+function parseFeedDate(date?: string): Date | undefined {
+  if (!date) return undefined;
+  const at = new Date(`${date.slice(0, 10)}T00:00:00.000Z`);
+  return Number.isNaN(at.getTime()) ? undefined : at;
 }
 
-/** Format a YYYY-MM-DD (or ISO) string as an ISO-8601 instant in UTC. */
-function iso(date: string): string {
-  return new Date(`${date.slice(0, 10)}T00:00:00.000Z`).toISOString();
+/** Format a date as an RFC-822 string in UTC, as RSS wants, or undefined when it cannot parse. */
+function rfc822(date?: string): string | undefined {
+  return parseFeedDate(date)?.toUTCString();
+}
+
+/** Format a date as an ISO-8601 instant in UTC, or undefined when it cannot parse. */
+function iso(date?: string): string | undefined {
+  return parseFeedDate(date)?.toISOString();
 }
 
 /** Build an RSS 2.0 document. */
@@ -52,17 +60,20 @@ export function buildRssFeed(channel: FeedChannel, items: FeedItem[]): string {
   const entries = items
     .map((item) => {
       const content = item.contentHtml ?? item.summary;
+      const pubDate = rfc822(item.date);
       return [
         '    <item>',
         `      <title>${escapeXml(item.title)}</title>`,
         `      <link>${escapeXml(item.url)}</link>`,
         `      <guid isPermaLink="true">${escapeXml(item.url)}</guid>`,
-        `      <pubDate>${rfc822(item.date)}</pubDate>`,
+        pubDate ? `      <pubDate>${pubDate}</pubDate>` : '',
         `      <description>${escapeXml(item.summary)}</description>`,
         // CDATA cannot contain `]]>`, so split that one sequence rather than escape the body.
         `      <content:encoded><![CDATA[${cdataSafe(content)}]]></content:encoded>`,
         '    </item>',
-      ].join('\n');
+      ]
+        .filter((line) => line !== '')
+        .join('\n');
     })
     .join('\n');
 
@@ -95,16 +106,20 @@ export function buildJsonFeed(channel: FeedChannel, items: FeedItem[]): string {
       feed_url: channel.feedUrl,
       ...(channel.language ? { language: channel.language } : {}),
       ...(channel.author ? { authors: [channel.author] } : {}),
-      items: items.map((item) => ({
-        id: item.url,
-        url: item.url,
-        title: item.title,
-        summary: item.summary,
-        date_published: iso(item.date),
-        ...(item.updated ? { date_modified: iso(item.updated) } : {}),
-        ...(item.contentHtml ? { content_html: item.contentHtml } : { content_text: item.summary }),
-        ...(item.tags && item.tags.length ? { tags: item.tags } : {}),
-      })),
+      items: items.map((item) => {
+        const datePublished = iso(item.date);
+        const dateModified = iso(item.updated);
+        return {
+          id: item.url,
+          url: item.url,
+          title: item.title,
+          summary: item.summary,
+          ...(datePublished ? { date_published: datePublished } : {}),
+          ...(dateModified ? { date_modified: dateModified } : {}),
+          ...(item.contentHtml ? { content_html: item.contentHtml } : { content_text: item.summary }),
+          ...(item.tags && item.tags.length ? { tags: item.tags } : {}),
+        };
+      }),
     },
     null,
     2,

package/src/lib/delivery/index.ts

@@ -4,9 +4,11 @@
 // helpers, the catch-all route loaders, and the head component. It imports nothing from auth,
 // github, or email, so importing it does not pull the server backend into a public bundle.
 export { createContentIndex, fromGlob } from './content-index.js';
-export type { RawFile, ContentSummary, ContentEntry, ContentIndex } from './content-index.js';
+export type { RawFile, ContentSummary, ContentEntry, ContentIndex, ContentProblem } from './content-index.js';
 export { createSiteIndex } from './site-index.js';
 export type { SiteIndex, ConceptIndex } from './site-index.js';
+export { createSiteIndexes } from './site-indexes.js';
+export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';
 export { deriveExcerpt, wordCount } from './excerpt.js';
 export { buildRssFeed, buildJsonFeed } from './feeds.js';
@@ -16,6 +18,8 @@ export type { SitemapUrl } from './sitemap.js';
 export { buildRobots } from './robots.js';
 export { buildSeoMeta } from './seo.js';
 export type { SeoInput, SeoMeta } from './seo.js';
+export { readSeoFields, resolveImageUrl } from './seo-fields.js';
+export type { SeoFields } from './seo-fields.js';
 export { paginate } from './paginate.js';
 export type { Page } from './paginate.js';
 export { rssResponse, jsonFeedResponse, sitemapResponse, robotsResponse } from './responses.js';

package/src/lib/delivery/seo-fields.ts

@@ -0,0 +1,43 @@
+// cairn-cms: the SEO head fields read at the cross-concept boundary (schema-source-of-truth design,
+// Plan 3). The catch-all route resolves any concept by request path, so the entry's frontmatter is
+// typed Record<string, unknown>; this reads the known head fields by name and coerces. Kept apart
+// from seo.ts (the head builder) so reading frontmatter and building the head stay distinct concerns.
+
+/** The head fields a concept can carry in frontmatter. Each is optional and omitted when absent.
+ *  `author` is article-scoped downstream: the head builder emits `article:author` only for a dated
+ *  entry, so an `author` on an undated Page is read here but not rendered. */
+export interface SeoFields {
+  description?: string;
+  image?: string;
+  robots?: string;
+  author?: string;
+}
+
+const KEYS = ['description', 'image', 'robots', 'author'] as const;
+
+/** Read the known SEO head fields off an entry's normalized frontmatter. Keeps a present string,
+ *  trimmed, and omits an absent, empty, or non-string value. Trimming the stored value keeps a stray
+ *  `robots: "  noindex  "` from reaching the head tag with surrounding whitespace. The field must be
+ *  declared in the concept's schema to survive the validate-once read; an undeclared key is not on the
+ *  normalized frontmatter. */
+export function readSeoFields(frontmatter: Record<string, unknown>): SeoFields {
+  const fields: SeoFields = {};
+  for (const key of KEYS) {
+    const value = frontmatter[key];
+    if (typeof value === 'string' && value.trim() !== '') fields[key] = value.trim();
+  }
+  return fields;
+}
+
+/** Resolve an author-supplied image path to an absolute URL against the site origin. An absolute or
+ *  protocol-relative URL passes through; a root-relative path anchors to the origin; a malformed
+ *  string returns undefined rather than throwing at build. The sites use a bare-domain origin, so a
+ *  bare path also anchors to the origin root; against a sub-path origin it would resolve relative to
+ *  that path, per the WHATWG URL rules. */
+export function resolveImageUrl(image: string, origin: string): string | undefined {
+  try {
+    return new URL(image, origin).href;
+  } catch {
+    return undefined;
+  }
+}