@glw907/cairn-cms 0.62.2 → 0.68.0

package/dist/media/manifest.js

@@ -13,6 +13,19 @@ export function parseMediaManifest(json) {
         return {};
     return json;
 }
+/**
+ * Read the committed media manifest from an `import.meta.glob` eager result, degrading a missing
+ *  file to an empty manifest. A static import of an absent `media.json` fails the Vite build before
+ *  any runtime degrade can run, so a fresh site with no manifest cannot build. A glob result is the
+ *  build-safe read: `import.meta.glob` returns `{}` when nothing matches rather than throwing, and
+ *  this helper extracts the single matched value and parses it, so a missing file reads a clean `{}`.
+ * @param globResult - The eager glob result for the committed manifest, an empty object when the
+ *  file is absent. The consumer passes
+ *  `import.meta.glob('<path-to-media.json>', { eager: true, import: 'default' })`.
+ */
+export function readCommittedManifest(globResult) {
+    return parseMediaManifest(Object.values(globResult)[0]);
+}
 /**
  * Validate one posted value as a MediaEntry, returning it narrowed or undefined. The trust boundary
  *  for an optimistic record the client re-posts: the upload action server-owned each field at

package/dist/render/highlight.d.ts

@@ -0,0 +1,9 @@
+import type { Root } from 'hast';
+/**
+ * The Shiki rehype plugin. Highlights every fenced-code block into a `<pre class="shiki">` whose
+ * tokens carry the cairn-tok-* classes (no inline style), then leaves the rest of the tree
+ * untouched. It runs as an async transformer because Shiki tokenizes asynchronously. Because the
+ * output is class-only it needs no special placement; it is safe anywhere after `remarkRehype`.
+ * @returns A unified transformer that mutates the hast tree in place.
+ */
+export declare function rehypeCairnHighlight(): (tree: Root) => Promise<void>;

package/dist/render/highlight.js

@@ -0,0 +1,206 @@
+import { toString } from 'hast-util-to-string';
+// The curated language set Shiki preloads. Each id pulls its aliases too (loading `bash` also
+// registers `sh`, `shell`, `zsh`; loading `js` registers `javascript`, `mjs`, `cjs`). A fence whose
+// language is absent or outside this set falls back to plaintext rather than throwing.
+const LANGS = [
+    'js',
+    'ts',
+    'jsx',
+    'tsx',
+    'svelte',
+    'html',
+    'css',
+    'json',
+    'bash',
+    'markdown',
+    'python',
+    'yaml',
+    'sql',
+];
+// The plaintext language id. Shiki special-cases it (and `plaintext`/`txt`/`ansi`) as always
+// available, so it is the safe fallback for an unknown or absent fence language: it escapes the
+// code text into the same <pre class="shiki"> wrapper with no token coloring.
+const PLAINTEXT = 'text';
+// Sentinel foreground colors, one per ramp slot. Shiki has no class-emitting mode, so the theme
+// assigns each scope group a unique sentinel hex, then the transformer below maps the resolved
+// sentinel back to its cairn-tok-* class and deletes the style. The sentinels never reach the
+// output. They are arbitrary distinct values; only their uniqueness and exact round-trip matter.
+const SENTINEL_INK = '#000000';
+const SENTINEL_TO_CLASS = {
+    '#000010': 'cairn-tok-comment',
+    '#000020': 'cairn-tok-keyword',
+    '#000030': 'cairn-tok-string',
+    '#000040': 'cairn-tok-function',
+    '#000050': 'cairn-tok-number',
+    '#000060': 'cairn-tok-punct',
+};
+// The Shiki theme that drives the class mapping. Every scope group resolves to its sentinel color;
+// the transformer turns the sentinel into a class. The background and default foreground are
+// sentinels too, stripped from the <pre> by the transformer so the site theme owns the surround.
+const CAIRN_CODE_THEME = {
+    name: 'cairn-roles',
+    type: 'light',
+    fg: SENTINEL_INK,
+    bg: '#ffffff',
+    settings: [
+        { settings: { foreground: SENTINEL_INK, background: '#ffffff' } },
+        {
+            scope: ['comment', 'punctuation.definition.comment', 'string.comment'],
+            settings: { foreground: '#000010' },
+        },
+        {
+            scope: [
+                'keyword',
+                'keyword.control',
+                'storage',
+                'storage.type',
+                'storage.modifier',
+                'variable.language',
+                'keyword.operator.new',
+                'keyword.operator.expression',
+            ],
+            settings: { foreground: '#000020' },
+        },
+        {
+            scope: ['string', 'string.quoted', 'string.template', 'constant.other.symbol'],
+            settings: { foreground: '#000030' },
+        },
+        {
+            scope: [
+                'entity.name.function',
+                'support.function',
+                'meta.function-call',
+                'entity.name.tag',
+                'support.type.property-name',
+            ],
+            settings: { foreground: '#000040' },
+        },
+        {
+            scope: [
+                'constant.numeric',
+                'constant.language',
+                'constant.character',
+                'constant.other',
+                'keyword.other.unit',
+            ],
+            settings: { foreground: '#000050' },
+        },
+        {
+            scope: ['punctuation', 'meta.brace', 'keyword.operator', 'meta.delimiter'],
+            settings: { foreground: '#000060' },
+        },
+    ],
+};
+// Read the `color:#rrggbb` hex out of a token span's inline style, lowercased for the sentinel map.
+function styleColor(style) {
+    if (typeof style !== 'string')
+        return undefined;
+    const match = /color:(#[0-9a-fA-F]{6})/.exec(style);
+    return match ? match[1].toLowerCase() : undefined;
+}
+// Append a class to a hast element's class list, building the string form Shiki uses.
+function addClass(node, className) {
+    const existing = node.properties?.class;
+    const prefix = typeof existing === 'string' && existing.length > 0 ? `${existing} ` : '';
+    (node.properties ??= {}).class = `${prefix}${className}`;
+}
+// The transformer that converts Shiki's sentinel-colored inline styles into the cairn-tok-* classes
+// and strips every style attribute, so the output is class-only. The <pre> loses its
+// background/foreground style (the site theme owns the surround); each token <span> trades its
+// sentinel color for the matching class, and a default-foreground span is left unclassed.
+const cairnTokenClasses = {
+    name: 'cairn-token-classes',
+    pre(node) {
+        if (node.properties)
+            delete node.properties.style;
+    },
+    code(node) {
+        if (node.properties)
+            delete node.properties.style;
+    },
+    span(node) {
+        const hex = styleColor(node.properties?.style);
+        if (node.properties)
+            delete node.properties.style;
+        const className = hex ? SENTINEL_TO_CLASS[hex] : undefined;
+        if (className)
+            addClass(node, className);
+    },
+};
+// The cached highlighter. Created once on first use and reused for every render. The dynamic import
+// keeps Shiki off the static client graph; the promise is cached so the WASM grammar load and the
+// theme registration happen at most once per process.
+let highlighterPromise;
+function getHighlighter() {
+    if (!highlighterPromise) {
+        highlighterPromise = import('shiki').then((shiki) => shiki.createHighlighter({ themes: [CAIRN_CODE_THEME], langs: [...LANGS] }));
+    }
+    return highlighterPromise;
+}
+// Read the fenced language off a <code> element's class list. Markdown emits the language as a
+// `language-<id>` class on the inner <code>. An empty or missing language returns undefined, which
+// the caller maps to plaintext.
+function codeLanguage(code) {
+    const className = code.properties?.className;
+    const classes = Array.isArray(className) ? className.map(String) : [];
+    const langClass = classes.find((c) => c.startsWith('language-'));
+    const lang = langClass?.slice('language-'.length);
+    return lang && lang.length > 0 ? lang : undefined;
+}
+// A fenced-code <pre> is a <pre> whose single element child is a <code>. Inline code (a bare <code>
+// with no <pre> parent) and any other <pre> are left untouched.
+function fencedCode(pre) {
+    const child = pre.children.find((c) => c.type === 'element');
+    return child?.tagName === 'code' ? child : undefined;
+}
+// Descend the tree and collect every fenced-code <pre>. The walk is synchronous and gathers the
+// targets up front, because the highlight itself is async (unist-util-visit cannot await).
+function collectFencedCode(node, jobs) {
+    for (const child of node.children) {
+        if (child.type !== 'element')
+            continue;
+        if (child.tagName === 'pre') {
+            const code = fencedCode(child);
+            if (code) {
+                jobs.push({ pre: child, code, lang: codeLanguage(code) ?? PLAINTEXT });
+                continue;
+            }
+        }
+        collectFencedCode(child, jobs);
+    }
+}
+/**
+ * The Shiki rehype plugin. Highlights every fenced-code block into a `<pre class="shiki">` whose
+ * tokens carry the cairn-tok-* classes (no inline style), then leaves the rest of the tree
+ * untouched. It runs as an async transformer because Shiki tokenizes asynchronously. Because the
+ * output is class-only it needs no special placement; it is safe anywhere after `remarkRehype`.
+ * @returns A unified transformer that mutates the hast tree in place.
+ */
+export function rehypeCairnHighlight() {
+    return async (tree) => {
+        const jobs = [];
+        collectFencedCode(tree, jobs);
+        if (jobs.length === 0)
+            return;
+        const highlighter = await getHighlighter();
+        const loaded = new Set(highlighter.getLoadedLanguages());
+        for (const job of jobs) {
+            // Fall back to plaintext for any language outside the preloaded set so Shiki never throws on
+            // an unknown fence. Plaintext still produces the <pre class="shiki"> wrapper with escaped text.
+            const lang = loaded.has(job.lang) ? job.lang : PLAINTEXT;
+            const result = highlighter.codeToHast(toString(job.code), {
+                lang,
+                theme: 'cairn-roles',
+                transformers: [cairnTokenClasses],
+            });
+            const pre = result.children.find((c) => c.type === 'element' && c.tagName === 'pre');
+            if (!pre)
+                continue;
+            // Rewrite the original <pre> into Shiki's <pre> in place: adopt its tag, properties, and
+            // children. Mutating the existing node avoids reindexing the parent's children array.
+            job.pre.tagName = pre.tagName;
+            job.pre.properties = pre.properties;
+            job.pre.children = pre.children;
+        }
+    };
+}

package/dist/render/pipeline.js

@@ -8,7 +8,8 @@ import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
 import rehypeSanitize from 'rehype-sanitize';
 import { VFile } from 'vfile';
-import { buildSanitizeSchema, rehypeAnchorRel, rehypeSinkGuard } from './sanitize-schema.js';
+import { buildSanitizeSchema, rehypeAnchorRel, rehypeSinkGuard, rehypeTaskListA11y } from './sanitize-schema.js';
+import { rehypeCairnHighlight } from './highlight.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
 import { remarkFigure } from './remark-figure.js';
 import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
@@ -40,6 +41,16 @@ export function createRenderer(registry = defineRegistry({ components: [] }), op
         ...floor,
         [rehypeDispatch, registry, options.stagger],
         rehypeSlug,
+        // Name each GFM task-list checkbox from its item text. It runs after the sanitize floor (which
+        // does not allow aria-label) so the added attribute survives, and is content-not-sink, so it is
+        // not gated by unsafeDisableSanitize.
+        rehypeTaskListA11y,
+        // Build-time syntax highlighting. It emits class-only output (the cairn-tok-* ramp, no inline
+        // style), so it is class-driven like the rest of the pipeline and needs no special placement
+        // relative to the sanitize floor or the sink guard: the token classes survive the floor because
+        // `className` is already allowed on `*`. It runs unconditionally (a code fence is content, not a
+        // sink) and ships no client highlighter (Shiki is build-only behind a dynamic import).
+        rehypeCairnHighlight,
     ];
     if (rel !== false)
         rehypePlugins.push([rehypeAnchorRel, rel]);

package/dist/render/registry.d.ts

@@ -78,7 +78,12 @@ export interface ComponentDef {
      *  result, so a build fn stays free of any motion concern.
      */
     build: (ctx: ComponentContext) => Element;
-    /** Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. */
+    /**
+     * Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. Maps a free-string role to a
+     *  glyph key in the site IconSet; choose a logically representative glyph and prefer glyphs
+     *  distinct across roles so the picker stays scannable. Overrides the engine
+     *  {@link DEFAULT_ICON_BY_ROLE} fallback for the roles it names.
+     */
     defaultIconByRole?: Record<string, string>;
     /** One line on when to reach for this component; feeds the picker and the reference file. */
     use?: string;
@@ -86,7 +91,10 @@ export interface ComponentDef {
     attributes?: AttributeField[];
     /** The named content regions this component accepts. */
     slots?: SlotDef[];
-    /** A glyph key from the site IconSet, shown beside the label in the picker. */
+    /**
+     * A glyph key from the site IconSet, shown beside the label in the picker. Choose a logically
+     *  representative glyph and prefer glyphs distinct across components so the picker stays scannable.
+     */
     icon?: string;
     /** A category heading for the picker. Components order by declaration within a group. */
     group?: string;

package/dist/render/registry.js

@@ -14,6 +14,19 @@ export function dataAttrProp(key) {
 function findIconField(def) {
     return def.attributes?.find((field) => field.type === 'icon');
 }
+/**
+ * The engine's role-to-glyph-key fallback for the conventional admonition roles, which a site's
+ *  IconSet may satisfy. A component's own {@link ComponentDef.defaultIconByRole} overrides it.
+ */
+const DEFAULT_ICON_BY_ROLE = {
+    note: 'info',
+    tip: 'lightbulb',
+    important: 'star',
+    warning: 'warning',
+    caution: 'alert-triangle',
+    info: 'info',
+    danger: 'flame',
+};
 /**
  * Build a registry from a site's component definitions. The single source the render
  * pipeline (directive stamp plus rehype dispatch) and the editor palette both read.
@@ -32,7 +45,14 @@ export function defineRegistry({ components }) {
         defs: components,
         names: components.map((c) => c.name),
         get: (name) => byName.get(name),
-        defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
+        defaultIcon: (name, role) => {
+            if (!role)
+                return undefined;
+            const def = byName.get(name);
+            if (!def || !findIconField(def))
+                return undefined;
+            return def.defaultIconByRole?.[role] ?? DEFAULT_ICON_BY_ROLE[role];
+        },
         iconField: (name) => {
             const def = byName.get(name);
             return def ? findIconField(def) : undefined;

package/dist/render/rehype-dispatch.d.ts

@@ -1,17 +1,13 @@
 import type { Root, Element, ElementContent } from 'hast';
 import { type ComponentContext, type ComponentRegistry } from './registry.js';
-/**
- *
- */
+/** Narrow a hast node to an Element, false for a text node, a comment, or undefined. */
 export declare function isElement(node: ElementContent | undefined): node is Element;
 /**
  * Read a declared string attribute off the component context, returning undefined for a boolean or
  *  absent value. Replaces the `typeof ctx.attributes[key] === 'string'` narrowing a build repeats.
  */
 export declare function strAttr(ctx: ComponentContext, key: string): string | undefined;
-/**
- *
- */
+/** Read a hast element property as a string, or undefined when it is absent or non-string. */
 export declare function strProp(node: Element, name: string): string | undefined;
 /** Wrap a pre-built glyph in an ec-icon span; secondary role adds the modifier. */
 export declare function iconSpan(glyphEl: Element, role?: string): Element;

package/dist/render/rehype-dispatch.js

@@ -1,8 +1,6 @@
 import { h } from 'hastscript';
 import { dataAttrProp } from './registry.js';
-/**
- *
- */
+/** Narrow a hast node to an Element, false for a text node, a comment, or undefined. */
 export function isElement(node) {
     return !!node && node.type === 'element';
 }
@@ -17,9 +15,7 @@ export function strAttr(ctx, key) {
 // hast Properties values are PropertyValue (string | number | boolean | array | null).
 // Directive markers (dataPrimitive/dataRole/dataAttr<Key>) are always stamped as strings;
 // this reads them back with that guarantee instead of casting at each call site.
-/**
- *
- */
+/** Read a hast element property as a string, or undefined when it is absent or non-string. */
 export function strProp(node, name) {
     const value = node.properties?.[name];
     return typeof value === 'string' ? value : undefined;

package/dist/render/sanitize-schema.d.ts

@@ -20,6 +20,16 @@ export declare function buildSanitizeSchema(registry: ComponentRegistry, extend?
  * `anchorRel` option (default `noopener noreferrer`); a site can override it or disable it entirely.
  */
 export declare function rehypeAnchorRel(rel: string): (tree: Root) => void;
+/**
+ * Give every GFM task-list checkbox an accessible name from its item text. remark-gfm emits a real
+ * `<input type="checkbox" disabled>` with no label, which axe's `label` rule flags as a critical
+ * violation even though the control is read-only; the visible label is the surrounding `<li>` text,
+ * not associated programmatically. This sets `aria-label` on each task-list checkbox to its item's
+ * text so the name travels with the control, keeping the engine's real disabled input (the bar's
+ * non-color cue) while clearing the violation on every site. It must run after the sanitize floor,
+ * which does not allow `aria-label`, so the attribute is added once the floor has run.
+ */
+export declare function rehypeTaskListA11y(): (tree: Root) => void;
 /**
  * Post-dispatch safety floor over the fully-built tree. The pre-dispatch rehype-sanitize floor
  * cleans author content, but a component build() runs after it and can route a raw author

package/dist/render/sanitize-schema.js

@@ -1,5 +1,6 @@
 import { defaultSchema } from 'hast-util-sanitize';
 import { visit } from 'unist-util-visit';
+import { toString } from 'hast-util-to-string';
 import { dataAttrProp } from './registry.js';
 // The fixed directive markers the stamp writes and the dispatch reads. They are inert data
 // attributes, never a script vector, and must survive the floor so the dispatch still runs.
@@ -58,6 +59,34 @@ export function rehypeAnchorRel(rel) {
         });
     };
 }
+/**
+ * Give every GFM task-list checkbox an accessible name from its item text. remark-gfm emits a real
+ * `<input type="checkbox" disabled>` with no label, which axe's `label` rule flags as a critical
+ * violation even though the control is read-only; the visible label is the surrounding `<li>` text,
+ * not associated programmatically. This sets `aria-label` on each task-list checkbox to its item's
+ * text so the name travels with the control, keeping the engine's real disabled input (the bar's
+ * non-color cue) while clearing the violation on every site. It must run after the sanitize floor,
+ * which does not allow `aria-label`, so the attribute is added once the floor has run.
+ */
+export function rehypeTaskListA11y() {
+    return (tree) => {
+        visit(tree, 'element', (node) => {
+            const className = node.properties?.className;
+            const isTaskItem = node.tagName === 'li' && Array.isArray(className) && className.includes('task-list-item');
+            if (!isTaskItem)
+                return;
+            const checkbox = node.children.find((child) => child.type === 'element' &&
+                child.tagName === 'input' &&
+                child.properties?.type === 'checkbox');
+            if (!checkbox)
+                return;
+            const label = toString(node).trim();
+            // Only when there is text to name it; an empty item leaves the box unnamed rather than blank.
+            if (label)
+                (checkbox.properties ??= {})['ariaLabel'] = label;
+        });
+    };
+}
 // URL-bearing hast properties the post-dispatch guard scheme-checks. hast camelCases attribute
 // names through property-information (srcset -> srcSet, xlink:href -> xLinkHref with a capital L,
 // formaction -> formAction). data is the <object data> URL attribute; data-* attributes camelCase

package/dist/sveltekit/guard.js

@@ -32,6 +32,16 @@ function isLocalHost(hostname) {
 export function createAuthGuard() {
     return async function handle({ event, resolve }) {
         const { pathname } = event.url;
+        // Fail closed if the dev-backend flag is set in a deployed runtime. Read both env sources: a
+        // Cloudflare Worker var lands on platform.env, an adapter-node OS var on process.env. A correct
+        // production build already eliminated the dev backend (the consumer gates it on the build-foldable
+        // `dev`), so a set flag signals a polluted environment; refuse loudly.
+        const platformFlag = event.platform?.env?.CAIRN_DEV_BACKEND;
+        const processFlag = typeof process !== 'undefined' ? process.env?.CAIRN_DEV_BACKEND : undefined;
+        if (platformFlag === '1' || platformFlag === true || processFlag === '1') {
+            log.error('guard.rejected', { reason: 'dev_backend_in_prod', path: pathname });
+            return new Response('cairn: the dev backend flag is set in a deployed environment. Unset CAIRN_DEV_BACKEND.', { status: 503 });
+        }
         // Rule 2 - non-admin: restore the framework's strict Origin check the consumer disabled when
         // they set checkOrigin: false to hand cairn the admin CSRF authority.
         if (!isAdminPath(pathname)) {

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.62.2",
+  "version": "0.68.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "sideEffects": [
     "**/*.svelte",
     "**/*.css"
@@ -34,15 +37,20 @@
     "check:docs": "node scripts/docs-links.mjs",
     "check:version": "node scripts/check-version.mjs",
     "check:prose": "node scripts/check-admin-prose.mjs",
+    "check:public-tokens": "node scripts/check-public-tokens.mjs",
+    "test:reskin": "node scripts/reskin-fixture.mjs",
     "lint": "eslint src/lib",
     "check:comments": "bash scripts/check-comments.sh",
+    "check:dev-package": "node scripts/check-dev-package.mjs",
     "prepare": "npm run package",
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:unit": "vitest run --project unit",
     "test:integration": "vitest run --project integration",
-    "test:component": "vitest run --project component"
+    "test:component": "vitest run --project component",
+    "emit-template": "node scripts/emit-template.mjs",
+    "test:emit": "node --test scripts/emit-template.test.mjs"
   },
   "exports": {
     ".": {
@@ -131,6 +139,7 @@
     "codemirror": "^6.0.2",
     "gray-matter": "^4",
     "hast-util-sanitize": "^5.0.2",
+    "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",
     "heic-to": "^1.5.2",
     "mdast-util-directive": "^3.1.0",
@@ -143,6 +152,7 @@
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "remark-stringify": "^11.0.0",
+    "shiki": "^4.3.0",
     "spellchecker-wasm": "^0.3.3",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
@@ -159,6 +169,7 @@
     "@types/node": "^22.19.19",
     "@vitest/browser": "^4.1.7",
     "@vitest/browser-playwright": "^4.1.7",
+    "culori": "^4.0.2",
     "daisyui": "^5.5.23",
     "eslint": "^9.39.4",
     "eslint-plugin-jsdoc": "^63.0.7",

package/src/lib/auth/types.ts

@@ -14,6 +14,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/src/lib/components/ComponentInsertDialog.svelte

@@ -317,11 +317,16 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
 
 {#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>
@@ -339,6 +344,9 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
       </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
@@ -395,9 +403,10 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
             {@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"
@@ -421,8 +430,10 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
             <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/src/lib/components/ConceptList.svelte

@@ -200,6 +200,38 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
       ? `Published ${data.publishedAll} ${data.publishedAll === 1 ? 'entry' : 'entries'}.`
       : '',
   );
+
+  // The one lifecycle error to announce (the visible alerts below keep their own styling). A blocked
+  // delete leads, then a form error, then a load error, since the refusal is the most recent and most
+  // actionable outcome of the last submit. The refusal announcement carries the blocker count, so a
+  // screen reader hears the magnitude (matching the visible banner) before navigating to the list.
+  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 ?? ''),
+  );
+
+  // The polite live region's text re-announces only when it changes, so a repeated identical error
+  // (a second submit failing the same way) would go silent. An invisible nonce flips on every fresh
+  // error so the region text always mutates and the screen reader speaks again (the MediaPicker
+  // discipline). The nonce is a zero-width space, never voiced, so the heard sentence is unchanged.
+  let announceNonce = $state(0);
+  function nonce(): string {
+    return announceNonce % 2 === 0 ? '' : '​';
+  }
+  // Each submit hands a fresh `form` (or `data` on a load) object, so the nonce bumps once per submit,
+  // keying the re-announce to the submit rather than to a string change the live region would swallow.
+  // The guard reads a plain non-reactive `lastSubmit`, so the bump fires only when the submit identity
+  // changes, never on the re-render the bump itself causes; that is what keeps the effect from looping.
+  let lastSubmit: unknown;
+  $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
@@ -225,20 +257,25 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
      {#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">