@glw907/cairn-cms 0.4.0 → 0.5.1

package/src/lib/components/LoginPage.svelte

@@ -1,13 +1,13 @@
 <script lang="ts">
   // The magic-link sign-in page. Requests a link via the better-auth client (client-side, same
-  // origin). To avoid enumeration the UI shows the SAME neutral copy whether or not the email is
-  // on the allowlist — the server only emails actual editors (see auth/config.ts send gate).
+  // origin). To avoid enumeration the UI shows the same neutral copy whether or not the email is
+  // on the allowlist. The server only emails actual editors (see auth/config.ts send gate).
   import { createAuthClient } from 'better-auth/svelte';
   import { magicLinkClient } from 'better-auth/client/plugins';
 
   // The browser client lives in the one component that needs it (requesting a link). Sign-out
-  // and editor management go through server endpoints, so no shared client module is needed —
-  // and a component-local const keeps better-auth's deep client types out of the packaged .d.ts.
+  // and editor management go through server endpoints, so no shared client module is needed.
+  // A component-local const keeps better-auth's deep client types out of the packaged .d.ts.
   const authClient = createAuthClient({ plugins: [magicLinkClient()] });
 
   interface Props {
@@ -23,7 +23,7 @@
     event.preventDefault();
     busy = true;
     // The magic-link email points at our /admin/auth/confirm page (built in config.ts), not a
-    // GET-verify URL — so the result is the same regardless of allowlist membership.
+    // GET-verify URL, so the result is the same regardless of allowlist membership.
     await authClient.signIn.magicLink({ email });
     busy = false;
     requested = true;

package/src/lib/components/NavTree.svelte

@@ -0,0 +1,128 @@
+<script lang="ts">
+  // The navigation tree editor (Pass L). Edits a local copy of the menu tree and posts the whole
+  // tree as JSON to the `save` action. DaisyUI primitives under the Warm Stone admin theme. Drag a
+  // row up or down to reorder within its level; use Indent/Outdent to nest under the previous
+  // sibling or promote a level (capped at the menu's maxDepth). The engine validates on save.
+  import { untrack } from 'svelte';
+  import type { NavLoadData } from '../sveltekit';
+  import type { NavNode } from '../nav';
+
+  let { data }: { data: NavLoadData } = $props();
+
+  // A flat, ordered working model is far simpler to drag-edit than a recursive one: each row
+  // carries an explicit depth, and the tree is rebuilt from (order + depth) only at submit time.
+  interface Row {
+    id: number;
+    depth: number;
+    label: string;
+    url: string;
+  }
+
+  let nextId = 1;
+  function flatten(nodes: NavNode[], depth: number, out: Row[]): Row[] {
+    for (const n of nodes) {
+      out.push({ id: nextId++, depth, label: n.label, url: n.url ?? '' });
+      if (n.children?.length) flatten(n.children, depth + 1, out);
+    }
+    return out;
+  }
+
+  let rows = $state<Row[]>(untrack(() => flatten(data.tree, 0, [])));
+  const maxDepthIndex = $derived(data.menu.maxDepth - 1); // depth is 0-based here
+
+  // Rebuild the nested tree from the flat rows by depth, then serialize for the hidden field.
+  function toTree(list: Row[]): NavNode[] {
+    const root: NavNode[] = [];
+    const stack: { depth: number; node: NavNode }[] = [];
+    for (const r of list) {
+      const node: NavNode = { label: r.label.trim() };
+      if (r.url.trim()) node.url = r.url.trim();
+      while (stack.length && stack[stack.length - 1].depth >= r.depth) stack.pop();
+      if (stack.length) (stack[stack.length - 1].node.children ??= []).push(node);
+      else root.push(node);
+      stack.push({ depth: r.depth, node });
+    }
+    return root;
+  }
+
+  const treeJson = $derived(JSON.stringify(toTree(rows)));
+
+  function addRow() {
+    rows = [...rows, { id: nextId++, depth: 0, label: 'New item', url: '' }];
+  }
+  function removeRow(id: number) {
+    rows = rows.filter((r) => r.id !== id);
+  }
+  function indent(i: number) {
+    // A row may nest at most one level deeper than the row above it, and never past the cap.
+    if (i === 0) return;
+    const ceiling = Math.min(rows[i - 1].depth + 1, maxDepthIndex);
+    if (rows[i].depth < ceiling) rows[i].depth += 1;
+  }
+  function outdent(i: number) {
+    if (rows[i].depth > 0) rows[i].depth -= 1;
+  }
+
+  let dragFrom = $state<number | null>(null);
+  function onDrop(to: number) {
+    if (dragFrom === null || dragFrom === to) return;
+    const next = [...rows];
+    const [moved] = next.splice(dragFrom, 1);
+    next.splice(to, 0, moved);
+    rows = next;
+    dragFrom = null;
+  }
+</script>
+
+<div class="cairn-admin">
+  <div class="flex items-center justify-between">
+    <h1 class="text-xl font-semibold">{data.menu.label}</h1>
+    <button type="button" class="btn btn-sm" onclick={addRow}>Add item</button>
+  </div>
+
+  {#if data.saved}
+    <div class="alert alert-success mt-3">Navigation saved.</div>
+  {/if}
+  {#if data.error}
+    <div class="alert alert-error mt-3">{data.error}</div>
+  {/if}
+
+  <form method="POST" action="?/save" class="mt-4">
+    <input type="hidden" name="tree" value={treeJson} />
+    <ul class="menu w-full gap-1">
+      {#each rows as row, i (row.id)}
+        <li
+          draggable="true"
+          ondragstart={() => (dragFrom = i)}
+          ondragover={(e) => e.preventDefault()}
+          ondrop={() => onDrop(i)}
+          style={`margin-left:${row.depth * 1.5}rem`}
+        >
+          <div class="flex items-center gap-2 p-2">
+            <span class="cursor-grab opacity-40" aria-hidden="true">&#x283F;</span>
+            <input class="input input-sm input-bordered flex-1" placeholder="Label" bind:value={row.label} />
+            <input
+              class="input input-sm input-bordered flex-1"
+              placeholder="/path or https://…"
+              list="cairn-nav-pages"
+              bind:value={row.url}
+            />
+            <button type="button" class="btn btn-xs btn-ghost" onclick={() => outdent(i)} aria-label="Outdent">&larr;</button>
+            <button type="button" class="btn btn-xs btn-ghost" onclick={() => indent(i)} aria-label="Indent">&rarr;</button>
+            <button type="button" class="btn btn-xs btn-ghost text-error" onclick={() => removeRow(row.id)} aria-label="Remove">&times;</button>
+          </div>
+        </li>
+      {/each}
+    </ul>
+
+    <datalist id="cairn-nav-pages">
+      {#each data.pages as p (p.url)}
+        <option value={p.url}>{p.label}</option>
+      {/each}
+    </datalist>
+
+    <div class="mt-4">
+      <button type="submit" class="btn btn-primary btn-sm">Save navigation</button>
+    </div>
+  </form>
+</div>

package/src/lib/components/index.ts

@@ -1,8 +1,10 @@
 // cairn-cms admin UI shell. Consumers import from 'cairn-cms/components'; each site's
 // admin route `.svelte` files are one-line shims around these.
 export { default as AdminLayout } from './AdminLayout.svelte';
-export { default as AdminList } from './AdminList.svelte';
+export { default as CollectionList } from './CollectionList.svelte';
 export { default as LoginPage } from './LoginPage.svelte';
 export { default as ConfirmPage } from './ConfirmPage.svelte';
 export { default as EditPage } from './EditPage.svelte';
 export { default as ManageAdmins } from './ManageAdmins.svelte';
+export { default as ComponentPalette } from './ComponentPalette.svelte';
+export { default as NavTree } from './NavTree.svelte';

package/src/lib/editor.ts

@@ -0,0 +1,38 @@
+// cairn-core: the editor cursor seam (decision P3). The component palette and any later insert
+// control talk to MarkdownEditor, never to Carta directly, so a swap to a different editing
+// engine is contained to this file. Verified against carta-md@4.11: `input.getSelection()` and
+// `input.insertAt(pos, text)` are public on the InputEnhancer.
+
+// Local structural type for the Carta surface this module uses. carta-md is a peerDep and its
+// types are erased at runtime, but the carta-boundary test bars any `.ts` file from importing
+// `carta-md` (C4 bundle guard). A structural type avoids that import while remaining compatible.
+interface CartaInput {
+  getSelection(): { start: number; end: number; direction: string; slice: string };
+  insertAt(position: number, text: string): void;
+}
+
+interface CartaLike {
+  input?: CartaInput;
+}
+
+/** The programmatic editing surface the admin relies on. */
+export interface MarkdownEditor {
+  /** Insert a component or template at the current cursor position. */
+  insertComponent(template: string): void;
+}
+
+/**
+ * Wrap a Carta instance as a MarkdownEditor. Takes a getter (not the instance) because the
+ * EditPage component creates the Carta instance once and `carta.input` is only populated after
+ * the editor mounts; reading it lazily at call time avoids capturing an undefined `input`.
+ */
+export function cartaEditor(getCarta: () => CartaLike): MarkdownEditor {
+  return {
+    insertComponent(template) {
+      const input = getCarta().input;
+      if (!input) return; // editor not mounted yet; nothing to insert into
+      const { start } = input.getSelection();
+      input.insertAt(start, template);
+    },
+  };
+}

package/src/lib/email.ts

@@ -1,9 +1,9 @@
 // cairn-core: pluggable magic-link email sender.
 //
-// Default adapter is Cloudflare Email Service → Email Sending (transactional, arbitrary
-// recipients) — distinct from Email Routing's recipient-restricted `EmailMessage` flow.
-// It is reached through the same `send_email` binding (configured without a
-// destination_address) but a different call shape: `binding.send({ to, from, ... })`.
+// The default adapter targets Cloudflare Email Service (Email Sending, transactional,
+// arbitrary recipients), distinct from Email Routing's recipient-restricted `EmailMessage`
+// flow. Both share the same `send_email` binding (configured without a destination_address)
+// but use a different call shape: `binding.send({ to, from, ... })`.
 // Resend can slot in behind the same `sendMagicLink` signature if needed.
 
 /** Cloudflare Email Sending binding surface (the object-form `send`, not the MIME form). */

package/src/lib/frontmatter.ts

@@ -0,0 +1,17 @@
+// cairn-core: coerce a frontmatter value to the YYYY-MM-DD string an <input type="date"> wants.
+// gray-matter parses an unquoted YAML date (date: 2026-05-14) into a JS Date, so a string-only
+// read leaves the date input empty and drops the date on save. This normalizes a Date or an
+// ISO-ish string to YYYY-MM-DD. A parsed YAML date is UTC midnight, so slicing the ISO string
+// avoids a local-timezone shift. Internal (not re-exported from the barrel), like utils.ts.
+
+/** A frontmatter date value (Date or string) to the `YYYY-MM-DD` an `<input type="date">` expects. */
+export function dateInputValue(value: unknown): string {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? '' : value.toISOString().slice(0, 10);
+  }
+  if (typeof value === 'string') {
+    const match = value.match(/^\d{4}-\d{2}-\d{2}/);
+    return match ? match[0] : '';
+  }
+  return '';
+}

package/src/lib/github.ts

@@ -2,8 +2,8 @@
 //
 // Reads (Pass B) list a collection directory and fetch a file's raw markdown; the token
 // is optional because ecnordic's repo is public. Writes (Pass C) mint a short-lived
-// GitHub App installation token — App JWT (RS256) signed with Web Crypto, no octokit
-// dependency — and commit through the contents API with author = editor, committer = the
+// GitHub App installation token (App JWT, RS256 signed with Web Crypto, no octokit
+// dependency) and commit through the contents API with author = editor, committer = the
 // App (cairn-cms[bot]). The same token also lifts reads to the authenticated rate limit
 // and unlocks private repos (e.g. 907-life).
 
@@ -90,7 +90,7 @@ function derLength(n: number): number[] {
 // AlgorithmIdentifier for rsaEncryption (OID 1.2.840.113549.1.1.1) with NULL parameters.
 const RSA_ALG_ID = [0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00];
 
-/** Wrap a PKCS#1 RSAPrivateKey (DER) as PKCS#8 — the only RSA form Web Crypto importKey takes. */
+/** Wrap a PKCS#1 RSAPrivateKey (DER) as PKCS#8 (the only RSA form Web Crypto importKey takes). */
 function pkcs1ToPkcs8(pkcs1: Uint8Array): Uint8Array {
   const octet = [0x04, ...derLength(pkcs1.length), ...pkcs1];
   const body = [0x02, 0x01, 0x00, ...RSA_ALG_ID, ...octet];
@@ -124,7 +124,7 @@ export async function appJwt(appId: string, privateKeyPem: string): Promise<stri
 export interface AppCredentials {
   appId: string;
   installationId: string;
-  /** The stored GITHUB_APP_PRIVATE_KEY_B64 — base64 of the PEM, single line. */
+  /** The stored GITHUB_APP_PRIVATE_KEY_B64: base64 of the PEM, single line. */
   privateKeyB64: string;
 }
 
@@ -139,7 +139,7 @@ export async function installationToken(creds: AppCredentials): Promise<string>
   return ((await res.json()) as { token: string }).token;
 }
 
-/** Standard (padded) base64 of UTF-8 text — the encoding the contents API expects. */
+/** Standard (padded) base64 of UTF-8 text, as the contents API expects. */
 function toBase64(text: string): string {
   return btoa(Array.from(encoder.encode(text), (b) => String.fromCharCode(b)).join(''));
 }
@@ -157,11 +157,24 @@ export interface CommitAuthor {
   email: string;
 }
 
+/**
+ * A concurrent edit lost the SHA race (C3): the file changed between the read and the PUT,
+ * from another editor or the site's own CI. Thrown so callers can fail safe (re-fetch and ask
+ * the editor to reapply) instead of surfacing a raw 409. Defined and caught inside the package
+ * so `instanceof` is reliable (no peer-boundary identity split, unlike kit's `redirect`/`error`).
+ */
+export class CommitConflictError extends Error {
+  constructor(public readonly path: string) {
+    super(`Commit conflict on ${path}: it changed since it was opened`);
+    this.name = 'CommitConflictError';
+  }
+}
+
 /**
  * Commit `content` to `path` on the configured branch via the contents API. Author is the
  * editor; committer is omitted so GitHub attributes it to the App (cairn-cms[bot]). Updates
  * the file in place when it exists (passing its sha), creates it otherwise. Returns the
- * commit sha.
+ * commit sha. A stale-sha 409 (someone committed in between) becomes a `CommitConflictError`.
  */
 export async function commitFile(
   repo: RepoRef,
@@ -183,6 +196,25 @@ export async function commitFile(
       ...(sha ? { sha } : {}),
     }),
   });
+  // 409 = the blob sha we read is no longer current. Fail safe: the caller re-fetches and the
+  // editor reapplies. (Full three-way merge stays out of scope; see ARCHITECTURE §5.)
+  if (res.status === 409) throw new CommitConflictError(path);
   if (!res.ok) throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
   return ((await res.json()) as { commit: { sha: string } }).commit.sha;
 }
+
+/**
+ * Deploy-time self-test for the GitHub App signer (M2): sign a dummy JWT with the configured
+ * private key. Exercises the brittle PKCS#1→PKCS#8 conversion + Web Crypto import/sign without
+ * any network call or secret in the result, so `/admin/healthz` catches a bad/rotated key
+ * before an editor's save fails. Returns `{ ok: false, detail }` rather than throwing.
+ */
+export async function signingSelfTest(appId: string, privateKeyB64: string): Promise<{ ok: boolean; detail?: string }> {
+  try {
+    const jwt = await appJwt(appId, atob(privateKeyB64));
+    if (jwt.split('.').length !== 3) return { ok: false, detail: 'malformed JWT' };
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, detail: err instanceof Error ? err.message : 'sign failed' };
+  }
+}

package/src/lib/index.ts

@@ -5,3 +5,6 @@ export * from './github';
 export * from './carta';
 export * from './content';
 export * from './adapter';
+export * from './slug';
+export * from './render';
+export * from './nav';

package/src/lib/nav.ts

@@ -0,0 +1,117 @@
+// cairn-core: the navigation tree. A menu lives in the site's git-committed `site.config.yaml`
+// under `menus.<name>`, read at build time by the public layout and edited from `/admin/nav`,
+// which commits the file back through the GitHub-App pipeline. The engine returns data only; each
+// site renders the tree with its own header markup.
+
+import { parse as parseYaml, parseDocument } from 'yaml';
+
+/** One navigation node. `url` omitted/empty is a label-only grouping header; `children` omitted is a leaf. */
+export interface NavNode {
+  label: string;
+  url?: string;
+  children?: NavNode[];
+}
+
+/** Total node cap across the whole tree, a guard against a runaway payload. */
+export const MAX_NAV_NODES = 200;
+
+export class NavValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NavValidationError';
+  }
+}
+
+/**
+ * Validate and normalize an untrusted value into a NavNode[]: arrays only, non-empty labels,
+ * depth within `maxDepth` (1 = flat), bounded node count, and only the three known keys kept.
+ * Throws NavValidationError on any violation. Used by `navSave` before writing.
+ */
+export function validateNavTree(value: unknown, maxDepth: number): NavNode[] {
+  let count = 0;
+
+  function walk(nodes: unknown, depth: number): NavNode[] {
+    if (!Array.isArray(nodes)) throw new NavValidationError('Navigation must be a list of items');
+    if (depth > maxDepth) throw new NavValidationError(`Navigation is nested deeper than ${maxDepth} levels`);
+    return nodes.map((raw) => {
+      if (typeof raw !== 'object' || raw === null) throw new NavValidationError('Each item must be an object');
+      const item = raw as Record<string, unknown>;
+      const label = typeof item.label === 'string' ? item.label.trim() : '';
+      if (!label) throw new NavValidationError('Each item needs a label');
+      if (++count > MAX_NAV_NODES) throw new NavValidationError('Too many navigation items');
+      const node: NavNode = { label };
+      if (typeof item.url === 'string' && item.url.trim()) node.url = item.url.trim();
+      if (item.children !== undefined) {
+        const children = walk(item.children, depth + 1);
+        if (children.length) node.children = children;
+      }
+      return node;
+    });
+  }
+
+  return walk(value, 1);
+}
+
+/**
+ * Shape of the YAML site-config file. Unknown keys are ignored so the file can grow without
+ * an engine change. Read at build time by the public site.
+ */
+export interface SiteConfig {
+  siteName: string;
+  description?: string;
+  author?: string;
+  url?: string;
+  locale?: string;
+  /** Named navigation menus, each a NavNode[] (normalized by extractMenu). */
+  menus?: Record<string, unknown>;
+  email?: { sender?: string; senderName?: string };
+  footer?: { copyrightName?: string };
+  settings?: {
+    feedMaxItems?: number;
+    homepageFeaturedCount?: number;
+    postTags?: string[];
+    [key: string]: unknown;
+  };
+}
+
+export class SiteConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SiteConfigError';
+  }
+}
+
+/** Parse the YAML site-config text into a typed object. Throws SiteConfigError on a malformed root. */
+export function parseSiteConfig(raw: string): SiteConfig {
+  const parsed = parseYaml(raw) as unknown;
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new SiteConfigError('Site config must be a YAML mapping');
+  }
+  const { siteName } = parsed as SiteConfig;
+  if (typeof siteName !== 'string' || !siteName.trim()) {
+    throw new SiteConfigError('Site config needs a siteName');
+  }
+  return parsed as SiteConfig;
+}
+
+/** Extract one named menu from a parsed config and validate it. Returns [] when the menu is absent. */
+export function extractMenu(config: SiteConfig, name: string, maxDepth: number): NavNode[] {
+  const menu = config.menus?.[name];
+  if (menu === undefined) return [];
+  return validateNavTree(menu, maxDepth);
+}
+
+/**
+ * Replace one named menu in the YAML site-config text and re-serialize, preserving every other
+ * top-level key (siteName, other menus, settings, ...). The `/admin/nav` editor commits the result.
+ * Parses into a Document so the rest of the file round-trips; YAML comments are not preserved
+ * (an accepted trade), but data keys are. A leaf node serializes without `url`/`children` keys.
+ */
+export function setMenu(raw: string, name: string, tree: NavNode[]): string {
+  const doc = parseDocument(raw);
+  if (doc.get('siteName') === undefined) {
+    throw new SiteConfigError('Site config must be a mapping with a siteName');
+  }
+  doc.setIn(['menus', name], tree);
+  return doc.toString();
+}

package/src/lib/render/glyph.ts

@@ -0,0 +1,14 @@
+import { s } from 'hastscript';
+import type { Element } from 'hast';
+
+/** A glyph name → SVG path-data map (the site owns the icon set). */
+export type IconSet = Record<string, string>;
+
+/** Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill. */
+export function glyph(name: string, icons: IconSet): Element {
+	return s(
+		'svg',
+		{ className: ['ec-glyph'], viewBox: '0 0 256 256', fill: 'currentColor', ariaHidden: 'true' },
+		[s('path', { d: icons[name] })],
+	);
+}

package/src/lib/render/index.ts

@@ -0,0 +1,8 @@
+// cairn-cms render engine: a directive-driven markdown → HTML pipeline whose
+// component vocabulary is supplied by a site's component registry. The site owns the
+// component builders, class names, icon set, and CSS; the engine owns the machinery.
+export * from './registry';
+export * from './glyph';
+export * from './remark-directives';
+export * from './rehype-dispatch';
+export * from './pipeline';

package/src/lib/render/pipeline.ts

@@ -0,0 +1,37 @@
+import { unified, type PluggableList } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
+import remarkRehype from 'remark-rehype';
+import rehypeRaw from 'rehype-raw';
+import rehypeSlug from 'rehype-slug';
+import rehypeStringify from 'rehype-stringify';
+import { remarkDirectiveStamp } from './remark-directives';
+import { rehypeDispatch } from './rehype-dispatch';
+import type { ComponentRegistry } from './registry';
+
+export interface RendererOptions {
+	/** A site's per-index motion formula for the top-level rise stagger
+	 *  (e.g. ecnordic's `(i) => '--rise:' + …`). Omit for no stagger. */
+	rise?: (idx: number) => string;
+}
+
+/** Compose a site's render pipeline from its component registry: directive syntax →
+ *  stamped markers → registry-built hast. Returns `renderMarkdown` plus the remark/
+ *  rehype plugin arrays (so the Carta editor preview can reuse the exact same set). */
+export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
+	const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
+	const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.rise], rehypeSlug];
+	const processor = unified()
+		.use(remarkParse)
+		.use(remarkGfm)
+		.use(remarkPlugins)
+		.use(remarkRehype, { allowDangerousHtml: true })
+		.use(rehypePlugins)
+		.use(rehypeStringify);
+	return {
+		remarkPlugins,
+		rehypePlugins,
+		renderMarkdown: async (content: string): Promise<string> => String(await processor.process(content)),
+	};
+}

package/src/lib/render/registry.ts

@@ -0,0 +1,36 @@
+import type { Element } from 'hast';
+
+/** A site component: how it inserts (editor) and how it renders (rehype). */
+export interface ComponentDef {
+	/** Directive name, e.g. 'card' (matches `:::card`). */
+	name: string;
+	/** Palette label. */
+	label: string;
+	/** Palette description. */
+	description: string;
+	/** Markdown scaffold inserted at the cursor by the editor palette. */
+	insertTemplate: string;
+	/** Build the final hast element from the stamped directive element. */
+	build: (node: Element, rise?: string) => Element;
+	/** Optional role→default-icon (e.g. `{ caution: 'warning' }`). */
+	defaultIconByRole?: Record<string, string>;
+}
+
+export interface ComponentRegistry {
+	defs: ComponentDef[];
+	names: string[];
+	get(name: string): ComponentDef | undefined;
+	defaultIcon(name: string, role?: string): string | undefined;
+}
+
+/** Build a registry from a site's component definitions. The single source the
+ *  render pipeline (directive stamp + rehype dispatch) and the editor palette read. */
+export function defineRegistry(input: { components: ComponentDef[] }): ComponentRegistry {
+	const byName = new Map(input.components.map((c) => [c.name, c]));
+	return {
+		defs: input.components,
+		names: input.components.map((c) => c.name),
+		get: (name) => byName.get(name),
+		defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
+	};
+}

package/src/lib/render/rehype-dispatch.ts

@@ -0,0 +1,97 @@
+import type { Root, Element, ElementContent, Properties } from 'hast';
+import { h } from 'hastscript';
+import type { ComponentRegistry } from './registry';
+
+export function isElement(node: ElementContent | undefined): node is Element {
+	return !!node && node.type === 'element';
+}
+
+// hast Properties values are PropertyValue (string | number | boolean | array | null).
+// Directive markers (dataIcon/dataRole/dataPrimitive) are always stamped as strings;
+// this reads them back with that guarantee instead of casting at each call site.
+export function strProp(node: Element, name: string): string | undefined {
+	const value = node.properties?.[name];
+	return typeof value === 'string' ? value : undefined;
+}
+
+/** Wrap a pre-built glyph in an ec-icon span; secondary role adds the modifier. */
+export function iconSpan(glyphEl: Element, role?: string): Element {
+	const className = role === 'secondary' ? ['ec-icon', 'ec-icon-secondary'] : ['ec-icon'];
+	return h('span', { className }, [glyphEl]);
+}
+
+/** A site's icon factory: turn a stamped icon name + role into a hast element. */
+export type MakeIcon = (name: string, role?: string) => Element;
+
+// Pull the section's <h2> out, retag it .card-title, and build the .ec-head row
+// (optional icon + heading). Returns the head plus the remaining body children.
+// `makeIcon` (site-supplied) turns the stamped data-icon into an element; omit it
+// for a head with no icon.
+export function splitHead(node: Element, makeIcon?: MakeIcon): { head: Element; rest: ElementContent[] } {
+	const children = node.children as ElementContent[];
+	const i = children.findIndex((c) => isElement(c) && c.tagName === 'h2');
+	const h2 = children[i] as Element;
+	h2.properties = { ...h2.properties, className: ['card-title'] };
+	const rest = children.filter((_, j) => j !== i);
+	const icon = strProp(node, 'dataIcon');
+	const role = strProp(node, 'dataRole');
+	const headKids: ElementContent[] = [];
+	if (makeIcon && icon) headKids.push(makeIcon(icon, role));
+	headKids.push(h2);
+	return { head: h('div', { className: ['ec-head'] }, headKids), rest };
+}
+
+/** Section wrapper: `<section class=…><div class="card-body">…</div></section>`,
+ *  with an optional inline rise style. */
+export function cardShell(classes: string[], rise: string | undefined, body: ElementContent[]): Element {
+	const properties: Properties = { className: classes };
+	if (rise) properties.style = rise;
+	return h('section', properties, [h('div', { className: ['card-body'] }, body)]);
+}
+
+/** Tag the first <ul> among children with `ec-grid` and strip its whitespace-only
+ *  text nodes so the bare list serializes without newlines. Returns that <ul>. */
+export function markFirstList(children: ElementContent[]): Element | undefined {
+	const ul = children.find((c) => isElement(c) && c.tagName === 'ul') as Element | undefined;
+	if (ul) {
+		ul.properties = { ...ul.properties, className: ['ec-grid'] };
+		ul.children = (ul.children as ElementContent[]).filter(
+			(c) => !(c.type === 'text' && /^\s*$/.test(c.value)),
+		);
+	}
+	return ul;
+}
+
+// Recurse into a node's children, transforming any nested primitive sections
+// (a grid inside a card, panels inside a split) WITHOUT a rise stagger.
+function transformChildren(children: ElementContent[], registry: ComponentRegistry): ElementContent[] {
+	return children.map((c) => {
+		if (isElement(c) && c.properties?.dataPrimitive) return transformNode(c, registry);
+		if (isElement(c)) c.children = transformChildren(c.children as ElementContent[], registry);
+		return c;
+	});
+}
+
+function transformNode(node: Element, registry: ComponentRegistry, rise?: string): Element {
+	node.children = transformChildren(node.children as ElementContent[], registry);
+	const name = strProp(node, 'dataPrimitive');
+	const def = name ? registry.get(name) : undefined;
+	return def ? def.build(node, rise) : node;
+}
+
+/** Rehype transformer: dispatch each stamped element through its registry `build`
+ *  fn. Top-level primitives get a document-order rise stagger when `rise` is
+ *  supplied (a site's per-index motion formula); nested ones don't. Non-primitive
+ *  content (lede, intro paragraphs, the page-toc nav) passes through untouched. */
+export function rehypeDispatch(registry: ComponentRegistry, rise?: (idx: number) => string) {
+	return (tree: Root) => {
+		let idx = 0;
+		tree.children = (tree.children as ElementContent[]).map((child) => {
+			if (isElement(child) && child.properties?.dataPrimitive) {
+				return transformNode(child, registry, rise ? rise(idx++) : undefined);
+			}
+			if (isElement(child)) child.children = transformChildren(child.children as ElementContent[], registry);
+			return child;
+		});
+	};
+}