@glw907/cairn-cms 0.54.0 → 0.56.0

package/src/lib/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/src/lib/components/editor-folding.ts

@@ -1,21 +1,23 @@
-// 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,
+  GutterMarker,
   ViewPlugin,
-  WidgetType,
+  gutter,
   keymap,
   type DecorationSet,
   type ViewUpdate,
@@ -24,17 +26,11 @@ import { EditorState, Prec, RangeSetBuilder, StateEffect, StateField, type Exten
 import { codeFolding, foldEffect, foldedRanges, unfoldEffect } from '@codemirror/language';
 import { caretContainerRange, containerRanges, fenceScan, type ContainerRange } 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: number) => (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: 'down' | 'right'): SVGSVGElement {
+function chevronSvg(): SVGSVGElement {
   const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
   svg.setAttribute('viewBox', '0 0 24 24');
   svg.setAttribute('fill', 'none');
@@ -44,57 +40,11 @@ function chevronSvg(direction: 'down' | 'right'): SVGSVGElement {
   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 {
-  constructor(
-    readonly range: ContainerRange,
-    readonly folded: boolean,
-    readonly caretInside: boolean,
-  ) {
-    super();
-  }
-  eq(other: FoldBandWidget) {
-    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: EditorView): HTMLElement {
-    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.
@@ -114,8 +64,7 @@ function placeholderDOM(view: EditorView, onclick: (event: Event) => void, 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: EditorState, range: ContainerRange): { from: number; to: number } | null {
   const opener = state.doc.line(range.fromLine + 1);
   const closer = state.doc.line(range.toLine + 1);
@@ -144,22 +93,47 @@ function foldExists(state: EditorState, from: number, to: number): boolean {
 // 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: EditorView): ContainerRange | null {
-  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: EditorView): string[] {
-  const doc = view.state.doc;
+function docLines(state: EditorState): string[] {
   const lines: string[] = [];
-  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<EditorState, { scan: ReturnType<typeof fenceScan>; ranges: ContainerRange[] }>();
+function foldScanFor(state: EditorState): { scan: ReturnType<typeof fenceScan>; ranges: ContainerRange[] } {
+  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: EditorState, lineFrom: number): ContainerRange | null {
+  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: EditorState, range: ContainerRange): boolean {
+  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.)
@@ -258,33 +232,21 @@ function safetyExtender(): Extension {
   });
 }
 
-// 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: EditorView, scan: ReturnType<typeof fenceScan>, ranges: ContainerRange[]): DecorationSet {
+// 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: EditorView, ranges: ContainerRange[]): DecorationSet {
   const builder = new RangeSetBuilder<Decoration>();
-  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) 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 }),
-    );
+    // 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);
   }
   return builder.finish();
 }
@@ -295,23 +257,20 @@ function foldPlugin() {
   return ViewPlugin.fromClass(
     class {
       decorations: DecorationSet;
-      scan: ReturnType<typeof fenceScan>;
       ranges: ContainerRange[];
       constructor(view: EditorView) {
-        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: ViewUpdate) {
         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) {
@@ -335,15 +294,88 @@ function foldPlugin() {
   );
 }
 
+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 {
+  constructor(
+    readonly container: ContainerRange,
+    readonly folded: boolean,
+    readonly active: boolean,
+  ) {
+    super();
+  }
+  eq(other: GutterMarker) {
+    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: EditorView) {
+    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(): Extension {
+  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(): Extension {
   return [
@@ -351,6 +383,7 @@ export function cairnFolding(): Extension {
     flashField,
     safetyExtender(),
     foldPlugin(),
+    foldGutterColumn(),
     foldKeymap,
   ];
 }

package/src/lib/components/editor-highlight.ts

@@ -7,7 +7,6 @@ import { Decoration, ViewPlugin, type DecorationSet, type EditorView, type ViewU
 import { RangeSetBuilder } from '@codemirror/state';
 import {
   caretContainerRange,
-  containerRanges,
   directiveLineKind,
   fenceScan,
   fenceTokens,
@@ -63,11 +62,6 @@ const fenceLines = DEPTH_STEPS.map((d) =>
 );
 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.
@@ -118,9 +112,6 @@ function buildDirectiveDecorations(view: EditorView, scan: FenceScan): Decoratio
   // 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);
@@ -133,9 +124,6 @@ function buildDirectiveDecorations(view: EditorView, scan: FenceScan): Decoratio
       // 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);
       } else if (kind === null && depth > 0) {

package/src/lib/content/concepts.ts

@@ -100,9 +100,11 @@ export function normalizeConcepts(
     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),

package/src/lib/content/manifest.ts

@@ -4,6 +4,7 @@
 // it; the save path patches one entry and commits it with the content in one commit. Each entry
 // carries its identity and its outbound cairn: edges, so the manifest is the link graph.
 import { parseMarkdown } from './frontmatter.js';
+import { deriveExcerpt } from './excerpt.js';
 import { entryIdentity, asString } from './identity.js';
 import { extractCairnLinks, type CairnRef, type LinkResolve } from './links.js';
 import type { ConceptDescriptor } from './types.js';
@@ -15,6 +16,7 @@ export interface ManifestEntry {
   title: string;
   date?: string;
   permalink: string;
+  summary?: string;
   draft: boolean;
   links: CairnRef[];
 }
@@ -47,6 +49,9 @@ export function manifestEntryFromFile(descriptor: ConceptDescriptor, file: { pat
     title: asString(frontmatter.title) ?? id,
     date,
     permalink,
+    // Coalesce an empty excerpt to undefined, so an empty-body entry carries no summary key at all
+    // (matching serialize's optional-spread) and the in-memory and serialized shapes agree.
+    summary: deriveExcerpt(body, { description: asString(frontmatter.description) }) || undefined,
     draft: frontmatter.draft === true,
     links: extractCairnLinks(body),
   };
@@ -70,6 +75,7 @@ export function serializeManifest(manifest: Manifest): string {
     title: e.title,
     ...(e.date ? { date: e.date } : {}),
     permalink: e.permalink,
+    ...(e.summary ? { summary: e.summary } : {}),
     draft: e.draft,
     links: [...e.links].sort(compareRef).map((r) => ({ concept: r.concept, id: r.id })),
   }));
@@ -102,6 +108,7 @@ export function parseManifest(raw: string): Manifest {
       typeof e.permalink === 'string' &&
       typeof e.draft === 'boolean' &&
       (e.date === undefined || typeof e.date === 'string') &&
+      (e.summary === undefined || typeof e.summary === 'string') &&
       Array.isArray(e.links);
     if (!ok) {
       throw new Error(`content manifest: malformed entry ${JSON.stringify(e)}`);

package/src/lib/content/types.ts

@@ -108,6 +108,8 @@ export interface ConceptConfig<S extends ConceptSchema = ConceptSchema> {
   dir: string;
   /** Sidebar label; defaults from the concept id when omitted. */
   label?: string;
+  /** The singular noun for the create affordances ("New post"); defaults to `label` when omitted. */
+  singular?: string;
   /** The concept's schema: the form projection, the generated validator, and the inferred type. */
   schema: S;
   /** Frontmatter keys to surface on each `ContentSummary.fields`, so a list card reads an authored
@@ -241,6 +243,9 @@ export interface ConceptDescriptor {
   /** Concept id, the key under `content`, e.g. "posts". */
   id: string;
   label: string;
+  /** The singular noun for the create affordances ("New post"); resolved from `ConceptConfig.singular`,
+   *  defaulting to `label` when the config omits it. */
+  singular: string;
   dir: string;
   routing: RoutingRule;
   /** The resolved permalink pattern, defaulted by `normalizeConcepts`. */

package/src/lib/delivery/content-index.ts

@@ -4,7 +4,7 @@
 // every operation reads the descriptor and its routing rule, never a hardcoded concept id.
 import { parseMarkdown } from '../content/frontmatter.js';
 import { entryId, entryIdentity, asDate, asString, asTags } from '../content/identity.js';
-import { deriveExcerpt, wordCount } from './excerpt.js';
+import { deriveExcerpt, wordCount } from '../content/excerpt.js';
 import type { ConceptDescriptor } from '../content/types.js';
 
 /** A raw content file before parsing: the glob key and the file's full markdown text. */

package/src/lib/delivery/data.ts

@@ -8,7 +8,7 @@ export type { SiteResolver, ConceptIndex } from './site-resolver.js';
 export { createSiteIndexes } from './site-indexes.js';
 export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';
-export { deriveExcerpt, wordCount } from './excerpt.js';
+export { deriveExcerpt, wordCount } from '../content/excerpt.js';
 export { buildRssFeed, buildJsonFeed } from './feeds.js';
 export type { FeedChannel, FeedItem } from './feeds.js';
 export { buildSitemap } from './sitemap.js';