@glw907/cairn-cms 0.4.0 → 0.5.1

package/dist/github.js

@@ -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).
 import { bytesToB64url } from './utils';
@@ -64,7 +64,7 @@ function derLength(n) {
 }
 // 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) {
     const octet = [0x04, ...derLength(pkcs1.length), ...pkcs1];
     const body = [0x02, 0x01, 0x00, ...RSA_ALG_ID, ...octet];
@@ -97,7 +97,7 @@ export async function installationToken(creds) {
         throw new Error(`GitHub installation token failed: ${res.status}`);
     return (await res.json()).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) {
     return btoa(Array.from(encoder.encode(text), (b) => String.fromCharCode(b)).join(''));
 }
@@ -110,11 +110,25 @@ export async function fileSha(repo, path, token) {
         throw new Error(`GitHub stat ${path} failed: ${res.status}`);
     return (await res.json()).sha;
 }
+/**
+ * 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 {
+    path;
+    constructor(path) {
+        super(`Commit conflict on ${path}: it changed since it was opened`);
+        this.path = path;
+        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, path, content, opts, token) {
     const sha = await fileSha(repo, path, token);
@@ -130,7 +144,28 @@ export async function commitFile(repo, path, content, opts, token) {
             ...(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()).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, privateKeyB64) {
+    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/dist/index.d.ts

@@ -3,4 +3,7 @@ export * from './github';
 export * from './carta';
 export * from './content';
 export * from './adapter';
+export * from './slug';
+export * from './render';
+export * from './nav';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAEA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAEA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC"}

package/dist/index.js

@@ -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/dist/nav.d.ts

@@ -0,0 +1,58 @@
+/** 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 declare const MAX_NAV_NODES = 200;
+export declare class NavValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function validateNavTree(value: unknown, maxDepth: number): NavNode[];
+/**
+ * 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 declare class SiteConfigError extends Error {
+    constructor(message: string);
+}
+/** Parse the YAML site-config text into a typed object. Throws SiteConfigError on a malformed root. */
+export declare function parseSiteConfig(raw: string): SiteConfig;
+/** Extract one named menu from a parsed config and validate it. Returns [] when the menu is absent. */
+export declare function extractMenu(config: SiteConfig, name: string, maxDepth: number): NavNode[];
+/**
+ * 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 declare function setMenu(raw: string, name: string, tree: NavNode[]): string;
+//# sourceMappingURL=nav.d.ts.map

package/dist/nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.d.ts","sourceRoot":"","sources":["../src/lib/nav.ts"],"names":[],"mappings":"AAOA,8GAA8G;AAC9G,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB;AAED,+EAA+E;AAC/E,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAuB3E;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,MAAM,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,QAAQ,CAAC,EAAE;QACT,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAUvD;AAED,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAIzF;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAO1E"}

package/dist/nav.js

@@ -0,0 +1,86 @@
+// 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';
+/** 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) {
+        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, maxDepth) {
+    let count = 0;
+    function walk(nodes, depth) {
+        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;
+            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 = { 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);
+}
+export class SiteConfigError extends Error {
+    constructor(message) {
+        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) {
+    const parsed = parseYaml(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new SiteConfigError('Site config must be a YAML mapping');
+    }
+    const { siteName } = parsed;
+    if (typeof siteName !== 'string' || !siteName.trim()) {
+        throw new SiteConfigError('Site config needs a siteName');
+    }
+    return parsed;
+}
+/** Extract one named menu from a parsed config and validate it. Returns [] when the menu is absent. */
+export function extractMenu(config, name, maxDepth) {
+    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, name, tree) {
+    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/dist/render/glyph.d.ts

@@ -0,0 +1,6 @@
+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 declare function glyph(name: string, icons: IconSet): Element;
+//# sourceMappingURL=glyph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"glyph.d.ts","sourceRoot":"","sources":["../../src/lib/render/glyph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,qEAAqE;AACrE,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7C,4FAA4F;AAC5F,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAM3D"}

package/dist/render/glyph.js

@@ -0,0 +1,5 @@
+import { s } from 'hastscript';
+/** Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill. */
+export function glyph(name, icons) {
+    return s('svg', { className: ['ec-glyph'], viewBox: '0 0 256 256', fill: 'currentColor', ariaHidden: 'true' }, [s('path', { d: icons[name] })]);
+}

package/dist/render/index.d.ts

@@ -0,0 +1,6 @@
+export * from './registry';
+export * from './glyph';
+export * from './remark-directives';
+export * from './rehype-dispatch';
+export * from './pipeline';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/render/index.ts"],"names":[],"mappings":"AAGA,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/dist/render/index.js

@@ -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/dist/render/pipeline.d.ts

@@ -0,0 +1,16 @@
+import { type PluggableList } from 'unified';
+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 declare function createRenderer(registry: ComponentRegistry, options?: RendererOptions): {
+    remarkPlugins: PluggableList;
+    rehypePlugins: PluggableList;
+    renderMarkdown: (content: string) => Promise<string>;
+};
+//# sourceMappingURL=pipeline.d.ts.map

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

@@ -0,0 +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;AAUtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC/B;yEACqE;IACrE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/B;AAED;;uFAEuF;AACvF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,GAAE,eAAoB;;;8BAavD,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;EAEzD"}

package/dist/render/pipeline.js

@@ -0,0 +1,29 @@
+import { unified } 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';
+/** 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, options = {}) {
+    const remarkPlugins = [remarkDirective, [remarkDirectiveStamp, registry]];
+    const rehypePlugins = [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(await processor.process(content)),
+    };
+}

package/dist/render/registry.d.ts

@@ -0,0 +1,28 @@
+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 declare function defineRegistry(input: {
+    components: ComponentDef[];
+}): ComponentRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/lib/render/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC5B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAC5C,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC7D;AAED;uFACuF;AACvF,wBAAgB,cAAc,CAAC,KAAK,EAAE;IAAE,UAAU,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG,iBAAiB,CAQvF"}

package/dist/render/registry.js

@@ -0,0 +1,11 @@
+/** 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) {
+    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/dist/render/rehype-dispatch.d.ts

@@ -0,0 +1,24 @@
+import type { Root, Element, ElementContent } from 'hast';
+import type { ComponentRegistry } from './registry';
+export declare function isElement(node: ElementContent | undefined): node is Element;
+export declare function strProp(node: Element, name: string): string | undefined;
+/** Wrap a pre-built glyph in an ec-icon span; secondary role adds the modifier. */
+export declare function iconSpan(glyphEl: Element, role?: string): Element;
+/** A site's icon factory: turn a stamped icon name + role into a hast element. */
+export type MakeIcon = (name: string, role?: string) => Element;
+export declare function splitHead(node: Element, makeIcon?: MakeIcon): {
+    head: Element;
+    rest: ElementContent[];
+};
+/** Section wrapper: `<section class=…><div class="card-body">…</div></section>`,
+ *  with an optional inline rise style. */
+export declare function cardShell(classes: string[], rise: string | undefined, body: ElementContent[]): Element;
+/** 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 declare function markFirstList(children: ElementContent[]): Element | undefined;
+/** 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 declare function rehypeDispatch(registry: ComponentRegistry, rise?: (idx: number) => string): (tree: Root) => void;
+//# sourceMappingURL=rehype-dispatch.d.ts.map

package/dist/render/rehype-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehype-dispatch.d.ts","sourceRoot":"","sources":["../../src/lib/render/rehype-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAc,MAAM,MAAM,CAAC;AAEtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,wBAAgB,SAAS,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,IAAI,OAAO,CAE3E;AAKD,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGvE;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAGjE;AAED,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;AAMhE,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,cAAc,EAAE,CAAA;CAAE,CAYvG;AAED;0CAC0C;AAC1C,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,OAAO,CAItG;AAED;kFACkF;AAClF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,GAAG,SAAS,CAS7E;AAmBD;;;mFAGmF;AACnF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,IACjF,MAAM,IAAI,UAUlB"}

package/dist/render/rehype-dispatch.js

@@ -0,0 +1,86 @@
+import { h } from 'hastscript';
+export function isElement(node) {
+    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, name) {
+    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, role) {
+    const className = role === 'secondary' ? ['ec-icon', 'ec-icon-secondary'] : ['ec-icon'];
+    return h('span', { className }, [glyphEl]);
+}
+// 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, makeIcon) {
+    const children = node.children;
+    const i = children.findIndex((c) => isElement(c) && c.tagName === 'h2');
+    const h2 = children[i];
+    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 = [];
+    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, rise, body) {
+    const 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) {
+    const ul = children.find((c) => isElement(c) && c.tagName === 'ul');
+    if (ul) {
+        ul.properties = { ...ul.properties, className: ['ec-grid'] };
+        ul.children = ul.children.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, registry) {
+    return children.map((c) => {
+        if (isElement(c) && c.properties?.dataPrimitive)
+            return transformNode(c, registry);
+        if (isElement(c))
+            c.children = transformChildren(c.children, registry);
+        return c;
+    });
+}
+function transformNode(node, registry, rise) {
+    node.children = transformChildren(node.children, 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, rise) {
+    return (tree) => {
+        let idx = 0;
+        tree.children = tree.children.map((child) => {
+            if (isElement(child) && child.properties?.dataPrimitive) {
+                return transformNode(child, registry, rise ? rise(idx++) : undefined);
+            }
+            if (isElement(child))
+                child.children = transformChildren(child.children, registry);
+            return child;
+        });
+    };
+}

package/dist/render/remark-directives.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+import type { ComponentRegistry } from './registry';
+export declare function remarkDirectiveStamp(registry: ComponentRegistry): (tree: Root) => void;
+//# sourceMappingURL=remark-directives.d.ts.map

package/dist/render/remark-directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remark-directives.d.ts","sourceRoot":"","sources":["../../src/lib/render/remark-directives.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8B,IAAI,EAAQ,MAAM,OAAO,CAAC;AAGpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAmCpD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,IAEvD,MAAM,IAAI,UA8BlB"}

package/dist/render/remark-directives.js

@@ -0,0 +1,74 @@
+import { visit } from 'unist-util-visit';
+// Reconstruct a directive's authored attribute block (`{#id .class key="value"}`).
+// Accidental prose directives carry none, so this is almost always empty.
+function serializeAttributes(attributes) {
+    if (!attributes)
+        return '';
+    const tokens = [];
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value == null)
+            tokens.push(key);
+        else if (key === 'id')
+            tokens.push(`#${value}`);
+        else if (key === 'class')
+            for (const c of value.split(/\s+/).filter(Boolean))
+                tokens.push(`.${c}`);
+        else
+            tokens.push(`${key}="${value}"`);
+    }
+    return tokens.length ? `{${tokens.join(' ')}}` : '';
+}
+// The vocabulary is container-only (`:::name`). A text directive (`:name`) or
+// leaf directive (`::name`) is therefore always an accidental colon in prose
+// ("4:00", "9:30", "ratio 16:9") that micromark tokenized as a directive.
+// Restore it to its literal source text so prose renders verbatim.
+function restoreLiteral(node) {
+    const marker = node.type === 'leafDirective' ? '::' : ':';
+    const attrs = serializeAttributes(node.attributes);
+    if (node.children.length === 0) {
+        return [{ type: 'text', value: marker + node.name + attrs }];
+    }
+    const open = { type: 'text', value: `${marker}${node.name}[` };
+    const close = { type: 'text', value: `]${attrs}` };
+    return [open, ...node.children, close];
+}
+// Stamp each registered container directive with data-* markers carrying its
+// component name, icon, and role. No structure is built here; the rehype
+// dispatcher rewrites the marked elements once their children are hast.
+// Text and leaf directives are restored to literal text (accidental prose colons).
+export function remarkDirectiveStamp(registry) {
+    const known = new Set(registry.names);
+    return (tree) => {
+        visit(tree, 'containerDirective', (node) => {
+            if (!known.has(node.name))
+                return;
+            const attrs = node.attributes ?? {};
+            const role = attrs.role || undefined;
+            let icon = attrs.icon || undefined;
+            if (!icon && role)
+                icon = registry.defaultIcon(node.name, role);
+            const properties = { dataPrimitive: node.name };
+            if (icon)
+                properties.dataIcon = icon;
+            if (role)
+                properties.dataRole = role;
+            const data = node.data ?? (node.data = {});
+            data.hName = 'div';
+            data.hProperties = properties;
+        });
+        visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {
+            if (!parent || index == null)
+                return;
+            const literal = restoreLiteral(node);
+            if (node.type === 'leafDirective') {
+                // Leaf directives sit at block level; wrap the restored text in a paragraph.
+                const paragraph = { type: 'paragraph', children: literal };
+                parent.children.splice(index, 1, paragraph);
+            }
+            else {
+                parent.children.splice(index, 1, ...literal);
+            }
+            return index;
+        });
+    };
+}

package/dist/slug.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Lowercase a title into a filename-safe slug stem.
+ * Apostrophes are dropped so "Geoff's" becomes "geoffs" (no spurious hyphen).
+ * All other non-alphanumeric runs become a single hyphen; leading/trailing hyphens are trimmed.
+ */
+export declare function slugify(title: string): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../src/lib/slug.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM7C"}

package/dist/slug.js

@@ -0,0 +1,15 @@
+// cairn-core: derive a filename-safe slug stem from a human title, for the create-entry form.
+// The admin is filename-based (Pass E): this produces the editable stem an author can adjust,
+// matching the server-side SLUG_RE (lowercase alphanumerics and internal hyphens). Pure.
+/**
+ * Lowercase a title into a filename-safe slug stem.
+ * Apostrophes are dropped so "Geoff's" becomes "geoffs" (no spurious hyphen).
+ * All other non-alphanumeric runs become a single hyphen; leading/trailing hyphens are trimmed.
+ */
+export function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/'/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}