@glw907/cairn-cms 0.24.0 → 0.26.0

package/dist/render/pipeline.d.ts

@@ -1,6 +1,6 @@
 import { type PluggableList } from 'unified';
 import type { Schema } from 'hast-util-sanitize';
-import type { ComponentRegistry } from './registry.js';
+import { type ComponentRegistry } from './registry.js';
 import type { LinkResolve } from '../content/links.js';
 export interface RendererOptions {
     /** Stamp a `data-rise` ordinal (0, 1, 2, …) on each top-level component so a site's
@@ -24,7 +24,7 @@ export interface RendererOptions {
 /** Compose a site's render pipeline from its component registry: directive syntax to
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
-export declare function createRenderer(registry: ComponentRegistry, options?: RendererOptions): {
+export declare function createRenderer(registry?: ComponentRegistry, options?: RendererOptions): {
     remarkPlugins: PluggableList;
     rehypePlugins: PluggableList;
     renderMarkdown: (content: string, opts?: {

package/dist/render/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/lib/render/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAStD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAMjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B;;0FAEsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;wCAGoC;IACpC,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C;;+EAE2E;IAC3E,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;+FAE2F;IAC3F,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC5B;AAED;;uFAEuF;AACvF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,GAAE,eAAoB;;;8BA0BrD,MAAM,SAAQ;QAAE,OAAO,CAAC,EAAE,WAAW,CAAA;KAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;EAKjG"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/lib/render/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAStD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAMjD,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B;;0FAEsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;wCAGoC;IACpC,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C;;+EAE2E;IAC3E,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;+FAE2F;IAC3F,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC5B;AAED;;uFAEuF;AACvF,wBAAgB,cAAc,CAC5B,QAAQ,GAAE,iBAAsD,EAChE,OAAO,GAAE,eAAoB;;;8BA2BK,MAAM,SAAQ;QAAE,OAAO,CAAC,EAAE,WAAW,CAAA;KAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;EAKjG"}

package/dist/render/pipeline.js

@@ -12,10 +12,11 @@ import { buildSanitizeSchema, rehypeAnchorRel } from './sanitize-schema.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
 import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
+import { defineRegistry } from './registry.js';
 /** Compose a site's render pipeline from its component registry: directive syntax to
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
-export function createRenderer(registry, options = {}) {
+export function createRenderer(registry = defineRegistry({ components: [] }), options = {}) {
     const remarkPlugins = [remarkDirective, [remarkDirectiveStamp, registry], remarkResolveCairnLinks];
     // The sanitize floor runs after rehype-raw (so author raw HTML is parsed, then cleaned) and
     // before the dispatch (so the site's trusted build() output and its inline SVG icons are never

package/dist/vite/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/vite/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/lib/vite/bin.ts"],"names":[],"mappings":""}

package/dist/vite/bin.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// cairn-manifest: the regenerate command. It evaluates the cairnManifest virtual module in write mode
+// through the consumer's own Vite resolution and writes the canonical content manifest. A thin shell
+// over writeManifest so the write logic stays testable apart from the CLI.
+import { writeManifest } from './index.js';
+writeManifest(process.cwd()).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/vite/index.d.ts

@@ -0,0 +1,33 @@
+import type { Plugin, PluginOption } from 'vite';
+/** Options for {@link cairnManifest}. Paths are app-root-absolute (the form `import.meta.glob` wants),
+ *  so they match the build's own resolution. */
+export interface CairnManifestOptions {
+    /** The module exporting the `cairn` adapter and the parsed `siteConfig`, app-root-absolute. */
+    configModule: string;
+    /** Per-concept content globs, keyed by concept id, app-root-absolute. */
+    content: Record<string, string>;
+    /** The committed manifest path, app-root-absolute. Defaults to `/src/content/.cairn/index.json`. */
+    manifestPath?: string;
+}
+/** Flatten the consumer's plugins option and drop the cairnManifest plugin at any nesting depth, so
+ *  the nested verify server can never re-enter its buildStart. Vite supports (and flattens) nested
+ *  plugin arrays, and findCairnOptions recurses into them, so a flat single-level filter would miss a
+ *  cairnManifest nested inside a shared preset's sub-array and let it survive into the nested server.
+ *  This mirrors findCairnOptions's recursion. Falsy slots pass through, which Vite tolerates. */
+export declare function stripCairnManifest(plugins: PluginOption | PluginOption[]): PluginOption[];
+/** Verify the committed manifest against the corpus from a Vite context, throwing on drift. The bin
+ *  and the plugin share this; the spike proved it runs cleanly inside the consumer's config. */
+export declare function verifyManifestFromVite(opts: CairnManifestOptions, root: string): Promise<void>;
+/** Regenerate the serialized manifest from the corpus in a Vite context, sharing the build's
+ *  resolution. The cairn-manifest bin (a later task) will call this and write the result. */
+export declare function buildManifestFromVite(opts: CairnManifestOptions, root: string): Promise<string>;
+/** The cairnManifest plugin. It serves the verify virtual module to the app graph and, in
+ *  buildStart, evaluates it through a nested Vite SSR load so a manifest drift fails the build. */
+export declare function cairnManifest(opts: CairnManifestOptions): Plugin;
+/** Regenerate the committed manifest from the consumer's corpus and write it to the configured
+ *  manifestPath. It loads the consumer's Vite config from `cwd`, reads the cairnManifest plugin's
+ *  options off the instance, evaluates the write-mode virtual module through the build's own
+ *  resolution, and writes the serialized manifest. The cairn-manifest bin calls this; it is exported
+ *  so the write logic is testable apart from the CLI shell. */
+export declare function writeManifest(cwd?: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/vite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/vite/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAWjD;gDACgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,+FAA+F;IAC/F,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA4ED;;;;iGAIiG;AACjG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,EAAE,GAAG,YAAY,EAAE,CAIzF;AAED;gGACgG;AAChG,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpG;AAED;6FAC6F;AAC7F,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAErG;AAED;mGACmG;AACnG,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CA2BhE;AAED;;;;+DAI+D;AAC/D,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB9E"}

package/dist/vite/index.js

@@ -0,0 +1,178 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** The key the cairnManifest plugin stashes its options under, so the write path can read them off the
+ *  plugin instance in the consumer's loaded config without re-parsing the config file. */
+const CAIRN_OPTIONS = Symbol.for('cairn-cms.manifest-options');
+const VIRTUAL_ID = 'virtual:cairn-manifest';
+const RESOLVED_ID = '\0' + VIRTUAL_ID;
+/** The default committed manifest path, app-root-absolute. */
+const DEFAULT_MANIFEST_PATH = '/src/content/.cairn/index.json';
+/** Build the virtual module source. In verify mode it throws on drift; in write mode it exports the
+ *  serialized manifest as `result`. The module runs in the app graph, so its `import.meta.glob`,
+ *  package, and `?raw` resolution is the build's own. */
+function virtualSource(opts, mode) {
+    const manifestPath = opts.manifestPath ?? DEFAULT_MANIFEST_PATH;
+    const globEntries = Object.entries(opts.content)
+        .map(([id, pattern]) => `  ${JSON.stringify(id)}: import.meta.glob(${JSON.stringify(pattern)}, { query: '?raw', import: 'default', eager: true }),`)
+        .join('\n');
+    // In write mode the committed file may not exist yet, so do not import it.
+    const committedImport = mode === 'verify' ? `import committed from ${JSON.stringify(manifestPath + '?raw')};` : '';
+    const resultExpr = mode === 'write' ? 'serializeManifest(built)' : '(verifyManifest(built, committed), "ok")';
+    return `
+import { buildSiteManifest } from '@glw907/cairn-cms/delivery/data';
+import { serializeManifest, verifyManifest } from '@glw907/cairn-cms';
+import { cairn, siteConfig } from ${JSON.stringify(opts.configModule)};
+${committedImport}
+const globs = {
+${globEntries}
+};
+const built = buildSiteManifest(cairn, siteConfig, globs);
+export const result = ${resultExpr};
+`;
+}
+/** Evaluate the virtual module in the given mode inside the consumer's own Vite resolution, then
+ *  return the module's `result`. It reuses the consumer's loaded config (so `$lib`, the config
+ *  module, `import.meta.glob`, and `?raw` resolve exactly as the build does) and strips the
+ *  cairnManifest plugin from the nested server's plugin list, so its buildStart never recurses.
+ *  This runs at build time and in the bin, never in the request lifecycle. */
+async function evalVirtual(opts, mode, root) {
+    const { createServer, loadConfigFromFile } = await import('vite');
+    // Load the consumer's real Vite config so the nested server inherits SvelteKit's resolution
+    // (the $lib alias, the app root, the ?raw and import.meta.glob handling). Drop cairnManifest from
+    // it so the nested server's buildStart does not recurse, and add a plugin that serves only the
+    // virtual module in the requested mode.
+    const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, undefined, root);
+    const inlineConfig = loaded?.config ?? {};
+    const server = await createServer({
+        ...inlineConfig,
+        root,
+        configFile: false,
+        logLevel: 'silent',
+        server: { middlewareMode: true, hmr: false, watch: null },
+        plugins: [...stripCairnManifest(inlineConfig.plugins ?? []), cairnVirtualOnly(opts, mode)],
+    });
+    try {
+        const mod = (await server.ssrLoadModule(VIRTUAL_ID));
+        return mod.result;
+    }
+    finally {
+        await server.close();
+    }
+}
+/** True for any plugin object whose name is the cairnManifest plugin, so the nested server drops it
+ *  and cannot recurse into another buildStart. The consumer's plugin list may nest arrays and hold
+ *  falsy slots, so guard the shape. */
+function isCairnManifestPlugin(p) {
+    return !!p && typeof p === 'object' && 'name' in p && p.name === 'cairn-manifest';
+}
+/** Flatten the consumer's plugins option and drop the cairnManifest plugin at any nesting depth, so
+ *  the nested verify server can never re-enter its buildStart. Vite supports (and flattens) nested
+ *  plugin arrays, and findCairnOptions recurses into them, so a flat single-level filter would miss a
+ *  cairnManifest nested inside a shared preset's sub-array and let it survive into the nested server.
+ *  This mirrors findCairnOptions's recursion. Falsy slots pass through, which Vite tolerates. */
+export function stripCairnManifest(plugins) {
+    if (Array.isArray(plugins))
+        return plugins.flatMap(stripCairnManifest);
+    if (isCairnManifestPlugin(plugins))
+        return [];
+    return [plugins];
+}
+/** Verify the committed manifest against the corpus from a Vite context, throwing on drift. The bin
+ *  and the plugin share this; the spike proved it runs cleanly inside the consumer's config. */
+export async function verifyManifestFromVite(opts, root) {
+    await evalVirtual(opts, 'verify', root);
+}
+/** Regenerate the serialized manifest from the corpus in a Vite context, sharing the build's
+ *  resolution. The cairn-manifest bin (a later task) will call this and write the result. */
+export async function buildManifestFromVite(opts, root) {
+    return evalVirtual(opts, 'write', root);
+}
+/** The cairnManifest plugin. It serves the verify virtual module to the app graph and, in
+ *  buildStart, evaluates it through a nested Vite SSR load so a manifest drift fails the build. */
+export function cairnManifest(opts) {
+    let root = process.cwd();
+    const plugin = {
+        name: 'cairn-manifest',
+        configResolved(config) {
+            // Capture the resolved app root so the nested server loads the same config the build did.
+            root = config.root;
+        },
+        resolveId(id) {
+            if (id === VIRTUAL_ID)
+                return RESOLVED_ID;
+        },
+        load(id) {
+            if (id === RESOLVED_ID)
+                return virtualSource(opts, 'verify');
+        },
+        async buildStart() {
+            try {
+                await verifyManifestFromVite(opts, root);
+            }
+            catch (err) {
+                this.error(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    // Stash the options on the instance so the cairn-manifest bin's writeManifest can read the content
+    // globs, config module, and manifest path off the plugin in the consumer's loaded config, sharing
+    // exactly the options the build verifies with.
+    plugin[CAIRN_OPTIONS] = opts;
+    return plugin;
+}
+/** Regenerate the committed manifest from the consumer's corpus and write it to the configured
+ *  manifestPath. It loads the consumer's Vite config from `cwd`, reads the cairnManifest plugin's
+ *  options off the instance, evaluates the write-mode virtual module through the build's own
+ *  resolution, and writes the serialized manifest. The cairn-manifest bin calls this; it is exported
+ *  so the write logic is testable apart from the CLI shell. */
+export async function writeManifest(cwd = process.cwd()) {
+    const { loadConfigFromFile } = await import('vite');
+    const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, undefined, cwd);
+    if (!loaded) {
+        throw new Error(`cairn-manifest: no Vite config found in ${cwd}`);
+    }
+    const opts = findCairnOptions(loaded.config.plugins);
+    if (!opts) {
+        throw new Error('cairn-manifest: the Vite config has no cairnManifest() plugin. Add it so the bin shares the build options.');
+    }
+    const serialized = await buildManifestFromVite(opts, cwd);
+    const manifestPath = opts.manifestPath ?? DEFAULT_MANIFEST_PATH;
+    // The manifest path is app-root-absolute (a leading slash relative to the project), so resolve it
+    // against cwd, not the filesystem root.
+    const outPath = join(cwd, manifestPath.replace(/^\//, ''));
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, serialized);
+}
+/** Walk a Vite plugins option (which may nest arrays, hold falsy slots, or be a thenable) and return
+ *  the stashed cairnManifest options from the first matching plugin, or null if there is none. */
+function findCairnOptions(plugins) {
+    if (!plugins)
+        return null;
+    if (Array.isArray(plugins)) {
+        for (const p of plugins) {
+            const found = findCairnOptions(p);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (typeof plugins === 'object' && CAIRN_OPTIONS in plugins) {
+        return plugins[CAIRN_OPTIONS] ?? null;
+    }
+    return null;
+}
+/** A minimal plugin that serves only the virtual module in one mode, for the nested SSR load. It
+ *  carries no buildStart, so the nested server never recurses into the verify. */
+function cairnVirtualOnly(opts, mode) {
+    return {
+        name: 'cairn-manifest-virtual',
+        resolveId(id) {
+            if (id === VIRTUAL_ID)
+                return RESOLVED_ID;
+        },
+        load(id) {
+            if (id === RESOLVED_ID)
+                return virtualSource(opts, mode);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [
@@ -13,6 +13,10 @@
     "type": "git",
     "url": "git+https://github.com/glw907/cairn-cms.git"
   },
+  "homepage": "https://github.com/glw907/cairn-cms#readme",
+  "bugs": {
+    "url": "https://github.com/glw907/cairn-cms/issues"
+  },
   "keywords": [
     "cms",
     "sveltekit",
@@ -22,9 +26,9 @@
     "markdown"
   ],
   "scripts": {
-    "package": "svelte-package",
+    "package": "svelte-package && chmod +x dist/vite/bin.js",
     "check:package": "npm run package && publint --strict && attw --pack . --ignore-rules no-resolution cjs-resolves-to-esm internal-resolution-error",
-    "prepare": "svelte-package",
+    "prepare": "npm run package",
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -58,11 +62,24 @@
       "svelte": "./dist/delivery/head.js",
       "default": "./dist/delivery/head.js"
     },
+    "./delivery/data": {
+      "types": "./dist/delivery/data.d.ts",
+      "svelte": "./dist/delivery/data.js",
+      "default": "./dist/delivery/data.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "default": "./dist/vite/index.js"
+    },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "cairn-manifest": "./dist/vite/bin.js"
+  },
   "files": [
     "dist",
-    "src/lib"
+    "src/lib",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
     "@sveltejs/kit": "^2",

package/src/lib/content/compose.ts

@@ -3,18 +3,27 @@
 // the same way and contributes the same kinds of things: nav entries, route logic,
 // concepts, components, field types, and save hooks. Shaped now so the extension contract
 // is additive later.
-import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, ConceptUrlPolicy, FieldTypeDef } from './types.js';
+import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, FieldTypeDef } from './types.js';
 import { normalizeConcepts } from './concepts.js';
+import { urlPolicyFrom, type SiteConfig } from '../nav/site-config.js';
+
+/** The input to {@link composeRuntime}. `siteConfig` is required so the per-concept URL policy is
+ *  always derived from one source and can never be silently dropped. `extensions` fold in after the
+ *  adapter's concepts. */
+export interface ComposeInput {
+  adapter: CairnAdapter;
+  siteConfig: SiteConfig;
+  extensions?: CairnExtension[];
+}
 
 /**
- * Fold an adapter and any extensions into the composed runtime (seam 2). Extension concepts
- * merge after the adapter's. The asset slot (seam 4) passes through untouched.
+ * Fold an adapter and any extensions into the composed runtime (seam 2). The per-concept URL policy
+ * is derived from the site config, the same source the delivery path uses, so the runtime and
+ * delivery permalinks cannot diverge. Extension concepts merge after the adapter's. The asset slot
+ * (seam 4) passes through untouched.
  */
-export function composeRuntime(
-  adapter: CairnAdapter,
-  extensions: CairnExtension[] = [],
-  urlPolicy: Record<string, ConceptUrlPolicy | undefined> = {},
-): CairnRuntime {
+export function composeRuntime({ adapter, siteConfig, extensions = [] }: ComposeInput): CairnRuntime {
+  if (!siteConfig) throw new Error('composeRuntime needs a site config to derive the URL policy');
   const content: Record<string, ConceptConfig | undefined> = { ...adapter.content };
   const adminPanels: AdminPanel[] = [];
   const fieldTypes: FieldTypeDef[] = [];
@@ -27,7 +36,7 @@ export function composeRuntime(
   }
   return {
     siteName: adapter.siteName,
-    concepts: normalizeConcepts(content, urlPolicy),
+    concepts: normalizeConcepts(content, urlPolicyFrom(siteConfig)),
     backend: adapter.backend,
     sender: adapter.sender,
     render: adapter.render,

package/src/lib/content/manifest.ts

@@ -140,15 +140,71 @@ export function parseManifest(raw: string): Manifest {
   return { version: 1, entries: obj.entries as ManifestEntry[] };
 }
 
-/** Throw if the committed manifest drifts from what the corpus says. Both sides are compared in the
- *  canonical serialized form, so semantic equality never spuriously fails. The build calls this so a
- *  raw-git content edit, which leaves the committed manifest stale, fails the build loudly. */
-export function verifyManifest(built: Manifest, committedRaw: string): void {
-  if (committedRaw !== serializeManifest(built)) {
-    throw new Error(
-      'content manifest is stale: the committed file does not match the corpus. Regenerate it (npm run cairn:manifest) and commit the result.',
+/** A changed entry and the fields that differ between the built and committed manifests. */
+export interface ManifestEntryDiff {
+  concept: string;
+  id: string;
+  fields: string[];
+}
+
+/** The drift between a freshly built manifest and the committed one, keyed by concept+id. */
+export interface ManifestDiff {
+  added: ManifestEntry[];
+  removed: ManifestEntry[];
+  changed: ManifestEntryDiff[];
+}
+
+const keyOf = (e: ManifestEntry) => `${e.concept}/${e.id}`;
+
+/** Compare a built manifest against a committed one, keyed by concept+id (the same identity
+ *  upsertEntry and removeEntry use). A changed entry names the fields that differ. Pure, so it is
+ *  unit-tested apart from any build. */
+export function diffManifests(built: Manifest, committed: Manifest): ManifestDiff {
+  const builtByKey = new Map(built.entries.map((e) => [keyOf(e), e]));
+  const committedByKey = new Map(committed.entries.map((e) => [keyOf(e), e]));
+  const added = built.entries.filter((e) => !committedByKey.has(keyOf(e)));
+  const removed = committed.entries.filter((e) => !builtByKey.has(keyOf(e)));
+  const changed: ManifestEntryDiff[] = [];
+  for (const b of built.entries) {
+    const c = committedByKey.get(keyOf(b));
+    if (!c) continue;
+    // ManifestEntry has no index signature, so read its keys through an unknown-cast record.
+    const br = b as unknown as Record<string, unknown>;
+    const cr = c as unknown as Record<string, unknown>;
+    const fields = [...new Set([...Object.keys(b), ...Object.keys(c)])].filter(
+      (k) => JSON.stringify(br[k]) !== JSON.stringify(cr[k]),
     );
+    if (fields.length > 0) changed.push({ concept: b.concept, id: b.id, fields });
   }
+  return { added, removed, changed };
+}
+
+/** Format a diff into a short human-readable block for a build error. */
+function formatDiff(d: ManifestDiff): string {
+  const lines: string[] = [];
+  for (const e of d.added) lines.push(`  + ${keyOf(e)}`);
+  for (const e of d.removed) lines.push(`  - ${keyOf(e)}`);
+  for (const e of d.changed) lines.push(`  ~ ${e.concept}/${e.id} (${e.fields.join(', ')})`);
+  return lines.join('\n');
+}
+
+/** Throw if the committed manifest drifts from what the corpus says. The canonical serialized form
+ *  is the fast-path equality guard, so semantic equality never spuriously fails. On a mismatch the
+ *  error names the added, removed, and changed entries, so a raw-git content edit that leaves the
+ *  committed manifest stale fails the build loudly with what drifted. */
+export function verifyManifest(built: Manifest, committedRaw: string): void {
+  const builtRaw = serializeManifest(built);
+  if (committedRaw === builtRaw) return;
+  // Diff the canonical built form, not the raw one. serializeManifest sorts each entry's links, so a
+  // build whose links are in extraction order would otherwise report a false (links) drift for an
+  // entry whose link set is identical and only the order differs. Reuse the serialized form so both
+  // sides are canonical.
+  const diff = diffManifests(parseManifest(builtRaw), parseManifest(committedRaw));
+  throw new Error(
+    'content manifest is stale: the committed file does not match the corpus.\n' +
+      formatDiff(diff) +
+      '\nRegenerate it (npm run cairn:manifest) and commit the result.',
+  );
 }
 
 /** Replace the entry with the same concept and id, or add it. Order does not matter, since

package/src/lib/content/validate.ts

@@ -9,7 +9,10 @@ import { dateInputValue, isCalendarDate } 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. 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
+ * one is omitted, so validated data carries no key for an absent tag field (`tags` or `freetags`).
+ * The delivery read model
+ * (`ContentSummary.tags`) fills that case with an empty array; the two layers differ on purpose.
+ * 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.
  *

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

@@ -25,6 +25,10 @@ export interface ContentSummary {
   title: string;
   date?: string;
   updated?: string;
+  /** The entry's tags, always present as an array and empty when the file declares none. This is the
+   *  read-model normalization. It differs on purpose from the validated `frontmatter.tags`, which the
+   *  validator omits when empty, so a published file carries no `tags: []` noise. Read `tags` here for
+   *  a list; read `frontmatter.tags` only when you need the validated, possibly-absent value. */
   tags: string[];
   excerpt: string;
   wordCount: number;

package/src/lib/delivery/data.ts

@@ -0,0 +1,26 @@
+// cairn-cms: the node-safe delivery data surface (@glw907/cairn-cms/delivery/data). The pure corpus
+// 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 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 { buildSiteManifest, buildLinkResolver } from './manifest.js';

package/src/lib/delivery/index.ts

@@ -1,31 +1,8 @@
-// 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 { buildSiteManifest, buildLinkResolver } from './manifest.js';
+// cairn-cms: the public delivery entry (@glw907/cairn-cms/delivery). The node-safe data surface
+// (re-exported from ./delivery/data) plus the SvelteKit catch-all route loaders. The head component
+// lives at ./delivery/head. Importing this pulls @sveltejs/kit through the route loaders, so a
+// plain-Node tool imports from ./delivery/data instead.
+export * from './data.js';
 export { createPublicRoutes } from '../sveltekit/public-routes.js';
 export type {
   PublicRoutesDeps,

package/src/lib/index.ts

@@ -31,6 +31,7 @@ export type {
 } from './content/types.js';
 export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
+export type { ComposeInput } from './content/compose.js';
 export {
   frontmatterFromForm,
   dateInputValue,
@@ -59,13 +60,14 @@ export {
   parseManifest,
   emptyManifest,
   verifyManifest,
+  diffManifests,
   upsertEntry,
   removeEntry,
   manifestEntryFromFile,
   manifestLinkResolver,
   inboundLinks,
 } from './content/manifest.js';
-export type { Manifest, ManifestEntry, LinkTarget, InboundLink } from './content/manifest.js';
+export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink } from './content/manifest.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
 export { defineRegistry, emptyValues } from './render/registry.js';
 export type {

package/src/lib/render/pipeline.ts

@@ -13,7 +13,7 @@ import { buildSanitizeSchema, rehypeAnchorRel } from './sanitize-schema.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
 import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
-import type { ComponentRegistry } from './registry.js';
+import { defineRegistry, type ComponentRegistry } from './registry.js';
 import type { LinkResolve } from '../content/links.js';
 
 export interface RendererOptions {
@@ -39,7 +39,10 @@ export interface RendererOptions {
 /** Compose a site's render pipeline from its component registry: directive syntax to
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
-export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
+export function createRenderer(
+  registry: ComponentRegistry = defineRegistry({ components: [] }),
+  options: RendererOptions = {},
+) {
   const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry], remarkResolveCairnLinks];
   // The sanitize floor runs after rehype-raw (so author raw HTML is parsed, then cleaned) and
   // before the dispatch (so the site's trusted build() output and its inline SVG icons are never

package/src/lib/vite/bin.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// cairn-manifest: the regenerate command. It evaluates the cairnManifest virtual module in write mode
+// through the consumer's own Vite resolution and writes the canonical content manifest. A thin shell
+// over writeManifest so the write logic stays testable apart from the CLI.
+import { writeManifest } from './index.js';
+
+writeManifest(process.cwd()).catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});