@glw907/cairn-cms 0.68.0 → 0.76.0

package/dist/index.js

@@ -2,14 +2,11 @@
 // GitHub read-and-commit backend in Plan 03; render and nav follow.
 export { requireOrigin } from './env.js';
 export { buildMagicLinkMessage, cloudflareSend } from './email.js';
-export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
+export { normalizeConcepts, findConcept, defineConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
 export { frontmatterFromForm, dateInputValue, serializeMarkdown, parseMarkdown, } from './content/frontmatter.js';
-export { defineFields } from './content/schema.js';
 export { defineAdapter } from './content/adapter.js';
-// The Contract v2 field vocabulary, additive beside `defineFields`. The individual *Field
-// interfaces and the bare `Infer` stay module-local: the old `FrontmatterField` model above
-// already exports those names, and the cutover plan frees them.
+// The Contract v2 field vocabulary: the one live field system.
 export { fields } from './content/fields.js';
 export { fieldset, initialValues } from './content/fieldset.js';
 export { isValidId, idFromFilename, filenameFromId, slugify, slugFromId, composeDatedId, } from './content/ids.js';
@@ -17,9 +14,9 @@ export { isValidId, idFromFilename, filenameFromId, slugify, slugFromId, compose
 // builder and the request-time resolver ship from the delivery entry; this surface is the
 // grammar, the manifest operations, and their types a migrating site adopts.
 export { parseCairnToken, extractCairnLinks, formatCairnToken, escapeLinkText } from './content/links.js';
-export { serializeManifest, parseManifest, emptyManifest, verifyManifest, diffManifests, upsertEntry, removeEntry, manifestEntryFromFile, manifestLinkResolver, inboundLinks, } from './content/manifest.js';
+export { serializeManifest, parseManifest, emptyManifest, verifyManifest, verifyReferences, diffManifests, upsertEntry, removeEntry, manifestEntryFromFile, manifestLinkResolver, inboundLinks, } from './content/manifest.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
-export { defineRegistry, emptyValues } from './render/registry.js';
+export { defineRegistry, defineComponent, emptyValues } from './render/registry.js';
 export { serializeComponent, parseComponent } from './render/component-grammar.js';
 export { validateComponent } from './render/component-validate.js';
 export { buildComponentInsert } from './render/component-insert.js';
@@ -32,5 +29,7 @@ export { remarkDirectiveStamp } from './render/remark-directives.js';
 // path. See docs/superpowers/specs/2026-06-05-cairn-render-authoring-surface-design.md.
 export { createRenderer } from './render/pipeline.js';
 export { CommitConflictError } from './github/types.js';
+// The Backend seam (Contract v2 backend phase): the store interface and its default GitHub provider.
+export { githubApp } from './github/backend.js';
 // Nav tree and site-config helpers (Plan 06).
-export { parseSiteConfig, urlPolicyFrom, extractMenu, setMenu, validateNavTree, MAX_NAV_NODES, NavValidationError, SiteConfigError, } from './nav/site-config.js';
+export { parseSiteConfig, extractMenu, setMenu, validateNavTree, MAX_NAV_NODES, NavValidationError, SiteConfigError, } from './nav/site-config.js';

package/dist/islands/index.d.ts

@@ -0,0 +1,12 @@
+import type { IslandRegistry } from './types.js';
+export type { IslandRegistry } from './types.js';
+/**
+ * Mount each island in `root` (default `document`) over its server-rendered fallback. Call it after each
+ *  client-side navigation, once the new DOM is in place (an `afterNavigate` callback): it tears down the
+ *  previous pass first, so it is idempotent and leak-free. An eager island (`hydrate: true`) mounts at once;
+ *  a `'visible'` island mounts on first intersection. An unknown directive name, a malformed prop payload,
+ *  or a component that throws leaves the static fallback in place, so one bad island never breaks the page.
+ *  Mount-and-replace clears the fallback, so an island whose fallback holds a focusable control should
+ *  restore focus itself; the shipped fallbacks are non-interactive.
+ */
+export declare function hydrateIslands(islands: IslandRegistry, root?: ParentNode): void;

package/dist/islands/index.js

@@ -0,0 +1,83 @@
+// cairn-cms islands (@glw907/cairn-cms/islands): the client runtime that mounts a site's live Svelte
+// components over the static fallbacks the render pipeline emits. cairn is Svelte-only by design, so this
+// mounts with Svelte's own mount()/unmount() directly, with no framework abstraction. A site imports this
+// dynamically, gated on a non-empty registry, so a static site never ships it (zero cost when unused).
+import { mount, unmount } from 'svelte';
+// The live Svelte instances of the current pass and the observers still waiting to fire, kept module-level
+// so the next pass can tear the previous one down. A layout calls hydrateIslands once per navigation, and
+// the previous mounts must unmount before the next mount over the same DOM.
+let mounted = [];
+let observers = [];
+// Tear down the previous pass: unmount live instances and disconnect observers that never fired. unmount
+// runs with outro: false so teardown is synchronous and deterministic on navigation; an island declaring an
+// out: transition would otherwise linger and briefly double-render against the next pass's fresh mount.
+function teardown() {
+    for (const o of observers)
+        o.disconnect();
+    observers = [];
+    for (const instance of mounted) {
+        try {
+            void unmount(instance, { outro: false });
+        }
+        catch {
+            // a component that throws on teardown must not block the rest
+        }
+    }
+    mounted = [];
+}
+// Mount one island over its boundary: parse props (try/catch, a malformed payload leaves the fallback),
+// clear the fallback, mount, and on a mount failure restore the fallback so the reader still sees content.
+// WATCH: props are trusted to equal the directive's declared scalar attributes (serializeIslandProps emits
+// only those). If a directive ever carries an attribute its island does not declare, this forwards it as-is.
+function mountIsland(node, Comp) {
+    let props;
+    try {
+        props = JSON.parse(node.getAttribute('data-cairn-props') ?? '{}');
+    }
+    catch {
+        return;
+    }
+    const fallback = [...node.childNodes];
+    node.replaceChildren();
+    try {
+        mounted.push(mount(Comp, { target: node, props }));
+    }
+    catch {
+        node.replaceChildren(...fallback);
+    }
+}
+// Defer a 'visible' island to first intersection, then mount once and stop observing.
+function observeIsland(node, Comp) {
+    const observer = new IntersectionObserver((entries, self) => {
+        for (const entry of entries) {
+            if (entry.isIntersecting) {
+                self.disconnect();
+                mountIsland(node, Comp);
+            }
+        }
+    });
+    observer.observe(node);
+    observers.push(observer);
+}
+/**
+ * Mount each island in `root` (default `document`) over its server-rendered fallback. Call it after each
+ *  client-side navigation, once the new DOM is in place (an `afterNavigate` callback): it tears down the
+ *  previous pass first, so it is idempotent and leak-free. An eager island (`hydrate: true`) mounts at once;
+ *  a `'visible'` island mounts on first intersection. An unknown directive name, a malformed prop payload,
+ *  or a component that throws leaves the static fallback in place, so one bad island never breaks the page.
+ *  Mount-and-replace clears the fallback, so an island whose fallback holds a focusable control should
+ *  restore focus itself; the shipped fallbacks are non-interactive.
+ */
+export function hydrateIslands(islands, root = document) {
+    teardown();
+    for (const node of root.querySelectorAll('[data-cairn-island]')) {
+        const name = node.getAttribute('data-cairn-island');
+        const Comp = name ? islands[name] : undefined;
+        if (!Comp)
+            continue;
+        if (node.getAttribute('data-cairn-hydrate') === 'visible')
+            observeIsland(node, Comp);
+        else
+            mountIsland(node, Comp);
+    }
+}

package/dist/islands/types.d.ts

@@ -0,0 +1,7 @@
+import type { Component } from 'svelte';
+/**
+ * A site's island components, keyed by directive name. Each value is the live Svelte component
+ *  {@link hydrateIslands} mounts over the matching `hydrate` directive's static fallback. The props a
+ *  component receives are the directive's declared scalar attributes (see the island boundary contract).
+ */
+export type IslandRegistry = Record<string, Component<Record<string, unknown>>>;

package/dist/islands/types.js

@@ -0,0 +1 @@
+export {};

package/dist/media/rewrite-plan.d.ts

@@ -1,5 +1,5 @@
 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';
 /**
  * One main entry the rewrite will touch: its identity, its file path, the transform's per-placement
@@ -59,8 +59,7 @@ export interface RewritePlan<P = unknown> {
  * editor surface and node-safe; the only IO is the usage index build and the per-entry reads.
  */
 export declare function planMediaRewrite<P = unknown>(args: {
-    backend: RepoRef;
-    token: string;
+    backend: Backend;
     concepts: ConceptDescriptor[];
     contentManifest: Manifest;
     hash: string;

package/dist/media/rewrite-plan.js

@@ -1,6 +1,5 @@
 import { findConcept } from '../content/concepts.js';
 import { filenameFromId } from '../content/ids.js';
-import { readRaw } from '../github/repo.js';
 import { buildUsageIndex } from './usage.js';
 /**
  * Plan a media rewrite for one asset hash. Builds the cross-branch usage index in strict mode (so an
@@ -22,7 +21,7 @@ import { buildUsageIndex } from './usage.js';
 export async function planMediaRewrite(args) {
     // Strict so an unverifiable branch read rejects here rather than degrading to an absent reference.
     // Do NOT wrap this: the throw is the fail-closed contract the apply relies on.
-    const index = await buildUsageIndex(args.backend, args.token, args.concepts, args.contentManifest, {
+    const index = await buildUsageIndex(args.backend, args.concepts, args.contentManifest, {
         strict: true,
     });
     const rows = index.get(args.hash) ?? [];
@@ -35,7 +34,7 @@ export async function planMediaRewrite(args) {
         if (!concept)
             return null;
         const path = `${concept.dir}/${filenameFromId(row.id)}`;
-        const markdown = await readRaw(args.backend, path, args.token);
+        const markdown = await args.backend.readFile(path, args.backend.defaultBranch);
         if (markdown === null)
             return null;
         const result = args.transform(markdown);

package/dist/media/usage.d.ts

@@ -1,5 +1,5 @@
 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';
 /** Where a reference lives: the published corpus on main, or a named open edit branch. */
 export type UsageOrigin = {
@@ -49,4 +49,4 @@ export interface BuildUsageOptions {
  * failure so the caller fails closed. Pass `branches` to reuse a branch list the caller already has
  * (the load path lists once for the media-union) rather than listing them a second time.
  */
-export declare function buildUsageIndex(repo: RepoRef, token: string, concepts: ConceptDescriptor[], manifest: Manifest, opts?: BuildUsageOptions): Promise<UsageIndex>;
+export declare function buildUsageIndex(backend: Backend, concepts: ConceptDescriptor[], manifest: Manifest, opts?: BuildUsageOptions): Promise<UsageIndex>;

package/dist/media/usage.js

@@ -1,5 +1,3 @@
-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';
@@ -24,7 +22,7 @@ function push(index, hash, entry) {
  * failure so the caller fails closed. Pass `branches` to reuse a branch list the caller already has
  * (the load path lists once for the media-union) rather than listing them a second time.
  */
-export async function buildUsageIndex(repo, token, concepts, manifest, opts = {}) {
+export async function buildUsageIndex(backend, concepts, manifest, opts = {}) {
     const index = new Map();
     // The main arm: the manifest already carries each entry's mediaRefs, so this is a pure reverse
     // map with no per-file read.
@@ -41,7 +39,7 @@ export async function buildUsageIndex(repo, token, concepts, manifest, opts = {}
     }
     // 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
@@ -58,7 +56,7 @@ export async function buildUsageIndex(repo, token, concepts, manifest, opts = {}
             return [];
         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);

package/dist/nav/site-config.d.ts

@@ -1,4 +1,3 @@
-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 {
     label: string;
@@ -28,12 +27,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
@@ -141,8 +137,6 @@ export declare class SiteConfigError extends Error {
 export declare function parseSiteConfig(raw: string): SiteConfig;
 /** Extract one named menu from a parsed config and validate it. Returns [] when the menu is absent. */
 export declare function extractMenu(config: SiteConfig, name: string, maxDepth: number): NavNode[];
-/** The per-concept URL policy from a parsed config, or an empty policy when the `content` key is absent. */
-export declare function urlPolicyFrom(config: SiteConfig): Record<string, ConceptUrlPolicy>;
 /**
  * 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/dist/nav/site-config.js

@@ -185,6 +185,12 @@ export function parseSiteConfig(raw) {
     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.content !== undefined) {
+        throw new SiteConfigError('cairn: site config no longer carries per-concept URL policy; move permalink/datePrefix into defineConcept (Contract v2)');
+    }
     return parsed;
 }
 /** Extract one named menu from a parsed config and validate it. Returns [] when the menu is absent. */
@@ -194,10 +200,6 @@ export function extractMenu(config, name, maxDepth) {
         return [];
     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) {
-    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/dist/render/component-grammar.js

@@ -5,11 +5,11 @@ import remarkStringify from 'remark-stringify';
 const COLON = ':';
 function attrBlock(def, values) {
     const parts = [];
-    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"`);
+                parts.push(`${name}="true"`);
         }
         else if (typeof v === 'string' && v !== '') {
             // The directive attribute grammar (mdast-util-directive) treats a literal `"` as the value
@@ -17,7 +17,7 @@ function attrBlock(def, values) {
             // 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(' ')}}` : '';
@@ -80,12 +80,12 @@ function valuesFromRoot(root, def) {
     const values = emptyComponentValues(def);
     if (!root)
         return values;
-    for (const field of def.attributes ?? []) {
-        const raw = root.attributes?.[field.key];
+    for (const [name, field] of Object.entries(def.attributes ?? {})) {
+        const raw = root.attributes?.[name];
         if (field.type === 'boolean')
-            values.attributes[field.key] = raw === 'true';
+            values.attributes[name] = raw === 'true';
         else if (typeof raw === 'string')
-            values.attributes[field.key] = raw;
+            values.attributes[name] = raw;
     }
     const titleSlot = slotByName(def, 'title');
     const bodySlot = slotByName(def, 'body');
@@ -144,7 +144,7 @@ export async function componentRoundTripSafety(markdown, def) {
     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' };
@@ -177,8 +177,8 @@ export async function parseComponentWithRawKeys(markdown, def) {
 // here; the parse must overwrite only the fields actually present in the markdown.
 function emptyComponentValues(def) {
     const attributes = {};
-    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 = {};
     for (const s of def.slots ?? [])
         slots[s.name] = s.kind === 'repeatable' ? [] : '';

package/dist/render/component-reference.js

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

package/dist/render/component-validate.d.ts

@@ -7,6 +7,9 @@ export type ComponentValidation = {
     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 declare function validateComponent(markdown: string, def: ComponentDef): Promise<ComponentValidation>;

package/dist/render/component-validate.js

@@ -1,32 +1,19 @@
 import { parseComponentWithRawKeys } from './component-grammar.js';
+import { fieldset } from '../content/fieldset.js';
 /**
- *
+ * 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, def) {
     const { values, rawKeys } = await parseComponentWithRawKeys(markdown, def);
     const errors = {};
-    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}".`;
@@ -41,15 +28,3 @@ export async function validateComponent(markdown, def) {
     }
     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, key, call) {
-    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/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

@@ -39,7 +39,7 @@ 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

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,10 +48,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
@@ -87,8 +69,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[];
     /**
@@ -114,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`
@@ -149,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,12 +8,12 @@ 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
@@ -65,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 ?? []) {
@@ -88,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 }) };
+}