@glw907/cairn-cms 0.10.0 → 0.14.0

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/CairnHead.svelte

@@ -0,0 +1,36 @@
+<!--
+@component
+Renders a page's SEO head from a SeoMeta object into <svelte:head>: a title, meta tags, link
+tags, and one escaped JSON-LD script. The title renders from seo.title by default; title={false}
+lets the site own the <title>, and a string overrides it. It carries no CSS, so it pulls in no
+admin styles.
+-->
+<script lang="ts">
+  import type { SeoMeta } from './seo.js';
+  import { jsonLdScript } from './json-ld.js';
+
+  let {
+    /** The plain-data head to render. */
+    seo,
+    /** Title override: a string replaces seo.title, false lets the site own <title>. */
+    title,
+  }: { seo: SeoMeta; title?: string | false } = $props();
+  const titleText = $derived(title === undefined ? seo.title : title);
+</script>
+
+<svelte:head>
+  {#if titleText !== false}
+    <title>{titleText}</title>
+  {/if}
+  {#each seo.meta as m}
+    {#if m.name}
+      <meta name={m.name} content={m.content} />
+    {:else if m.property}
+      <meta property={m.property} content={m.content} />
+    {/if}
+  {/each}
+  {#each seo.links as l}
+    <link rel={l.rel} type={l.type} href={l.href} title={l.title} />
+  {/each}
+  {@html jsonLdScript(seo.jsonLd)}
+</svelte:head>

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

@@ -28,19 +28,30 @@ export interface ContentSummary {
   draft: boolean;
 }
 
-/** The detail view: a summary plus the frontmatter and the body to render. */
-export interface ContentEntry extends ContentSummary {
-  frontmatter: Record<string, unknown>;
+/** The detail view: a summary plus the frontmatter and the body to render. The frontmatter
+ *  type defaults to `Record<string, unknown>`; the typed-reads pass infers it from the concept
+ *  fields. Generic now so that change does not break this signature. */
+export interface ContentEntry<F = Record<string, unknown>> extends ContentSummary {
+  frontmatter: F;
   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 {
+export interface ContentIndex<F = Record<string, unknown>> {
   all(opts?: { includeDrafts?: boolean }): ContentSummary[];
-  byId(id: string): ContentEntry | undefined;
+  byId(id: string): ContentEntry<F> | undefined;
   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[]`. */
@@ -68,24 +79,34 @@ function asTags(value: unknown): string[] {
 }
 
 /** Build a concept's index from its raw files and normalized descriptor. */
-export function createContentIndex(files: RawFile[], descriptor: ConceptDescriptor): ContentIndex {
-  const entries: ContentEntry[] = files.map((file) => {
+export function createContentIndex<F = Record<string, unknown>>(
+  files: RawFile[],
+  descriptor: ConceptDescriptor,
+): ContentIndex<F> {
+  const problems: ContentProblem[] = [];
+  const entries: ContentEntry<F>[] = files.map((file) => {
     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);
+    const { frontmatter: raw, body } = parseMarkdown(file.raw);
+    const date = asDate(raw.date);
+    const draft = raw.draft === true;
+    // Validate once at build. The cheap summary stays raw-derived and robust; the typed detail
+    // frontmatter carries the normalized data on success, the raw frontmatter on failure. A
+    // failure is recorded, not thrown, so the query surface does not explode on construction.
+    const result = descriptor.validate(raw, body);
+    if (!result.ok) problems.push({ id, draft, errors: result.errors });
     return {
       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,
+      draft,
+      frontmatter: (result.ok ? result.data : raw) as F,
       body,
     };
   });
@@ -95,11 +116,11 @@ export function createContentIndex(files: RawFile[], descriptor: ConceptDescript
     descriptor.routing.dated ? (b.date ?? '').localeCompare(a.date ?? '') : a.title.localeCompare(b.title),
   );
 
-  const summarize = (entry: ContentEntry): ContentSummary => {
+  const summarize = (entry: ContentEntry<F>): ContentSummary => {
     const { frontmatter: _frontmatter, body: _body, ...summary } = entry;
     return summary;
   };
-  const visible = (list: ContentEntry[], includeDrafts?: boolean): ContentEntry[] =>
+  const visible = (list: ContentEntry<F>[], includeDrafts?: boolean): ContentEntry<F>[] =>
     includeDrafts ? list : list.filter((entry) => !entry.draft);
 
   return {
@@ -126,5 +147,6 @@ export function createContentIndex(files: RawFile[], descriptor: ConceptDescript
         older: i < list.length - 1 ? summarize(list[i + 1]) : undefined,
       };
     },
+    problems: () => problems,
   };
 }

package/src/lib/delivery/index.ts

@@ -0,0 +1,36 @@
+// cairn-cms: the public delivery entry (@glw907/cairn-cms/delivery). The complete, canonical,
+// backend-free toolkit a SvelteKit site wires its public pages with: the content index and the
+// site resolver, the descriptor helper, the syndication and SEO builders, the endpoint response
+// 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, 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';
+export type { FeedChannel, FeedItem } from './feeds.js';
+export { buildSitemap } from './sitemap.js';
+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';
+export { jsonLdScript } from './json-ld.js';
+export { permalink } from '../content/permalink.js';
+export { createPublicRoutes } from '../sveltekit/public-routes.js';
+export type {
+  PublicRoutesDeps,
+  ListData,
+  TagData,
+  TagIndexData,
+  EntryData,
+} from '../sveltekit/public-routes.js';
+export { default as CairnHead } from './CairnHead.svelte';

package/src/lib/delivery/json-ld.ts

@@ -0,0 +1,16 @@
+// cairn-cms: serialize a JSON-LD object into a safe inline script string. JSON.stringify does
+// not escape <, >, or &, so a value containing "</script>" would close the element and inject
+// markup. Escaping the three characters to their JSON unicode forms keeps the structured data
+// identical for a parser while making the bytes unable to break out of the script element.
+// The line separator U+2028 and paragraph separator U+2029 get the same treatment: they are
+// legal inside a JSON string but unsafe in inline script text, where some parsers read them as
+// line terminators, so an author pasting one into frontmatter would corrupt the JSON-LD block.
+export function jsonLdScript(data: Record<string, unknown>): string {
+  const json = JSON.stringify(data)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+  return `<script type="application/ld+json">${json}</script>`;
+}

package/src/lib/delivery/responses.ts

@@ -0,0 +1,34 @@
+// cairn-cms: response helpers for the public delivery endpoints. Each wraps a builder in a
+// Response with the correct Content-Type, so a site's +server.ts GET is a single call. The
+// content type is the one detail every site otherwise copies and occasionally gets wrong.
+import { buildRssFeed, buildJsonFeed, type FeedChannel, type FeedItem } from './feeds.js';
+import { buildSitemap, type SitemapUrl } from './sitemap.js';
+import { buildRobots } from './robots.js';
+
+/** An RSS 2.0 feed response. */
+export function rssResponse(channel: FeedChannel, items: FeedItem[]): Response {
+  return new Response(buildRssFeed(channel, items), {
+    headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' },
+  });
+}
+
+/** A JSON Feed 1.1 response. */
+export function jsonFeedResponse(channel: FeedChannel, items: FeedItem[]): Response {
+  return new Response(buildJsonFeed(channel, items), {
+    headers: { 'Content-Type': 'application/feed+json; charset=utf-8' },
+  });
+}
+
+/** A sitemap response. */
+export function sitemapResponse(urls: SitemapUrl[]): Response {
+  return new Response(buildSitemap(urls), {
+    headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+  });
+}
+
+/** A robots.txt response. */
+export function robotsResponse(opts: { sitemapUrl: string; disallow?: string[] }): Response {
+  return new Response(buildRobots(opts), {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+}

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;
+  }
+}