@glw907/cairn-cms 0.56.1 → 0.57.0

package/dist/media/sniff.js

@@ -0,0 +1,106 @@
+// cairn-cms: content-type sniffing and the engine-level upload deny-list. The upload action trusts no
+// client-declared type: it sniffs the real type from the leading bytes and screens the payload against a
+// deny-list a site cannot override. Both functions are pure and Worker-clean (a plain Uint8Array, no
+// Node Buffer and no stream), so they run unchanged on Cloudflare Workers and under vitest.
+//
+// The sniff is necessary but not sufficient. A polyglot can carry a valid image magic and an HTML tail,
+// and this byte check sees only the magic. The delivery route's response headers (X-Content-Type-Options:
+// nosniff, Content-Disposition: inline, a restrictive Content-Security-Policy) are the real XSS control
+// for the served bytes; sniffing here is the ingest gate, not the served-bytes defense.
+/** The leading ASCII whitespace bytes skipped before the deny-list's first-byte-is-`<` check:
+ *  tab (0x09), newline (0x0A), carriage return (0x0D), and space (0x20). */
+const WHITESPACE = new Set([0x09, 0x0a, 0x0d, 0x20]);
+/** The single byte `<` (0x3C). A payload whose first non-whitespace byte is `<` is markup (SVG, HTML,
+ *  XML) and is denied regardless of its declared type or any site `allowedTypes`. */
+const LT = 0x3c;
+/** Declared content types denied at the engine level, independent of any site `allowedTypes`. SVG and
+ *  the markup types carry active content (script, foreignObject), so they never ingest as media. */
+const DENIED_TYPES = new Set(['image/svg+xml', 'image/svg', 'text/html', 'application/xml']);
+/** The ISO-BMFF major-brand codes (at bytes 8..11 of an `ftyp` box) that mean an AVIF image. */
+const AVIF_BRANDS = new Set(['avif', 'avis']);
+/** The ISO-BMFF major-brand codes that mean a HEIF/HEIC image. */
+const HEIC_BRANDS = new Set(['heic', 'heix', 'heif', 'hevc', 'hevx', 'mif1', 'msf1']);
+/** True when every byte of `magic` matches `bytes` starting at `offset`. False if `bytes` is too
+ *  short to hold the whole magic. */
+function matches(bytes, offset, magic) {
+    if (bytes.length < offset + magic.length)
+        return false;
+    for (let i = 0; i < magic.length; i++) {
+        if (bytes[offset + i] !== magic[i])
+            return false;
+    }
+    return true;
+}
+/** The four ASCII characters at bytes `offset..offset+3`, or null when the input is too short. Used to
+ *  read an ISO-BMFF brand code as a string. */
+function ascii4(bytes, offset) {
+    if (bytes.length < offset + 4)
+        return null;
+    return String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+}
+/**
+ * Detect the MIME type of an image from its leading magic bytes. Reads only the first ~32 bytes and
+ * returns the recognized type, or null for an unrecognized magic or an input too short for a given
+ * check. This is the server's source of truth for an upload's type; the client-declared type is
+ * advisory. Recognizes JPEG, PNG, GIF, WebP, and the AVIF/HEIC ISO-BMFF brands.
+ */
+export function sniffMediaType(bytes) {
+    // JPEG: starts FF D8 FF.
+    if (matches(bytes, 0, [0xff, 0xd8, 0xff]))
+        return 'image/jpeg';
+    // PNG: the 8-byte signature 89 50 4E 47 0D 0A 1A 0A; the leading 89 50 4E 47 ('.PNG') is enough.
+    if (matches(bytes, 0, [0x89, 0x50, 0x4e, 0x47]))
+        return 'image/png';
+    // GIF: 'GIF8' (the 87a and 89a versions share this prefix).
+    if (matches(bytes, 0, [0x47, 0x49, 0x46, 0x38]))
+        return 'image/gif';
+    // WebP: a RIFF container ('RIFF' at 0..3) whose form type is 'WEBP' at 8..11.
+    if (matches(bytes, 0, [0x52, 0x49, 0x46, 0x46]) && matches(bytes, 8, [0x57, 0x45, 0x42, 0x50])) {
+        return 'image/webp';
+    }
+    // AVIF and HEIC are ISO base media format files: an 'ftyp' box tag at bytes 4..7, then the 4-byte
+    // major brand at bytes 8..11. A truncated box (no brand bytes) or an unknown brand returns null.
+    if (matches(bytes, 4, [0x66, 0x74, 0x79, 0x70])) {
+        const brand = ascii4(bytes, 8);
+        if (brand !== null) {
+            if (AVIF_BRANDS.has(brand))
+                return 'image/avif';
+            if (HEIC_BRANDS.has(brand))
+                return 'image/heic';
+        }
+    }
+    return null;
+}
+/** The bare file extension (no dot) for each sniffed media type the upload path stores. The ext is
+ *  derived from the server-sniffed type, never the client filename, so the stored key and the
+ *  delivery extension allow-list always agree. An unmappable type returns null (the upload 415s). */
+const EXT_BY_TYPE = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/avif': 'avif',
+};
+/** The storage extension for a sniffed media type, or null for a type the upload path does not store
+ *  (HEIC, an unknown type). Driven by the sniffed type, so the key's ext is server-owned. */
+export function extForMediaType(type) {
+    return EXT_BY_TYPE[type] ?? null;
+}
+/**
+ * The engine-level upload deny predicate. Returns true (reject) when the upload is markup a site can
+ * never override: a declared type of image/svg+xml, image/svg, text/html, or application/xml, OR a
+ * payload whose first non-whitespace byte is `<` (an 0x3C after skipping leading ASCII whitespace).
+ * This runs ahead of and independent of any site `allowedTypes`, since SVG and HTML carry active
+ * content. The byte check catches a markup payload sent under a permitted declared type.
+ */
+export function isDeniedUpload(bytes, declaredType) {
+    if (declaredType !== undefined && DENIED_TYPES.has(declaredType.toLowerCase()))
+        return true;
+    for (let i = 0; i < bytes.length; i++) {
+        if (WHITESPACE.has(bytes[i]))
+            continue;
+        return bytes[i] === LT;
+    }
+    // An empty or all-whitespace payload has no opening byte to deny here; the type and size gates own it.
+    return false;
+}

package/dist/media/store.d.ts

@@ -0,0 +1,25 @@
+import type { R2Bucket, R2Conditional, R2HTTPMetadata, R2Object, R2ObjectBody, R2Range } from '@cloudflare/workers-types';
+/** The narrow R2 surface the media pipeline uses. The engine depends on this, not on R2Bucket, so the
+ *  multipart, list, and conditional-read surface R2 also carries never leaks into the media code. */
+export interface MediaStore {
+    /** Store bytes under a content-addressed key, with the response HTTP metadata (the content type)
+     *  and optional custom metadata (the upload stores the full sha256 here, so a short-hash collision
+     *  is detectable on a later dedup probe). */
+    put(key: string, bytes: ArrayBuffer | Uint8Array, httpMetadata?: R2HTTPMetadata, customMetadata?: Record<string, string>): Promise<void>;
+    /** The object's metadata, or null when no object lives at the key (the dedup probe). */
+    head(key: string): Promise<R2Object | null>;
+    /** The object body for streaming to a delivery response, or null when the key is absent. The
+     *  delivery route passes `onlyIf` and `range` through for conditional and partial reads: an
+     *  `onlyIf` etag match returns a body-less R2Object (the 304 shape), so the return widens to
+     *  `R2Object` alongside `R2ObjectBody`. */
+    get(key: string, opts?: {
+        range?: R2Range;
+        onlyIf?: R2Conditional;
+    }): Promise<R2ObjectBody | R2Object | null>;
+    /** Remove the object at the key. A delete of an absent key is a no-op, the R2 contract. */
+    delete(key: string): Promise<void>;
+}
+/** Wrap an R2 bucket binding as a MediaStore. Each method delegates to the binding; put folds the
+ *  HTTP and custom metadata into R2's options shape and drops the returned R2Object the pipeline does
+ *  not read. */
+export declare function r2Store(bucket: R2Bucket): MediaStore;

package/dist/media/store.js

@@ -0,0 +1,16 @@
+/** Wrap an R2 bucket binding as a MediaStore. Each method delegates to the binding; put folds the
+ *  HTTP and custom metadata into R2's options shape and drops the returned R2Object the pipeline does
+ *  not read. */
+export function r2Store(bucket) {
+    return {
+        async put(key, bytes, httpMetadata, customMetadata) {
+            const options = httpMetadata || customMetadata
+                ? { ...(httpMetadata ? { httpMetadata } : {}), ...(customMetadata ? { customMetadata } : {}) }
+                : undefined;
+            await bucket.put(key, bytes, options);
+        },
+        head: (key) => bucket.head(key),
+        get: (key, opts) => bucket.get(key, opts),
+        delete: (key) => bucket.delete(key),
+    };
+}

package/dist/media/transform-url.d.ts

@@ -0,0 +1,26 @@
+/** A single image variant: the resize and format directives Cloudflare Images applies to the
+ *  original bytes. Every field is optional. width, height, quality, and fit are emitted only when
+ *  set; format and gravity always appear, defaulting to auto. */
+export interface VariantSpec {
+    /** Target width in pixels. */
+    width?: number;
+    /** Target height in pixels. */
+    height?: number;
+    /** Output quality, 1 to 100. */
+    quality?: number;
+    /** How the image fits the target box. */
+    fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+    /** Crop focus, `auto` or `face` or a coordinate string. */
+    gravity?: 'auto' | 'face' | string;
+    /** Output format, `auto` to let Cloudflare negotiate, or a forced codec. */
+    format?: 'auto' | 'webp' | 'avif' | string;
+}
+/** Build the on-demand Cloudflare Images transform URL for a delivery path. The options are
+ *  comma-joined in the stable order width, height, quality, fit, format, gravity, with width through
+ *  fit emitted only when the spec sets them and format and gravity always present (defaulting to
+ *  auto). The publicPath is appended unaltered, so the result is `/cdn-cgi/image/<options><publicPath>`. */
+export declare function variantUrl(publicPath: string, spec: VariantSpec): string;
+/** Build a variant URL from a named preset. Looks up presetName in variants and builds its spec with
+ *  variantUrl. Throws a cairn:-prefixed error naming the unknown preset when the name is absent, so a
+ *  typo in a preset name fails loudly rather than silently rendering an unsized image. */
+export declare function presetUrl(publicPath: string, presetName: string, variants: Record<string, VariantSpec>): string;

package/dist/media/transform-url.js

@@ -0,0 +1,38 @@
+// cairn-cms: the Cloudflare Images transform URL. A delivery path names the original bytes; an
+// on-demand variant is that path prefixed with `/cdn-cgi/image/<options>/`, where the options are a
+// comma-joined list of resize and format directives Cloudflare reads at the edge. This module owns
+// the option encoding and the stable option order, so the same spec always builds the same URL and
+// a CDN cache keys on it cleanly. The delivery path is appended unaltered, since it already carries
+// its own leading slash.
+/** Build the on-demand Cloudflare Images transform URL for a delivery path. The options are
+ *  comma-joined in the stable order width, height, quality, fit, format, gravity, with width through
+ *  fit emitted only when the spec sets them and format and gravity always present (defaulting to
+ *  auto). The publicPath is appended unaltered, so the result is `/cdn-cgi/image/<options><publicPath>`. */
+export function variantUrl(publicPath, spec) {
+    const options = [];
+    if (spec.width !== undefined)
+        options.push(`width=${spec.width}`);
+    if (spec.height !== undefined)
+        options.push(`height=${spec.height}`);
+    if (spec.quality !== undefined)
+        options.push(`quality=${spec.quality}`);
+    if (spec.fit !== undefined)
+        options.push(`fit=${spec.fit}`);
+    options.push(`format=${spec.format ?? 'auto'}`);
+    options.push(`gravity=${spec.gravity ?? 'auto'}`);
+    // The source must be its own path segment after the options, so it needs a leading slash;
+    // Cloudflare reads a slashless join as a malformed options list. publicPath carries one, but this
+    // guards a caller that passes a relative path from fusing the options and the source.
+    const source = publicPath.startsWith('/') ? publicPath : `/${publicPath}`;
+    return `/cdn-cgi/image/${options.join(',')}${source}`;
+}
+/** Build a variant URL from a named preset. Looks up presetName in variants and builds its spec with
+ *  variantUrl. Throws a cairn:-prefixed error naming the unknown preset when the name is absent, so a
+ *  typo in a preset name fails loudly rather than silently rendering an unsized image. */
+export function presetUrl(publicPath, presetName, variants) {
+    const spec = variants[presetName];
+    if (spec === undefined) {
+        throw new Error(`cairn: unknown image variant preset "${presetName}"`);
+    }
+    return variantUrl(publicPath, spec);
+}

package/dist/media/usage.d.ts

@@ -0,0 +1,48 @@
+import type { ConceptDescriptor } from '../content/types.js';
+import type { RepoRef } from '../github/types.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 = {
+    kind: 'published';
+} | {
+    kind: 'branch';
+    branch: string;
+};
+/** One entry that references an asset, in a shape the screen links and groups by. */
+export interface UsageEntry {
+    /** The concept id, e.g. "posts". */
+    concept: string;
+    /** The entry id (its filename stem). */
+    id: string;
+    /** The entry title for display, from the manifest (published) or frontmatter (branch). */
+    title: string;
+    /** The public permalink, present for a published entry (carried from the manifest). */
+    permalink?: string;
+    /** Published vs the cairn/* branch the edit lives on. */
+    origin: UsageOrigin;
+}
+/** Content hash to the distinct entries that reference it. A hash with no row is "no references
+ *  found" (see the raw-HTML caveat above), never a proven orphan. */
+export type UsageIndex = Map<string, UsageEntry[]>;
+/** Build options. `branches` lets a caller that already listed the open cairn/* branches pass them
+ *  in so the index does not list them a second time (the load path lists once for the media-union).
+ *  `strict` flips the per-branch read from degrade-and-skip to fail-closed: a delete gate must not
+ *  treat a transient branch-read failure as an absent reference, so it rethrows instead. */
+export interface BuildUsageOptions {
+    /** The open cairn/* branch names, already listed. When present the index skips its own listing. */
+    branches?: string[];
+    /** When true a branch read that throws rejects the whole build, so the caller can fail closed. */
+    strict?: boolean;
+}
+/**
+ * Build the hash-keyed usage index over main (from the manifest's per-entry mediaRefs) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read, rather than sinking the whole screen. That tolerance is right
+ * for the Library DISPLAY, but wrong for the delete gate: a transient branch-read failure would make
+ * a still-referenced asset look orphaned. Pass `strict: true` (the delete path) to rethrow a branch
+ * 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>;

package/dist/media/usage.js

@@ -0,0 +1,90 @@
+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';
+import { parseMarkdown } from '../content/frontmatter.js';
+import { extractMediaRefs } from '../content/media-refs.js';
+/** Append a row under its hash, creating the bucket on first use. */
+function push(index, hash, entry) {
+    const rows = index.get(hash);
+    if (rows)
+        rows.push(entry);
+    else
+        index.set(hash, [entry]);
+}
+/**
+ * Build the hash-keyed usage index over main (from the manifest's per-entry mediaRefs) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read, rather than sinking the whole screen. That tolerance is right
+ * for the Library DISPLAY, but wrong for the delete gate: a transient branch-read failure would make
+ * a still-referenced asset look orphaned. Pass `strict: true` (the delete path) to rethrow a branch
+ * 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 = {}) {
+    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.
+    for (const entry of manifest.entries) {
+        for (const hash of entry.mediaRefs ?? []) {
+            push(index, hash, {
+                concept: entry.concept,
+                id: entry.id,
+                title: entry.title,
+                permalink: entry.permalink,
+                origin: { kind: 'published' },
+            });
+        }
+    }
+    // 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));
+    // 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
+    // wider Promise.all, since the combined fan-out would queue behind that throttle.
+    const perBranch = await Promise.all(names.map(async (name) => {
+        // Resolve the branch name to a configured entry with the same guard the branch tooling uses: a
+        // malformed name, an id that fails the slug rule (entry paths are built from it, so this is the
+        // path confinement), or a concept this site does not configure is skipped, no read attempted.
+        const ref = parsePendingBranch(name);
+        if (!ref || !isValidId(ref.id))
+            return [];
+        const concept = findConcept(concepts, ref.concept);
+        if (!concept)
+            return [];
+        const path = `${concept.dir}/${filenameFromId(ref.id)}`;
+        try {
+            const raw = await readRaw({ ...repo, branch: name }, path, token);
+            if (raw === null)
+                return []; // The file is absent on the branch: nothing to extract.
+            const { frontmatter, body } = parseMarkdown(raw);
+            const fmTitle = frontmatter.title;
+            const title = typeof fmTitle === 'string' && fmTitle.trim() ? fmTitle : ref.id;
+            const rows = [];
+            for (const hash of extractMediaRefs(frontmatter, body, concept.fields)) {
+                rows.push({
+                    hash,
+                    entry: { concept: concept.id, id: ref.id, title, origin: { kind: 'branch', branch: name } },
+                });
+            }
+            return rows;
+        }
+        catch (err) {
+            // In strict mode a branch failure fails the whole build so the delete gate can fail closed;
+            // otherwise degrade this one branch rather than sinking the screen.
+            if (opts.strict)
+                throw err;
+            return [];
+        }
+    }));
+    // Fold the per-branch rows back in, preserving the branch order so the index reads stably.
+    for (const rows of perBranch) {
+        for (const { hash, entry } of rows)
+            push(index, hash, entry);
+    }
+    return index;
+}

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

@@ -7,6 +7,26 @@ export declare function parseComponent(markdown: string, def: ComponentDef): Pro
 /** The raw attribute keys present on the component's opening directive, read from the parsed tree
  *  (quote-aware, unlike a regex over the source). Used by validation to flag unknown keys. */
 export declare function parseRawAttributeKeys(markdown: string, def: ComponentDef): string[];
+/** The result of {@link componentRoundTripSafety}: whether re-opening a placed block into the
+ *  guided form and re-serializing it is provably lossless. */
+export type RoundTripSafety = {
+    safe: true;
+} | {
+    safe: false;
+    reason: 'unknown-attribute' | 'undeclared-child' | 'not-idempotent' | 'not-a-component';
+};
+/** Decide whether guided edit of this placed block is provably lossless. A block a person typed by
+ *  hand can carry more than the schema models (an attribute the def does not list, a child container
+ *  the def does not declare, slot content the form cannot represent stably), and parsing such a block
+ *  into the form then re-serializing would silently drop it. The edit affordance is offered only when
+ *  this returns `{ safe: true }`. Checks run in order and return the first failure:
+ *
+ *  1. `not-a-component`: the def's opening container is not present.
+ *  2. `unknown-attribute`: the block carries an attribute key the def does not declare.
+ *  3. `undeclared-child`: the root has a direct child container directive that is not a declared
+ *     nested slot. Such a child would otherwise fold into the body slot and move on re-serialize.
+ *  4. `not-idempotent`: `parse -> serialize -> parse` does not recover the same values. */
+export declare function componentRoundTripSafety(markdown: string, def: ComponentDef): Promise<RoundTripSafety>;
 /** Parse the component once and derive both the guided-form values and the raw attribute keys.
  *  Validation needs both, so this seam spares it the double parse that calling
  *  {@link parseComponent} and {@link parseRawAttributeKeys} separately would cost. */

package/dist/render/component-grammar.js

@@ -58,7 +58,7 @@ function isContainer(node) {
 }
 // Pin the bullet to `-` so a markdown body or slot that uses dash bullets round-trips unchanged
 // rather than drifting to remark-stringify's default `*`, which would silently mutate author content.
-const toMd = unified().use(remarkStringify, { bullet: '-' });
+const toMd = unified().use(remarkDirective).use(remarkStringify, { bullet: '-' });
 /** Render mdast children back to trimmed markdown text. */
 function childrenToText(children) {
     const root = { type: 'root', children };
@@ -120,6 +120,40 @@ export async function parseComponent(markdown, def) {
 export function parseRawAttributeKeys(markdown, def) {
     return rawKeysFromRoot(findComponentRoot(markdown, def));
 }
+/** Decide whether guided edit of this placed block is provably lossless. A block a person typed by
+ *  hand can carry more than the schema models (an attribute the def does not list, a child container
+ *  the def does not declare, slot content the form cannot represent stably), and parsing such a block
+ *  into the form then re-serializing would silently drop it. The edit affordance is offered only when
+ *  this returns `{ safe: true }`. Checks run in order and return the first failure:
+ *
+ *  1. `not-a-component`: the def's opening container is not present.
+ *  2. `unknown-attribute`: the block carries an attribute key the def does not declare.
+ *  3. `undeclared-child`: the root has a direct child container directive that is not a declared
+ *     nested slot. Such a child would otherwise fold into the body slot and move on re-serialize.
+ *  4. `not-idempotent`: `parse -> serialize -> parse` does not recover the same values. */
+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));
+    for (const key of parseRawAttributeKeys(markdown, def)) {
+        if (!declaredKeys.has(key))
+            return { safe: false, reason: 'unknown-attribute' };
+    }
+    const slotNames = new Set(nestedSlots(def).map((s) => s.name));
+    for (const child of root.children) {
+        if (isContainer(child) && !slotNames.has(child.name)) {
+            return { safe: false, reason: 'undeclared-child' };
+        }
+    }
+    // The values are plain strings, booleans, and string arrays in declared (object-key) order, so a
+    // stable JSON.stringify is a sufficient deep-equal.
+    const v1 = await parseComponent(markdown, def);
+    const v2 = await parseComponent(serializeComponent(def, v1), def);
+    if (JSON.stringify(v1) !== JSON.stringify(v2))
+        return { safe: false, reason: 'not-idempotent' };
+    return { safe: true };
+}
 /** Parse the component once and derive both the guided-form values and the raw attribute keys.
  *  Validation needs both, so this seam spares it the double parse that calling
  *  {@link parseComponent} and {@link parseRawAttributeKeys} separately would cost. */
@@ -146,8 +180,18 @@ function isDirectiveLabel(node) {
 function readLabel(root) {
     for (const child of root.children) {
         const p = child;
-        if (p.type === 'paragraph' && p.data?.directiveLabel)
-            return (p.children ?? []).map((c) => c.value ?? '').join('');
+        if (p.type !== 'paragraph' || !p.data?.directiveLabel)
+            continue;
+        const kids = p.children ?? [];
+        // When every label child is a plain text node, join the raw `.value`s. That keeps the pure-text
+        // path identical to before, so a literal `[` or `]` in the title is not re-escaped by the
+        // stringifier (serializeComponent already escapes brackets, and remark un-escapes them on parse).
+        // When the label carries inline markdown (a link, bold, emphasis), the text-only join would drop
+        // the markup, so stringify the children to recover the full inline source losslessly.
+        if (kids.every((c) => c.type === 'text')) {
+            return kids.map((c) => c.value ?? '').join('');
+        }
+        return childrenToText(kids);
     }
     return undefined;
 }

package/dist/render/component-validate.js

@@ -12,6 +12,16 @@ export async function validateComponent(markdown, def) {
         }
         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;
         }
     }
     for (const key of rawKeys) {
@@ -28,3 +38,15 @@ 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

@@ -1,5 +1,6 @@
 import { type PluggableList } from 'unified';
 import type { Schema } from 'hast-util-sanitize';
+import { type MediaResolve } from './resolve-media.js';
 import { type ComponentRegistry } from './registry.js';
 import type { LinkResolve } from '../content/links.js';
 export interface RendererOptions {
@@ -29,5 +30,6 @@ export declare function createRenderer(registry?: ComponentRegistry, options?: R
     rehypePlugins: PluggableList;
     renderMarkdown: (content: string, opts?: {
         resolve?: LinkResolve;
+        resolveMedia?: MediaResolve;
     }) => Promise<string>;
 };

package/dist/render/pipeline.js

@@ -10,14 +10,22 @@ import rehypeSanitize from 'rehype-sanitize';
 import { VFile } from 'vfile';
 import { buildSanitizeSchema, rehypeAnchorRel, rehypeSinkGuard } from './sanitize-schema.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
+import { remarkFigure } from './remark-figure.js';
 import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
+import { remarkResolveMedia, MEDIA_RESOLVE } from './resolve-media.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
 import { defineRegistry } from './registry.js';
 /** Compose a site's render pipeline from its component registry: directive syntax to
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
 export function createRenderer(registry = defineRegistry({ components: [] }), options = {}) {
-    const remarkPlugins = [remarkDirective, [remarkDirectiveStamp, registry], remarkResolveCairnLinks];
+    const remarkPlugins = [
+        remarkDirective,
+        [remarkDirectiveStamp, registry],
+        remarkResolveCairnLinks,
+        remarkFigure,
+        remarkResolveMedia,
+    ];
     // The sanitize floor runs after rehype-raw (so author raw HTML is parsed, then cleaned) and
     // before the dispatch (so the site's trusted build() output and its inline SVG icons are never
     // sanitized). The anchor-rel hardening runs last so it also covers component-built anchors.
@@ -48,7 +56,10 @@ export function createRenderer(registry = defineRegistry({ components: [] }), op
         remarkPlugins,
         rehypePlugins,
         renderMarkdown: async (content, opts = {}) => {
-            const file = new VFile({ value: content, data: { [CAIRN_RESOLVE]: opts.resolve } });
+            const file = new VFile({
+                value: content,
+                data: { [CAIRN_RESOLVE]: opts.resolve, [MEDIA_RESOLVE]: opts.resolveMedia },
+            });
             return String(await processor.process(file));
         },
     };

package/dist/render/registry.d.ts

@@ -15,6 +15,15 @@ export interface AttributeField {
     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;
 }
 export type SlotKind = 'markdown' | 'inline' | 'repeatable';
 /** One named content region of a component. The slots named `title` and `body` are special: `title`
@@ -27,6 +36,9 @@ export interface SlotDef {
     help?: string;
     /** For `kind: 'repeatable'`: the fields composing each list item (v1 uses the first field). */
     itemFields?: AttributeField[];
+    /** 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}`. */
+    itemLabel?: (item: Record<string, string | boolean>, index: number) => string;
 }
 /** The structured input a component's `build` receives. The engine stamps the component's
  *  attributes and partitions its slots from the rendered hast, so `build` arranges hast and
@@ -64,6 +76,18 @@ export interface ComponentDef {
     attributes?: AttributeField[];
     /** The named content regions this component accepts. */
     slots?: SlotDef[];
+    /** A glyph key from the site IconSet, shown beside the label in the picker. */
+    icon?: string;
+    /** A category heading for the picker. Components order by declaration within a group. */
+    group?: string;
+    /** Omit from the top-level picker (for a nested or round-trip-only component). */
+    hidden?: boolean;
+    /** A structured sample the picker seeds the form with and renders through the same path a real
+     *  insert takes. Declaring `preview` is what opts the component into the two-pane configure layout. */
+    preview?: {
+        attributes?: Record<string, string | boolean>;
+        slots?: Record<string, string | string[]>;
+    };
 }
 export interface ComponentRegistry {
     defs: ComponentDef[];
@@ -93,3 +117,7 @@ export interface ComponentValues {
 /** Seed an empty {@link ComponentValues} from a component's schema: attribute defaults (or '' / false)
  *  and empty slot values ([] for repeatable, '' otherwise). */
 export declare function emptyValues(def: ComponentDef): ComponentValues;
+/** Seed {@link ComponentValues} from a component's `preview` sample: the {@link emptyValues} base
+ *  with `def.preview.attributes` and `def.preview.slots` overlaid (a shallow merge per side). When
+ *  the def declares no `preview`, returns exactly the {@link emptyValues} output. */
+export declare function previewValues(def: ComponentDef): ComponentValues;

package/dist/render/registry.js

@@ -16,6 +16,9 @@ function findIconField(def) {
  */
 export function defineRegistry({ components }) {
     for (const c of components) {
+        if (c.name === 'figure') {
+            throw new Error('cairn: "figure" is a reserved directive name handled by the engine render step; a component cannot use it');
+        }
         if (c.defaultIconByRole && Object.keys(c.defaultIconByRole).length > 0 && !findIconField(c)) {
             throw new Error(`cairn: component "${c.name}" sets defaultIconByRole but declares no type:'icon' attribute, so the default icon can never render`);
         }
@@ -45,3 +48,15 @@ export function emptyValues(def) {
     }
     return { attributes, slots };
 }
+/** Seed {@link ComponentValues} from a component's `preview` sample: the {@link emptyValues} base
+ *  with `def.preview.attributes` and `def.preview.slots` overlaid (a shallow merge per side). When
+ *  the def declares no `preview`, returns exactly the {@link emptyValues} output. */
+export function previewValues(def) {
+    const base = emptyValues(def);
+    if (!def.preview)
+        return base;
+    return {
+        attributes: { ...base.attributes, ...def.preview.attributes },
+        slots: { ...base.slots, ...def.preview.slots },
+    };
+}

package/dist/render/remark-figure.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+/** Rewrite the reserved `figure` container directive into a placed <figure>. Every other directive
+ *  is left to remarkDirectiveStamp, which already skips unregistered names. */
+export declare function remarkFigure(): (tree: Root) => void;