@voithos-labs/aragonite 0.10.1

package/dist/perf/instruments.d.ts

@@ -0,0 +1,49 @@
+import type { DocumentView } from '../core/node-views';
+export interface PerfSnapshot {
+    snapshotCount: number;
+    snapshotCloneBytes: number;
+    rebuildDepths: Record<number, number>;
+    /** Container reparses the kind re-derivation gate let through (see rebuildUnsharedChain). */
+    containerKindReparses: number;
+    parseCount: number;
+    parseMsTotal: number;
+    parseBlockCount: number;
+    inlineComputeCount: number;
+    /** Inline-format coverage reads that actually parsed — the pressed-state read's cost. */
+    formatCoverageReads: number;
+    undoLiveBytes: number;
+    undoEntryCount: number;
+    blockRenderCount: number;
+    blockRenderMsTotal: number;
+    keystrokeInPageMs: number[];
+    blockRenderPaths: string[];
+    mountedBlockCount: number;
+    decorationRuns: number;
+    islandRebuilds: number;
+    islandKeyScans: number;
+}
+export declare function enablePerfInstruments(): void;
+export declare function disablePerfInstruments(): void;
+export declare function resetPerfInstruments(): void;
+export declare function perfEnabled(): boolean;
+export declare function perfSnapshot(): PerfSnapshot;
+export declare function recordSnapshotClone(bytes: number): void;
+export declare function recordRebuildDepth(depth: number): void;
+export declare function recordContainerKindReparse(): void;
+export declare function recordParse(ms: number, blockCount: number): void;
+export declare function recordInlineCompute(): void;
+export declare function recordFormatCoverageRead(): void;
+export declare function setUndoGauge(liveBytes: number, entryCount: number): void;
+export declare function recordBlockRender(ms: number, path?: number[]): void;
+export declare function recordDecorationRun(): void;
+export declare function recordIslandRebuild(): void;
+export declare function recordIslandKeyScan(): void;
+export declare function incMountedBlocks(): void;
+export declare function decMountedBlocks(): void;
+export declare function markKeystrokeStart(): void;
+export declare function markKeystrokeSettle(): void;
+/**
+ * Serialized-byte proxy without building the string. Counts UTF-16 code units: exact
+ * against `serialize().length`, approximate against on-disk bytes for non-ASCII.
+ */
+export declare function docByteLength(doc: DocumentView): number;

package/dist/perf/instruments.js

@@ -0,0 +1,154 @@
+/**
+ * Dev-mode performance counters for the profiling harness. A leaf module, so the seams that
+ * record into it can depend on it from anywhere. Recording stays off until a runtime switch
+ * that only arms in dev/Vitest, leaving production one boolean check per record call.
+ * Internal — never exported from the editor barrel.
+ */
+import { DEV } from 'esm-env';
+let enabled = false;
+let counters = emptySnapshot();
+let keystrokeStart = null;
+function emptySnapshot() {
+    return {
+        snapshotCount: 0,
+        snapshotCloneBytes: 0,
+        rebuildDepths: {},
+        containerKindReparses: 0,
+        parseCount: 0,
+        parseMsTotal: 0,
+        parseBlockCount: 0,
+        inlineComputeCount: 0,
+        formatCoverageReads: 0,
+        undoLiveBytes: 0,
+        undoEntryCount: 0,
+        blockRenderCount: 0,
+        blockRenderMsTotal: 0,
+        keystrokeInPageMs: [],
+        blockRenderPaths: [],
+        mountedBlockCount: 0,
+        decorationRuns: 0,
+        islandRebuilds: 0,
+        islandKeyScans: 0
+    };
+}
+// ── Switch and readout ──────────────────────────────────────────────────────
+export function enablePerfInstruments() {
+    if (DEV || (typeof process !== 'undefined' && process?.env?.VITEST)) {
+        enabled = true;
+    }
+}
+export function disablePerfInstruments() {
+    enabled = false;
+}
+export function resetPerfInstruments() {
+    counters = emptySnapshot();
+    keystrokeStart = null;
+}
+export function perfEnabled() {
+    return enabled;
+}
+export function perfSnapshot() {
+    return {
+        ...counters,
+        rebuildDepths: { ...counters.rebuildDepths },
+        keystrokeInPageMs: [...counters.keystrokeInPageMs],
+        blockRenderPaths: [...counters.blockRenderPaths]
+    };
+}
+// ── Recorders ───────────────────────────────────────────────────────────────
+export function recordSnapshotClone(bytes) {
+    if (!enabled)
+        return;
+    counters.snapshotCount++;
+    counters.snapshotCloneBytes += bytes;
+}
+export function recordRebuildDepth(depth) {
+    if (!enabled)
+        return;
+    counters.rebuildDepths[depth] = (counters.rebuildDepths[depth] ?? 0) + 1;
+}
+export function recordContainerKindReparse() {
+    if (!enabled)
+        return;
+    counters.containerKindReparses++;
+}
+export function recordParse(ms, blockCount) {
+    if (!enabled)
+        return;
+    counters.parseCount++;
+    counters.parseMsTotal += ms;
+    counters.parseBlockCount += blockCount;
+}
+export function recordInlineCompute() {
+    if (!enabled)
+        return;
+    counters.inlineComputeCount++;
+}
+export function recordFormatCoverageRead() {
+    if (!enabled)
+        return;
+    counters.formatCoverageReads++;
+}
+export function setUndoGauge(liveBytes, entryCount) {
+    if (!enabled)
+        return;
+    counters.undoLiveBytes = liveBytes;
+    counters.undoEntryCount = entryCount;
+}
+export function recordBlockRender(ms, path) {
+    if (!enabled)
+        return;
+    counters.blockRenderCount++;
+    counters.blockRenderMsTotal += ms;
+    if (path)
+        counters.blockRenderPaths.push(path.join(','));
+}
+// notifyEdit runs every source, so a typing pass records keystrokes × sources — the
+// ceiling that catches a per-block cascade.
+export function recordDecorationRun() {
+    if (!enabled)
+        return;
+    counters.decorationRuns++;
+}
+export function recordIslandRebuild() {
+    if (!enabled)
+        return;
+    counters.islandRebuilds++;
+}
+// One querySelectorAll per destructive/printable keystroke, even when the block holds none.
+export function recordIslandKeyScan() {
+    if (!enabled)
+        return;
+    counters.islandKeyScans++;
+}
+export function incMountedBlocks() {
+    if (!enabled)
+        return;
+    counters.mountedBlockCount++;
+}
+export function decMountedBlocks() {
+    if (!enabled)
+        return;
+    counters.mountedBlockCount--;
+}
+export function markKeystrokeStart() {
+    if (!enabled)
+        return;
+    keystrokeStart = performance.now();
+}
+export function markKeystrokeSettle() {
+    if (!enabled || keystrokeStart === null)
+        return;
+    counters.keystrokeInPageMs.push(performance.now() - keystrokeStart);
+    keystrokeStart = null;
+}
+/**
+ * Serialized-byte proxy without building the string. Counts UTF-16 code units: exact
+ * against `serialize().length`, approximate against on-disk bytes for non-ASCII.
+ */
+export function docByteLength(doc) {
+    let length = doc.prefix.length + doc.suffix.length;
+    for (const child of doc.children)
+        length += child.leadingTrivia.length + child.raw.length;
+    return length;
+}

package/dist/perf/use-mount-gauge.svelte.d.ts

@@ -0,0 +1 @@
+export declare function useMountGauge(): void;

package/dist/perf/use-mount-gauge.svelte.js

@@ -0,0 +1,15 @@
+/**
+ * Count the calling component in the dev mount gauge. Rows and list items aren't
+ * BlockHosts, so without this a windowed giant container would read as ~0 mounted blocks.
+ */
+import { perfEnabled, incMountedBlocks, decMountedBlocks } from './instruments';
+export function useMountGauge() {
+    $effect(() => {
+        // One decision per mount: the gauge is a net balance, so re-reading the flag at
+        // teardown would let an arm/disarm flip unbalance it.
+        if (!perfEnabled())
+            return;
+        incMountedBlocks();
+        return decMountedBlocks;
+    });
+}

package/dist/plugin.d.ts

@@ -0,0 +1,102 @@
+import type { AnyBlockKind, InlineNode } from './core/nodes';
+import type { NodeView } from './core/node-views';
+import type { ChromeLeafOptions } from './editor-actions/plugin/chrome-leaf';
+export { definePlugin, isPluginInstalled } from './schema/plugin-install';
+export type { EditorPlugin, EditorPluginEntry } from './schema/plugin-install';
+export type { PluginSetupContext, OnEditorCallback, EditorContext } from './schema/plugin-install';
+export type { PresentationMode } from './presentation-mode';
+export { definePluginBlock } from './schema/define-plugin-block';
+export { declarePluginKind, declaredPluginKind } from './schema/plugin-kind';
+export type { PluginBlockKind, AnyBlockKind } from './core/nodes';
+export { declarePluginInlineKind, declaredPluginInlineKind, isInlineKindDeclared } from './schema/plugin-kind';
+export type { PluginInlineKind, InlineNode, ImageFields, ImageSyntaxRewriter } from './core/nodes';
+export { registerInlineSyntax, INLINE_PRIORITIES } from './core/inline/scan/plugin-syntax';
+export type { InlineSyntaxRecognizer, InlineSyntaxOptions } from './core/inline/scan/plugin-syntax';
+export { registerInlineWidgetKind, mintWidgetShell, isWidgetActivationClick } from './core/inline/inline-widgets';
+export type { InlineWidgetDescriptor, InlineWidgetComponentProps, InlineWidgetEditingPolicy, InlineWidgetEditingContext } from './core/inline/inline-widgets';
+export { registerBlockKind, augmentBlockKind } from './schema/block-kind-descriptor';
+export type { BlockKindDescriptor, BlockKindRegistration, BlockKindAugmentation, ContainerDescriptorGroup, MergeRole, UnwrapRole } from './schema/block-kind-descriptor';
+export type { ChildRawChange } from './schema/child-spans';
+export type { ClosureBlock, ClosureColumn, ClosureCell, SimpleLeafClosureCells, ContainerClosureCells } from './schema/closure';
+export { simpleLeafClosure, containerClosure } from './schema/closure';
+export { registerBlockComponent, defineBlockComponent } from './schema/block-component-registry';
+export type { BlockComponentEntry } from './schema/block-component-registry';
+export type { BlockComponent, BlockComponentExports, BlockComponentProps } from './block-component';
+export { registerBlockOpener } from './schema/block-openers';
+export type { BlockOpener, BlockOpenerResult, OpenContext } from './schema/block-openers';
+export { lineStartsOuterBlock } from './schema/block-openers';
+export type { OuterBlockScan } from './schema/block-openers';
+export { OPENER_PRIORITIES } from './schema/opener-priorities';
+export { registerBlockCompleter } from './schema/block-completions';
+export type { BlockCompleter, CompletionResult } from './schema/block-completions';
+export type { CommandId } from './schema/commands';
+export type { KeyBinding } from './schema/keybindings';
+export { registerBlockCommand } from './schema/block-commands';
+export type { BlockCommandContext, BlockCommandHandler } from './schema/block-commands';
+export type { PluginCommandId, AnyCommandId } from './schema/command-id';
+export { registerGlobalCommand } from './schema/global-commands';
+export { parse, type ParseScope } from './core/parser';
+export type { Document } from './core/nodes';
+export { serialize, concatChildren as serializeChildren } from './core/serializer';
+export { trimTrailingLineEnding, normalizeLineEndings } from './core/lines';
+export { splitLines } from './core/lines';
+export type { ParsedLine } from './core/lines';
+export { isBlankLine } from './core/parser';
+export { parseContainerBody } from './core/parser';
+export type { ContainerBodyWrap } from './core/parser';
+export { matchFenceOpen, matchFenceClose, escalatedFenceLength } from './core/parsers/fence-syntax';
+export type { FenceOpen } from './core/parsers/fence-syntax';
+export { htmlBlockTagLineMatcher } from './core/parsers/html-block';
+export { blockquoteExtent } from './core/parsers/blockquote';
+export type { CstNode } from './core/nodes';
+export type { NodeView, DocumentView } from './core/node-views';
+export { setPluginMetadata, getPluginMetadata } from './core/nodes';
+export { getContentRange } from './core/inline';
+export type { ContentRange } from './core/inline';
+export { headingLevel } from './core/nodes';
+export { isProseKind } from './core/inline';
+/**
+ * Inline-parse a prose leaf. No link-reference resolver is available to a plugin, so
+ * reference links parse as `unresolvedReference`; every other construct fully resolves.
+ */
+export declare function computeInlineContent(node: NodeView): InlineNode[];
+export { isBlockKindDeclared } from './schema/plugin-kind';
+export { isBlockKindRegistered } from './schema/block-kind-descriptor';
+export { isBlockComponentRegistered } from './schema/block-component-registry';
+export { isBlockOpenerRegistered } from './schema/block-openers';
+export { isBlockCompleterRegistered } from './schema/block-completions';
+export { isPasteTransformRegistered } from './tree-operations/paste/paste-transforms';
+export { default as BlockList } from './components/BlockList.svelte';
+export { createContainerBlock } from './editor-actions/plugin/container';
+export type { ContainerBlock, ContainerBlockComponent, ContainerBlockDeps, ContainerBlockListProps } from './editor-actions/plugin/container';
+export type { RefSlots } from './reactivity/publish-ref.svelte';
+export declare function registerChromeLeaf(kind: AnyBlockKind, opts?: ChromeLeafOptions): void;
+export type { ChromeLeafOptions };
+export { chromeChild } from './editor-actions/plugin/chrome-leaf';
+export { isCollapsedContainer } from './schema/reserved-chrome';
+export { createEditableLeaf } from './components/blocks/editable-leaf';
+export type { EditableLeaf, EditableLeafDeps, EditableLeafMode, EditableLeafSurfaceProps, EditableLeafRenderProps } from './components/blocks/editable-leaf';
+export type { StickyColumnDirection } from './block-component';
+export { activateDirectives } from './components/blocks/directive/activate-directives';
+export { registerDirective, isDirectiveRegistered } from './core/directive/registry';
+export type { DirectiveDefinition, ParsedDirective } from './core/directive/registry';
+export { escalatedColonCount, parseDirectiveAttributes, serializeDirective } from './core/directive/grammar';
+export type { DirectiveTier, DirectiveFence, DirectiveAttributes } from './core/directive/grammar';
+export { createDirectiveRebuild } from './editor-actions/plugin/directive-container';
+export { DIRECTIVE_BODY_WRAP } from './core/directive/kinds';
+export { createBoundedMemo } from './bounded-memo';
+export type { BoundedMemoOptions } from './bounded-memo';
+export { createScanIndex } from './scan-index';
+export { registerPasteTransform } from './tree-operations/paste/paste-transforms';
+export type { PasteTransform } from './tree-operations/paste/paste-transforms';
+export type { Decoration, MarkDecoration, WidgetDecoration, ReplaceDecoration, BlockDecoration, DecorationWidgetSpec, ProvideContext, DecorationSource, DecorationSourceHandle, DecorationRegistry } from './decorations/types';
+export type { EditEvent, EditorEventMap, SelectionChangeEvent, EditorError } from './editor-events';
+export type { OperationKind } from './schema/operations';
+export type { EditorRects } from './editor-rects';
+export { caretOffsetAtPoint } from './cursor/point-offset';
+export type { CaretTarget } from './schema/block-kind-descriptor';
+export { CURSOR_END } from './block-component';
+export type { CursorEnd } from './block-component';
+export type { EditorSelection, SelectionPoint } from './selection/primitives';
+export { SELECTION_END } from './block-component';
+export type { SelectionEnd } from './block-component';

package/dist/plugin.js

@@ -0,0 +1,156 @@
+// The plugin-authoring surface, published at the `@voithos-labs/aragonite/plugin` subpath. Only the
+// authoring API belongs here — not the `<Editor>` embedding barrel (index.ts), no test
+// helpers, no internal dispatch. Sections tagged (pre-freeze) may change until the 1.0
+// freeze.
+import TextEditableBlock from './components/blocks/text/TextEditableBlock.svelte';
+import { registerChromeLeaf as bindChromeLeaf } from './editor-actions/plugin/chrome-leaf';
+import { computeInlineContent as parseLeafInline } from './core/inline';
+// ── Plugin unit (pre-freeze) ─────────────────────────────────────────────────
+// Installation is once per process — the editor's `plugins` prop does it, so a
+// consumer rarely calls installPlugins directly.
+export { definePlugin, isPluginInstalled } from './schema/plugin-install';
+// The single-block shortcut: one kind, one component, one register step.
+export { definePluginBlock } from './schema/define-plugin-block';
+// ── Kind declaration ─────────────────────────────────────────────────────────
+export { declarePluginKind, declaredPluginKind } from './schema/plugin-kind';
+// ── Inline authoring surface (pre-freeze) ────────────────────────────────────
+// Mint an inline kind, hook the scanner on a trigger character, register a live atomic widget.
+export { declarePluginInlineKind, declaredPluginInlineKind, isInlineKindDeclared } from './schema/plugin-kind';
+export { registerInlineSyntax, INLINE_PRIORITIES } from './core/inline/scan/plugin-syntax';
+export { registerInlineWidgetKind, mintWidgetShell, isWidgetActivationClick } from './core/inline/inline-widgets';
+// ── Block-kind descriptor registry ───────────────────────────────────────────
+// BlockKindRegistration is the write-side shape; BlockKindDescriptor is the flat
+// read-side one, still exported as the referent of ContainerDescriptorGroup's fields.
+export { registerBlockKind, augmentBlockKind } from './schema/block-kind-descriptor';
+export { simpleLeafClosure, containerClosure } from './schema/closure';
+// ── Component registry ───────────────────────────────────────────────────────
+export { registerBlockComponent, defineBlockComponent } from './schema/block-component-registry';
+// ── Parser-opener registry ───────────────────────────────────────────────────
+export { registerBlockOpener } from './schema/block-openers';
+// The shared "does this line start a block at the outer level" gate, so a container opener
+// scanning its own extent ends it where cmark-gfm does instead of forking the rule.
+export { lineStartsOuterBlock } from './schema/block-openers';
+// The built-in priority ladder a plugin opener prices against (pre-freeze) — see the
+// plugin guide's opener-priority section for the two placement rules.
+export { OPENER_PRIORITIES } from './schema/opener-priorities';
+// ── Enter-completion registry (pre-freeze) ───────────────────────────────────
+// The opener's sibling for a grammar whose lines must be adjacent, which Enter alone can
+// never type into existence: a completer reads one typed line and answers the lines that
+// complete it, plus where the caret seats inside the mint.
+export { registerBlockCompleter } from './schema/block-completions';
+// ── Command mint (pre-freeze) ────────────────────────────────────────────────
+// A (kind, name) block-command mints a PluginCommandId; AnyCommandId spans built-in and minted.
+export { registerBlockCommand } from './schema/block-commands';
+// A global command is process-wide but runs against the dispatching instance's EditorContext.
+export { registerGlobalCommand } from './schema/global-commands';
+// ── Parse / serialize helpers (pre-freeze) ───────────────────────────────────
+// Re-exported so an opener needn't reach into core/ deep paths the packaged artifact
+// doesn't expose.
+export { parse } from './core/parser';
+export { serialize, concatChildren as serializeChildren } from './core/serializer';
+export { trimTrailingLineEnding, normalizeLineEndings } from './core/lines';
+// The `ParsedLine[]` every line-scoped seam here consumes — without it a `source →
+// source` transform holding nothing but a string could not reach `blockquoteExtent`.
+export { splitLines } from './core/lines';
+// GFM §2.1's blank line (spaces and tabs only). `String.trim()` would admit the whole
+// Unicode whitespace set and split a block on a pasted non-breaking space.
+export { isBlankLine } from './core/parser';
+// A container whose body sits between chrome lines of its own (`:::note` … `:::`,
+// `<summary>` … `</details>`) parses that body here, not with `parse`: the blank line
+// against a chrome line is a separator, and only this seam knows to keep it out of the
+// children. See `design/syntax-tree.md` § blank lines.
+export { parseContainerBody } from './core/parser';
+// ── Fence grammar (pre-freeze) ───────────────────────────────────────────────
+// The built-in CommonMark fence recognizers, so a plugin claiming a fence (```mermaid) never
+// reimplements the rules. The opener match keeps verbatim indent/info bytes, for byte-exact
+// rebuilds; `escalatedFenceLength` is `escalatedColonCount`'s fence twin, owed by any kind that
+// rebuilds its own raw around a body it did not parse.
+export { matchFenceOpen, matchFenceClose, escalatedFenceLength } from './core/parsers/fence-syntax';
+// ── HTML tag-line grammar (pre-freeze) ───────────────────────────────────────
+// CommonMark's type-6 tag-line shape for one tag name. What actually closes such a
+// container is everything the spec passes through raw (indented, upper-cased, trailing
+// space) — looser than any canonical form a rebuild emits.
+export { htmlBlockTagLineMatcher } from './core/parsers/html-block';
+// ── Blockquote grammar (pre-freeze) ──────────────────────────────────────────
+// The built-in blockquote extent scanner, so a plugin claiming a blockquote-shaped
+// construct (`> [!NOTE]`) reuses CommonMark §5.1 lazy continuation instead of forking it.
+export { blockquoteExtent } from './core/parsers/blockquote';
+// Store/read a plugin kind's own metadata shape without casting through `BlockMetadata`.
+export { setPluginMetadata, getPluginMetadata } from './core/nodes';
+// The content span within a block's raw, syntax markers excluded (a heading's `#` prefix).
+export { getContentRange } from './core/inline';
+// A heading's level (ATX or setext), null otherwise: the typed path past the
+// built-in-node narrowing this barrel keeps internal.
+export { headingLevel } from './core/nodes';
+// Pure and uncached — the reactive-safe path a widget's `$derived` reads. `isProseKind`
+// gates the walk so a code block's bytes are never inline-scanned.
+export { isProseKind } from './core/inline';
+/**
+ * Inline-parse a prose leaf. No link-reference resolver is available to a plugin, so
+ * reference links parse as `unresolvedReference`; every other construct fully resolves.
+ */
+export function computeInlineContent(node) {
+    return parseLeafInline(node);
+}
+// ── Idempotent-registration probes ─────────────────────────────────────────────
+// The register-once registries throw on duplicate; a plugin re-registers safely
+// (HMR / re-import) by guarding on these.
+export { isBlockKindDeclared } from './schema/plugin-kind';
+export { isBlockKindRegistered } from './schema/block-kind-descriptor';
+export { isBlockComponentRegistered } from './schema/block-component-registry';
+export { isBlockOpenerRegistered } from './schema/block-openers';
+export { isBlockCompleterRegistered } from './schema/block-completions';
+export { isPasteTransformRegistered } from './tree-operations/paste/paste-transforms';
+// ── Container-authoring surface (pre-freeze) ─────────────────────────────────
+// Lets a plugin build an editable nested container as thinly as the built-in
+// blockquote, without touching any editor context key.
+export { default as BlockList } from './components/BlockList.svelte';
+export { createContainerBlock } from './editor-actions/plugin/container';
+// The one seam allowed to import components/, so editor-actions keeps no upward
+// value edge to the component tree.
+export function registerChromeLeaf(kind, opts) {
+    bindChromeLeaf(kind, TextEditableBlock, opts);
+}
+// Mint the reserved child-0 node for a container's chrome leaf: text plus its newline.
+export { chromeChild } from './editor-actions/plugin/chrome-leaf';
+// One definition of collapsed, shared by a component's getter and the model-layer walks.
+export { isCollapsedContainer } from './schema/reserved-chrome';
+// ── Editable-leaf authoring surface (pre-freeze) ─────────────────────────────
+// A text-editing leaf with native caret/IME/undo/selection parity, plain (per-keystroke
+// commits) or render-primary (reveal-to-edit, one commit on blur). The
+// createContainerBlock sibling for leaves.
+export { createEditableLeaf } from './components/blocks/editable-leaf';
+// ── Directive authoring (pre-freeze) ─────────────────────────────────────────
+// `activateDirectives()` claims `:::` — call it once at startup, before the editor
+// parses. The other symbols are inert: importing them does NOT claim the grammar.
+export { activateDirectives } from './components/blocks/directive/activate-directives';
+export { registerDirective, isDirectiveRegistered } from './core/directive/registry';
+// `escalatedColonCount` is the rule `serializeDirective` already applies; exported for
+// emitters that build `:::name` text by concatenation instead of through the CST, where
+// a body line reproducing the fence would otherwise close the container early.
+export { escalatedColonCount, parseDirectiveAttributes, serializeDirective } from './core/directive/grammar';
+// The `rebuildRaw` for a directive container whose child 0 is an editable title.
+export { createDirectiveRebuild } from './editor-actions/plugin/directive-container';
+// The wrap every `:::` body parses with; a directive kind declares it as its `container.bodyWrap`
+// so the editor's separator settle knows the blank line against the fence belongs to the fence.
+export { DIRECTIVE_BODY_WRAP } from './core/directive/kinds';
+// ── Renderer utilities (pre-freeze) ──────────────────────────────────────────
+// A bounded LRU memo for a renderer's per-source work, sync or async (store the
+// promise). See the plugin guide's renderer recipe.
+export { createBoundedMemo } from './bounded-memo';
+// ── Recognizer scan index (pre-freeze) ───────────────────────────────────────
+// The bounded decline for a grammar with no early-stop byte (the guide's inline-kinds
+// section): a per-block position collector becomes a memoized lookup answering the first
+// candidate at or after `from` (-1 when none), one scan per block behind a cap-2 memo.
+export { createScanIndex } from './scan-index';
+// ── Paste transforms (pre-freeze) ────────────────────────────────────────────
+// A pre-parse clipboard rewrite: inspect the raw pasted text, replace it or decline
+// (null). Transforms run in install order at every paste site — never on load or typing.
+export { registerPasteTransform } from './tree-operations/paste/paste-transforms';
+// ── Caret geometry (pre-freeze) ──────────────────────────────────────────────
+// The kit a kind answers `caretTargetAtPoint` with: the landing shape, the probe that turns a
+// point in one of your own elements into an offset (NEAREST, so a press on your chrome still
+// names one), and the sentinel for "wherever this leaf ends".
+export { caretOffsetAtPoint } from './cursor/point-offset';
+export { CURSOR_END } from './block-component';
+export { SELECTION_END } from './block-component';

package/dist/plugins/admonitions/AdmonitionBlock.svelte

@@ -0,0 +1,144 @@
+<!--
+  One alert box for both admonition kinds: the directive admonition (editable title
+  chrome leaf at child 0) and the GitHub alert (no title, a static badge instead).
+  createContainerBlock hides all child-list state, so this owns only its chrome;
+  node/index/path go in as thunks so each is re-read live, never snapshotted.
+-->
+<script lang="ts">
+	import { BlockList, createContainerBlock, getPluginMetadata, type NodeView } from '../../plugin';
+	import {
+		capitalize,
+		coerceAdmonitionName,
+		GITHUB_ALERT,
+		type AdmonitionMetadata,
+		type GithubAlertMetadata
+	} from './kinds';
+
+	let { node, index, myPath = [] }: { node: NodeView; index: number; myPath?: number[] } = $props();
+	let boxEl: HTMLElement | undefined = $state();
+
+	const { blockListProps, containerApi, handleKeydown } = createContainerBlock({
+		getNode: () => node,
+		getIndex: () => index,
+		getPath: () => myPath,
+		getBoxEl: () => boxEl
+	});
+
+	const isAlert = $derived(node.kind === GITHUB_ALERT);
+	const kind = $derived(
+		isAlert
+			? coerceAdmonitionName(getPluginMetadata<GithubAlertMetadata>(node)?.alertType?.toLowerCase())
+			: coerceAdmonitionName(getPluginMetadata<AdmonitionMetadata>(node)?.name)
+	);
+	const titleEmpty = $derived(isAlert || (node.children?.[0]?.raw ?? '').trim() === '');
+
+	export { containerApi };
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+	class="admonition"
+	data-kind={kind}
+	data-title-empty={titleEmpty}
+	data-alert-source={isAlert ? 'github' : 'directive'}
+	aria-label={`${capitalize(kind)} ${isAlert ? 'alert' : 'admonition'}`}
+	bind:this={boxEl}
+	onkeydown={handleKeydown}
+>
+	{#if isAlert}
+		<!-- Static badge: contenteditable=false keeps the caret in the body, where the
+		     alert's real content lives. -->
+		<div class="admonition-title" contenteditable="false" aria-hidden="true"></div>
+	{/if}
+	<BlockList {...blockListProps} />
+</div>
+
+<style>
+	/* A gutter rail, not a card: a document, not a boxed callout. */
+	.admonition {
+		position: relative;
+		margin: 0.8em 0;
+		padding: 0.15em 0 0.15em 1em;
+		border-left: 3px solid var(--adm-accent);
+	}
+
+	/* One block per kind carries the whole axis: accent, icon glyph, untitled label. Fixed hex,
+	   not theme tokens: GitHub's alert palette is canonically one color per kind, so admonitions
+	   read identically across host themes. */
+	.admonition[data-kind='note'] {
+		--adm-accent: #1f6feb;
+		--adm-label: 'Note';
+		--adm-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1a7 7 0 1 0 0 14A7 7 0 0 0 8 1zm.9 3.3a.9.9 0 1 1-1.8 0 .9.9 0 0 1 1.8 0zM7.1 7h1.8v5.2H7.1z'/%3E%3C/svg%3E");
+	}
+	.admonition[data-kind='tip'] {
+		--adm-accent: #2da44e;
+		--adm-label: 'Tip';
+		--adm-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1a4.5 4.5 0 0 0-2.7 8.1c.4.3.7.8.7 1.3v.6h4v-.6c0-.5.3-1 .7-1.3A4.5 4.5 0 0 0 8 1zM6 12.5h4v.8H6zm.5 1.7h3l-.6.6a1 1 0 0 1-.7.3h-.4a1 1 0 0 1-.7-.3z'/%3E%3C/svg%3E");
+	}
+	.admonition[data-kind='important'] {
+		--adm-accent: #8250df;
+		--adm-label: 'Important';
+		--adm-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M2.5 2h11a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H6l-3 2.6V11H2.5a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1zM7.1 4.2h1.8v3.6H7.1zm0 4.4h1.8v1.6H7.1z'/%3E%3C/svg%3E");
+	}
+	.admonition[data-kind='warning'] {
+		--adm-accent: #d29922;
+		--adm-label: 'Warning';
+		--adm-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1.3 15 14H1zM7.1 6h1.8v4H7.1zm0 5h1.8v1.6H7.1z'/%3E%3C/svg%3E");
+	}
+	.admonition[data-kind='caution'] {
+		--adm-accent: #e5534b;
+		--adm-label: 'Caution';
+		--adm-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M5 1.3h6l4 4v6l-4 4H5l-4-4V5.3zM7.1 4h1.8v5H7.1zm0 6h1.8v1.6H7.1z'/%3E%3C/svg%3E");
+	}
+
+	/* Positioned so the icon and untitled-name pseudo-elements anchor to the row. */
+	.admonition :global(.admonition-title) {
+		position: relative;
+		font-weight: 600;
+		color: var(--adm-accent);
+		padding-left: 1.7em;
+		min-height: 1.4em;
+		line-height: 1.4em;
+	}
+
+	/* The alert badge is static chrome, never a caret target. */
+	.admonition[data-alert-source='github'] :global(.admonition-title) {
+		user-select: none;
+		cursor: default;
+	}
+
+	/* Masked, not colored, so one glyph recolors per kind. */
+	.admonition :global(.admonition-title)::before {
+		content: '';
+		position: absolute;
+		left: 0;
+		top: 2px;
+		width: 1.1em;
+		height: 1.4em;
+		background-color: var(--adm-accent);
+		-webkit-mask: var(--adm-icon) center / 1.1em no-repeat;
+		mask: var(--adm-icon) center / 1.1em no-repeat;
+		pointer-events: none;
+		user-select: none;
+	}
+
+	/* The empty title leaf holds a lone <br>, which pre-wrap paints as a trailing empty
+	   line; capping to one row keeps the title-to-body gap equal to the titled variants. */
+	.admonition[data-title-empty='true'] :global(.admonition-title) {
+		height: 1.4em;
+	}
+
+	/* Absolute, not inline: the empty leaf's <br> would wrap generated content onto a
+	   second row and break titled/untitled geometry parity. */
+	.admonition[data-title-empty='true'] :global(.admonition-title)::after {
+		content: var(--adm-label);
+		position: absolute;
+		left: 1.7em;
+		top: 2px;
+		opacity: 0.72;
+		font-weight: 600;
+		line-height: 1.4em;
+		pointer-events: none;
+		user-select: none;
+	}
+</style>

package/dist/plugins/admonitions/AdmonitionBlock.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type NodeView } from '../../plugin';
+type $$ComponentProps = {
+    node: NodeView;
+    index: number;
+    myPath?: number[];
+};
+declare const AdmonitionBlock: import("svelte").Component<$$ComponentProps, {
+    containerApi: import("../../plugin").ContainerBlockComponent;
+}, "">;
+type AdmonitionBlock = ReturnType<typeof AdmonitionBlock>;
+export default AdmonitionBlock;

package/dist/plugins/admonitions/admonition-kind.d.ts

@@ -0,0 +1,8 @@
+export interface AdmonitionsOptions {
+    /**
+     * Rewrite pasted GitHub-alert blockquotes to `:::name` source before the parse
+     * (default false). Off, they stay GitHub bytes and render as `githubAlert`.
+     */
+    convertAlertsOnPaste?: boolean;
+}
+export declare function registerAdmonitions(options?: AdmonitionsOptions): void;