@glw907/cairn-cms 0.5.0 → 0.6.0-rc.0

package/src/lib/components/NavTree.svelte

@@ -0,0 +1,138 @@
+<!--
+@component
+The navigation tree editor. It edits a flat working copy of the menu (each row carries an
+explicit depth) and posts the whole tree as JSON to the save action. Vertical order comes from
+svelte-sortable-list (mouse, and keyboard with Space to lift, arrows to move, Space to drop);
+depth comes from the Indent and Outdent buttons, capped at the menu's maxDepth. The engine
+validates on save.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { SortableList, sortItems } from '@rodrigodagostino/svelte-sortable-list';
+  import type { SortableList as SortableListNS } from '@rodrigodagostino/svelte-sortable-list';
+  import '@rodrigodagostino/svelte-sortable-list/styles.css';
+  import type { NavLoadData } from '../sveltekit/nav-routes.js';
+  import type { NavNode } from '../nav/site-config.js';
+
+  interface Props {
+    /** The nav load's data: the menu meta, the current tree, page options, and flags. */
+    data: NavLoadData;
+  }
+
+  let { data }: Props = $props();
+
+  // A flat, ordered working model is simpler to reorder than a recursive one: each row carries an
+  // explicit depth, and the nested tree is rebuilt from order plus depth only at submit time.
+  interface Row {
+    id: string;
+    depth: number;
+    label: string;
+    url: string;
+  }
+
+  let nextId = 1;
+  function flatten(nodes: NavNode[], depth: number, out: Row[]): Row[] {
+    for (const n of nodes) {
+      out.push({ id: `row-${nextId++}`, depth, label: n.label, url: n.url ?? '' });
+      if (n.children?.length) flatten(n.children, depth + 1, out);
+    }
+    return out;
+  }
+
+  // untrack here is not for runtime behavior -- $state runs its initializer once regardless.
+  // It suppresses the Svelte compiler warning that `data` (a prop) is referenced outside a
+  // reactive context. The component is always remounted on save/error (both redirect), so
+  // a one-time snapshot of the initial tree is correct.
+  let rows = $state<Row[]>(untrack(() => flatten(data.tree, 0, [])));
+  // depth is 0-based internally; maxDepth in the config is 1-based (1 = flat, 2 = one nesting level)
+  const maxDepthIndex = $derived(data.menu.maxDepth - 1);
+
+  // Rebuild the nested tree from the flat rows by depth, then serialize for the hidden field.
+  function toTree(list: Row[]): NavNode[] {
+    const root: NavNode[] = [];
+    const stack: { depth: number; node: NavNode }[] = [];
+    for (const r of list) {
+      const node: NavNode = { label: r.label.trim() };
+      if (r.url.trim()) node.url = r.url.trim();
+      while (stack.length && stack[stack.length - 1].depth >= r.depth) stack.pop();
+      if (stack.length) (stack[stack.length - 1].node.children ??= []).push(node);
+      else root.push(node);
+      stack.push({ depth: r.depth, node });
+    }
+    return root;
+  }
+
+  const treeJson = $derived(JSON.stringify(toTree(rows)));
+
+  function addRow() {
+    rows = [...rows, { id: `row-${nextId++}`, depth: 0, label: 'New item', url: '' }];
+  }
+  function removeRow(id: string) {
+    rows = rows.filter((r) => r.id !== id);
+  }
+  function indent(i: number) {
+    // A row may nest at most one level deeper than the row above it, and never past the cap.
+    if (i === 0) return;
+    const ceiling = Math.min(rows[i - 1].depth + 1, maxDepthIndex);
+    if (rows[i].depth < ceiling) rows[i].depth += 1;
+  }
+  function outdent(i: number) {
+    if (rows[i].depth > 0) rows[i].depth -= 1;
+  }
+
+  function handleDragEnd(e: SortableListNS.RootEvents['ondragend']) {
+    const { draggedItemIndex, targetItemIndex, isCanceled } = e;
+    if (!isCanceled && typeof targetItemIndex === 'number' && draggedItemIndex !== targetItemIndex) {
+      rows = sortItems(rows, draggedItemIndex, targetItemIndex);
+    }
+  }
+</script>
+
+<h1 class="mb-4 text-xl font-semibold">{data.menu.label}</h1>
+
+{#if data.saved}
+  <div role="status" class="alert alert-success mb-4 text-sm">Navigation saved.</div>
+{/if}
+{#if data.error}
+  <div role="alert" class="alert alert-error mb-4 text-sm">{data.error}</div>
+{/if}
+
+<form method="POST" action="?/save">
+  <input type="hidden" name="tree" value={treeJson} />
+
+  <div class="mb-2">
+    <button type="button" class="btn btn-sm" onclick={addRow}>Add item</button>
+  </div>
+
+  <div class="sortable-list-area" style="min-height:2.5rem">
+    <SortableList.Root ondragend={handleDragEnd} aria-label="Navigation items">
+      {#each rows as row, index (row.id)}
+        <SortableList.Item id={row.id} {index} aria-label={`${row.label || 'Untitled'}, level ${row.depth + 1}`}>
+          <div class="flex items-center gap-2 p-2" style={`margin-left:${row.depth * 1.5}rem`}>
+            <input class="input input-sm flex-1" placeholder="Label" aria-label="Label" bind:value={row.label} />
+            <input
+              class="input input-sm flex-1"
+              placeholder="/path or https://example.com"
+              list="cairn-nav-pages"
+              aria-label="URL"
+              bind:value={row.url}
+            />
+            <button type="button" class="btn btn-xs btn-ghost" onclick={() => outdent(index)} aria-label="Outdent">&larr;</button>
+            <button type="button" class="btn btn-xs btn-ghost" onclick={() => indent(index)} aria-label="Indent">&rarr;</button>
+            <button type="button" class="btn btn-xs btn-ghost text-error" onclick={() => removeRow(row.id)} aria-label={`Remove ${row.label}`}>&times;</button>
+          </div>
+        </SortableList.Item>
+      {/each}
+    </SortableList.Root>
+  </div>
+
+  <datalist id="cairn-nav-pages">
+    {#each data.pages as p (p.url)}
+      <option value={p.url}>{p.label}</option>
+    {/each}
+  </datalist>
+
+  <div class="mt-4">
+    <button type="submit" class="btn btn-primary btn-sm">Save navigation</button>
+  </div>
+</form>

package/src/lib/components/cairn-admin.css

@@ -0,0 +1,42 @@
+/* Warm Stone: the cairn admin theme. Self-contained, since DaisyUI v5 reads these vars at point
+   of use, so this fully overrides the host's theme with no @plugin and no host build step. */
+[data-theme='cairn-admin'] {
+  color-scheme: light;
+  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+
+  --color-base-100: oklch(98.5% 0.004 75);
+  --color-base-200: oklch(96% 0.005 75);
+  --color-base-300: oklch(92% 0.008 75);
+  --color-base-content: oklch(28% 0.012 75);
+
+  --color-primary: oklch(52% 0.2 293);
+  --color-primary-content: oklch(98% 0.012 293);
+  --color-secondary: oklch(45% 0.02 75);
+  --color-secondary-content: oklch(98% 0.004 75);
+  --color-accent: oklch(58% 0.16 300);
+  --color-accent-content: oklch(98% 0.012 300);
+  --color-neutral: oklch(32% 0.012 75);
+  --color-neutral-content: oklch(96% 0.004 75);
+
+  --color-info: oklch(60% 0.12 240);
+  --color-info-content: oklch(98% 0.012 240);
+  --color-success: oklch(58% 0.12 150);
+  --color-success-content: oklch(98% 0.012 150);
+  --color-warning: oklch(75% 0.15 70);
+  --color-warning-content: oklch(26% 0.05 70);
+  --color-error: oklch(58% 0.2 25);
+  --color-error-content: oklch(98% 0.012 25);
+
+  /* Accessible muted text tones: >= 4.5:1 contrast on base-100/base-200. */
+  --color-muted: oklch(48% 0.01 75);
+  --color-subtle: oklch(42% 0.01 75);
+
+  --radius-selector: 0.5rem;
+  --radius-field: 0.5rem;
+  --radius-box: 0.75rem;
+  --size-selector: 0.25rem;
+  --size-field: 0.25rem;
+  --border: 1px;
+  --depth: 1;
+  --noise: 0;
+}

package/src/lib/components/index.ts

@@ -1,8 +1,11 @@
-// cairn-cms admin UI shell. Consumers import from 'cairn-cms/components'; each site's
-// admin route `.svelte` files are one-line shims around these.
+// Admin Svelte components (Plan 05). The Warm Stone theme ships as a CSS side effect imported
+// by the components that set `data-theme="cairn-admin"`.
 export { default as AdminLayout } from './AdminLayout.svelte';
-export { default as AdminList } from './AdminList.svelte';
 export { default as LoginPage } from './LoginPage.svelte';
 export { default as ConfirmPage } from './ConfirmPage.svelte';
+export { default as ConceptList } from './ConceptList.svelte';
 export { default as EditPage } from './EditPage.svelte';
-export { default as ManageAdmins } from './ManageAdmins.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 NavTree } from './NavTree.svelte';

package/src/lib/content/compose.ts

@@ -0,0 +1,39 @@
+// cairn-cms: composition aggregation (seam 2). One place folds the adapter and any
+// extensions into the runtime the engine serves from. A future `CairnExtension` folds in
+// the same way and contributes the same kinds of things: nav entries, route logic,
+// concepts, components, field types, and save hooks. Shaped now so the extension contract
+// is additive later.
+import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, FieldTypeDef } from './types.js';
+import { normalizeConcepts } from './concepts.js';
+
+/**
+ * Fold an adapter and any extensions into the composed runtime (seam 2). Extension concepts
+ * merge after the adapter's. The asset slot (seam 4) passes through untouched.
+ */
+export function composeRuntime(
+  adapter: CairnAdapter,
+  extensions: CairnExtension[] = [],
+): CairnRuntime {
+  const content: Record<string, ConceptConfig | undefined> = { ...adapter.content };
+  const adminPanels: AdminPanel[] = [];
+  const fieldTypes: FieldTypeDef[] = [];
+  for (const extension of extensions) {
+    // An extension adds concepts; a key that collides with the adapter is last-write-wins.
+    // Reserved seam, unused today, so the collision policy is deliberately left simple.
+    if (extension.content) Object.assign(content, extension.content);
+    if (extension.adminPanels) adminPanels.push(...extension.adminPanels);
+    if (extension.fieldTypes) fieldTypes.push(...extension.fieldTypes);
+  }
+  return {
+    siteName: adapter.siteName,
+    concepts: normalizeConcepts(content),
+    backend: adapter.backend,
+    sender: adapter.sender,
+    renderPreview: adapter.renderPreview,
+    registry: adapter.registry,
+    navMenu: adapter.navMenu,
+    assets: adapter.assets,
+    adminPanels,
+    fieldTypes,
+  };
+}

package/src/lib/content/concepts.ts

@@ -0,0 +1,57 @@
+// cairn-cms: concept normalization (seam 1). The adapter declares concepts as
+// `content: { posts?, pages? }`; this turns each declared key into a uniform descriptor
+// (id, label, directory, concept-fixed routing, fields, validator) the admin reads. A
+// future Fragments concept attaches by adding one key under `content` and one routing
+// entry, with no reshape here.
+import type { ConceptConfig, ConceptDescriptor, RoutingRule } from './types.js';
+
+/**
+ * Concept-fixed routing, keyed by concept id (spec §7.2). Posts are dated feed entries;
+ * pages are plain navigable structure. Not in adapter config. A future Fragments adds one
+ * entry here and one key under `content`.
+ */
+export const CONCEPT_ROUTING: Readonly<Record<string, RoutingRule>> = {
+  posts: { routable: true, dated: true, inFeeds: true },
+  pages: { routable: true, dated: false, inFeeds: false },
+};
+
+/** Routing for a concept with no table entry: a plain, non-feed, routable page. */
+const DEFAULT_ROUTING: RoutingRule = { routable: true, dated: false, inFeeds: false };
+
+/** Title-case a concept id for the default sidebar label, e.g. "posts" to "Posts". */
+function defaultLabel(id: string): string {
+  return id.charAt(0).toUpperCase() + id.slice(1);
+}
+
+/**
+ * Normalize an adapter's declared concepts into uniform descriptors (seam 1). Each declared
+ * key under `content` becomes one descriptor; an undeclared (`undefined`) concept is
+ * skipped. `routing` is injectable so a contract test can prove a new concept attaches
+ * additively; production passes the default `CONCEPT_ROUTING`.
+ */
+export function normalizeConcepts(
+  content: Record<string, ConceptConfig | undefined>,
+  routing: Readonly<Record<string, RoutingRule>> = CONCEPT_ROUTING,
+): ConceptDescriptor[] {
+  const descriptors: ConceptDescriptor[] = [];
+  for (const [id, config] of Object.entries(content)) {
+    if (!config) continue;
+    descriptors.push({
+      id,
+      label: config.label ?? defaultLabel(id),
+      dir: config.dir,
+      routing: routing[id] ?? DEFAULT_ROUTING,
+      fields: config.fields,
+      validate: config.validate,
+    });
+  }
+  return descriptors;
+}
+
+/** Look up a normalized concept by id, or undefined when the site does not enable it. */
+export function findConcept(
+  concepts: ConceptDescriptor[],
+  id: string,
+): ConceptDescriptor | undefined {
+  return concepts.find((concept) => concept.id === id);
+}

package/src/lib/content/frontmatter.ts

@@ -0,0 +1,71 @@
+// cairn-cms: frontmatter form decoding and on-disk serialization. `frontmatterFromForm`
+// is the form-to-data half of the edit loop; `serializeMarkdown`/`parseMarkdown` are the
+// on-disk write/read pair. Kept as one seam so a site owns its serialization contract
+// (quoting, key order) without the save endpoint reaching for gray-matter directly.
+import matter from 'gray-matter';
+import type { FrontmatterField } from './types.js';
+
+/** Decode submitted form data into raw frontmatter, one rule per field type. */
+export function frontmatterFromForm(
+  fields: FrontmatterField[],
+  form: FormData,
+): Record<string, unknown> {
+  const data: Record<string, unknown> = {};
+  for (const field of fields) {
+    switch (field.type) {
+      case 'boolean':
+        data[field.name] = form.get(field.name) === 'on';
+        break;
+      case 'tags':
+        data[field.name] = form.getAll(field.name).map(String);
+        break;
+      case 'freetags':
+        // One comma-separated input to trimmed, de-duplicated, non-empty tags.
+        data[field.name] = [
+          ...new Set(
+            String(form.get(field.name) ?? '')
+              .split(',')
+              .map((tag) => tag.trim())
+              .filter(Boolean),
+          ),
+        ];
+        break;
+      default:
+        // FormData.get returns null for an absent field; normalize to an empty string so
+        // a caller reading a text value never gets null.
+        data[field.name] = form.get(field.name) ?? '';
+    }
+  }
+  return data;
+}
+
+/**
+ * Coerce a frontmatter date value to the `YYYY-MM-DD` an `<input type="date">` wants.
+ * gray-matter parses an unquoted YAML date into a JS Date, so a string-only read would
+ * leave the input empty and drop the date on save. A parsed YAML date is UTC midnight, so
+ * slicing the ISO string avoids a local-timezone shift.
+ */
+export function dateInputValue(value: unknown): string {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? '' : value.toISOString().slice(0, 10);
+  }
+  if (typeof value === 'string') {
+    const match = value.match(/^\d{4}-\d{2}-\d{2}/);
+    return match ? match[0] : '';
+  }
+  return '';
+}
+
+/** Reassemble a markdown file from frontmatter and body for committing. */
+export function serializeMarkdown(frontmatter: object, body: string): string {
+  return matter.stringify(body, frontmatter);
+}
+
+/** Parse a markdown file into its frontmatter and body: the read-side inverse of serialize. */
+export function parseMarkdown(source: string): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+} {
+  const parsed = matter(source);
+  return { frontmatter: parsed.data, body: parsed.content };
+}

package/src/lib/content/ids.ts

@@ -0,0 +1,38 @@
+// cairn-cms: filename-based content ids (spec §7.2). An entry's id is its markdown filename
+// without `.md`, so there is no slug codec. `slugify` derives a filename-safe stem from a
+// title for the create-entry form.
+
+/** Lowercase alphanumerics with single internal hyphens: the on-disk filename stem rule. */
+const ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** True when `id` is a valid filename stem: lowercase, no slashes, no leading or trailing hyphen. */
+export function isValidId(id: string): boolean {
+  return ID_RE.test(id);
+}
+
+/**
+ * A content entry's id from its filename: the basename without the `.md` suffix. Pass a
+ * basename, not a path; the caller strips any directory prefix first (Plan 03's Git Trees
+ * listing yields basenames directly).
+ */
+export function idFromFilename(filename: string): string {
+  return filename.replace(/\.md$/, '');
+}
+
+/** The on-disk filename for an id: the id plus `.md`. */
+export function filenameFromId(id: string): string {
+  return `${id}.md`;
+}
+
+/**
+ * Lowercase a title into a filename-safe slug stem. Apostrophes are dropped so "Geoff's"
+ * becomes "geoffs" (no spurious hyphen). All other non-alphanumeric runs collapse to a
+ * single hyphen; leading and trailing hyphens are trimmed.
+ */
+export function slugify(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/'/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}

package/src/lib/content/types.ts

@@ -0,0 +1,235 @@
+// cairn-cms: the adapter contract a site implements, and the engine-internal descriptors
+// the contract normalizes into.
+//
+// The adapter is the single seam the engine consumes (spec §8). A site supplies a
+// `CairnAdapter` at `src/lib/cairn.config.ts` declaring its backend repo, the content
+// concepts it enables, its magic-link sender, and a design-accurate `renderPreview`. The
+// engine never hard-codes a concept, directory, or field; it reads them here. Field
+// 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';
+
+/** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
+interface FieldBase {
+  /** Frontmatter key and form input name. */
+  name: string;
+  /** Form label. */
+  label: string;
+  /** A required field fails validation when empty (spec §7.4). */
+  required?: boolean;
+}
+
+/** A single-line text input. */
+export interface TextField extends FieldBase {
+  type: 'text';
+}
+/** A multi-line text input. */
+export interface TextareaField extends FieldBase {
+  type: 'textarea';
+  /** Visible rows; the editor picks a default when omitted. */
+  rows?: number;
+}
+/** A `YYYY-MM-DD` date input. */
+export interface DateField extends FieldBase {
+  type: 'date';
+}
+/** A checkbox; absent means false. */
+export interface BooleanField extends FieldBase {
+  type: 'boolean';
+}
+/** A closed-vocabulary tag set, rendered as checkboxes (ecnordic). */
+export interface TagsField extends FieldBase {
+  type: 'tags';
+  /** The controlled vocabulary. */
+  options: readonly string[];
+}
+/** Free-form tags, edited as one comma-separated input (907). */
+export interface FreeTagsField extends FieldBase {
+  type: 'freetags';
+  placeholder?: string;
+}
+
+/**
+ * The discriminated union the per-concept frontmatter form is generated from. Adding a
+ * field type is one variant here plus one decode arm in `frontmatterFromForm` and one in
+ * `validateFields`.
+ */
+export type FrontmatterField =
+  | TextField
+  | TextareaField
+  | DateField
+  | BooleanField
+  | TagsField
+  | FreeTagsField;
+
+/**
+ * A validator's verdict. On success it carries the normalized frontmatter to commit; on
+ * failure it carries field-keyed error messages (the empty key is a form-level error).
+ * Invalid input bounces to the form and never reaches git (spec §7.4).
+ */
+export type ValidationResult =
+  | { ok: true; data: Record<string, unknown> }
+  | { ok: false; errors: Record<string, string> };
+
+/**
+ * Per-site configuration for one content concept (spec §8). Concept-fixed behavior such as
+ * routability is not here; it lives in the engine's routing table (`CONCEPT_ROUTING`).
+ */
+export interface ConceptConfig {
+  /** Repo-relative content directory, e.g. "src/content/posts". */
+  dir: string;
+  /** Sidebar label; defaults from the concept id when omitted. */
+  label?: string;
+  /** Drives the per-concept frontmatter form, in order. */
+  fields: FrontmatterField[];
+  /** Validate submitted frontmatter before any commit. */
+  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+}
+
+/** The GitHub App backend a site reads from and commits to (spec §8). Plain data the GitHub engine (Plan 03) consumes. */
+export interface BackendConfig {
+  owner: string;
+  repo: string;
+  /** Commit target, e.g. "main". */
+  branch: string;
+  appId: string;
+  installationId: string;
+}
+
+/** Magic-link sender identity for Cloudflare Email Sending. */
+export interface SenderConfig {
+  from: string;
+  replyTo?: string;
+}
+
+/** A git-committed YAML menu this site's nav editor manages (Plan 06). */
+export interface NavMenuConfig {
+  /** Repo-relative path to the site-config YAML, e.g. "src/lib/site.config.yaml". */
+  configPath: string;
+  /** Key within the file's menus map, e.g. "primary". */
+  menuName: string;
+  /** Sidebar label for the menu. */
+  label: string;
+  /** Max nesting depth allowed in the editor; defaults to 2. */
+  maxDepth?: number;
+}
+
+/** Reserved asset slot (seam 4). Typed and unused in the rebuild; R7/R9 read it later with no contract change. */
+export interface AssetConfig {
+  /** Repo-relative asset roots, e.g. ["static/images"]. */
+  roots: string[];
+  /** Public URL base, e.g. "/images". */
+  publicBase: string;
+}
+
+/** The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`. */
+export interface CairnAdapter {
+  siteName: string;
+  /**
+   * Which content concepts this site enables. A future `fragments?` key attaches here with
+   * no reshape of the contract (seam 1). A site never has two of the same concept.
+   */
+  content: {
+    posts?: ConceptConfig;
+    pages?: ConceptConfig;
+  };
+  backend: BackendConfig;
+  sender: SenderConfig;
+  /** Design-accurate preview: the same render pipeline the site ships. */
+  renderPreview(md: string): string | Promise<string>;
+  /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
+  registry?: ComponentRegistry;
+  navMenu?: NavMenuConfig;
+  assets?: AssetConfig;
+}
+
+/**
+ * Concept-fixed routing for a normalized concept (spec §7.2). Posts are dated feed entries;
+ * pages are plain navigable structure. Not in adapter config.
+ */
+export interface RoutingRule {
+  /** Routable as a standalone URL. A future Fragments concept is embedded, not routable. */
+  routable: boolean;
+  /** Carries a date (posts). */
+  dated: boolean;
+  /** Appears in feeds and the sitemap (posts). */
+  inFeeds: boolean;
+}
+
+/**
+ * The engine-internal, uniform view of one concept after normalization (seam 1). The admin
+ * nav, the list views, and the editor all read this, never the raw config.
+ */
+export interface ConceptDescriptor {
+  /** Concept id, the key under `content`, e.g. "posts". */
+  id: string;
+  label: string;
+  dir: string;
+  routing: RoutingRule;
+  fields: FrontmatterField[];
+  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+}
+
+/**
+ * A site-defined admin screen contributed by an extension (Mode 2). It gains a sidebar entry, the
+ * `/admin` guard, and the session, and may commit through the same GitHub pipeline. The dispatch
+ * route is built in Plan 09; the `load`/`actions`/`component` members are typed loosely here and
+ * tightened when the machinery lands.
+ */
+export interface AdminPanel {
+  /** Routes under `/admin/<id>`; also the sidebar key. */
+  id: string;
+  /** Sidebar label. */
+  label: string;
+  /** Owner-gated, like editor management. */
+  owner?: boolean;
+  /** Server load, behind the guard. Typed in Plan 09. */
+  load?: (event: unknown) => unknown;
+  /** Named form actions, which may use the commit pipeline. Typed in Plan 09. */
+  actions?: Record<string, (event: unknown) => Promise<unknown>>;
+  /** The panel UI, rendered inside the admin shell. Typed as a component in Plan 09. */
+  component: unknown;
+}
+
+/**
+ * A custom frontmatter field type contributed by an extension (Mode 2): a renderer plus a validator
+ * dispatched alongside the built-in field union. The renderer and validator are typed in Plan 09
+ * when the form dispatch becomes a registry; the `type` key reserves the discriminator now.
+ */
+export interface FieldTypeDef {
+  /** The field-type discriminator, e.g. "color". */
+  type: string;
+}
+
+/**
+ * A future build-time extension (seam 2). It folds in the same way the adapter does and
+ * contributes the same kinds of things. Reserved and unused in the rebuild; the shape is
+ * fixed now so the extension contract is additive later.
+ */
+export interface CairnExtension {
+  /** Additional concepts, merged after the adapter's. */
+  content?: Record<string, ConceptConfig>;
+  /** Site-defined admin panels (Mode 2). Carried onto the runtime now; dispatched in Plan 09. */
+  adminPanels?: AdminPanel[];
+  /** Custom field types (Mode 2). Carried onto the runtime now; dispatched in Plan 09. */
+  fieldTypes?: FieldTypeDef[];
+}
+
+/**
+ * The composed runtime the engine serves from (seam 2 output). The single aggregation point
+ * (`composeRuntime`) folds the adapter and any extensions into this shape.
+ */
+export interface CairnRuntime {
+  siteName: string;
+  concepts: ConceptDescriptor[];
+  backend: BackendConfig;
+  sender: SenderConfig;
+  renderPreview(md: string): string | Promise<string>;
+  registry?: ComponentRegistry;
+  navMenu?: NavMenuConfig;
+  assets?: AssetConfig;
+  /** Admin panels contributed by extensions (Mode 2). Empty until Plan 09 wires the dispatch route. */
+  adminPanels?: AdminPanel[];
+  /** Field types contributed by extensions (Mode 2). Empty until Plan 09 wires the form dispatch. */
+  fieldTypes?: FieldTypeDef[];
+}