@voithos-labs/aragonite 0.10.1

package/dist/plugins/parrot/ParrotBlock.svelte.d.ts

@@ -0,0 +1,21 @@
+import { type NodeView } from '../../plugin';
+type $$ComponentProps = {
+    node: NodeView;
+    index: number;
+    myPath?: number[];
+};
+declare const ParrotBlock: import("svelte").Component<$$ComponentProps, {
+    editable: true;
+    focusable: true;
+    focus: (offset: number) => void;
+    getCursorOffset: () => number | null;
+    parkCaret: (offset: number) => void;
+    focusAtColumn: (x: number, from: import("../../plugin").StickyColumnDirection) => void;
+    getSelectedText: () => string;
+    setSelection: (start: number, end: number) => void;
+    measurePartialRects: (startOffset: number, endOffset: number) => DOMRect[];
+    runCommand: (id: import("../../plugin").CommandId) => boolean;
+    insertMarkdown: (md: string) => boolean;
+}, "">;
+type ParrotBlock = ReturnType<typeof ParrotBlock>;
+export default ParrotBlock;

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

@@ -0,0 +1 @@
+export { parrotPlugin, PARROT } from './parrot-plugin';

package/dist/plugins/parrot/index.js

@@ -0,0 +1,2 @@
+// A `%%parrot` line dances as an ASCII party parrot; frames via terminal-parrot (MIT).
+export { parrotPlugin, PARROT } from './parrot-plugin';

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

@@ -0,0 +1,3 @@
+import { type EditorPlugin } from '../../plugin';
+export declare const PARROT = "parrot";
+export declare function parrotPlugin(): EditorPlugin;

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

@@ -0,0 +1,49 @@
+// parrot-plugin.ts
+import { caretOffsetAtPoint, declarePluginKind, definePluginBlock, registerBlockKind, registerBlockOpener, simpleLeafClosure } from '../../plugin';
+import ParrotBlock from './ParrotBlock.svelte';
+export const PARROT = 'parrot';
+/** Where a press in the block puts the caret. The caption renders the bytes after `%%parrot `,
+ *  so an offset in it sits that far along the source; the revealed source IS the source. */
+function parrotCaretAtPoint(blockEl, clientX, clientY) {
+    const source = blockEl.querySelector('.parrot-source');
+    const view = source ?? blockEl.querySelector('.parrot-caption');
+    if (!view)
+        return null;
+    const offset = caretOffsetAtPoint(view, clientX, clientY) ?? 0;
+    return { path: [], offset: source ? offset : offset + '%%parrot '.length };
+}
+function registerParrotBlock() {
+    const parrot = declarePluginKind(PARROT);
+    registerBlockKind(parrot, {
+        gapEdges: 'none',
+        mergeRole: 'not-mergeable',
+        editable: true,
+        supportsInline: false,
+        conformanceFixture: '%%parrot party responsibly\n',
+        caretTargetAtPoint: parrotCaretAtPoint,
+        closure: simpleLeafClosure({
+            focus: { mode: 'implemented', via: 'createEditableLeaf render-primary reveal' },
+            searchPaint: { mode: 'implemented', via: 'source raw scanned, matches painted as marks' },
+            undo: { mode: 'implemented', via: 'render-primary: one commit when the caret leaves' },
+            simOracle: { mode: 'inherit-default' }
+        })
+    });
+    registerBlockOpener(parrot, {
+        priority: 25,
+        interruptsParagraph: (text) => text.startsWith('%%parrot'),
+        tryOpen(ctx) {
+            if (!ctx.line.text.startsWith('%%parrot'))
+                return null;
+            const node = { kind: parrot, leadingTrivia: ctx.leadingTrivia, raw: ctx.line.raw };
+            return { node, consumed: 1 };
+        }
+    });
+}
+export function parrotPlugin() {
+    return definePluginBlock({
+        name: 'parrot',
+        kind: PARROT,
+        component: ParrotBlock,
+        register: registerParrotBlock
+    });
+}

package/dist/plugins/toc/TocBlock.svelte

@@ -0,0 +1,218 @@
+<script lang="ts">
+	// Render-primary editable leaf: all editing behavior lives in `createEditableLeaf`,
+	// so this component owns only the list↔source swap and navigation.
+	import {
+		createEditableLeaf,
+		type BlockComponent,
+		type DocumentView,
+		type EditorRects,
+		type NodeView
+	} from '../../plugin';
+	import { collectHeadings, resolveMaxDepth } from './heading-outline';
+	import { createNavigationQueue } from './navigation-queue';
+
+	let {
+		node,
+		index,
+		myPath = [],
+		document,
+		rects,
+		maxDepth = 6
+	}: {
+		node: NodeView;
+		index: number;
+		myPath?: number[];
+		document?: DocumentView;
+		rects?: EditorRects;
+		maxDepth?: number;
+	} = $props();
+
+	let sourceEl: HTMLDivElement | undefined = $state();
+	let revealed = $state(false);
+
+	const leaf = createEditableLeaf({
+		getNode: () => node,
+		getIndex: () => index,
+		getPath: () => myPath,
+		getEl: () => sourceEl ?? null,
+		mode: 'render-primary',
+		isRevealed: () => revealed,
+		setRevealed: (value) => {
+			revealed = value;
+		}
+	});
+
+	// 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));
+
+	// 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));
+
+	// 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.
+	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.
+	function onEntryPointerDown(e: PointerEvent): void {
+		e.stopPropagation();
+	}
+
+	// ── BlockComponent interface ────────────────────────────────────────────────
+
+	export const editable = true;
+	export const focusable = true;
+
+	export const focus = leaf.focus;
+	export const parkCaret = leaf.parkCaret;
+	export const focusAtColumn = leaf.focusAtColumn;
+	export const getCursorOffset = leaf.getCursorOffset;
+	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;
+
+	void ({
+		editable,
+		focusable,
+		focus,
+		parkCaret,
+		focusAtColumn,
+		getCursorOffset,
+		getSelectedText,
+		setSelection,
+		measurePartialRects,
+		runCommand,
+		insertMarkdown
+	} satisfies BlockComponent);
+</script>
+
+{#if revealed}
+	<div
+		bind:this={sourceEl}
+		{...leaf.surfaceProps}
+		class="toc-block-source md-source-surface"
+		aria-label="TOC source"
+	></div>
+{:else}
+	<div
+		class="toc-block-render"
+		aria-label="Table of contents (click to edit)"
+		{...leaf.renderProps}
+	>
+		<nav class="toc-block-nav" aria-label="Document headings">
+			{#if headings.length === 0}
+				<span class="toc-block-empty">No headings yet</span>
+			{:else}
+				<ol>
+					{#each headings as heading (heading.id)}
+						<!-- A real `<button>`, not a role-tagged `<li>`: native focus, tab order
+						     and Enter/Space activation for free. -->
+						<li>
+							<button
+								type="button"
+								class="toc-block-item toc-block-level-{heading.level}"
+								onpointerdown={onEntryPointerDown}
+								onclick={() => navigation.navigateTo(heading.path)}
+							>
+								{heading.label}
+							</button>
+						</li>
+					{/each}
+				</ol>
+			{/if}
+		</nav>
+	</div>
+{/if}
+
+<style>
+	/* Deltas over the shared .md-source-surface (editor.css). */
+	.toc-block-source {
+		outline: none;
+		padding: 8px 12px;
+		white-space: pre;
+	}
+
+	.toc-block-render {
+		display: block;
+		padding: 4px 12px;
+		cursor: text;
+		border: 1px solid transparent;
+		border-left: 3px solid var(--color-accent, #567b67);
+		border-radius: 4px;
+	}
+
+	.toc-block-render:hover {
+		background: var(--color-bg-secondary, rgba(128, 128, 128, 0.12));
+	}
+
+	.toc-block-nav ol {
+		margin: 0;
+		padding-left: 1.4em;
+		list-style: none;
+	}
+
+	/* Native button chrome reset to a plain full-row entry: the accent hover and focus
+	   ring are the only affordances. */
+	.toc-block-item {
+		display: block;
+		width: 100%;
+		text-align: left;
+		padding: 0;
+		border: none;
+		background: none;
+		font-family: inherit;
+		font-size: 0.9em;
+		line-height: 1.6;
+		color: inherit;
+		cursor: pointer;
+		border-radius: var(--radius-ui, 3px);
+	}
+
+	.toc-block-item:hover {
+		color: var(--color-accent, #567b67);
+		text-decoration: underline;
+	}
+
+	.toc-block-item:focus-visible {
+		outline: 2px solid var(--color-accent, #567b67);
+		outline-offset: 1px;
+	}
+
+	/* A flat `<ol>` keeps list semantics; the padding is what shows the hierarchy. */
+	.toc-block-level-1 {
+		padding-left: 0;
+	}
+	.toc-block-level-2 {
+		padding-left: 1.1em;
+	}
+	.toc-block-level-3 {
+		padding-left: 2.2em;
+	}
+	.toc-block-level-4 {
+		padding-left: 3.3em;
+	}
+	.toc-block-level-5 {
+		padding-left: 4.4em;
+	}
+	.toc-block-level-6 {
+		padding-left: 5.5em;
+	}
+
+	.toc-block-empty {
+		font-size: 0.9em;
+		color: var(--color-text-muted, #aaaaaa);
+	}
+
+	/* The entry's own line box lands a pixel under the WCAG 2.5.8 minimum a thumb needs. */
+	@media (pointer: coarse) {
+		.toc-block-item {
+			min-height: 24px;
+		}
+	}
+</style>

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

@@ -0,0 +1,24 @@
+import { type DocumentView, type EditorRects, type NodeView } from '../../plugin';
+type $$ComponentProps = {
+    node: NodeView;
+    index: number;
+    myPath?: number[];
+    document?: DocumentView;
+    rects?: EditorRects;
+    maxDepth?: number;
+};
+declare const TocBlock: import("svelte").Component<$$ComponentProps, {
+    editable: true;
+    focusable: true;
+    focus: (offset: number) => void;
+    parkCaret: (offset: number) => void;
+    focusAtColumn: (x: number, from: import("../../plugin").StickyColumnDirection) => void;
+    getCursorOffset: () => number | null;
+    getSelectedText: () => string;
+    setSelection: (start: number, end: number) => void;
+    measurePartialRects: (startOffset: number, endOffset: number) => DOMRect[];
+    runCommand: (id: import("../../plugin").CommandId) => boolean;
+    insertMarkdown: (md: string) => boolean;
+}, "">;
+type TocBlock = ReturnType<typeof TocBlock>;
+export default TocBlock;

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+import { type DocumentView, 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`. */
+    path: number[];
+    level: number;
+    label: string;
+}
+/**
+ * Plain-text projection: markers drop with their wrapper, value nodes show what they
+ * 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[];

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

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+import { computeInlineContent, headingLevel } 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.
+ */
+export function projectInlineText(nodes, raw) {
+    let text = '';
+    for (const node of nodes) {
+        if (node.children)
+            text += projectInlineText(node.children, raw);
+        else if (typeof node.text === 'string')
+            text += node.text;
+        else if (typeof node.decoded === 'string')
+            text += node.decoded;
+        else if (typeof node.url === 'string')
+            text += node.url;
+        else if (node.kind === 'rawHtml')
+            continue;
+        else
+            text += raw.slice(node.start, node.end);
+    }
+    return text;
+}
+export function collectHeadings(document, maxDepth) {
+    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 ?? [], []);
+    return entries;
+}

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

@@ -0,0 +1,2 @@
+export { tocPlugin, TOC_BLOCK } from './toc-plugin';
+export type { TocOptions, MaxHeadingLevel } from './toc-plugin';

package/dist/plugins/toc/index.js

@@ -0,0 +1,2 @@
+// A `[[toc]]` leaf rendering the document's heading outline, click-to-navigate.
+export { tocPlugin, TOC_BLOCK } from './toc-plugin';

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export interface NavigationQueue {
+    navigateTo(path: number[]): Promise<void>;
+}
+export declare function createNavigationQueue(deps: {
+    navigateTo: (path: number[]) => Promise<unknown>;
+}): NavigationQueue;

package/dist/plugins/toc/navigation-queue.js

@@ -0,0 +1,21 @@
+export function createNavigationQueue(deps) {
+    let navigating = false;
+    let pendingPath = null;
+    async function navigateTo(path) {
+        pendingPath = path;
+        if (navigating)
+            return;
+        navigating = true;
+        try {
+            while (pendingPath) {
+                const target = pendingPath;
+                pendingPath = null;
+                await deps.navigateTo(target);
+            }
+        }
+        finally {
+            navigating = false;
+        }
+    }
+    return { navigateTo };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+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. */
+export interface TocOptions {
+    /** Deepest heading level listed (default 6 = every level). */
+    maxDepth?: MaxHeadingLevel;
+}
+export declare function tocPlugin(options?: TocOptions): EditorPlugin;

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

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+import { definePlugin, declarePluginKind, declaredPluginKind, registerBlockKind, registerBlockOpener, registerBlockComponent, defineBlockComponent, simpleLeafClosure, OPENER_PRIORITIES } from '../../plugin';
+import TocBlock from './TocBlock.svelte';
+import { MAX_HEADING_DEPTH } from './heading-outline';
+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.
+    registerBlockKind(toc, {
+        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.
+        gapEdges: 'both',
+        conformanceFixture: '[[toc]]\n',
+        closure: simpleLeafClosure({
+            focus: {
+                mode: 'implemented',
+                via: 'createEditableLeaf render-primary reveal (source ⇄ folded heading list)'
+            },
+            selectionPaint: {
+                mode: 'implemented',
+                via: 'measurePartialRects (raw offsets) while the source is revealed'
+            },
+            searchPaint: {
+                mode: 'implemented',
+                via: 'source raw scanned and navigable; while folded, createEditableLeaf covers the rendered block box (opaque single-unit fallback)'
+            },
+            undo: {
+                mode: 'implemented',
+                via: 'render-primary — the reveal→edit→blur cycle commits as one undo entry'
+            },
+            simOracle: { mode: 'implemented', via: 'toc document-prop e2e' }
+        })
+    });
+    registerBlockOpener(toc, {
+        // Gap placement below the only bracket-consuming built-in, so `[[toc]]` resolves here
+        // whatever that matcher claims.
+        priority: OPENER_PRIORITIES.linkReferenceDefinition - 5,
+        interruptsParagraph: (text) => text === TOC_LINE,
+        tryOpen(ctx) {
+            // Exact line only, so this process-wide opener never misfires on indented or
+            // trailing content in a sibling plugin's document.
+            if (ctx.line.text !== TOC_LINE)
+                return null;
+            return {
+                node: { kind: toc, leadingTrivia: ctx.leadingTrivia, raw: ctx.line.raw },
+                consumed: 1
+            };
+        }
+    });
+}
+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',
+        setup() {
+            registerTocBlock();
+            registerBlockComponent(declaredPluginKind(TOC_BLOCK), defineBlockComponent(TocBlock, () => ({ maxDepth })));
+        }
+    });
+}

package/dist/presentation-mode.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+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).
+ */
+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;

package/dist/presentation-mode.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+/** Keyed by the union, so a rung added to it fails `npm run check` here rather than falling
+ *  silently through {@link asPresentationMode}'s door. */
+const MODES = {
+    source: true,
+    reading: true,
+    'preview-block': true,
+    '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.
+ */
+export function asPresentationMode(value) {
+    return value != null && Object.hasOwn(MODES, value) ? value : 'source';
+}
+/** 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 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. */
+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).
+ */
+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.
+ */
+export function isReadingMode(getMode) {
+    return getMode?.() === 'reading';
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+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. */
+    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. */
+    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. */
+export declare function createBlockListState(getNode: () => NodeView): BlockListState;