@glw907/cairn-cms 0.55.0 → 0.56.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 0.56.0
+
+Two passes ship together: the markdown editor's folding gets a proper home, and the engine's gates,
+tooling, and docs harden.
+
+The editor folds directive containers (`:::name` blocks), and the fold control now lives in a real
+gutter column to the left of the text rather than a chevron hidden in the line. At rest the gutter is
+empty; the chevron reveals when you hover the gutter cell, stays while a block is folded, and shows
+while the caret is inside a block. The control is a real button now, so folding is reachable by
+keyboard and screen reader, where before only unfolding was. The folded-row tint and the "N lines"
+pill carry over unchanged, and the fold scope is the same: directive containers only.
+
+For consumers, two additive surface touches from the tooling pass. A concept can now set an optional
+`singular` label, so the create affordances read "New post" instead of "New Posts"; it defaults to the
+concept's `label`, so a concept that sets nothing is unchanged. And `AuthEnv` is now exported from
+`@glw907/cairn-cms/sveltekit` as well as the root, so the `app.d.ts` Platform block can import it from
+the subpath the auth helpers live on (the deploy guide now shows that block verbatim).
+
+The rest hardens the engine's own gates and docs. A new `check:reference:signatures` gate compares
+each reference page's declared type signature against the export's real type, so a stale signature in
+an existing page is caught (it found and fixed two on its first run). A plain-Node dist-spawn test
+rot-proofs the `/delivery/data` node-safety guarantee, an admin-shell DOM check guards the drawer
+layout against a silent scoping regression, and the `cairn-manifest` bin now resolves the Vite root
+from the loaded config rather than the current directory. A docs sweep documents the preview frame's
+dual stylesheet emission, the `cairnManifest`-derived `cairn-doctor` inputs, the prerender policy for
+the feed routes, and an interim security contact.
+
+No consumer action: every change is additive, the `singular` field is optional, and the folding
+redesign is internal to the admin editor.
+
 ## 0.55.0
 
 The office list rises to the gold standard. The post and page list gains a triage filter layer and

package/dist/components/ConceptList.svelte

@@ -183,6 +183,10 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
   });
   const derivedSlug = $derived(slugEdited ? slug : slugify(title));
   const slugPlaceholder = $derived(data.dated ? 'my-entry' : 'about-us');
+  // The create affordances name one new item, so they read in the singular ("New post"). The
+  // descriptor resolves `singular` (defaulting it to the label), so the fallback here only guards an
+  // older caller that ships no `singular` on its ListData.
+  const createNoun = $derived(data.singular ?? data.label);
 
   // Shared column-header typography: small uppercase muted labels. The sort buttons add their own
   // flex layout and a hover affordance on top of this.
@@ -212,7 +216,7 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
       <input type="search" aria-label="Search {data.label}" bind:value={query} placeholder="Search {data.label.toLowerCase()}" oninput={() => (page = 1)} />
     </label>
     <button type="button" class="btn btn-primary btn-sm shrink-0" aria-haspopup="dialog" onclick={() => createDialog?.showModal()}>
-      <PlusIcon class="h-4 w-4" /> New {data.label}
+      <PlusIcon class="h-4 w-4" /> New {createNoun}
     </button>
   </div>
 </header>
@@ -280,7 +284,7 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
       <p class="text-sm text-[var(--color-muted)]">Stack your first one and it will show up here.</p>
     </div>
     <button type="button" class="btn btn-primary btn-sm" aria-haspopup="dialog" onclick={() => createDialog?.showModal()}>
-      <PlusIcon class="h-4 w-4" /> New {data.label}
+      <PlusIcon class="h-4 w-4" /> New {createNoun}
     </button>
   </div>
 {:else}
@@ -367,7 +371,7 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
            short list always shows its next step rather than just stopping. Same action as the
            header New button. -->
       <button type="button" class="flex w-full items-center gap-2 border-t border-[var(--cairn-card-border)] px-6 py-3 text-sm font-medium text-primary hover:bg-primary/[0.06]" aria-haspopup="dialog" onclick={() => createDialog?.showModal()}>
-        <PlusIcon class="h-4 w-4" /> New {data.label}
+        <PlusIcon class="h-4 w-4" /> New {createNoun}
       </button>
     {/if}
   </div>
@@ -399,7 +403,7 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
 <dialog class="modal" aria-labelledby="cairn-create-dialog-title" bind:this={createDialog}>
   <div class="modal-box">
     <div class="mb-3 flex items-center justify-between">
-      <h2 id="cairn-create-dialog-title" class="text-base font-semibold">New {data.label}</h2>
+      <h2 id="cairn-create-dialog-title" class="text-base font-semibold">New {createNoun}</h2>
       <button type="button" class="btn btn-ghost btn-sm" aria-label="Close" onclick={() => createDialog?.close()}>✕</button>
     </div>
     <form method="POST" action="?/create" onsubmit={() => (creating = true)} class="flex flex-col gap-3">

package/dist/components/MarkdownEditor.svelte

@@ -100,23 +100,20 @@ through the adapter's render. Swapping the editor stays a one-file change.
       `color-mix(in oklab, var(--color-accent) var(--cairn-directive-rail-${step}, ${fallback}), transparent)`;
     // With `active`, the row's own (deepest) bar takes the full-strength -active mix at the same
     // 2px width. The emphasis is strength only: a rail column carrying both an active and a
-    // quiet segment (two sibling containers at one depth) keeps one weight top to bottom.
-    // With `dropInnermost`, the row's own deepest bar is omitted: a fold chevron replaces it on a
-    // paired opener row, so the bar would double the chevron's positional cue. The outer bars and
-    // their spacers stay, so the nesting still reads.
-    const rails = (depth: number, active = false, dropInnermost = false): string => {
+    // quiet segment (two sibling containers at one depth) keeps one weight top to bottom. A paired
+    // opener row paints its full rail like any other fence row; the fold chevron lives in the gutter
+    // column left of the rails, so the opener no longer drops its innermost bar.
+    const rails = (depth: number, active = false): string => {
       const layers: string[] = [];
       for (let d = 1; d <= depth; d++) {
         const edge = 8 * d - 6;
         if (d > 1) layers.push(`inset ${edge - 2}px 0 0 0 var(--color-base-100, oklch(99% 0.004 75))`);
-        if (dropInnermost && d === depth) continue;
         const own = active && d === depth;
         layers.push(
           `inset ${edge}px 0 0 0 ${own ? railColor('active', '100%') : railColor(d, railFallbacks[d - 1] ?? '92%')}`,
         );
       }
-      // A depth-1 opener drops its only bar, so the row paints no rail at all.
-      return layers.length ? layers.join(', ') : 'none';
+      return layers.join(', ');
     };
     const directiveInk = {
       backgroundColor: 'color-mix(in oklab, var(--color-accent) 8%, transparent)',
@@ -132,14 +129,6 @@ through the adapter's render. Swapping the editor stays a one-file change.
         `${prefix}.cm-cairn-directive-fence.cm-cairn-depth-${depth}, ${prefix}.cm-cairn-directive-content.cm-cairn-depth-${depth}`;
       railRules[row('')] = { boxShadow: rails(depth) };
       railRules[row('.cm-cairn-caret-block')] = { boxShadow: rails(depth, true) };
-      // A paired opener row drops its own innermost bar (the fold chevron stands in its place),
-      // both quiet and caret-active. The extra opener class outranks the base fence rule above.
-      railRules[`.cm-cairn-directive-fence.cm-cairn-directive-opener.cm-cairn-depth-${depth}`] = {
-        boxShadow: rails(depth, false, true),
-      };
-      railRules[`.cm-cairn-caret-block.cm-cairn-directive-opener.cm-cairn-depth-${depth}`] = {
-        boxShadow: rails(depth, true, true),
-      };
     }
     const theme = EditorView.theme(
       {
@@ -199,39 +188,67 @@ through the adapter's render. Swapping the editor stays a one-file change.
         },
         '.cm-cairn-directive-leaf': directiveInk,
         '.cm-cairn-directive-inline': directiveInk,
-        // Container folding. The fold band is the 28px gutter click target on an opener row; the
-        // line is the positioning context so the chevron sits over the container's own bar x. The
-        // band is laid over the gutter (a zero-width inline widget at line start, expanded by the
-        // absolute children), so only the gutter shows the pointer cursor, never the opener text.
-        '.cm-line:has(.cm-cairn-fold-band)': { position: 'relative' },
-        '.cm-cairn-fold-band': {
-          position: 'absolute',
-          left: '0',
-          top: '0',
-          width: '28px',
-          height: '100%',
+        // Container folding lives in a real gutter column now, not an in-text band. The gutter is a
+        // fixed-x column left of the content; the chevron is empty at rest and reveals on hovering
+        // the gutter cell (the VS Code / Zed / Obsidian standard), forced on when folded or when the
+        // caret is inside the container. One rotating chevron in the directive ink; the rails carry
+        // depth, so the ink does not restep. The lone gutter's wrapper loses its default background
+        // and border so the column blends into the quiet surface.
+        // Neutralize the gutter wrapper so the column blends in. This assumes the fold gutter is the
+        // only gutter (it is today: no lineNumbers or foldGutter in the build); a future line-number
+        // or lint gutter would need its own chrome and a narrower selector here.
+        '.cm-gutters': { backgroundColor: 'transparent', border: '0', color: 'inherit' },
+        // 24px wide so the cell clears the WCAG 2.5.8 target-size floor unconditionally.
+        '.cm-cairn-fold-gutter': { width: '24px' },
+        '.cm-cairn-fold-gutter .cm-gutterElement': { display: 'flex', alignItems: 'stretch', padding: '0' },
+        '.cm-cairn-fold-btn': {
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          width: '100%',
+          padding: '0',
+          background: 'transparent',
+          border: '0',
           cursor: 'pointer',
-          zIndex: '1',
+          color: 'var(--cairn-directive-ink-2, oklch(50% 0.16 300))',
         },
-        '.cm-cairn-fold-band svg': {
-          position: 'absolute',
-          top: '50%',
-          transform: 'translateY(-50%)',
+        '.cm-cairn-fold-btn svg': {
           width: '11px',
           height: '11px',
-          // The chevron fades in on rail-band hover; folded and caret-inside states force it on.
+          // Empty at rest; the gutter-cell hover, the folded state, and the caret-active state each
+          // force it on. A 120ms fade in and out, and a 120ms rotate for the folded turn.
           opacity: '0',
-          transition: 'opacity 120ms ease',
-          color: 'var(--cairn-directive-ink-2, oklch(50% 0.16 300))',
+          transition: 'opacity 120ms ease, transform 120ms ease',
+        },
+        // Reveal on gutter-cell hover, on the folded and caret-active states, and on keyboard focus
+        // so a focused control shows its glyph, not just the ring.
+        '.cm-cairn-fold-gutter .cm-gutterElement:hover .cm-cairn-fold-btn svg, .cm-cairn-fold-btn:focus-visible svg, .cm-cairn-fold-folded svg, .cm-cairn-fold-active svg':
+          { opacity: '1' },
+        // Folded rotates the single chevron to point right; caret-active takes the stronger ink.
+        '.cm-cairn-fold-folded svg': { transform: 'rotate(-90deg)' },
+        '.cm-cairn-fold-active': { color: 'var(--cairn-directive-ink-active, oklch(46% 0.16 300))' },
+        // A visible focus ring for keyboard users landing on the gutter button or the pill, reusing
+        // the surface hairline's 70% primary mix (3:1+ non-text contrast on both themes).
+        '.cm-cairn-fold-btn:focus-visible': {
+          outline: '2px solid color-mix(in oklab, var(--color-primary) 70%, transparent)',
+          outlineOffset: '-2px',
+          borderRadius: '4px',
+        },
+        '.cm-cairn-fold-pill:focus-visible': {
+          outline: '2px solid color-mix(in oklab, var(--color-primary) 70%, transparent)',
+          outlineOffset: '1px',
+        },
+        // No-hover pointers (touch) cannot reveal on hover, so the rest-state chevron is persistent
+        // and legible. Scoped to the rest state (not folded, not caret-active) so those forced-on
+        // states still read at full strength on touch rather than this rule clamping them to 0.65.
+        '@media (hover: none)': {
+          '.cm-cairn-fold-btn:not(.cm-cairn-fold-folded):not(.cm-cairn-fold-active) svg': { opacity: '0.65' },
         },
-        '.cm-cairn-fold-band:hover svg, .cm-cairn-fold-folded svg, .cm-cairn-fold-active svg': {
-          opacity: '1',
+        // Respect a reduced-motion preference: drop the chevron fade/rotate and the unfold flash.
+        '@media (prefers-reduced-motion: reduce)': {
+          '.cm-cairn-fold-btn svg': { transition: 'none' },
+          '.cm-cairn-fold-flash': { transition: 'none' },
         },
-        // The chevron steps its ink with the container's depth, matching the label inks; the
-        // caret-inside state takes the strongest ink.
-        '.cm-cairn-fold-depth-1 svg': { color: 'var(--color-accent)' },
-        '.cm-cairn-fold-depth-3 svg': { color: 'var(--cairn-directive-ink-3, oklch(48% 0.16 300))' },
-        '.cm-cairn-fold-active svg': { color: 'var(--cairn-directive-ink-active, oklch(46% 0.16 300))' },
         // The folded-row wash: a soft accent tint, square and full-row, returning as a STATE signal
         // so folded spots read in a scan. The rails are inset box-shadows on the same line element
         // and render above this background, so the rail column runs through the wash unbroken.
@@ -274,9 +291,11 @@ through the adapter's render. Swapping the editor stays a one-file change.
           color: 'var(--cairn-focus-dim-ink, oklch(66% 0.01 75))',
           backgroundColor: 'transparent',
         },
-        // The fold machinery dims with its row: a folded opener row under focus mode drops its
-        // chevron, pill, and wash to the dim tone like any other machinery line.
-        '.cm-cairn-focus-dim .cm-cairn-fold-band svg, .cm-cairn-focus-dim .cm-cairn-fold-pill': {
+        // The fold pill dims with its folded opener row like any machinery line (the pill is a
+        // widget inside the line). The gutter chevron lives in a separate DOM column that focus-dim
+        // cannot reach by descendant selector, and it is already hidden at rest and forced visible
+        // only when folded or caret-active, so a folded chevron stays findable without a dim rule.
+        '.cm-cairn-focus-dim .cm-cairn-fold-pill': {
           color: 'var(--cairn-focus-dim-ink, oklch(66% 0.01 75))',
         },
         '.cm-cairn-focus-dim.cm-cairn-folded-row': { backgroundColor: 'transparent' },

package/dist/components/editor-folding.d.ts

@@ -1,7 +1,8 @@
 import { type Extension } from '@codemirror/state';
 /**
- * The cairn fold extension: the CodeMirror fold system with the pill placeholder, the chevron and
- * wash affordance, the safety invariant, and the Ctrl+Shift+[ / ] keymap. Session-local and never
- * persisted: the fold state lives in CodeMirror's foldState field, which this never serializes.
+ * The cairn fold extension: the CodeMirror fold system with the pill placeholder, the gutter chevron
+ * and folded-row wash affordance, the safety invariant, and the Ctrl+Shift+[ / ] keymap.
+ * Session-local and never persisted: the fold state lives in CodeMirror's foldState field, which
+ * this never serializes.
  */
 export declare function cairnFolding(): Extension;

package/dist/components/editor-folding.js

@@ -1,29 +1,25 @@
-// Container folding: CodeMirror's fold system driven by cairn's directive grammar, with the rail
-// band as the affordance. Client-only like editor-highlight and editor-modes; MarkdownEditor
+// Container folding: CodeMirror's fold system driven by cairn's directive grammar, with a real
+// gutter column as the affordance. Client-only like editor-highlight and editor-modes; MarkdownEditor
 // reaches this module through a dynamic import, so the static @codemirror imports here never enter
 // a server bundle (guarded by the editor-boundary test).
 //
-// The architecture (plan decision 4): @codemirror/language's codeFolding plus foldEffect/
+// The architecture (spec 2026-06-14): @codemirror/language's codeFolding plus foldEffect/
 // unfoldEffect, never a custom fold store. Fold ranges come only from containerRanges, the pure
 // pairing helper beside fenceScan. The safety invariant lives in one transactionExtender that
-// appends unfold effects when a change or selection touches a folded range. The chevrons are
-// widget decorations from this module's own ViewPlugin (the rails are box-shadows, there is no CM
-// gutter element to hang a foldGutter on).
+// appends unfold effects when a change or selection touches a folded range. The control is a custom
+// gutter() whose GutterMarker is a focusable button on each paired-opener row; a lower-level
+// gutter (not foldGutter) is what lets the caret-inside state stay live, since its lineMarkerChange
+// recomputes on selection changes.
 //
 // The safety invariant: an author never edits, deletes, or fails to see hidden text.
-import { Decoration, EditorView, ViewPlugin, WidgetType, keymap, } from '@codemirror/view';
+import { Decoration, EditorView, GutterMarker, ViewPlugin, gutter, keymap, } from '@codemirror/view';
 import { EditorState, Prec, RangeSetBuilder, StateEffect, StateField } from '@codemirror/state';
 import { codeFolding, foldEffect, foldedRanges, unfoldEffect } from '@codemirror/language';
 import { caretContainerRange, containerRanges, fenceScan } from './markdown-directives.js';
-// Deeper nesting shares the third visual step, matching the rail stepping in editor-highlight.
-const DEPTH_STEPS = 3;
-// The chevron sits over the container's own innermost bar: depth 1 at x0, depth 2 at x8, depth 3
-// at x16, so indentation telegraphs the nesting and depth 3 never collides with depth 2.
-const chevronX = (depth) => (Math.min(depth, DEPTH_STEPS) - 1) * 8;
-// The two chevron glyphs from the gold-standard mockup: down (caret inside) and right (folded).
+// One chevron glyph; CSS rotates it (down open, right folded) and reveals it on gutter hover. The
+// gutter is the fixed-x home, so the chevron no longer encodes depth by position.
 const CHEVRON_DOWN = 'm6 9 6 6 6-6';
-const CHEVRON_RIGHT = 'm9 6 6 6-6 6';
-function chevronSvg(direction) {
+function chevronSvg() {
     const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
     svg.setAttribute('viewBox', '0 0 24 24');
     svg.setAttribute('fill', 'none');
@@ -33,55 +29,10 @@ function chevronSvg(direction) {
     svg.setAttribute('stroke-linejoin', 'round');
     svg.setAttribute('aria-hidden', 'true');
     const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
-    path.setAttribute('d', direction === 'down' ? CHEVRON_DOWN : CHEVRON_RIGHT);
+    path.setAttribute('d', CHEVRON_DOWN);
     svg.appendChild(path);
     return svg;
 }
-// The opener-row band: the whole 28px gutter is the click target (cursor pointer over the band
-// only, the opener text never folds), and the chevron lives inside it at the container's bar x.
-// The widget knows its own container and whether it is folded, so the click toggles the right
-// range; the depth class lets the theme step the chevron ink.
-class FoldBandWidget extends WidgetType {
-    range;
-    folded;
-    caretInside;
-    constructor(range, folded, caretInside) {
-        super();
-        this.range = range;
-        this.folded = folded;
-        this.caretInside = caretInside;
-    }
-    eq(other) {
-        return (other.range.fromLine === this.range.fromLine &&
-            other.range.toLine === this.range.toLine &&
-            other.range.depth === this.range.depth &&
-            other.folded === this.folded &&
-            other.caretInside === this.caretInside);
-    }
-    toDOM(view) {
-        const band = document.createElement('span');
-        const depth = Math.min(this.range.depth, DEPTH_STEPS);
-        // Folded rows always show the chevron (right); an open container shows it down while the caret
-        // is inside; otherwise it fades in on rail-band hover (the band's own :hover, in the theme).
-        // The depth class carries the stepped ink.
-        const state = this.folded ? ' cm-cairn-fold-folded' : this.caretInside ? ' cm-cairn-fold-active' : '';
-        band.className = `cm-cairn-fold-band cm-cairn-fold-depth-${depth}${state}`;
-        const chevron = chevronSvg(this.folded ? 'right' : 'down');
-        chevron.style.left = `${chevronX(this.range.depth)}px`;
-        band.appendChild(chevron);
-        band.addEventListener('mousedown', (e) => {
-            // mousedown, not click: a click would first move the caret into the line. preventDefault
-            // keeps the caret where it is and stops the band from stealing focus from the editor.
-            e.preventDefault();
-            e.stopPropagation();
-            toggleFold(view, this.range);
-        });
-        return band;
-    }
-    ignoreEvent() {
-        return false;
-    }
-}
 // The pill placeholder: a real focusable button counting the hidden lines, the screen-reader story
 // for a fold. preparePlaceholder computes the count off the folded char range so placeholderDOM
 // renders it without re-deriving. Clicking unfolds through CodeMirror's own onclick handler.
@@ -99,8 +50,7 @@ function placeholderDOM(view, onclick, lines) {
 }
 // The char range a container folds: end-of-opener-line to end-of-closer-line, so the bare closer
 // never dangles. Null when the opener and closer share a line (nothing to hide). The one place
-// that turns a line range into the fold range, shared by the toggle, the keymap, and the
-// decoration build.
+// that turns a line range into the fold range, shared by the toggle, the keymap, and the gutter.
 function foldCharRange(state, range) {
     const opener = state.doc.line(range.fromLine + 1);
     const closer = state.doc.line(range.toLine + 1);
@@ -129,20 +79,44 @@ function foldExists(state, from, to) {
 // returns the nearest enclosing container, but a container that never closes (an unbalanced
 // opener) must not fold, so the result is only honored when containerRanges actually pairs it.
 function caretFoldRange(view) {
-    const scan = fenceScan(docLines(view));
+    const { scan, ranges } = foldScanFor(view.state);
     const caretLine = view.state.doc.lineAt(view.state.selection.main.head).number - 1;
     const inner = caretContainerRange(scan, caretLine);
     if (!inner)
         return null;
-    return (containerRanges(scan).find((r) => r.fromLine === inner.fromLine && r.toLine === inner.toLine) ?? null);
+    return ranges.find((r) => r.fromLine === inner.fromLine && r.toLine === inner.toLine) ?? null;
 }
-function docLines(view) {
-    const doc = view.state.doc;
+function docLines(state) {
     const lines = [];
-    for (let n = 1; n <= doc.lines; n++)
-        lines.push(doc.line(n).text);
+    for (let n = 1; n <= state.doc.lines; n++)
+        lines.push(state.doc.line(n).text);
     return lines;
 }
+// The scan and its paired ranges, memoized per state so the gutter's per-line lookups stay linear
+// rather than rescanning the whole document on every line.
+const scanCache = new WeakMap();
+function foldScanFor(state) {
+    let cached = scanCache.get(state);
+    if (!cached) {
+        const scan = fenceScan(docLines(state));
+        cached = { scan, ranges: containerRanges(scan) };
+        scanCache.set(state, cached);
+    }
+    return cached;
+}
+// The paired container whose opener sits at this line start, or null (a closer, a prose line, or an
+// unbalanced opener gets nothing). The sole source of which rows carry a fold control.
+function openerRangeAt(state, lineFrom) {
+    const lineIndex = state.doc.lineAt(lineFrom).number - 1;
+    return foldScanFor(state).ranges.find((r) => r.fromLine === lineIndex) ?? null;
+}
+// Whether the caret's innermost container is exactly this one, the caret-inside active state.
+function caretInside(state, range) {
+    const { scan } = foldScanFor(state);
+    const caretLine = state.doc.lineAt(state.selection.main.head).number - 1;
+    const inner = caretContainerRange(scan, caretLine);
+    return !!inner && inner.fromLine === range.fromLine && inner.toLine === range.toLine;
+}
 // The keymap: Ctrl+Shift+[ folds, Ctrl+Shift+] unfolds, the innermost container at the caret. No
 // fold-all, no chords. (CodeMirror's own foldKeymap binds the same keys to its tree-folding
 // commands; this module replaces them with the container-aware versions and never adds foldKeymap.)
@@ -242,31 +216,23 @@ function safetyExtender() {
         return effects.length ? { effects } : null;
     });
 }
-// The chevron-and-wash plugin: a widget on each opener row of a paired container (the band with
-// the chevron) and the folded-row wash line decoration. Rebuilds on doc change (the container set
-// moves), selection change (the caret-inside chevron state), viewport change, and any fold change
-// (a fold flips a chevron and adds a wash). The hover reveal is the band's own CSS :hover in the
-// theme, so it costs no rebuild.
-function foldDecorations(view, scan, ranges) {
+// The folded-row wash plugin: a line decoration on each folded opener row, square and full-row so
+// folded spots read in a scan. Rebuilds on doc change (the container set moves), viewport change,
+// and any fold change (a fold adds a wash, an unfold removes it). The chevron lives in the gutter
+// now, not here; this plugin carries only the wash and the unfold flash scheduling.
+function foldDecorations(view, ranges) {
     const builder = new RangeSetBuilder();
-    const caretLine = view.state.doc.lineAt(view.state.selection.main.head).number - 1;
-    const inner = caretContainerRange(scan, caretLine);
-    // One opener row may host several enclosing containers' bars, but only its OWN container opens
-    // there, so a single band per opener row. Sort by opener line so the builder receives ascending
-    // positions; equal openers cannot happen (one open per line).
+    // Sort by opener line so the builder receives ascending positions; equal openers cannot happen
+    // (one open per line).
     const byOpener = [...ranges].sort((a, b) => a.fromLine - b.fromLine);
     for (const range of byOpener) {
         const span = foldCharRange(view.state, range);
         if (!span)
             continue;
         const opener = view.state.doc.line(range.fromLine + 1);
-        const folded = foldExists(view.state, span.from, span.to);
-        // The folded opener row carries the wash; a line decoration so the rails (box-shadows on the
-        // same element) run through it unbroken.
-        if (folded)
+        // A line decoration so the rails (box-shadows on the same element) run through it unbroken.
+        if (foldExists(view.state, span.from, span.to))
             builder.add(opener.from, opener.from, washLine);
-        const caretInside = !!inner && inner.fromLine === range.fromLine && inner.toLine === range.toLine;
-        builder.add(opener.from, opener.from, Decoration.widget({ widget: new FoldBandWidget(range, folded, caretInside), side: -1 }));
     }
     return builder.finish();
 }
@@ -274,21 +240,18 @@ const washLine = Decoration.line({ class: 'cm-cairn-folded-row' });
 function foldPlugin() {
     return ViewPlugin.fromClass(class {
         decorations;
-        scan;
         ranges;
         constructor(view) {
-            this.scan = fenceScan(docLines(view));
-            this.ranges = containerRanges(this.scan);
-            this.decorations = foldDecorations(view, this.scan, this.ranges);
+            this.ranges = foldScanFor(view.state).ranges;
+            this.decorations = foldDecorations(view, this.ranges);
         }
         update(update) {
             if (update.docChanged) {
-                this.scan = fenceScan(docLines(update.view));
-                this.ranges = containerRanges(this.scan);
+                this.ranges = foldScanFor(update.view.state).ranges;
             }
             const foldChanged = update.transactions.some((tr) => tr.effects.some((e) => e.is(foldEffect) || e.is(unfoldEffect)));
-            if (update.docChanged || update.viewportChanged || update.selectionSet || foldChanged) {
-                this.decorations = foldDecorations(update.view, this.scan, this.ranges);
+            if (update.docChanged || update.viewportChanged || foldChanged) {
+                this.decorations = foldDecorations(update.view, this.ranges);
             }
             // Flash the revealed lines on an unfold, then schedule the clear. Folding adds no flash.
             for (const tr of update.transactions) {
@@ -311,14 +274,82 @@ function foldPlugin() {
         }
     }, { decorations: (v) => v.decorations });
 }
+const FOLD_KEY_HINT = ' (Ctrl+Shift+[)';
+const UNFOLD_KEY_HINT = ' (Ctrl+Shift+])';
+// The gutter control: a real focusable button per paired-opener row, holding one chevron that CSS
+// rotates (down open, right folded) and reveals on gutter hover. mousedown keeps the caret and
+// focus where they are; click toggles, so one handler serves a mouse click and a keyboard
+// activation (Enter/Space) with no double-toggle. The folded and caret-active classes carry the
+// state the theme reads.
+class FoldMarker extends GutterMarker {
+    container;
+    folded;
+    active;
+    constructor(container, folded, active) {
+        super();
+        this.container = container;
+        this.folded = folded;
+        this.active = active;
+    }
+    eq(other) {
+        return (other instanceof FoldMarker &&
+            other.container.fromLine === this.container.fromLine &&
+            other.container.toLine === this.container.toLine &&
+            other.folded === this.folded &&
+            other.active === this.active);
+    }
+    toDOM(view) {
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        const label = this.folded ? 'Unfold this section' : 'Fold this section';
+        btn.className =
+            'cm-cairn-fold-btn' +
+                (this.folded ? ' cm-cairn-fold-folded' : '') +
+                (this.active ? ' cm-cairn-fold-active' : '');
+        btn.setAttribute('aria-label', label);
+        btn.title = label + (this.folded ? UNFOLD_KEY_HINT : FOLD_KEY_HINT);
+        btn.appendChild(chevronSvg());
+        btn.addEventListener('mousedown', (e) => e.preventDefault());
+        btn.addEventListener('click', (e) => {
+            e.preventDefault();
+            toggleFold(view, this.container);
+        });
+        return btn;
+    }
+}
+// The fold gutter: a fixed-x column (width from the theme) carrying one FoldMarker per paired
+// opener. lineMarker returns null for every other row, so the column is empty whitespace down the
+// rest of the surface. lineMarkerChange recomputes the markers on a doc change, a selection change
+// (the caret-inside state follows the cursor), and any fold effect (a fold flips the chevron).
+function foldGutterColumn() {
+    return gutter({
+        class: 'cm-cairn-fold-gutter',
+        lineMarker(view, line) {
+            const range = openerRangeAt(view.state, line.from);
+            if (!range)
+                return null;
+            const span = foldCharRange(view.state, range);
+            if (!span)
+                return null;
+            const folded = foldExists(view.state, span.from, span.to);
+            return new FoldMarker(range, folded, caretInside(view.state, range));
+        },
+        lineMarkerChange(update) {
+            return (update.docChanged ||
+                update.selectionSet ||
+                update.transactions.some((tr) => tr.effects.some((e) => e.is(foldEffect) || e.is(unfoldEffect))));
+        },
+    });
+}
 // The design notes' diagnostics rules (a deliberately refolded erroring container keeps its fold
 // and tints the pill warning ink instead of re-springing on every lint) have no trigger today: the
 // editor carries no lint source, so there is nothing to refold around or to tint. Deliberately not
 // built; do not invent a lint system to satisfy a rule with no input.
 /**
- * The cairn fold extension: the CodeMirror fold system with the pill placeholder, the chevron and
- * wash affordance, the safety invariant, and the Ctrl+Shift+[ / ] keymap. Session-local and never
- * persisted: the fold state lives in CodeMirror's foldState field, which this never serializes.
+ * The cairn fold extension: the CodeMirror fold system with the pill placeholder, the gutter chevron
+ * and folded-row wash affordance, the safety invariant, and the Ctrl+Shift+[ / ] keymap.
+ * Session-local and never persisted: the fold state lives in CodeMirror's foldState field, which
+ * this never serializes.
  */
 export function cairnFolding() {
     return [
@@ -326,6 +357,7 @@ export function cairnFolding() {
         flashField,
         safetyExtender(),
         foldPlugin(),
+        foldGutterColumn(),
         foldKeymap,
     ];
 }

package/dist/components/editor-highlight.js

@@ -5,7 +5,7 @@ import { HighlightStyle } from '@codemirror/language';
 import { tags } from '@lezer/highlight';
 import { Decoration, ViewPlugin } from '@codemirror/view';
 import { RangeSetBuilder } from '@codemirror/state';
-import { caretContainerRange, containerRanges, directiveLineKind, fenceScan, fenceTokens, findInlineDirectives, markerPrefix, } from './markdown-directives.js';
+import { caretContainerRange, directiveLineKind, fenceScan, fenceTokens, findInlineDirectives, markerPrefix, } from './markdown-directives.js';
 /** Markdown token colors over the admin theme variables. */
 export function cairnHighlightStyle() {
     // Rule order is load-bearing. HighlightStyle emits its CSS in spec order, so on a span that
@@ -48,11 +48,6 @@ const DEPTH_STEPS = [1, 2, 3];
 const fenceLines = DEPTH_STEPS.map((d) => Decoration.line({ class: `cm-cairn-directive-fence cm-cairn-depth-${d}`, attributes: { title: MACHINERY_HINT } }));
 const contentLines = DEPTH_STEPS.map((d) => Decoration.line({ class: `cm-cairn-directive-content cm-cairn-depth-${d}` }));
 const leafLine = Decoration.line({ class: 'cm-cairn-directive-leaf', attributes: { title: MACHINERY_HINT } });
-// A paired container's opener row, where the fold chevron replaces the container's own innermost
-// rail bar. The class is additive over the fence depth class, so the theme drops only the deepest
-// bar on this row while the outer bars stay; an unbalanced opener never gets it (no chevron, bar
-// intact). Added just after the fence depth line decoration so the row carries both classes.
-const openerLine = Decoration.line({ class: 'cm-cairn-directive-opener' });
 const inlineMark = Decoration.mark({ class: 'cm-cairn-directive-inline' });
 // Within a fence line, machinery (colons, brackets, braces) dims to the marker tone while the
 // directive name and label keep a depth-stepped ink: meaning over machinery.
@@ -101,9 +96,6 @@ function buildDirectiveDecorations(view, scan) {
     // as its own line decoration just ahead of the row's depth decoration.
     const caretLine = view.state.doc.lineAt(view.state.selection.main.head).number - 1;
     const caret = caretContainerRange(scan, caretLine);
-    // The opener rows that carry a fold chevron, so the rail rule drops their innermost bar. Only
-    // paired containers fold, so an unbalanced opener is absent here and keeps its full rail.
-    const openerLines = new Set(containerRanges(scan).map((r) => r.fromLine));
     for (const { from, to } of view.visibleRanges) {
         for (let pos = from; pos <= to;) {
             const line = view.state.doc.lineAt(pos);
@@ -116,10 +108,6 @@ function buildDirectiveDecorations(view, scan) {
             // inside a code block, outside any container); it gets no machinery treatment.
             if (kind === 'fence' && depth > 0) {
                 builder.add(line.from, line.from, fenceLines[depth - 1]);
-                // A paired opener row gets the opener class just after its fence depth class, so the rail
-                // rule below drops the innermost bar where the chevron renders.
-                if (openerLines.has(line.number - 1))
-                    builder.add(line.from, line.from, openerLine);
             }
             else if (kind === 'leaf') {
                 builder.add(line.from, line.from, leafLine);

package/dist/content/concepts.js

@@ -76,9 +76,11 @@ export function normalizeConcepts(content, urlPolicy = {}, routing = CONCEPT_ROU
         const conceptRouting = routing[id] ?? DEFAULT_ROUTING;
         const policy = urlPolicy[id] ?? {};
         validateUrlPolicy(id, policy, conceptRouting.dated);
+        const label = config.label ?? defaultLabel(id);
         descriptors.push({
             id,
-            label: config.label ?? defaultLabel(id),
+            label,
+            singular: config.singular ?? label,
             dir: config.dir,
             routing: conceptRouting,
             permalink: policy.permalink ?? defaultPermalink(id),