@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/editor-props.d.ts

@@ -1,6 +1,6 @@
 /**
  * Public prop and instance-handle types for <Editor>. Editor.svelte annotates its
- * $props() and instance surface against these, so neither can drift from the component.
+ * $props() and its instance methods against these, so neither can drift from the component.
  */
 import type { Snippet } from 'svelte';
 import type { AnyBlockKind } from './core/nodes';
@@ -13,9 +13,13 @@ import type { EditorEvents } from './editor-events';
 import type { SearchState } from './search/search-state.svelte';
 import type { DecorationRegistry } from './decorations/types';
 import type { EditorRects } from './editor-rects';
+import type { InlineMenuRegistry } from './inline-menu/types';
+import type { InsertEntry } from './schema/insert-catalogue';
 import type { EditorPluginEntry } from './schema/plugin-install';
+import type { SyntaxOptions } from './schema/registry-view';
 import type { InteractionTraceEntry } from './debug/interaction-trace';
 export type { EditorPluginEntry } from './schema/plugin-install';
+export type { SyntaxOptions } from './schema/registry-view';
 export type { InteractionTraceEntry } from './debug/interaction-trace';
 export interface EditorProps {
     source?: string;
@@ -25,39 +29,37 @@ export interface EditorProps {
     onLinkActivate?: (url: string, event: MouseEvent) => void;
     /** Import hook for image-bearing pastes, set once at mount. Each image file is offered
      *  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. */
+     *  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. */
+     *  installing this is what puts the run button in a code block's side gutter, and the host
+     *  owns the runtime, the result, and where output goes. Absent, no run button 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. */
+     *  button: 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. */
+    /** The host's own content, 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
+     *  staying fixed, which is what lets the editor keep its own scroll container and windowing. */
     header?: Snippet;
-    /** 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. */
+    /** The block drag handle (default on; never in reading mode), shown on hover, or outright on
+     *  touch. Only blocks a user picks up whole have one (code, tables, equations, diagrams,
+     *  pictures, list items, dividers, cards), never prose. `false` removes them, except on a
+     *  picture, whose handle is its only pointer move. Alt+Arrow reorder always works. */
     blockDragHandles?: boolean;
     searchBar?: boolean;
     /** The editor's own formatting popover beside a prose selection (default on; reading mode
      *  never shows it). A host with its own bar over `runCommand` passes false. */
     selectionToolbar?: boolean;
-    /** Where the editor's own find/replace bar renders. Default (absent) keeps it pinned inside
-     *  the editor root; an element relocates the SAME bar into it, theme scope included, so
-     *  host-scroll embeds can put it in a pane's chrome instead of mid-page. Read live, and
+    /** Where the editor's own find/replace bar renders. Absent, it stays fixed inside the editor
+     *  root; an element moves that same bar into it, theme styling included, so an embed that
+     *  scrolls in the host can put it in a pane's own frame instead of mid-page. Read live, and
      *  ignored while `searchBar` is false. Positioning inside it is the element's own business. */
     searchBarAnchor?: HTMLElement | null;
-    /** Who owns the scroll, set once at mount. `'self'` (default) makes the root its own
-     *  scrollport. `'host'` lets an ancestor scroll it, and the editor windows against that
-     *  scroller instead — so the mounted set stays O(viewport) either way. The one behavioural
+    /** Who owns the scroll, set once at mount. `'self'` (default) makes the editor root its own
+     *  scroll container. `'host'` lets an ancestor scroll it, and the editor windows against that
+     *  scroller instead, so the mounted set stays O(viewport) either way. The one behavioural
      *  difference is scroll anchoring; the consumer guide's scrollMode section has the trade. */
     scrollMode?: 'self' | 'host';
     /** Theme name reflected to `data-editor-theme` on the editor root. Built-ins:
@@ -67,18 +69,28 @@ export interface EditorProps {
      *  wrapper keys its own palette off the same attribute set on the wrapper. */
     theme?: string;
     /** How the document presents, read live like `theme`; `'source'` by default. The consumer
-     *  guide's Presentation modes section describes what each rung shows and allows. */
+     *  guide's Presentation modes section describes what each mode shows and allows. */
     presentationMode?: PresentationMode;
     /** Per-instance keymap overrides over the built-in command vocabulary. */
     keybindings?: KeybindingOverride[];
-    /** Plugins installed once, in array order, at mount. Set-once: a later change to
-     *  this prop is ignored — installation is process-global and cannot re-run. An
-     *  entry may be a bare unit or `{ plugin, options }` for per-instance options.
-     *  The array is the enablement set too: this editor activates exactly what it
+    /** Plugins installed once, in array order, at mount. Set-once: a later change to this
+     *  prop is ignored, because installation is process-global and cannot re-run. An entry
+     *  may be a plugin on its own or `{ plugin, options }` for per-instance options. The
+     *  array also says which plugins are enabled: this editor activates exactly what it
      *  lists, and no prop at all activates everything installed. */
     plugins?: readonly EditorPluginEntry[];
+    /** GFM syntaxes to switch off in this editor, each on by default and read once at mount:
+     *  `indentedCode: false` reads a line indented by a tab or four spaces as prose, and
+     *  `setextHeading: false` reads `===` or `---` under text as prose or a divider. Only the
+     *  reading changes: a loaded file keeps every byte, and saves as it came. */
+    syntax?: SyntaxOptions;
 }
-/** The `bind:this` surface a consumer can name and hold a ref to. */
+export interface InsertMarkdownOptions {
+    /** `caret` (the default) inserts where the caret is; `below` inserts into a new paragraph
+     *  after the top-level block that holds it. */
+    placement?: 'caret' | 'below';
+}
+/** The `bind:this` handle a consumer can name and hold a ref to. */
 export interface EditorInstance {
     getSource(): string;
     /**
@@ -88,80 +100,85 @@ export interface EditorInstance {
      * own declared kind name.
      */
     getBlockKindAt(path: number[]): AnyBlockKind | null;
+    /**
+     * The live selection, or null when nothing is focused. While an image is selected whole it is
+     * a caret at the image's edge its selection came from (its end after a click).
+     */
     getSelection(): EditorSelection | null;
     /**
-     * Restore a `getSelection()` snapshot. Async because the target is scrolled into view
-     * first, and true means it got there, not merely that it mounted. Never throws: an
-     * out-of-range offset clamps in that endpoint's own coordinate space (a TABLE
-     * endpoint's row-major cell index clamps to the last cell, not a character position),
-     * and an unresolvable path or an unsettled scroll resolves false.
+     * Restore a `getSelection()` snapshot. Async because the target is scrolled into view first,
+     * and true means it got there, not merely that it mounted. Never throws: an out-of-range
+     * offset clamps in its own coordinate space (a table's cell index to the last cell), and an
+     * unresolvable path, or a scroll that never arrives, resolves false. A caret at the start of a
+     * list lands in its first item; one inside a closed body lands on its title row.
      */
     setSelection(selection: EditorSelection): Promise<boolean>;
     /**
-     * Land the caret at a viewport point exactly as a click there would: the point clamps into the
-     * nearest block's box, the block under it resolves the landing, a live cross-block range ends
-     * first. For a shell owning chrome beside the document: the shell decides whether a click on
-     * its own territory comes here, the editor decides where the caret goes. False when no
-     * focusable landing resolves. A point below the whole document resolves against the CST, not
-     * the rendered slice: past a windowed-out tail it claims the point and lands after the reveal.
+     * Put the caret at a viewport point exactly as a click there would: the point clamps into the
+     * nearest block's box, the block under it picks the spot, and a live cross-block range ends
+     * first. A host decides which of its clicks come here. False when no focusable position
+     * resolves; a point past an unmounted tail lands there once that mounts.
      */
     placeCaretAtPoint(x: number, y: number): boolean;
     /**
-     * Insert markdown at the caret exactly as pasting it would, minus the clipboard: paste
-     * transforms, every container-aware strategy, delete-selection-first, one undo entry, and
-     * focus at the end of the insertion. True means the pipeline took the text, not that its
-     * commit has flushed — read the result back through the `edit` event. False, and nothing
-     * mutates, when this editor holds no caret, in reading mode, or at a gap caret.
+     * Insert markdown exactly as pasting it would, minus the clipboard: paste transforms,
+     * delete-selection-first, one undo entry, focus at the end. Resolves true once the insert has
+     * landed; false, with nothing changed, with no caret, in reading mode, or at a gap caret.
+     * `placement: 'below'` first adds an empty paragraph after the caret's top-level block.
      */
-    insertMarkdown(md: string): boolean;
+    insertMarkdown(md: string, options?: InsertMarkdownOptions): Promise<boolean>;
     /**
-     * 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.
+     * Run a command by id at the focused element, or across a painted range where the id has a
+     * cross-block handler (a format toggle marks every block it touches, a table works 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 handler as a keybinding's argument
+     * would (`heading.cycle` takes the level, 0 for plain text); a handler that takes none ignores it.
      */
     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.
-     * False wherever the door declines before dispatch: an unknown id, reading mode, a block-local
-     * id with nothing focused (a gap caret included, where only the global ids stay live), and the
-     * link editor while a cross-block range is painted. True is reachability, not success: the arm
-     * that would run still decides whether it writes, and over a range it may reach no block at all.
+     * Whether `runCommand(id)` would reach that command's handler right now, so a host can grey a
+     * toolbar button out instead of hiding it. False wherever dispatch declines before it starts:
+     * an unknown id, reading mode, a block-local id with nothing focused (a gap caret included,
+     * where only the global ids stay live), and the link editor while a cross-block range is
+     * painted. True means reachable, not successful: the handler still decides whether it writes.
      */
     canRunCommand(commandId: string): boolean;
     /**
-     * Whether the command's toggle-state reads ON where a press would land — the read a toolbar
-     * paints pressed from, answered by the same bytes the toggle would rewrite. State, not
-     * admissibility, so a disabled button may still paint pressed. Over a cross-block range the
-     * answer is the range's own coverage: true only where every block it touches carries the
-     * mark; the link editor reads ON inside the construct its card would edit, in live mode
-     * alone. False for an id with no state of its own, and with nothing focused.
+     * Whether the command's toggle reads on where a keypress would land: a toolbar's pressed
+     * state, from the same bytes the toggle would rewrite. State, not permission, so a disabled
+     * button may still paint pressed. Over a cross-block range, true only where every touched block
+     * has the mark. False for an id with no state, and with nothing focused.
      */
     isCommandActive(commandId: string): boolean;
     getEvents(): EditorEvents;
     getSearch(): SearchState;
     getDecorations(): DecorationRegistry;
+    /** The same registry a plugin reaches as `editor.inlineMenus`, for a host that owns the menu's
+     *  data (its document index, its tag list) rather than shipping a plugin for it. */
+    getInlineMenus(): InlineMenuRegistry;
+    /**
+     * The blocks the insert menus offer, in menu order: the built-ins, then each block a plugin this
+     * editor activated registered. The list the right-click flyout draws, for a host building its own
+     * insert button; each entry's `markdown` is what to hand `insertMarkdown`. A fresh frozen list per call.
+     */
+    getInsertCatalogue(): readonly InsertEntry[];
     getRects(): EditorRects;
     getDiagnostics(): EditorDiagnostics;
     /**
-     * Every MODIFIER chord this instance consumes, normalized (`Mod` covers Ctrl and Cmd).
-     * Composed live from the kind keymaps, the command tables, the plugins this editor activated,
-     * the `keybindings` overrides and the search option, so a host accelerator table is derived,
-     * not hand-copied. Bare keys are out of contract: a focused document owns them. So is a
-     * DISABLED chord (`command: null`), released for the host to claim app-wide yet still
-     * swallowed INSIDE the editor, whose native fall-through would bypass the CST undo stack.
+     * Every modifier chord this instance consumes, normalized (`Mod` covers Ctrl and Cmd), composed
+     * live from the kind keymaps, command tables, active plugins, `keybindings` overrides and search,
+     * so a host's accelerator table is derived. Bare keys aren't listed, nor is a chord turned off
+     * with `command: null`, which the editor still swallows so it can't bypass the undo stack.
      */
     reservedChords(): ReadonlySet<string>;
     /** Whether this instance consumes that keystroke, answered with the editor's own chord
-     *  normalization so a host never re-implements the Ctrl/Cmd fold. */
+     *  normalization so a host never re-implements the Ctrl-equals-Cmd rule. */
     claimsChord(event: KeyboardEvent): boolean;
 }
 /**
- * The diagnostics door: arm the interaction trace, read it, and serialize an attachable
- * field report. The recorder ships default-off, so a consumer opts in, reproduces, then
- * serializes. The trace is process-global — two instances interleave their entries.
+ * Diagnostics for a bug report: turn the interaction trace on, read it, and serialize a
+ * report a user can attach. Recording is off by default, so a consumer opts in, reproduces
+ * the problem, then serializes. The trace is process-global: two instances interleave entries.
  */
 export interface EditorDiagnostics {
     enableTrace(): void;
@@ -170,7 +187,7 @@ export interface EditorDiagnostics {
     traceSnapshot(): InteractionTraceEntry[];
     /**
      * A fenced-markdown snapshot (timestamp, trace tail, ops-log tail, selection). The
-     * document source is EXCLUDED by default; pass `{ includeSource: true }` to opt in.
+     * document source is left out by default; pass `{ includeSource: true }` to opt in.
      */
     serializeDiagnostics(opts?: {
         includeSource?: boolean;

package/dist/editor-rects.d.ts

@@ -1,58 +1,47 @@
+/**
+ * Viewport-space geometry over the rendered document, the public face of the measurement calls
+ * block components expose. Offsets mean what `measurePartialRects` means for that block (raw
+ * offsets on prose, cell coordinates in a grid). jsdom reports boxes of about zero size, so e2e
+ * covers this file rather than unit tests.
+ */
 import type { BlockComponent } from './block-component';
-import type { RevealAnchorState } from './cursor/reveal-anchor';
+import type { ScrollOwner } from './cursor/scroll-owner';
 export interface EditorRects {
     /** The block's outermost box, or null when it isn't mounted. */
     blockRect(path: number[]): DOMRect | null;
-    /**
-     * Rects covering `[start, end)` in the block's measurable content — one per visual
-     * line on a wrapped prose leaf, one per cell on a grid surface. `SELECTION_END` is
-     * accepted as `end`. Empty when the block isn't mounted or can't measure.
-     */
+    /** Rects covering `[start, end)` of the block's measurable content: one per visual line of prose,
+     *  one per grid cell. `end` accepts `SELECTION_END`; empty when the block isn't mounted. */
     rangeRects(path: number[], start: number, end: number): DOMRect[];
     /**
-     * The live native single-block caret, or null — including in cross-block mode, whose
-     * parked range is not a caret and must not leak out as one.
+     * The browser's caret when it sits in one block, or null. Null in cross-block mode too,
+     * where the held range is not a caret and must not leak out as one.
      */
     caretRect(): DOMRect | null;
-    /** Scroll a windowed-out block into its window and await its mount. Resolves
-     *  true once the block's element is present. */
+    /** Scroll a block that is not rendered yet into the mounted range and await its mount.
+     *  Resolves true once the block's element is present. */
     reveal(path: number[]): Promise<boolean>;
-    /**
-     * Reveal (mount) the block at `path`, then scroll the viewport to it. `block` defaults to
-     * `'nearest'`; `hold` (default true) keeps the reveal's pin afterward, so a later layout
-     * shift cannot push the target back out. Resolves true only once the position settles; a
-     * reveal superseded by a later one stops refining and reports honest visibility.
-     */
+    /** Mount the block at `path` and scroll to it (`block` defaults to `'nearest'`); `hold`, default
+     *  true, keeps it where it landed against later layout shifts. True once in view and settled. */
     scrollTo(path: readonly number[], opts?: {
         block?: 'nearest' | 'center';
         hold?: boolean;
     }): Promise<boolean>;
-    /**
-     * Navigate to `path`: reveal, scroll, and land the caret at `offset` in it (default 0),
-     * so the next keystroke (Ctrl+Z included) addresses the document rather than the
-     * affordance that was clicked. Runs the same restore road undo and `setSelection` use.
-     * True means the caret landed AND the target settled into view.
-     */
+    /** Mount `path`, scroll there and land the caret at `offset` (default 0) as an edit does, so the
+     *  next key addresses the document; a closed `<details>` on the way opens. True once in view. */
     navigateTo(path: readonly number[], offset?: number): Promise<boolean>;
 }
 export declare function createEditorRects(deps: {
     getBlockElByPath: (path: number[]) => HTMLElement | null;
-    getBlockComponentByPath: (path: number[]) => BlockComponent | null;
+    getBlockComponent: (path: number[]) => BlockComponent | null;
+    /** Mounts `path`, opening a collapsed body on the way: every caller here is a navigation. */
     revealPath: (path: number[]) => Promise<unknown>;
     getEditorRoot: () => HTMLElement | null;
-    /** True when an ancestor owns the scroll (`scrollMode="host"`): the root is then no
-     *  scrollport but spans the WHOLE document, so intersecting a block with it answers
-     *  "is this in the document" rather than "is this visible". */
-    isHostScroll: () => boolean;
-    /** Host mode's ancestors that bound what can be seen. Intersected WITH the window
-     *  viewport, never instead of it: a bound that clips nothing would swallow the fold. */
-    getClipBounds: () => HTMLElement[];
+    scroll: Pick<ScrollOwner, 'place'>;
     isCrossBlock: () => boolean;
-    /** True for nodes in the host's `header` slot — inside the root, but not this
+    /** True for nodes in the host's `header` snippet: inside the root, but not this
      *  editor's content. */
     isHostChrome: (node: Node | null) => boolean;
-    revealAnchor: RevealAnchorState;
-    /** Land a caret at a raw offset in `path` through the shared restore road. Injected
-     *  because this surface owns geometry, not the selection model. */
+    /** Put a caret at a raw offset in `path` through the caret landing, as a navigation. Injected
+     *  because this file owns geometry, not the selection model. */
     landCaretAt: (path: number[], offset: number) => Promise<boolean>;
 }): EditorRects;

package/dist/editor-rects.js

@@ -1,72 +1,14 @@
-/**
- * Viewport-space geometry over the rendered document, the public face of the measurement
- * primitives block components expose. Offsets inherit `measurePartialRects`' per-surface
- * meaning (raw offsets on prose leaves, cell-index coordinates on grid surfaces). Rects
- * are real only in a browser — jsdom reports ~0-sized boxes — so e2e covers this surface,
- * not unit tests.
- */
-import { tick } from 'svelte';
-// Post-mount measure passes settle within a few Svelte flushes; `tick` is the repo's only
-// sequencing primitive, so the wait is a bounded count of them.
-const REVEAL_SETTLE_TICKS = 12;
 export function createEditorRects(deps) {
-    function isInView(el, root) {
-        const br = el.getBoundingClientRect();
-        // Self mode: the root IS the scrollport, and what lies outside it is the host
-        // page's business, not the editor's.
-        if (!deps.isHostScroll()) {
-            const er = root.getBoundingClientRect();
-            return br.top < er.bottom && br.bottom > er.top;
-        }
-        if (br.top >= window.innerHeight || br.bottom <= 0)
-            return false;
-        for (const bound of deps.getClipBounds()) {
-            const cr = bound.getBoundingClientRect();
-            if (br.top >= cr.bottom || br.bottom <= cr.top)
-                return false;
-        }
-        return true;
-    }
-    // The anchor's re-assertion (`correctAnchor`) is model-based and runs pre-flush, so it
-    // can lag the DOM by a boundary block's height; each tick refines placement AFTER the
-    // flush, when DOM reads are exact, and stops once the target stops moving. A SUPERSEDED
-    // claim bails at once (the viewport belongs to the newer reveal), but one that merely
-    // lost its pin to a user gesture keeps refining — it is still arriving.
-    async function settleInView(path, block, claim) {
-        const root = deps.getEditorRoot();
-        if (!root)
-            return deps.getBlockElByPath(path) != null;
-        let placedTop = null;
-        for (let i = 0; i < REVEAL_SETTLE_TICKS; i++) {
-            await tick();
-            if (claim.isSuperseded())
-                break;
-            const el = deps.getBlockElByPath(path);
-            if (!el) {
-                placedTop = null; // transiently unmounted mid re-slice — keep settling
-                continue;
-            }
-            // Converged: the anchor correction no longer disturbs the prior precise placement.
-            const afterAnchor = el.getBoundingClientRect().top;
-            if (afterAnchor === placedTop)
-                break;
-            el.scrollIntoView({ block });
-            placedTop = el.getBoundingClientRect().top;
-        }
-        const el = deps.getBlockElByPath(path);
-        return el != null && isInView(el, root);
-    }
     return {
         blockRect(path) {
             return deps.getBlockElByPath(path)?.getBoundingClientRect() ?? null;
         },
         rangeRects(path, start, end) {
-            return deps.getBlockComponentByPath(path)?.measurePartialRects?.(start, end) ?? [];
+            return deps.getBlockComponent(path)?.measurePartialRects?.(start, end) ?? [];
         },
         caretRect() {
-            // Read SelectionState, not the `data-cross-block` DOM mirror: that attribute is
-            // written by a deferred $effect and lags the synchronous selectionChange emit, so
-            // a subscriber reading mid-emit would get the parked range as a caret.
+            // Read `SelectionState`, not the `data-cross-block` attribute: a deferred `$effect`
+            // writes the attribute, so it lags the synchronous `selectionChange` emit.
             if (deps.isCrossBlock())
                 return null;
             const root = deps.getEditorRoot();
@@ -78,8 +20,8 @@ export function createEditorRects(deps) {
             const range = selection.getRangeAt(0);
             if (!root.contains(range.commonAncestorContainer))
                 return null;
-            // A caret in the host's header slot is inside the root but is not a document
-            // caret; reporting it would float caret-following chrome over the host's field.
+            // A caret in the host's header snippet is inside the root but is not a document
+            // caret; reporting it would float caret-following controls over the host's field.
             if (deps.isHostChrome(range.commonAncestorContainer))
                 return null;
             return range.getBoundingClientRect();
@@ -91,21 +33,11 @@ export function createEditorRects(deps) {
         async scrollTo(path, opts) {
             const p = [...path];
             const block = opts?.block ?? 'nearest';
-            // Claim before the first await so the pin survives a clearing gesture that
-            // triggered this reveal (a match click's pointerdown releases, then this re-claims).
-            const claim = deps.revealAnchor.claim(p, block);
+            // Placed before the first await so the hold survives the gesture that started this
+            // scroll (a match click's pointerdown releases, then this places again).
+            const placement = deps.scroll.place(p, { block, hold: opts?.hold !== false });
             await deps.revealPath(p);
-            // Gated: a claim superseded during a long mount wait would otherwise yank the
-            // viewport once, before the settle's first tick could bail it.
-            if (!claim.isSuperseded())
-                deps.getBlockElByPath(p)?.scrollIntoView({ block });
-            const landed = await settleInView(p, block, claim);
-            // Release on 'center': the anchor holds only a coarse pin, whose later corrections
-            // would drift a target the settle already placed exactly. 'nearest' holds by
-            // default — the coarse top-pin IS its contract. A failed reveal never pins.
-            if (block === 'center' || !landed || opts?.hold === false)
-                claim.release();
-            return landed;
+            return placement.scroll();
         },
         navigateTo(path, offset = 0) {
             return deps.landCaretAt([...path], offset);

package/dist/env.d.ts

@@ -1,12 +1,14 @@
 /**
- * The editor's toolchain-coupling seam: build flags come from `esm-env`, here and at the
- * `if (DEV)` gates whose constant a production build folds away. The override door for a
- * toolchain those defaults read wrong (a bundler resolving no export conditions, a runner
- * other than Vitest) is published on the `@voithos-labs/aragonite/testing` subpath, not from here.
+ * Where the editor reads its build flags, and the one module that imports `esm-env`. The way to
+ * override them for a toolchain these defaults read wrong (a bundler resolving no export
+ * conditions, a runner other than Vitest) is published on the `@voithos-labs/aragonite/testing`
+ * subpath, not here.
  */
 export declare const editorEnv: {
     isDev: boolean;
     isTest: boolean;
 };
+/** Whether dev-only checks run: in a dev build, or wherever the override turned dev on. */
+export declare function isDevChecks(): boolean;
 export declare function configureEditorEnv(partial: Partial<typeof editorEnv>): void;
 export declare function resetEditorEnv(): void;

package/dist/env.js

@@ -1,8 +1,8 @@
 /**
- * The editor's toolchain-coupling seam: build flags come from `esm-env`, here and at the
- * `if (DEV)` gates whose constant a production build folds away. The override door for a
- * toolchain those defaults read wrong (a bundler resolving no export conditions, a runner
- * other than Vitest) is published on the `@voithos-labs/aragonite/testing` subpath, not from here.
+ * Where the editor reads its build flags, and the one module that imports `esm-env`. The way to
+ * override them for a toolchain these defaults read wrong (a bundler resolving no export
+ * conditions, a runner other than Vitest) is published on the `@voithos-labs/aragonite/testing`
+ * subpath, not here.
  */
 import { DEV } from 'esm-env';
 function computeDefaults() {
@@ -12,6 +12,10 @@ function computeDefaults() {
     };
 }
 export const editorEnv = computeDefaults();
+/** Whether dev-only checks run: in a dev build, or wherever the override turned dev on. */
+export function isDevChecks() {
+    return DEV || editorEnv.isDev;
+}
 export function configureEditorEnv(partial) {
     Object.assign(editorEnv, partial);
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { default as Editor } from './components/Editor.svelte';
-export type { EditorProps, EditorInstance } from './editor-props';
+export type { EditorProps, EditorInstance, InsertMarkdownOptions, SyntaxOptions } from './editor-props';
 export type { EditorDiagnostics, InteractionTraceEntry } from './editor-props';
 export type { BlockComponent } from './block-component';
 export type { ResolveImageUrl, ResolveLinkUrl, PastedImage, PasteImageHook, CodeRunRequest, RunCodeHook, CodeMenuItem, CodeMenuItemsHook } from './editor-keys';
@@ -20,8 +20,12 @@ export { parseInline, getContentRange, isProseKind } from './core/inline';
 export type { ContentRange } from './core/inline';
 export type { BlockKind, LeafBlockKind, ContainerBlockKind, AnyBlockKind, CstNode, Document, BlockMetadata, HeadingMetadata, SetextHeadingMetadata, FencedCodeMetadata, ThematicBreakMetadata, LinkReferenceDefinitionMetadata, TableMetadata, BlockquoteMetadata, ListMetadata, ListItemMetadata, InlineNodeKind, InlineNode } from './core/nodes';
 export type { NodeView, DocumentView } from './core/node-views';
-export type { EditorEvents, EditEvent, EditorEventMap, EditorError, SelectionChangeEvent } from './editor-events';
+export type { EditorEvents, EditEvent, EditorEventMap, EditorError, SelectionChangeEvent, SourceSwapEvent } from './editor-events';
 export type { Decoration, MarkDecoration, WidgetDecoration, ReplaceDecoration, BlockDecoration, DecorationWidgetSpec, ProvideContext, DecorationSource, DecorationSourceHandle, DecorationRegistry } from './decorations/types';
 export type { EditorRects } from './editor-rects';
 export { SELECTION_END } from './block-component';
 export type { SelectionEnd } from './block-component';
+export type { InlineMenuRegistry, InlineMenuOpenOptions, InlineMenuSource, InlineMenuSourceHandle, InlineMenuItem, InlineMenuQuery, InlineMenuRowProps } from './inline-menu/types';
+export { registerInsertEntry } from './schema/insert-catalogue';
+export type { InsertEntry } from './schema/insert-catalogue';
+export type { MenuIconName } from './menu-icons';

package/dist/index.js

@@ -1,4 +1,4 @@
-// Public, supported surface of the editor module: adding an export is non-breaking,
+// The editor module's public, supported API: adding an export is non-breaking,
 // removing one is breaking. Anything not re-exported here is internal.
 // ── Component ────────────────────────────────────────────────────────────────
 export { default as Editor } from './components/Editor.svelte';
@@ -10,10 +10,13 @@ export { installPlugins } from './schema/plugin-install';
 // re-derive path-lexicographic comparison.
 export { normalize as normalizeSelection } from './selection/primitives';
 // ── Commands (pre-freeze: the id space opens up when the command registry unifies) ──
-// The ids `editor.runCommand()` supports — what a selection toolbar needs.
+// The ids `editor.runCommand()` supports: what a selection toolbar needs.
 export { TOOLBAR_COMMANDS } from './schema/commands';
 // ── CST utilities ────────────────────────────────────────────────────────────
 export { parse } from './core/parser';
 export { serialize } from './core/serializer';
 export { parseInline, getContentRange, isProseKind } from './core/inline';
 export { SELECTION_END } from './block-component';
+// ── Insert catalogue ───────────────────────────────────────────────────────────
+// The blocks the insert menus offer, plugin blocks included, via `editor.getInsertCatalogue()`.
+export { registerInsertEntry } from './schema/insert-catalogue';

package/dist/inline-menu/inline-menu-session.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The inline menu's rules: which source a just-typed trigger opens, where in a line of prose it
+ * may open at all, and what an open session's query is now. Pure, so all three are testable
+ * without an editor.
+ */
+import type { InlineNode } from '../core/nodes';
+import type { GrammarView } from '../schema/block-openers';
+import type { InlineMenuSource } from './types';
+/** Identity only, never a captured node: every keystroke writes a new leaf to state. */
+export interface InlineMenuSession {
+    source: string;
+    path: number[];
+    /** Raw offset of the trigger's first byte. */
+    start: number;
+    triggerLength: number;
+}
+export interface InlineMenuOpening {
+    source: InlineMenuSource;
+    start: number;
+}
+/** The source a just-typed run opens; `from` is where the run began, since a burst of keystrokes
+ *  arrives as one change. The trigger nearest the caret wins, then the longer, so `[[` beats `[`. */
+export declare function findOpening(sources: Iterable<InlineMenuSource>, raw: string, caret: number, from: number): InlineMenuOpening | null;
+/** Whether a trigger at this offset sits in prose the author is writing, as each construct's
+ *  policy row declares: a link's text is prose, its destination and a code span are not. */
+export declare function isProseOffset(nodes: InlineNode[], offset: number, grammar: GrammarView): boolean;
+/** Whether the offset sits in a destination opened with `](` and not yet closed: those bytes are
+ *  text until the `)` lands, so the inline tree has no link to decline. */
+export declare function isUnclosedDestination(raw: string, offset: number): boolean;
+/** Where the just-typed run began, or null when the change from `previous` to `raw` is anything
+ *  but bytes inserted to end at the caret (a deletion, a caret move, an edit elsewhere). */
+export declare function typedRunStart(previous: string, raw: string, caret: number): number | null;
+/** The open session's query at this caret, or null once the session is over: the trigger is
+ *  gone, the caret stepped in front of the query, or the source declines what was typed. */
+export declare function sessionQuery(session: InlineMenuSession, source: InlineMenuSource, raw: string, caret: number): string | null;
+/** Step the active row, wrapping at both ends; a list of none has no active row. */
+export declare function stepActive(index: number, delta: 1 | -1, count: number): number;