@glw907/cairn-cms 0.52.1 → 0.54.0

package/src/lib/components/cairn-admin.css

@@ -1,4 +1,4 @@
-/* Cairn's own typefaces, self-hosted so the admin needs no external font request. Figtree carries
+/* Cairn's own typefaces, self-hosted so the admin needs no external font request. IBM Plex Sans carries
    the body and UI (friendly, highly legible at small sizes); Bricolage Grotesque gives the brand and
    the page headings a distinct voice; iA Writer Mono is the editor writing surface. The first two are
    variable (one file spans the weight range), the editor face ships four static files, and all three
@@ -10,7 +10,7 @@
    of use, so this fully overrides the host's theme with no @plugin and no host build step. */
 [data-theme='cairn-admin'] {
   color-scheme: light;
-  --font-body: 'Figtree Variable', system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+  --font-body: 'IBM Plex Sans Variable', system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
   --font-display: 'Bricolage Grotesque Variable', var(--font-body);
   --font-editor: 'iA Writer Mono', ui-monospace, monospace;
   font-family: var(--font-body);
@@ -47,8 +47,9 @@
   --cairn-directive-rail-2: 82%;
   --cairn-directive-rail-3: 92%;
   /* Cursor-aware emphasis: the caret container's own bar steps to a full-strength accent rail
-     (also 1px wider) and an ink one notch past depth 3. Locked pairs on base-100: rail = solid
-     accent (5.28:1, non-text floor 3:1), ink 46% (7.47:1). Do not lighten without re-checking. */
+     at the same 2px width (strength only) and an ink one notch past depth 3. Locked pairs on
+     base-100: rail = solid accent (5.28:1, non-text floor 3:1), ink 46% (7.47:1). Do not
+     lighten without re-checking. */
   --cairn-directive-rail-active: 100%;
   --cairn-directive-ink-active: oklch(46% 0.16 300);
   /* The editor's inline-code chip, a quiet tint beside base-200. Locked pair: base-content ink
@@ -63,6 +64,14 @@
      ever sits on; on the chips it measured as low as 2.63:1. Do not lighten without
      re-checking. */
   --cairn-focus-dim-ink: oklch(66% 0.01 75);
+  /* Focus mode's rail percentages: the directive bars dim with their text (about a third of the
+     quiet 72/82/92 ramp), so a dimmed block keeps its structure without staying the one
+     chromatic object in the field. Deliberately sub-3:1, the same transient-state call as the
+     dim ink; the quiet ramp is one toggle away. */
+  --cairn-focus-dim-rail-1: 24%;
+  --cairn-focus-dim-rail-2: 28%;
+  --cairn-focus-dim-rail-3: 32%;
+  --cairn-focus-dim-rail-active: 36%;
   --color-neutral: oklch(32% 0.012 75);
   --color-neutral-content: oklch(96% 0.004 75);
 
@@ -103,7 +112,7 @@
    >= 4.5:1 contrast on the dark bases. The polish pass tunes these values against the reference. */
 [data-theme='cairn-admin-dark'] {
   color-scheme: dark;
-  --font-body: 'Figtree Variable', system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+  --font-body: 'IBM Plex Sans Variable', system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
   --font-display: 'Bricolage Grotesque Variable', var(--font-body);
   --font-editor: 'iA Writer Mono', ui-monospace, monospace;
   font-family: var(--font-body);
@@ -119,6 +128,9 @@
   --color-base-300: oklch(30% 0.014 75);
   --color-base-content: oklch(93% 0.006 75);
 
+  /* Locked pair: pressed footer-toggle text (text-primary on the bg-primary/10 plate over
+     dark base-100) measures 4.66:1, only 0.16 above the AA floor. Do not darken dark
+     --color-primary without re-checking that pair. */
   --color-primary: oklch(68% 0.18 293);
   --color-primary-content: oklch(20% 0.04 293);
   --color-secondary: oklch(72% 0.02 75);
@@ -139,10 +151,10 @@
   --cairn-directive-rail-2: 74%;
   --cairn-directive-rail-3: 86%;
   /* Cursor-aware emphasis on dark: the caret container's own bar steps to a solid accent rail
-     (also 1px wider) and an ink one notch past depth 3. Locked pairs on base-100: rail = solid
-     accent (5.86:1, non-text floor 3:1), ink 82% (8.84:1, priced on the gamut-clipped sRGB
-     render; the 0.14 chroma sits outside sRGB at this lightness). Do not darken without
-     re-checking. */
+     at the same 2px width (strength only) and an ink one notch past depth 3. Locked pairs on
+     base-100: rail = solid accent (5.86:1, non-text floor 3:1), ink 82% (8.84:1, priced on the
+     gamut-clipped sRGB render; the 0.14 chroma sits outside sRGB at this lightness). Do not
+     darken without re-checking. */
   --cairn-directive-rail-active: 100%;
   --cairn-directive-ink-active: oklch(82% 0.14 300);
   /* The inline-code chip on dark sits one step above base-100 so it reads raised. Locked pair:
@@ -153,6 +165,12 @@
      the proposed 50% measured 2.74:1, under the 3:1 floor, so it sits at 53%. Locked pair on
      base-100: 3.12:1. Do not darken without re-checking. */
   --cairn-focus-dim-ink: oklch(53% 0.01 75);
+  /* Focus mode's rail percentages on dark, a third of the quiet 62/74/86 ramp; the same
+     deliberate sub-3:1 transient-state call as the dim ink. */
+  --cairn-focus-dim-rail-1: 21%;
+  --cairn-focus-dim-rail-2: 25%;
+  --cairn-focus-dim-rail-3: 29%;
+  --cairn-focus-dim-rail-active: 33%;
   --color-neutral: oklch(80% 0.01 75);
   --color-neutral-content: oklch(22% 0.008 75);
 
@@ -260,6 +278,13 @@
     outline-offset: -1px;
   }
 
+  /* Under focus mode the document title eases back with the rest of the context: at 30px bold
+     it would otherwise be the strongest ink on the page and pull the eye off the lit
+     paragraph. Its own focus restores full ink, so editing the title is never dimmed. */
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .cairn-doc-title-dim:not(:focus) {
+    color: var(--cairn-focus-dim-ink);
+  }
+
   /* Menu items come as anchors or buttons, and the omitted Preflight is what made them match:
      without it a button keeps the UA chrome (outset border, gray fill, centered system-font
      text) while its anchor siblings render flat. This scoped substitute levels the buttons to
@@ -274,12 +299,24 @@
     text-align: start;
   }
 
-  /* The admin topbar plus the edit page's sticky action header stack about 120px of veil over the
-     top of the content column, and a control the browser scrolls into view could land hidden
-     beneath them (WCAG 2.4.11 Focus Not Obscured). The scroll margin keeps any focus or fragment
-     scroll clear of the whole sticky stack. */
+  /* The same leveling for every bare admin button, not only menu items: a button styled with
+     utilities (the footer's posture segments and mode toggles, a list's sort-column headers, the
+     zen chip's exit) otherwise keeps the UA outset border and gray fill, since the admin omits
+     global Preflight. A .btn keeps its full DaisyUI chrome, and a utility (a bg-*, a border-l for
+     a segment divider) still wins from the utilities layer, so a control opts back into a border
+     or fill by naming it. */
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) button:not(.btn) {
+    border: 0 solid;
+    background-color: transparent;
+    font: inherit;
+    color: inherit;
+  }
+
+  /* The one header band is the 4rem topbar, and a control the browser scrolls into view could land
+     hidden beneath it (WCAG 2.4.11 Focus Not Obscured). The scroll margin keeps any focus or
+     fragment scroll clear of the sticky band, with a little slack. */
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) :is(a, button, input, textarea, select, summary, [tabindex]) {
-    scroll-margin-top: 8.5rem;
+    scroll-margin-top: 5.5rem;
   }
 }
 

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/fonts/{Figtree-OFL.txt → IBMPlexSans-OFL.txt}

@@ -1,4 +1,4 @@
-Copyright 2022 The Figtree Project Authors (https://github.com/erikdkennedy/figtree)
+Copyright 2019 IBM Corp. All rights reserved. IBMPlexSans-Italic[wdth,wght].ttf: Copyright 2019 IBM Corp. All rights reserved.
 
 This Font Software is licensed under the SIL Open Font License, Version 1.1.
 This license is copied below, and is also available with a FAQ at:
@@ -18,7 +18,7 @@ with others.
 
 The OFL allows the licensed fonts to be used, studied, modified and
 redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded, 
+fonts, including any derivative works, can be bundled, embedded,
 redistributed and/or sold with any software provided that any reserved
 names are not used by derivative works. The fonts and derivatives,
 however, cannot be released under any other type of license. The