@glw907/cairn-cms 0.62.2 → 0.76.0

package/dist/render/highlight.js

@@ -0,0 +1,206 @@
+import { toString } from 'hast-util-to-string';
+// 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',
+];
+// 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 = {
+    '#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 = {
+    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) {
+    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, className) {
+    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 = {
+    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;
+function getHighlighter() {
+    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) {
+    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) {
+    const child = pre.children.find((c) => c.type === 'element');
+    return child?.tagName === 'code' ? child : undefined;
+}
+// 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, jobs) {
+    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) => {
+        const jobs = [];
+        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.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/dist/render/pipeline.d.ts

@@ -4,12 +4,6 @@ import { type MediaResolve } from './resolve-media.js';
 import { 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

package/dist/render/pipeline.js

@@ -8,7 +8,8 @@ import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
 import rehypeSanitize from 'rehype-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';
@@ -38,8 +39,18 @@ export function createRenderer(registry = defineRegistry({ components: [] }), op
     const rehypePlugins = [
         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]);

package/dist/render/registry.d.ts

@@ -1,32 +1,6 @@
 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';
 export type SlotKind = 'markdown' | 'inline' | 'repeatable';
 /**
  * One named content region of a component. The slots named `title` and `body` are special: `title`
@@ -39,7 +13,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}`.
@@ -74,19 +48,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;
@@ -106,8 +106,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;
 }
 /**
  * The hast property name carrying one declared attribute from stamp to dispatch, e.g. `tone`
@@ -141,3 +141,11 @@ export declare function emptyValues(def: ComponentDef): ComponentValues;
  *  the def declares no `preview`, returns exactly the {@link emptyValues} output.
  */
 export declare function previewValues(def: ComponentDef): ComponentValues;
+/**
+ * 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 declare function defineComponent<const D extends ComponentDef>(def: D): D & {
+    attributeSchema: Fieldset;
+};

package/dist/render/registry.js

@@ -1,3 +1,4 @@
+import { fieldset } from '../content/fieldset.js';
 /**
  * The hast property name carrying one declared attribute from stamp to dispatch, e.g. `tone`
  *  becomes `dataAttrTone`. The directive stamp writes it and the rehype dispatch reads it, so both
@@ -7,13 +8,26 @@ export function dataAttrProp(key) {
     return `dataAttr${key.charAt(0).toUpperCase()}${key.slice(1)}`;
 }
 /**
- * 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) {
-    return def.attributes?.find((field) => field.type === 'icon');
+    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 = {
+    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.
@@ -32,7 +46,14 @@ export function defineRegistry({ components }) {
         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;
@@ -45,8 +66,8 @@ export function defineRegistry({ components }) {
  */
 export function emptyValues(def) {
     const attributes = {};
-    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 = {};
     for (const slot of def.slots ?? []) {
@@ -68,3 +89,23 @@ export function previewValues(def) {
         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, attributes) {
+    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(def) {
+    const attributes = def.attributes ?? {};
+    checkComponentAttributes(def.name, attributes);
+    return { ...def, attributeSchema: fieldset(attributes, { behavior: def.behavior }) };
+}

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

@@ -1,17 +1,13 @@
 import type { Root, Element, ElementContent } from 'hast';
 import { type ComponentContext, type ComponentRegistry } from './registry.js';
-/**
- *
- */
+/** Narrow a hast node to an Element, false for a text node, a comment, or undefined. */
 export declare function isElement(node: ElementContent | undefined): node is Element;
 /**
  * Read a declared string attribute off the component context, returning undefined for a boolean or
  *  absent value. Replaces the `typeof ctx.attributes[key] === 'string'` narrowing a build repeats.
  */
 export declare function strAttr(ctx: ComponentContext, key: string): string | undefined;
-/**
- *
- */
+/** Read a hast element property as a string, or undefined when it is absent or non-string. */
 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;
@@ -33,10 +29,10 @@ export declare function headRow(title: ElementContent[], icon?: Element, level?:
 export declare function markFirstList(children: ElementContent[]): Element | undefined;
 /**
  * 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 declare function rehypeDispatch(registry: ComponentRegistry, stagger?: boolean): (tree: Root) => void;
+export declare function rehypeDispatch(registry: ComponentRegistry): (tree: Root) => void;

package/dist/render/rehype-dispatch.js

@@ -1,8 +1,6 @@
 import { h } from 'hastscript';
 import { dataAttrProp } from './registry.js';
-/**
- *
- */
+/** Narrow a hast node to an Element, false for a text node, a comment, or undefined. */
 export function isElement(node) {
     return !!node && node.type === 'element';
 }
@@ -17,9 +15,7 @@ export function strAttr(ctx, key) {
 // 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, name) {
     const value = node.properties?.[name];
     return typeof value === 'string' ? value : undefined;
@@ -60,7 +56,7 @@ export function markFirstList(children) {
 }
 // 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, registry) {
     return children.map((c) => {
         if (isElement(c) && c.properties?.dataPrimitive)
@@ -74,11 +70,11 @@ function transformChildren(children, registry) {
 // 'true'/'false'; everything else is the literal string the author wrote.
 function readAttributes(node, def) {
     const out = {};
-    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;
 }
@@ -130,6 +126,31 @@ function partitionSlots(node) {
         },
     };
 }
+// 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, attributes) {
+    const out = {};
+    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, def, attributes, fallback) {
+    const properties = {
+        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, registry) {
     node.children = transformChildren(node.children, registry);
     const name = strProp(node, 'dataPrimitive');
@@ -143,24 +164,24 @@ function transformNode(node, registry) {
         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, stagger) {
+export function rehypeDispatch(registry) {
     return (tree) => {
         let idx = 0;
         tree.children = tree.children.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))

package/dist/render/remark-directives.js

@@ -63,8 +63,7 @@ export function remarkDirectiveStamp(registry) {
             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);
@@ -78,10 +77,10 @@ export function remarkDirectiveStamp(registry) {
             // 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];
+            for (const name of Object.keys(def?.attributes ?? {})) {
+                const raw = name === iconKey ? icon : attrs[name];
                 if (raw != null)
-                    properties[dataAttrProp(field.key)] = raw;
+                    properties[dataAttrProp(name)] = raw;
             }
             const data = node.data ?? (node.data = {});
             data.hName = 'div';

package/dist/render/sanitize-schema.d.ts

@@ -20,6 +20,16 @@ export declare function buildSanitizeSchema(registry: ComponentRegistry, extend?
  * `anchorRel` option (default `noopener noreferrer`); a site can override it or disable it entirely.
  */
 export declare function rehypeAnchorRel(rel: string): (tree: Root) => void;
+/**
+ * Give every GFM task-list checkbox an accessible name from its item text. remark-gfm emits a real
+ * `<input type="checkbox" disabled>` with no label, which axe's `label` rule flags as a critical
+ * violation even though the control is read-only; the visible label is the surrounding `<li>` text,
+ * not associated programmatically. This sets `aria-label` on each task-list checkbox to its item's
+ * text so the name travels with the control, keeping the engine's real disabled input (the bar's
+ * non-color cue) while clearing the violation on every site. It must run after the sanitize floor,
+ * which does not allow `aria-label`, so the attribute is added once the floor has run.
+ */
+export declare function rehypeTaskListA11y(): (tree: Root) => void;
 /**
  * Post-dispatch safety floor over the fully-built tree. The pre-dispatch rehype-sanitize floor
  * cleans author content, but a component build() runs after it and can route a raw author