@voithos-labs/aragonite 0.10.2 → 0.10.3

package/dist/editor-keys.d.ts

@@ -45,6 +45,35 @@ export interface PastedImage {
 /** Host import hook for pasted images: resolves to the markdown to insert, or null
  *  to skip that image. Called once per image file, in clipboard order. */
 export type PasteImageHook = (image: PastedImage) => Promise<string | null>;
+/** What a code block hands its host when the run affordance is pressed. */
+export interface CodeRunRequest {
+    /** The fence body alone — opener and closer lines excluded. */
+    code: string;
+    /** The opener's full info string, untrimmed of trailing attributes (`py {1-3}`). */
+    info: string;
+    /** Child indices from the document root to this block. */
+    path: number[];
+}
+/**
+ * Host hook for executing a code block. The editor runs nothing itself: installing this is
+ * what puts the run affordance on the block's rail, and the host owns everything after —
+ * the engine, the result, and where output goes. Absent, no run affordance renders.
+ */
+export type RunCodeHook = (request: CodeRunRequest) => void;
+/** One entry in a code block's overflow menu. `run` is called with the menu already closed. */
+export interface CodeMenuItem {
+    id: string;
+    label: string;
+    run: () => void;
+    /** Renders dimmed and refuses activation. */
+    disabled?: boolean;
+}
+/**
+ * Host hook for the code block's overflow menu, consulted each time the menu opens so the
+ * items can read live state. Absent — or returning nothing — renders no overflow affordance:
+ * the editor has no app-level actions of its own to put there.
+ */
+export type CodeMenuItemsHook = (request: CodeRunRequest) => readonly CodeMenuItem[];
 export type PresentationModeGetter = () => PresentationMode;
 /** The editor's theme name, as reflected to `data-editor-theme`. An open string:
  *  built-ins are `'dark'`/`'light'`, and a consumer may name its own. */
@@ -150,6 +179,10 @@ export interface EditorPolicies {
     /** Set-once host import hook for image-bearing pastes. Required-nullable: a mount must
      *  answer, and `undefined` deliberately leaves the paste on the text/plain path. */
     onPasteImage: PasteImageHook | undefined;
+    /** Set-once host execution hook; its presence is what renders the run affordance. */
+    onRunCode: RunCodeHook | undefined;
+    /** Set-once host menu hook; its presence is what renders the overflow affordance. */
+    codeMenuItems: CodeMenuItemsHook | undefined;
     /** Resolved image URLs that failed to load this session. One Set per instance, so a
      *  failed load never suppresses another editor's broken-state recompute
      *  (`components/image/widget-dom.ts`). */

package/dist/editor-props.d.ts

@@ -4,7 +4,7 @@
  */
 import type { Snippet } from 'svelte';
 import type { AnyBlockKind } from './core/nodes';
-import type { PasteImageHook, ResolveImageUrl, ResolveLinkUrl } from './editor-keys';
+import type { CodeMenuItemsHook, PasteImageHook, ResolveImageUrl, ResolveLinkUrl, RunCodeHook } from './editor-keys';
 import type { ImageLoadPolicy } from './core/inline-render';
 import type { PresentationMode } from './presentation-mode';
 import type { KeybindingOverride } from './schema/keybinding-overrides';
@@ -27,14 +27,24 @@ export interface EditorProps {
      *  in order and the markdown returned is inserted at the caret; `null` skips it.
      *  Installing it takes the WHOLE paste — the clipboard's `text/plain` is not pasted. */
     onPasteImage?: PasteImageHook;
+    /** Execution hook for code blocks, set once at mount. The editor runs nothing itself:
+     *  installing this is what puts the run affordance on a code block's rail, and the host
+     *  owns the engine, the result, and where output goes. Absent, no run affordance renders. */
+    onRunCode?: RunCodeHook;
+    /** Overflow-menu hook for code blocks, set once at mount and consulted each time a menu
+     *  opens so items can read live state. Absent, or returning nothing, renders no overflow
+     *  affordance — the editor has no app-level actions of its own to offer there. */
+    codeMenuItems?: CodeMenuItemsHook;
     /** Host chrome rendered INSIDE the editor's scroll container, above the first block
      *  (a title, properties panel, tag row). It scrolls away with the document rather than
      *  pinning, which is what lets the editor keep its own scrollport and windowing. */
     header?: Snippet;
-    /** Opt into the pointer affordances: the block drag handle and the table's row and column
-     *  grips (default off, so the surface stays gutter-free). A hover reveals them; touch, which
-     *  has none, shows them outright. Keyboard reorder (Alt+Arrow) and the cell menu are always
-     *  available and need no opt-in. */
+    /** The block drag handle (default on; reading mode never shows it). A hover reveals it;
+     *  touch, which has none, shows it outright. Only the blocks a reader picks up whole carry
+     *  one — code, tables, equations, diagrams, pictures, list items, dividers, cards — never
+     *  prose (paragraph, heading, quote, note). `false` removes them, except on a picture,
+     *  whose grip is the only pointer road to move it. Keyboard reorder (Alt+Arrow) is always
+     *  available, as is the table's right-click cell menu. */
     blockDragHandles?: boolean;
     searchBar?: boolean;
     /** Where the editor's own find/replace bar renders. Default (absent) keeps it pinned inside
@@ -102,14 +112,13 @@ export interface EditorInstance {
      */
     insertMarkdown(md: string): boolean;
     /**
-     * Run a command by id at the focused surface, no chord in the path, so a consumer's
-     * `keybindings` rebind cannot rewire a toolbar button. `TOOLBAR_COMMANDS` names the built-in
-     * ids; a plugin's global name resolves ahead of the focused block, its per-block one stays
-     * chord-only. Semantics match the chord: one undo entry, same caret — over a cross-block range
-     * a format toggle marks every block it touches, a table by its cells. False, and nothing mutates,
-     * on an unknown id, in reading mode, with nothing focused, and on the link editor over a range.
+     * Run a command by id at the focused surface, or across a painted range where the id has a
+     * cross-block arm (a format toggle marks every block it touches, a table by its cells). False,
+     * and nothing mutates, on an unknown id, in reading mode, with nothing focused, and on the link
+     * editor over a range. `arg` reaches the arm as a keybinding's argument would (`heading.cycle`
+     * takes the level, 0 for plain text); an arm that takes none ignores it.
      */
-    runCommand(commandId: string): boolean;
+    runCommand(commandId: string, arg?: unknown): boolean;
     /**
      * Whether `runCommand(id)` would reach that command's arm right now, asked at the seam that
      * would run it, so a host can grey a toolbar button out instead of hiding the affordance.

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { default as Editor } from './components/Editor.svelte';
 export type { EditorProps, EditorInstance } from './editor-props';
 export type { EditorDiagnostics, InteractionTraceEntry } from './editor-props';
 export type { BlockComponent } from './block-component';
-export type { ResolveImageUrl, ResolveLinkUrl, PastedImage, PasteImageHook } from './editor-keys';
+export type { ResolveImageUrl, ResolveLinkUrl, PastedImage, PasteImageHook, CodeRunRequest, RunCodeHook, CodeMenuItem, CodeMenuItemsHook } from './editor-keys';
 export type { ImageLoadPolicy } from './core/inline-render';
 export type { PresentationMode } from './presentation-mode';
 export type { SearchState, SearchOptions } from './search/search-state.svelte';

package/dist/plugin.d.ts

@@ -29,9 +29,15 @@ export type { OuterBlockScan } from './schema/block-openers';
 export { OPENER_PRIORITIES } from './schema/opener-priorities';
 export { registerBlockCompleter } from './schema/block-completions';
 export type { BlockCompleter, CompletionResult } from './schema/block-completions';
+export { registerLanguage, listLanguages } from './components/blocks/code/code-languages';
+export type { LanguageGrammar } from './components/blocks/code/code-languages';
+export { tokenizeBody as highlightCode } from './components/blocks/code/code-renderer';
+export type { LanguageFn } from 'highlight.js';
 export type { CommandId } from './schema/commands';
 export type { KeyBinding } from './schema/keybindings';
 export { registerBlockCommand } from './schema/block-commands';
+export { registerBlockContextActions } from './schema/context-actions';
+export type { BlockContextAction, BlockActionContext, BlockContextActionProvider } from './schema/context-actions';
 export type { BlockCommandContext, BlockCommandHandler } from './schema/block-commands';
 export type { PluginCommandId, AnyCommandId } from './schema/command-id';
 export { registerGlobalCommand } from './schema/global-commands';

package/dist/plugin.js

@@ -38,9 +38,20 @@ export { OPENER_PRIORITIES } from './schema/opener-priorities';
 // never type into existence: a completer reads one typed line and answers the lines that
 // complete it, plus where the caret seats inside the mint.
 export { registerBlockCompleter } from './schema/block-completions';
+// ── Code-block languages (pre-freeze) ────────────────────────────────────────
+// The registry behind fenced-code highlighting. The editor bootstraps a curated set (every
+// grammar is bundle weight for every consumer), so a host needing more registers them itself,
+// BEFORE mounting an editor: a block on screen re-tokenizes only when its bytes next change.
+// An unregistered language is not an error — the fence still round-trips, just untokenized.
+export { registerLanguage, listLanguages } from './components/blocks/code/code-languages';
+// The code block's own tokenizer, for a plugin whose source surface wants the same highlighting
+// (block math paints its LaTeX with it). Text-preserving: the fragment's textContent is `body`.
+export { tokenizeBody as highlightCode } from './components/blocks/code/code-renderer';
 // ── Command mint (pre-freeze) ────────────────────────────────────────────────
 // A (kind, name) block-command mints a PluginCommandId; AnyCommandId spans built-in and minted.
 export { registerBlockCommand } from './schema/block-commands';
+// The block context menu: a kind's right-click actions, empty unless something registers them.
+export { registerBlockContextActions } from './schema/context-actions';
 // A global command is process-wide but runs against the dispatching instance's EditorContext.
 export { registerGlobalCommand } from './schema/global-commands';
 // ── Parse / serialize helpers (pre-freeze) ───────────────────────────────────

package/dist/plugins/latex/BlockMath.svelte

@@ -8,10 +8,32 @@
 	// Render-primary editable leaf: all editing behavior lives in `createEditableLeaf`,
 	// so this component owns only the render↔source swap visuals.
 	import { createEditableLeaf, type BlockComponent, type NodeView } from '../../plugin';
+	// Plugin-local like the other labels here: bundled plugins import only the public barrel.
+	// The three ways the source and its preview can share the block while editing (see
+	// `math-layout.ts`); the host's plugin options pick the starting one. The toggle cycles
+	// them and names the NEXT layout.
+	type MathLayout = MathBlockLayout;
+	const LAYOUT_NEXT: Record<MathLayout, MathLayout> = {
+		split: 'stacked',
+		stacked: 'source',
+		source: 'split'
+	};
+	const LAYOUT_TITLE: Record<MathLayout, string> = {
+		split: 'Preview beside the source',
+		stacked: 'Preview below the source',
+		source: 'Source only'
+	};
 	import { renderDisplayMath } from './math-renderer';
 	import { mathDisplaySource } from './latex-kind';
+	import { completeBareMathSource, mathBodySpan, renderMathSource } from './math-source';
+	import { resolveDefaultLayout, type MathBlockLayout } from './math-layout';
 
-	let { node, index, myPath = [] }: { node: NodeView; index: number; myPath?: number[] } = $props();
+	let {
+		node,
+		index,
+		myPath = [],
+		blockLayout = 'split'
+	}: { node: NodeView; index: number; myPath?: number[]; blockLayout?: MathBlockLayout } = $props();
 
 	// eslint-disable-next-line no-useless-assignment -- <script module> counter read by the next instance mount
 	const mountId = nextMountId++;
@@ -20,6 +42,9 @@
 	let sourceEl: HTMLDivElement | undefined = $state();
 	let renderEl: HTMLDivElement | undefined = $state();
 	let revealed = $state(false);
+	// The in-flight source while revealed: a render-primary edit reaches the CST only on blur,
+	// so the live preview reads the surface, not the node. Null when nothing is in flight.
+	let draft = $state<string | null>(null);
 
 	const leaf = createEditableLeaf({
 		getNode: () => node,
@@ -30,16 +55,58 @@
 		isRevealed: () => revealed,
 		setRevealed: (value) => {
 			revealed = value;
+			draft = null;
+		},
+		renderSource: renderMathSource,
+		completeBareSource: completeBareMathSource,
+		onSourceEdit: (text) => {
+			draft = text;
 		}
 	});
 
+	// While editing, the preview is a sibling of the surface that holds focus: its scrollbar (a
+	// wide equation overflows the half-width card) must not take that focus, since losing it is
+	// what folds the editor. Same device as the eye button; a fold click is a click while folded.
+	function keepSourceFocus(e: MouseEvent): void {
+		if (revealed) e.preventDefault();
+	}
+
+	// Per-instance and per-session: a reader who changes the layout is asking about THIS equation
+	// while they edit it, not setting a preference for the document. The starting layout is the
+	// host's: this editor's plugin options, else the factory's default.
+	// svelte-ignore state_referenced_locally
+	let layout = $state<MathLayout>(resolveDefaultLayout(leaf.getOptions(), blockLayout));
+	const previewOpen = $derived(layout !== 'source');
+
+	// The edits the leaf applies itself report through `onSourceEdit`; this is the native path
+	// (a composition's commit), where the highlight goes stale until repainted. The leaf's own
+	// handler runs first so the IME bookkeeping it owns is untouched.
+	function onSourceInput(e: Event): void {
+		leaf.surfaceProps.oninput();
+		if ((e as InputEvent).isComposing) return;
+		leaf.repaintSource();
+		draft = sourceEl?.textContent ?? null;
+	}
+
 	// ── View rendering ──────────────────────────────────────────────────────────
 
 	// Re-runs on every remount of the render div and on any source change; the
 	// document-wide memo clones a cached node, so a repeat formula is cheap.
 	$effect(() => {
-		if (revealed || !renderEl) return;
-		renderEl.replaceChildren(renderDisplayMath(mathDisplaySource(leaf.sourceText)).dom);
+		if (!renderEl) return;
+		// Runs while REVEALED as well: the split keeps a live preview beside the source, so the
+		// equation re-renders as it is typed rather than only when the source folds away.
+		const text = draft ?? leaf.sourceText;
+		const source = mathDisplaySource(text);
+		renderEl.replaceChildren(renderDisplayMath(source).dom);
+		// The span a press on the glyphs lands in: the descriptor's `caretTargetAtPoint` reads the
+		// rendered element alone and has no other way to the bytes behind it.
+		const body = mathBodySpan(text);
+		renderEl.dataset.bodyStart = String(body.start);
+		renderEl.dataset.bodyEnd = String(body.end);
+		// An equation with nothing in it renders nothing, which folded would be an invisible block
+		// the user cannot find to delete; it keeps the card's fill instead, like an empty fence.
+		renderEl.toggleAttribute('data-empty', source.trim() === '');
 		renderCount += 1;
 		renderEl.dataset.renderCount = String(renderCount);
 	});
@@ -74,46 +141,214 @@
 	} satisfies BlockComponent);
 </script>
 
-{#if revealed}
-	<div
-		bind:this={sourceEl}
-		{...leaf.surfaceProps}
-		class="math-block-source md-source-surface"
-		aria-label="Math source"
-	></div>
-{:else}
-	<div
-		bind:this={renderEl}
-		class="math-block-render"
-		data-mount-id={mountId}
-		role="button"
-		tabindex="-1"
-		aria-label="Math (click to edit)"
-		{...leaf.renderProps}
-	></div>
-{/if}
+<!-- Editing shows source AND render side by side rather than swapping one for the other: the
+	swap re-flowed the whole document on every click, and a preview that only appears after you
+	stop editing is the one you needed while typing. Each half is a card, and the eye sits in the
+	top-right of whichever card is showing. -->
+<div
+	class="math-block"
+	class:math-block-editing={revealed}
+	class:math-block-split={revealed && layout === 'split'}
+	class:math-block-stacked={revealed && layout === 'stacked'}
+>
+	{#if revealed}
+		<div class="math-block-card">
+			<div
+				bind:this={sourceEl}
+				{...leaf.surfaceProps}
+				oninput={onSourceInput}
+				class="math-block-source md-source-surface"
+				aria-label="Math source"
+			></div>
+			<!-- The toggle keeps one seat: the top-right card. Side by side that is the preview; stacked
+				and source-only it is this card. -->
+			{#if layout !== 'split'}
+				{@render layoutToggle()}
+			{/if}
+		</div>
+	{/if}
+	{#if !revealed || previewOpen}
+		<div class="math-block-card">
+			<div
+				bind:this={renderEl}
+				class="math-block-render"
+				data-mount-id={mountId}
+				role="button"
+				tabindex="-1"
+				aria-label="Math (click to edit)"
+				{...leaf.renderProps}
+				onmousedown={keepSourceFocus}
+			></div>
+			{#if revealed && layout === 'split'}
+				{@render layoutToggle()}
+			{/if}
+		</div>
+	{/if}
+</div>
+
+{#snippet layoutToggle()}
+	{@const next = LAYOUT_NEXT[layout]}
+	<button
+		type="button"
+		class="math-preview-toggle"
+		aria-label={LAYOUT_TITLE[next]}
+		title={LAYOUT_TITLE[next]}
+		onmousedown={(e) => e.preventDefault()}
+		onclick={() => (layout = next)}
+	>
+		<svg
+			viewBox="0 0 24 24"
+			width="13"
+			height="13"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="1.75"
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			aria-hidden="true"
+		>
+			{#if layout === 'split'}
+				<rect width="18" height="18" x="3" y="3" rx="2" /><path d="M12 3v18" />
+			{:else if layout === 'stacked'}
+				<rect width="18" height="18" x="3" y="3" rx="2" /><path d="M3 12h18" />
+			{:else}
+				<path
+					d="M10.733 5.076a10.744 10.744 0 0 1 11.205 6.575 1 1 0 0 1 0 .696 10.747 10.747 0 0 1-1.444 2.49"
+				/><path d="M14.084 14.158a3 3 0 0 1-4.242-4.242" /><path
+					d="M17.479 17.499a10.75 10.75 0 0 1-15.417-5.151 1 1 0 0 1 0-.696 10.75 10.75 0 0 1 4.446-5.143"
+				/><path d="m2 2 20 20" />
+			{/if}
+		</svg>
+	</button>
+{/snippet}
 
 <style>
-	/* Deltas over the shared .md-source-surface (editor.css). */
+	/* At rest the render alone, laid out as a plain block so it centres exactly as it did
+	   before any of this existed. Editing turns the block into two equal cards. */
+	.math-block-split {
+		display: grid;
+		grid-template-columns: 1fr 1fr;
+		align-items: stretch;
+		gap: 6px;
+	}
+
+	/* Stacked: the source over its preview, each the block's full width — for the equation too
+	   long to read at half width. Not the default: it grows the block and reshuffles the page. */
+	.math-block-stacked {
+		display: grid;
+		grid-template-columns: 1fr;
+		gap: 6px;
+	}
+
+	/* The equation's cards are boxes like a code block's, and take the same stand-off from their
+	   neighbours (editor.css, fencedCode). Padding, not margin: the height model measures the
+	   host's box. */
+	:global(.block-host[data-block-kind='mathBlock']) {
+		padding-block: 6px;
+	}
+
+	/* Each half is its own card, and the containing block for its eye. */
+	.math-block-card {
+		position: relative;
+		min-width: 0;
+		border-radius: 8px;
+	}
+
+	/* Keyed on EDITING, not on the split: folding the preview away leaves one card, and a card
+	   that lost its fill the moment it stood alone would read as having left edit mode. */
+	.math-block-editing .math-block-card {
+		display: flex;
+		align-items: center;
+		background: var(--color-bg-secondary, rgba(128, 128, 128, 0.12));
+	}
+
+	/* Deltas over the shared .md-source-surface (editor.css) — including its accent border,
+	   which announced a state the card's own fill already carries. */
 	.math-block-source {
 		outline: none;
-		padding: 12px;
-		white-space: pre;
-		overflow-x: auto;
-		overflow-y: hidden;
+		padding: 10px 12px;
+		/* WRAP, rather than scroll sideways. The card is half the block's width, so any real
+		   formula overflows it, and a horizontal scrollbar hides the very text being edited.
+		   `pre-wrap` keeps the author's own line breaks and wraps only what is too long;
+		   LaTeX carries no indentation structure for wrapping to destroy. */
+		white-space: pre-wrap;
+		overflow-wrap: anywhere;
+		/* LEFT, like every other source surface. Centring gave each line a different starting
+		   x, which is exactly what makes multi-line LaTeX unreadable; the RENDER is the half
+		   that is genuinely centred, and the pairing is what Overleaf and friends do. */
+		text-align: left;
+		background: transparent;
+		border-color: transparent;
+		border-radius: 8px;
+	}
+
+	/* The card stretches the source so its box fills the column; without it a short formula's
+	   surface shrink-wraps and the caret only lands where the text is. */
+	.math-block-editing .math-block-card > .math-block-source {
+		flex: 1;
+		min-width: 0;
 	}
 
 	.math-block-render {
 		display: block;
-		padding: 8px 12px;
+		width: 100%;
+		padding: 10px 12px;
 		text-align: center;
 		cursor: text;
 		border: 1px solid transparent;
-		border-radius: 4px;
+		border-radius: 8px;
 		overflow-x: auto;
 	}
 
-	.math-block-render:hover {
+	/* Folded and empty: the fill stays, so there is a box to see and click into. */
+	.math-block:not(.math-block-editing) .math-block-render[data-empty] {
 		background: var(--color-bg-secondary, rgba(128, 128, 128, 0.12));
+		/* The editing card's height exactly — one source line at its size, plus its padding and
+		   hairline — so folding and unfolding an empty equation moves nothing. */
+		min-height: calc(0.9em * 1.5 + 22px);
+		box-sizing: border-box;
+	}
+
+	/* At rest the render is the whole block and a hover tint is its only affordance; inside a
+	   card the fill is already there, so the tint would double it. */
+	.math-block:not(.math-block-editing) .math-block-render:hover {
+		background: var(--color-bg-secondary, rgba(128, 128, 128, 0.12));
+	}
+
+	.math-preview-toggle {
+		position: absolute;
+		top: 4px;
+		right: 4px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 22px;
+		height: 22px;
+		padding: 0;
+		border: none;
+		border-radius: 5px;
+		background: transparent;
+		color: var(--color-ui-muted, #8f8f89);
+		cursor: pointer;
+		opacity: 0;
+		transition: opacity 120ms ease-out;
+	}
+
+	/* Transient like every other affordance here: the pointer over the block, or the eye itself
+	   holding focus. */
+	.math-block:hover .math-preview-toggle,
+	.math-preview-toggle:focus-visible {
+		opacity: 1;
+	}
+
+	.math-preview-toggle:hover {
+		background: var(--color-ui-faint, rgba(255, 255, 255, 0.07));
+		color: var(--color-text-secondary, #cfcfca);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.math-preview-toggle {
+			transition: none;
+		}
 	}
 </style>

package/dist/plugins/latex/BlockMath.svelte.d.ts

@@ -1,8 +1,10 @@
 import { type NodeView } from '../../plugin';
+import { type MathBlockLayout } from './math-layout';
 type $$ComponentProps = {
     node: NodeView;
     index: number;
     myPath?: number[];
+    blockLayout?: MathBlockLayout;
 };
 declare const BlockMath: import("svelte").Component<$$ComponentProps, {
     editable: true;

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

@@ -1,3 +1,4 @@
-export { latexPlugin } from './register';
+export { latexPlugin, type LatexPluginOptions } from './register';
 export { MATH_INLINE, MATH_BLOCK, MATH_FENCE } from './latex-kind';
 export type { MathRenderer } from './math-renderer';
+export type { MathBlockLayout } from './math-layout';

package/dist/plugins/latex/latex-kind.js

@@ -4,7 +4,7 @@
  * never imported here. Recognition is gated on registration, so with no extension
  * loaded parsing stays byte-identical to bare GFM.
  */
-import { createScanIndex, declarePluginInlineKind, declarePluginKind, registerInlineSyntax, registerInlineWidgetKind, registerBlockKind, registerBlockOpener, isInlineKindDeclared, simpleLeafClosure, matchFenceOpen, matchFenceClose, OPENER_PRIORITIES } from '../../plugin';
+import { caretOffsetAtPoint, createScanIndex, declarePluginInlineKind, declarePluginKind, registerInlineSyntax, registerInlineWidgetKind, registerBlockKind, registerBlockOpener, isInlineKindDeclared, simpleLeafClosure, matchFenceOpen, matchFenceClose, OPENER_PRIORITIES } from '../../plugin';
 import MathInline from './MathInline.svelte';
 import { registerMathBlockCompleter } from './math-completion';
 export const MATH_INLINE = 'math';
@@ -35,6 +35,10 @@ function recognizeMath(raw, pos, end, kind) {
     const opener = raw[afterOpen];
     if (isWhitespace(opener) || isDigit(opener))
         return null;
+    // `$$` is the display fence, or the empty pair a keystroke just closed: never an inline
+    // opener, or its closer search would jump to the far end of the next formula on the line.
+    if (opener === '$')
+        return null;
     // The index spans the whole block, so `end` decides the claim: a closer past the
     // scan range leaves the `$` literal.
     const close = firstCloserFrom(raw, pos + 2);
@@ -49,11 +53,18 @@ export function registerMathInline() {
     if (isInlineKindDeclared(MATH_INLINE))
         return;
     const kind = declarePluginInlineKind(MATH_INLINE);
-    registerInlineSyntax('$', (raw, pos, end) => recognizeMath(raw, pos, end, kind));
+    registerInlineSyntax('$', (raw, pos, end) => recognizeMath(raw, pos, end, kind), {
+        autoPair: true
+    });
     registerInlineWidgetKind(kind, {
         isWidget: () => true,
         component: MathInline,
-        editing: { revealSource: true }
+        editing: {
+            revealSource: true,
+            // `$…$`: one delimiter each side, so a revealing click seats the caret on the last
+            // character of the formula rather than past its closing `$`.
+            revealContentSpan: (source) => source.length >= 2 ? { start: 1, end: source.length - 1 } : null
+        }
     });
 }
 // ── Rendered display source ────────────────────────────────────────────────────
@@ -101,6 +112,7 @@ export function registerMathBlock() {
         // edge can grow a sibling.
         gapEdges: 'both',
         conformanceFixture: '$$\nx^2\n$$\n',
+        caretTargetAtPoint: mathCaretAtPoint,
         closure: simpleLeafClosure({
             focus: {
                 mode: 'implemented',
@@ -155,6 +167,26 @@ export function registerMathBlock() {
     // Co-registered so one install teaches both forms (the admonition/githubAlert precedent).
     registerMathFence();
 }
+/** Where a press on the folded equation puts the caret. KaTeX paints glyphs, not source bytes,
+ *  so the press walks the body span in proportion to how far along the equation it fell; the
+ *  fence lines carry no glyph of their own. */
+function mathCaretAtPoint(blockEl, clientX, clientY) {
+    const render = blockEl.querySelector('.math-block-render');
+    if (!render)
+        return null;
+    const start = Number(render.dataset.bodyStart);
+    const end = Number(render.dataset.bodyEnd);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return null;
+    // `.katex-html` is the painted half: its MathML twin is clipped to a pixel, and the pair
+    // measured together answers for a point no reader aimed at.
+    const glyphs = render.querySelector('.katex-html');
+    const along = glyphs ? caretOffsetAtPoint(glyphs, clientX, clientY) : null;
+    const total = glyphs?.textContent?.length ?? 0;
+    if (along === null || total === 0)
+        return { path: [], offset: end };
+    return { path: [], offset: start + Math.round((along / total) * (end - start)) };
+}
 // ── Fenced ```math display math ─────────────────────────────────────────────────
 // GitHub's third math form: a source-holding leaf like the `$$` block, rendered by
 // the same component.
@@ -170,6 +202,7 @@ export function registerMathFence() {
         editable: true,
         supportsInline: false,
         gapEdges: 'both',
+        caretTargetAtPoint: mathCaretAtPoint,
         conformanceFixture: '```math\nx^2\n```\n',
         closure: simpleLeafClosure({
             focus: {

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

@@ -15,5 +15,8 @@ export function tryCompleteMathBlock(line) {
 export function registerMathBlockCompleter(kind) {
     if (isBlockCompleterRegistered(kind))
         return;
-    registerBlockCompleter(kind, { tryComplete: tryCompleteMathBlock });
+    // On type as well as at Enter: a lone `$$` can only be the pair's opener, so the block forms
+    // as the second `$` lands — the way a typed ` ``` ` is a fence at once — with the caret on
+    // the body line. The one-line `$$x$$` form is still reachable by typing into that body.
+    registerBlockCompleter(kind, { tryComplete: tryCompleteMathBlock, onType: true });
 }

package/dist/plugins/latex/math-layout.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How a `$$` block lays out its source and preview while it is being edited. `split` (side by
+ * side) is the default because it moves the page least; `stacked` suits long equations; `source`
+ * shows no preview. A host picks the default through `latexPlugin({ blockLayout })`, and the
+ * block's own toggle still cycles from there.
+ */
+export type MathBlockLayout = 'split' | 'stacked' | 'source';
+export declare const MATH_BLOCK_LAYOUTS: readonly MathBlockLayout[];
+export declare function isMathBlockLayout(value: unknown): value is MathBlockLayout;
+/**
+ * The starting layout: this editor's per-instance plugin options first (`{ plugin, options:
+ * { blockLayout } }`), then the factory's own default (`latexPlugin({ blockLayout })`), then
+ * `split`. An unknown value falls through rather than throwing.
+ */
+export declare function resolveDefaultLayout(options: unknown, fallback?: MathBlockLayout): MathBlockLayout;

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

@@ -0,0 +1,13 @@
+export const MATH_BLOCK_LAYOUTS = ['split', 'stacked', 'source'];
+export function isMathBlockLayout(value) {
+    return MATH_BLOCK_LAYOUTS.includes(value);
+}
+/**
+ * The starting layout: this editor's per-instance plugin options first (`{ plugin, options:
+ * { blockLayout } }`), then the factory's own default (`latexPlugin({ blockLayout })`), then
+ * `split`. An unknown value falls through rather than throwing.
+ */
+export function resolveDefaultLayout(options, fallback = 'split') {
+    const declared = options?.blockLayout;
+    return isMathBlockLayout(declared) ? declared : fallback;
+}