@glw907/cairn-cms 0.53.0 → 0.54.0

package/dist/components/editor-folding.js

@@ -0,0 +1,331 @@
+// 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, } 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).
+const CHEVRON_DOWN = 'm6 9 6 6 6-6';
+const CHEVRON_RIGHT = 'm9 6 6 6-6 6';
+function chevronSvg(direction) {
+    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 {
+    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.
+function preparePlaceholder(state, range) {
+    return state.doc.lineAt(range.to).number - state.doc.lineAt(range.from).number;
+}
+function placeholderDOM(view, onclick, lines) {
+    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, range) {
+    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, range) {
+    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, from, to) {
+    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) {
+    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) {
+    const doc = view.state.doc;
+    const lines = [];
+    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();
+const flashLine = Decoration.line({ class: 'cm-cairn-fold-flash' });
+const flashField = StateField.define({
+    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();
+                    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() {
+    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 = [];
+        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, scan, 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).
+    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;
+        scan;
+        ranges;
+        constructor(view) {
+            this.scan = fenceScan(docLines(view));
+            this.ranges = containerRanges(this.scan);
+            this.decorations = foldDecorations(view, this.scan, this.ranges);
+        }
+        update(update) {
+            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() {
+    return [
+        codeFolding({ preparePlaceholder, placeholderDOM }),
+        flashField,
+        safetyExtender(),
+        foldPlugin(),
+        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, directiveLineKind, fenceScan, fenceTokens, findInlineDirectives, } from './markdown-directives.js';
+import { caretContainerRange, containerRanges, 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
@@ -17,7 +17,9 @@ export function cairnHighlightStyle() {
         { 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' },
@@ -46,6 +48,11 @@ 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.
@@ -55,6 +62,25 @@ const fenceLabels = DEPTH_STEPS.map((d) => Decoration.mark({ class: `cm-cairn-di
 // alike, carries this class on top of its depth classes; the theme steps that block's rail and
 // 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();
+function hangLine(width) {
+    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
@@ -75,6 +101,9 @@ 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);
@@ -87,15 +116,35 @@ 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);
+            }
+            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, line.from + token.to, 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]);
                 for (const r of findInlineDirectives(line.text)) {
                     builder.add(line.from + r.from, line.from + r.to, inlineMark);
                 }

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

@@ -0,0 +1,16 @@
+/** 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 declare const editorShortcuts: ShortcutRow[];
+/** The closing reassurance under the grid: the keys never gate the markdown that authors type. */
+export declare const shortcutsClosingLine = "Typing markdown always works; the keys are conveniences, never requirements.";

package/dist/components/editor-shortcuts.js

@@ -0,0 +1,36 @@
+// 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.
+/**
+ * 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 = [
+    { 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/dist/components/markdown-directives.d.ts

@@ -38,6 +38,17 @@ export interface ContainerRange {
  * unclosed container runs to the document end.
  */
 export declare function caretContainerRange(scan: FenceScan, caretLine: number): ContainerRange | null;
+/**
+ * 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 declare function containerRanges(scan: FenceScan): ContainerRange[];
 /** One span of a fence line, in line-local offsets: machinery (`mark`) or meaning (`label`). */
 export interface FenceToken {
     from: number;
@@ -51,6 +62,12 @@ export interface FenceToken {
  * no spans at all.
  */
 export declare function fenceTokens(line: string): FenceToken[];
+/**
+ * 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 declare function markerPrefix(line: string): string | null;
 /** Inline directive ranges (`:name[...]{...}`) within a line of text. */
 export declare function findInlineDirectives(text: string): {
     from: number;

package/dist/components/markdown-directives.js

@@ -108,6 +108,33 @@ export function caretContainerRange(scan, caretLine) {
     }
     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) {
+    const { depths, roles } = scan;
+    const out = [];
+    const stack = [];
+    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;
+}
 /**
  * Split a fence line into machinery and meaning. The colon run, the label's brackets, and the
  * whole {attrs} group are machinery; the directive name and the label text are meaning, the
@@ -141,6 +168,20 @@ export function fenceTokens(line) {
     }
     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) {
+    const m = MARKER.exec(line);
+    return m ? m[0] : null;
+}
 /** Inline directive ranges (`:name[...]{...}`) within a line of text. */
 export function findInlineDirectives(text) {
     const out = [];

package/dist/components/topbar-context.d.ts

@@ -0,0 +1,13 @@
+import { type Snippet } from 'svelte';
+/** 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 declare function provideTopbar(holder: TopbarHolder): TopbarHolder;
+/** Called by a descendant document (EditPage) to reach the holder it registers its desk into. */
+export declare function useTopbar(): TopbarHolder | undefined;

package/dist/components/topbar-context.js

@@ -0,0 +1,17 @@
+import { getContext, setContext } 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');
+/** Called by AdminLayout once: creates the holder, provides it on context, returns it to render. */
+export function provideTopbar(holder) {
+    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() {
+    return getContext(TOPBAR_CONTEXT_KEY);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [