@glw907/cairn-cms 0.62.2 → 0.76.0

package/dist/index.d.ts

@@ -2,22 +2,27 @@ export { requireOrigin } from './env.js';
 export type { Role, Editor, AuthEnv } from './auth/types.js';
 export type { AuthBranding, MagicLinkMessage, SendMagicLink } from './email.js';
 export { buildMagicLinkMessage, cloudflareSend } from './email.js';
-export type { CairnAdapter, ConceptConfig, FrontmatterField, TextField, TextareaField, DateField, BooleanField, TagsField, FreeTagsField, ImageField, ImageValue, ValidationResult, BackendConfig, SenderConfig, NavMenuConfig, PreviewConfig, ResolvedPreview, AssetConfig, RoutingRule, ConceptDescriptor, ConceptUrlPolicy, CairnExtension, CairnRuntime, AdminPanel, FieldTypeDef, } from './content/types.js';
-export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
+export type { CairnAdapter, ConceptConfig, NamedField, ImageValue, ValidationResult, ValidationIssue, SenderConfig, NavMenuConfig, PreviewConfig, ResolvedPreview, AssetConfig, RoutingRule, ConceptDescriptor, ConceptUrlPolicy, CairnExtension, CairnRuntime, SiteRender, AdminPanel, FieldTypeDef, } from './content/types.js';
+export { normalizeConcepts, findConcept, defineConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
 export type { ComposeInput } 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';
-export type { ConceptSchema, Infer, InferFields, DefineFieldsOptions, StandardInput, StandardSchemaV1 } from './content/schema.js';
+export type { StandardInput, StandardSchemaV1 } from './content/standard-schema.js';
+export { fields } from './content/fields.js';
+export type { FieldDescriptor, TextField, TextareaField, NumberField, SelectField, MultiselectField, UrlField, EmailField, DateField, DatetimeField, BooleanField, IconField, ImageField, ObjectField, ReferenceField, ArrayField, } from './content/fields.js';
+export { fieldset, initialValues } from './content/fieldset.js';
+export type { Fieldset, InferFieldset, FieldsetOptions, BehaviorTable, FieldBehavior } from './content/fieldset.js';
 export { isValidId, idFromFilename, filenameFromId, slugify, slugFromId, composeDatedId, } from './content/ids.js';
 export type { DatePrefix } from './content/ids.js';
 export { parseCairnToken, extractCairnLinks, formatCairnToken, escapeLinkText } from './content/links.js';
 export type { CairnRef, LinkResolve } from './content/links.js';
-export { serializeManifest, parseManifest, emptyManifest, verifyManifest, diffManifests, upsertEntry, removeEntry, manifestEntryFromFile, manifestLinkResolver, inboundLinks, } from './content/manifest.js';
-export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink } from './content/manifest.js';
-export { defineRegistry, emptyValues } from './render/registry.js';
-export type { ComponentDef, ComponentRegistry, FieldType, AttributeField, SlotKind, SlotDef, ComponentValues, } from './render/registry.js';
+export { serializeManifest, parseManifest, emptyManifest, verifyManifest, verifyReferences, diffManifests, upsertEntry, removeEntry, manifestEntryFromFile, manifestLinkResolver, inboundLinks, } from './content/manifest.js';
+export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink, InboundReference } from './content/manifest.js';
+export type { ReferenceEdge } from './content/references.js';
+export type { ResolvedReference } from './delivery/site-resolver.js';
+export { defineRegistry, defineComponent, emptyValues } from './render/registry.js';
+export type { ComponentDef, ComponentRegistry, SlotKind, SlotDef, ComponentValues, } from './render/registry.js';
 export { serializeComponent, parseComponent } from './render/component-grammar.js';
 export { validateComponent } from './render/component-validate.js';
 export type { ComponentValidation } from './render/component-validate.js';
@@ -29,7 +34,10 @@ export type { IconSet } from './render/glyph.js';
 export { remarkDirectiveStamp } from './render/remark-directives.js';
 export { createRenderer } from './render/pipeline.js';
 export type { RendererOptions } from './render/pipeline.js';
-export type { RepoRef, RepoFile, CommitAuthor, AppCredentials } from './github/types.js';
+export type { RepoFile, CommitAuthor } from './github/types.js';
 export { CommitConflictError } from './github/types.js';
-export { parseSiteConfig, urlPolicyFrom, extractMenu, setMenu, validateNavTree, MAX_NAV_NODES, NavValidationError, SiteConfigError, } from './nav/site-config.js';
+export { githubApp } from './github/backend.js';
+export type { Backend, BackendProvider, GithubAppProvider, BackendEnv } from './github/backend.js';
+export type { FileChange } from './github/repo.js';
+export { parseSiteConfig, extractMenu, setMenu, validateNavTree, MAX_NAV_NODES, NavValidationError, SiteConfigError, } from './nav/site-config.js';
 export type { NavNode, SiteConfig } from './nav/site-config.js';

package/dist/index.js

@@ -2,19 +2,21 @@
 // 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: 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';
 // Internal-link token and the committed content manifest (content-graph design). The corpus
 // 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';
@@ -27,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/log/events.d.ts

@@ -1 +1 @@
-export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'publish.address_collision' | 'github.unreachable' | 'guard.rejected' | 'media.uploaded' | 'media.upload_failed' | 'media.delivery_failed' | 'media.orphan_reconcile' | 'media.resolve_missing' | 'media.deleted' | 'media.delete_blocked' | 'media.bulk_deleted' | 'media.orphans_purged' | 'media.replaced' | 'media.replace_blocked' | 'media.alt_propagated' | 'dictionary.added' | 'dictionary.add_conflict' | 'tidy.done' | 'tidy.error' | 'tidy.refused' | 'tidy.empty';
+export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'publish.address_collision' | 'github.unreachable' | 'guard.rejected' | 'media.uploaded' | 'media.upload_failed' | 'media.delivery_failed' | 'media.orphan_reconcile' | 'media.resolve_missing' | 'media.resolver_absent' | 'media.deleted' | 'media.delete_blocked' | 'media.bulk_deleted' | 'media.orphans_purged' | 'media.replaced' | 'media.replace_blocked' | 'media.alt_propagated' | 'dictionary.added' | 'dictionary.add_conflict' | 'tidy.done' | 'tidy.error' | 'tidy.refused' | 'tidy.empty';

package/dist/media/index.d.ts

@@ -1,5 +1,5 @@
 export { normalizeAssets, type ResolvedAssetConfig } from './config.js';
-export { parseMediaManifest, findByHash, upsertMediaEntry, removeMediaEntry, serializeMediaManifest, parseMediaEntries, type MediaEntry, type MediaManifest, } from './manifest.js';
+export { parseMediaManifest, readCommittedManifest, findByHash, upsertMediaEntry, removeMediaEntry, serializeMediaManifest, parseMediaEntries, type MediaEntry, type MediaManifest, } from './manifest.js';
 export { hashBytes, shortHash, slugifyFilename, r2Key, publicPath } from './naming.js';
 export { presetUrl, variantUrl, type VariantSpec } from './transform-url.js';
 export { parseMediaToken, mediaToken, type MediaRef } from './reference.js';

package/dist/media/index.js

@@ -6,7 +6,7 @@
 // delivery-route factory and `requireBucket` stay on `/sveltekit`, off this surface, so the public
 // `.d.ts` for `/media` names no kit or workers-types type.
 export { normalizeAssets } from './config.js';
-export { parseMediaManifest, findByHash, upsertMediaEntry, removeMediaEntry, serializeMediaManifest, parseMediaEntries, } from './manifest.js';
+export { parseMediaManifest, readCommittedManifest, findByHash, upsertMediaEntry, removeMediaEntry, serializeMediaManifest, parseMediaEntries, } from './manifest.js';
 export { hashBytes, shortHash, slugifyFilename, r2Key, publicPath } from './naming.js';
 export { presetUrl, variantUrl } from './transform-url.js';
 export { parseMediaToken, mediaToken } from './reference.js';

package/dist/media/manifest.d.ts

@@ -26,6 +26,17 @@ export type MediaManifest = Record<string, MediaEntry>;
  *  object is returned as the manifest.
  */
 export declare function parseMediaManifest(json: unknown): MediaManifest;
+/**
+ * Read the committed media manifest from an `import.meta.glob` eager result, degrading a missing
+ *  file to an empty manifest. A static import of an absent `media.json` fails the Vite build before
+ *  any runtime degrade can run, so a fresh site with no manifest cannot build. A glob result is the
+ *  build-safe read: `import.meta.glob` returns `{}` when nothing matches rather than throwing, and
+ *  this helper extracts the single matched value and parses it, so a missing file reads a clean `{}`.
+ * @param globResult - The eager glob result for the committed manifest, an empty object when the
+ *  file is absent. The consumer passes
+ *  `import.meta.glob('<path-to-media.json>', { eager: true, import: 'default' })`.
+ */
+export declare function readCommittedManifest(globResult: Record<string, unknown>): MediaManifest;
 /**
  * Parse the posted `media` field into a validated list of MediaEntry rows. The field arrives as a
  *  JSON string (the usual form-post shape), an already-parsed array, or junk. A string is JSON-parsed

package/dist/media/manifest.js

@@ -13,6 +13,19 @@ export function parseMediaManifest(json) {
         return {};
     return json;
 }
+/**
+ * Read the committed media manifest from an `import.meta.glob` eager result, degrading a missing
+ *  file to an empty manifest. A static import of an absent `media.json` fails the Vite build before
+ *  any runtime degrade can run, so a fresh site with no manifest cannot build. A glob result is the
+ *  build-safe read: `import.meta.glob` returns `{}` when nothing matches rather than throwing, and
+ *  this helper extracts the single matched value and parses it, so a missing file reads a clean `{}`.
+ * @param globResult - The eager glob result for the committed manifest, an empty object when the
+ *  file is absent. The consumer passes
+ *  `import.meta.glob('<path-to-media.json>', { eager: true, import: 'default' })`.
+ */
+export function readCommittedManifest(globResult) {
+    return parseMediaManifest(Object.values(globResult)[0]);
+}
 /**
  * Validate one posted value as a MediaEntry, returning it narrowed or undefined. The trust boundary
  *  for an optimistic record the client re-posts: the upload action server-owned each field at

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/highlight.d.ts

@@ -0,0 +1,9 @@
+import type { Root } from 'hast';
+/**
+ * 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 declare function rehypeCairnHighlight(): (tree: Root) => Promise<void>;