@glw907/cairn-cms 0.56.0 → 0.56.2

package/src/lib/components/EditPage.svelte

@@ -21,6 +21,7 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   import { beforeNavigate } from '$app/navigation';
   import { page } from '$app/state';
   import BlocksIcon from '@lucide/svelte/icons/blocks';
+  import SquarePenIcon from '@lucide/svelte/icons/square-pen';
   import LinkIcon from '@lucide/svelte/icons/link';
   import FileSymlinkIcon from '@lucide/svelte/icons/file-symlink';
   import PanelRightIcon from '@lucide/svelte/icons/panel-right';
@@ -28,7 +29,7 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   import CsrfField from './CsrfField.svelte';
   import MarkdownEditor from './MarkdownEditor.svelte';
   import EditorToolbar from './EditorToolbar.svelte';
-  import ComponentInsertDialog, { insertableDefs } from './ComponentInsertDialog.svelte';
+  import ComponentInsertDialog, { insertableDefs, hasSchema } from './ComponentInsertDialog.svelte';
   import LinkPicker from './LinkPicker.svelte';
   import WebLinkDialog from './WebLinkDialog.svelte';
   import DeleteDialog from './DeleteDialog.svelte';
@@ -39,7 +40,8 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   import { unwrapCairnLink, type FormatKind } from './markdown-format.js';
   import { buildPreviewDoc, deviceLabel, previewDevice, previewDevices, type PreviewDeviceId } from './preview-doc.js';
   import { directiveLineKind, findInlineDirectives } from './markdown-directives.js';
-  import type { ComponentRegistry } from '../render/registry.js';
+  import type { ComponentRegistry, ComponentDef } from '../render/registry.js';
+  import { parseComponent, componentRoundTripSafety } from '../render/component-grammar.js';
   import type { IconSet } from '../render/glyph.js';
   import type { ContentFormFailure, EditData } from '../sveltekit/content-routes.js';
   import type { TextareaField, TagsField, FreeTagsField } from '../content/types.js';
@@ -263,6 +265,10 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // Which pane the editor card shows. The toolbar's tablist drives it; Write is always the
   // landing tab.
   let mode = $state<'write' | 'preview'>('write');
+  // Preview is read-only, so the insert controls the page renders into the toolbar disable with the
+  // strip's own format buttons. Declared here (above the Edit-block derivations that read it) so it
+  // is in scope before its first use.
+  const insertDisabled = $derived(mode === 'preview');
   let previewHtml = $state('');
   // True after a render call threw, so the preview pane can say so instead of going blank.
   let previewFailed = $state(false);
@@ -353,6 +359,9 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // preview knob, or a styleless document (behind the hint below) when the site sets none.
   const previewDoc = $derived(buildPreviewDoc(previewHtml, data.preview));
   let insert = $state.raw<(text: string) => void>(() => {});
+  // The editor's range-replace seam, registered by MarkdownEditor on mount; the dialog's Update
+  // routes through it to overwrite an edited block's source span. A no-op until then.
+  let replaceRange = $state.raw<(from: number, to: number, text: string) => void>(() => {});
   let insertLink = $state.raw<(href: string, title: string) => void>(() => {});
   // The editor's current selection, registered by MarkdownEditor on mount; the web link dialog
   // reads it for the Text field's default.
@@ -366,7 +375,9 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // breaks SSR and hydration); the toolbar snippet renders plain triggers that open them here.
   let webLinkDialog = $state<DialogHandle | null>(null);
   let linkPicker = $state<DialogHandle | null>(null);
-  let insertDialog = $state<DialogHandle | null>(null);
+  // The insert dialog binds the full instance, not the bare DialogHandle: the Edit-block control
+  // drives editComponent(def, values, range) on it, beyond the shared open().
+  let insertDialog = $state<ComponentInsertDialog | null>(null);
   // The lifecycle dialogs, opened from the header's overflow menu.
   let deleteDialog = $state<DialogHandle | null>(null);
   let renameDialog = $state<DialogHandle | null>(null);
@@ -379,6 +390,92 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   // by, so the toolbar trigger and the dialog appear and disappear together.
   const hasComponents = $derived(insertableDefs(registry).length > 0);
 
+  // The directive container at the editor caret, reported by MarkdownEditor whenever it changes
+  // (null outside any container). The Edit-block control resolves it against the registry and the
+  // round-trip safety gate below; its identity is the key the async gate guards against a stale
+  // result. The reporter's name+markdown+from+to shape; declared locally because MarkdownEditor's
+  // matching interface is not exported.
+  type CaretComponent = { name: string | null; markdown: string; from: number; to: number };
+  let caretComponent = $state<CaretComponent | null>(null);
+  // A def is actionable for guided edit when it has a schema (the same notion the insert catalog
+  // lists by): a template-only def has no form to re-open into. Reuses the dialog's exported
+  // hasSchema so the two surfaces can never drift on what counts as editable.
+  function editableDef(name: string | null): ComponentDef | undefined {
+    if (!name) return undefined;
+    const def = registry?.get(name);
+    if (!def) return undefined;
+    return hasSchema(def) ? def : undefined;
+  }
+  // The resolved editability: the def, the source range, and the validated markdown when the caret
+  // sits on a known, schema-bearing component whose round-trip safety check passed for the CURRENT
+  // caret; null otherwise. The def, range, and markdown are captured from one caretComponent
+  // snapshot, so editBlock() never mixes a newer markdown with an older range. The Edit-block
+  // control enables only when this is set.
+  let editable = $state<{ def: ComponentDef; range: { from: number; to: number }; markdown: string } | null>(null);
+  // Why edit is unavailable, distinguishing "not on a component" from "on an unsafe one" so the
+  // disabled tooltip is honest. 'none' covers both no-caret-component and an unknown/template-only
+  // one (no guided form either way); 'unsafe' is a known component the safety gate refused.
+  let editReason = $state<'none' | 'unsafe'>('none');
+  // Resolve editability when the caret-component changes, async-safe. componentRoundTripSafety is
+  // async, so a slow check could resolve after a newer caret move; guard latest-wins on the
+  // caretComponent identity (the EditPage preview-debounce pattern), only applying a result when
+  // the caret has not moved since the check started. A block whose check did not pass for the
+  // current caret never enables edit.
+  $effect(() => {
+    const current = caretComponent;
+    const def = editableDef(current?.name ?? null);
+    if (!current || !def) {
+      editable = null;
+      editReason = 'none';
+      return;
+    }
+    let stale = false;
+    void componentRoundTripSafety(current.markdown, def)
+      .then((result) => {
+        if (stale || caretComponent !== current) return;
+        if (result.safe) {
+          editable = { def, range: { from: current.from, to: current.to }, markdown: current.markdown };
+          editReason = 'none';
+        } else {
+          editable = null;
+          editReason = 'unsafe';
+        }
+      })
+      .catch(() => {
+        // A parse throw during the safety check must never leave a stale block enabled. Guarded by
+        // the same latest-wins identity, fall back to the safe default of no editable block.
+        if (stale || caretComponent !== current) return;
+        editable = null;
+        editReason = 'none';
+      });
+    return () => {
+      stale = true;
+    };
+  });
+  // The Edit-block control's accessible label and tooltip: a plain reason in each state. Enabled
+  // names the action; the two disabled reasons are honest about why.
+  const editBlockLabel = $derived(
+    editable
+      ? 'Edit the component at the cursor'
+      : editReason === 'unsafe'
+        ? "This block can't be edited in the form. Edit it as markdown."
+        : 'Place the cursor in a component to edit it',
+  );
+  // Whether the Edit-block control is unavailable: either Preview hides the Write surface, or the
+  // caret is not on a safe, schema-bearing component. The control stays focusable and announced in
+  // this state (aria-disabled, not the native disabled attribute), so its reason reaches assistive
+  // technology; the dead click is made inert in editBlock().
+  const editBlockUnavailable = $derived(insertDisabled || !editable);
+  // Activate edit: parse the block into form values, then open the dialog in edit mode over the
+  // stored source range. Guarded by editable AND the preview-mode disable, so the control is inert
+  // unless the gate passed and the editor is on the Write tab. The def, range, and markdown all come
+  // from the one editable snapshot, so a newer caret markdown is never paired with an older range.
+  async function editBlock() {
+    if (insertDisabled || !editable) return;
+    const values = await parseComponent(editable.markdown, editable.def);
+    insertDialog?.editComponent(editable.def, values, editable.range);
+  }
+
   // The header's status badge, in ConceptList's vocabulary: a pending entry reads Edited (or New
   // when it has never been published); otherwise the live site matches and it reads Published.
   const status = $derived.by(() => {
@@ -563,10 +660,6 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     mode = m;
   }
 
-  // Preview is read-only, so the insert controls the page renders into the toolbar disable with
-  // the strip's own format buttons.
-  const insertDisabled = $derived(mode === 'preview');
-
   // The editor card's keyboard shortcuts. Bound to the card so they fire wherever focus sits in the
   // strip or the surface, without claiming the keys page-wide. The listener attaches
   // programmatically: it is event delegation, not an interaction affordance, which Svelte's a11y
@@ -903,6 +996,24 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
             >
               <BlocksIcon class="h-4 w-4" aria-hidden="true" />
             </button>
+            <!-- Edit block re-opens the component at the caret into the guided form. It is
+                 unavailable while Preview shows (like the insert controls) and whenever the caret is
+                 not on a safe, schema-bearing component; the tooltip names the reason in each state.
+                 The unavailable state uses aria-disabled, not the native disabled attribute, so the
+                 control stays focusable and its reason reaches assistive technology; the disabled
+                 look rides a class and editBlock() early-returns so the dead click is inert. -->
+            <button
+              type="button"
+              class="btn btn-sm btn-ghost btn-square"
+              class:btn-disabled={editBlockUnavailable}
+              aria-haspopup="dialog"
+              aria-label={editBlockLabel}
+              title={editBlockLabel}
+              aria-disabled={editBlockUnavailable}
+              onclick={editBlock}
+            >
+              <SquarePenIcon class="h-4 w-4" aria-hidden="true" />
+            </button>
           {/if}
           <button
             type="button"
@@ -950,6 +1061,8 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
           name="body"
           {surface}
           registerInsert={(fn) => (insert = fn)}
+          onComponentAtCaret={(info) => (caretComponent = info)}
+          registerReplaceRange={(fn) => (replaceRange = fn)}
           registerInsertLink={(fn) => (insertLink = fn)}
           registerGetSelection={(fn) => (getSelection = fn)}
           registerFormat={(fn) => (format = fn)}
@@ -1239,7 +1352,16 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
      <form>, and a form nested in a form is invalid HTML the parser repairs by dropping the outer
      tag, which breaks the SSR'd document and hydration. The toolbar snippet's triggers drive them
      through their exported open(). -->
-<ComponentInsertDialog bind:this={insertDialog} trigger={false} {registry} {insert} {icons} />
+<ComponentInsertDialog
+  bind:this={insertDialog}
+  trigger={false}
+  {registry}
+  {insert}
+  update={(range, md) => replaceRange(range.from, range.to, md)}
+  {icons}
+  {render}
+  preview={data.preview}
+/>
 <WebLinkDialog bind:this={webLinkDialog} trigger={false} insert={insertLink} selection={getSelection} />
 <LinkPicker bind:this={linkPicker} trigger={false} linkTargets={data.linkTargets} insert={insertLink} />
 

package/src/lib/components/MarkdownEditor.svelte

@@ -10,6 +10,16 @@ through the adapter's render. Swapping the editor stays a one-file change.
 <script lang="ts">
   import { onMount, onDestroy } from 'svelte';
   import { applyMarkdownFormat, insertInlineLink, type FormatKind, type FormatResult } from './markdown-format.js';
+  import { fenceScan, caretContainerRange, directiveOpenerName } from './markdown-directives.js';
+
+  /** The directive container at the caret: the opener's name, the block's markdown, and the
+   *  document character offsets of its inclusive line range. */
+  interface ComponentAtCaret {
+    name: string | null;
+    markdown: string;
+    from: number;
+    to: number;
+  }
 
   interface Props {
     /** The markdown source; bindable so the parent reads edits back. */
@@ -24,6 +34,12 @@ through the adapter's render. Swapping the editor stays a one-file change.
     registerGetSelection?: (get: () => string) => void;
     /** Receives a `(kind) => void` that transforms the current selection; the host's toolbar calls it. */
     registerFormat?: (format: (kind: FormatKind) => void) => void;
+    /** Reports the directive container at the caret (or null when outside any container) whenever
+     *  the reported value changes; the host resolves it against the registry to offer Edit-block. */
+    onComponentAtCaret?: (info: ComponentAtCaret | null) => void;
+    /** Receives a `(from, to, text) => void` that overwrites a document span; the dialog's Update
+     *  calls it to write an edited block back over its original range. */
+    registerReplaceRange?: (replace: (from: number, to: number, text: string) => void) => void;
     /** Generic CodeMirror completion sources wired into the editor; the link autocomplete is one. The
      *  type is referenced inline so no static `@codemirror/*` import sits in this client-only file. */
     completionSources?: import('@codemirror/autocomplete').CompletionSource[];
@@ -43,6 +59,8 @@ through the adapter's render. Swapping the editor stays a one-file change.
     registerInsertLink,
     registerGetSelection,
     registerFormat,
+    onComponentAtCaret,
+    registerReplaceRange,
     completionSources = [],
     focusMode = false,
     typewriter = false,
@@ -365,6 +383,10 @@ through the adapter's render. Swapping the editor stays a one-file change.
           surfaceCompartment.of(surface === 'prose' ? proseTheme : markupTheme),
           EditorView.updateListener.of((update) => {
             if (update.docChanged) value = update.state.doc.toString();
+            // A doc edit can change the block's span and a caret move can change which block the
+            // caret sits in, so the reporter runs on either; the dedupe below absorbs the no-ops.
+            if (onComponentAtCaret && (update.docChanged || update.selectionSet))
+              reportComponentAtCaret(update.state);
           }),
         ],
       }),
@@ -374,6 +396,10 @@ through the adapter's render. Swapping the editor stays a one-file change.
     registerInsertLink?.(insertLink);
     registerGetSelection?.(selectedText);
     registerFormat?.(applyFormat);
+    registerReplaceRange?.(replaceRange);
+    // Report the caret's starting container once the editor exists, so a caret that mounts inside
+    // a block is known without waiting for the first move.
+    if (onComponentAtCaret) reportComponentAtCaret(view.state);
     mounted = true;
   });
 
@@ -406,6 +432,55 @@ through the adapter's render. Swapping the editor stays a one-file change.
     });
   });
 
+  // The last value handed to onComponentAtCaret, so the reporter fires only on a change. The
+  // identity compared is name + markdown + from + to. A pure caret move within one block leaves all
+  // four unchanged, so it does not refire; an edit inside the block changes the markdown even when
+  // it keeps the same length (an equal-length replacement leaves from and to unchanged), so the
+  // markdown must be part of the equality or such an edit would keep a stale report.
+  let lastCaretReport: ComponentAtCaret | null = null;
+
+  // Compute the directive container at the caret from a CodeMirror state and report it through
+  // onComponentAtCaret, deduped so a caret move within the same block does not refire. fenceScan
+  // lines are 0-based; doc.line(n) is 1-based, so the line range maps with a +1 on each bound.
+  function reportComponentAtCaret(state: import('@codemirror/state').EditorState) {
+    const doc = state.doc;
+    const lines: string[] = [];
+    for (let n = 1; n <= doc.lines; n++) lines.push(doc.line(n).text);
+    const caretLine = doc.lineAt(state.selection.main.head).number - 1;
+    const range = caretContainerRange(fenceScan(lines), caretLine);
+    let next: ComponentAtCaret | null = null;
+    if (range) {
+      const fromPos = doc.line(range.fromLine + 1).from;
+      const toPos = doc.line(range.toLine + 1).to;
+      next = {
+        name: directiveOpenerName(lines[range.fromLine] ?? ''),
+        markdown: doc.sliceString(fromPos, toPos),
+        from: fromPos,
+        to: toPos,
+      };
+    }
+    const prev = lastCaretReport;
+    const same =
+      prev === next ||
+      (prev !== null &&
+        next !== null &&
+        prev.name === next.name &&
+        prev.markdown === next.markdown &&
+        prev.from === next.from &&
+        prev.to === next.to);
+    if (same) return;
+    lastCaretReport = next;
+    onComponentAtCaret?.(next);
+  }
+
+  // Overwrite a document span with new text and drop the caret after it, mirroring insertAtCursor's
+  // dispatch shape. A no-op before the editor mounts, the same guard the other seams carry.
+  function replaceRange(from: number, to: number, text: string) {
+    if (!view) return;
+    view.dispatch({ changes: { from, to, insert: text }, selection: { anchor: from + text.length } });
+    view.focus();
+  }
+
   function insertAtCursor(text: string) {
     if (!view) {
       value = value ? `${value}\n\n${text}` : text;

package/src/lib/components/markdown-directives.ts

@@ -17,6 +17,17 @@ const INLINE = /(?<![:\w]):[\w-]+\[[^\]]*\](\{[^}]*\})?/g;
 // never opens a real container.
 const CODE_FENCE = /^\s{0,3}(`{3,}|~{3,})/;
 
+/**
+ * The directive name from a container opener line (`:::callout{...}` -> `callout`,
+ * `::::cta[Book]` -> `cta`), or null when the line is not a named container opener. Reads the
+ * same FENCE match the scan uses: group 2 is the name, empty on a bare closer, so a closer or a
+ * non-fence line returns null.
+ */
+export function directiveOpenerName(line: string): string | null {
+  const m = FENCE.exec(line);
+  return m && m[2] ? m[2] : null;
+}
+
 /** Classify a whole line as a container fence, a leaf directive, or neither. */
 export function directiveLineKind(line: string): 'fence' | 'leaf' | null {
   if (FENCE.test(line)) return 'fence';

package/src/lib/render/component-grammar.ts

@@ -76,7 +76,7 @@ function isContainer(node: RootContent): node is RootContent & DirectiveNode {
 
 // 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: RootContent[]): string {
@@ -149,6 +149,48 @@ export function parseRawAttributeKeys(markdown: string, def: ComponentDef): stri
   return rawKeysFromRoot(findComponentRoot(markdown, def));
 }
 
+/** 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 async function componentRoundTripSafety(markdown: string, def: ComponentDef): Promise<RoundTripSafety> {
+  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 as DirectiveNode).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. */
@@ -178,8 +220,22 @@ function isDirectiveLabel(node: RootContent): boolean {
 
 function readLabel(root: DirectiveNode): string | undefined {
   for (const child of root.children) {
-    const p = child as { type: string; data?: { directiveLabel?: boolean }; children?: { value?: string }[] };
-    if (p.type === 'paragraph' && p.data?.directiveLabel) return (p.children ?? []).map((c) => c.value ?? '').join('');
+    const p = child as {
+      type: string;
+      data?: { directiveLabel?: boolean };
+      children?: RootContent[];
+    };
+    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 as { type: string }).type === 'text')) {
+      return kids.map((c) => (c as { value?: string }).value ?? '').join('');
+    }
+    return childrenToText(kids);
   }
   return undefined;
 }

package/src/lib/render/component-validate.ts

@@ -1,5 +1,5 @@
 import { parseComponentWithRawKeys } from './component-grammar.js';
-import type { ComponentDef } from './registry.js';
+import type { ComponentDef, ComponentValues } from './registry.js';
 
 /** A validation verdict: ok, or field-keyed error messages. */
 export type ComponentValidation = { ok: true } | { ok: false; errors: Record<string, string> };
@@ -18,6 +18,15 @@ export async function validateComponent(markdown: string, def: ComponentDef): Pr
     }
     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;
     }
   }
 
@@ -34,3 +43,15 @@ export async function validateComponent(markdown: string, def: ComponentDef): Pr
 
   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: ComponentDef, key: string, call: () => string | null): string | null {
+  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/src/lib/render/registry.ts

@@ -22,6 +22,12 @@ 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';
@@ -36,6 +42,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
@@ -75,6 +84,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 {
@@ -145,3 +166,15 @@ export function emptyValues(def: ComponentDef): ComponentValues {
   }
   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: ComponentDef): ComponentValues {
+  const base = emptyValues(def);
+  if (!def.preview) return base;
+  return {
+    attributes: { ...base.attributes, ...def.preview.attributes },
+    slots: { ...base.slots, ...def.preview.slots },
+  };
+}