@glw907/cairn-cms 0.62.2 → 0.76.0

package/src/lib/render/highlight.ts

@@ -0,0 +1,259 @@
+// cairn-cms: build-time syntax highlighting for the shared render pipeline. It tokenizes fenced
+// code with Shiki and emits a <pre class="shiki"> whose tokens carry semantic CLASS names from a
+// fixed cairn ramp (cairn-tok-keyword, cairn-tok-string, ...), never an inline style and never a
+// baked hex literal. The colors live in the site theme, so recoloring the theme recolors code with
+// no markup change.
+//
+// CLASS-DRIVEN (load-bearing): the output is class-only, with no `style` attribute on the <pre>,
+// the <code>, or any token <span>. cairn is class-driven by design (the sink guard in
+// sanitize-schema.ts strips every inline `style` wholesale), and class output survives that floor
+// naturally because `className` is already allowed on `*`. The highlighter therefore needs no
+// special placement and no ordering invariant: it runs as an ordinary rehype plugin. Never weaken
+// the sanitize floor or the sink guard to accommodate this step, and never add `style` to an
+// allowlist; the point is that class-only output needs neither.
+//
+// THE .cairn-tok-* CLASS CONTRACT: the engine owns the token class names (below); the site owns the
+// colors. This mirrors the engine's .cairn-place-* figure-placement contract: a site styles the
+// classes in its own theme. The showcase binds each class to a --cairn-code-* role variable in
+// examples/showcase/src/lib/theme.css, so the syntax palette re-skins with the rest of the theme.
+//
+//   .cairn-tok-keyword    a language keyword, storage class, or control word
+//   .cairn-tok-string     a string or quoted literal
+//   .cairn-tok-comment    a comment
+//   .cairn-tok-function   a function name, tag name, or property key
+//   .cairn-tok-number     a numeric, boolean, or other constant literal
+//   .cairn-tok-punct      punctuation and operators
+//
+// Default text carries no token class and inherits the code block's foreground (--cairn-code-ink).
+//
+// SERVER/BUILD-ONLY: Shiki is loaded through a dynamic import so it stays out of the static client
+// graph (a separate async chunk). The highlighter runs only inside the async pipeline, at
+// render/prerender and in the Worker SSR. The highlighter is created once and its promise cached.
+import type { Root, Element } from 'hast';
+import { toString } from 'hast-util-to-string';
+import type { Highlighter, ThemeRegistrationRaw, ShikiTransformer } from 'shiki';
+
+// The curated language set Shiki preloads. Each id pulls its aliases too (loading `bash` also
+// registers `sh`, `shell`, `zsh`; loading `js` registers `javascript`, `mjs`, `cjs`). A fence whose
+// language is absent or outside this set falls back to plaintext rather than throwing.
+const LANGS = [
+  'js',
+  'ts',
+  'jsx',
+  'tsx',
+  'svelte',
+  'html',
+  'css',
+  'json',
+  'bash',
+  'markdown',
+  'python',
+  'yaml',
+  'sql',
+] as const;
+
+// The plaintext language id. Shiki special-cases it (and `plaintext`/`txt`/`ansi`) as always
+// available, so it is the safe fallback for an unknown or absent fence language: it escapes the
+// code text into the same <pre class="shiki"> wrapper with no token coloring.
+const PLAINTEXT = 'text';
+
+// Sentinel foreground colors, one per ramp slot. Shiki has no class-emitting mode, so the theme
+// assigns each scope group a unique sentinel hex, then the transformer below maps the resolved
+// sentinel back to its cairn-tok-* class and deletes the style. The sentinels never reach the
+// output. They are arbitrary distinct values; only their uniqueness and exact round-trip matter.
+const SENTINEL_INK = '#000000';
+const SENTINEL_TO_CLASS: Record<string, string> = {
+  '#000010': 'cairn-tok-comment',
+  '#000020': 'cairn-tok-keyword',
+  '#000030': 'cairn-tok-string',
+  '#000040': 'cairn-tok-function',
+  '#000050': 'cairn-tok-number',
+  '#000060': 'cairn-tok-punct',
+};
+
+// The Shiki theme that drives the class mapping. Every scope group resolves to its sentinel color;
+// the transformer turns the sentinel into a class. The background and default foreground are
+// sentinels too, stripped from the <pre> by the transformer so the site theme owns the surround.
+const CAIRN_CODE_THEME: ThemeRegistrationRaw = {
+  name: 'cairn-roles',
+  type: 'light',
+  fg: SENTINEL_INK,
+  bg: '#ffffff',
+  settings: [
+    { settings: { foreground: SENTINEL_INK, background: '#ffffff' } },
+    {
+      scope: ['comment', 'punctuation.definition.comment', 'string.comment'],
+      settings: { foreground: '#000010' },
+    },
+    {
+      scope: [
+        'keyword',
+        'keyword.control',
+        'storage',
+        'storage.type',
+        'storage.modifier',
+        'variable.language',
+        'keyword.operator.new',
+        'keyword.operator.expression',
+      ],
+      settings: { foreground: '#000020' },
+    },
+    {
+      scope: ['string', 'string.quoted', 'string.template', 'constant.other.symbol'],
+      settings: { foreground: '#000030' },
+    },
+    {
+      scope: [
+        'entity.name.function',
+        'support.function',
+        'meta.function-call',
+        'entity.name.tag',
+        'support.type.property-name',
+      ],
+      settings: { foreground: '#000040' },
+    },
+    {
+      scope: [
+        'constant.numeric',
+        'constant.language',
+        'constant.character',
+        'constant.other',
+        'keyword.other.unit',
+      ],
+      settings: { foreground: '#000050' },
+    },
+    {
+      scope: ['punctuation', 'meta.brace', 'keyword.operator', 'meta.delimiter'],
+      settings: { foreground: '#000060' },
+    },
+  ],
+};
+
+// Read the `color:#rrggbb` hex out of a token span's inline style, lowercased for the sentinel map.
+function styleColor(style: unknown): string | undefined {
+  if (typeof style !== 'string') return undefined;
+  const match = /color:(#[0-9a-fA-F]{6})/.exec(style);
+  return match ? match[1].toLowerCase() : undefined;
+}
+
+// Append a class to a hast element's class list, building the string form Shiki uses.
+function addClass(node: Element, className: string): void {
+  const existing = node.properties?.class;
+  const prefix = typeof existing === 'string' && existing.length > 0 ? `${existing} ` : '';
+  (node.properties ??= {}).class = `${prefix}${className}`;
+}
+
+// The transformer that converts Shiki's sentinel-colored inline styles into the cairn-tok-* classes
+// and strips every style attribute, so the output is class-only. The <pre> loses its
+// background/foreground style (the site theme owns the surround); each token <span> trades its
+// sentinel color for the matching class, and a default-foreground span is left unclassed.
+const cairnTokenClasses: ShikiTransformer = {
+  name: 'cairn-token-classes',
+  pre(node) {
+    if (node.properties) delete node.properties.style;
+  },
+  code(node) {
+    if (node.properties) delete node.properties.style;
+  },
+  span(node) {
+    const hex = styleColor(node.properties?.style);
+    if (node.properties) delete node.properties.style;
+    const className = hex ? SENTINEL_TO_CLASS[hex] : undefined;
+    if (className) addClass(node, className);
+  },
+};
+
+// The cached highlighter. Created once on first use and reused for every render. The dynamic import
+// keeps Shiki off the static client graph; the promise is cached so the WASM grammar load and the
+// theme registration happen at most once per process.
+let highlighterPromise: Promise<Highlighter> | undefined;
+
+function getHighlighter(): Promise<Highlighter> {
+  if (!highlighterPromise) {
+    highlighterPromise = import('shiki').then((shiki) =>
+      shiki.createHighlighter({ themes: [CAIRN_CODE_THEME], langs: [...LANGS] }),
+    );
+  }
+  return highlighterPromise;
+}
+
+// Read the fenced language off a <code> element's class list. Markdown emits the language as a
+// `language-<id>` class on the inner <code>. An empty or missing language returns undefined, which
+// the caller maps to plaintext.
+function codeLanguage(code: Element): string | undefined {
+  const className = code.properties?.className;
+  const classes = Array.isArray(className) ? className.map(String) : [];
+  const langClass = classes.find((c) => c.startsWith('language-'));
+  const lang = langClass?.slice('language-'.length);
+  return lang && lang.length > 0 ? lang : undefined;
+}
+
+// A fenced-code <pre> is a <pre> whose single element child is a <code>. Inline code (a bare <code>
+// with no <pre> parent) and any other <pre> are left untouched.
+function fencedCode(pre: Element): Element | undefined {
+  const child = pre.children.find((c): c is Element => c.type === 'element');
+  return child?.tagName === 'code' ? child : undefined;
+}
+
+// One pending highlight: the original <pre> to replace, the inner <code> to read text from, and the
+// fenced language. The <pre> is rewritten in place (mutated to become Shiki's <pre>) after the async
+// tokenize, which keeps the parent-children typing uniform across Root and Element.
+interface Job {
+  pre: Element;
+  code: Element;
+  lang: string;
+}
+
+// Descend the tree and collect every fenced-code <pre>. The walk is synchronous and gathers the
+// targets up front, because the highlight itself is async (unist-util-visit cannot await).
+function collectFencedCode(node: Root | Element, jobs: Job[]): void {
+  for (const child of node.children) {
+    if (child.type !== 'element') continue;
+    if (child.tagName === 'pre') {
+      const code = fencedCode(child);
+      if (code) {
+        jobs.push({ pre: child, code, lang: codeLanguage(code) ?? PLAINTEXT });
+        continue;
+      }
+    }
+    collectFencedCode(child, jobs);
+  }
+}
+
+/**
+ * The Shiki rehype plugin. Highlights every fenced-code block into a `<pre class="shiki">` whose
+ * tokens carry the cairn-tok-* classes (no inline style), then leaves the rest of the tree
+ * untouched. It runs as an async transformer because Shiki tokenizes asynchronously. Because the
+ * output is class-only it needs no special placement; it is safe anywhere after `remarkRehype`.
+ * @returns A unified transformer that mutates the hast tree in place.
+ */
+export function rehypeCairnHighlight() {
+  return async (tree: Root): Promise<void> => {
+    const jobs: Job[] = [];
+    collectFencedCode(tree, jobs);
+    if (jobs.length === 0) return;
+
+    const highlighter = await getHighlighter();
+    const loaded = new Set(highlighter.getLoadedLanguages());
+
+    for (const job of jobs) {
+      // Fall back to plaintext for any language outside the preloaded set so Shiki never throws on
+      // an unknown fence. Plaintext still produces the <pre class="shiki"> wrapper with escaped text.
+      const lang = loaded.has(job.lang) ? job.lang : PLAINTEXT;
+      const result = highlighter.codeToHast(toString(job.code), {
+        lang,
+        theme: 'cairn-roles',
+        transformers: [cairnTokenClasses],
+      });
+      const pre = result.children.find(
+        (c): c is Element => c.type === 'element' && c.tagName === 'pre',
+      );
+      if (!pre) continue;
+      // Rewrite the original <pre> into Shiki's <pre> in place: adopt its tag, properties, and
+      // children. Mutating the existing node avoids reindexing the parent's children array.
+      job.pre.tagName = pre.tagName;
+      job.pre.properties = pre.properties;
+      job.pre.children = pre.children;
+    }
+  };
+}

package/src/lib/render/pipeline.ts

@@ -9,7 +9,8 @@ import rehypeStringify from 'rehype-stringify';
 import rehypeSanitize from 'rehype-sanitize';
 import type { Schema } from 'hast-util-sanitize';
 import { VFile } from 'vfile';
-import { buildSanitizeSchema, rehypeAnchorRel, rehypeSinkGuard } from './sanitize-schema.js';
+import { buildSanitizeSchema, rehypeAnchorRel, rehypeSinkGuard, rehypeTaskListA11y } from './sanitize-schema.js';
+import { rehypeCairnHighlight } from './highlight.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
 import { remarkFigure } from './remark-figure.js';
 import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
@@ -19,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
@@ -72,8 +67,18 @@ 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
+    // not gated by unsafeDisableSanitize.
+    rehypeTaskListA11y,
+    // Build-time syntax highlighting. It emits class-only output (the cairn-tok-* ramp, no inline
+    // style), so it is class-driven like the rest of the pipeline and needs no special placement
+    // relative to the sanitize floor or the sink guard: the token classes survive the floor because
+    // `className` is already allowed on `*`. It runs unconditionally (a code fence is content, not a
+    // sink) and ships no client highlighter (Shiki is build-only behind a dynamic import).
+    rehypeCairnHighlight,
   ];
   if (rel !== false) rehypePlugins.push([rehypeAnchorRel, rel]);
   // The sink guard runs last, over the fully-built tree, so it neutralizes a sink a component

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,19 +58,45 @@ 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;
-  /** Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. */
+  /**
+   * 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
+   *  distinct across roles so the picker stays scannable. Overrides the engine
+   *  {@link DEFAULT_ICON_BY_ROLE} fallback for the roles it names.
+   */
   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[];
-  /** A glyph key from the site IconSet, shown beside the label in the picker. */
+  /**
+   * A glyph key from the site IconSet, shown beside the label in the picker. Choose a logically
+   *  representative glyph and prefer glyphs distinct across components so the picker stays scannable.
+   */
   icon?: string;
   /** A category heading for the picker. Components order by declaration within a group. */
   group?: string;
@@ -115,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;
 }
 
 /**
@@ -129,14 +131,28 @@ 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];
 }
 
+/**
+ * The engine's role-to-glyph-key fallback for the conventional admonition roles, which a site's
+ *  IconSet may satisfy. A component's own {@link ComponentDef.defaultIconByRole} overrides it.
+ */
+const DEFAULT_ICON_BY_ROLE: Record<string, string> = {
+  note: 'info',
+  tip: 'lightbulb',
+  important: 'star',
+  warning: 'warning',
+  caution: 'alert-triangle',
+  info: 'info',
+  danger: 'flame',
+};
+
 /**
  * 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.
@@ -159,7 +175,12 @@ export function defineRegistry({ components }: { components: ComponentDef[] }):
     defs: components,
     names: components.map((c) => c.name),
     get: (name) => byName.get(name),
-    defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
+    defaultIcon: (name, role) => {
+      if (!role) return undefined;
+      const def = byName.get(name);
+      if (!def || !findIconField(def)) return undefined;
+      return def.defaultIconByRole?.[role] ?? DEFAULT_ICON_BY_ROLE[role];
+    },
     iconField: (name) => {
       const def = byName.get(name);
       return def ? findIconField(def) : undefined;
@@ -182,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 ?? []) {
@@ -205,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

@@ -2,9 +2,7 @@ import type { Root, Element, ElementContent } from 'hast';
 import { h } from 'hastscript';
 import { dataAttrProp, type ComponentContext, type ComponentDef, type ComponentRegistry } from './registry.js';
 
-/**
- *
- */
+/** Narrow a hast node to an Element, false for a text node, a comment, or undefined. */
 export function isElement(node: ElementContent | undefined): node is Element {
   return !!node && node.type === 'element';
 }
@@ -21,9 +19,7 @@ export function strAttr(ctx: ComponentContext, key: string): string | undefined
 // hast Properties values are PropertyValue (string | number | boolean | array | null).
 // Directive markers (dataPrimitive/dataRole/dataAttr<Key>) are always stamped as strings;
 // this reads them back with that guarantee instead of casting at each call site.
-/**
- *
- */
+/** Read a hast element property as a string, or undefined when it is absent or non-string. */
 export function strProp(node: Element, name: string): string | undefined {
   const value = node.properties?.[name];
   return typeof value === 'string' ? value : undefined;
@@ -73,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);
@@ -86,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;
 }
@@ -139,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');
@@ -151,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 = {});