@glw907/cairn-cms 0.5.1 → 0.6.0-rc.1

package/src/lib/github/types.ts

@@ -0,0 +1,46 @@
+// src/lib/github/types.ts
+// cairn-cms: the GitHub backend's plain data types and its one typed error. The backend
+// reads repo coordinates from the adapter's `BackendConfig` (spec §8); `RepoRef` is the
+// `{ owner, repo, branch }` subset, so `backend` is assignable wherever a `RepoRef` is
+// wanted with no conversion.
+
+/** Repo coordinates pinned to a branch: the structural subset of `BackendConfig` the read and commit paths need. */
+export interface RepoRef {
+  owner: string;
+  repo: string;
+  branch: string;
+}
+
+/** A markdown file in a concept directory. `id` is the filename without `.md`. */
+export interface RepoFile {
+  id: string;
+  name: string;
+  path: string;
+}
+
+/** A commit author: the signed-in editor (spec §7.4). The committer is left to the App. */
+export interface CommitAuthor {
+  name: string;
+  email: string;
+}
+
+/** What the App signer needs: the app id, the installation, and the base64 PEM secret. */
+export interface AppCredentials {
+  appId: string;
+  installationId: string;
+  /** The stored `GITHUB_APP_PRIVATE_KEY_B64`: base64 of the PEM, single line. */
+  privateKeyB64: string;
+}
+
+/**
+ * A concurrent edit lost the SHA race: the file changed between the read and the PUT, from
+ * another editor or the site's own CI. Thrown so the save fails 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, unlike kit's `redirect`/`error` across the peer boundary.
+ */
+export class CommitConflictError extends Error {
+  constructor(public readonly path: string) {
+    super(`Commit conflict on ${path}: it changed since it was opened`);
+    this.name = 'CommitConflictError';
+  }
+}

package/src/lib/index.ts

@@ -1,10 +1,86 @@
-// cairn-cms public API. Consumers import content/email/github/adapter from 'cairn-cms';
-// auth (better-auth factory, guards, manage-editors) lives at the 'cairn-cms/auth' subpath.
-export * from './email';
-export * from './github';
-export * from './carta';
-export * from './content';
-export * from './adapter';
-export * from './slug';
-export * from './render';
-export * from './nav';
+// Engine entry. Auth landed in Plan 01, the content model and adapter in Plan 02, and the
+// GitHub read-and-commit backend in Plan 03; render and nav follow.
+export { requireOrigin } from './env.js';
+export type { Role, Editor, AuthEnv } from './auth/types.js';
+export type { AuthBranding, MagicLinkMessage, SendMagicLink } from './email.js';
+export { buildMagicLinkMessage, cloudflareSend } from './email.js';
+
+// Content model and adapter contract (Plan 02).
+export type {
+  CairnAdapter,
+  ConceptConfig,
+  FrontmatterField,
+  TextField,
+  TextareaField,
+  DateField,
+  BooleanField,
+  TagsField,
+  FreeTagsField,
+  ValidationResult,
+  BackendConfig,
+  SenderConfig,
+  NavMenuConfig,
+  AssetConfig,
+  RoutingRule,
+  ConceptDescriptor,
+  CairnExtension,
+  CairnRuntime,
+  AdminPanel,
+  FieldTypeDef,
+} from './content/types.js';
+export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
+export { composeRuntime } from './content/compose.js';
+export {
+  frontmatterFromForm,
+  dateInputValue,
+  serializeMarkdown,
+  parseMarkdown,
+} from './content/frontmatter.js';
+export { validateFields } from './content/validate.js';
+export { isValidId, idFromFilename, filenameFromId, slugify } from './content/ids.js';
+// Render engine (Plan 04): generic directive pipeline; sites own the component registry.
+export { defineRegistry } from './render/registry.js';
+export type { ComponentDef, ComponentRegistry } from './render/registry.js';
+export { glyph } from './render/glyph.js';
+export type { IconSet } from './render/glyph.js';
+export { remarkDirectiveStamp } from './render/remark-directives.js';
+export {
+  rehypeDispatch,
+  isElement,
+  strProp,
+  iconSpan,
+  splitHead,
+  cardShell,
+  markFirstList,
+} from './render/rehype-dispatch.js';
+export type { MakeIcon } from './render/rehype-dispatch.js';
+export { createRenderer } from './render/pipeline.js';
+export type { RendererOptions } from './render/pipeline.js';
+
+// GitHub read-and-commit backend (Plan 03).
+export type { RepoRef, RepoFile, CommitAuthor, AppCredentials } from './github/types.js';
+export { CommitConflictError } from './github/types.js';
+export { appJwt, installationToken, signingSelfTest } from './github/signing.js';
+export {
+  treeUrl,
+  markdownFilesIn,
+  listMarkdown,
+  contentsUrl,
+  readRaw,
+  fileSha,
+  commitFile,
+} from './github/repo.js';
+export { appCredentials } from './github/credentials.js';
+export type { GithubKeyEnv } from './github/credentials.js';
+
+// Nav tree and site-config helpers (Plan 06).
+export {
+  parseSiteConfig,
+  extractMenu,
+  setMenu,
+  validateNavTree,
+  MAX_NAV_NODES,
+  NavValidationError,
+  SiteConfigError,
+} from './nav/site-config.js';
+export type { NavNode, SiteConfig } from './nav/site-config.js';

package/src/lib/{nav.ts → nav/site-config.ts}

@@ -1,11 +1,10 @@
-// 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.
-
+// The navigation tree and its YAML site-config. A menu lives in the site's git-committed config
+// 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. This module is pure: parse, validate, and
+// rewrite only. The engine returns data; each site renders the tree with its own 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. */
+/** One navigation node. An omitted or empty `url` is a label-only grouping header; no `children` is a leaf. */
 export interface NavNode {
   label: string;
   url?: string;
@@ -15,6 +14,15 @@ export interface NavNode {
 /** Total node cap across the whole tree, a guard against a runaway payload. */
 export const MAX_NAV_NODES = 200;
 
+/** Maximum character length for a node label. */
+export const MAX_LABEL_LENGTH = 500;
+
+/** Maximum character length for a node URL. */
+export const MAX_URL_LENGTH = 2048;
+
+/** Allowlist for safe URL schemes: site-relative, in-page anchors, http(s), mailto, and tel. */
+const SAFE_URL = /^(\/|#|https?:\/\/|mailto:|tel:)/i;
+
 export class NavValidationError extends Error {
   constructor(message: string) {
     super(message);
@@ -23,9 +31,9 @@ export class NavValidationError extends Error {
 }
 
 /**
- * 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.
+ * Validate and normalize an untrusted value into a NavNode[]: arrays only, non-empty labels, depth
+ * within `maxDepth` (1 is flat), a 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;
@@ -38,9 +46,15 @@ export function validateNavTree(value: unknown, maxDepth: number): NavNode[] {
       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 (label.length > MAX_LABEL_LENGTH) throw new NavValidationError('Label is too long (max 500 characters)');
       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 (typeof item.url === 'string' && item.url.trim()) {
+        const url = item.url.trim();
+        if (url.length > MAX_URL_LENGTH) throw new NavValidationError('URL is too long (max 2048 characters)');
+        if (!SAFE_URL.test(url)) throw new NavValidationError('URL must start with /, #, http(s)://, mailto:, or tel:');
+        node.url = url;
+      }
       if (item.children !== undefined) {
         const children = walk(item.children, depth + 1);
         if (children.length) node.children = children;
@@ -53,8 +67,8 @@ export 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.
+ * 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;
@@ -64,14 +78,7 @@ export interface SiteConfig {
   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;
-  };
+  [key: string]: unknown;
 }
 
 export class SiteConfigError extends Error {
@@ -102,10 +109,10 @@ export function extractMenu(config: SiteConfig, name: string, maxDepth: number):
 }
 
 /**
- * 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.
+ * Replace one named menu in the YAML site-config text and reserialize, preserving every other
+ * top-level key (siteName, other menus, settings). Parses into a Document so the rest of the file
+ * round-trips. YAML comments are not preserved (an accepted trade); 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);

package/src/lib/render/glyph.ts

@@ -1,14 +1,14 @@
 import { s } from 'hastscript';
 import type { Element } from 'hast';
 
-/** A glyph name → SVG path-data map (the site owns the icon set). */
+/** A glyph name to 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] })],
-	);
+  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

@@ -1,8 +1,8 @@
-// cairn-cms render engine: a directive-driven markdown → HTML pipeline whose
+// cairn-cms render engine: a directive-driven markdown to 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';
+export * from './registry.js';
+export * from './glyph.js';
+export * from './remark-directives.js';
+export * from './rehype-dispatch.js';
+export * from './pipeline.js';

package/src/lib/render/pipeline.ts

@@ -6,32 +6,33 @@ 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';
+import { remarkDirectiveStamp } from './remark-directives.js';
+import { rehypeDispatch } from './rehype-dispatch.js';
+import type { ComponentRegistry } from './registry.js';
 
 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;
+  /** Stamp a `data-rise` ordinal (0, 1, 2, …) on each top-level component so a site's
+   *  CSS can drive an entrance-cascade delay off it. Omit for no stagger. The ordinal
+   *  is inert, so a consumer's sanitize floor can keep `data-rise` and drop `style`. */
+  stagger?: boolean;
 }
 
-/** Compose a site's render pipeline from its component registry: directive syntax →
- *  stamped markers → registry-built hast. Returns `renderMarkdown` plus the remark/
+/** 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 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)),
-	};
+  const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
+  const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.stagger], 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

@@ -1,36 +1,45 @@
+// cairn-cms: the directive component registry (seam 3). One declaration per component,
+// carrying how it inserts in the editor and how it renders in rehype. The render pipeline
+// (Plan 04) and the future component palette both derive from this single source, so the
+// parser, the render dispatch, and the editor never drift apart. The adapter references
+// `ComponentRegistry` from here.
 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>;
+  /** 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. The engine
+   *  stamps the entrance-stagger ordinal (`data-rise`) on the top-level result, so a
+   *  build fn stays free of any motion concern. */
+  build: (node: Element) => Element;
+  /** Optional role-to-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;
+  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),
-	};
+/**
+ * Build a registry from a site's component definitions. The single source the render
+ * pipeline (directive stamp plus rehype dispatch) and the editor palette both read.
+ */
+export function defineRegistry({ components }: { components: ComponentDef[] }): ComponentRegistry {
+  const byName = new Map(components.map((c) => [c.name, c]));
+  return {
+    defs: components,
+    names: 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

@@ -1,23 +1,23 @@
-import type { Root, Element, ElementContent, Properties } from 'hast';
+import type { Root, Element, ElementContent } from 'hast';
 import { h } from 'hastscript';
-import type { ComponentRegistry } from './registry';
+import type { ComponentRegistry } from './registry.js';
 
 export function isElement(node: ElementContent | undefined): node is Element {
-	return !!node && node.type === '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;
+  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]);
+  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. */
@@ -28,70 +28,72 @@ export type MakeIcon = (name: string, role?: string) => Element;
 // `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 };
+  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)]);
+/** Section wrapper: `<section class=…><div class="card-body">…</div></section>`. */
+export function cardShell(classes: string[], body: ElementContent[]): Element {
+  return h('section', { className: classes }, [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;
+  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.
+// (a grid inside a card, panels inside a split). Nested primitives never carry the
+// entrance stagger; only top-level ones do (stamped in the transformer below).
 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;
-	});
+  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;
+function transformNode(node: Element, registry: ComponentRegistry): 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) : 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
+ *  fn. When `stagger` is on, each top-level primitive gets a `data-rise` attribute
+ *  carrying its document-order index (0, 1, 2, …); the site's CSS maps that ordinal
+ *  to an entrance delay. The index is inert, so a consumer's sanitize floor can keep
+ *  `data-rise` while dropping `style`. Nested primitives never get it. 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;
-		});
-	};
+export function rehypeDispatch(registry: ComponentRegistry, stagger?: boolean) {
+  return (tree: Root) => {
+    let idx = 0;
+    tree.children = (tree.children as ElementContent[]).map((child) => {
+      if (isElement(child) && child.properties?.dataPrimitive) {
+        const el = transformNode(child, registry);
+        if (stagger) el.properties = { ...el.properties, dataRise: String(idx++) };
+        return el;
+      }
+      if (isElement(child)) child.children = transformChildren(child.children as ElementContent[], registry);
+      return child;
+    });
+  };
 }