@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/plugins/latex/math-source.js

@@ -1,97 +1,58 @@
 /**
- * The `$$` block's source as DOM, shaped like a code block's: each fence line in a
- * `.md-fence-line` wrapper the marker-hiding modes collapse, the body as LaTeX highlight
- * tokens. Text-preserving by construction — opener + body + closer is the input — so the
- * offset walk and G1.28 hold. Anything not shaped like a fence paints as plain tokens.
+ * The block form's source as DOM, drawn the way a code block draws its own: the fence lines as
+ * markers the marker-hiding modes collapse, the body as highlighted LaTeX tokens. It emits exactly
+ * the source's text, so the DOM-to-offset traversal stays exact (G1.28). Anything not shaped like
+ * a fence paints as plain tokens.
  */
-import { highlightCode } from '../../plugin';
+import { displayLines, fenceBodyAsDrawn, highlightCode, isBlankText, renderFencedSource, sliceFencedSource } from '../../plugin';
 const FENCE = '$$';
+const unsliced = (text) => ({ opener: '', body: text, closer: '' });
+/** Both block forms are an opener line, a body and a closer line. GitHub's ```math reads as a code
+ *  fence does; the `$$` form closes on a line that is exactly `$$`, or on line 0 itself. */
 function sliceMathSource(text) {
     if (!text.startsWith(FENCE))
-        return { opener: '', body: text, closer: '' };
-    const firstNewline = text.indexOf('\n');
-    // One-line form: `$$x^2$$`.
-    if (firstNewline === -1) {
-        if (text.length >= 4 && text.endsWith(FENCE)) {
-            return { opener: FENCE, body: text.slice(2, -2), closer: FENCE };
-        }
-        return { opener: '', body: text, closer: '' };
+        return sliceFencedSource(text) ?? unsliced(text);
+    const firstBreak = text.indexOf('\n');
+    if (firstBreak === -1) {
+        return text.length >= 4 && text.endsWith(FENCE)
+            ? { opener: FENCE, body: text.slice(2, -2), closer: FENCE }
+            : unsliced(text);
     }
-    if (text.slice(0, firstNewline) !== FENCE)
-        return { opener: '', body: text, closer: '' };
-    const opener = text.slice(0, firstNewline + 1);
+    if (displayLines(text)[0].text !== FENCE)
+        return unsliced(text);
+    const opener = text.slice(0, firstBreak + 1);
     const rest = text.slice(opener.length);
-    const lastNewline = rest.lastIndexOf('\n');
-    const lastLine = lastNewline === -1 ? rest : rest.slice(lastNewline + 1);
+    const lastBreak = rest.lastIndexOf('\n');
+    const lastLine = rest.slice(lastBreak + 1);
     if (lastLine !== FENCE)
         return { opener, body: rest, closer: '' };
-    if (lastNewline === -1)
-        return { opener, body: '', closer: FENCE };
-    // The newline before the closer belongs to the closer's line (the code block's rule), so
-    // collapsing that line leaves no blank line at the box's edge — unless the body is blank,
-    // where that newline IS the one line the caret can sit on.
-    const bodyWithEnding = rest.slice(0, lastNewline + 1);
-    if (!/\S/.test(bodyWithEnding))
-        return { opener, body: bodyWithEnding, closer: FENCE };
-    return { opener, body: rest.slice(0, lastNewline), closer: rest.slice(lastNewline) };
-}
-function fenceLine(text) {
-    const line = document.createElement('span');
-    line.className = 'md-fence-line';
-    const marker = document.createElement('span');
-    marker.className = 'md-marker md-fence';
-    marker.textContent = text.replace(/\n$/, '').replace(/^\n/, '');
-    if (text.startsWith('\n'))
-        line.appendChild(document.createTextNode('\n'));
-    line.appendChild(marker);
-    if (text.endsWith('\n'))
-        line.appendChild(document.createTextNode('\n'));
-    return line;
+    return { opener, body: rest.slice(0, lastBreak + 1), closer: lastLine };
 }
 /**
- * Where the body sits inside the block's source. The fence lines carry no glyph of their own, so
- * a point measured against the rendered equation names a place in this span and nowhere else.
+ * Where the body sits inside the block's source. The fence lines paint no glyphs of their own,
+ * so a point measured against the rendered equation can only name a place inside this span.
  */
 export function mathBodySpan(text) {
-    if (/^[ \t]*(?:`{3,}|~{3,})/.test(text)) {
-        const firstBreak = text.indexOf('\n');
-        if (firstBreak === -1)
-            return { start: text.length, end: text.length };
-        const closer = /(?:\r?\n)?[ \t]*(?:`{3,}|~{3,})[ \t]*\r?\n?$/.exec(text);
-        return { start: firstBreak + 1, end: closer ? closer.index : text.length };
-    }
-    const { opener, body } = sliceMathSource(text);
-    return { start: opener.length, end: opener.length + body.length };
+    const source = sliceMathSource(text);
+    const start = source.opener.length;
+    return { start, end: start + fenceBodyAsDrawn(source).length };
 }
-/**
- * A `$$` block with no body LINE — `$$$$`, `$$\n$$`, a whitespace-only one-liner — has nowhere
- * for a caret to sit once the fence lines hide, and Backspace has no byte it could mean. The
- * completion every such block takes as its source is revealed: opener, one empty body line,
- * closer, caret on that line. A block that already has a body line, blank or not, is left alone.
- */
+/** A block with no body line (`$$$$`, `$$\n$$`) has no caret position once the fence lines hide,
+ *  so it gains one empty body line with the caret on it. */
 export function completeBareMathSource(text) {
     const { opener, body, closer } = sliceMathSource(text);
     if (!opener || !closer)
         return null;
-    if (body.includes('\n') || body.trim() !== '')
+    if (body.includes('\n') || !isBlankText(body))
         return null;
-    const completed = `${FENCE}\n\n${FENCE}`;
-    return { text: completed, caret: FENCE.length + 1 };
+    // A one-line `$$$$` has no ending of its own to repeat.
+    const [openerLine] = displayLines(opener);
+    const ending = openerLine.ending || '\n';
+    return {
+        text: openerLine.text + ending + ending + closer,
+        caret: openerLine.text.length + ending.length
+    };
 }
 export function renderMathSource(text) {
-    const { opener, body, closer } = sliceMathSource(text);
-    const frag = document.createDocumentFragment();
-    if (opener)
-        frag.appendChild(fenceLine(opener));
-    frag.appendChild(highlightCode(body, 'latex'));
-    // An empty last body line has only the hidden closer after it; the anchor gives the caret
-    // that line (see `code-renderer.ts`).
-    if (closer.startsWith('\n') && body.endsWith('\n')) {
-        const anchor = document.createElement('br');
-        anchor.dataset.caretAnchor = 'closer';
-        frag.appendChild(anchor);
-    }
-    if (closer)
-        frag.appendChild(fenceLine(closer));
-    return frag;
+    return renderFencedSource(sliceMathSource(text), (body) => highlightCode(body, 'latex'));
 }

package/dist/plugins/latex/register.d.ts

@@ -1,19 +1,18 @@
 /**
- * `renderer` is required because there is no baked-in default engine; `katexRenderer`
- * is the one-import path. The plugin unit installs this setup once per process, so it
- * runs unguarded.
+ * `katexRenderer` is the one-import way to supply `renderer`; without one, each formula shows its
+ * source. The plugin installs this setup once per process, so it runs unguarded.
  */
 import { type EditorPlugin } from '../../plugin';
 import { type MathRenderer } from './math-renderer';
 import { type MathBlockLayout } from './math-layout';
 export interface LatexPluginOptions {
-    renderer: MathRenderer;
-    /**
-     * How a `$$` block opens for editing: `split` (source beside the preview, the default),
-     * `stacked` (preview below), or `source` (no preview). Definition-time, so it is the
-     * bare-install default; an editor's `{ plugin, options: { blockLayout } }` entry overrides it
-     * per instance. The block's own toggle cycles from whichever applies.
-     */
+    renderer?: MathRenderer;
+    /** How a `$$` block opens for editing (`math-layout.ts`); an editor's
+     *  `{ plugin, options: { blockLayout } }` entry overrides it. */
     blockLayout?: MathBlockLayout;
 }
-export declare function latexPlugin(options: LatexPluginOptions): EditorPlugin;
+/** What one editor reads: the renderer is process-wide, so only the layout varies per editor. */
+export interface LatexEditorOptions {
+    blockLayout: MathBlockLayout;
+}
+export declare function latexPlugin(options?: LatexPluginOptions): EditorPlugin;

package/dist/plugins/latex/register.js

@@ -1,25 +1,39 @@
 /**
- * `renderer` is required because there is no baked-in default engine; `katexRenderer`
- * is the one-import path. The plugin unit installs this setup once per process, so it
- * runs unguarded.
+ * `katexRenderer` is the one-import way to supply `renderer`; without one, each formula shows its
+ * source. The plugin installs this setup once per process, so it runs unguarded.
  */
-import { definePlugin, registerBlockComponent, defineBlockComponent, declaredPluginKind } from '../../plugin';
+import { definePlugin, registerBlockComponent, defineBlockComponent, declaredPluginKind, registerInsertEntry } from '../../plugin';
 import { registerMathInline, registerMathBlock, MATH_BLOCK, MATH_FENCE } from './latex-kind';
-import { setMathRenderer } from './math-renderer';
+import { mathSlot } from './math-renderer';
 import { isMathBlockLayout } from './math-layout';
 import BlockMath from './BlockMath.svelte';
-export function latexPlugin(options) {
-    const blockLayout = isMathBlockLayout(options.blockLayout) ? options.blockLayout : 'split';
+export function latexPlugin(options = {}) {
+    const { renderer } = options;
     return definePlugin({
         name: 'latex',
+        defaults: {
+            blockLayout: isMathBlockLayout(options.blockLayout) ? options.blockLayout : 'split'
+        },
+        // An unknown layout keeps the default rather than breaking the block.
+        parseOptions(raw) {
+            const blockLayout = raw?.blockLayout;
+            return isMathBlockLayout(blockLayout) ? { blockLayout } : {};
+        },
         setup() {
-            setMathRenderer(options.renderer);
+            mathSlot.set(renderer ? ({ source, display }, { theme }) => renderer(source, { display, theme }) : null);
             registerMathInline();
-            // registerMathBlock co-registers the ```math fence kind; both render through BlockMath.
+            // registerMathBlock also registers the ```math fence kind; both render through BlockMath.
             registerMathBlock();
-            const blockMath = defineBlockComponent(BlockMath, () => ({ blockLayout }));
+            const blockMath = defineBlockComponent(BlockMath);
             registerBlockComponent(declaredPluginKind(MATH_BLOCK), blockMath);
             registerBlockComponent(declaredPluginKind(MATH_FENCE), blockMath);
+            registerInsertEntry({
+                id: 'math',
+                label: 'Math block',
+                icon: 'sigma',
+                keywords: ['math', 'latex', 'equation', 'tex'],
+                markdown: '$$\n\n$$\n'
+            });
         }
     });
 }

package/dist/plugins/latex/renderer.d.ts

@@ -1,13 +1,12 @@
 /**
- * The engine adapter behind the `@voithos-labs/aragonite/plugins/latex/renderer` subpath. Importing
- * it is how a consumer opts into `katex`, an optional peer the engine-free core never
- * pulls.
+ * The KaTeX adapter behind the `@voithos-labs/aragonite/plugins/latex/renderer` subpath.
+ * Importing it is how a consumer opts into `katex`, an optional peer dependency nothing else
+ * pulls in.
  */
 import 'katex/dist/katex.min.css';
-import type { MathRenderer } from './math-renderer';
-/**
- * `throwOnError: false` keeps a malformed formula from crashing the editor; its fallback is
- * swapped for the source painted as an error — red, in the code face, the parser's message on
- * hover — so a broken formula reads as what the author typed, not as a sentence about it.
- */
-export declare const katexRenderer: MathRenderer;
+import { type MathRender } from './math-renderer';
+/** `throwOnError: false` paints a malformed formula as `mathErrorNode` rather than throwing.
+ *  KaTeX draws no colors of its own, so it has no use for the theme. */
+export declare const katexRenderer: (source: string, { display }: {
+    display: boolean;
+}) => MathRender;

package/dist/plugins/latex/renderer.js

@@ -1,17 +1,15 @@
 /**
- * The engine adapter behind the `@voithos-labs/aragonite/plugins/latex/renderer` subpath. Importing
- * it is how a consumer opts into `katex`, an optional peer the engine-free core never
- * pulls.
+ * The KaTeX adapter behind the `@voithos-labs/aragonite/plugins/latex/renderer` subpath.
+ * Importing it is how a consumer opts into `katex`, an optional peer dependency nothing else
+ * pulls in.
  */
 import katex from 'katex';
-// Rides this module so a consumer wiring the adapter cannot forget it: `htmlAndMathml` emits
-// a `.katex-mathml` a11y tree this CSS clips to 1px, and unloaded every equation paints twice.
+// Imported here so a consumer wiring the adapter cannot forget it: `htmlAndMathml` emits a
+// `.katex-mathml` accessibility tree this CSS clips to 1px; without it every equation paints twice.
 import 'katex/dist/katex.min.css';
-/**
- * `throwOnError: false` keeps a malformed formula from crashing the editor; its fallback is
- * swapped for the source painted as an error — red, in the code face, the parser's message on
- * hover — so a broken formula reads as what the author typed, not as a sentence about it.
- */
+import { mathErrorNode } from './math-renderer';
+/** `throwOnError: false` paints a malformed formula as `mathErrorNode` rather than throwing.
+ *  KaTeX draws no colors of its own, so it has no use for the theme. */
 export const katexRenderer = (source, { display }) => {
     const container = document.createElement('span');
     container.innerHTML = katex.renderToString(source, {
@@ -22,20 +20,7 @@ export const katexRenderer = (source, { display }) => {
     const errorSpan = container.querySelector('.katex-error');
     if (errorSpan) {
         const message = (errorSpan.getAttribute('title') ?? 'invalid LaTeX').replace(/^ParseError:\s*/, '');
-        return { dom: buildErrorNode(source, message), error: message };
+        return { dom: mathErrorNode(source, message), error: message };
     }
     return { dom: container };
 };
-function buildErrorNode(source, message) {
-    const span = document.createElement('span');
-    span.className = 'math-error';
-    span.textContent = source;
-    span.title = message;
-    // Inline style rather than a stylesheet: the span lands inside any prose block, where no
-    // plugin sheet is guaranteed to be mounted.
-    span.style.color = 'var(--color-error, #d03025)';
-    span.style.fontFamily = 'var(--font-code, ui-monospace, monospace)';
-    span.style.fontSize = '0.9em';
-    span.style.cursor = 'help';
-    return span;
-}

package/dist/plugins/mermaid/MermaidBlock.svelte

@@ -1,25 +1,26 @@
 <script lang="ts">
-	// Render-primary on the public seam: `createContainerBlock` supplies the metadata
-	// commit and kind-command keydown, but the body renders the diagram, with no
-	// BlockList. Editing swaps in a plugin-owned textarea whose draft commits through
-	// the metadata seam as one undoable entry.
+	// Render-primary, built on the public API: `createContainerBlock` supplies the metadata
+	// commit and the keydown for kind commands, but the body renders the diagram, with no
+	// BlockList. Editing swaps in a textarea this plugin owns, whose text commits through the
+	// metadata update as one undo entry.
 	import { tick } from 'svelte';
 	import {
 		createContainerBlock,
 		getPluginMetadata,
 		trimTrailingLineEnding,
 		normalizeLineEndings,
+		POINTER_GESTURE_ATTR,
 		type NodeView
 	} from '../../plugin';
 	import { joinMermaidBody, type MermaidMetadata } from './mermaid-kind';
-	import { hasMermaidRenderer, renderMermaid, type MermaidRenderResult } from './mermaid-renderer';
+	import { mermaidSlot, type MermaidRenderResult } from './mermaid-renderer';
 
 	let { node, index, myPath = [] }: { node: NodeView; index: number; myPath?: number[] } = $props();
 
 	let boxEl: HTMLElement | undefined = $state();
 
-	// Every steady state carries a focus surface — the edit textarea included, so a broken or
-	// empty diagram is an arrow stop and a recovery entry point rather than a caret trap.
+	// Every state has something focusable, the edit textarea included, so a broken or empty
+	// diagram is a stop for the arrow keys and a way back in rather than a caret trap.
 	function focusSurfaceEl(): HTMLElement | null {
 		return (
 			boxEl?.querySelector<HTMLElement>('.mermaid-source, .mermaid-viewport, .mermaid-surface') ??
@@ -32,6 +33,7 @@
 		updateOwnMetadata,
 		handleKeydown,
 		moveFocusOut,
+		captureScrollPosition,
 		getPresentationMode,
 		getTheme
 	} = createContainerBlock({
@@ -45,15 +47,15 @@
 		commandHooks: () => ({ openEdit, openFocusView })
 	});
 
-	// The factory routes whole-block focus, delete, traversal and reorder, and carries
-	// the `measurePartialRects` the overlays paint off: there are no child hosts here.
+	// The factory handles whole-block focus, delete, traversal and reorder, and provides the
+	// `measurePartialRects` the overlays are painted from: there are no child blocks here.
 	export { containerApi };
 
 	const code = $derived(getPluginMetadata<MermaidMetadata>(node)?.code ?? '');
 	const displayCode = $derived(trimTrailingLineEnding(code));
 
-	// An empty diagram has no picture to draw and the engine rejects it, so its natural view is
-	// the edit surface; reading mode, which writes no bytes, gets a placeholder instead.
+	// An empty diagram has no picture to draw and mermaid rejects it, so it opens straight into
+	// the textarea; reading mode, which writes no bytes, gets a placeholder instead.
 	const isEmpty = $derived(displayCode.trim() === '');
 	const isReading = $derived(getPresentationMode() === 'reading');
 
@@ -62,15 +64,15 @@
 	let rendered = $state<MermaidRenderResult | null>(null);
 	$effect(() => {
 		const current = code;
-		// Reading the theme here is what subscribes this effect to a flip, which has to
-		// redraw because the engine writes colors into the SVG.
+		// Reading the theme here is what makes this effect re-run when the theme changes, and
+		// it must redraw because mermaid writes colors into the SVG.
 		const theme = getTheme();
-		if (isEmpty || !hasMermaidRenderer()) return;
+		if (isEmpty || !mermaidSlot.configured) return;
 		let stale = false;
-		void renderMermaid(current, theme).then(async (result) => {
+		void mermaidSlot.render(current, { theme }).then(async (result) => {
 			if (stale) return;
-			// A swap replaces the rendered surface alone, so only focus INSIDE it is re-handed:
-			// the editor hidden input host and the toolbar are box children and survive untouched.
+			// A redraw replaces only the rendered element, so only focus inside it is handed back:
+			// the editor's hidden input and the toolbar are children of the box and survive.
 			const hadFocus = focusSurfaceEl()?.contains(document.activeElement) ?? false;
 			rendered = result;
 			if (hadFocus) {
@@ -86,7 +88,7 @@
 	const surfaceState = $derived(
 		isEmpty
 			? 'empty'
-			: !hasMermaidRenderer()
+			: !mermaidSlot.configured
 				? 'no-renderer'
 				: rendered?.error
 					? 'error'
@@ -142,34 +144,35 @@
 	const view = createPanZoom();
 	const overlayView = createPanZoom();
 
-	// Focus-gated so the in-document diagram never hijacks the page: unfocused, a bare
-	// wheel scrolls and a stray drag cannot pan. Any descendant focus counts.
-	const isFocused = () => !!boxEl?.contains(document.activeElement);
+	// Turned on by focus, so an unfocused diagram hijacks neither the page nor the editor's own
+	// drag. The markup attribute is written from this one value.
+	let gestureArmed = $state(false);
+	// The attribute that tells the editor's pointer handling a drag here is the diagram's own.
+	const viewportGesture = $derived({ [POINTER_GESTURE_ATTR]: gestureArmed ? '' : undefined });
+	const overlayGesture = { [POINTER_GESTURE_ATTR]: '' };
 
 	function onViewportWheel(e: WheelEvent): void {
-		if (!isFocused() || !(e.ctrlKey || e.metaKey)) return;
+		if (!gestureArmed || !(e.ctrlKey || e.metaKey)) return;
 		e.preventDefault();
 		e.stopPropagation();
 		view.zoomBy(e.deltaY);
 	}
 
 	function onViewportPointerDown(e: PointerEvent): void {
-		// Never preventDefault, so the browser's focus-on-mousedown still lands: the
-		// first click focuses, and only a drag on the now-focused block pans.
 		e.stopPropagation();
-		if (isFocused()) view.beginPan(e);
+		if (gestureArmed) view.beginPan(e);
 	}
 
 	function onOverlayWheel(e: WheelEvent): void {
-		// A dedicated zoom surface with nothing behind to scroll, so unlike the
-		// in-document view a bare wheel zooms.
+		// A zoom view of its own with nothing behind it to scroll, so unlike the in-document
+		// view a plain wheel zooms.
 		e.preventDefault();
 		e.stopPropagation();
 		overlayView.zoomBy(e.deltaY);
 	}
 
-	// One click contract for the viewport and the non-rendered cards, so dblclick stays
-	// the recovery path out of a broken diagram.
+	// The viewport and the cards that show no picture answer clicks the same way, so a double
+	// click stays the way out of a broken diagram.
 	function onSurfacePointerDown(e: PointerEvent): void {
 		e.stopPropagation();
 	}
@@ -219,8 +222,11 @@
 		// there too, so this closes the command path.
 		if (isReading) return;
 		if (!editing) seedDraft();
+		// Captured before the swap: the card reaches its fitted height only after mounting, and
+		// a scroll container at the document's end clamps against the short layout in between.
+		const restoreScroll = captureScrollPosition();
 		editRequested = true;
-		void tick().then(() => textareaEl?.focus());
+		void restoreScroll().then(() => textareaEl?.focus({ preventScroll: true }));
 	}
 
 	function cancelEdit(): void {
@@ -239,10 +245,12 @@
 		// an untouched CRLF block must not rewrite its bytes on blur.
 		if (value === normalizeLineEndings(editSeed)) return;
 		const lineEnding = getPluginMetadata<MermaidMetadata>(node)?.openerLineEnding ?? '\n';
-		updateOwnMetadata({ code: joinMermaidBody(value, lineEnding) });
-		// Only a keyboard commit refocuses; a blur commit must not yank focus back from
-		// wherever the user clicked.
-		if (refocus) refocusBlock();
+		// Only a keyboard commit puts the caret back on the block; a blur commit must not yank
+		// focus back from wherever the user clicked.
+		updateOwnMetadata(
+			{ code: joinMermaidBody(value, lineEnding) },
+			refocus ? { caret: { path: [], offset: 0 } } : undefined
+		);
 	}
 
 	// Logical lines, not visual: the box carries no editor caret geometry, so the newlines
@@ -269,8 +277,8 @@
 			e.preventDefault();
 			cancelEdit();
 		} else if (atEditBoxEdge(e.key) && moveFocusOut(e)) {
-			// Focus leaves the box, so `focusout` commits the draft: the arrow exit forks
-			// nothing off the blur path.
+			// Focus leaves the box, so `focusout` commits the text: leaving by arrow key takes
+			// the same path as a blur.
 			e.preventDefault();
 		} else if (e.key === 'Tab') {
 			// Escape is the exit, so Tab indents in place. execCommand inserts through the
@@ -306,7 +314,13 @@
 </script>
 
 <!-- svelte-ignore a11y_no_static_element_interactions -->
-<div class="mermaid-block" bind:this={boxEl} onkeydown={handleKeydown}>
+<div
+	class="mermaid-block"
+	bind:this={boxEl}
+	onkeydown={handleKeydown}
+	onfocusin={() => (gestureArmed = true)}
+	onfocusout={(e) => (gestureArmed = boxEl?.contains(e.relatedTarget as Node | null) ?? false)}
+>
 	{#if editing}
 		<textarea
 			bind:this={textareaEl}
@@ -330,6 +344,7 @@
 			<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 			<div
 				class="mermaid-viewport"
+				{...viewportGesture}
 				tabindex="0"
 				role="img"
 				aria-label="Mermaid diagram"
@@ -345,8 +360,8 @@
 				</div>
 			</div>
 		{:else}
-			<!-- {#key} keeps the per-arm remount: a state flip replaces the surface element,
-			     and its focus/blur timing with it. -->
+			<!-- {#key} remounts once per state: a change of state replaces the element, and
+			     its focus and blur timing with it. -->
 			{#key surfaceState}
 				<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 				<div
@@ -358,7 +373,7 @@
 					ondblclick={onSurfaceDblClick}
 				>
 					{#if surfaceState === 'empty'}
-						<!-- Reading mode only: everywhere else an empty diagram renders its edit surface. -->
+						<!-- Reading mode only: everywhere else an empty diagram opens its textarea. -->
 						<div class="mermaid-empty">Empty diagram</div>
 					{:else if surfaceState === 'no-renderer'}
 						<pre class="mermaid-static">{displayCode}</pre>
@@ -392,6 +407,7 @@
 			</div>
 			<div
 				class="mermaid-overlay-viewport"
+				{...overlayGesture}
 				onwheel={onOverlayWheel}
 				onpointerdown={(e) => {
 					e.stopPropagation();
@@ -432,8 +448,8 @@
 		background: var(--color-bg-secondary, rgba(128, 128, 128, 0.12));
 	}
 
-	/* Revealed on hover/focus so the diagram carries no chrome at rest (SearchBar's
-	   elevated-surface + ghost-button convention). */
+	/* Shown on hover or focus so the diagram has no buttons over it at rest, following
+	   SearchBar's raised panel and plain buttons. */
 	.mermaid-toolbar {
 		position: absolute;
 		top: 6px;
@@ -457,7 +473,7 @@
 		pointer-events: auto;
 	}
 
-	/* Reading mode drops the edit affordance; Focus/Reset are view-only and stay. */
+	/* Reading mode drops the edit button; Focus and Reset only change the view, so they stay. */
 	:global([data-presentation='reading']) .mermaid-toolbar :global([data-testid='mermaid-edit']) {
 		display: none;
 	}
@@ -492,8 +508,8 @@
 		outline: none;
 	}
 
-	/* Only a focused block pans, so only then does the viewport hint with the grab cursor.
-	   `:focus-within`: whole-block focus lands on the editor's hidden input host beside it. */
+	/* Only a focused block pans, so only then does the viewport show the grab cursor.
+	   `:focus-within`, because whole-block focus goes to the editor's hidden input beside it. */
 	.mermaid-block:focus-within .mermaid-viewport {
 		cursor: grab;
 	}
@@ -504,8 +520,8 @@
 		justify-content: center;
 	}
 
-	/* Deltas over the shared .md-source-surface (editor.css). Height is written by the
-	   fit-to-content effect; `overflow-y: hidden` keeps the grow visible instead of scrolled. */
+	/* Only the differences from the shared .md-source-surface (editor.css). Height is written by
+	   the fit-to-content effect; `overflow-y: hidden` lets the box grow rather than scroll. */
 	.mermaid-source {
 		padding: 8px;
 		overflow-y: hidden;

package/dist/plugins/mermaid/index.js

@@ -1,3 +1,3 @@
-// Importing this pulls no rendering engine; the adapter lives at the `/renderer` subpath.
+// Importing this pulls in no renderer; the adapter lives at the `/renderer` subpath.
 export { mermaidPlugin } from './register';
 export { MERMAID } from './mermaid-kind';

package/dist/plugins/mermaid/mermaid-kind.d.ts

@@ -1,7 +1,7 @@
 /**
- * The reference whole-block container, on public registration seams only: an opaque
+ * The worked example of a whole-block container, using public registration only: an opaque
  * container with no children, its diagram code in typed metadata, so an
- * `updateOwnMetadata({ code })` commit is the whole edit path. Uninstall safety is by
+ * `updateOwnMetadata({ code })` commit is the whole edit path. Uninstalling is safe by
  * construction: without this opener the same bytes parse as plain `fencedCode`.
  */
 import { type CstNode } from '../../plugin';
@@ -25,11 +25,8 @@ export interface MermaidMetadata {
  * ending put back on every body line. An emptied body commits as `''`, no stray line.
  */
 export declare function joinMermaidBody(draft: string, lineEnding: string): string;
-/**
- * The opener's inverse, and the byte path every code edit rides. The body is a metadata string
- * this kind never re-parses, so the fence is sized against it here — a diagram line that reads as
- * this block's closer would otherwise truncate the block on its next load.
- */
+/** The opener's inverse, which every code edit goes through; the fence is sized against the body
+ *  here, since a diagram line reading as the closer would cut the block short on reload. */
 export declare function rebuildMermaidRaw(node: CstNode): void;
 export interface MermaidUiHooks {
     openEdit(): void;