@voithos-labs/aragonite 0.10.1

package/dist/core/directive/grammar.js

@@ -0,0 +1,88 @@
+/**
+ * Pure fence grammar for the `:::name` directive primitive, framework-free and CST-free.
+ * Byte round-trip is the master invariant: `serializeDirective` reproduces the opener colons,
+ * the verbatim `info` (leading separator included), the body wrap, and a matched closer exactly.
+ */
+import { escalateTerminatorRun } from '../terminator-escalation';
+const OPENER = /^(:{2,})([A-Za-z][A-Za-z0-9-]*)(.*)$/;
+export function matchDirectiveOpener(lineText) {
+    const match = OPENER.exec(lineText);
+    if (!match)
+        return null;
+    const colonCount = match[1].length;
+    return {
+        tier: colonCount === 2 ? 'leaf' : 'container',
+        colonCount,
+        name: match[2],
+        info: match[3]
+    };
+}
+const COLON = 0x3a;
+// Char-scan, not `new RegExp` per call: this runs inside the parser's per-line loop and
+// must not allocate.
+export function isDirectiveCloser(lineText, openColonCount) {
+    let count = 0;
+    while (count < lineText.length && lineText.charCodeAt(count) === COLON)
+        count++;
+    return count >= openColonCount && count === lineText.length;
+}
+/**
+ * The colon count needed to wrap `body`: one past its longest whole-line colon run, never below
+ * `minimum`. Without it a body line reproducing the terminator reads as the container's own
+ * closer and ejects everything below it on reparse.
+ */
+export function escalatedColonCount(body, minimum) {
+    // A closer line is colons end to end, so its own length IS the run.
+    return escalateTerminatorRun(body, minimum, (text, required) => isDirectiveCloser(text, required) ? text.length : null);
+}
+// ── Serialize ─────────────────────────────────────────────────────────────────
+export function serializeDirective(parts) {
+    const lineEnding = parts.lineEnding ?? '\n';
+    const inner = `${parts.innerPrefix}${parts.body}${parts.innerSuffix}`;
+    // Re-derived on every emit rather than latched into metadata, so two emits over the same
+    // state always agree (G1.13). `colonCount` is a floor, not a target.
+    const colonCount = escalatedColonCount(inner, parts.colonCount);
+    const opener = ':'.repeat(colonCount);
+    const closer = ':'.repeat(Math.max(colonCount, parts.closerColonCount ?? colonCount));
+    const closerEnd = (parts.closerNewline ?? true) ? (parts.closerLineEnding ?? lineEnding) : '';
+    return `${opener}${parts.name}${parts.info}${lineEnding}${inner}${closer}${closerEnd}`;
+}
+const LABEL = /^\s*\[([^\]]*)\]/;
+const BRACES = /\{([^}]*)\}/;
+// Quoted segments fold in, so `title="a b"` stays one token instead of splitting on its space.
+const ATTR_TOKEN = /(?:[^\s"]+|"[^"]*")+/g;
+/**
+ * Opt-in `info -> structure` reader for a leading `[label]` and a `{#id .class key=val}` block.
+ * One-way: there is no inverse serializer, and the verbatim `info` stays the round-trip truth.
+ */
+export function parseDirectiveAttributes(info) {
+    const attributes = { classes: [], properties: {} };
+    let rest = info;
+    const labelMatch = LABEL.exec(info);
+    if (labelMatch) {
+        attributes.label = labelMatch[1];
+        rest = info.slice(labelMatch[0].length);
+    }
+    const braceMatch = BRACES.exec(rest);
+    if (!braceMatch)
+        return attributes;
+    for (const token of braceMatch[1].match(ATTR_TOKEN) ?? []) {
+        if (token.startsWith('#')) {
+            attributes.id = token.slice(1);
+        }
+        else if (token.startsWith('.')) {
+            attributes.classes.push(token.slice(1));
+        }
+        else {
+            const eq = token.indexOf('=');
+            if (eq > 0) {
+                const value = token.slice(eq + 1);
+                attributes.properties[token.slice(0, eq)] = unquote(value);
+            }
+        }
+    }
+    return attributes;
+}
+function unquote(value) {
+    return value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+}

package/dist/core/directive/kinds.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generic fallback kinds for the `:::name` directive primitive, so `:::anything` stays lossless
+ * with no plugin installed. The container is `'opaque'`: its fence lives in the node's own
+ * `raw`, not in a child, making `rebuildDirectiveContainerRaw` the single reconstruction path.
+ * Imports stay core-relative because the `$lib/plugin` barrel would cycle back through core.
+ */
+import { type CstNode } from '../nodes';
+import type { ContainerBodyWrap } from '../parser';
+export declare const DIRECTIVE_CONTAINER = "directiveContainer";
+export declare const DIRECTIVE_LEAF = "directiveLeaf";
+export declare const DIRECTIVE_TEXT = "directiveText";
+/** The `:::` opener and closer bracket every directive body, whatever kind the name mints. */
+export declare const DIRECTIVE_BODY_WRAP: ContainerBodyWrap;
+/** Fence bytes a container node round-trips through `rebuildDirectiveContainerRaw`. */
+export interface DirectiveContainerMetadata {
+    name: string;
+    colonCount: number;
+    info: string;
+    closerColonCount: number;
+    closerNewline: boolean;
+    /** Authored line ending for the opener and closer chrome lines. */
+    lineEnding: string;
+}
+export declare function registerDirectiveKinds(): void;
+/**
+ * The `:` recognizer (text-recognizer.ts) stamps this kind on the span it delimits. The widget
+ * opts into `revealSource`, so focus swaps the island for editable source and blur/Enter commits
+ * (the shared reveal primitive in widget-interaction.ts). Idempotent for HMR.
+ */
+export declare function registerDirectiveTextKind(): void;
+export declare function rebuildDirectiveContainerRaw(node: CstNode): void;

package/dist/core/directive/kinds.js

@@ -0,0 +1,137 @@
+/**
+ * Generic fallback kinds for the `:::name` directive primitive, so `:::anything` stays lossless
+ * with no plugin installed. The container is `'opaque'`: its fence lives in the node's own
+ * `raw`, not in a child, making `rebuildDirectiveContainerRaw` the single reconstruction path.
+ * Imports stay core-relative because the `$lib/plugin` barrel would cycle back through core.
+ */
+import { declarePluginKind, declarePluginInlineKind, isInlineKindDeclared } from '../../schema/plugin-kind';
+import { registerBlockKind, isBlockKindRegistered } from '../../schema/block-kind-descriptor';
+import { containerClosure } from '../../schema/closure';
+import { getPluginMetadata } from '../nodes';
+import { displayLength, trimTrailingLineEnding, trailingLineEnding } from '../lines';
+import { concatChildren as serializeChildren } from '../serializer';
+import { registerInlineWidgetKind, mintWidgetShell } from '../inline/inline-widgets';
+import { matchDirectiveOpener, serializeDirective } from './grammar';
+export const DIRECTIVE_CONTAINER = 'directiveContainer';
+export const DIRECTIVE_LEAF = 'directiveLeaf';
+export const DIRECTIVE_TEXT = 'directiveText';
+/** The `:::` opener and closer bracket every directive body, whatever kind the name mints. */
+export const DIRECTIVE_BODY_WRAP = {
+    afterOpenerLine: true,
+    beforeCloserLine: true
+};
+export function registerDirectiveKinds() {
+    if (isBlockKindRegistered(DIRECTIVE_CONTAINER))
+        return; // idempotent for HMR / re-import
+    registerBlockKind(declarePluginKind(DIRECTIVE_CONTAINER), {
+        mergeRole: 'container',
+        editable: true,
+        supportsInline: false,
+        // Opaque tier rule: no textual escape hatch at either edge, so both take the gap caret.
+        gapEdges: 'both',
+        container: {
+            contract: 'opaque',
+            rebuildRaw: rebuildDirectiveContainerRaw,
+            bodyWrap: DIRECTIVE_BODY_WRAP,
+            unwrapRole: {
+                firstChildBackspace: 'lift-first-child-keep-container',
+                middleChildBackspace: 'default-merge'
+            }
+        },
+        conformanceFixture: ':::spoiler\n\nhidden\n\n:::\n',
+        closure: containerClosure({
+            roundTripVia: 'container contract=opaque — rebuildDirectiveContainerRaw',
+            focus: { mode: 'implemented', via: 'focus walks into the first body child' },
+            mergeBackspace: {
+                mode: 'implemented',
+                via: 'mergeRole=container + unwrapRole (lift-first-child-keep-container; default-merge) — Backspace at the body start lifts the first block out and the fences close over the rest'
+            },
+            undo: { mode: 'inherit-default' },
+            simOracle: { mode: 'implemented', via: 'directive e2e under the [invariant:] watcher' }
+        })
+    });
+    registerBlockKind(declarePluginKind(DIRECTIVE_LEAF), {
+        gapEdges: 'none',
+        mergeRole: 'not-mergeable',
+        editable: true,
+        supportsInline: false,
+        getContentRange: directiveLeafContentRange,
+        keymap: DIRECTIVE_LEAF_KEYMAP,
+        conformanceFixture: '::spoiler\n',
+        closure: {
+            roundTrip: { mode: 'inherit-default' },
+            focus: { mode: 'implemented', via: 'native caret in the raw-editable contenteditable' },
+            mergeBackspace: {
+                mode: 'implemented',
+                via: 'not-mergeable — Backspace moves focus (mergePrev walk), never concatenates'
+            },
+            selectionPaint: { mode: 'implemented', via: 'measurePartialRects (raw offsets)' },
+            searchPaint: {
+                mode: 'implemented',
+                via: 'content-range raw scanned (::name marker skipped); marks'
+            },
+            reorder: { mode: 'implemented', via: 'Alt+Arrow block.move keymap' },
+            undo: { mode: 'inherit-default' },
+            clipboard: { mode: 'inherit-default' },
+            simOracle: { mode: 'implemented', via: 'directive e2e under the [invariant:] watcher' }
+        }
+    });
+}
+// ── Text tier: inline `:name[label]{attrs}` ────────────────────────────────────
+/**
+ * The `:` recognizer (text-recognizer.ts) stamps this kind on the span it delimits. The widget
+ * opts into `revealSource`, so focus swaps the island for editable source and blur/Enter commits
+ * (the shared reveal primitive in widget-interaction.ts). Idempotent for HMR.
+ */
+export function registerDirectiveTextKind() {
+    if (isInlineKindDeclared(DIRECTIVE_TEXT))
+        return;
+    const kind = declarePluginInlineKind(DIRECTIVE_TEXT);
+    registerInlineWidgetKind(kind, {
+        isWidget: () => true,
+        buildWidget: buildDirectiveTextWidget,
+        editing: { revealSource: true }
+    });
+}
+/** Renders the verbatim `:name[...]` source dimmed inside the shared widget shell. */
+function buildDirectiveTextWidget(node, raw) {
+    const shell = mintWidgetShell('directive-text-widget', node);
+    shell.textContent = raw.slice(node.start, node.end);
+    return shell;
+}
+// Enter opens a paragraph sibling: a leaf never holds an in-line break, so the split reparses
+// its empty tail. Backspace/Delete take the not-mergeable walk, moving focus without joining.
+const DIRECTIVE_LEAF_KEYMAP = [
+    { chord: 'Enter', command: 'block.split' },
+    { chord: 'Tab', command: 'block.insertTab' },
+    { chord: 'Backspace', command: 'block.mergePrev' },
+    { chord: 'Delete', command: 'block.mergeNext' },
+    { chord: 'Alt+ArrowUp', command: 'block.moveUp' },
+    { chord: 'Alt+ArrowDown', command: 'block.moveDown' }
+];
+// The `::name` fence is a dimmed marker prefix, on the heading marker-range mechanism. A raw
+// that no longer opens a fence reparses to a paragraph first, so the null branch is a floor.
+function directiveLeafContentRange(node) {
+    const fence = matchDirectiveOpener(trimTrailingLineEnding(node.raw));
+    const start = fence ? fence.colonCount + fence.name.length : 0;
+    return { start, end: displayLength(node.raw) };
+}
+export function rebuildDirectiveContainerRaw(node) {
+    const meta = getPluginMetadata(node);
+    if (!meta)
+        return;
+    node.raw = serializeDirective({
+        colonCount: meta.colonCount,
+        name: meta.name,
+        info: meta.info,
+        innerPrefix: node.innerPrefix ?? '',
+        body: serializeChildren(node.children ?? []),
+        innerSuffix: node.innerSuffix ?? '',
+        closerColonCount: meta.closerColonCount,
+        closerNewline: meta.closerNewline,
+        lineEnding: meta.lineEnding,
+        // The parse side threads only the opener ending, so a mixed-ending directive recovers
+        // the closer's from the current raw, whose last line it is.
+        closerLineEnding: trailingLineEnding(node.raw)
+    });
+}

package/dist/core/directive/registry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Name-to-kind registry for the directive primitive: the shared opener resolves a fence's
+ * `(tier, name)` here, then delegates to `fromDirective` or builds a lossless generic node.
+ * Register-once with no unregister, the `customElements` model the schema registries follow.
+ * Tier scopes the key, so a container and a leaf may share a name.
+ */
+import type { DirectiveTier, DirectiveFence } from './grammar';
+import type { AnyBlockKind, PluginInlineKind, CstNode, InlineNode, Document } from '../nodes';
+export interface ParsedDirective {
+    fence: DirectiveFence;
+    body?: Document;
+    /** Passed through so a factory node serializes intact. */
+    leadingTrivia: string;
+    /** The exact consumed slice (opener + body + closer); a factory sets `node.raw` to this. */
+    raw: string;
+    closerColonCount: number;
+    closerNewline: boolean;
+    /** Opener line ending; a factory stores it so a rebuild reproduces CRLF chrome lines. */
+    lineEnding: string;
+}
+export interface DirectiveDefinition {
+    kind: AnyBlockKind | PluginInlineKind;
+    /** Omit to let the opener build a generic lossless node. */
+    fromDirective?(parsed: ParsedDirective): CstNode | InlineNode;
+}
+export declare function registerDirective(tier: DirectiveTier, name: string, def: DirectiveDefinition): void;
+export declare function resolveDirective(tier: DirectiveTier, name: string): DirectiveDefinition | undefined;
+/**
+ * Pre-narrowed: the registration contract above guarantees a block node for these tiers, so the
+ * union narrowing lives at this choke point instead of a cast per opener call site.
+ */
+export declare function resolveBlockDirectiveFactory(tier: 'leaf' | 'container', name: string): ((parsed: ParsedDirective) => CstNode) | undefined;
+export declare function isDirectiveRegistered(tier: DirectiveTier, name: string): boolean;
+/**
+ * What "does this kind have a recognizer" must ask: a directive kind owns no opener of its own,
+ * so an opener-registry probe alone reads the whole directive tier as unrecognizable.
+ */
+export declare function isDirectiveKind(kind: AnyBlockKind | PluginInlineKind): boolean;
+export declare function __resetDirectiveRegistryForTests(): void;

package/dist/core/directive/registry.js

@@ -0,0 +1,49 @@
+/**
+ * Name-to-kind registry for the directive primitive: the shared opener resolves a fence's
+ * `(tier, name)` here, then delegates to `fromDirective` or builds a lossless generic node.
+ * Register-once with no unregister, the `customElements` model the schema registries follow.
+ * Tier scopes the key, so a container and a leaf may share a name.
+ */
+import { registerOnce } from '../../schema/register-once';
+const definitions = new Map();
+const keyOf = (tier, name) => `${tier}:${name}`;
+export function registerDirective(tier, name, def) {
+    // Fail loud at registration so a tier/factory mismatch can't silently no-op at dispatch.
+    if (tier === 'container' && !def.fromDirective) {
+        throw new Error(`registerDirective: container "${name}" requires a fromDirective factory ` +
+            `(a kind-only container would orphan the generic rebuild path).`);
+    }
+    if (tier === 'text' && def.fromDirective) {
+        throw new Error(`registerDirective: text "${name}" is kind-only; fromDirective is not used for inline nodes.`);
+    }
+    const key = keyOf(tier, name);
+    registerOnce(definitions.has(key), () => definitions.set(key, def), `registerDirective: "${key}" is already registered. Directives are register-once.`);
+}
+export function resolveDirective(tier, name) {
+    return definitions.get(keyOf(tier, name));
+}
+/**
+ * Pre-narrowed: the registration contract above guarantees a block node for these tiers, so the
+ * union narrowing lives at this choke point instead of a cast per opener call site.
+ */
+export function resolveBlockDirectiveFactory(tier, name) {
+    const factory = definitions.get(keyOf(tier, name))?.fromDirective;
+    return factory;
+}
+export function isDirectiveRegistered(tier, name) {
+    return definitions.has(keyOf(tier, name));
+}
+/**
+ * What "does this kind have a recognizer" must ask: a directive kind owns no opener of its own,
+ * so an opener-registry probe alone reads the whole directive tier as unrecognizable.
+ */
+export function isDirectiveKind(kind) {
+    for (const def of definitions.values()) {
+        if (def.kind === kind)
+            return true;
+    }
+    return false;
+}
+export function __resetDirectiveRegistryForTests() {
+    definitions.clear();
+}

package/dist/core/directive/text-recognizer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Inline text-directive recognizer for `:name[label]{attrs}`. It OWNS the whole span: returning
+ * `end` past the `[label]{attrs}` keeps the scanner's bracket stack from competing for the inner
+ * `[label]`. Conservative by construction, declining unless `[` or `{` follows the name, so
+ * `:smile:`, `10:30`, and `://` stay literal. Meaning is parsed elsewhere (`grammar.ts`).
+ */
+import type { InlineNode, PluginInlineKind } from '../nodes';
+export declare function recognizeTextDirective(raw: string, pos: number, end: number, kind: PluginInlineKind): InlineNode | null;

package/dist/core/directive/text-recognizer.js

@@ -0,0 +1,87 @@
+/**
+ * Inline text-directive recognizer for `:name[label]{attrs}`. It OWNS the whole span: returning
+ * `end` past the `[label]{attrs}` keeps the scanner's bracket stack from competing for the inner
+ * `[label]`. Conservative by construction, declining unless `[` or `{` follows the name, so
+ * `:smile:`, `10:30`, and `://` stay literal. Meaning is parsed elsewhere (`grammar.ts`).
+ */
+import { createBoundedMemo } from '../../bounded-memo';
+import { resolveDirective } from './registry';
+const isNameStart = (code) => (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a); // A-Z a-z
+const isNameChar = (code) => isNameStart(code) || (code >= 0x30 && code <= 0x39) || code === 0x2d; // + 0-9 -
+/**
+ * Balanced-run matches for one block's raw. Without the memo, a paragraph carrying many `:name[`
+ * starts pays a full block scan each. Matching is prefix-determined, so one stack pass answers
+ * every consultation and the caller's `end` filters the result. Bounded rather than weak-keyed
+ * because a string cannot key a WeakMap; two entries cover a block's own scan.
+ */
+const balancedRuns = createBoundedMemo({ cap: 2 });
+function matchBalancedRuns(raw) {
+    const label = new Map();
+    const attrs = new Map();
+    const labelOpens = [];
+    const attrsOpens = [];
+    for (let i = 0; i < raw.length; i++) {
+        switch (raw[i]) {
+            case '[':
+                labelOpens.push(i);
+                break;
+            case ']': {
+                const open = labelOpens.pop();
+                if (open !== undefined)
+                    label.set(open, i + 1);
+                break;
+            }
+            case '{':
+                attrsOpens.push(i);
+                break;
+            case '}': {
+                const open = attrsOpens.pop();
+                if (open !== undefined)
+                    attrs.set(open, i + 1);
+                break;
+            }
+        }
+    }
+    return { label, attrs };
+}
+/** -1 when the run reaches `end` unbalanced. Nesting counts by depth, so `[a[b]c]` is one run. */
+function consumeBalanced(raw, open, end, openCh) {
+    const runs = balancedRuns(raw, () => matchBalancedRuns(raw));
+    const close = (openCh === '[' ? runs.label : runs.attrs).get(open);
+    return close !== undefined && close <= end ? close : -1;
+}
+export function recognizeTextDirective(raw, pos, end, kind) {
+    // `://` is a scheme separator (http://, mailto:), never a directive.
+    if (raw[pos + 1] === '/' && raw[pos + 2] === '/')
+        return null;
+    let i = pos + 1;
+    if (i >= end || !isNameStart(raw.charCodeAt(i)))
+        return null;
+    i++;
+    while (i < end && isNameChar(raw.charCodeAt(i)))
+        i++;
+    const nameEnd = i;
+    // The conservative gate: a bare `:name` stays literal unless `[` or `{` follows immediately.
+    if (i >= end)
+        return null;
+    const gate = raw[i];
+    if (gate !== '[' && gate !== '{')
+        return null;
+    if (gate === '[') {
+        const labelEnd = consumeBalanced(raw, i, end, '[');
+        if (labelEnd < 0)
+            return null;
+        i = labelEnd;
+    }
+    // Mandatory under the `{` gate, optional after a label: the same run either way.
+    if (i < end && raw[i] === '{') {
+        const attrsEnd = consumeBalanced(raw, i, end, '{');
+        if (attrsEnd < 0)
+            return null;
+        i = attrsEnd;
+    }
+    // Sibling-path parity with the block opener: a registered name resolves to the plugin's own
+    // inline kind, an unregistered one keeps the generic `kind`.
+    const def = resolveDirective('text', raw.slice(pos + 1, nameEnd));
+    return { kind: (def?.kind ?? kind), start: pos, end: i };
+}

package/dist/core/escapable.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CommonMark's 32 escapable ASCII punctuation characters (§2.4). A core leaf because both the
+ * inline scanner and the block-level link-reference parser (§4.7) need it, and neither should
+ * import the other's directory to reach a lexical constant.
+ */
+export declare const ESCAPABLE_PUNCTUATION: Set<string>;

package/dist/core/escapable.js

@@ -0,0 +1,6 @@
+/**
+ * CommonMark's 32 escapable ASCII punctuation characters (§2.4). A core leaf because both the
+ * inline scanner and the block-level link-reference parser (§4.7) need it, and neither should
+ * import the other's directory to reach a lexical constant.
+ */
+export const ESCAPABLE_PUNCTUATION = new Set('!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~');

package/dist/core/inline/backticks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Backtick-run indexing for code spans (CommonMark §6.1): a run of N backticks closes with the
+ * next run of exactly N. Indexed once, then binary-searched per opener, because a per-opener
+ * forward rescan to EOF turns a run-length ladder quadratic.
+ */
+/**
+ * Wrap `content` as a code span. The fence runs one backtick past the longest run it encloses, so
+ * nothing inside can close it; content touching a backtick at either edge takes a space pad too,
+ * without which the fence and that byte merge into one longer run and the span closes elsewhere.
+ */
+export declare function wrapAsCodeSpan(content: string): string;
+/** Run start positions by run length, ascending within each length. */
+export type BacktickRunIndex = Map<number, number[]>;
+export declare function indexBacktickRuns(raw: string, from: number, end: number): BacktickRunIndex;
+/** First run of exactly `tickLen` starting after `openerStart`, or -1 when nothing closes it. */
+export declare function findBacktickCloser(index: BacktickRunIndex, tickLen: number, openerStart: number): number;

package/dist/core/inline/backticks.js

@@ -0,0 +1,62 @@
+/**
+ * Backtick-run indexing for code spans (CommonMark §6.1): a run of N backticks closes with the
+ * next run of exactly N. Indexed once, then binary-searched per opener, because a per-opener
+ * forward rescan to EOF turns a run-length ladder quadratic.
+ */
+/**
+ * Wrap `content` as a code span. The fence runs one backtick past the longest run it encloses, so
+ * nothing inside can close it; content touching a backtick at either edge takes a space pad too,
+ * without which the fence and that byte merge into one longer run and the span closes elsewhere.
+ */
+export function wrapAsCodeSpan(content) {
+    const fence = '`'.repeat(longestBacktickRun(content) + 1);
+    const pad = content.startsWith('`') || content.endsWith('`') ? ' ' : '';
+    return fence + pad + content + pad + fence;
+}
+function longestBacktickRun(text) {
+    let longest = 0;
+    let run = 0;
+    for (const char of text) {
+        run = char === '`' ? run + 1 : 0;
+        if (run > longest)
+            longest = run;
+    }
+    return longest;
+}
+export function indexBacktickRuns(raw, from, end) {
+    const runs = new Map();
+    let i = from;
+    while (i < end) {
+        if (raw[i] !== '`') {
+            i++;
+            continue;
+        }
+        const start = i;
+        do {
+            i++;
+        } while (i < end && raw[i] === '`');
+        const len = i - start;
+        const positions = runs.get(len);
+        if (positions)
+            positions.push(start);
+        else
+            runs.set(len, [start]);
+    }
+    return runs;
+}
+/** First run of exactly `tickLen` starting after `openerStart`, or -1 when nothing closes it. */
+export function findBacktickCloser(index, tickLen, openerStart) {
+    const positions = index.get(tickLen);
+    if (!positions)
+        return -1;
+    let lo = 0;
+    let hi = positions.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (positions[mid] <= openerStart)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo < positions.length ? positions[lo] : -1;
+}

package/dist/core/inline/character-refs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CommonMark §2.5 entity and numeric character references: named (`©`), decimal, hex.
+ * Per spec, zero, out-of-range, and surrogate code points decode to U+FFFD.
+ */
+import type { InlineNode } from '../nodes';
+/** Match one character reference; `pos` must point at an `&`. */
+export declare function matchCharacterReference(raw: string, pos: number, end: number): InlineNode | null;

package/dist/core/inline/character-refs.js

@@ -0,0 +1,70 @@
+/**
+ * CommonMark §2.5 entity and numeric character references: named (`©`), decimal, hex.
+ * Per spec, zero, out-of-range, and surrogate code points decode to U+FFFD.
+ */
+import { HTML5_NAMED_ENTITIES } from './html-entities';
+const REPLACEMENT = '�';
+// The longest body that can decode (`CounterClockwiseContourIntegral`). Capping the `;` search
+// keeps `&`-floods linear, where an unbounded indexOf rescans the region per candidate.
+const MAX_REFERENCE_BODY = 31;
+/** Match one character reference; `pos` must point at an `&`. */
+export function matchCharacterReference(raw, pos, end) {
+    const searchEnd = Math.min(end, pos + MAX_REFERENCE_BODY + 2);
+    let semi = -1;
+    for (let i = pos + 1; i < searchEnd; i++) {
+        if (raw[i] === ';') {
+            semi = i;
+            break;
+        }
+    }
+    if (semi === -1)
+        return null;
+    const body = raw.slice(pos + 1, semi);
+    if (body.length === 0)
+        return null;
+    let decoded;
+    if (body[0] === '#') {
+        decoded = decodeNumeric(body);
+    }
+    else {
+        decoded = Object.hasOwn(HTML5_NAMED_ENTITIES, body) ? HTML5_NAMED_ENTITIES[body] : null;
+    }
+    if (decoded === null)
+        return null;
+    return {
+        kind: 'entityReference',
+        start: pos,
+        end: semi + 1,
+        decoded
+    };
+}
+function decodeNumeric(body) {
+    if (body.length < 2)
+        return null;
+    const isHex = body[1] === 'x' || body[1] === 'X';
+    const digits = body.slice(isHex ? 2 : 1);
+    if (digits.length === 0)
+        return null;
+    if (isHex) {
+        if (digits.length > 6)
+            return null;
+        if (!/^[0-9A-Fa-f]+$/.test(digits))
+            return null;
+    }
+    else {
+        if (digits.length > 7)
+            return null;
+        if (!/^[0-9]+$/.test(digits))
+            return null;
+    }
+    const codePoint = parseInt(digits, isHex ? 16 : 10);
+    if (codePoint === 0)
+        return REPLACEMENT;
+    if (codePoint > 0x10ffff)
+        return REPLACEMENT;
+    if (codePoint >= 0xd800 && codePoint <= 0xdfff)
+        return REPLACEMENT;
+    // The C1 range decodes verbatim, no cp1252 remap: a divergence from an HTML5 reference here
+    // is deliberate, following CommonMark §2.5's letter.
+    return String.fromCodePoint(codePoint);
+}

package/dist/core/inline/destination-bytes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The scan's inverse for the two fields every bracketed construct hides: a destination and a
+ * title. One home so the image and link write seams cannot drift apart on what needs escaping —
+ * the sibling-path shape that put an unencoded space in one seam and not the other.
+ */
+export declare function encodeDestination(url: string): string;
+export declare function escapeTitle(title: string): string;

package/dist/core/inline/destination-bytes.js

@@ -0,0 +1,14 @@
+/**
+ * The scan's inverse for the two fields every bracketed construct hides: a destination and a
+ * title. One home so the image and link write seams cannot drift apart on what needs escaping —
+ * the sibling-path shape that put an unencoded space in one seam and not the other.
+ */
+// Bare destinations end at whitespace/`"`/`'` and carry parens only in balanced pairs
+// (CommonMark §6.3); a trailing backslash would escape the closer instead. Idempotent: an
+// encoded URL has no literal stop-char left.
+export function encodeDestination(url) {
+    return url.replace(/[ \t\r\n()"'\\]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0'));
+}
+export function escapeTitle(title) {
+    return title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}

package/dist/core/inline/entity-widget.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Visibility gate and DOM builder for the decoded-entity inline widget. A character reference
+ * renders as an atomic widget showing its decoded glyph, but only when that glyph is visible:
+ * an entity decoding to nothing drawable (` `, `​`) keeps its literal
+ * source span, because an invisible atomic island is a caret trap.
+ */
+import type { InlineNode } from '../nodes';
+/** True when the decoded value draws at least one glyph, so it earns a widget. */
+export declare function entityRendersGlyph(decoded: string | undefined): boolean;
+/** Source bytes ride the shell's `data-source-*`, so the raw-aware walk reads back `©`. */
+export declare function buildEntityWidget(node: InlineNode): HTMLSpanElement;