@glw907/cairn-cms 0.53.0 → 0.55.0

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

@@ -0,0 +1,356 @@
+// 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
+// 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/
+// 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).
+//
+// The safety invariant: an author never edits, deletes, or fails to see hidden text.
+import {
+  Decoration,
+  EditorView,
+  ViewPlugin,
+  WidgetType,
+  keymap,
+  type DecorationSet,
+  type ViewUpdate,
+} from '@codemirror/view';
+import { EditorState, Prec, RangeSetBuilder, StateEffect, StateField, type Extension } from '@codemirror/state';
+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).
+const CHEVRON_DOWN = 'm6 9 6 6 6-6';
+const CHEVRON_RIGHT = 'm9 6 6 6-6 6';
+
+function chevronSvg(direction: 'down' | 'right'): SVGSVGElement {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('fill', 'none');
+  svg.setAttribute('stroke', 'currentColor');
+  svg.setAttribute('stroke-width', '2.5');
+  svg.setAttribute('stroke-linecap', 'round');
+  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);
+  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.
+function preparePlaceholder(state: EditorState, range: { from: number; to: number }): number {
+  return state.doc.lineAt(range.to).number - state.doc.lineAt(range.from).number;
+}
+
+function placeholderDOM(view: EditorView, onclick: (event: Event) => void, lines: number): HTMLElement {
+  const pill = document.createElement('button');
+  pill.type = 'button';
+  pill.className = 'cm-cairn-fold-pill';
+  pill.textContent = `${lines} lines`;
+  pill.setAttribute('aria-label', `Show ${lines} hidden lines`);
+  pill.addEventListener('click', onclick);
+  return pill;
+}
+
+// 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.
+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);
+  if (closer.to <= opener.to) return null;
+  return { from: opener.to, to: closer.to };
+}
+
+// Fold one container, or unfold it if already folded. The range comes from containerRanges, so a
+// half-typed fence can never fold. A no-op when the container has nothing to hide.
+function toggleFold(view: EditorView, range: ContainerRange): void {
+  const span = foldCharRange(view.state, range);
+  if (!span) return;
+  const effect = foldExists(view.state, span.from, span.to) ? unfoldEffect : foldEffect;
+  view.dispatch({ effects: effect.of(span) });
+}
+
+function foldExists(state: EditorState, from: number, to: number): boolean {
+  let found = false;
+  foldedRanges(state).between(from, from, (a, b) => {
+    if (a === from && b === to) found = true;
+  });
+  return found;
+}
+
+// The innermost container at the caret, the unit the keymap folds and unfolds. caretContainerRange
+// 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 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
+  );
+}
+
+function docLines(view: EditorView): string[] {
+  const doc = view.state.doc;
+  const lines: string[] = [];
+  for (let n = 1; n <= doc.lines; n++) lines.push(doc.line(n).text);
+  return lines;
+}
+
+// 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.)
+// At Prec.high so it resolves the shifted bracket ahead of the default keymap's Ctrl-[ indentLess,
+// which the same keystroke also matches on the non-shift lookup.
+const foldKeymap = Prec.high(
+  keymap.of([
+  {
+    key: 'Mod-Shift-[',
+    run: (view) => {
+      const range = caretFoldRange(view);
+      const span = range && foldCharRange(view.state, range);
+      if (!span || foldExists(view.state, span.from, span.to)) return false;
+      view.dispatch({ effects: foldEffect.of(span) });
+      return true;
+    },
+  },
+  {
+    key: 'Mod-Shift-]',
+    run: (view) => {
+      const range = caretFoldRange(view);
+      const span = range && foldCharRange(view.state, range);
+      if (!span || !foldExists(view.state, span.from, span.to)) return false;
+      view.dispatch({ effects: unfoldEffect.of(span) });
+      return true;
+    },
+  },
+  ]),
+);
+
+// The unfold flash: a one-time low-alpha accent line decoration on the revealed lines, faded out
+// over ~400ms. A StateEffect carries the revealed char range; the field decorates those lines
+// until a follow-up effect clears it. Driven by the plugin, which schedules the clear.
+const flashEffect = StateEffect.define<{ from: number; to: number } | null>();
+const flashLine = Decoration.line({ class: 'cm-cairn-fold-flash' });
+
+const flashField = StateField.define<DecorationSet>({
+  create() {
+    return Decoration.none;
+  },
+  update(deco, tr) {
+    deco = deco.map(tr.changes);
+    for (const e of tr.effects) {
+      if (e.is(flashEffect)) {
+        if (!e.value) {
+          deco = Decoration.none;
+        } else {
+          const builder = new RangeSetBuilder<Decoration>();
+          const first = tr.state.doc.lineAt(e.value.from).number;
+          const last = tr.state.doc.lineAt(e.value.to).number;
+          for (let n = first; n <= last; n++) {
+            const line = tr.state.doc.line(n);
+            builder.add(line.from, line.from, flashLine);
+          }
+          deco = builder.finish();
+        }
+      }
+    }
+    return deco;
+  },
+  provide: (f) => EditorView.decorations.from(f),
+});
+
+const FLASH_MS = 400;
+
+// The safety invariant, in one transactionExtender. CodeMirror's own fold field already clears a
+// fold the selection head sits inside and a fold a delete touches; this covers the rest: an insert
+// touching a fold boundary, a paste across it, an undo/redo landing inside, and a selection range
+// (not just its head) extending into hidden text. It reads the start state's folds, maps them
+// forward, and appends an unfold effect for any the change or new selection touches. A replace
+// inside a fold leaves it open afterward, which falls out of the same rule.
+function safetyExtender(): Extension {
+  return EditorState.transactionExtender.of((tr) => {
+    if (!tr.docChanged && !tr.selection) return null;
+    const startFolds = foldedRanges(tr.startState);
+    if (startFolds.size === 0) return null;
+    const effects: StateEffect<unknown>[] = [];
+    startFolds.between(0, tr.startState.doc.length, (from, to) => {
+      // The fold's position after the change, for the selection test.
+      const mappedFrom = tr.changes.mapPos(from, 1);
+      const mappedTo = tr.changes.mapPos(to, -1);
+      let touched = false;
+      if (tr.docChanged) {
+        tr.changes.iterChangedRanges((fromA, toA) => {
+          if (fromA <= to && toA >= from) touched = true;
+        });
+      }
+      if (!touched && tr.selection) {
+        for (const range of tr.selection.ranges) {
+          if (range.from < mappedTo && range.to > mappedFrom) touched = true;
+        }
+      }
+      if (touched) effects.push(unfoldEffect.of({ from, to }));
+    });
+    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: EditorView, scan: ReturnType<typeof fenceScan>, 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).
+  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 }),
+    );
+  }
+  return builder.finish();
+}
+
+const washLine = Decoration.line({ class: 'cm-cairn-folded-row' });
+
+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);
+      }
+      update(update: ViewUpdate) {
+        if (update.docChanged) {
+          this.scan = fenceScan(docLines(update.view));
+          this.ranges = containerRanges(this.scan);
+        }
+        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);
+        }
+        // Flash the revealed lines on an unfold, then schedule the clear. Folding adds no flash.
+        for (const tr of update.transactions) {
+          for (const e of tr.effects) {
+            if (e.is(unfoldEffect)) {
+              const { from, to } = e.value;
+              const view = update.view;
+              queueMicrotask(() => {
+                if (!view.dom.isConnected) return;
+                view.dispatch({ effects: flashEffect.of({ from, to }) });
+                setTimeout(() => {
+                  if (view.dom.isConnected) view.dispatch({ effects: flashEffect.of(null) });
+                }, FLASH_MS);
+              });
+            }
+          }
+        }
+      }
+    },
+    { decorations: (v) => v.decorations },
+  );
+}
+
+// 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.
+ */
+export function cairnFolding(): Extension {
+  return [
+    codeFolding({ preparePlaceholder, placeholderDOM }),
+    flashField,
+    safetyExtender(),
+    foldPlugin(),
+    foldKeymap,
+  ];
+}

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

@@ -7,10 +7,12 @@ import { Decoration, ViewPlugin, type DecorationSet, type EditorView, type ViewU
 import { RangeSetBuilder } from '@codemirror/state';
 import {
   caretContainerRange,
+  containerRanges,
   directiveLineKind,
   fenceScan,
   fenceTokens,
   findInlineDirectives,
+  markerPrefix,
   type FenceScan,
 } from './markdown-directives.js';
 
@@ -25,7 +27,9 @@ export function cairnHighlightStyle(): HighlightStyle {
     { tag: tags.heading1, fontSize: '1.5em', fontWeight: '700', color: 'var(--color-base-content)' },
     { tag: tags.heading2, fontSize: '1.3em', fontWeight: '700', color: 'var(--color-base-content)' },
     { tag: tags.heading3, fontSize: '1.17em', fontWeight: '700', color: 'var(--color-base-content)' },
-    // h4 and deeper share the weight only; body size keeps the low levels from outranking h3.
+    // A real step for h4, between h3 and body, so a hand-typed #### reads as a heading.
+    { tag: tags.heading4, fontSize: '1.05em', fontWeight: '700', color: 'var(--color-base-content)' },
+    // h5 and deeper share the weight only; body size keeps the low levels from outranking h4.
     { tag: tags.heading, fontWeight: '700', color: 'var(--color-base-content)' },
     { tag: tags.strong, fontWeight: '700' },
     { tag: tags.emphasis, fontStyle: 'italic' },
@@ -59,6 +63,11 @@ 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.
@@ -69,6 +78,26 @@ const fenceLabels = DEPTH_STEPS.map((d) => Decoration.mark({ class: `cm-cairn-di
 // label ink up one notch while the other containers sit quieter.
 const caretBlockLine = Decoration.line({ class: 'cm-cairn-caret-block' });
 
+// The hanging-indent line decoration for a quote or list line, keyed by the marker's character
+// width. The width rides a --cairn-hang custom property so the theme's padding-left rule adds it
+// to the directive gutter rather than replacing it (an inline padding-left would win the cascade
+// and erase the gutter). The equal negative text-indent pulls the first line back by the marker
+// width, so the marker sits in the indent and a wrapped continuation resumes under the content
+// (the Obsidian/HyperMD idiom). The surface is iA Writer Mono, fixed pitch, so n chars is exactly
+// n ch. Built lazily and memoized; marker widths repeat.
+const hangLines = new Map<number, Decoration>();
+function hangLine(width: number): Decoration {
+  let deco = hangLines.get(width);
+  if (!deco) {
+    deco = Decoration.line({
+      class: 'cm-cairn-hang',
+      attributes: { style: `--cairn-hang:${width}ch;text-indent:-${width}ch` },
+    });
+    hangLines.set(width, deco);
+  }
+  return deco;
+}
+
 // Depth needs the whole document, since a visible line's containers can open above the viewport.
 // One regex pass per line, linear in the document; at admin entry sizes (tens of kilobytes) that
 // is well under a millisecond. The plugin caches the fence scan, so it reruns only when the
@@ -89,6 +118,9 @@ 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);
@@ -101,6 +133,26 @@ 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) {
+        builder.add(line.from, line.from, contentLines[depth - 1]);
+      }
+      // A quote or list line hangs its wrapped continuation under the content. The decoration is
+      // a line decoration too, so it enters at line.from after the depth and caret-block lines
+      // and before any mark decoration on the same row; inside a container it composes with the
+      // gutter padding. A fence or leaf machinery line is never a quote or list, so this only
+      // fires on prose and content rows.
+      if (kind === null) {
+        const prefix = markerPrefix(line.text);
+        if (prefix) builder.add(line.from, line.from, hangLine(prefix.length));
+      }
+      // Mark decorations start at offsets past line.from, so they enter after every line
+      // decoration on the row.
+      if (kind === 'fence' && depth > 0) {
         for (const token of fenceTokens(line.text)) {
           builder.add(
             line.from + token.from,
@@ -108,9 +160,7 @@ function buildDirectiveDecorations(view: EditorView, scan: FenceScan): Decoratio
             token.kind === 'mark' ? fenceMark : fenceLabels[depth - 1],
           );
         }
-      } else if (kind === 'leaf') builder.add(line.from, line.from, leafLine);
-      else if (kind === null) {
-        if (depth > 0) builder.add(line.from, line.from, contentLines[depth - 1]);
+      } else if (kind === null) {
         for (const r of findInlineDirectives(line.text)) {
           builder.add(line.from + r.from, line.from + r.to, inlineMark);
         }

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

@@ -0,0 +1,42 @@
+// The one keyboard-shortcut table, the single source the shortcuts sheet (ShortcutsDialog) and the
+// Markdown help dialog both render. Order and content follow the gold-standard mockup's screen 5
+// (docs/internal/design/2026-06-12-editor-shell-gold-standard.html), one change: Write / Preview
+// shows Ctrl Alt P, the binding actually wired in EditPage (Firefox reserves Ctrl Shift P for
+// private browsing at the browser level, below preventDefault), and the fold pair the editor wires
+// in editor-folding.ts joins the editor-structure rows. The keys read with literal "Ctrl" to match
+// the toolbar tooltips, which never localize to Cmd.
+
+/** One shortcut row: a human label and the chord that triggers it. */
+export type ShortcutRow = { label: string; keys: string };
+
+/**
+ * The shortcut vocabulary, in the mockup's reading order. Each entry is verified against the
+ * handler that implements it: Save / Publish / Details panel / Zen / Write-Preview / Focus mode and
+ * This sheet ride EditPage's window keydown; Bold / Italic / Inline code / Web link / the heading
+ * pair / Quote / the list pair ride EditPage's card keydown; Fold / unfold ride editor-folding's
+ * CodeMirror keymap; the command palette rides AdminLayout's Ctrl K; Continue list / quote is the
+ * built-in markdown keymap on Enter.
+ */
+export const editorShortcuts: ShortcutRow[] = [
+  { label: 'Save', keys: 'Ctrl S' },
+  { label: 'Bold', keys: 'Ctrl B' },
+  { label: 'Publish', keys: 'Ctrl Shift S' },
+  { label: 'Italic', keys: 'Ctrl I' },
+  { label: 'Details panel', keys: 'Ctrl .' },
+  { label: 'Web link', keys: 'Ctrl K' },
+  { label: 'Zen', keys: 'Ctrl Shift .' },
+  { label: 'Inline code', keys: 'Ctrl E' },
+  { label: 'Write / Preview', keys: 'Ctrl Alt P' },
+  { label: 'Heading / smaller', keys: 'Ctrl Alt 2 / 3' },
+  { label: 'Focus mode', keys: 'Ctrl Shift F' },
+  { label: 'Quote', keys: 'Ctrl Shift 9' },
+  { label: 'Command palette', keys: 'Ctrl K (global)' },
+  { label: 'Bulleted / numbered list', keys: 'Ctrl Shift 8 / 7' },
+  { label: 'Fold / unfold', keys: 'Ctrl Shift [ / ]' },
+  { label: 'This sheet', keys: 'Ctrl /' },
+  { label: 'Continue list / quote', keys: 'Enter' },
+];
+
+/** The closing reassurance under the grid: the keys never gate the markdown that authors type. */
+export const shortcutsClosingLine =
+  'Typing markdown always works; the keys are conveniences, never requirements.';

package/src/lib/components/markdown-directives.ts

@@ -124,6 +124,32 @@ export function caretContainerRange(scan: FenceScan, caretLine: number): Contain
   return { fromLine, toLine, depth };
 }
 
+/**
+ * Every paired directive container in the document, as inclusive line ranges. Walks the scan's
+ * roles with a stack: an opener pushes its line, a closer pops the nearest open one and emits the
+ * pair at the opener's depth. The ranges come back in close order, so an inner container precedes
+ * the outer that holds it, which is exactly the order a fold consumer wants (folding the innermost
+ * first). An unbalanced opener is left on the stack and never emitted (a half-typed fence earns no
+ * fold range, the safety invariant), and a stray closer with nothing open is dropped. The scan
+ * already disowns a fence-shaped line inside a code block (its role is null), so a documented
+ * example can neither open nor close a range. This is the sole source of fold ranges.
+ */
+export function containerRanges(scan: FenceScan): ContainerRange[] {
+  const { depths, roles } = scan;
+  const out: ContainerRange[] = [];
+  const stack: number[] = [];
+  for (let i = 0; i < roles.length; i++) {
+    if (roles[i] === 'opener') {
+      stack.push(i);
+    } else if (roles[i] === 'closer') {
+      const fromLine = stack.pop();
+      if (fromLine === undefined) continue;
+      out.push({ fromLine, toLine: i, depth: depths[fromLine] ?? 1 });
+    }
+  }
+  return out;
+}
+
 /** One span of a fence line, in line-local offsets: machinery (`mark`) or meaning (`label`). */
 export interface FenceToken {
   from: number;
@@ -163,6 +189,22 @@ export function fenceTokens(line: string): FenceToken[] {
   return out;
 }
 
+// The marker prefix of a quote or list line: leading indentation, the marker itself, and the one
+// space after it. A task checkbox (`[ ]`/`[x]`) extends a bullet's marker. Ordered markers vary in
+// width (a two-digit number is wider than a bullet), so the width is read from the match, never
+// assumed. The anchored alternatives mirror the markers the highlight pass styles.
+const MARKER = /^(\s*)(?:[-*+](?: \[[ xX]\])?|\d+[.)]|>) /;
+
+/**
+ * The marker prefix of a line (indentation plus marker plus its trailing space), or null when the
+ * line carries no quote or list marker. The hanging-indent decoration uses the prefix length, in
+ * fixed-pitch chars, to wrap continuation lines under the content rather than under the marker.
+ */
+export function markerPrefix(line: string): string | null {
+  const m = MARKER.exec(line);
+  return m ? m[0] : null;
+}
+
 /** Inline directive ranges (`:name[...]{...}`) within a line of text. */
 export function findInlineDirectives(text: string): { from: number; to: number }[] {
   const out: { from: number; to: number }[] = [];

package/src/lib/components/topbar-context.ts

@@ -0,0 +1,30 @@
+import { getContext, setContext, type Snippet } from 'svelte';
+
+// The topbar context portal. On an edit route the document owns the band's live state (status,
+// save-state, the lifecycle actions), so the desk's controls have to render up in AdminLayout's
+// one topbar rather than in a second header of their own. AdminLayout owns a holder and provides
+// it; EditPage, a descendant through the children snippet, registers its desk snippet into the
+// holder and clears it on teardown. CairnAdmin's view switch unmounts EditPage, which nulls the
+// holder, so the band reverts to the office layout with no route plumbing.
+
+const TOPBAR_CONTEXT_KEY = Symbol('cairn-topbar');
+
+/** The shared holder: the desk snippet a document registers, or null on the office routes. */
+export interface TopbarHolder {
+  desk: Snippet | null;
+  /** True while the document is in zen: AdminLayout drops the whole topbar element so the band
+   *  slides away (the desk's three clusters include AdminLayout-owned chrome, the drawer toggle and
+   *  breadcrumb, that must vanish with it). EditPage sets this; the office routes leave it false. */
+  zen: boolean;
+}
+
+/** Called by AdminLayout once: creates the holder, provides it on context, returns it to render. */
+export function provideTopbar(holder: TopbarHolder): TopbarHolder {
+  setContext(TOPBAR_CONTEXT_KEY, holder);
+  return holder;
+}
+
+/** Called by a descendant document (EditPage) to reach the holder it registers its desk into. */
+export function useTopbar(): TopbarHolder | undefined {
+  return getContext<TopbarHolder | undefined>(TOPBAR_CONTEXT_KEY);
+}

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/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';