@glw907/cairn-cms 0.62.2 → 0.76.0

package/src/lib/components/ReferenceField.svelte

@@ -0,0 +1,126 @@
+<!--
+@component
+The reference field editor arm. A single `reference` renders a combobox-style button showing the
+current target's resolved title (looked up in the site's link targets), opening EntryPicker scoped to
+the field's concept; on pick it sets the value and emits one hidden input the decoder reads. A many
+`array(reference)` renders a removable chip list, each chip showing the target's resolved title, plus
+an EntryPicker that marks the already-held ids and adds another; it emits one hidden input per selected
+id, so frontmatterFromForm's getAll reads them all. EntryPicker owns the search and grouped list; this
+component owns the cardinality, the chips, and the hidden inputs the form submits.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import type { LinkTarget } from '../content/manifest.js';
+  import type { ReferenceField } from '../content/fields.js';
+  import type { NamedField } from '../content/types.js';
+  import EntryPicker from './EntryPicker.svelte';
+
+  interface Props {
+    /** The reference or array(reference) descriptor this arm renders. */
+    field: NamedField;
+    /** The current value: one id for a single reference, a list of ids for an array. */
+    value: string | string[];
+    /** The site's link targets, from the committed manifest (editLoad ships them). */
+    targets: LinkTarget[];
+    /** Called when the committed ids change (a pick, an add, or a remove), so the host sets
+     *  fieldsDirty. The hidden-input writes do not fire the form's oninput, so the field signals
+     *  dirty explicitly, the same way MediaHeroField does. */
+    ondirty?: () => void;
+  }
+
+  let { field, value, targets, ondirty }: Props = $props();
+
+  // The descriptor's concept, read from the single reference or the array's reference item, so the
+  // picker scopes to the right concept and a chip resolves its title within that concept's targets.
+  // Narrow on field.type so the access needs no cast; the array item is always a reference here
+  // (fieldset's checkArrayItems enforces it at declaration), so the one cast names that guarantee.
+  const concept = $derived.by(() => {
+    if (field.type === 'array') return (field.item as ReferenceField).concept;
+    if (field.type === 'reference') return field.concept;
+    return '';
+  });
+
+  // The single reference's current id, seeded once from the prop and owned thereafter (untrack marks
+  // the read a deliberate one-time seed, not a reactive dependency). Updated on pick.
+  let singleId = $state(untrack(() => (typeof value === 'string' ? value : '')));
+  // The array's current ids, seeded once from the prop and updated as chips are added and removed.
+  let ids = $state<string[]>(untrack(() => (Array.isArray(value) ? [...value] : [])));
+
+  // The headless picker; this component drives it so it can carry the concept filter and the held ids.
+  let picker = $state<{ open: () => void } | null>(null);
+
+  /** Resolve an id to its target title within this field's concept, falling back to the bare id. */
+  function titleFor(id: string): string {
+    return targets.find((t) => t.concept === concept && t.id === id)?.title ?? id;
+  }
+
+  function chooseSingle(target: LinkTarget) {
+    singleId = target.id;
+    ondirty?.();
+  }
+  function chooseMany(target: LinkTarget) {
+    if (!ids.includes(target.id)) {
+      ids = [...ids, target.id];
+      ondirty?.();
+    }
+  }
+  function remove(id: string) {
+    ids = ids.filter((x) => x !== id);
+    ondirty?.();
+  }
+</script>
+
+{#if field.type === 'array'}
+  <fieldset class="m-0 flex min-w-0 flex-col gap-2 border-0 p-0">
+    <legend class="text-sm font-medium">{field.label}</legend>
+    {#if ids.length}
+      <ul class="flex flex-wrap gap-2">
+        {#each ids as id (id)}
+          <li class="badge badge-ghost gap-1">
+            <span>{titleFor(id)}</span>
+            <button type="button" class="btn btn-ghost btn-xs btn-square" aria-label={`Remove ${titleFor(id)}`} onclick={() => remove(id)}>
+              <svg xmlns="http://www.w3.org/2000/svg" class="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12" /></svg>
+            </button>
+            <input type="hidden" name={field.name} value={id} />
+          </li>
+        {/each}
+      </ul>
+    {/if}
+    <div>
+      <button type="button" class="btn btn-sm btn-ghost" aria-haspopup="dialog" aria-label={`Add ${field.label}`} onclick={() => picker?.open()}>
+        Add {field.label}
+      </button>
+    </div>
+  </fieldset>
+  <EntryPicker
+    bind:this={picker}
+    {targets}
+    choose={chooseMany}
+    conceptFilter={concept}
+    selectedIds={ids}
+    trigger={false}
+    heading={`Choose ${field.label}`}
+    searchLabel={`Search ${concept}`}
+    emptyText={`No ${concept} to choose.`}
+  />
+{:else}
+  <div class="flex flex-col gap-1">
+    <span class="text-sm font-medium">{field.label}</span>
+    <button type="button" class="btn btn-sm btn-ghost justify-start" aria-haspopup="dialog" aria-label={field.label} onclick={() => picker?.open()}>
+      {#if singleId}{titleFor(singleId)}{:else}<span class="text-[var(--color-muted)]">Choose {field.label}</span>{/if}
+    </button>
+    {#if singleId}
+      <input type="hidden" name={field.name} value={singleId} />
+    {/if}
+  </div>
+  <EntryPicker
+    bind:this={picker}
+    {targets}
+    choose={chooseSingle}
+    conceptFilter={concept}
+    trigger={false}
+    heading={`Choose ${field.label}`}
+    searchLabel={`Search ${concept}`}
+    emptyText={`No ${concept} to choose.`}
+  />
+{/if}

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.