@voithos-labs/aragonite 0.10.3 → 0.10.4

package/dist/selection/selection-drop.js

@@ -0,0 +1,253 @@
+/**
+ * Dragging a selection and dropping it. The browser's own version is two native edits committed
+ * apart — `deleteByDrag` on the source, `insertFromDrop` on the target — so undo takes two presses
+ * over a document that lost bytes in between, and inside one block the source commit rebuilds the
+ * surface under the drop. Owned here instead: one snapshot over two raw writes, which splice
+ * nothing, so no path moves under the second.
+ */
+import { emitClipboardError } from '../editor-events';
+import { ambientLengthOf } from '../ambient/ambient-dom';
+import { toClampedRawOffset } from '../cursor/coordinate-spaces';
+import { domTextOffsetAtNode } from '../cursor/widget-offset';
+import { trailingLineEnding, trimTrailingLineEnding } from '../core/lines';
+import { replaceRangeRaw } from '../components/blocks/text/live-selection-edit';
+import { blockNodeAt, emptyParagraph, writeOwnRaw } from '../tree-operations/node-primitives';
+import { cloneNode } from '../tree-operations/clone';
+import { cutRangeFromDisplay } from '../tree-operations/node-ops';
+import { rebuildAncestryRaw } from '../schema/container-raw';
+import { applyPasteTransforms } from '../tree-operations/paste/paste-transforms';
+import { replaceBlockAtParent } from '../tree-operations/paste/replace-block-at-parent';
+import { parseReplacement } from '../tree-operations/paste/replacement-parse';
+import { blockNearPoint } from './nearest-block';
+import { findSurfaceForElement } from './path-lookup';
+import { containerAmbientPrefix } from './range-delete';
+/** A drag that IS this gesture but whose shape the seam does not move — a range leaving its
+ *  surface, an empty one. The drop cancels it rather than handing it back. */
+const DECLINED = 'declined';
+// ── Public entry ───────────────────────────────────────────────────────────
+export function installSelectionDrop(deps) {
+    let source = null;
+    const onDragStart = (e) => {
+        source = readSelectionSource(deps.editorRoot, e.target);
+    };
+    const onDragEnd = () => {
+        source = null;
+    };
+    // The editor is the drop target for every drag this seam recognized, declined ones included:
+    // the drop below must RUN to cancel the browser's pair of native edits.
+    const onDragOver = (e) => {
+        if (source)
+            e.preventDefault();
+    };
+    const onDrop = (e) => {
+        const from = source;
+        source = null;
+        if (!from)
+            return;
+        // Before every decline below, not after: the browser's two edits land apart and its undo
+        // is not ours, so a shape this seam declines mutates nothing rather than half of it.
+        e.preventDefault();
+        if (from === DECLINED || deps.isReadOnly())
+            return;
+        const target = dropTarget(deps, e.clientX, e.clientY);
+        if (!target)
+            return;
+        const text = movedText(deps, from);
+        if (text === null)
+            return;
+        void runDrop(deps, from, target, text, e.ctrlKey || e.altKey).catch((error) => {
+            // A throw between the two writes leaves a snapshot pushed and half the move applied;
+            // the host hears it on the channel the paste route reports through.
+            emitClipboardError(deps.events, { error, path: from.path });
+        });
+    };
+    deps.editorRoot.addEventListener('dragstart', onDragStart);
+    deps.editorRoot.addEventListener('dragend', onDragEnd);
+    deps.editorRoot.addEventListener('dragover', onDragOver);
+    deps.editorRoot.addEventListener('drop', onDrop);
+    return () => {
+        deps.editorRoot.removeEventListener('dragstart', onDragStart);
+        deps.editorRoot.removeEventListener('dragend', onDragEnd);
+        deps.editorRoot.removeEventListener('dragover', onDragOver);
+        deps.editorRoot.removeEventListener('drop', onDrop);
+    };
+}
+/** Where a splice of `delta` blocks at `at` inside `parent` leaves `target`: what the drop's
+ *  second write addresses once the first one's reparse changed its slot's block count. */
+export function shiftPathAfterSplice(target, parent, at, delta) {
+    if (delta === 0 || target.length <= parent.length)
+        return target;
+    for (let i = 0; i < parent.length; i++)
+        if (target[i] !== parent[i])
+            return target;
+    if (target[parent.length] <= at)
+        return target;
+    const shifted = target.slice();
+    shifted[parent.length] += delta;
+    return shifted;
+}
+/** Where a drop at `offset` lands once `[start, end)` left the same block, `shrunkBy` bytes
+ *  shorter than the range was wide once the join seam cleaned up. Null inside the range. */
+export function dropOffsetAfterCut(offset, start, end, shrunkBy) {
+    if (offset > start && offset < end)
+        return null;
+    return offset <= start ? offset : Math.max(0, offset - shrunkBy);
+}
+// ── Reading the gesture ────────────────────────────────────────────────────
+/**
+ * The native range the drag carries, in its surface's raw offsets. `null` is "not this gesture" and
+ * leaves the drag to the browser; {@link DECLINED} is this gesture in a shape the seam does not
+ * move, which the drop cancels. A cross-block selection reaches neither: it paints through the
+ * overlay and leaves no native range for the browser to drag.
+ */
+function readSelectionSource(editorRoot, dragged) {
+    const sel = window.getSelection();
+    if (!sel || sel.isCollapsed || sel.rangeCount === 0)
+        return null;
+    const range = sel.getRangeAt(0);
+    // A draggable of its own (a rendered link, an image) is not this gesture, even with a range
+    // painted elsewhere: a selection drag grips a node the range covers.
+    if (!(dragged instanceof Node) || !range.intersectsNode(dragged))
+        return null;
+    const surface = surfaceOf(range.startContainer);
+    if (!surface || !editorRoot.contains(surface))
+        return null;
+    // Past this point the drag IS the editor's selection, so every remaining shape declines.
+    if (!surface.contains(range.endContainer))
+        return DECLINED;
+    const found = findSurfaceForElement(surface);
+    if (!found)
+        return DECLINED;
+    const ambient = ambientLengthOf(surface);
+    const start = toClampedRawOffset(domTextOffsetAtNode(surface, range.startContainer, range.startOffset), ambient);
+    const end = toClampedRawOffset(domTextOffsetAtNode(surface, range.endContainer, range.endOffset), ambient);
+    return start < end ? { ...found, start, end } : DECLINED;
+}
+/** The block and offset a drop point addresses, as a single-click caret would land. Null where
+ *  the point names no character position (a whole-block unit, a table cell). */
+function dropTarget(deps, clientX, clientY) {
+    const near = blockNearPoint(deps.editorRoot, clientX, clientY);
+    const point = near?.endpointHere();
+    if (!point || !('offset' in point) || point.cellCoordinate)
+        return null;
+    return blockNodeAt(deps.getDoc(), point.path) ? { path: point.path, offset: point.offset } : null;
+}
+/** The source surface's own bytes for the range, past the paste transforms. Null for a payload
+ *  this seam does not own: a line break needs the structural paste route. */
+function movedText(deps, from) {
+    const node = blockNodeAt(deps.getDoc(), from.path);
+    if (!node)
+        return null;
+    const raw = trimTrailingLineEnding(node.raw).slice(from.start, from.end);
+    const text = applyPasteTransforms(raw, deps.activePlugins);
+    return text && !/[\r\n]/.test(text) ? text : null;
+}
+// ── The commit ceremony ────────────────────────────────────────────────────
+async function runDrop(deps, from, to, text, copy) {
+    if (copy) {
+        await writeBlockRaw(deps, to.path, insert(to.offset, text), to.offset + text.length, true);
+        return;
+    }
+    const cut = cutFrom(deps, from);
+    if (!cut)
+        return;
+    if (pathsEqual(cut.path, to.path)) {
+        const offset = dropOffsetAfterCut(to.offset, from.start, from.end, cut.shrunkBy);
+        if (offset === null)
+            return;
+        const merged = spliceAt(cut.raw, offset, text);
+        await writeBlockRaw(deps, cut.path, () => merged, offset + text.length, true);
+        return;
+    }
+    deps.controller.pushUndoSnapshotPath(from.path, from.start);
+    // A table's caret door reads a cell landing, never a character offset (G1.29), so the
+    // transient caret the second write moves off is its first cell.
+    const sourceCaret = from.inCell ? 0 : from.start;
+    const spliced = await writeBlockRaw(deps, cut.path, () => cut.raw, sourceCaret, false);
+    const at = cut.path[cut.path.length - 1];
+    const target = shiftPathAfterSplice(to.path, cut.path.slice(0, -1), at, spliced);
+    await writeBlockRaw(deps, target, insert(to.offset, text), to.offset + text.length, false);
+}
+function insert(offset, text) {
+    return (raw) => spliceAt(raw, offset, text);
+}
+/** The source surface's display bytes with the dragged range gone, through the delete seam so a
+ *  live-mode join cleans up after itself. */
+function cutFrom(deps, from) {
+    const node = blockNodeAt(deps.getDoc(), from.path);
+    if (!node)
+        return null;
+    if (from.inCell)
+        return cutFromCell(deps, from, node);
+    const before = trimTrailingLineEnding(node.raw);
+    const edit = replaceRangeRaw(node, { start: from.start, end: from.end }, '', deps.getPresentationMode?.(), deps.linkRef, containerAmbientPrefix(deps.getDoc(), from.path));
+    const raw = trimTrailingLineEnding(edit.raw);
+    return { path: from.path, raw, shrunkBy: before.length - raw.length };
+}
+/** A cell's bytes are joined into its row, so the TABLE is the block the cut rewrites: the cell's
+ *  own range-delete on a copy, then the kind's escape and the ancestry rebuild around it. */
+function cutFromCell(deps, from, cell) {
+    const tablePath = from.path.slice(0, -2);
+    // The cell path is resolved from a DOM selector contract, so the kind is read, not assumed.
+    const table = blockNodeAt(deps.getDoc(), tablePath);
+    if (!table || table.kind !== 'table')
+        return null;
+    const cut = cutRangeFromDisplay(cell, cell.raw, { start: from.start, end: from.end }, deps.getPresentationMode?.(), deps.linkRef);
+    const rebuilt = cloneNode(table);
+    const inner = from.path.slice(-2);
+    const [rowIdx, colIdx] = inner;
+    const written = rebuilt.children?.[rowIdx]?.children?.[colIdx];
+    if (!written)
+        return null;
+    writeOwnRaw(written, cut.display, deps.grammar);
+    rebuildAncestryRaw(rebuilt, inner);
+    const raw = trimTrailingLineEnding(rebuilt.raw);
+    return { path: tablePath, raw, shrunkBy: trimTrailingLineEnding(table.raw).length - raw.length };
+}
+/**
+ * Replace the block at `path` with the reparse of the bytes `rewrite` returns, at its parent
+ * scope. Answers how many blocks the slot grew or shrank by, which is what keeps a second
+ * write's path honest. `own` pushes this write's own undo entry.
+ */
+async function writeBlockRaw(deps, path, rewrite, caret, own) {
+    const doc = deps.getDoc();
+    const node = blockNodeAt(doc, path);
+    if (!node)
+        return 0;
+    const written = rewrite(trimTrailingLineEnding(node.raw));
+    // A block emptied by the cut keeps its slot as a blank paragraph: no splice, so the second
+    // write's path is still the one this gesture resolved.
+    const parsed = parseReplacement(node, written, deps.grammar, () => [
+        emptyParagraph(node.leadingTrivia ?? '', trailingLineEnding(node.raw))
+    ]);
+    if (!parsed)
+        return 0;
+    const landed = await replaceBlockAtParent({
+        doc,
+        blockPath: path,
+        replacement: parsed.replacement,
+        controller: deps.coordinator,
+        undoEntry: own ? 'own' : 'join',
+        focusReplacementIndex: parsed.replacement.length - 1,
+        focusOffset: caret,
+        source: 'selection-drop',
+        ...(deps.grammar ? { grammar: deps.grammar } : {})
+    });
+    // The LANDED count, not the parse's: a body rule inside the scope can rewrite the list. Zero
+    // is the unmounted-scope decline, which wrote nothing and so moved nothing.
+    return Math.max(0, landed - 1);
+}
+// ── Small helpers ──────────────────────────────────────────────────────────
+function spliceAt(raw, offset, text) {
+    const at = Math.max(0, Math.min(offset, raw.length));
+    return raw.slice(0, at) + text + raw.slice(at);
+}
+function pathsEqual(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+function surfaceOf(node) {
+    let el = node instanceof HTMLElement ? node : node.parentElement;
+    while (el && el.contentEditable !== 'true')
+        el = el.parentElement;
+    return el;
+}

package/dist/styles/editor-theme.css

@@ -69,6 +69,10 @@
 	   --color-bg-secondary, which is measured against the base bg. */
 	--color-ui-faint: rgba(255, 255, 255, 0.07);
 
+	/* One radius for a picture, the crop frame that clips it and the selection ring on the
+	   overlay above it: half the surface radius, enough to soften a photo without a card look. */
+	--md-image-radius: 4px;
+
 	/* Markdown syntax override points, deliberately neutral so the default rendering carries no
 	   extra palette. Mode-independent: the chrome tokens they chain to carry the light/dark
 	   split. */
@@ -112,8 +116,8 @@
 	/* Presentational tokens (mode-independent). */
 	/* Washes over the host-declarable selection base, alpha apart, so a host that names one
 	   base moves the selection, the search matches and the reorder chrome together. */
-	--selection-overlay-bg: color-mix(in srgb, var(--color-selection, #6496ff) 30%, transparent);
-	--search-match-bg: color-mix(in srgb, var(--color-selection, #6496ff) 22%, transparent);
+	--selection-overlay-bg: rgba(100, 150, 255, 0.3);
+	--search-match-bg: rgba(100, 150, 255, 0.22);
 	/* Painted on top of the match text, so it must keep an alpha channel or it hides it. */
 	--search-match-active-bg: rgba(216, 166, 87, 0.55);
 	--md-ref-label-color: rgba(128, 128, 128, 0.45);
@@ -125,7 +129,7 @@
 	--md-reorder-indicator: var(--color-selection, #6496ff);
 	/* Wash on the container being reordered within during a nested drag. Tinted with the reorder
 	   accent, not neutral grey, so the shift stays perceptible for low-contrast vision. */
-	--reorder-scope-bg: color-mix(in srgb, var(--color-selection, #6496ff) 14%, transparent);
+	--reorder-scope-bg: rgba(100, 150, 255, 0.14);
 	--syntax-marker-dim: 0.65;
 
 	/* Menu/popout elevation, per mode: a shadow tuned for a near-black surface is invisible
@@ -143,6 +147,17 @@
 	--vr-spacer-bg: rgba(255, 255, 255, 0.025);
 }
 
+/* The washes follow a host's `--color-selection` where the engine can mix; the static values
+   above are the same tints of the default base, for engines without `color-mix` (WebKit before
+   Safari 16.2). */
+@supports (color: color-mix(in srgb, red, blue)) {
+	:where(.editor, .aragonite-editor-theme) {
+		--selection-overlay-bg: color-mix(in srgb, var(--color-selection, #6496ff) 30%, transparent);
+		--search-match-bg: color-mix(in srgb, var(--color-selection, #6496ff) 22%, transparent);
+		--reorder-scope-bg: color-mix(in srgb, var(--color-selection, #6496ff) 14%, transparent);
+	}
+}
+
 :where(.editor, .aragonite-editor-theme)[data-editor-theme='light'] {
 	--color-bg-secondary: rgba(0, 0, 0, 0.035);
 	--color-bg-elevated: #f5f6f8;

package/dist/styles/editor.css

@@ -168,9 +168,7 @@
 	max-width: 100%;
 	height: auto;
 	display: block;
-	/* Enough to take the hard corner off a photo sitting in prose, not enough to read as a
-	   card: half the surface radius the block chrome uses. */
-	border-radius: 4px;
+	border-radius: var(--md-image-radius);
 }
 
 /* A cropped image: the widget is the frame (width and aspect set inline from the `|WxH` hint,
@@ -178,15 +176,16 @@
 :where(.editor) .md-image-widget.md-image-cropped {
 	overflow: hidden;
 	max-width: 100%;
-	/* The frame clips the picture, so the rounding belongs to it; the picture inside is square
-	   again or its own corners would cut inside the frame's. */
-	border-radius: 4px;
-}
-
-:where(.editor) .md-image-widget.md-image-cropped img {
-	border-radius: 0;
+	/* The frame clips the picture, so the rounding belongs to it. `clip-path` alongside
+	   `overflow`, because a rounded overflow clip is the one Chromium drops when the picture
+	   inside gets its own compositing layer, and a crop is exactly when that happens. */
+	border-radius: var(--md-image-radius);
+	clip-path: inset(0 round var(--md-image-radius));
 }
 
+/* The picture keeps its own radius rather than going square inside the frame: at zoom 1 it sits
+   exactly on the frame, so the two corners coincide, and above 1 its corners are outside the
+   frame entirely. Either way the crop cannot come out with harder corners than the plain image. */
 :where(.editor) .md-image-widget.md-image-cropped img {
 	position: absolute;
 	max-width: none;
@@ -321,6 +320,20 @@
 	z-index: 10;
 }
 
+/* A selected image says so with a hairline ring. It rides the overlay, not the widget: a cropped
+   widget clips its own pseudo-elements, and a border on the picture would move the layout. Held
+   just off the edge so it reads as a ring around the picture rather than part of it, over a
+   translucent dark line that keeps it legible against a pale photo. */
+:where(.editor) .md-image-overlay::before {
+	content: '';
+	position: absolute;
+	inset: -2px;
+	border: 1px solid var(--color-accent, #567b67);
+	border-radius: calc(var(--md-image-radius, 4px) + 2px);
+	box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.18);
+	pointer-events: none;
+}
+
 :where(.editor) .md-image-overlay > * {
 	pointer-events: auto;
 }
@@ -652,12 +665,16 @@
 	.task-checkbox::before {
 	content: '';
 	visibility: visible;
+	/* Centred by layout and sized to whole pixels, never by a translate: a transformed box
+	   rasterises at fractional edges on a scaled desktop and reads shorter than it is wide.
+	   The unrounded pair is the fallback for a browser without `round()`. */
 	position: absolute;
-	left: 50%;
-	top: 50%;
+	inset: 0;
+	margin: auto;
 	width: 1.2em;
 	height: 1.2em;
-	transform: translate(-50%, -50%);
+	width: round(1.2em, 1px);
+	height: round(1.2em, 1px);
 	box-sizing: border-box;
 	border: 1.5px solid var(--color-ui-muted, #8f8f89);
 	border-radius: 0.28em;
@@ -699,6 +716,40 @@
 	transform: translate(-50%, -50%) rotate(45deg);
 }
 
+/* The span is the SLOT, a full line-height tall; the box is the pseudo-element inside it. The
+   hover tint the source modes put on the span (ListItemBlock) would draw a tall rectangle
+   round the square, so in the rendered modes it moves onto the box: an open box fills with
+   the tint, a checked one is already a solid fill and keeps it. */
+:where(.editor):is(
+		[data-presentation='reading'],
+		[data-presentation^='preview-'],
+		[data-presentation='live']
+	)
+	.list-item-block[data-list-marker='task']
+	.task-checkbox:hover {
+	background-color: transparent;
+}
+
+:where(.editor):is(
+		[data-presentation='reading'],
+		[data-presentation^='preview-'],
+		[data-presentation='live']
+	)
+	.list-item-block[data-list-marker='task']
+	.task-checkbox::before {
+	transition: background-color 60ms ease-out;
+}
+
+:where(.editor):is(
+		[data-presentation='reading'],
+		[data-presentation^='preview-'],
+		[data-presentation='live']
+	)
+	.list-item-block[data-list-marker='task']:not([data-task-checked='true'])
+	.task-checkbox:hover::before {
+	background-color: var(--md-marker-hover-bg, rgba(128, 128, 128, 0.15));
+}
+
 /* ── Reading mode ─────────────────────────────────────────────────────────────
    The marker-hiding families reading shares with the preview rungs and `live` are in the
    section above; reading adds only its read-only inertness on top — `live` takes none of it. */

package/dist/tree-operations/paste/replace-block-at-parent.d.ts

@@ -26,4 +26,6 @@ export interface ReplaceBlockAtParentArgs {
     /** The clipboard's own trailing blank line, where nothing in the splice stands for it. */
     trailingSeparator?: string;
 }
-export declare function replaceBlockAtParent(args: ReplaceBlockAtParentArgs): Promise<void>;
+/** Answers how many blocks LANDED in the slot — the body rule below can rewrite the list, so a
+ *  caller whose next write addresses a later sibling asks here rather than counting its own. */
+export declare function replaceBlockAtParent(args: ReplaceBlockAtParentArgs): Promise<number>;

package/dist/tree-operations/paste/replace-block-at-parent.js

@@ -25,12 +25,14 @@ function landTrailingSeparator(args, children, afterIndex, ending) {
         return;
     args.doc.suffix = ending;
 }
+/** Answers how many blocks LANDED in the slot — the body rule below can rewrite the list, so a
+ *  caller whose next write addresses a later sibling asks here rather than counting its own. */
 export async function replaceBlockAtParent(args) {
     const { doc, blockPath, controller, undoEntry, focusOffset, source } = args;
     const blockIdx = blockPath[blockPath.length - 1];
     const scope = resolveParentScope(doc, blockPath, controller);
     if (!scope)
-        return;
+        return 0;
     // A replacement is minted before any byte sink sees it, so the owner's bodyWrite escape
     // lands here — on the clipboard blocks AND the target's split halves alike.
     const ownerKind = blockPath.length > 1 ? scope.node.kind : undefined;
@@ -72,4 +74,5 @@ export async function replaceBlockAtParent(args) {
             return controller.landCaret([...scope.path, caret.index], landedPasteOffset(landed, caret, focusOffset));
         }
     });
+    return replacement.length;
 }

package/dist/tree-operations/paste/replacement-parse.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The bytes a block is replaced BY, parsed the one way every replace-at-parent caller needs them:
+ * terminated in the original's own line ending (G4.20), reparsed in the instance grammar, carrying
+ * the original's leading trivia, with editable containers ensured.
+ */
+import type { CstNode } from '../../core/nodes';
+import type { GrammarView } from '../../schema/block-openers';
+export interface ParsedReplacement {
+    replacement: CstNode[];
+    /** The parse's own trailing blank, for a caller that lands one (`paste/dispatch.ts`). */
+    suffix: string;
+}
+/**
+ * Null where `raw` parses to nothing and the caller named no `fallback` — the block keeps its
+ * bytes rather than being replaced by an empty splice.
+ */
+export declare function parseReplacement(original: CstNode, raw: string, grammar: GrammarView | undefined, fallback?: () => CstNode[]): ParsedReplacement | null;

package/dist/tree-operations/paste/replacement-parse.js

@@ -0,0 +1,22 @@
+/**
+ * The bytes a block is replaced BY, parsed the one way every replace-at-parent caller needs them:
+ * terminated in the original's own line ending (G4.20), reparsed in the instance grammar, carrying
+ * the original's leading trivia, with editable containers ensured.
+ */
+import { parse } from '../../core/parser';
+import { terminateLine } from '../../core/lines';
+import { ensureEditableContainers, normalizeReplacementTrivia } from '../node-primitives';
+/**
+ * Null where `raw` parses to nothing and the caller named no `fallback` — the block keeps its
+ * bytes rather than being replaced by an empty splice.
+ */
+export function parseReplacement(original, raw, grammar, fallback) {
+    const parsed = parse(terminateLine(raw, original.raw), { grammar, scope: 'fragment' });
+    const children = parsed.children.length > 0 ? parsed.children : fallback?.();
+    if (!children || children.length === 0)
+        return null;
+    const replacement = normalizeReplacementTrivia(original, children);
+    for (const node of replacement)
+        ensureEditableContainers(node);
+    return { replacement, suffix: parsed.suffix };
+}

package/docs/guide/consumer-guide.md

@@ -130,10 +130,11 @@ Everything supported is exported from `@voithos-labs/aragonite`. Before 1.0 the
 | `blockDragHandles` | The block drag handle, revealed on hover and shown outright on touch (default on; reading mode hides it). Only object blocks carry one — code, tables, equations, diagrams, pictures, list items, dividers, cards — never prose. `false` removes them, except on a picture; keyboard reorder (Alt+Arrow) and the cell menu need no opt-in |
 | `searchBar`        | The built-in find/replace bar and its Mod+F / Mod+H shortcuts (default on)                                                                                                                                                                                                                                                                |
 | `searchBarAnchor`  | An element to render that same bar into, instead of inside the editor root (see [Where the find bar lives](#where-the-find-bar-lives))                                                                                                                                                                                                    |
+| `selectionToolbar` | The built-in formatting popover over a selection: the marks, the link, a heading picker, inline code and copy (default on; reading mode never shows it; see [Recipe: a selection toolbar](#recipe-a-selection-toolbar))                                                                                                                   |
 
 **Set once at mount:** `resolveImageUrl`, `resolveLinkUrl`, `imageLoadPolicy`, `onLinkActivate`, `onPasteImage`, `onRunCode`, `codeMenuItems`, `blockDragHandles`, `scrollMode`, and `plugins`. Set them at mount and leave them; a swap later isn't guaranteed to reach blocks that are already built.
 
-**Read live:** `theme`, `searchBar`, `searchBarAnchor`, `presentationMode`, and `keybindings` may change after mount, and `header` re-renders like any other Svelte snippet.
+**Read live:** `theme`, `searchBar`, `searchBarAnchor`, `selectionToolbar`, `presentationMode`, and `keybindings` may change after mount, and `header` re-renders like any other Svelte snippet.
 
 ## The instance surface
 
@@ -283,8 +284,8 @@ editor.runCommand('nope'); // false, unknown id, nothing changed
 
 The ids you can pass:
 
-- **`TOOLBAR_COMMANDS`** (exported from the package) has what a selection toolbar needs: `toggleStrong`, `toggleEmphasis`, `toggleStrikethrough`, `toggleCode`, and `editLink`. The rest of the built-in commands stay internal for now.
-- **`heading.cycle`, with a level.** The arm behind `Mod+0` to `Mod+6`: `runCommand('heading.cycle', 2)` re-marks the focused prose block as a level-2 heading and `0` makes it a paragraph, which is what a heading picker calls.
+- **`TOOLBAR_COMMANDS`** (exported from the package) has what a selection toolbar needs: `toggleStrong`, `toggleEmphasis`, `toggleStrikethrough`, `toggleCode`, `editLink`, and `setHeading`. The rest of the built-in commands stay internal for now.
+- **`setHeading`, with a level.** The arm behind `Mod+0` to `Mod+6`: `runCommand(TOOLBAR_COMMANDS.setHeading, 2)` re-marks the focused prose block as a level-2 heading and `0` makes it a paragraph, which is what a heading picker calls. A heading level belongs to one block, so over a selection spanning blocks it declines rather than guessing which block you meant.
 - **A plugin's global command name.** `registerGlobalCommand` registers it (see the [plugin guide](plugin-guide.md)), and it resolves ahead of the focused block, so you can fire a plugin's editor-wide action without a keystroke. A plugin's per-block command stays keyboard-only.
 
 `arg` is the argument a keymap binding would bake in (`{ chord: 'Mod+2', command: 'heading.cycle', arg: 2 }`), handed to the command as it is; a command that takes none ignores it.
@@ -292,7 +293,7 @@ The ids you can pass:
 What the boolean means:
 
 - **`true` means the editor took the command, not that the edit has landed.** A toggle inside a construct whose markers a preview mode has revealed (see [Presentation modes](#presentation-modes)) settles that reveal first, so read the outcome on the `edit` channel rather than polling `getSource()`.
-- **`false` means nothing changed**: an unknown id, reading mode, a command that needs a focused block when none is, or the link editor over a selection spanning blocks (a link lives inside one block, and a range across blocks gives it none).
+- **`false` means nothing changed**: an unknown id, reading mode, a command that needs a focused block when none is, or the link editor or a heading level over a selection spanning blocks (a link lives inside one block, a heading level is one block's, and a range across blocks gives them none).
 
 Two more things before you wire buttons:
 
@@ -301,12 +302,13 @@ Two more things before you wire buttons:
 
 `canRunCommand(commandId: string): boolean`
 
-Tells you whether `runCommand(id)` would reach the command right now, which is what greys a toolbar button out instead of hiding it. It answers `false` exactly where `runCommand` declines before dispatch: an unknown id, reading mode, a block-scoped id with nothing focused, and the link editor while the selection spans blocks. `true` means reachable, not that it'll write (across blocks it may find no block that can hold the mark), so keep reading `runCommand`'s boolean too.
+Tells you whether `runCommand(id)` would reach the command right now, which is what greys a toolbar button out instead of hiding it. It answers `false` exactly where `runCommand` declines before dispatch: an unknown id, reading mode, a block-scoped id with nothing focused, and the link editor or a heading level while the selection spans blocks. `true` means reachable, not that it'll write (across blocks it may find no block that can hold the mark), so keep reading `runCommand`'s boolean too.
 
 ```ts
 // with a selection spanning two paragraphs
 editor.canRunCommand(TOOLBAR_COMMANDS.toggleStrong); // true
 editor.canRunCommand(TOOLBAR_COMMANDS.editLink); // false, a link can't span blocks
+editor.canRunCommand(TOOLBAR_COMMANDS.setHeading); // false, a heading level is one block's
 ```
 
 `isCommandActive(commandId: string): boolean`
@@ -1047,7 +1049,7 @@ The bundled toc plugin does exactly that walk over its live document, and clicki
 
 ### Recipe: a selection toolbar
 
-Float a formatting bar above the user's selection. Nine steps, and the anchoring ones have a snippet after the list:
+The editor ships one: a popover that opens beside a prose selection with the marks, the link, a heading picker (inside one block only), inline code and copy, on by default and off with `selectionToolbar={false}`. It is built on the doors below and nothing else, so this recipe is also how to replace it with your own. Nine steps, and the anchoring ones have a snippet after the list:
 
 1. **Subscribe to `selectionChange`.** A `null` payload or a collapsed selection (anchor equals focus) hides the bar.
 2. **Put the endpoints in document order first.** `normalizeSelection(snapshot)` answers `{ start, end }` (by path, then by offset when the paths match), so a backward drag anchors exactly like a forward one. Anchor to `start`; a hand-rolled comparison gets the container-and-its-child pair wrong, where the shorter path is the earlier one.
@@ -1055,7 +1057,7 @@ Float a formatting bar above the user's selection. Nine steps, and the anchoring
 4. **Single-block selections**: `getSelection()` reports the range's real endpoints, so anchor with `rangeRects(start.path, start.offset, end.offset)`, the same call with a real end offset in place of `SELECTION_END`. (Reading the native `window.getSelection()` range works too, since within one block the editor delegates selection to the browser.) A selection **inside a table** shares the table's path on both endpoints and carries cell indices in `offset`, which the `cellCoordinate` flag need not mark, so exclude it with `getBlockKindAt(start.path) === 'table'`, never by the flag alone.
 5. **Re-anchor on the next `selectionChange`, not on scroll.** Rects are viewport-space snapshots; a `position: fixed` bar drifts under scroll until the selection next changes. Wire a scroll listener only if your UX demands live tracking.
 6. **Fire the buttons through `runCommand`, not synthetic keystrokes.** `runCommand(TOOLBAR_COMMANDS.toggleStrong)` says what the button means; a synthesized `Ctrl+B` says which key the button impersonates, and a user's rebind then silently rewires it.
-7. **Grey the declining buttons out with `canRunCommand`, on the same `selectionChange`.** Ask it per button and disable the ones that answer `false`, so a selection spanning blocks shows the link button dimmed rather than dead while the format toggles stay live. Still read `runCommand`'s boolean, per [Toolbar commands](#toolbar-commands).
+7. **Grey the declining buttons out with `canRunCommand`, on the same `selectionChange`.** Ask it per button and disable the ones that answer `false`, so a selection spanning blocks shows the link button dimmed rather than dead while the format toggles stay live (the editor's own bar goes one further and drops a labelled row the door declines, which is why its heading picker vanishes there). Still read `runCommand`'s boolean, per [Toolbar commands](#toolbar-commands).
 8. **Paint the pressed states with `isCommandActive`, on that same `selectionChange`.** A selection already inside a bold run shows the bold button pressed (`aria-pressed` is the accessible spelling), and pressing it then unwraps: the pressed paint and the press read the same bytes, so they agree by construction. In live mode a selection sitting inside a link shows the link button pressed the same way, off the link the card would edit, and clicking it opens that link's card with the selection left alone; a selection that runs out of the link isn't inside it, so the button unpresses and the click falls back to creating a new link over the range.
 9. **Keep focus in the document**, for the same reason the insert toolbar does: cancel the button's mousedown default, or restore a `getSelection()` snapshot before calling.
 
@@ -1073,7 +1075,7 @@ editor.getEvents().on('selectionChange', (sel) => {
 });
 ```
 
-The repository's `SelectionToolbar` component, mounted by the showcase's live mode and the dev harness alike, is this recipe end to end: both anchoring branches, the table exclusion, the five `TOOLBAR_COMMANDS` buttons greyed by `canRunCommand` and pressed by `isCommandActive`, and the mousedown cancel that keeps the caret in the document.
+The editor's own bar (`src/lib/components/menu/SelectionToolbar.svelte`) is this recipe end to end: both anchoring branches, the table exclusion, the `TOOLBAR_COMMANDS` buttons greyed by `canRunCommand` and pressed by `isCommandActive`, and the mousedown cancel that keeps the caret in the document.
 
 ### Recipe: an insert toolbar