@glw907/cairn-cms 0.62.2 → 0.76.0

package/CHANGELOG.md

@@ -2,6 +2,222 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 0.76.0
+
+<!-- release-size: minor -->
+
+The Contract v2 rollup, plus content islands, published as one release. cairn is still `0.x` and the
+contract may change again before a stable 1.0. This consolidates the unpublished `0.69.0`–`0.75.0`
+development minors plus islands into one published `0.76.0` release. The last published release was
+`0.68.0`, so a consumer crosses the whole window in a single jump and applies the "Consumers must" steps
+below; the granular per-phase history lives in `docs/STATUS.md` and the plan post-mortems.
+
+What changed. The field system unifies on the `fieldset({...})` record built from the `fields.*`
+constructors, the one live field system for concepts and directive components alike, with the leaf
+vocabulary (`text`, `textarea`, `number`, `select`, `multiselect`, `url`, `email`, `date`, `datetime`,
+`boolean`, `image`, `icon`, `reference`) plus the `object` and `array` containers. The adapter moves from
+flat keys into six subsystem groups (`content`, `backend`, `email`, `rendering`, `media`, `editor`), and a
+concept owns its own URL policy through `defineConcept`. The `backend` becomes a `Backend` interface behind
+a `githubApp(...)` provider, so content stays build-time over the committed manifest and no runtime database
+slips in. The `render` seam becomes the entry-aware `render({ body, concept?, frontmatter?, resolve?,
+resolveMedia? }) => Promise<string>`. Content islands add opt-in client interactivity over a static, no-JS
+fallback. References and structured fields arrive additively.
+
+This is breaking. Consumers must, in order:
+
+The field system (replaces the v1 `defineFields`):
+
+1. Move each concept's `schema` from `defineFields([...])` (an array) to `fieldset({...})` (a record).
+2. Drop the per-field `name`; the record key is now the frontmatter key.
+3. Rename field help from `description` to `help`.
+4. Move a closed `tags` field to `fields.multiselect({ options: [...] })`, and an open `freetags` field to
+   `fields.multiselect({ creatable: true })` (its `placeholder` is preserved).
+5. Preserve each field's frontmatter key, especially `tags`, or tag pages and feeds read empty.
+6. Extract a frontmatter type with `InferFieldset`, and drop imports of the removed `defineFields`,
+   `ConceptSchema`, `Infer`, `InferFields`, `DefineFieldsOptions`, `FrontmatterField`, `TagsField`, and
+   `FreeTagsField`.
+
+The adapter and concepts:
+
+7. Regroup the adapter into `content`/`backend`/`email`/`rendering`/`media`/`editor` (`sender` to `email`,
+   `render`/`registry`/`icons` to `rendering.{render,components,icons}`, `assets` to `media`,
+   `navMenu`/`preview`/`supportContact` to `editor.{nav,preview,supportContact}`).
+8. Rename each concept's `schema:` to `fields:` and declare it through `defineConcept`.
+9. Move `permalink` and `datePrefix` from the YAML `content:` block onto the concept via `defineConcept`,
+   and declare each concept's routing with the routing shorthand. A leftover YAML `content:` block now
+   throws at `parseSiteConfig`.
+10. Move `siteName` out of the adapter into the YAML site-config.
+
+Directive components:
+
+11. Declare each component's `attributes` as a `fields.*` record (was an `AttributeField[]` array), a
+    repeatable slot's `itemFields` the same way, and wrap each component in `defineComponent({ ... })`.
+12. Move any cross-field attribute `validate` into the component's `behavior` table with the
+    `validate(value, siblings)` signature, reading `siblings.min` rather than `all.attributes.min`.
+13. Replace a `pattern: { source, message }` attribute with `fields.text({ pattern })` plus a
+    `behavior.validate` for a custom message, and drop imports of `AttributeField` and `FieldType`.
+    Attribute validation now format-checks every value, so a directive that previously saved a malformed
+    value now fails `validateComponent`.
+
+The backend:
+
+14. Change the adapter's `backend` from a `{ owner, repo, branch, appId, installationId }` object literal to
+    `backend: githubApp({ ... })`, importing `githubApp` from `@glw907/cairn-cms`. Drop imports of the
+    removed `BackendConfig`, `RepoRef`, and `AppCredentials`, and replace `GithubKeyEnv` (from the
+    `/sveltekit` subpath) with `BackendEnv`.
+
+The render seam:
+
+15. Change the adapter `render` from `(md, opts) => ...` to
+    `({ body, resolve, resolveMedia }) => ...`, read the markdown from `body`, and return a
+    `Promise<string>` (a typical body is `renderMarkdown(body, { resolve, resolveMedia })`). Drop any
+    `stagger` option; `data-rise` is now always emitted and is inert without `[data-rise]` CSS. The
+    attribute now appears in all rendered output, including the syndication feeds and prerendered pages,
+    so a consumer that snapshots rendered HTML sees it.
+
+Additive in this window, with no action required to keep working: reference fields (`fields.reference` and
+`fields.array(fields.reference(...))`), structured fields (`fields.object` and the generalized
+`fields.array`), and content islands (`hydrate` on a component, `rendering.islands`, and the `./islands`
+runtime). Adopt them through their guides: [references](docs/guides/link-content-with-references.md),
+[structured fields](docs/guides/structured-fields.md), and [islands](docs/guides/add-an-island.md).
+
+ecxc-ski and 907-life stay pinned to the prior version range until they cut over. See [Upgrading
+cairn](docs/guides/upgrade-cairn.md) for the per-change actions.
+
+## 0.68.0
+
+<!-- release-size: minor -->
+
+The second pre-cutover engine-hardening pass clears eight engine-misc items: two admin accessibility
+fixes, an engine default-icon fallback, and gate, doc, and tooling hygiene.
+
+The component picker dialog now caps its height at 85vh and scrolls its catalog within a held header
+and footer, so a long catalog no longer takes the page over. A repeated content-lifecycle error in the
+concept list now re-announces to a screen reader: the errors route through one polite live region that
+re-speaks an identical message through an invisible nonce, and the visible alerts drop their redundant
+`role` so the message announces once.
+
+The component registry ships a default role-to-glyph fallback for the conventional admonition roles
+(`note`, `tip`, `important`, `warning`, `caution`, `info`, `danger`). A component that declares an icon
+field but no `defaultIconByRole` entry for a role now resolves the engine default, which a site's icon
+set styles; a component's own `defaultIconByRole` still wins. The `ComponentDef.icon` and
+`defaultIconByRole` guidance now states the "logically representative, prefer distinct" rule.
+
+Three gates and one doc tightened: the admin-prose gate now scans the `.ts` copy modules it skipped, a
+new `check:dev-package` gate type-checks and comment-lints `packages/**` in CI, the two
+`rehype-dispatch` helpers gained real doc contracts, and the friction log marks its killed and shipped
+items resolved so it stops resurfacing dead work.
+
+No consumer action is required. The accessibility fixes and the icon fallback are additive; a site using
+the registry's `defaultIcon` may now see an engine default glyph where it previously saw none.
+
+## 0.67.0
+
+<!-- release-size: minor -->
+
+The Contract v2 `fieldset` validator reaches constraint parity with `defineFields`, the first of two
+pre-cutover engine-hardening passes. Both validators now call one shared constraint module, so they
+cannot drift, and a v1-vs-v2 parity matrix proves they agree on the overlapping field types.
+
+The `fieldset` validator gains the checks it lacked. A `text` or `textarea` field now enforces its
+`min`, `max`, `length`, and `pattern`, and a `date` field enforces its `min` and `max`, with the same
+messages `defineFields` produces. A malformed `pattern` now fails at `fieldset()` call time, not on
+every save, the way `defineFields` already compiled patterns at declaration. The validator also reads a
+parsed value, not only a form string: a numeric `number` (a finite `0` included), a `Date` on a
+`datetime` field, the way the `date` field already coerced a parsed `Date`. A `multiselect` given a lone
+scalar (a single hand-edited `tags: news`) coerces it to a single-element list rather than dropping it
+or reporting a misleading "required".
+
+No consumer action is required. The `fieldset` surface is still additive and not yet wired into the
+adapter or editor, and the new behavior brings it in line with the long-standing `defineFields` checks.
+
+## 0.66.0
+
+<!-- release-size: minor -->
+
+Contract v2 begins with an additive `fields.*` field vocabulary, exported beside the existing
+`defineFields` model. The new surface is opt-in and does not yet wire into the adapter or editor, so a
+site on the current field model is unaffected.
+
+A concept can declare its fields as a record of `fields.*` constructors, each returning a plain-data
+descriptor. The scalars are `text`, `textarea`, `number`, `select`, `multiselect`, `url`, `email`,
+`date`, `datetime`, and `boolean`, with `image` as the rich leaf. `fieldset(record)` derives a
+server-side validator from those descriptors, returning field-keyed errors or normalized data, and
+exposes Standard Schema v1 at its boundary. `InferFieldset` reads the inferred frontmatter type from a
+fieldset, and `initialValues` resolves each field's `default` for the editor form, including the
+`'today'` sentinel on a date field through an injected clock. The new root-barrel exports are `fields`,
+`fieldset`, `initialValues`, and the types `FieldDescriptor`, `Fieldset`, `InferFieldset`,
+`FieldsetOptions`, and `BehaviorTable`.
+
+No consumer action is required. The vocabulary is a foundation; the contract-v2 cutover, a later
+breaking release, migrates concepts off `defineFields` and carries the "Consumers must:" line then.
+
+## 0.65.0
+
+<!-- release-size: minor -->
+
+Build-time syntax highlighting moves into the engine render pipeline, and the public side gains the
+Waymark design foundation in the showcase template (the scaffolder's Part B2).
+
+Fenced code is now highlighted at build time. The render pipeline runs Shiki at build and SSR and
+emits role-bound `.cairn-tok-*` token classes with no inline style and no client highlighter, so the
+reading route ships no highlighter JavaScript and the colors come from the site's theme. The engine
+owns the `.cairn-tok-*` class contract (the way it owns `.cairn-place-*` for figures); a site styles
+the classes from its own `--cairn-code-*` variables. Adds `shiki` and `hast-util-to-string` to the
+engine's dependencies.
+
+GFM task-list checkboxes now carry an `aria-label` from their item text, so a screen reader names the
+read-only control. This clears an axe `label` violation on every site while keeping the real disabled
+input the design calls for.
+
+No consumer action is required. A site gets highlighting automatically; to color the tokens, style the
+`.cairn-tok-*` classes from a `--cairn-code-*` ramp (the Waymark showcase template does this, bound to
+the DaisyUI roles). The broader Waymark design foundation (the oklch token layer, the bespoke reading
+surface, the chrome, the `/styleguide` route, and the dual-gamut contrast, token-resolution, and
+re-skin CI gates) ships in `examples/showcase`, the deployable starter, not the published engine.
+
+## 0.64.0
+
+<!-- release-size: minor -->
+
+A small pre-Part-B DX pass fixes two engine warts the scaffolder's template would otherwise bake in,
+and retires a third item that was already resolved.
+
+`readCommittedManifest`, exported from `/media`, reads a committed media manifest from an
+`import.meta.glob` result and degrades a missing file to an empty manifest. A fresh site with no
+`src/content/.cairn/media.json` no longer fails its build: the static import that crashed gives way to
+the glob, which returns `{}` for no match. The showcase reads its manifest this way.
+
+A new `media.resolver_absent` log event (level `warn`) makes a silently-broken public-image setup
+diagnosable. The public route emits it once, at construction, when media is configured on but no
+`resolveMedia` reached it, so a forgotten resolver wiring becomes a queryable Workers Logs event
+instead of a bare `media:` token on every hero image. `PublicRoutesDeps` gains an optional
+`assetsEnabled` flag a site threads from its resolved asset config.
+
+No consumer action is required. A site that wants the no-crash manifest read can adopt
+`readCommittedManifest`, and a site that wants the resolver diagnostic threads `assetsEnabled` into
+`createPublicRoutes`.
+
+## 0.63.0
+
+<!-- release-size: minor -->
+
+The local-development fake backend moves out of the engine and the showcase into a separate, dev-only
+package, `@glw907/cairn-cms-dev`, the first part of the `create-cairn-site` scaffolder. The package
+holds the in-memory GitHub, R2, D1, and Anthropic doubles and a blessed `devBackendHandle()` that
+installs them and an owner-session bypass, so a site runs `/admin` locally with no cloud accounts. A
+consumer installs it as a `devDependency` and activates it from `hooks.server.ts` behind a
+build-foldable `dev` gate, so a production build eliminates it from the bundle.
+
+The auth guard gains a fail-closed tripwire. If `CAIRN_DEV_BACKEND` is set in a deployed runtime, the
+guard refuses the request with a 503 and logs `guard.rejected` with `reason: "dev_backend_in_prod"`.
+It reads the flag from both the Worker `platform.env` and `process.env`, so it fires on Cloudflare and
+adapter-node alike. `AuthEnv` carries a new optional `CAIRN_DEV_BACKEND?: string | boolean` field for
+it.
+
+No consumer action is required. The tripwire fires only when the flag is set, and the new package is
+opt-in for sites that want the local dev backend.
+
 ## 0.62.2
 
 The edit-load address-collision advisory now checks the published corpus only. It fires when an entry

package/dist/ambient.d.ts

@@ -1,8 +1,10 @@
 import type { Editor } from './auth/types.js';
+import type { Backend } from './github/backend.js';
 declare global {
     namespace App {
         interface Locals {
             editor?: Editor | null;
+            backend?: Backend;
         }
     }
 }

package/dist/auth/types.d.ts

@@ -11,6 +11,13 @@ export interface AuthEnv {
     AUTH_DB?: D1Database;
     /** Canonical origin for confirmation links, never read from a request header (spec 7.1, risk H3). */
     PUBLIC_ORIGIN?: string;
+    /**
+     * Dev-backend tripwire flag. The dev backend sets this in local development; if it is ever set in
+     * a deployed runtime the guard refuses (the build-foldable `dev` gate should have eliminated the
+     * dev backend, so a set flag signals a polluted environment). A string from a Worker var or a
+     * boolean.
+     */
+    CAIRN_DEV_BACKEND?: string | boolean;
     /** Cloudflare Email Sending binding. */
     EMAIL?: {
         send(message: {

package/dist/components/CairnAdmin.svelte.d.ts

@@ -2,8 +2,7 @@ import type { AdminData } from '../sveltekit/cairn-admin.js';
 import type { ContentFormFailure } from '../sveltekit/content-routes.js';
 import type { ComponentRegistry } from '../render/registry.js';
 import type { IconSet } from '../render/glyph.js';
-import type { LinkResolve } from '../content/links.js';
-import type { MediaResolve } from '../render/resolve-media.js';
+import type { SiteRender } from '../content/types.js';
 interface Props {
     /** The discriminated view data from `createCairnAdmin`'s load. */
     data: AdminData;
@@ -16,11 +15,7 @@ interface Props {
         ok?: boolean;
     }) | null;
     /** The site's design-accurate render pipeline, for the edit view's preview pane. */
-    render?: (md: string, opts?: {
-        stagger?: boolean;
-        resolve?: LinkResolve;
-        resolveMedia?: MediaResolve;
-    }) => string | Promise<string>;
+    render?: SiteRender;
     /** The site's component registry, for the edit view's insert palette. */
     registry?: ComponentRegistry;
     /** The site's icon set, for the edit view's guided form fields. */

package/dist/components/ComponentForm.svelte

@@ -26,7 +26,7 @@ let working = $state(untrack(() => initial ?? previewValues(def)));
 $effect(() => {
   values = working;
 });
-const attributes = $derived(def.attributes ?? []);
+const attributes = $derived(Object.entries(def.attributes ?? {}));
 const flatSlots = $derived((def.slots ?? []).filter((s) => s.kind !== "repeatable"));
 const repeatableSlots = $derived((def.slots ?? []).filter((s) => s.kind === "repeatable"));
 function slotItems(name) {
@@ -59,7 +59,7 @@ function removeItem(name, index) {
 function rowLabel(slot, value, index) {
   const fallback = `${slot.label} ${index + 1}`;
   if (!slot.itemLabel) return fallback;
-  const key = slot.itemFields?.[0]?.key ?? "text";
+  const key = Object.keys(slot.itemFields ?? {})[0] ?? "text";
   const derived = slot.itemLabel({ [key]: value }, index);
   return derived && derived.trim() ? derived : fallback;
 }
@@ -74,10 +74,26 @@ function slotString(name) {
   const v = working.slots[name];
   return typeof v === "string" ? v : "";
 }
+function inputType(type) {
+  switch (type) {
+    case "number":
+      return "number";
+    case "date":
+      return "date";
+    case "datetime":
+      return "datetime-local";
+    case "url":
+      return "url";
+    case "email":
+      return "email";
+    default:
+      return "text";
+  }
+}
 const incompleteState = $derived.by(() => {
-  for (const field of attributes) {
+  for (const [name, field] of attributes) {
     if (!field.required || field.type === "boolean") continue;
-    if (asString(field.key) === "") return true;
+    if (asString(name) === "") return true;
   }
   for (const slot of def.slots ?? []) {
     if (!slot.required) continue;
@@ -97,9 +113,9 @@ function markTouched(key) {
 }
 const errors = $derived.by(() => {
   const out = {};
-  for (const field of attributes) {
-    if (field.required && field.type !== "boolean" && touched[field.key] && asString(field.key) === "") {
-      out[field.key] = `${field.label} is required.`;
+  for (const [name, field] of attributes) {
+    if (field.required && field.type !== "boolean" && touched[name] && asString(name) === "") {
+      out[name] = `${field.label} is required.`;
     }
   }
   for (const slot of def.slots ?? []) {
@@ -127,16 +143,16 @@ async function submit() {
 </script>
 
 <div class="flex flex-col gap-3" bind:this={formEl}>
-  {#each attributes as field (field.key)}
+  {#each attributes as [name, field] (name)}
     {#if field.type === 'boolean'}
       <label class="label cursor-pointer justify-start gap-2">
         <input
           class="checkbox checkbox-sm"
           type="checkbox"
-          aria-invalid={Boolean(errors[field.key])}
-          aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
-          checked={asBool(field.key)}
-          onchange={(e) => (working.attributes[field.key] = e.currentTarget.checked)}
+          aria-invalid={Boolean(errors[name])}
+          aria-describedby={errors[name] ? `err-${name}` : undefined}
+          checked={asBool(name)}
+          onchange={(e) => (working.attributes[name] = e.currentTarget.checked)}
         />
         <span class="text-sm">{field.label}</span>
       </label>
@@ -146,14 +162,14 @@ async function submit() {
         <select
           class="select"
           aria-required={field.required ? 'true' : undefined}
-          aria-invalid={Boolean(errors[field.key])}
-          aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
-          value={asString(field.key)}
+          aria-invalid={Boolean(errors[name])}
+          aria-describedby={errors[name] ? `err-${name}` : undefined}
+          value={asString(name)}
           onchange={(e) => {
-            working.attributes[field.key] = e.currentTarget.value;
-            markTouched(field.key);
+            working.attributes[name] = e.currentTarget.value;
+            markTouched(name);
           }}
-          onblur={() => markTouched(field.key)}
+          onblur={() => markTouched(name)}
         >
           {#if !field.required}<option value="">—</option>{/if}
           {#each field.options ?? [] as opt (opt)}<option value={opt}>{opt}</option>{/each}
@@ -165,9 +181,9 @@ async function submit() {
         <IconPicker
           {icons}
           label={field.label}
-          value={asString(field.key)}
+          value={asString(name)}
           required={field.required ?? false}
-          onChange={(name) => (working.attributes[field.key] = name)}
+          onChange={(glyph) => (working.attributes[name] = glyph)}
         />
       </div>
     {:else}
@@ -175,19 +191,20 @@ async function submit() {
         <span class="text-sm font-medium">{field.label}{#if field.required}<span data-testid="cairn-pk-req" class="text-error" aria-hidden="true">*</span>{/if}</span>
         <input
           class="input"
+          type={inputType(field.type)}
           aria-required={field.required ? 'true' : undefined}
-          aria-invalid={Boolean(errors[field.key])}
-          aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
-          value={asString(field.key)}
+          aria-invalid={Boolean(errors[name])}
+          aria-describedby={errors[name] ? `err-${name}` : undefined}
+          value={asString(name)}
           oninput={(e) => {
-            working.attributes[field.key] = e.currentTarget.value;
-            markTouched(field.key);
+            working.attributes[name] = e.currentTarget.value;
+            markTouched(name);
           }}
-          onblur={() => markTouched(field.key)}
+          onblur={() => markTouched(name)}
         />
       </label>
     {/if}
-    {#if errors[field.key]}<span id={`err-${field.key}`} role="alert" class="text-error text-xs">{errors[field.key]}</span>{/if}
+    {#if errors[name]}<span id={`err-${name}`} role="alert" class="text-error text-xs">{errors[name]}</span>{/if}
   {/each}
 
   {#each flatSlots as slot (slot.name)}

package/dist/components/ComponentInsertDialog.svelte

@@ -7,7 +7,7 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
 -->
 <script module lang="ts">const SEARCH_THRESHOLD = 8;
 export function hasSchema(def) {
-  return (def.attributes?.length ?? 0) > 0 || (def.slots?.length ?? 0) > 0;
+  return Object.keys(def.attributes ?? {}).length > 0 || (def.slots?.length ?? 0) > 0;
 }
 export function insertableDefs(registry) {
   return (registry?.defs ?? []).filter(
@@ -49,10 +49,10 @@ let previewDoc = $state("");
 const emptyRequired = $derived.by(() => {
   if (!picked || !formValues) return [];
   const out = [];
-  for (const field of picked.attributes ?? []) {
+  for (const [name, field] of Object.entries(picked.attributes ?? {})) {
     if (!field.required || field.type === "boolean") continue;
-    const v = formValues.attributes[field.key];
-    if (typeof v !== "string" || v === "") out.push(field.label);
+    const v = formValues.attributes[name];
+    if (typeof v !== "string" || v === "") out.push(field.label ?? name);
   }
   for (const slot of picked.slots ?? []) {
     if (!slot.required) continue;
@@ -75,7 +75,7 @@ $effect(() => {
   previewState = "settling";
   const handle = setTimeout(async () => {
     try {
-      const html = await render(md);
+      const html = await render({ body: md });
       if (run === previewRun) {
         previewDoc = buildPreviewDoc(html, preview);
         previewState = "settled";
@@ -197,11 +197,16 @@ function onSearchKeydown(e) {
 
 {#if defs.length > 0}
   <dialog class="modal" aria-labelledby="cairn-insert-dialog-title" bind:this={dialog} onclose={onClose} oncancel={onCancel}>
-    <div class="modal-box {twoPane ? 'max-w-3xl' : ''}">
+    <!-- The box caps at 85vh and is a flex column so its header holds while only the body scrolls,
+         per the design system's dialog-sizing recipe. The cap rides Tailwind utilities (the utilities
+         layer) so it beats DaisyUI's `.modal-box` max-height: 100vh; a components-layer rule loses the
+         cascade. overflow-hidden keeps the box from being a second scroll container. Matches TidyReview. -->
+    <div class="modal-box flex max-h-[85vh] flex-col overflow-hidden {twoPane ? 'max-w-3xl' : ''}">
       <!-- The shared header: at the configure step it carries the Back control and the
            "Insert > group" eyebrow breadcrumb above the component label; while browsing it is the
-           plain "Insert a component" title. -->
-      <div class="mb-3 flex items-center gap-3">
+           plain "Insert a component" title. It holds (flex-none) while the body scrolls, per the
+           design system's dialog-sizing recipe. -->
+      <div class="mb-3 flex flex-none items-center gap-3">
         {#if picked && !editing}
           <button type="button" class="btn btn-ghost btn-sm btn-square" aria-label="Back to components" onclick={back}>
             <svg class="h-4 w-4" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true"><path d="M165.7 202.3a8 8 0 0 1-11.4 11.4l-80-80a8 8 0 0 1 0-11.4l80-80a8 8 0 0 1 11.4 11.4L91.3 128Z" /></svg>
@@ -219,6 +224,9 @@ function onSearchKeydown(e) {
       </div>
 
       {#if picked}
+        <!-- The configure body is the box's scroll container (flex-1, min-h-0): the shared header
+             above holds while the form scrolls within the 85vh cap. -->
+        <div class="-mr-1 flex min-h-0 flex-1 flex-col overflow-y-auto pr-1">
         {#key picked}
           {#if twoPane}
             <!-- Two panes: the form on the left, the live preview on the right. Below the breakpoint
@@ -275,9 +283,10 @@ function onSearchKeydown(e) {
             {@render configureForm(picked)}
           {/if}
         {/key}
+        </div>
       {:else}
         {#if showSearch}
-          <div class="mb-3 flex items-center gap-2 rounded-field border border-[var(--cairn-card-border)] bg-base-100 px-3 py-2">
+          <div class="mb-3 flex flex-none items-center gap-2 rounded-field border border-[var(--cairn-card-border)] bg-base-100 px-3 py-2">
             <svg class="ec-glyph h-4 w-4 text-[var(--color-muted)]" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true"><path d="M229.7 218.3 179.6 168.2A92.2 92.2 0 1 0 168.2 179.6l50.1 50.1a8 8 0 0 0 11.4-11.4ZM40 112a72 72 0 1 1 72 72 72.1 72.1 0 0 1-72-72Z" /></svg>
             <input
               type="search"
@@ -301,8 +310,10 @@ function onSearchKeydown(e) {
             <button type="button" class="text-[0.8125rem] font-medium text-primary underline [text-underline-offset:2px]" onclick={() => (query = '')}>Clear search</button>
           </div>
         {:else}
-          <!-- One scroll region holds every group, so the arrow keys roam the whole catalog. -->
-          <div data-cairn-pk-list>
+          <!-- One scroll region holds every group, so the arrow keys roam the whole catalog. It
+               is the box's scroll container (flex-1, min-h-0): the header above holds while the
+               list scrolls within the 85vh cap. -->
+          <div data-cairn-pk-list class="-mr-1 min-h-0 flex-1 overflow-y-auto pr-1">
             {#each groups as group (group.heading)}
               <div class="mt-3 first:mt-0">
                 {#if group.heading}

package/dist/components/ComponentInsertDialog.svelte.d.ts

@@ -10,8 +10,7 @@ export declare function hasSchema(def: ComponentDef): boolean;
 export declare function insertableDefs(registry?: ComponentRegistry): ComponentDef[];
 import type { IconSet } from '../render/glyph.js';
 import type { ComponentValues } from '../render/registry.js';
-import type { ResolvedPreview } from '../content/types.js';
-import type { LinkResolve } from '../content/links.js';
+import type { ResolvedPreview, SiteRender } from '../content/types.js';
 interface Props {
     /** The site's component registry. */
     registry?: ComponentRegistry;
@@ -29,10 +28,7 @@ interface Props {
      *  `preview`, the configure step splits to two panes and renders the configured directive
      *  through this into a sandboxed iframe (the same path EditPage's preview uses). Optional: a
      *  host that passes none simply gets no preview pane. */
-    render?: (md: string, opts?: {
-        stagger?: boolean;
-        resolve?: LinkResolve;
-    }) => string | Promise<string>;
+    render?: SiteRender;
     /** The adapter's resolved preview knob (stylesheets and container class), threaded to
      *  buildPreviewDoc so the preview frame links the site's own CSS, the same as EditPage. */
     preview?: ResolvedPreview | null;

package/dist/components/ConceptList.svelte

@@ -120,6 +120,22 @@ const sortButton = `inline-flex items-center gap-1 ${headerLabel} hover:text-bas
 const publishedAllMessage = $derived(
   data.publishedAll !== null && data.publishedAll > 0 ? `Published ${data.publishedAll} ${data.publishedAll === 1 ? "entry" : "entries"}.` : ""
 );
+const lifecycleError = $derived(
+  deleteRefused ? `This ${data.label.toLowerCase()} could not be deleted. ${deleteRefused.inboundLinks.length} ${deleteRefused.inboundLinks.length === 1 ? "page links" : "pages link"} to it.` : data.formError ?? data.error ?? ""
+);
+let announceNonce = $state(0);
+function nonce() {
+  return announceNonce % 2 === 0 ? "" : "​";
+}
+let lastSubmit;
+$effect(() => {
+  const submit = form ?? data;
+  if (submit !== lastSubmit) {
+    lastSubmit = submit;
+    if (lifecycleError) announceNonce++;
+  }
+});
+const liveError = $derived(lifecycleError ? `${lifecycleError}${nonce()}` : "");
 </script>
 
 <!-- The non-color selected cue for the triage controls (WCAG 1.4.1): a small check glyph that
@@ -145,20 +161,25 @@ const publishedAllMessage = $derived(
      {#if}-gated role element inserted fresh is announced inconsistently, so the visible alert
      below keeps its styling without a role and the message is announced once. -->
 <div class="sr-only" aria-live="polite">{publishedAllMessage}</div>
+<!-- One persistent polite region announces the lifecycle errors, re-announcing a repeat through the
+     nonce. The visible alerts below keep their styling and drop the live `role` (a fresh-inserted
+     role element announces inconsistently and clobbers a repeat), so the message is announced once. -->
+<div class="sr-only" aria-live="polite">{liveError}</div>
 {#if publishedAllMessage}
   <div class="alert alert-success mb-4 text-sm">{publishedAllMessage}</div>
 {/if}
 {#if data.formError}
-  <div role="alert" class="alert alert-error mb-4 text-sm">{data.formError}</div>
+  <div class="alert alert-error mb-4 text-sm">{data.formError}</div>
 {/if}
 {#if data.error}
-  <div role="alert" class="alert alert-warning mb-4 text-sm">{data.error}</div>
+  <div class="alert alert-warning mb-4 text-sm">{data.error}</div>
 {/if}
 
 {#if deleteRefused}
   <!-- A `?/delete` was refused: name the blockers up front, matching the editor's refusal banner,
-       so the author sees why without re-opening a dialog. -->
-  <div role="alert" aria-label="This {data.label.toLowerCase()} could not be deleted" class="alert alert-error mb-4 flex-col items-start text-sm">
+       so the author sees why without re-opening a dialog. The polite region above announces it, so
+       the box itself carries no role or label (a bare div with an aria-label gets no accessible name). -->
+  <div class="alert alert-error mb-4 flex-col items-start text-sm">
     <p class="font-medium">This {data.label.toLowerCase()} could not be deleted.</p>
     <p>{deleteRefused.inboundLinks.length} {deleteRefused.inboundLinks.length === 1 ? 'page links' : 'pages link'} to it. Remove or repoint the {deleteRefused.inboundLinks.length === 1 ? 'link' : 'links'} listed below, then delete again.</p>
     <ul class="mt-1 w-full">