@glw907/cairn-cms 0.68.0 → 0.76.0

package/src/lib/media/usage.ts

@@ -19,10 +19,8 @@
 // is therefore "found in N entries" / "no references found", never a bare "unused": absence of a row
 // means no reference was found, not a proof that none exists.
 import type { ConceptDescriptor } from '../content/types.js';
-import type { RepoRef } from '../github/types.js';
+import type { Backend } from '../github/backend.js';
 import type { Manifest } from '../content/manifest.js';
-import { listBranches } from '../github/branches.js';
-import { readRaw } from '../github/repo.js';
 import { PENDING_PREFIX, parsePendingBranch } from '../content/pending.js';
 import { findConcept } from '../content/concepts.js';
 import { isValidId, filenameFromId } from '../content/ids.js';
@@ -84,8 +82,7 @@ function push(index: UsageIndex, hash: string, entry: UsageEntry): void {
  * (the load path lists once for the media-union) rather than listing them a second time.
  */
 export async function buildUsageIndex(
-  repo: RepoRef,
-  token: string,
+  backend: Backend,
   concepts: ConceptDescriptor[],
   manifest: Manifest,
   opts: BuildUsageOptions = {},
@@ -108,7 +105,7 @@ export async function buildUsageIndex(
 
   // The branch arm: read each open cairn/* branch's one edited file. The path is derivable from the
   // branch name, so no tree-listing is needed. The branch list is reused when the caller passes it.
-  const names = opts.branches ?? (await listBranches(repo, PENDING_PREFIX, token));
+  const names = opts.branches ?? (await backend.listBranches(PENDING_PREFIX));
   // Read the branches in parallel rather than one at a time, so the latency floor is one round trip
   // instead of N. workerd self-throttles to 6 simultaneous outbound connections, so this batch and
   // the load path's media-union batch each stay under the limit; do NOT merge the two into one
@@ -125,7 +122,7 @@ export async function buildUsageIndex(
 
       const path = `${concept.dir}/${filenameFromId(ref.id)}`;
       try {
-        const raw = await readRaw({ ...repo, branch: name }, path, token);
+        const raw = await backend.readFile(path, name);
         if (raw === null) return []; // The file is absent on the branch: nothing to extract.
         const { frontmatter, body } = parseMarkdown(raw);
         const fmTitle = frontmatter.title;

package/src/lib/nav/site-config.ts

@@ -3,7 +3,6 @@
 // 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';
-import type { ConceptUrlPolicy } from '../content/types.js';
 
 /** One navigation node. An omitted or empty `url` is a label-only grouping header; no `children` is a leaf. */
 export interface NavNode {
@@ -75,12 +74,9 @@ 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>;
-  /** Per-concept URL policy: the permalink pattern and date-prefix granularity, keyed by concept id. */
-  content?: Record<string, ConceptUrlPolicy>;
   /**
    * The editor spellcheck settings. The dialect is declared once per site (spec 1.2), so a British
    *  site loads the British word list and "colour" reads as correct. Today only US English ships, so an
@@ -285,6 +281,14 @@ export function parseSiteConfig(raw: string): SiteConfig {
   if (typeof siteName !== 'string' || !siteName.trim()) {
     throw new SiteConfigError('Site config needs a siteName');
   }
+  // Contract v2 moved per-concept URL policy out of the YAML and onto defineConcept. A leftover
+  // `content:` block here would silently do nothing while the concept defaulted its permalink, so a
+  // half-migrated site (one carrying a non-default datePrefix) would rewrite every post URL. Fail loud.
+  if ((parsed as SiteConfig).content !== undefined) {
+    throw new SiteConfigError(
+      'cairn: site config no longer carries per-concept URL policy; move permalink/datePrefix into defineConcept (Contract v2)',
+    );
+  }
   return parsed as SiteConfig;
 }
 
@@ -295,11 +299,6 @@ export function extractMenu(config: SiteConfig, name: string, maxDepth: number):
   return validateNavTree(menu, maxDepth);
 }
 
-/** The per-concept URL policy from a parsed config, or an empty policy when the `content` key is absent. */
-export function urlPolicyFrom(config: SiteConfig): Record<string, ConceptUrlPolicy> {
-  return config.content ?? {};
-}
-
 /**
  * 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

package/src/lib/render/component-grammar.ts

@@ -9,17 +9,17 @@ const COLON = ':';
 
 function attrBlock(def: ComponentDef, values: ComponentValues): string {
   const parts: string[] = [];
-  for (const field of def.attributes ?? []) {
-    const v = values.attributes[field.key];
+  for (const [name, field] of Object.entries(def.attributes ?? {})) {
+    const v = values.attributes[name];
     if (field.type === 'boolean') {
-      if (v === true) parts.push(`${field.key}="true"`);
+      if (v === true) parts.push(`${name}="true"`);
     } else if (typeof v === 'string' && v !== '') {
       // The directive attribute grammar (mdast-util-directive) treats a literal `"` as the value
       // terminator and decodes HTML entities, so a backslash escape does not survive a round-trip.
       // Encode `&` first (so existing entities are not double-decoded) then `"`; the parser decodes
       // both back. A backslash is literal in this grammar and needs no escaping.
       const escaped = v.replace(/&/g, '&').replace(/"/g, '"');
-      parts.push(`${field.key}="${escaped}"`);
+      parts.push(`${name}="${escaped}"`);
     }
   }
   return parts.length ? `{${parts.join(' ')}}` : '';
@@ -103,10 +103,10 @@ function valuesFromRoot(root: (RootContent & DirectiveNode) | undefined, def: Co
   const values = emptyComponentValues(def);
   if (!root) return values;
 
-  for (const field of def.attributes ?? []) {
-    const raw = root.attributes?.[field.key];
-    if (field.type === 'boolean') values.attributes[field.key] = raw === 'true';
-    else if (typeof raw === 'string') values.attributes[field.key] = raw;
+  for (const [name, field] of Object.entries(def.attributes ?? {})) {
+    const raw = root.attributes?.[name];
+    if (field.type === 'boolean') values.attributes[name] = raw === 'true';
+    else if (typeof raw === 'string') values.attributes[name] = raw;
   }
 
   const titleSlot = slotByName(def, 'title');
@@ -181,7 +181,7 @@ export async function componentRoundTripSafety(markdown: string, def: ComponentD
   const root = findComponentRoot(markdown, def);
   if (!root) return { safe: false, reason: 'not-a-component' };
 
-  const declaredKeys = new Set((def.attributes ?? []).map((f) => f.key));
+  const declaredKeys = new Set(Object.keys(def.attributes ?? {}));
   for (const key of parseRawAttributeKeys(markdown, def)) {
     if (!declaredKeys.has(key)) return { safe: false, reason: 'unknown-attribute' };
   }
@@ -220,7 +220,7 @@ export async function parseComponentWithRawKeys(
 // here; the parse must overwrite only the fields actually present in the markdown.
 function emptyComponentValues(def: ComponentDef): ComponentValues {
   const attributes: Record<string, string | boolean> = {};
-  for (const f of def.attributes ?? []) attributes[f.key] = f.type === 'boolean' ? false : '';
+  for (const [name, field] of Object.entries(def.attributes ?? {})) attributes[name] = field.type === 'boolean' ? false : '';
   const slots: Record<string, string | string[]> = {};
   for (const s of def.slots ?? []) slots[s.name] = s.kind === 'repeatable' ? [] : '';
   return { attributes, slots };

package/src/lib/render/component-reference.ts

@@ -27,9 +27,10 @@ function componentSection(def: ComponentDef): string {
 /** Seed example values that show every declared field: an ellipsis for strings, one sample list item. */
 function exampleValues(def: ComponentDef): ComponentValues {
   const values = emptyValues(def);
-  for (const field of def.attributes ?? []) {
-    if (field.type === 'boolean') values.attributes[field.key] = false;
-    else values.attributes[field.key] = field.options?.[0] ?? '…';
+  for (const [name, field] of Object.entries(def.attributes ?? {})) {
+    if (field.type === 'boolean') values.attributes[name] = false;
+    else if (field.type === 'select') values.attributes[name] = field.options[0] ?? '…';
+    else values.attributes[name] = '…';
   }
   for (const slot of def.slots ?? []) {
     if (slot.kind === 'repeatable') values.slots[slot.name] = ['…'];

package/src/lib/render/component-validate.ts

@@ -1,38 +1,25 @@
 import { parseComponentWithRawKeys } from './component-grammar.js';
-import type { ComponentDef, ComponentValues } from './registry.js';
+import { fieldset } from '../content/fieldset.js';
+import type { ComponentDef } from './registry.js';
 
 /** A validation verdict: ok, or field-keyed error messages. */
 export type ComponentValidation = { ok: true } | { ok: false; errors: Record<string, string> };
 
 /**
- *
+ * Validate a serialized component directive against its definition: the attributes through the same
+ *  `fieldset` validator a concept field uses (coercion, constraints, required, select domain, pattern,
+ *  and any per-attribute `behavior.validate`), then the two component-only checks, an unknown attribute
+ *  key and an unfilled required slot.
  */
 export async function validateComponent(markdown: string, def: ComponentDef): Promise<ComponentValidation> {
   const { values, rawKeys } = await parseComponentWithRawKeys(markdown, def);
   const errors: Record<string, string> = {};
-  const declared = new Set((def.attributes ?? []).map((f) => f.key));
 
-  for (const field of def.attributes ?? []) {
-    const v = values.attributes[field.key];
-    const filled = field.type === 'boolean' ? true : typeof v === 'string' && v !== '';
-    if (field.required && !filled) {
-      errors[field.key] = `${field.label} is required.`;
-      continue;
-    }
-    if (field.type === 'select' && typeof v === 'string' && v !== '' && !(field.options ?? []).includes(v)) {
-      errors[field.key] = `${field.label} must be one of: ${(field.options ?? []).join(', ')}.`;
-      continue;
-    }
-    if (field.pattern && typeof v === 'string' && v !== '' && !new RegExp(field.pattern.source).test(v)) {
-      errors[field.key] = field.pattern.message;
-      continue;
-    }
-    if (field.validate) {
-      const message = runFieldValidator(def, field.key, () => field.validate!(v, values));
-      if (typeof message === 'string') errors[field.key] = message;
-    }
-  }
+  const schema = def.attributeSchema ?? fieldset(def.attributes ?? {}, { behavior: def.behavior });
+  const result = schema.validate(values.attributes, '');
+  if (!result.ok) Object.assign(errors, result.errors);
 
+  const declared = new Set(Object.keys(def.attributes ?? {}));
   for (const key of rawKeys) {
     if (!declared.has(key)) errors[key] = `Unknown attribute "${key}".`;
   }
@@ -46,15 +33,3 @@ export async function validateComponent(markdown: string, def: ComponentDef): Pr
 
   return Object.keys(errors).length ? { ok: false, errors } : { ok: true };
 }
-
-// Run a site-supplied attribute validator. The validator is author code, so a throw is contained:
-// the field is treated as valid and a dev-time warning names the component and field so the author
-// can find the bug. A returned string is the field error; anything else (null) is clean.
-function runFieldValidator(def: ComponentDef, key: string, call: () => string | null): string | null {
-  try {
-    return call();
-  } catch (err) {
-    console.warn(`cairn: validate() for component "${def.name}" field "${key}" threw; treating the field as valid.`, err);
-    return null;
-  }
-}

package/src/lib/render/pipeline.ts

@@ -20,12 +20,6 @@ import { defineRegistry, 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
-   *  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;
   /**
    * Extend the sanitize allowlist. Receives cairn's default schema (defaultSchema plus the
    *  directive markers and the common benign tags) and returns the schema to use. Add to the
@@ -73,7 +67,7 @@ export function createRenderer(
   const rehypePlugins: PluggableList = [
     rehypeRaw,
     ...floor,
-    [rehypeDispatch, registry, options.stagger],
+    [rehypeDispatch, registry],
     rehypeSlug,
     // Name each GFM task-list checkbox from its item text. It runs after the sanitize floor (which
     // does not allow aria-label) so the added attribute survives, and is content-not-sink, so it is

package/src/lib/render/registry.ts

@@ -4,33 +4,9 @@
 // parser, the render dispatch, and the editor never drift apart. The adapter references
 // `ComponentRegistry` from here.
 import type { Element, ElementContent } from 'hast';
-
-/** The input types a component attribute or repeatable item field can take. */
-export type FieldType = 'text' | 'select' | 'icon' | 'boolean';
-
-/** One `{key="value"}` attribute on a component directive, or one field of a repeatable item. */
-export interface AttributeField {
-  /** The attribute name as it appears in the directive, e.g. `icon`. */
-  key: string;
-  /** The form label. */
-  label: string;
-  type: FieldType;
-  required?: boolean;
-  /** Initial value; a string for text/select/icon, a boolean for boolean. */
-  default?: string | boolean;
-  /** Allowed values for `type: 'select'`. */
-  options?: readonly string[];
-  /** Helper text shown under the field. */
-  help?: string;
-  /** A RegExp `source` to validate the value against, plus the message to show on a mismatch. */
-  pattern?: { source: string; message: string };
-  /**
-   * A pure, browser-safe cross-field validator. Returns an error string, or null when valid.
-   *  Receives the field's value and the full {@link ComponentValues} so a rule can read sibling
-   *  fields. The picker wraps the call in try/catch so an author's throw never crashes the form.
-   */
-  validate?: (value: string | boolean, all: ComponentValues) => string | null;
-}
+import type { FieldDescriptor } from '../content/fields.js';
+import type { BehaviorTable, Fieldset } from '../content/fieldset.js';
+import { fieldset } from '../content/fieldset.js';
 
 export type SlotKind = 'markdown' | 'inline' | 'repeatable';
 
@@ -45,7 +21,7 @@ export interface SlotDef {
   required?: boolean;
   help?: string;
   /** For `kind: 'repeatable'`: the fields composing each list item (v1 uses the first field). */
-  itemFields?: AttributeField[];
+  itemFields?: Record<string, FieldDescriptor>;
   /**
    * For `kind: 'repeatable'`: derives a row's label from its item values and zero-based index.
    *  When it returns nothing, the picker falls back to `${label} ${index + 1}`.
@@ -82,10 +58,18 @@ export interface ComponentDef {
   insertTemplate?: string;
   /**
    * Build the final hast element from the component context (attributes plus partitioned
-   *  slots). The engine stamps the entrance-stagger ordinal (`data-rise`) on the top-level
+   *  slots). The engine stamps the entrance ordinal (`data-rise`) on the top-level
    *  result, so a build fn stays free of any motion concern.
    */
   build: (ctx: ComponentContext) => Element;
+  /**
+   * Opt this directive into client hydration (phase 4b islands). `true` mounts the island eagerly on
+   *  first load and after client-side navigation; `'visible'` defers the mount to first intersection.
+   *  The engine wraps {@link ComponentDef.build}'s output in an island boundary, and the site registers
+   *  the live Svelte component under the same name on `rendering.islands`. Absent leaves the directive a
+   *  static, server-only component.
+   */
+  hydrate?: boolean | 'visible';
   /**
    * Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. Maps a free-string role to a
    *  glyph key in the site IconSet; choose a logically representative glyph and prefer glyphs
@@ -95,8 +79,18 @@ export interface ComponentDef {
   defaultIconByRole?: Record<string, string>;
   /** One line on when to reach for this component; feeds the picker and the reference file. */
   use?: string;
-  /** The `{key="value"}` attributes this component accepts. */
-  attributes?: AttributeField[];
+  /** The `{key="value"}` attributes this component accepts, keyed by attribute name. */
+  attributes?: Record<string, FieldDescriptor>;
+  /**
+   * Per-attribute function-valued behavior (a cross-field `validate`), keyed by attribute name.
+   *  {@link defineComponent} bundles it into the attribute {@link Fieldset}.
+   */
+  behavior?: BehaviorTable;
+  /**
+   * The attribute validator {@link defineComponent} builds from `attributes` and `behavior`.
+   *  Engine-internal: the constructor sets it, and {@link validateComponent} runs it.
+   */
+  attributeSchema?: Fieldset;
   /** The named content regions this component accepts. */
   slots?: SlotDef[];
   /**
@@ -123,8 +117,8 @@ export interface ComponentRegistry {
   names: string[];
   get(name: string): ComponentDef | undefined;
   defaultIcon(name: string, role?: string): string | undefined;
-  /** The component's first `type:'icon'` attribute, or undefined when it declares none. */
-  iconField(name: string): AttributeField | undefined;
+  /** The name of the component's first `type:'icon'` attribute, or undefined when it declares none. */
+  iconField(name: string): string | undefined;
 }
 
 /**
@@ -137,12 +131,12 @@ export function dataAttrProp(key: string): string {
 }
 
 /**
- * A component's first `type:'icon'` attribute, or undefined when it declares none. Both the
- *  construction-time guard and the registry's `iconField` derive the icon field from this one
+ * The name of a component's first `type:'icon'` attribute, or undefined when it declares none. Both
+ *  the construction-time guard and the registry's `iconField` derive the icon field from this one
  *  predicate rather than spelling the `type === 'icon'` find twice.
  */
-function findIconField(def: ComponentDef): AttributeField | undefined {
-  return def.attributes?.find((field) => field.type === 'icon');
+function findIconField(def: ComponentDef): string | undefined {
+  return Object.entries(def.attributes ?? {}).find(([, field]) => field.type === 'icon')?.[0];
 }
 
 /**
@@ -209,8 +203,8 @@ export interface ComponentValues {
  */
 export function emptyValues(def: ComponentDef): ComponentValues {
   const attributes: Record<string, string | boolean> = {};
-  for (const field of def.attributes ?? []) {
-    attributes[field.key] = field.default ?? (field.type === 'boolean' ? false : '');
+  for (const [name, field] of Object.entries(def.attributes ?? {})) {
+    attributes[name] = field.default ?? (field.type === 'boolean' ? false : '');
   }
   const slots: Record<string, string | string[]> = {};
   for (const slot of def.slots ?? []) {
@@ -232,3 +226,28 @@ export function previewValues(def: ComponentDef): ComponentValues {
     slots: { ...base.slots, ...def.preview.slots },
   };
 }
+
+/** The descriptor types that serialize to a single directive-attribute string (decision 2). */
+const ATTRIBUTE_TYPES = new Set(['text', 'textarea', 'number', 'select', 'url', 'email', 'date', 'datetime', 'boolean', 'icon']);
+
+/** Reject an attribute type that cannot serialize to a single directive-attribute string (decision 2). */
+function checkComponentAttributes(name: string, attributes: Record<string, FieldDescriptor>): void {
+  for (const [key, field] of Object.entries(attributes)) {
+    if (!ATTRIBUTE_TYPES.has(field.type)) {
+      throw new Error(
+        `cairn: component "${name}" attribute "${key}" is type "${field.type}"; a directive attribute must be a single-value scalar (text, textarea, number, select, url, email, date, datetime, boolean, or icon).`,
+      );
+    }
+  }
+}
+
+/**
+ * Declare a site component, building its attribute validator from the `fields.*` descriptors and
+ *  validating the component at declaration. Mirrors {@link defineConcept}: a malformed attribute type
+ *  or pattern fails at module load. The built `attributeSchema` is what {@link validateComponent} runs.
+ */
+export function defineComponent<const D extends ComponentDef>(def: D): D & { attributeSchema: Fieldset } {
+  const attributes = def.attributes ?? {};
+  checkComponentAttributes(def.name, attributes);
+  return { ...def, attributeSchema: fieldset(attributes, { behavior: def.behavior }) };
+}

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

@@ -69,7 +69,7 @@ export function markFirstList(children: ElementContent[]): Element | undefined {
 
 // Recurse into a node's children, transforming any nested primitive sections
 // (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).
+// entrance ordinal; 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);
@@ -82,10 +82,10 @@ function transformChildren(children: ElementContent[], registry: ComponentRegist
 // 'true'/'false'; everything else is the literal string the author wrote.
 function readAttributes(node: Element, def: ComponentDef): Record<string, string | boolean> {
   const out: Record<string, string | boolean> = {};
-  for (const field of def.attributes ?? []) {
-    const value = strProp(node, dataAttrProp(field.key));
+  for (const [name, field] of Object.entries(def.attributes ?? {})) {
+    const value = strProp(node, dataAttrProp(name));
     if (value == null) continue;
-    out[field.key] = field.type === 'boolean' ? value === 'true' : value;
+    out[name] = field.type === 'boolean' ? value === 'true' : value;
   }
   return out;
 }
@@ -135,6 +135,40 @@ function partitionSlots(node: Element): {
   };
 }
 
+// Serialize a hydrate component's declared attributes into the island prop payload. A `number` field is
+// coerced from its stamped string to a JSON number here; a `boolean` already arrived as a real boolean
+// from readAttributes (which coerces 'true'/'false' upstream), and every other field stays the literal
+// string the author wrote. The result is JSON.stringify-ed into data-cairn-props and parsed on the client.
+function serializeIslandProps(
+  def: ComponentDef,
+  attributes: Record<string, string | boolean>,
+): Record<string, string | number | boolean> {
+  const out: Record<string, string | number | boolean> = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    const type = def.attributes?.[key]?.type;
+    out[key] = type === 'number' && typeof value === 'string' ? Number(value) : value;
+  }
+  return out;
+}
+
+// Wrap a hydrate component's static fallback in its island boundary. The boundary carries the directive
+// name and the JSON prop payload; a 'visible' island also carries data-cairn-hydrate="visible". The
+// boundary attributes are inert data-* and survive both the sanitize floor (this runs after it) and the
+// sink guard (which strips only style/on*). The fallback is build()'s no-JS, first-paint representation.
+function islandBoundary(
+  name: string,
+  def: ComponentDef,
+  attributes: Record<string, string | boolean>,
+  fallback: Element,
+): Element {
+  const properties: Record<string, string> = {
+    dataCairnIsland: name,
+    dataCairnProps: JSON.stringify(serializeIslandProps(def, attributes)),
+  };
+  if (def.hydrate === 'visible') properties.dataCairnHydrate = 'visible';
+  return { type: 'element', tagName: 'div', properties, children: [fallback] };
+}
+
 function transformNode(node: Element, registry: ComponentRegistry): Element {
   node.children = transformChildren(node.children as ElementContent[], registry);
   const name = strProp(node, 'dataPrimitive');
@@ -147,24 +181,25 @@ function transformNode(node: Element, registry: ComponentRegistry): Element {
     items: parts.items,
     node,
   };
-  return def.build(ctx);
+  const built = def.build(ctx);
+  return def.hydrate ? islandBoundary(name!, def, ctx.attributes, built) : built;
 }
 
 /**
  * Rehype transformer: dispatch each stamped element through its registry `build`
- *  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
+ *  fn. 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, stagger?: boolean) {
+export function rehypeDispatch(registry: ComponentRegistry) {
   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++) };
+        el.properties = { ...el.properties, dataRise: String(idx++) };
         return el;
       }
       if (isElement(child)) child.children = transformChildren(child.children as ElementContent[], registry);

package/src/lib/render/remark-directives.ts

@@ -62,8 +62,7 @@ export function remarkDirectiveStamp(registry: ComponentRegistry) {
       const def = registry.get(node.name);
       const attrs = node.attributes ?? {};
       const role = attrs.role || undefined;
-      const iconField = registry.iconField(node.name);
-      const iconKey = iconField?.key ?? 'icon';
+      const iconKey = registry.iconField(node.name) ?? 'icon';
       let icon = attrs[iconKey] || undefined;
       if (!icon && role) icon = registry.defaultIcon(node.name, role);
 
@@ -76,9 +75,9 @@ export function remarkDirectiveStamp(registry: ComponentRegistry) {
       // back to that default the same way a missing one does. data-attr-<key> survives to the
       // element; build() consumes it and returns a fresh element, so the marker never reaches the
       // published DOM.
-      for (const field of def?.attributes ?? []) {
-        const raw = field === iconField ? icon : attrs[field.key];
-        if (raw != null) properties[dataAttrProp(field.key)] = raw;
+      for (const name of Object.keys(def?.attributes ?? {})) {
+        const raw = name === iconKey ? icon : attrs[name];
+        if (raw != null) properties[dataAttrProp(name)] = raw;
       }
 
       const data = node.data ?? (node.data = {});

package/src/lib/render/sanitize-schema.ts

@@ -23,7 +23,7 @@ export function buildSanitizeSchema(
   registry: ComponentRegistry,
   extend?: (defaults: Schema) => Schema,
 ): Schema {
-  const attrMarkers = registry.defs.flatMap((d) => (d.attributes ?? []).map((a) => dataAttrProp(a.key)));
+  const attrMarkers = registry.defs.flatMap((d) => Object.keys(d.attributes ?? {}).map((key) => dataAttrProp(key)));
   const markers = [...FIXED_MARKERS, ...attrMarkers];
   const attributes = defaultSchema.attributes ?? {};
   // defaultSchema's `a` entry carries a className tuple (`['className', 'data-footnote-backref']`)

package/src/lib/sveltekit/cairn-admin.ts

@@ -22,7 +22,7 @@ import { createEditorRoutes } from './editors-routes.js';
 import { createNavRoutes, type NavLoadData } from './nav-routes.js';
 import type { AuthBranding, SendMagicLink } from '../email.js';
 import type { AuthEnv, Editor } from '../auth/types.js';
-import type { GithubKeyEnv } from '../github/credentials.js';
+import type { BackendEnv } from '../github/credentials.js';
 import type { CairnRuntime } from '../content/types.js';
 import type { CookieJar, EventBase } from './types.js';
 
@@ -31,20 +31,20 @@ import type { CookieJar, EventBase } from './types.js';
  * (ContentEvent minus params, which the dispatcher synthesizes, plus RequestContext's cookies
  * and setHeaders). A real SvelteKit RequestEvent satisfies it.
  */
-export interface AdminEvent extends EventBase<GithubKeyEnv & AuthEnv> {
+export interface AdminEvent extends EventBase<BackendEnv & AuthEnv> {
   cookies: CookieJar;
   setHeaders(headers: Record<string, string>): void;
 }
 
 /**
  * Injectable dependencies. Branding defaults from the runtime's siteName and sender, so a
- *  site overrides it only to change the magic-link email identity; `send` and `mintToken`
- *  are the same seams the underlying factories take.
+ *  site overrides it only to change the magic-link email identity; `send` is the same seam the
+ *  underlying auth factory takes. The content backend rides `event.locals.backend` (the dev double)
+ *  or the adapter's provider, so it is not a dep here.
  */
 export interface CairnAdminDeps {
   branding?: AuthBranding;
   send?: SendMagicLink;
-  mintToken?: ContentRoutesDeps['mintToken'];
   /**
    * Build the Anthropic client for the tidy action. Forwarded to the content routes; a site that
    *  enables tidy injects a stub here to avoid a real network call. Defaults to the real SDK client.
@@ -83,13 +83,12 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
   };
   const auth = createAuthRoutes({ branding, send: deps.send });
   const content = createContentRoutes(runtime, {
-    mintToken: deps.mintToken,
     anthropic: deps.anthropic,
     tidyTimeoutMs: deps.tidyTimeoutMs,
   });
   const editors = createEditorRoutes();
   // The nav surface exists only when the site configures a menu; without one its view is a 404.
-  const nav = runtime.navMenu ? createNavRoutes(runtime, { mintToken: deps.mintToken }) : null;
+  const nav = runtime.navMenu ? createNavRoutes(runtime) : null;
 
   /**
    * Build the event a wrapped content load reads. The catch-all route carries only a rest
@@ -111,8 +110,8 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
 
   /**
    * Serve the admin view the pathname names, or a 404 for any shape the parser refuses.
-   *  The authed views run the layout load and the view load concurrently; both mint a GitHub
-   *  token, and the installation-token cache coalesces the mints into one signing.
+   *  The authed views run the layout load and the view load concurrently; both resolve the same
+   *  backend, and the installation-token cache coalesces their lazy mints into one signing.
    */
   async function load(event: AdminEvent): Promise<AdminData> {
     const view = parseAdminPath(event.url.pathname, runtime.concepts);