@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/plugins/slash-commands/slash-source.js

@@ -0,0 +1,108 @@
+/**
+ * The `/` list: the insert catalogue, three heading rows and the host's own entries, read fresh
+ * from the editor on every keystroke. A pick removes the `/query` bytes first (its `insert` is
+ * empty), then `onCommit` does the row's work through the editor's own entry points.
+ */
+import { blockNodeAt, isBlankText } from '../../plugin';
+import { acceptsQuery, filterEntries, splitQuery } from './filter';
+export const SLASH_COMMANDS_MENU = 'slash-commands';
+const HEADING_LEVELS = [1, 2, 3];
+/** The `/` source for one editor: its rows come from `editor.options` and the live catalogue. */
+export function createSlashSource(editor) {
+    function rows() {
+        const { entries = [], exclude = [] } = editor.options;
+        const hidden = new Set([...exclude, ...entries.map((entry) => entry.id)]);
+        const builtIn = [
+            ...editor.insertCatalogue.map(catalogueRow),
+            ...HEADING_LEVELS.map(headingRow)
+        ];
+        return [...builtIn.filter((row) => !hidden.has(row.id)), ...entries.map(hostRow)];
+    }
+    return {
+        name: SLASH_COMMANDS_MENU,
+        trigger: '/',
+        // A slash inside a word (`and/or`, `9/22`) is text.
+        opensAt: (raw, pos) => pos === 0 || /\s/.test(raw[pos - 1]),
+        accepts: (query) => acceptsQuery(rows(), query),
+        items: ({ query }) => {
+            const { head, argument } = splitQuery(query);
+            return filterEntries(rows(), head).map((row) => ({
+                id: row.id,
+                label: row.label,
+                icon: row.icon,
+                detail: argument === null ? undefined : argumentDetail(row, argument),
+                insert: ''
+            }));
+        },
+        onCommit: async (item, range) => {
+            const row = rows().find((candidate) => candidate.id === item.id);
+            if (!row)
+                return;
+            const { argument } = splitQuery(range.query);
+            const action = row.action;
+            if (action.kind === 'heading') {
+                editor.runCommand('heading.cycle', action.level);
+            }
+            else if (action.kind === 'run') {
+                action.run(editor, argument ?? undefined);
+            }
+            else {
+                // An empty line becomes the block; a line with text keeps it and gets the block below.
+                // Copied because `blockNodeAt` takes a mutable path and the range's is readonly.
+                const empty = isBlankText(blockNodeAt(editor.document, [...range.path])?.raw ?? '');
+                // Awaited, so the block lands inside the pick's undo entry.
+                await editor.insertMarkdown(action.build(argument).markdown, {
+                    placement: empty ? 'caret' : 'below'
+                });
+            }
+        }
+    };
+}
+// ── Rows ─────────────────────────────────────────────────────────────────────
+function catalogueRow(entry) {
+    const { withArgument } = entry;
+    return {
+        id: entry.id,
+        label: entry.label,
+        icon: entry.icon,
+        keywords: entry.keywords,
+        takesArgument: withArgument !== undefined,
+        action: {
+            kind: 'insert',
+            // A space with no word after it yet is no argument, so `withArgument` only sees a word.
+            build: (argument) => argument && withArgument ? withArgument(argument) : { markdown: entry.markdown }
+        }
+    };
+}
+function headingRow(level) {
+    return {
+        id: `h${level}`,
+        label: `Heading ${level}`,
+        icon: 'heading',
+        keywords: [`h${level}`, 'heading', 'title'],
+        takesArgument: false,
+        action: { kind: 'heading', level }
+    };
+}
+function hostRow(entry) {
+    const base = {
+        id: entry.id,
+        label: entry.label,
+        icon: entry.icon,
+        keywords: entry.keywords ?? []
+    };
+    if (entry.run) {
+        return {
+            ...base,
+            takesArgument: !!entry.takesArgument,
+            action: { kind: 'run', run: entry.run }
+        };
+    }
+    const markdown = entry.insert ?? '';
+    return { ...base, takesArgument: false, action: { kind: 'insert', build: () => ({ markdown }) } };
+}
+function argumentDetail(row, argument) {
+    if (row.action.kind === 'insert')
+        return row.action.build(argument).detail;
+    return argument === '' ? undefined : argument;
+}

package/dist/plugins/toc/TocBlock.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
-	// Render-primary editable leaf: all editing behavior lives in `createEditableLeaf`,
-	// so this component owns only the list↔source swap and navigation.
+	// A render-primary editable block: all editing behavior lives in `createEditableLeaf`, so
+	// this component owns only the swap between the list and the source, and navigation.
 	import {
 		createEditableLeaf,
 		type BlockComponent,
@@ -8,23 +8,22 @@
 		type EditorRects,
 		type NodeView
 	} from '../../plugin';
-	import { collectHeadings, resolveMaxDepth } from './heading-outline';
+	import { collectHeadings, MAX_HEADING_DEPTH } from './heading-outline';
 	import { createNavigationQueue } from './navigation-queue';
+	import type { TocOptions } from './toc-plugin';
 
 	let {
 		node,
 		index,
 		myPath = [],
 		document,
-		rects,
-		maxDepth = 6
+		rects
 	}: {
 		node: NodeView;
 		index: number;
 		myPath?: number[];
 		document?: DocumentView;
 		rects?: EditorRects;
-		maxDepth?: number;
 	} = $props();
 
 	let sourceEl: HTMLDivElement | undefined = $state();
@@ -42,22 +41,24 @@
 		}
 	});
 
-	// Instance options win; the `maxDepth` prop is the factory argument, which a bare install
-	// (and only a bare install) is configured by.
-	const depth = $derived(resolveMaxDepth(leaf.getOptions(), maxDepth));
+	// Undefined only for a block mounted with no editor, as the unit tests mount it.
+	const options = leaf.getOptions() as Required<TocOptions> | undefined;
+	const depth = options?.maxDepth ?? MAX_HEADING_DEPTH;
 
-	// The walk reads heading bytes through the prop, subscribing to the CST's $state proxy, so
-	// an edit above re-runs it; it stays uncached to keep the derived reactive-safe.
-	const headings = $derived(collectHeadings(document, depth));
+	// This reads heading bytes through the prop, subscribing to the CST's $state proxy, so an
+	// edit above re-runs it; left uncached so the derived stays reactive.
+	const headings = $derived(
+		collectHeadings(document, depth, leaf.getEditor()?.computeInlineContent)
+	);
 
-	// Serialized per block (see `navigation-queue.ts` for why). `navigateTo` lands the caret as
-	// well as scrolling, so focus never stays where the editor's chords cannot reach it.
+	// One navigation at a time per block (`navigation-queue.ts` says why). `navigateTo` moves
+	// the caret as well as scrolling, so focus never stays somewhere the keyboard cannot reach.
 	const navigation = createNavigationQueue({
 		navigateTo: (path) => rects?.navigateTo(path) ?? Promise.resolve()
 	});
 
-	// Suppresses the leaf's reveal-on-pointerdown so an entry activation navigates
-	// instead of folding the block open. View-only, so it works in reading mode too.
+	// Stops the block showing its source on pointerdown, so clicking an entry navigates instead
+	// of opening the source. It only reads, so it works in reading mode too.
 	function onEntryPointerDown(e: PointerEvent): void {
 		e.stopPropagation();
 	}
@@ -74,8 +75,8 @@
 	export const getSelectedText = leaf.getSelectedText;
 	export const setSelection = leaf.setSelection;
 	export const measurePartialRects = leaf.measurePartialRects;
-	export const runCommand = leaf.runCommand;
 	export const insertMarkdown = leaf.insertMarkdown;
+	export const afterSourceCommit = leaf.afterSourceCommit;
 
 	void ({
 		editable,
@@ -87,8 +88,8 @@
 		getSelectedText,
 		setSelection,
 		measurePartialRects,
-		runCommand,
-		insertMarkdown
+		insertMarkdown,
+		afterSourceCommit
 	} satisfies BlockComponent);
 </script>
 
@@ -131,7 +132,7 @@
 {/if}
 
 <style>
-	/* Deltas over the shared .md-source-surface (editor.css). */
+	/* Only the differences from the shared .md-source-surface (editor.css). */
 	.toc-block-source {
 		outline: none;
 		padding: 8px 12px;
@@ -157,8 +158,8 @@
 		list-style: none;
 	}
 
-	/* Native button chrome reset to a plain full-row entry: the accent hover and focus
-	   ring are the only affordances. */
+	/* The browser's button styling is reset to a plain full-width row: the accent hover and
+	   the focus ring are the only cues. */
 	.toc-block-item {
 		display: block;
 		width: 100%;

package/dist/plugins/toc/TocBlock.svelte.d.ts

@@ -5,7 +5,6 @@ type $$ComponentProps = {
     myPath?: number[];
     document?: DocumentView;
     rects?: EditorRects;
-    maxDepth?: number;
 };
 declare const TocBlock: import("svelte").Component<$$ComponentProps, {
     editable: true;
@@ -17,8 +16,8 @@ declare const TocBlock: import("svelte").Component<$$ComponentProps, {
     getSelectedText: () => string;
     setSelection: (start: number, end: number) => void;
     measurePartialRects: (startOffset: number, endOffset: number) => DOMRect[];
-    runCommand: (id: import("../../plugin").CommandId) => boolean;
-    insertMarkdown: (md: string) => boolean;
+    insertMarkdown: (md: string) => Promise<boolean>;
+    afterSourceCommit: (run: () => void) => void;
 }, "">;
 type TocBlock = ReturnType<typeof TocBlock>;
 export default TocBlock;

package/dist/plugins/toc/heading-outline.d.ts

@@ -1,21 +1,15 @@
 /**
- * The heading outline as a pure function over the read-only document. The walk
- * recurses through containers, so a heading nested in a blockquote or list is still
- * collected at its own path and remains navigable.
+ * The heading outline as a pure function over the read-only document. It recurses through
+ * containers, so a heading nested in a blockquote or list is still collected at its own path
+ * and stays navigable.
  */
-import { type DocumentView, type InlineNode } from '../../plugin';
+import { type DocumentView, type EditorContext, type InlineNode } from '../../plugin';
 /** Deepest heading level a document can list; `[[toc]]` has no meaning past GFM's six. */
 export declare const MAX_HEADING_DEPTH = 6;
-/**
- * The instance's `{ plugin, options }` depth, else `fallback` (the factory argument's
- * bare-install default). Options arrive as `unknown` from the platform, so anything but a
- * whole number in 1..6 is not a depth and falls back rather than listing nothing.
- */
-export declare function resolveMaxDepth(options: unknown, fallback: number): number;
 export interface TocEntry {
     /** Stable and unique per position: the keyed-loop identity. */
     id: string;
-    /** Doc-absolute block path of the heading, for `rects.scrollTo`. */
+    /** Document-absolute block path of the heading, for `rects.scrollTo`. */
     path: number[];
     level: number;
     label: string;
@@ -25,4 +19,5 @@ export interface TocEntry {
  * render to, and anything unrecognized falls back to its source bytes.
  */
 export declare function projectInlineText(nodes: readonly InlineNode[], raw: string): string;
-export declare function collectHeadings(document: DocumentView | undefined, maxDepth: number): TocEntry[];
+/** Labels read through `read`, the editor's inline parse, so syntax it left out stays text. */
+export declare function collectHeadings(document: DocumentView | undefined, maxDepth: number, read?: EditorContext['computeInlineContent']): TocEntry[];

package/dist/plugins/toc/heading-outline.js

@@ -1,22 +1,11 @@
 /**
- * The heading outline as a pure function over the read-only document. The walk
- * recurses through containers, so a heading nested in a blockquote or list is still
- * collected at its own path and remains navigable.
+ * The heading outline as a pure function over the read-only document. It recurses through
+ * containers, so a heading nested in a blockquote or list is still collected at its own path
+ * and stays navigable.
  */
-import { computeInlineContent, headingLevel } from '../../plugin';
+import { computeInlineContent, headingLevel, trimWhitespace, walkBlocks } from '../../plugin';
 /** Deepest heading level a document can list; `[[toc]]` has no meaning past GFM's six. */
 export const MAX_HEADING_DEPTH = 6;
-/**
- * The instance's `{ plugin, options }` depth, else `fallback` (the factory argument's
- * bare-install default). Options arrive as `unknown` from the platform, so anything but a
- * whole number in 1..6 is not a depth and falls back rather than listing nothing.
- */
-export function resolveMaxDepth(options, fallback) {
-    const declared = options?.maxDepth;
-    if (typeof declared !== 'number' || !Number.isInteger(declared))
-        return fallback;
-    return declared >= 1 && declared <= MAX_HEADING_DEPTH ? declared : fallback;
-}
 /**
  * Plain-text projection: markers drop with their wrapper, value nodes show what they
  * render to, and anything unrecognized falls back to its source bytes.
@@ -39,27 +28,24 @@ export function projectInlineText(nodes, raw) {
     }
     return text;
 }
-export function collectHeadings(document, maxDepth) {
+/** Labels read through `read`, the editor's inline parse, so syntax it left out stays text. */
+export function collectHeadings(document, maxDepth, read = computeInlineContent) {
     const entries = [];
-    const walk = (children, basePath) => {
-        children.forEach((node, index) => {
-            const path = [...basePath, index];
-            const level = headingLevel(node);
-            if (level !== null) {
-                if (level <= maxDepth) {
-                    entries.push({
-                        id: path.join('.'),
-                        path,
-                        level,
-                        label: projectInlineText(computeInlineContent(node), node.raw).trim()
-                    });
-                }
-            }
-            else if (node.children && node.children.length > 0) {
-                walk(node.children, path);
-            }
-        });
-    };
-    walk(document?.children ?? [], []);
+    if (!document)
+        return entries;
+    walkBlocks(document, (node, path) => {
+        const level = headingLevel(node);
+        if (level === null)
+            return;
+        if (level <= maxDepth) {
+            entries.push({
+                id: path.join('.'),
+                path,
+                level,
+                label: trimWhitespace(projectInlineText(read(node), node.raw))
+            });
+        }
+        return 'skip';
+    });
     return entries;
 }

package/dist/plugins/toc/navigation-queue.d.ts

@@ -1,8 +1,6 @@
 /**
- * Per-block serialization for `rects.navigateTo`. The reveal anchor
- * (`cursor/reveal-anchor.ts`) decides which pin survives a race but cannot un-land a
- * caret, and two overlapping navigations from one block land two. A mid-flight call
- * overwrites the pending target, so the newest wins with no extra scroll.
+ * One `rects.navigateTo` at a time per block, since two overlapping navigations would move the
+ * caret twice. A call while one is in progress replaces the pending target, so the newest wins.
  */
 export interface NavigationQueue {
     navigateTo(path: number[]): Promise<void>;

package/dist/plugins/toc/toc-plugin.d.ts

@@ -1,14 +1,14 @@
 /**
- * A `[[toc]]` leaf whose folded view lists the document's headings, read straight off
- * `BlockComponentProps.document` — the reference consumer of that prop. Recognition is
- * gated on registration, so with no plugin loaded `[[toc]]` is a plain paragraph.
+ * A `[[toc]]` block whose rendered view lists the document's headings, read straight off
+ * `BlockComponentProps.document`: the worked example of using that prop. Recognition starts
+ * only once the plugin registers, so without it `[[toc]]` is a plain paragraph.
  */
 import { type EditorPlugin } from '../../plugin';
 export declare const TOC_BLOCK = "toc";
 export declare function registerTocBlock(): void;
 export type MaxHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
-/** The per-instance `{ plugin, options }` shape, and the factory argument's, which are one
- *  vocabulary on purpose: the instance entry overrides the factory default. */
+/** The factory argument, which sets every editor's default, and an editor's `{ plugin, options }`
+ *  entry, which overrides it. */
 export interface TocOptions {
     /** Deepest heading level listed (default 6 = every level). */
     maxDepth?: MaxHeadingLevel;

package/dist/plugins/toc/toc-plugin.js

@@ -1,7 +1,7 @@
 /**
- * A `[[toc]]` leaf whose folded view lists the document's headings, read straight off
- * `BlockComponentProps.document` — the reference consumer of that prop. Recognition is
- * gated on registration, so with no plugin loaded `[[toc]]` is a plain paragraph.
+ * A `[[toc]]` block whose rendered view lists the document's headings, read straight off
+ * `BlockComponentProps.document`: the worked example of using that prop. Recognition starts
+ * only once the plugin registers, so without it `[[toc]]` is a plain paragraph.
  */
 import { definePlugin, declarePluginKind, declaredPluginKind, registerBlockKind, registerBlockOpener, registerBlockComponent, defineBlockComponent, simpleLeafClosure, OPENER_PRIORITIES } from '../../plugin';
 import TocBlock from './TocBlock.svelte';
@@ -10,14 +10,15 @@ export const TOC_BLOCK = 'toc';
 const TOC_LINE = '[[toc]]';
 export function registerTocBlock() {
     const toc = declarePluginKind(TOC_BLOCK);
-    // A source-holding leaf like `fencedCode`: `serialize` re-emits `leadingTrivia + raw`,
-    // so a raw taken verbatim from the line round-trips.
+    // A block that holds its own source, like `fencedCode`: `serialize` re-emits
+    // `leadingTrivia + raw`, so a raw taken verbatim from the line round-trips.
     registerBlockKind(toc, {
+        label: 'Table of contents',
         mergeRole: 'not-mergeable',
         editable: true,
         supportsInline: false,
-        // Render-primary like the math forms: the folded view leaves a caret no textual landing
-        // at either edge, so both boundaries open against another trapped kind.
+        // Render-primary like the math blocks: the rendered view gives the caret nowhere to sit
+        // at either edge, so both edges take the gap caret.
         gapEdges: 'both',
         conformanceFixture: '[[toc]]\n',
         closure: simpleLeafClosure({
@@ -41,8 +42,8 @@ export function registerTocBlock() {
         })
     });
     registerBlockOpener(toc, {
-        // Gap placement below the only bracket-consuming built-in, so `[[toc]]` resolves here
-        // whatever that matcher claims.
+        // Just below the only built-in that consumes brackets, so `[[toc]]` resolves here
+        // whatever that matcher does.
         priority: OPENER_PRIORITIES.linkReferenceDefinition - 5,
         interruptsParagraph: (text) => text === TOC_LINE,
         tryOpen(ctx) {
@@ -58,14 +59,20 @@ export function registerTocBlock() {
     });
 }
 export function tocPlugin(options) {
-    // Definition-time, so it is the BARE-install default only: the block prefers this editor's
-    // `{ plugin, options }` depth, which is what lets two instances differ.
-    const maxDepth = options?.maxDepth ?? MAX_HEADING_DEPTH;
     return definePlugin({
         name: 'toc',
+        defaults: { maxDepth: options?.maxDepth ?? MAX_HEADING_DEPTH },
+        // Anything but a whole number in 1..6 keeps the default rather than listing nothing.
+        parseOptions(raw) {
+            const maxDepth = raw?.maxDepth;
+            return isMaxHeadingLevel(maxDepth) ? { maxDepth } : {};
+        },
         setup() {
             registerTocBlock();
-            registerBlockComponent(declaredPluginKind(TOC_BLOCK), defineBlockComponent(TocBlock, () => ({ maxDepth })));
+            registerBlockComponent(declaredPluginKind(TOC_BLOCK), defineBlockComponent(TocBlock));
         }
     });
 }
+function isMaxHeadingLevel(value) {
+    return (Number.isInteger(value) && value >= 1 && value <= MAX_HEADING_DEPTH);
+}

package/dist/presentation-mode.d.ts

@@ -1,32 +1,24 @@
 /**
- * The presentation-mode contract. `source` is the editing default (always-visible styled
- * source); `reading` hides markers and makes the surface inert; `preview-block` reveals the
- * caret's block and `preview-inline` narrows that reveal to the caret-touched construct
- * (`components/blocks/text/construct-reveal.ts`); `live` hides markers with no reveal at all,
- * while staying editable. Every door reports the EFFECTIVE mode.
+ * The presentation-mode contract. `source` is the editing default (styled source); `reading`
+ * hides markers and is read-only; the preview modes show markers back in the caret's block or
+ * construct (`components/blocks/text/construct-reveal.ts`); `live` hides markers and shows none
+ * back while staying editable. Every read reports the mode in effect.
  */
 export type PresentationMode = 'source' | 'reading' | 'preview-block' | 'preview-inline' | 'live';
-/**
- * A mode read off the DOM or handed in untyped, narrowed to the contract. The marker-hiding CSS
- * families match known values only, so an unrecognized one must read as the editing default here or
- * the stylesheet and the caret walk disagree about the same block.
- */
+/** Narrows a mode read off the DOM or handed in untyped: an unrecognized value reads as the
+ *  editing default, as the marker-hiding CSS does, or the two would disagree about a block. */
 export declare function asPresentationMode(value: string | null | undefined): PresentationMode;
 /** Membership for the marker-hiding CSS families and the `data-list-marker` hook that
  *  feeds them: styled source is the one mode that paints Markdown syntax. */
 export declare function hidesMarkers(mode: PresentationMode): boolean;
-/** The reveal-on-focus rungs, which alone need the `data-focused` attribute — live hides
- *  markers (see `hidesMarkers`) but never reveals them, so it is deliberately not one. */
+/** The modes that show markers back in a focused block, the only ones needing `data-focused`;
+ *  live hides markers and never shows them back. */
 export declare function isPreviewMode(mode: PresentationMode): boolean;
-/**
- * Whether the mode paints a marker in the block the caret is in: styled source always, and the
- * preview rungs by revealing that block. The question every seam writing at the caret asks, since
- * a rewrite may only drop bytes the reader never saw (live-mode.md § 2).
- */
+/** Whether the mode paints markers in the caret's block: the check everything writing at the caret
+ *  asks, since a rewrite may drop only bytes the user never saw (`docs/design/live-mode.md` § 2). */
 export declare function paintsFocusedMarkers(mode: PresentationMode): boolean;
-/**
- * The read-only gate the dispatch seams key off. Structural parameter type so the
- * schema/selection layers need no editor-keys import; an `undefined` getter (test
- * doubles, unwired surfaces) means not reading.
- */
-export declare function isReadingMode(getMode: (() => PresentationMode) | undefined): boolean;
+/** The converse, the one check a rewrite asks before dropping delimiter bytes at the caret. */
+export declare function hidesDelimitersAtCaret(mode: PresentationMode): boolean;
+/** The read-only check every dispatch path keys off. A plain getter type keeps `schema/` and
+ *  `selection/` off `editor-keys`; the getter is required, since only the editor picks the default. */
+export declare function isReadingMode(getMode: () => PresentationMode): boolean;

package/dist/presentation-mode.js

@@ -1,12 +1,11 @@
 /**
- * The presentation-mode contract. `source` is the editing default (always-visible styled
- * source); `reading` hides markers and makes the surface inert; `preview-block` reveals the
- * caret's block and `preview-inline` narrows that reveal to the caret-touched construct
- * (`components/blocks/text/construct-reveal.ts`); `live` hides markers with no reveal at all,
- * while staying editable. Every door reports the EFFECTIVE mode.
+ * The presentation-mode contract. `source` is the editing default (styled source); `reading`
+ * hides markers and is read-only; the preview modes show markers back in the caret's block or
+ * construct (`components/blocks/text/construct-reveal.ts`); `live` hides markers and shows none
+ * back while staying editable. Every read reports the mode in effect.
  */
-/** Keyed by the union, so a rung added to it fails `npm run check` here rather than falling
- *  silently through {@link asPresentationMode}'s door. */
+/** Keyed by the union, so a mode added to it fails `npm run check` here rather than falling
+ *  silently through {@link asPresentationMode}. */
 const MODES = {
     source: true,
     reading: true,
@@ -14,11 +13,8 @@ const MODES = {
     'preview-inline': true,
     live: true
 };
-/**
- * A mode read off the DOM or handed in untyped, narrowed to the contract. The marker-hiding CSS
- * families match known values only, so an unrecognized one must read as the editing default here or
- * the stylesheet and the caret walk disagree about the same block.
- */
+/** Narrows a mode read off the DOM or handed in untyped: an unrecognized value reads as the
+ *  editing default, as the marker-hiding CSS does, or the two would disagree about a block. */
 export function asPresentationMode(value) {
     return value != null && Object.hasOwn(MODES, value) ? value : 'source';
 }
@@ -27,24 +23,22 @@ export function asPresentationMode(value) {
 export function hidesMarkers(mode) {
     return mode !== 'source';
 }
-/** The reveal-on-focus rungs, which alone need the `data-focused` attribute — live hides
- *  markers (see `hidesMarkers`) but never reveals them, so it is deliberately not one. */
+/** The modes that show markers back in a focused block, the only ones needing `data-focused`;
+ *  live hides markers and never shows them back. */
 export function isPreviewMode(mode) {
     return mode === 'preview-block' || mode === 'preview-inline';
 }
-/**
- * Whether the mode paints a marker in the block the caret is in: styled source always, and the
- * preview rungs by revealing that block. The question every seam writing at the caret asks, since
- * a rewrite may only drop bytes the reader never saw (live-mode.md § 2).
- */
+/** Whether the mode paints markers in the caret's block: the check everything writing at the caret
+ *  asks, since a rewrite may drop only bytes the user never saw (`docs/design/live-mode.md` § 2). */
 export function paintsFocusedMarkers(mode) {
     return !hidesMarkers(mode) || isPreviewMode(mode);
 }
-/**
- * The read-only gate the dispatch seams key off. Structural parameter type so the
- * schema/selection layers need no editor-keys import; an `undefined` getter (test
- * doubles, unwired surfaces) means not reading.
- */
+/** The converse, the one check a rewrite asks before dropping delimiter bytes at the caret. */
+export function hidesDelimitersAtCaret(mode) {
+    return !paintsFocusedMarkers(mode);
+}
+/** The read-only check every dispatch path keys off. A plain getter type keeps `schema/` and
+ *  `selection/` off `editor-keys`; the getter is required, since only the editor picks the default. */
 export function isReadingMode(getMode) {
-    return getMode?.() === 'reading';
+    return getMode() === 'reading';
 }

package/dist/reactivity/block-list-state.svelte.d.ts

@@ -1,22 +1,20 @@
 /**
- * A container's inner BlockList scope: the keyed-each id source and the component-ref slot
- * array. Structural mutations route through the commit primitives on UndoController, which
- * apply `StructuralChange` descriptors to keep ids/refs aligned with children.
+ * A container's inner block list: where its keyed-each ids come from and where its child
+ * component refs are stored. Structural changes go through the commit calls on
+ * `UndoController`, which apply a `StructuralChange` to keep ids and refs lined up with the
+ * children.
  */
 import type { BlockComponent } from '../block-component';
 import type { NodeView } from '../core/node-views';
 import { type RefSlots } from './publish-ref.svelte';
 export interface BlockListState {
-    /** Settable because ids live on the node, where the write reaches the `$state` proxy.
-     *  Refs do not: the array identity IS the scope, so `replaceRefs` publishes contents
-     *  and the property itself never moves. */
+    /** Settable because the ids live on the node, where the write reaches the `$state` proxy.
+     *  The refs array keeps its identity for life; `replaceRefs` rewrites its contents. */
     innerBlockIds: string[];
     readonly innerBlockRefs: (BlockComponent | undefined)[];
-    /** This scope's slot accessors, minted once here so every consumer — the child list,
-     *  the container surface, the mount registry — addresses the scope by one identity. */
+    /** The accessors over `innerBlockRefs` that a child's mount writes through. */
     readonly refSlots: RefSlots<BlockComponent>;
 }
-/** `getNode` must be a live getter — by-value freezes on the initial node and misses
- *  undo's deep-clone reassignment. A view suffices: the only writes target `childIds`,
- *  the bytes-view carve-out. */
+/** `getNode` must be a live getter: a node passed by value goes stale when undo swaps in a deep
+ *  clone. A view is enough, since `childIds` is the only field written. */
 export declare function createBlockListState(getNode: () => NodeView): BlockListState;