@glw907/cairn-cms 0.68.0 → 0.76.0

package/src/lib/components/RepeatableField.svelte

@@ -0,0 +1,310 @@
+<!--
+@component
+The repeatable-row editor, the arm for a non-reference `array` container. It renders a list of rows,
+each row either a single leaf (`array(text)`, `array(image)`) or a flat object group
+(`array(object({...}))`), with keyboard-operable add, remove, and reorder. Each row collapses to its
+`itemLabel` summary and expands to edit, the same buries-fewer-fields move the Details panel makes.
+
+Rows are wrapped in a `{ id, value }` envelope so node identity follows a row through a reorder or a
+remove and an in-progress edit (or the keyboard focus) never jumps to the wrong row. The id is a
+seed-time counter, not a random uuid, so the server and client agree at hydration. The envelope is
+UI-only; the form names derive from each row's CURRENT position (`${name}.${i}`), so the Task 3
+decoder reads a compact, ordered set. The component seeds once from `rows`; the `{#key entryKey}`
+wrapper in EditPage remounts it on an entry change, so it adds no re-seed effect.
+
+A structural mutation (add, remove, reorder) marks the form dirty, because those do not fire the
+form's `oninput`; a leaf edit inside a row does not, because the row inputs sit inside the edit form
+whose `oninput` bubbles. An always-mounted polite live region announces add and remove.
+-->
+<script lang="ts">
+  import { tick, untrack } from 'svelte';
+  import { sortItems } from '@rodrigodagostino/svelte-sortable-list';
+  import FieldInput from './FieldInput.svelte';
+  import ObjectGroupField from './ObjectGroupField.svelte';
+  import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
+  import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
+  import ArrowUpIcon from '@lucide/svelte/icons/arrow-up';
+  import ArrowDownIcon from '@lucide/svelte/icons/arrow-down';
+  import Trash2Icon from '@lucide/svelte/icons/trash-2';
+  import PlusIcon from '@lucide/svelte/icons/plus';
+  import type { NamedField } from '../content/types.js';
+  import type { ArrayField, ObjectField } from '../content/fields.js';
+  import type { LinkTarget } from '../content/manifest.js';
+  import type { MediaEntry } from '../media/manifest.js';
+  import type { MediaLibraryEntry } from '../media/library-entry.js';
+  import type { IconSet } from '../render/glyph.js';
+  import type MediaHeroField from './MediaHeroField.svelte';
+
+  interface Props {
+    /** The array descriptor to render; its `item` is the per-row leaf or flat object. */
+    field: NamedField & ArrayField;
+    /** The form name prefix for this list; each row renders at `${name}.${i}`. */
+    name: string;
+    /** The seed rows: a list of leaf values, or a list of object slices for an object item. */
+    rows: unknown[];
+    /** The site link targets the reference arm offers (threaded through to each row). */
+    targets: LinkTarget[];
+    /** Mark the edit form dirty; called on add, remove, and reorder (these skip the form's oninput). */
+    markFieldsDirty: () => void;
+    /** The merged committed-plus-uploaded media library, keyed by content hash. */
+    mediaLibrary: Record<string, MediaLibraryEntry>;
+    /** The concept the entry belongs to (the upload action's route param). */
+    conceptId: string;
+    /** The entry id (the upload action's route param). */
+    id: string;
+    /** The host's hero-field refs, keyed by the prefixed `name` so two rows do not collide. */
+    heroFieldRefs: Record<string, MediaHeroField>;
+    /** Called with the server-owned record on a successful upload, so the host merges it. */
+    onuploaded: (record: MediaEntry) => void;
+    /** Called when a hero's needs-alt status changes, keyed by the prefixed `name`. */
+    onheroneedsalt: (name: string, needsAlt: boolean) => void;
+    /** The site's icon set, forwarded to each row's icon arm. */
+    icons?: IconSet;
+  }
+
+  let {
+    field,
+    name,
+    rows: seedRows,
+    targets,
+    markFieldsDirty,
+    mediaLibrary,
+    conceptId,
+    id,
+    heroFieldRefs,
+    onuploaded,
+    onheroneedsalt,
+    icons,
+  }: Props = $props();
+
+  /** One row of editable state: a stable id for keyed identity, and the row's current value. */
+  interface Row {
+    id: number;
+    value: unknown;
+  }
+
+  // The id of the next appended row. Seeded past the initial rows so a freshly added row never
+  // collides with a seeded one; a plain counter (not randomUUID) so SSR and the client agree.
+  let nextId = untrack(() => seedRows.length);
+
+  // The rows, seeded once from the prop and owned thereafter (untrack marks the read a deliberate
+  // one-time seed). No re-seed effect: EditPage's {#key entryKey} wrapper remounts on entry change.
+  let rows = $state<Row[]>(untrack(() => seedRows.map((value, i) => ({ id: i, value }))));
+
+  // Which rows are expanded for editing, keyed by row id; a collapsed row shows its summary only.
+  let expanded = $state<Record<number, boolean>>({});
+
+  // The polite announcement, mounted empty and filled on a structural mutation.
+  let announcement = $state('');
+
+  // The Add button, the last link in the remove focus chain (when no row remains to focus).
+  let addButton = $state<HTMLButtonElement | null>(null);
+
+  // This instance's outer fieldset. Every focus query scopes to it, so two RepeatableField lists on
+  // one page (the showcase posts concept renders both an array(object) and an array(image)) never
+  // move focus into the other list. A document-wide query would index across both row sets.
+  let root = $state<HTMLFieldSetElement | null>(null);
+
+  const isObjectItem = $derived(field.item.type === 'object');
+  const rowLabel = $derived(field.label ?? field.name);
+
+  // The live itemLabel text per row id, tracked so a collapsed row's summary follows the author's
+  // edits. The row inputs stay uncontrolled (the keyed envelope owns the seed; writing row.value on
+  // every keystroke risks edit loss), so this mirrors only the summary-label field, read on input.
+  let summaries = $state<Record<number, string>>({});
+
+  // The form name of a row's itemLabel field: the object sub-field path, or the leaf row path itself.
+  function summaryNameFor(index: number): string {
+    return isObjectItem && field.itemLabel != null
+      ? `${name}.${index}.${field.itemLabel}`
+      : `${name}.${index}`;
+  }
+
+  // Mirror a row's itemLabel value into the live summary map when its input fires. A non-summary
+  // input in the row is ignored, so the collapsed label tracks only the label field.
+  function onRowInput(row: Row, index: number, event: Event) {
+    const target = event.target as HTMLInputElement;
+    if (target.name === summaryNameFor(index)) {
+      summaries = { ...summaries, [row.id]: target.value };
+    }
+  }
+
+  // The collapsed summary for a row: the live itemLabel text when the author has edited it, else its
+  // seeded itemLabel value (object row) or the leaf value, falling back to a positional placeholder.
+  function summaryFor(value: unknown, index: number, rowId: number): string {
+    if (rowId in summaries) {
+      const live = summaries[rowId].trim();
+      if (live !== '') return live;
+    }
+    let text = '';
+    if (isObjectItem && field.itemLabel != null && value !== null && typeof value === 'object') {
+      text = String((value as Record<string, unknown>)[field.itemLabel] ?? '').trim();
+    } else if (!isObjectItem && value != null && typeof value !== 'object') {
+      text = String(value).trim();
+    }
+    return text !== '' ? text : `${rowLabel} ${index + 1}`;
+  }
+
+  // An empty value for a freshly added row: an empty object for an object item, an empty string for
+  // a leaf. The decoder prunes an all-default row, so an untouched added row never reaches the form.
+  function emptyValue(): unknown {
+    return isObjectItem ? {} : '';
+  }
+
+  function toggle(rowId: number) {
+    expanded = { ...expanded, [rowId]: !expanded[rowId] };
+  }
+
+  async function add() {
+    const row: Row = { id: nextId++, value: emptyValue() };
+    rows = [...rows, row];
+    expanded = { ...expanded, [row.id]: true };
+    markFieldsDirty();
+    announcement = 'Row added';
+    await tick();
+    // Land focus on the first operable control in the new row's EDIT BODY (not the row header's
+    // toggle/move/remove chrome). The selector spans an array(image) row too, whose MediaHeroField
+    // empty state is a <button> dropzone with only hidden inputs.
+    const firstInput = root?.querySelector<HTMLElement>(
+      `[data-cairn-row="${row.id}"] [data-cairn-row-body] :is(input:not([type=hidden]),textarea,select,button)`,
+    );
+    firstInput?.focus();
+  }
+
+  async function remove(index: number) {
+    rows = rows.filter((_, i) => i !== index);
+    markFieldsDirty();
+    announcement = 'Row removed';
+    await tick();
+    // Focus chain: the next row's remove control, else the previous row's, else the Add button.
+    const removeButtons = root?.querySelectorAll<HTMLElement>('[data-cairn-row-remove]') ?? [];
+    if (removeButtons[index]) removeButtons[index].focus();
+    else if (removeButtons[index - 1]) removeButtons[index - 1].focus();
+    else addButton?.focus();
+  }
+
+  async function move(index: number, dir: 1 | -1) {
+    const target = index + dir;
+    if (target < 0 || target >= rows.length) return;
+    rows = sortItems(rows, index, target);
+    markFieldsDirty();
+    await tick();
+    // Keep keyboard focus on the moved row after a reorder. The arrow that fired the move can become
+    // disabled at the first or last boundary, so focus the opposite-direction arrow, falling back to
+    // the row toggle. Both queries scope to this instance's fieldset.
+    const movedRow = root?.querySelectorAll<HTMLElement>('[data-cairn-row]')[target];
+    const opposite = dir === 1 ? '[data-cairn-row-up]' : '[data-cairn-row-down]';
+    const focusTarget =
+      movedRow?.querySelector<HTMLElement>(`${opposite}:not([disabled])`) ??
+      movedRow?.querySelector<HTMLElement>('[data-cairn-row-toggle]');
+    focusTarget?.focus();
+  }
+</script>
+
+<fieldset bind:this={root} class="m-0 flex min-w-0 flex-col gap-2 border-0 p-0">
+  <legend class="text-sm font-medium">{rowLabel}</legend>
+
+  {#if rows.length}
+    <ul class="flex flex-col gap-2">
+      {#each rows as row, i (row.id)}
+        {@const rowSummary = summaryFor(row.value, i, row.id)}
+        <li
+          class="rounded-[var(--radius-field)] border border-[var(--color-base-300)]"
+          data-cairn-row={row.id}
+          oninput={(e) => onRowInput(row, i, e)}
+        >
+          <div class="flex items-center gap-1 p-1">
+            <button
+              type="button"
+              class="btn btn-ghost btn-sm flex-1 justify-start gap-2 font-normal"
+              data-cairn-row-toggle
+              aria-expanded={expanded[row.id] ? 'true' : 'false'}
+              onclick={() => toggle(row.id)}
+            >
+              {#if expanded[row.id]}
+                <ChevronDownIcon class="h-4 w-4 shrink-0" aria-hidden="true" />
+              {:else}
+                <ChevronRightIcon class="h-4 w-4 shrink-0" aria-hidden="true" />
+              {/if}
+              <span class="truncate">{rowSummary}</span>
+            </button>
+            <button
+              type="button"
+              class="btn btn-ghost btn-sm btn-square"
+              data-cairn-row-up
+              aria-label={`Move ${rowSummary} up`}
+              disabled={i === 0}
+              onclick={() => move(i, -1)}
+            >
+              <ArrowUpIcon class="h-4 w-4" aria-hidden="true" />
+            </button>
+            <button
+              type="button"
+              class="btn btn-ghost btn-sm btn-square"
+              data-cairn-row-down
+              aria-label={`Move ${rowSummary} down`}
+              disabled={i === rows.length - 1}
+              onclick={() => move(i, 1)}
+            >
+              <ArrowDownIcon class="h-4 w-4" aria-hidden="true" />
+            </button>
+            <button
+              type="button"
+              class="btn btn-ghost btn-sm btn-square"
+              data-cairn-row-remove
+              aria-label={`Remove ${rowSummary}`}
+              onclick={() => remove(i)}
+            >
+              <Trash2Icon class="h-4 w-4" aria-hidden="true" />
+            </button>
+          </div>
+          {#if expanded[row.id]}
+            <div data-cairn-row-body class="flex flex-col gap-3 border-t border-[var(--color-base-300)] p-3">
+              {#if field.item.type === 'object'}
+                <ObjectGroupField
+                  field={{ ...(field.item as ObjectField), name: field.name }}
+                  name={`${name}.${i}`}
+                  frontmatter={(row.value !== null && typeof row.value === 'object' ? row.value : {}) as Record<string, unknown>}
+                  {targets}
+                  {markFieldsDirty}
+                  {mediaLibrary}
+                  {conceptId}
+                  {id}
+                  {heroFieldRefs}
+                  {onuploaded}
+                  {onheroneedsalt}
+                  {icons}
+                />
+              {:else}
+                <FieldInput
+                  field={{ ...field.item, name: '_value' }}
+                  name={`${name}.${i}`}
+                  frontmatter={{ _value: row.value }}
+                  {targets}
+                  {markFieldsDirty}
+                  {mediaLibrary}
+                  {conceptId}
+                  {id}
+                  {heroFieldRefs}
+                  {onuploaded}
+                  {onheroneedsalt}
+                  {icons}
+                />
+              {/if}
+            </div>
+          {/if}
+        </li>
+      {/each}
+    </ul>
+  {/if}
+
+  <div>
+    <button type="button" class="btn btn-sm btn-ghost gap-1" bind:this={addButton} onclick={add}>
+      <PlusIcon class="h-4 w-4" aria-hidden="true" />
+      Add {rowLabel}
+    </button>
+  </div>
+
+  <!-- Always mounted so add/remove announce consistently; a {#if}-gated region announces unevenly. -->
+  <div role="status" aria-live="polite" class="sr-only">{announcement}</div>
+</fieldset>

package/src/lib/components/preview-doc.ts

@@ -64,9 +64,13 @@ export function buildPreviewDoc(html: string, preview: ResolvedPreview | null):
   // parent's base URL, so a clicked fragment or root link could render the admin login inside
   // the frame. Targeting every link at a new tab turns each click into a popup, and the sandbox
   // (which grants no allow-popups) blocks it, so a proofing click goes nowhere.
+  // The marker on the root lets a site scope an entrance animation (driven off [data-rise]) away
+  // from the preview, which shows the resting state of content and runs the same pipeline; without
+  // it, content would re-animate on every debounced render. cairn provides the hook; the site owns
+  // its animation and decides what to suppress under [data-cairn-preview].
   return [
     '<!doctype html>',
-    '<html>',
+    '<html data-cairn-preview>',
     '<head>',
     '<meta charset="utf-8">',
     '<meta name="viewport" content="width=device-width, initial-scale=1">',

package/src/lib/components/tidy-validate.ts

@@ -62,7 +62,7 @@ const DIVERGENCE_FRACTION = 0.5;
 // text rather than going through extractMediaRefs for two reasons. First, a true MULTISET is the
 // invariant a backstop wants: extractMediaRefs dedups by hash, so a doubled token collapsing to one
 // would read as equal, and the validator must catch a dropped duplicate. Second, the raw scan covers
-// the whole text including frontmatter without threading the concept's FrontmatterField[] to the call
+// the whole text including frontmatter without threading the concept's NamedField[] to the call
 // site, which the validator otherwise has no reason to know. A token mangled inside a code fence is
 // caught here too, redundantly with the code check, which is the right posture for a backstop.
 const MEDIA_TOKEN = /media:[A-Za-z0-9.-]+/g;

package/src/lib/content/adapter.ts

@@ -4,7 +4,28 @@
 // full-auto typed reads in createSiteIndexes, while still checking the adapter against the contract.
 import type { CairnAdapter } from './types.js';
 
+// Fail closed on an inconsistent island registry: a hydrate component with no live component, or a
+// registered island with no hydrate component. Either is a wiring mistake the site author should see at
+// build time, not a silent forever-fallback. Read-only over the rendering group; imports no runtime.
+function assertIslandsConsistent(rendering: CairnAdapter['rendering']): void {
+  const islands = rendering.islands ?? {};
+  const hydrated = new Set(
+    (rendering.components?.defs ?? []).filter((d) => d.hydrate).map((d) => d.name),
+  );
+  for (const name of hydrated) {
+    if (!(name in islands)) {
+      throw new Error(`cairn: component '${name}' declares hydrate but rendering.islands has no entry for it.`);
+    }
+  }
+  for (const name of Object.keys(islands)) {
+    if (!hydrated.has(name)) {
+      throw new Error(`cairn: rendering.islands has '${name}' but no component declares hydrate for it.`);
+    }
+  }
+}
+
 /** Declare a site's adapter while preserving each concept's concrete schema type for typed reads. */
 export function defineAdapter<const A extends CairnAdapter>(adapter: A): A {
+  assertIslandsConsistent(adapter.rendering);
   return adapter;
 }

package/src/lib/content/advisories.ts

@@ -12,10 +12,8 @@
 // notice and never blocks the editor or the publish. The scope splits by call site: the main arm at
 // edit-load (synchronous, no extra GitHub read per open) and the full cross-branch check at publish.
 import type { ConceptDescriptor } from './types.js';
-import type { RepoRef } from '../github/types.js';
+import type { Backend } from '../github/backend.js';
 import type { Manifest } from './manifest.js';
-import { listBranches } from '../github/branches.js';
-import { readRaw } from '../github/repo.js';
 import { PENDING_PREFIX, parsePendingBranch } from './pending.js';
 import { findConcept } from './concepts.js';
 import { isValidId, filenameFromId } from './ids.js';
@@ -90,8 +88,7 @@ export function mainAddressIndex(manifest: Manifest): AddressIndex {
  * publish. The branches are read in one Promise.all, the way buildUsageIndex reads them.
  */
 export async function buildAddressIndex(
-  repo: RepoRef,
-  token: string,
+  backend: Backend,
   concepts: ConceptDescriptor[],
   manifest: Manifest,
 ): Promise<AddressIndex> {
@@ -101,7 +98,7 @@ export async function buildAddressIndex(
 
   // The branch arm: read each open cairn/* branch's one edited file and resolve its permalink. The
   // path is derivable from the branch name, so no tree-listing is needed.
-  const names = await listBranches(repo, PENDING_PREFIX, token);
+  const names = await backend.listBranches(PENDING_PREFIX);
   const perBranch = await Promise.all(
     names.map(async (name): Promise<{ permalink: string; entry: AddressEntry } | null> => {
       // Resolve the branch name with the branch tooling's guard: a malformed name, an id that fails
@@ -113,7 +110,7 @@ export async function buildAddressIndex(
 
       const path = `${concept.dir}/${filenameFromId(ref.id)}`;
       try {
-        const raw = await readRaw({ ...repo, branch: name }, path, token);
+        const raw = await backend.readFile(path, name);
         if (raw === null) return null; // The file is absent on the branch: nothing to resolve.
         const { frontmatter } = parseMarkdown(raw);
         const fmTitle = frontmatter.title;

package/src/lib/content/compose.ts

@@ -8,10 +8,18 @@ import { resolveConcepts } from './concepts.js';
 import { normalizeAssets } from '../media/config.js';
 import { dictionaryFileForDialect, type SiteConfig } from '../nav/site-config.js';
 
+// The internal artifact paths the adapter does not carry. They share the `.cairn/` content root the
+// manifests use, so `composeRuntime` defaults them by convention rather than reading them off config.
+// The personal dictionary sits beside the manifests, so the spec's `content/.cairn/dictionary.txt`
+// resolves the same configurable way the manifest paths do.
+const CONTENT_MANIFEST_PATH = 'src/content/.cairn/index.json';
+const MEDIA_MANIFEST_PATH = 'src/content/.cairn/media.json';
+const DICTIONARY_PATH = 'src/content/.cairn/dictionary.txt';
+
 /**
- * The input to {@link composeRuntime}. `siteConfig` is required so the per-concept URL policy is
- *  always derived from one source and can never be silently dropped. `extensions` fold in after the
- *  adapter's concepts.
+ * The input to {@link composeRuntime}. `siteConfig` is required: it is the canonical home for the
+ *  site name, the spellcheck dialect, and the tidy block, so they can never be silently dropped.
+ *  `extensions` fold in after the adapter's concepts.
  */
 export interface ComposeInput {
   adapter: CairnAdapter;
@@ -20,13 +28,14 @@ export interface ComposeInput {
 }
 
 /**
- * Fold an adapter and any extensions into the composed runtime (seam 2). The per-concept URL policy
- * is derived from the site config, the same source the delivery path uses, so the runtime and
- * delivery permalinks cannot diverge. Extension concepts merge after the adapter's. The asset slot
+ * Fold an adapter and any extensions into the composed runtime (seam 2). This is the one place the
+ * grouped adapter maps onto the flat runtime, and the one place the internal manifest and dictionary
+ * paths default by convention. Each concept declares its own routing and URL policy, so the runtime
+ * and delivery permalinks cannot diverge. Extension concepts merge after the adapter's. The media slot
  * (seam 4) passes through untouched.
  */
 export function composeRuntime({ adapter, siteConfig, extensions = [] }: ComposeInput): CairnRuntime {
-  if (!siteConfig) throw new Error('composeRuntime needs a site config to derive the URL policy');
+  if (!siteConfig) throw new Error('composeRuntime needs a site config for the site name and editor settings');
   const content: Record<string, ConceptConfig | undefined> = { ...adapter.content };
   const adminPanels: AdminPanel[] = [];
   const fieldTypes: FieldTypeDef[] = [];
@@ -38,23 +47,21 @@ export function composeRuntime({ adapter, siteConfig, extensions = [] }: Compose
     if (extension.fieldTypes) fieldTypes.push(...extension.fieldTypes);
   }
   return {
-    siteName: adapter.siteName,
-    concepts: resolveConcepts(content, siteConfig),
+    siteName: siteConfig.siteName,
+    concepts: resolveConcepts(content),
     backend: adapter.backend,
-    sender: adapter.sender,
-    supportContact: adapter.supportContact,
-    render: adapter.render,
-    manifestPath: adapter.manifestPath ?? 'src/content/.cairn/index.json',
-    registry: adapter.registry,
-    icons: adapter.icons,
-    navMenu: adapter.navMenu,
-    preview: adapter.preview,
-    assets: adapter.assets,
-    resolvedAssets: normalizeAssets(adapter.assets),
-    mediaManifestPath: adapter.mediaManifestPath ?? 'src/content/.cairn/media.json',
-    // The personal dictionary sits beside the manifests under the same `.cairn/` content root, so the
-    // spec's `content/.cairn/dictionary.txt` resolves the same configurable way the manifest paths do.
-    dictionaryPath: adapter.dictionaryPath ?? 'src/content/.cairn/dictionary.txt',
+    sender: adapter.email,
+    supportContact: adapter.editor?.supportContact,
+    render: adapter.rendering.render,
+    manifestPath: CONTENT_MANIFEST_PATH,
+    registry: adapter.rendering.components,
+    icons: adapter.rendering.icons,
+    navMenu: adapter.editor?.nav,
+    preview: adapter.editor?.preview,
+    assets: adapter.media,
+    resolvedAssets: normalizeAssets(adapter.media),
+    mediaManifestPath: MEDIA_MANIFEST_PATH,
+    dictionaryPath: DICTIONARY_PATH,
     // The spellcheck dictionary is resolved once here from the site config's dialect (default US),
     // so the runtime and the editor never re-derive it. The site config is the one home for the
     // dialect; the editor resolves this filename to a real asset URL on the main thread.

package/src/lib/content/concepts.ts

@@ -1,23 +1,41 @@
-// 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, ConceptUrlPolicy, RoutingRule } from './types.js';
-import { urlPolicyFrom, type SiteConfig } from '../nav/site-config.js';
+// cairn-cms: concept normalization (seam 1). The adapter declares concepts as an open `content`
+// record; this turns each declared key into a uniform descriptor (id, label, directory, declared
+// routing, fields, validator) the admin reads. A new concept attaches by adding one key under
+// `content` and declaring its own routing and URL policy, with no reshape here.
+import type { ConceptConfig, ConceptDescriptor, ConceptUrlPolicy, NamedField, RoutingRule } from './types.js';
+import type { Fieldset } from './fieldset.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 },
+/** Re-attach each fieldset record key to its descriptor as `name`, the normalized `NamedField[]`. */
+function namedFields(schema: Fieldset): NamedField[] {
+  return Object.entries(schema.fields).map(([name, descriptor]) => ({ name, ...descriptor }));
+}
+
+/** The named routing shorthands, each expanding to a concrete rule. */
+const ROUTING_SHORTHANDS: Readonly<Record<'feed' | 'page' | 'embedded', RoutingRule>> = {
+  feed: { routable: true, dated: true, inFeeds: true },
+  page: { routable: true, dated: false, inFeeds: false },
+  embedded: { routable: false, 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 };
+/** Expand a concept's routing shorthand to a concrete rule. The single resolution point: omitted is `page`. */
+export function resolveRouting(routing: ConceptConfig['routing']): RoutingRule {
+  if (routing === undefined) return ROUTING_SHORTHANDS.page;
+  return typeof routing === 'string' ? ROUTING_SHORTHANDS[routing] : routing;
+}
+
+/**
+ * Declare a concept while preserving its fieldset type for typed reads, and validate its URL policy at
+ * declaration so a bad permalink or datePrefix fails at module load rather than at a defaulted render.
+ * Mirrors {@link defineAdapter}; the validation is the build-independent net for a concept with no entries.
+ */
+export function defineConcept<const C extends ConceptConfig>(concept: C): C {
+  validateUrlPolicy(
+    concept.label ?? concept.dir,
+    { permalink: concept.permalink, datePrefix: concept.datePrefix },
+    resolveRouting(concept.routing).dated,
+  );
+  return concept;
+}
 
 /** Title-case a concept id for the default sidebar label, e.g. "posts" to "Posts". */
 function defaultLabel(id: string): string {
@@ -41,7 +59,7 @@ const DATE_PREFIXES = new Set<string>(['year', 'month', 'day']);
  * here rather than emitting a wrong or defaulted URL at render. The permalink must be root-relative and
  * use only known tokens, a date token requires a dated concept, and the datePrefix must be in range.
  */
-function validateUrlPolicy(id: string, policy: ConceptUrlPolicy, dated: boolean): void {
+export function validateUrlPolicy(id: string, policy: ConceptUrlPolicy, dated: boolean): void {
   if (policy.permalink !== undefined) {
     const pattern = policy.permalink;
     if (!pattern.startsWith('/')) {
@@ -67,38 +85,48 @@ function validateUrlPolicy(id: string, policy: ConceptUrlPolicy, dated: boolean)
 }
 
 /**
- * Normalize an adapter's declared concepts into uniform descriptors (seam 1). URL policy
- * (`permalink`, `datePrefix`) comes from the YAML site-config, passed here as `urlPolicy` keyed by
- * concept id; each value defaults when the YAML omits it (`/:slug` for Pages, `/<id>/:slug`
- * otherwise; `datePrefix` defaults to `day`). `routing` is injectable so a contract test can prove
- * a new concept attaches additively; production passes the default `CONCEPT_ROUTING`.
+ * Normalize an adapter's declared concepts into uniform descriptors (seam 1). Each concept declares its
+ * own routing (a shorthand or an explicit rule, resolved by `resolveRouting`) and URL policy
+ * (`permalink`, `datePrefix`) on the config; both default when omitted (`/:slug` for Pages, `/<id>/:slug`
+ * otherwise; `datePrefix` defaults to `day`). A new concept attaches by adding one key under `content`.
  */
 export function normalizeConcepts(
   content: Record<string, ConceptConfig | undefined>,
-  urlPolicy: Record<string, ConceptUrlPolicy | undefined> = {},
-  routing: Readonly<Record<string, RoutingRule>> = CONCEPT_ROUTING,
 ): ConceptDescriptor[] {
   const descriptors: ConceptDescriptor[] = [];
   const declaredConcepts = new Set(
     Object.keys(content).filter((key) => content[key] !== undefined),
   );
-  for (const key of Object.keys(urlPolicy)) {
-    if (!declaredConcepts.has(key)) {
-      throw new Error(`cairn: URL policy names concept "${key}", which is not declared under content`);
-    }
-  }
   for (const [id, config] of Object.entries(content)) {
     if (!config) continue;
+    const fs = config.fields;
     const summaryFields = config.summaryFields ?? [];
-    const declared = new Set(config.schema.fields.map((field) => field.name));
+    const declared = new Set(Object.keys(fs.fields));
     const undeclared = summaryFields.find((key) => !declared.has(key));
     if (undeclared !== undefined) {
       throw new Error(
         `cairn: concept "${id}" summaryFields key "${undeclared}" is not a declared field`,
       );
     }
-    const conceptRouting = routing[id] ?? DEFAULT_ROUTING;
-    const policy = urlPolicy[id] ?? {};
+    // A reference (or array of reference) field names the concept it targets. Validate that concept at
+    // declaration, so a typo fails loudly here rather than at the build's verifyReferences gate (or, in
+    // the editor picker, as a silently empty target list). The check is the field descriptor's concept
+    // against the declared content keys.
+    for (const [name, descriptor] of Object.entries(fs.fields)) {
+      const targetConcept =
+        descriptor.type === 'reference'
+          ? descriptor.concept
+          : descriptor.type === 'array' && descriptor.item.type === 'reference'
+            ? descriptor.item.concept
+            : undefined;
+      if (targetConcept !== undefined && !declaredConcepts.has(targetConcept)) {
+        throw new Error(
+          `cairn: concept "${id}" reference field "${name}" names concept "${targetConcept}", which is not declared under content`,
+        );
+      }
+    }
+    const conceptRouting = resolveRouting(config.routing);
+    const policy: ConceptUrlPolicy = { permalink: config.permalink, datePrefix: config.datePrefix };
     validateUrlPolicy(id, policy, conceptRouting.dated);
     const label = config.label ?? defaultLabel(id);
     descriptors.push({
@@ -109,24 +137,24 @@ export function normalizeConcepts(
       routing: conceptRouting,
       permalink: policy.permalink ?? defaultPermalink(id),
       datePrefix: policy.datePrefix ?? 'day',
-      fields: config.schema.fields,
+      fields: namedFields(fs),
+      schema: fs,
       summaryFields,
-      validate: config.schema.validate,
+      validate: fs.validate,
     });
   }
   return descriptors;
 }
 
 /**
- * Resolve a site's concept descriptors from its content map and parsed site config. The admin runtime
- * (composeRuntime) and the delivery layer (siteDescriptors) both call this, so the per-concept URL
- * policy is derived once from the YAML and the runtime and delivery permalinks cannot diverge.
+ * Resolve a site's concept descriptors from its content map. The admin runtime (composeRuntime) and the
+ * delivery layer (siteDescriptors) both call this, so the per-concept routing and URL policy are derived
+ * once from the concept declarations and the runtime and delivery permalinks cannot diverge.
  */
 export function resolveConcepts(
   content: Record<string, ConceptConfig | undefined>,
-  siteConfig: SiteConfig,
 ): ConceptDescriptor[] {
-  return normalizeConcepts(content, urlPolicyFrom(siteConfig));
+  return normalizeConcepts(content);
 }
 
 /** Look up a normalized concept by id, or undefined when the site does not enable it. */