@glw907/cairn-cms 0.8.0 → 0.10.0

package/src/lib/components/IconPicker.svelte

@@ -0,0 +1,51 @@
+<!--
+@component
+A visual icon choice over the site's IconSet. Each glyph is a toggle button; the selected one carries
+aria-pressed. When the field is optional, a None button clears the value. The glyph renders inline from
+the IconSet path data, matching the renderer's 256-unit viewBox.
+-->
+<script lang="ts">
+  import type { IconSet } from '../render/glyph.js';
+
+  interface Props {
+    /** The site's glyph name to SVG path-data map. */
+    icons: IconSet;
+    /** The currently selected glyph name, or '' for none. */
+    value: string;
+    /** When false, a None choice is offered. */
+    required: boolean;
+    /** Called with the new glyph name (or '' for none). */
+    onChange: (name: string) => void;
+  }
+
+  let { icons, value, required, onChange }: Props = $props();
+
+  const names = $derived(Object.keys(icons));
+</script>
+
+<div class="flex flex-wrap gap-2" role="group" aria-label="Icon">
+  {#if !required}
+    <button
+      type="button"
+      class="btn btn-sm"
+      class:btn-primary={value === ''}
+      aria-pressed={value === ''}
+      onclick={() => onChange('')}
+    >None</button>
+  {/if}
+  {#each names as name (name)}
+    <button
+      type="button"
+      class="btn btn-sm gap-1"
+      class:btn-primary={value === name}
+      aria-pressed={value === name}
+      aria-label={name}
+      onclick={() => onChange(name)}
+    >
+      <svg class="ec-glyph" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true" width="16" height="16">
+        <path d={icons[name]} />
+      </svg>
+      <span class="text-xs">{name}</span>
+    </button>
+  {/each}
+</div>

package/src/lib/components/MarkdownEditor.svelte

@@ -1,81 +1,120 @@
 <!--
 @component
-The `MarkdownEditor` seam (spec §6, seam 5): a thin wrapper over Carta exposing a bindable value
-and a cursor-insert callback. Carta and Shiki are client-only, so the editor mounts after the
-component does; until then the hidden field still carries the value so the form submits correctly.
-Swapping Carta for a bare CodeMirror editor stays a one-file change.
+The `MarkdownEditor` seam (spec §6, seam 5): a thin wrapper over CodeMirror 6 exposing a bindable
+value and a cursor-insert callback. CodeMirror is client-only, so it mounts after the component does
+through a dynamic import; until then a plain textarea carries the value so the form still submits, and
+the hidden field mirrors the value throughout. The edit surface owns its toolbar; the design-accurate
+preview lives in EditPage through the adapter's render. Swapping the editor stays a one-file change.
 -->
 <script lang="ts">
-  import { onMount } from 'svelte';
+  import { onMount, onDestroy } from 'svelte';
+  import EditorToolbar from './EditorToolbar.svelte';
+  import { applyMarkdownFormat, type FormatKind } from './markdown-format.js';
 
   interface Props {
     /** The markdown source; bindable so the parent reads edits back. */
     value: string;
     /** The hidden field name the value is mirrored to for form submit. */
     name: string;
-    /** Carta extensions from the adapter, for the design-accurate preview. */
-    plugins?: unknown[];
     /** Receives a `(text) => void` that inserts at the cursor; the palette calls it. */
     registerInsert?: (insert: (text: string) => void) => void;
   }
 
-  let { value = $bindable(), name, plugins = [], registerInsert }: Props = $props();
-
-  // Local structural type for the Carta editing surface this seam uses. carta-md re-exports its
-  // Svelte components from the package entry, so its `Carta` class is not reachable as a named
-  // export under NodeNext; a structural type stays compatible without naming it (the shape
-  // legacy/src/lib/editor.ts relied on, verified against carta-md@4.11).
-  interface CartaInput {
-    getSelection(): { start: number };
-    insertAt(position: number, text: string): void;
-    update(): boolean;
-  }
-  interface CartaLike {
-    input?: CartaInput;
-  }
+  let { value = $bindable(), name, registerInsert }: Props = $props();
 
+  let host = $state<HTMLDivElement | null>(null);
   let mounted = $state(false);
-  // Carta and the MarkdownEditor component load only in the browser, after mount, so the server
-  // bundle never pulls in Carta or Shiki (guarded by the carta-boundary test). The component keeps
-  // its real type, so `value` stays bindable; the Carta constructor is reached through a cast
-  // because the package entry does not surface the class by name.
-  let Editor = $state<(typeof import('carta-md'))['MarkdownEditor'] | null>(null);
-  let carta = $state<CartaLike | null>(null);
+  // The CodeMirror view, untyped at the runtime boundary because @codemirror/* loads only in the
+  // browser. The type-only `import(...)` annotation is erased; the value import is dynamic in onMount,
+  // so the server bundle never pulls CodeMirror (guarded by the editor-boundary test).
+  let view: import('@codemirror/view').EditorView | null = null;
 
   onMount(async () => {
-    const mod = await import('carta-md');
-    const CartaCtor = (
-      mod as unknown as { Carta: new (options: { extensions?: unknown[]; sanitizer: false }) => CartaLike }
-    ).Carta;
-    const instance = new CartaCtor({
-      extensions: plugins,
-      // Sanitization is the site adapter's concern; the seam passes raw markdown through.
-      sanitizer: false,
-    });
-    carta = instance;
-    Editor = mod.MarkdownEditor;
-    // Insert at the current cursor through carta.input once the editor is mounted; fall back to
-    // appending while input is not yet populated (the pre-mount textarea phase).
-    registerInsert?.((text: string) => {
-      const inp = instance.input;
-      if (inp) {
-        const pos = inp.getSelection().start;
-        const prefix = pos > 0 ? '\n\n' : '';
-        inp.insertAt(pos, `${prefix}${text}`);
-        inp.update();
-      } else {
-        value = value ? `${value}\n\n${text}` : text;
-      }
+    const viewMod = await import('@codemirror/view');
+    const stateMod = await import('@codemirror/state');
+    const markdownMod = await import('@codemirror/lang-markdown');
+    const commandsMod = await import('@codemirror/commands');
+    const languageMod = await import('@codemirror/language');
+
+    if (!host) return;
+
+    const { EditorView, keymap } = viewMod;
+    const theme = EditorView.theme(
+      {
+        '&': { backgroundColor: 'var(--color-base-100)', color: 'var(--color-base-content)', fontSize: '0.875rem' },
+        '.cm-content': { fontFamily: 'ui-monospace, monospace', padding: '0.75rem', lineHeight: '1.7' },
+        '.cm-cursor': { borderLeftColor: 'var(--color-primary)' },
+        '&.cm-focused': { outline: '2px solid var(--color-primary)', outlineOffset: '-2px' },
+        '.cm-line': { padding: '0' },
+      },
+      { dark: false },
+    );
+
+    view = new EditorView({
+      parent: host,
+      state: stateMod.EditorState.create({
+        doc: value,
+        extensions: [
+          commandsMod.history(),
+          keymap.of([...commandsMod.defaultKeymap, ...commandsMod.historyKeymap]),
+          markdownMod.markdown(),
+          EditorView.lineWrapping,
+          languageMod.syntaxHighlighting(languageMod.defaultHighlightStyle, { fallback: true }),
+          theme,
+          EditorView.updateListener.of((update) => {
+            if (update.docChanged) value = update.state.doc.toString();
+          }),
+        ],
+      }),
     });
+
+    registerInsert?.(insertAtCursor);
     mounted = true;
   });
+
+  onDestroy(() => view?.destroy());
+
+  // Reconcile an externally reassigned `value` into the mounted editor. A no-op until `view` exists,
+  // and the doc-equality guard ignores the updateListener's own writes so the two never feed back.
+  $effect(() => {
+    const incoming = value;
+    if (!view) return;
+    const current = view.state.doc.toString();
+    if (incoming === current) return;
+    view.dispatch({ changes: { from: 0, to: current.length, insert: incoming } });
+  });
+
+  function insertAtCursor(text: string) {
+    if (!view) {
+      value = value ? `${value}\n\n${text}` : text;
+      return;
+    }
+    const pos = view.state.selection.main.head;
+    const prefix = pos > 0 ? '\n\n' : '';
+    const insert = `${prefix}${text}`;
+    view.dispatch({ changes: { from: pos, insert }, selection: { anchor: pos + insert.length } });
+    view.focus();
+  }
+
+  function applyFormat(kind: FormatKind) {
+    if (!view) return;
+    const { from, to } = view.state.selection.main;
+    const doc = view.state.doc.toString();
+    const next = applyMarkdownFormat(doc, from, to, kind);
+    view.dispatch({
+      changes: { from: 0, to: doc.length, insert: next.doc },
+      selection: { anchor: next.from, head: next.to },
+    });
+    view.focus();
+  }
 </script>
 
-<input type="hidden" {name} value={value} />
+<input type="hidden" {name} {value} />
 
-{#if mounted && Editor && carta}
-  {@const EditorComponent = Editor}
-  <EditorComponent carta={carta as never} bind:value theme="default" mode="tabs" />
-{:else}
-  <textarea class="textarea min-h-64 w-full font-mono text-sm" bind:value aria-label="Markdown source"></textarea>
-{/if}
+<div class="border-base-300 overflow-hidden rounded-box border">
+  <EditorToolbar format={applyFormat} />
+  <div bind:this={host}></div>
+  {#if !mounted}
+    <textarea class="textarea min-h-64 w-full font-mono text-sm" bind:value aria-label="Markdown source"></textarea>
+  {/if}
+</div>

package/src/lib/components/index.ts

@@ -7,5 +7,7 @@ export { default as ConceptList } from './ConceptList.svelte';
 export { default as EditPage } from './EditPage.svelte';
 export { default as ManageEditors } from './ManageEditors.svelte';
 export { default as MarkdownEditor } from './MarkdownEditor.svelte';
-export { default as ComponentPalette } from './ComponentPalette.svelte';
+export { default as ComponentInsertDialog } from './ComponentInsertDialog.svelte';
+export { default as ComponentForm } from './ComponentForm.svelte';
+export { default as IconPicker } from './IconPicker.svelte';
 export { default as NavTree } from './NavTree.svelte';

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

@@ -0,0 +1,39 @@
+/**
+ * Pure markdown selection transforms for the editor toolbar. Each call maps a document and a
+ * selection range to a new document and a new selection, with no DOM. The MarkdownEditor view
+ * dispatches the result; keeping the logic here lets it unit-test without a browser.
+ */
+export type FormatKind = 'bold' | 'italic' | 'code' | 'heading' | 'quote' | 'ul' | 'link';
+
+export interface FormatResult {
+  doc: string;
+  from: number;
+  to: number;
+}
+
+const WRAP: Record<'bold' | 'italic' | 'code', string> = { bold: '**', italic: '_', code: '`' };
+const LINE_PREFIX: Record<'heading' | 'quote' | 'ul', string> = { heading: '# ', quote: '> ', ul: '- ' };
+
+export function applyMarkdownFormat(doc: string, from: number, to: number, kind: FormatKind): FormatResult {
+  if (kind === 'bold' || kind === 'italic' || kind === 'code') {
+    const marker = WRAP[kind];
+    const next = doc.slice(0, from) + marker + doc.slice(from, to) + marker + doc.slice(to);
+    return { doc: next, from: from + marker.length, to: to + marker.length };
+  }
+
+  if (kind === 'link') {
+    const text = doc.slice(from, to);
+    const placeholder = 'url';
+    const lead = `[${text}](`; // everything before the url placeholder
+    const inserted = `${lead}${placeholder})`;
+    const urlStart = from + lead.length;
+    return { doc: doc.slice(0, from) + inserted + doc.slice(to), from: urlStart, to: urlStart + placeholder.length };
+  }
+
+  const prefix = LINE_PREFIX[kind];
+  const lineStart = doc.lastIndexOf('\n', from - 1) + 1; // 0 when the selection is on the first line
+  const region = doc.slice(lineStart, to);
+  const prefixed = region.replace(/^/gm, prefix);
+  const added = prefixed.length - region.length;
+  return { doc: doc.slice(0, lineStart) + prefixed + doc.slice(to), from: from + prefix.length, to: to + added };
+}

package/src/lib/content/compose.ts

@@ -32,6 +32,7 @@ export function composeRuntime(
     sender: adapter.sender,
     render: adapter.render,
     registry: adapter.registry,
+    icons: adapter.icons,
     navMenu: adapter.navMenu,
     assets: adapter.assets,
     adminPanels,

package/src/lib/content/types.ts

@@ -8,6 +8,7 @@
 // descriptors are plain data so a `load` function can hand them across the server-to-client
 // boundary to the editor form.
 import type { ComponentRegistry } from '../render/registry.js';
+import type { IconSet } from '../render/glyph.js';
 import type { DatePrefix } from './ids.js';
 
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
@@ -151,6 +152,8 @@ export interface CairnAdapter {
   render(md: string, opts?: { stagger?: boolean }): string | Promise<string>;
   /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
   registry?: ComponentRegistry;
+  /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
+  icons?: IconSet;
   navMenu?: NavMenuConfig;
   assets?: AssetConfig;
 }
@@ -243,6 +246,8 @@ export interface CairnRuntime {
   /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
   render(md: string, opts?: { stagger?: boolean }): string | Promise<string>;
   registry?: ComponentRegistry;
+  /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
+  icons?: IconSet;
   navMenu?: NavMenuConfig;
   assets?: AssetConfig;
   /** Admin panels contributed by extensions (Mode 2). Empty until Plan 09 wires the dispatch route. */

package/src/lib/index.ts

@@ -48,8 +48,22 @@ export {
 } from './content/ids.js';
 export type { DatePrefix } from './content/ids.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
-export { defineRegistry } from './render/registry.js';
-export type { ComponentDef, ComponentRegistry } from './render/registry.js';
+export { defineRegistry, emptyValues } from './render/registry.js';
+export type {
+  ComponentDef,
+  ComponentRegistry,
+  FieldType,
+  AttributeField,
+  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';
+export { buildComponentInsert, type ComponentInsert } from './render/component-insert.js';
+export { generateComponentReference } from './render/component-reference.js';
+export type { ReferenceOptions } from './render/component-reference.js';
 export { glyph } from './render/glyph.js';
 export type { IconSet } from './render/glyph.js';
 export { remarkDirectiveStamp } from './render/remark-directives.js';

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

@@ -0,0 +1,167 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkDirective from 'remark-directive';
+import remarkStringify from 'remark-stringify';
+import type { Root, RootContent } from 'mdast';
+import type { ComponentDef, ComponentValues, SlotDef } from './registry.js';
+
+const COLON = ':';
+
+function attrBlock(def: ComponentDef, values: ComponentValues): string {
+  const parts: string[] = [];
+  for (const field of def.attributes ?? []) {
+    const v = values.attributes[field.key];
+    if (field.type === 'boolean') {
+      if (v === true) parts.push(`${field.key}="true"`);
+    } else if (typeof v === 'string' && v !== '') {
+      // The directive attribute grammar (mdast-util-directive) treats a literal `"` as the value
+      // terminator and decodes HTML entities, so a backslash escape does not survive a round-trip.
+      // 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}"`);
+    }
+  }
+  return parts.length ? `{${parts.join(' ')}}` : '';
+}
+
+function slotByName(def: ComponentDef, name: string): SlotDef | undefined {
+  return (def.slots ?? []).find((s) => s.name === name);
+}
+
+function nestedSlots(def: ComponentDef): SlotDef[] {
+  return (def.slots ?? []).filter((s) => s.name !== 'title' && s.name !== 'body');
+}
+
+export function serializeComponent(def: ComponentDef, values: ComponentValues): string {
+  const fence = COLON.repeat(nestedSlots(def).length > 0 ? 4 : 3);
+
+  const title = slotByName(def, 'title') ? (values.slots.title as string) ?? '' : '';
+  // Escape brackets in the label so a `[` or `]` in the title does not break the directive label
+  // grammar; remark un-escapes them back to literal text on parse, so readLabel recovers them.
+  const label = title ? `[${title.replace(/\[/g, '\\[').replace(/\]/g, '\\]')}]` : '';
+
+  const open = `${fence}${def.name}${label}${attrBlock(def, values)}`;
+
+  const lines: string[] = [open];
+  const body = slotByName(def, 'body') ? (values.slots.body as string) ?? '' : '';
+  if (body) lines.push(body);
+
+  for (const slot of nestedSlots(def)) {
+    const raw = values.slots[slot.name];
+    const content =
+      slot.kind === 'repeatable'
+        ? (Array.isArray(raw) ? raw : []).filter((i) => i !== '').map((i) => `- ${i}`).join('\n')
+        : ((raw as string | undefined) ?? '');
+    if (!content) continue;
+    if (lines.length > 1) lines.push(''); // blank line before this block
+    lines.push(`${COLON.repeat(3)}${slot.name}`, content, COLON.repeat(3));
+  }
+
+  lines.push(fence);
+  return lines.join('\n');
+}
+
+// A minimal structural view of a mdast containerDirective node (mdast-util-directive shape).
+interface DirectiveNode {
+  type: 'containerDirective' | 'leafDirective' | 'textDirective';
+  name: string;
+  attributes?: Record<string, string | null> | null;
+  children: RootContent[];
+}
+
+function isContainer(node: RootContent): node is RootContent & DirectiveNode {
+  return (node as DirectiveNode).type === 'containerDirective';
+}
+
+// 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: '-' });
+
+/** Render mdast children back to trimmed markdown text. */
+function childrenToText(children: RootContent[]): string {
+  const root: Root = { type: 'root', children };
+  return String(toMd.stringify(root)).trim();
+}
+
+/** Parse a serialized component directive back into guided-form values, the inverse of
+ *  {@link serializeComponent}. The grammar is reversible, so the editor can round-trip a
+ *  saved directive through the form. */
+export async function parseComponent(markdown: string, def: ComponentDef): Promise<ComponentValues> {
+  const tree = unified().use(remarkParse).use(remarkDirective).parse(markdown) as Root;
+  const root = tree.children.find(
+    (c): c is RootContent & DirectiveNode => isContainer(c) && (c as DirectiveNode).name === def.name,
+  );
+  const values = emptyComponentValues(def);
+  if (!root) return values;
+
+  for (const field of def.attributes ?? []) {
+    const raw = root.attributes?.[field.key];
+    if (field.type === 'boolean') values.attributes[field.key] = raw === 'true';
+    else if (typeof raw === 'string') values.attributes[field.key] = raw;
+  }
+
+  const titleSlot = slotByName(def, 'title');
+  const bodySlot = slotByName(def, 'body');
+  const nested = nestedSlots(def);
+  const nestedNames = new Set(nested.map((s) => s.name));
+
+  const directChildren = root.children.filter(
+    (c) => !(isContainer(c) && nestedNames.has((c as DirectiveNode).name)) && !isDirectiveLabel(c),
+  );
+  const nestedChildren = root.children.filter(
+    (c): c is RootContent & DirectiveNode => isContainer(c) && nestedNames.has((c as DirectiveNode).name),
+  );
+
+  if (titleSlot) values.slots.title = readLabel(root) ?? '';
+  if (bodySlot) values.slots.body = childrenToText(directChildren);
+
+  for (const slot of nested) {
+    const node = nestedChildren.find((c) => c.name === slot.name);
+    if (!node) continue;
+    if (slot.kind === 'repeatable') values.slots[slot.name] = readListItems(node.children);
+    else values.slots[slot.name] = childrenToText(node.children);
+  }
+
+  return values;
+}
+
+/** 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 function parseRawAttributeKeys(markdown: string, def: ComponentDef): string[] {
+  const tree = unified().use(remarkParse).use(remarkDirective).parse(markdown) as Root;
+  const root = tree.children.find(
+    (c): c is RootContent & DirectiveNode => isContainer(c) && (c as DirectiveNode).name === def.name,
+  );
+  return Object.keys(root?.attributes ?? {});
+}
+
+// A bare parse base: empty strings, false, and empty lists, with no attribute defaults applied. The
+// `emptyValues` helper in registry.ts seeds form defaults instead, so it is deliberately not reused
+// here; the parse must overwrite only the fields actually present in the markdown.
+function emptyComponentValues(def: ComponentDef): ComponentValues {
+  const attributes: Record<string, string | boolean> = {};
+  for (const f of def.attributes ?? []) attributes[f.key] = f.type === 'boolean' ? false : '';
+  const slots: Record<string, string | string[]> = {};
+  for (const s of def.slots ?? []) slots[s.name] = s.kind === 'repeatable' ? [] : '';
+  return { attributes, slots };
+}
+
+// mdast-util-directive carries the `[label]` as a paragraph whose `data.directiveLabel` is set.
+function isDirectiveLabel(node: RootContent): boolean {
+  return Boolean((node as { data?: { directiveLabel?: boolean } }).data?.directiveLabel);
+}
+
+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('');
+  }
+  return undefined;
+}
+
+function readListItems(children: RootContent[]): string[] {
+  const list = children.find((c) => (c as { type: string }).type === 'list') as { children?: RootContent[] } | undefined;
+  if (!list?.children) return [];
+  return list.children.map((li) => childrenToText((li as { children?: RootContent[] }).children ?? []));
+}

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

@@ -0,0 +1,15 @@
+import { serializeComponent } from './component-grammar.js';
+import { validateComponent } from './component-validate.js';
+import type { ComponentDef, ComponentValues } from './registry.js';
+
+/** The outcome of preparing a guided-form component for insertion: the markdown to insert, or the
+ *  field-keyed errors to show on the form. */
+export type ComponentInsert = { ok: true; markdown: string } | { ok: false; errors: Record<string, string> };
+
+/** Serialize a component's form values, then validate the result against its schema. Returns the
+ *  markdown to insert at the cursor, or the field errors keyed by attribute key or slot name. */
+export async function buildComponentInsert(def: ComponentDef, values: ComponentValues): Promise<ComponentInsert> {
+  const markdown = serializeComponent(def, values);
+  const verdict = await validateComponent(markdown, def);
+  return verdict.ok ? { ok: true, markdown } : { ok: false, errors: verdict.errors };
+}

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

@@ -0,0 +1,38 @@
+import { serializeComponent } from './component-grammar.js';
+import { emptyValues, type ComponentDef, type ComponentRegistry, type ComponentValues } from './registry.js';
+
+export interface ReferenceOptions {
+  /** The H1 title of the reference document. */
+  title: string;
+  /** The one-line blockquote summary under the title. */
+  summary: string;
+}
+
+/** Build a self-contained markdown reference (the llms-full.txt shape) for a component registry, for
+ *  authors and for pointing an LLM at one curated file. */
+export function generateComponentReference(registry: ComponentRegistry, opts: ReferenceOptions): string {
+  const sections = registry.defs.map((def) => componentSection(def));
+  return `# ${opts.title}\n\n> ${opts.summary}\n\n${sections.join('\n\n')}\n`;
+}
+
+function componentSection(def: ComponentDef): string {
+  const lines = [`## ${def.label} (\`:::${def.name}\`)`, '', def.description ?? ''];
+  if (def.use) lines.push('', `**When to use:** ${def.use}`);
+  lines.push('', '```', serializeComponent(def, exampleValues(def)), '```');
+  return lines.join('\n');
+}
+
+/** Seed example values that show every declared field: an ellipsis for strings, one sample list item. */
+function exampleValues(def: ComponentDef): ComponentValues {
+  const values = emptyValues(def);
+  for (const field of def.attributes ?? []) {
+    if (field.type === 'boolean') values.attributes[field.key] = false;
+    else values.attributes[field.key] = field.options?.[0] ?? '…';
+  }
+  for (const slot of def.slots ?? []) {
+    if (slot.kind === 'repeatable') values.slots[slot.name] = ['…'];
+    else if (slot.name === 'title') values.slots[slot.name] = 'Title';
+    else values.slots[slot.name] = '…';
+  }
+  return values;
+}

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

@@ -0,0 +1,36 @@
+import { parseComponent, parseRawAttributeKeys } from './component-grammar.js';
+import type { ComponentDef } from './registry.js';
+
+/** A validation verdict: ok, or field-keyed error messages. */
+export type ComponentValidation = { ok: true } | { ok: false; errors: Record<string, string> };
+
+export async function validateComponent(markdown: string, def: ComponentDef): Promise<ComponentValidation> {
+  const values = await parseComponent(markdown, def);
+  const errors: Record<string, string> = {};
+  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(', ')}.`;
+    }
+  }
+
+  for (const key of parseRawAttributeKeys(markdown, def)) {
+    if (!declared.has(key)) errors[key] = `Unknown attribute "${key}".`;
+  }
+
+  for (const slot of def.slots ?? []) {
+    if (!slot.required) continue;
+    const v = values.slots[slot.name];
+    const filled = Array.isArray(v) ? v.length > 0 : typeof v === 'string' && v !== '';
+    if (!filled) errors[slot.name] = `${slot.label} is required.`;
+  }
+
+  return Object.keys(errors).length ? { ok: false, errors } : { ok: true };
+}

package/src/lib/render/pipeline.ts

@@ -19,7 +19,7 @@ export interface RendererOptions {
 
 /** 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 Carta editor preview can reuse the exact same set). */
+ *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
 export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
   const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
   const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.stagger], rehypeSlug];