@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/core/inline/image-dimensions.js

@@ -1,11 +1,13 @@
-// `|N` / `|NxM` is an Obsidian extension, not part of GFM. The `@X,Y[,Z]` tail on the `NxM`
-// form is this editor's own: the pan and zoom of the image inside that frame.
+// The size hint at the end of an image's alt text, read and written here. `|N` / `|NxM` is an
+// Obsidian extension, not part of GFM; the `@X,Y[,Z]` tail on the `NxM` form is this editor's
+// own: the pan and zoom of the image inside that frame.
 const MAX_DIMENSION = 10000;
 export const MAX_CROP_ZOOM = 4;
 // The longest decodable suffix, `|10000x10000@100,100,4.00`. Bounding the pipe search to that
 // tail keeps nested-label floods linear.
 const MAX_SUFFIX_SEARCH = 26;
 const NO_HINT = { width: undefined, height: undefined, crop: undefined };
+// ── Reading ─────────────────────────────────────────────────────────────────
 export function parseImageDimensions(alt) {
     const lastPipe = boundedLastPipe(alt);
     const dims = lastPipe === -1 ? null : parseDimensionSuffix(alt.slice(lastPipe + 1));
@@ -76,3 +78,18 @@ function parseStrictInt(s) {
         return null;
     return n;
 }
+// ── Writing ─────────────────────────────────────────────────────────────────
+/** The suffix `parseImageDimensions` reads back as these values; empty for no width. */
+export function buildDimSuffix(width, height, crop) {
+    if (width === undefined)
+        return '';
+    if (height === undefined)
+        return `|${width}`;
+    return `|${width}x${height}${crop ? buildCropTail(crop) : ''}`;
+}
+/** The pan in whole percents, then the zoom to two decimals, left out at 1. */
+function buildCropTail(crop) {
+    const z = Math.round(crop.z * 100) / 100;
+    const zoom = z === 1 ? '' : `,${String(z)}`;
+    return `@${Math.round(crop.x)},${Math.round(crop.y)}${zoom}`;
+}

package/dist/core/inline/image-source-bytes.d.ts

@@ -0,0 +1,11 @@
+import type { ImageFields, InlineNode } from '../nodes';
+/** Bytes to splice over `image`'s range, or null when the edit is refused. A node a plugin's
+ *  syntax owns is written by its `rewriteImage` hook (`docs/design/plugin-contract.md`). */
+export declare function buildImageEditBytes(image: InlineNode, blockRaw: string, fields: ImageFields): string | null;
+/** Only the optional keys the node holds, so a rebuild adds no field the source lacked and
+ *  repeated resizes leave the alt text unchanged. */
+export declare function imageFieldsFromInline(image: InlineNode): ImageFields;
+export declare function sameImageFields(a: ImageFields, b: ImageFields): boolean;
+/** The inverse of the built-in grammar; call `buildImageEditBytes`, which decides whether the
+ *  bytes are GFM's to write. */
+export declare function buildImageSourceBytes(fields: ImageFields): string;

package/dist/core/inline/image-source-bytes.js

@@ -0,0 +1,71 @@
+// Where an image edit becomes bytes: the one function every image write goes through, and
+// below it the GFM serializer, which nothing else may call.
+import { encodeDestination, escapeTitle } from './destination-bytes';
+import { buildDimSuffix } from './image-dimensions';
+import { devWarn } from '../../dev-warn';
+// ── Where the bytes are written ─────────────────────────────────────────────
+/** Bytes to splice over `image`'s range, or null when the edit is refused. A node a plugin's
+ *  syntax owns is written by its `rewriteImage` hook (`docs/design/plugin-contract.md`). */
+export function buildImageEditBytes(image, blockRaw, fields) {
+    const claim = image.syntaxClaim;
+    if (!claim)
+        return buildImageSourceBytes(fields);
+    const bytes = claim.rewriteImage?.(blockRaw.slice(image.start, image.end), fields) ?? null;
+    if (bytes === null) {
+        devWarn('image-edit', `declined: the "${claim.prefix}" inline syntax handler owns these bytes and ` +
+            `${claim.rewriteImage ? 'its rewriteImage hook cannot represent this edit' : 'registered no rewriteImage hook'}`, fields);
+    }
+    return bytes;
+}
+/** Only the optional keys the node holds, so a rebuild adds no field the source lacked and
+ *  repeated resizes leave the alt text unchanged. */
+export function imageFieldsFromInline(image) {
+    return {
+        alt: image.alt ?? '',
+        url: image.url ?? '',
+        ...(image.title !== undefined ? { title: image.title } : {}),
+        ...(image.width !== undefined ? { width: image.width } : {}),
+        ...(image.height !== undefined ? { height: image.height } : {}),
+        ...(image.crop !== undefined ? { crop: image.crop } : {}),
+        ...(image.label !== undefined ? { label: image.label } : {})
+    };
+}
+export function sameImageFields(a, b) {
+    return (a.alt === b.alt &&
+        a.url === b.url &&
+        a.title === b.title &&
+        a.width === b.width &&
+        a.height === b.height &&
+        a.label === b.label &&
+        a.crop?.x === b.crop?.x &&
+        a.crop?.y === b.crop?.y &&
+        a.crop?.z === b.crop?.z);
+}
+// ── The GFM serializer ──────────────────────────────────────────────────────
+/** The inverse of the built-in grammar; call `buildImageEditBytes`, which decides whether the
+ *  bytes are GFM's to write. */
+export function buildImageSourceBytes(fields) {
+    const dimSuffix = buildDimSuffix(fields.width, fields.height, fields.crop);
+    const altSegment = escapeAlt(fields.alt) + dimSuffix;
+    // A reference image's url and title belong to its link reference definition.
+    if (fields.label !== undefined) {
+        return `![${altSegment}][${fields.label}]`;
+    }
+    const titleSegment = fields.title !== undefined ? ` "${escapeTitle(fields.title)}"` : '';
+    return `![${altSegment}](${encodeDestination(fields.url)}${titleSegment})`;
+}
+// Alt text keeps the label's bytes as written: a bare bracket is escaped so it can't end the
+// label, and an existing backslash pair passes through so repeated commits never double it.
+function escapeAlt(alt) {
+    let out = '';
+    for (let i = 0; i < alt.length; i++) {
+        const ch = alt[i];
+        if (ch === '\\' && i + 1 < alt.length) {
+            out += ch + alt[i + 1];
+            i++;
+            continue;
+        }
+        out += ch === '[' || ch === ']' || ch === '\\' ? '\\' + ch : ch;
+    }
+    return out;
+}

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

@@ -2,41 +2,48 @@
 import type { AnyInlineKind, CstNode, InlineNode } from '../nodes';
 import type { NodeView } from '../node-views';
 import type { LinkReferenceResolver } from './link-reference-resolver';
+import type { Reading } from '../../schema/reading';
+import { type GrammarView } from '../../schema/block-openers';
 import { inlineDescendants } from './walk';
 export interface ContentRange {
     start: number;
     end: number;
 }
 declare const contentLengthBrand: unique symbol;
-/** Raw-space length of a block's rendered content, mintable only from its content range: a
- *  DOM-measured length answers in walk space and lags the pass that is rewriting the DOM. */
+/** Raw-offset length of a block's rendered content, built only from its content range: a
+ *  DOM-measured length counts as the DOM traversal does and lags the pass rewriting the DOM. */
 export type ContentLength = number & {
     readonly [contentLengthBrand]: true;
 };
 /** Content range within a prose block's raw; marker-bearing kinds override via descriptor. */
 export declare function getContentRange(node: NodeView): ContentRange;
-/** The one {@link ContentLength} mint. */
+/** The structure between a block's content and its line ending, like a setext underline: drawn
+ *  as a marker after the text, and kept by every edit that keeps the block's head. */
+export declare function structuralSuffix(node: NodeView): string;
+/** The structural suffix's part on the text's own line, an ATX closing run: a line break made
+ *  at the text's end goes after it. A setext underline starts on a line of its own. */
+export declare function sameLineSuffix(node: NodeView): string;
+/** {@link sameLineSuffix} over a prose block's raw and its content end. */
+export declare function sameLineSuffixOf(raw: string, contentEnd: number): string;
+/** The one place a {@link ContentLength} is created. */
 export declare function contentLengthOf(node: NodeView): ContentLength;
 export declare function isProseKind(kind: CstNode['kind']): boolean;
-/**
- * The bytes an INLINE construct's delimiters do not cover, or null for a kind that has none — a
- * bare text run, an escape, a pair emptied of content. The inline twin of {@link getContentRange},
- * here rather than beside one of its callers because the caret bounds, the typing seat, the
- * destructive arm and the toggles all need the same answer.
- */
+/** The inline counterpart of {@link getContentRange}: the bytes a construct's delimiters do not
+ *  cover, or null for one with no content (a text run, an escape, an emptied pair). */
 export declare function constructContentRange(node: InlineNode): ContentRange | null;
-/**
- * A prose node's inline tree, pure: no caching, no reactive reads. The render path calls this
- * directly; the caching accessor (inline-cache.ts) calls it on a miss.
- */
-export declare function computeInlineContent(node: NodeView, resolver?: LinkReferenceResolver): InlineNode[];
-/**
- * Parse inline content over raw[start, end). Node offsets are absolute into raw, and every byte
- * lands in exactly one node's range. Both bounds are checked, not just typed: a caller the
- * compiler cannot reach that passes only the source would otherwise get one whole-string text
- * node, which is wrong output that looks like a result.
- */
-export declare function parseInline(raw: string, start: number, end: number, resolver?: LinkReferenceResolver): InlineNode[];
+/** Uncached and free of reactive reads, so the render path can call it directly. An editor
+ *  passes its own grammar, so a plugin it left out takes no bytes. */
+export declare function computeInlineContent(node: NodeView, resolver: LinkReferenceResolver | undefined, grammar: GrammarView): InlineNode[];
+type InlineReader = (node: NodeView) => InlineNode[];
+/** The inline parse a plugin gets: this editor's grammar and the document's definitions as they
+ *  stand at each call. A new function per definitions change, so a cache keyed on it refreshes. */
+export declare function inlineReaderFor(reading: Reading): InlineReader;
+/** Node offsets are absolute into raw, and each byte of raw[start, end) lands in exactly one node.
+ *  With no grammar it reads every installed plugin's syntax; the editor uses {@link readInline}. */
+export declare function parseInline(raw: string, start: number, end: number, resolver?: LinkReferenceResolver, grammar?: GrammarView): InlineNode[];
+/** Both bounds are checked at runtime: a caller outside the type checker that passes only the
+ *  source would get one whole-string text node, wrong output that looks like a result. */
+export declare function readInline(raw: string, start: number, end: number, resolver: LinkReferenceResolver | undefined, grammar: GrammarView): InlineNode[];
 export { inlineDescendants };
 /** Every construct kind anywhere in a parse, at any depth. */
 export declare function constructKinds(nodes: readonly InlineNode[]): Set<AnyInlineKind>;

package/dist/core/inline/index.js

@@ -1,10 +1,12 @@
 /** Inline parser entry. See docs/design/inline-parsing.md. */
-import { displayLength } from '../lines';
+import { displayLength, firstDisplayLine } from '../lines';
 import { getBlockKindDescriptor } from '../../schema/block-kind-descriptor';
-// Registered before any descriptor read, headless of the editor mount. Explicit call: a bare
-// side-effect import is tree-shaken from the production build.
+// The built-in descriptors register before any read, with or without a mounted editor; the call
+// is explicit because a bare side-effect import is tree-shaken from the production build.
 import { registerBuiltInDescriptors } from '../../schema/built-in-descriptors';
+import { defaultGrammarView } from '../../schema/block-openers';
 import { scanInline } from './scan';
+import { codeSpanFence } from './scan/code-spans';
 import { inlineDescendants } from './walk';
 import { recordInlineCompute } from '../../perf/instruments';
 registerBuiltInDescriptors();
@@ -15,55 +17,75 @@ export function getContentRange(node) {
         return d.getContentRange(node);
     return { start: 0, end: displayLength(node.raw) };
 }
-/** The one {@link ContentLength} mint. */
+/** The structure between a block's content and its line ending, like a setext underline: drawn
+ *  as a marker after the text, and kept by every edit that keeps the block's head. */
+export function structuralSuffix(node) {
+    // A kind that is not prose shows its whole display as content.
+    if (!isProseKind(node.kind))
+        return '';
+    return node.raw.slice(getContentRange(node).end, displayLength(node.raw));
+}
+/** The structural suffix's part on the text's own line, an ATX closing run: a line break made
+ *  at the text's end goes after it. A setext underline starts on a line of its own. */
+export function sameLineSuffix(node) {
+    if (!isProseKind(node.kind))
+        return '';
+    return sameLineSuffixOf(node.raw, getContentRange(node).end);
+}
+/** {@link sameLineSuffix} over a prose block's raw and its content end. */
+export function sameLineSuffixOf(raw, contentEnd) {
+    return firstDisplayLine(raw.slice(contentEnd, displayLength(raw))).text;
+}
+/** The one place a {@link ContentLength} is created. */
 export function contentLengthOf(node) {
     return getContentRange(node).end;
 }
 export function isProseKind(kind) {
     return getBlockKindDescriptor(kind).supportsInline;
 }
-/**
- * The bytes an INLINE construct's delimiters do not cover, or null for a kind that has none — a
- * bare text run, an escape, a pair emptied of content. The inline twin of {@link getContentRange},
- * here rather than beside one of its callers because the caret bounds, the typing seat, the
- * destructive arm and the toggles all need the same answer.
- */
+/** The inline counterpart of {@link getContentRange}: the bytes a construct's delimiters do not
+ *  cover, or null for one with no content (a text run, an escape, an emptied pair). */
 export function constructContentRange(node) {
     const children = node.children;
     if (children && children.length > 0) {
         return { start: children[0].start, end: children[children.length - 1].end };
     }
-    // A code span carries its content as `text` rather than children, and a matched span's two
-    // backtick runs are equal, so what the content does not cover splits evenly between them.
-    if (node.kind === 'inlineCode' && node.text !== undefined) {
-        const fence = (node.end - node.start - node.text.length) / 2;
-        if (Number.isInteger(fence) && fence > 0) {
-            return { start: node.start + fence, end: node.end - fence };
-        }
-    }
-    return null;
+    // A code span carries its content as `text` rather than children.
+    const fence = node.kind === 'inlineCode' ? codeSpanFence(node) : 0;
+    return fence > 0 ? { start: node.start + fence, end: node.end - fence } : null;
 }
-/**
- * A prose node's inline tree, pure: no caching, no reactive reads. The render path calls this
- * directly; the caching accessor (inline-cache.ts) calls it on a miss.
- */
-export function computeInlineContent(node, resolver) {
+/** Uncached and free of reactive reads, so the render path can call it directly. An editor
+ *  passes its own grammar, so a plugin it left out takes no bytes. */
+export function computeInlineContent(node, resolver, grammar) {
     recordInlineCompute();
     const range = getContentRange(node);
-    return parseInline(node.raw, range.start, range.end, resolver);
+    return readInline(node.raw, range.start, range.end, resolver, grammar);
+}
+const readersByReading = new WeakMap();
+/** The inline parse a plugin gets: this editor's grammar and the document's definitions as they
+ *  stand at each call. A new function per definitions change, so a cache keyed on it refreshes. */
+export function inlineReaderFor(reading) {
+    const epoch = reading.resolverEpoch;
+    const held = readersByReading.get(reading);
+    if (held?.epoch === epoch)
+        return held.read;
+    const read = (node) => computeInlineContent(node, reading.resolver, reading.grammar);
+    readersByReading.set(reading, { epoch, read });
+    return read;
 }
 // ── Inline Parser ──────────────────────────────────────────────────────────
-/**
- * Parse inline content over raw[start, end). Node offsets are absolute into raw, and every byte
- * lands in exactly one node's range. Both bounds are checked, not just typed: a caller the
- * compiler cannot reach that passes only the source would otherwise get one whole-string text
- * node, which is wrong output that looks like a result.
- */
-export function parseInline(raw, start, end, resolver) {
+/** Node offsets are absolute into raw, and each byte of raw[start, end) lands in exactly one node.
+ *  With no grammar it reads every installed plugin's syntax; the editor uses {@link readInline}. */
+export function parseInline(raw, start, end, resolver, grammar) {
+    return readInline(raw, start, end, resolver, grammar ?? defaultGrammarView);
+}
+/** Both bounds are checked at runtime: a caller outside the type checker that passes only the
+ *  source would get one whole-string text node, wrong output that looks like a result. */
+export function readInline(raw, start, end, resolver, grammar) {
     if (!Number.isFinite(start) || !Number.isFinite(end)) {
-        throw new TypeError('parseInline requires both scan bounds — to scan a whole string, call parseInline(src, 0, src.length)');
+        throw new TypeError('parseInline requires both scan bounds: to scan a whole string, call parseInline(src, 0, src.length)');
     }
-    return scanInline(raw, start, end, resolver);
+    return scanInline(raw, start, end, resolver, grammar);
 }
 // ── Inline Tree Walks ──────────────────────────────────────────────────────
 export { inlineDescendants };

package/dist/core/inline/inline-cache.d.ts

@@ -1,20 +1,17 @@
 /**
- * Lazy `inlineContent` accessor for non-render consumers, over a node-keyed WeakMap.
- * Non-reactive by design: never call from the render path (which uses computeInlineContent),
- * since a reactive read+write here re-introduces the keyed-`{#each}` corruption G4.2 guards.
- * One sub-entry per signature space, so resolver-less and signature-bearing callers cannot
- * evict each other on a bracket-bearing block.
+ * Lazy `inlineContent` accessor for code outside the render path, over a node-keyed WeakMap.
+ * Never call it from the render path, which computes from `node.raw` with `computeInlineContent` so a
+ * render effect reads nothing else (G4.2). Resolver-less and resolving callers get
+ * separate slots so they never evict each other, and a slot answers only its own grammar.
  */
 import type { InlineNode } from '../nodes';
 import type { NodeView } from '../node-views';
 import type { LinkReferenceResolver } from './link-reference-resolver';
-export declare function getInlineContent(node: NodeView, resolver?: LinkReferenceResolver, signature?: string): InlineNode[];
-/**
- * The one spelling of `getInlineContent(node, ref.current, ref.signature)`, so a non-render
- * call site cannot drop the signature and silently desync from what render drew. `linkRef`
- * stays structural: naming editor-keys' type would cycle that module back onto this layer.
- */
-export declare function resolvedInlineContent(node: NodeView, linkRef?: {
-    current?: LinkReferenceResolver;
-    signature?: string;
-}): InlineNode[];
+import type { GrammarView } from '../../schema/block-openers';
+import type { Reading } from '../../schema/reading';
+export declare function getInlineContent(node: NodeView, resolver: LinkReferenceResolver | undefined, signature: string | undefined, grammar: GrammarView): InlineNode[];
+/** The parts of an editor's reading its inline parse needs. */
+export type InlineReading = Pick<Reading, 'grammar' | 'resolver' | 'resolverSignature'>;
+/** Takes the whole reading, so a call site outside the render path cannot drop the signature or
+ *  the grammar and disagree with what the render path drew. */
+export declare function resolvedInlineContent(node: NodeView, reading: InlineReading): InlineNode[];

package/dist/core/inline/inline-cache.js

@@ -1,28 +1,25 @@
 import { computeInlineContent, isProseKind } from './index';
 const cache = new WeakMap();
-export function getInlineContent(node, resolver, signature = '') {
+export function getInlineContent(node, resolver, signature = '', grammar) {
     if (!isProseKind(node.kind))
         return [];
-    // A block resolves through an LRD only if it holds a bracket; mirroring the render gate keeps
-    // a bracketless block off both the resolver and the signature.
+    // A block resolves a link reference definition only if it holds a bracket; the render path
+    // checks the same, so a bracketless block skips both the resolver and the signature.
     const hasRef = node.raw.includes('[');
     const sig = hasRef ? signature : '';
     const effectiveResolver = hasRef ? resolver : undefined;
     const entry = cache.get(node);
     const slot = sig === '' ? 'plain' : 'resolved';
     const hit = entry?.[slot];
-    if (hit && hit.raw === node.raw && hit.signature === sig)
+    if (hit && hit.raw === node.raw && hit.signature === sig && hit.grammar === grammar) {
         return hit.content;
-    const content = computeInlineContent(node, effectiveResolver);
-    // Spread, so refilling one slot carries the other one through untouched.
-    cache.set(node, { ...entry, [slot]: { raw: node.raw, signature: sig, content } });
+    }
+    const content = computeInlineContent(node, effectiveResolver, grammar);
+    cache.set(node, { ...entry, [slot]: { raw: node.raw, signature: sig, grammar, content } });
     return content;
 }
-/**
- * The one spelling of `getInlineContent(node, ref.current, ref.signature)`, so a non-render
- * call site cannot drop the signature and silently desync from what render drew. `linkRef`
- * stays structural: naming editor-keys' type would cycle that module back onto this layer.
- */
-export function resolvedInlineContent(node, linkRef) {
-    return getInlineContent(node, linkRef?.current, linkRef?.signature ?? '');
+/** Takes the whole reading, so a call site outside the render path cannot drop the signature or
+ *  the grammar and disagree with what the render path drew. */
+export function resolvedInlineContent(node, reading) {
+    return getInlineContent(node, reading.resolver, reading.resolverSignature, reading.grammar);
 }

package/dist/core/inline/inline-widgets.d.ts

@@ -1,59 +1,54 @@
 /**
- * The single source of truth for which inline kinds render as live atomic widgets
- * (contenteditable=false islands marked `[data-inline-widget]`) and how each is recognized.
- * Recognition is registry-owned; DOM building dispatches by layer: a `buildWidget` for
- * core-built widgets, a `component` mounted through the injected portal builder, or neither
- * for the image, whose per-instance builder is injected per render.
+ * The one registry of which inline kinds render as live widgets (non-editable spans marked
+ * `[data-inline-widget]`) and how each is recognized. DOM building has three routes: a
+ * `buildWidget` for core-built widgets, a `component` mounted through the injected portal
+ * builder, or neither for the image, whose builder is injected per render.
  */
 import type { Component } from 'svelte';
-import type { AnyInlineKind, InlineNode } from '../nodes';
+import { type AnyInlineKind, type InlineNode } from '../nodes';
 import type { DocumentView, NodeView } from '../node-views';
 import type { PresentationMode } from '../../presentation-mode';
+import type { GrammarView } from '../../schema/block-openers';
 /**
- * The atomic-widget shell every core builder shares. Its `data-*` attributes are the offset
- * walk's only handle, so the shell is minted here once and builders add only the body.
+ * The widget shell every core builder shares. Its `data-*` attributes are the only handle the
+ * DOM-to-offset traversal has, so the shell is created here once and builders add only the body.
  */
 export declare function mintWidgetShell(className: string, node: InlineNode): HTMLSpanElement;
-/** The raw byte range a shell carries, or null when the attributes are absent or malformed —
- *  {@link mintWidgetShell}'s inverse, so the mint and every read-back move together. */
+/** The raw byte range a shell carries, or null when the attributes are absent or malformed:
+ *  {@link mintWidgetShell}'s inverse, kept beside it so the two move together. */
 export declare function widgetSourceRange(el: Element): {
     start: number;
     end: number;
 } | null;
 /**
  * Props a `component` widget kind is mounted with. Frozen at mount: the pool remounts on a
- * source change, so `source` never shifts under a live instance, but `inline.start`/`end` CAN
- * lag once adjacent typing moves the widget. The live position is the wrapper's re-stamped
- * `data-source-*`, never these fields. The getters below are live for the same reason inverted:
- * an instance the pool reuses would go stale on a frozen value.
+ * source change, so `source` never shifts under a live instance, but `inline.start`/`end` can
+ * lag once typing beside the widget moves it. The live position is the wrapper's rewritten
+ * `data-source-*`, never these fields. The getters below are live for the inverse reason: a
+ * reused instance would go stale on a frozen value.
  */
 export interface InlineWidgetComponentProps {
     inline: InlineNode;
     source: string;
-    /** Absent reads as 'source'. */
-    getPresentationMode?: () => PresentationMode;
-    /** A widget whose body an ENGINE paints emits colors no stylesheet reaches, so it keys its
-     *  render on this. One styled with CSS tokens needs nothing here. Absent reads as 'dark'. */
-    getTheme?: () => string;
+    getPresentationMode: () => PresentationMode;
+    /** A widget whose body a renderer such as KaTeX draws emits colors no stylesheet reaches, so
+     *  it keys its render on this. One styled with CSS tokens needs nothing. */
+    getTheme: () => string;
     /** The pool keys on `${kind} ${source}`, so a widget whose value derives from the document
      *  (footnote numbering) needs this to survive edits elsewhere that change no source. */
-    getDocument?: () => DocumentView | undefined;
-    /**
-     * Memo key for a whole-document derivation: the `$state` document is mutated in place, so
-     * its identity never changes and an identity-keyed memo would hit forever on stale data.
-     * Read it INSIDE the widget's `$derived`; that read is what subscribes it to edits anywhere.
-     */
-    getContentVersion?: () => number;
-    /** `EditorRects.navigateTo`: reveal, scroll and land the caret at a raw offset in a block
-     *  path. Absent in a bare harness, so a widget that navigates declines rather than throws. */
-    navigateTo?: (path: number[], offset?: number) => Promise<boolean>;
+    getDocument: () => DocumentView | undefined;
+    /** Memo key for a whole-document derivation, since the `$state` document mutates in place and
+     *  keeps its identity. Read it inside the widget's `$derived` to re-run on edits anywhere. */
+    getContentVersion: () => number;
+    /** `EditorRects.navigateTo`: mount, scroll to and put the caret at a raw offset in a block
+     *  path. Resolves false where it can't land, so a widget never needs a fallback. */
+    navigateTo: (path: number[], offset?: number) => Promise<boolean>;
+    /** `EditorContext.computeInlineContent` for the widget's editor: it parses as that editor draws,
+     *  and it's a new function whenever the document's definitions change. */
+    computeInlineContent: (node: NodeView) => InlineNode[];
 }
-/**
- * The editor's activation gesture, shared by the surface deciding whether to reveal and the
- * widget deciding whether to act: a Ctrl/Cmd chord while editing, a plain click in reading
- * mode, where there is no caret for a plain click to place. The link click's rule
- * (`Editor.svelte`), applied to widgets.
- */
+/** Shared by the editable element deciding whether to show the source and the widget deciding
+ *  whether to act. Reading mode has no caret to place, so a plain click activates, as for links. */
 export declare function isWidgetActivationClick(modified: boolean, mode: PresentationMode): boolean;
 /** The closed vocabularies as values, so the published conformance kit checks a registration
  *  against the type's own members rather than a copy that ages out of step with it. */
@@ -61,37 +56,30 @@ export declare const DELETE_GRANULARITIES: readonly ["atomic", "select-then-dele
 export declare const ON_EDGE_POLICIES: readonly ["select", "step-over"];
 /**
  * Per-kind editing behavior, read by the caret-edge dispatch
- * (`components/blocks/text/edge-policy-dispatch.ts`). `atomic` deletes in one press where
+ * (`components/blocks/text/edge-policy-dispatch.ts`). `atomic` deletes in one keypress where
  * `select-then-delete` takes two; `onEdge` chooses between selecting the construct whole and
  * stepping over it like a character.
  */
 export interface InlineWidgetEditingPolicy {
     revealSource?: boolean;
-    /**
-     * Where this kind's editable CONTENT sits inside its source span, as offsets relative to
-     * that span — `$x$` answers `{ start: 1, end: 2 }`. It bounds a caret entering the source,
-     * and `end` is where a revealing click lands when the kind maps no point of its own. Only
-     * the kind knows its own delimiters; absent, the caret keeps the leading edge.
-     */
+    /** The editable content's offsets in the source span (`$x$` gives `{ start: 1, end: 2 }`),
+     *  bounding the caret; a click with no mapped point lands at `end`. Absent: the start edge. */
     revealContentSpan?: (source: string) => {
         start: number;
         end: number;
     } | null;
-    /**
-     * The offset in `source` a press on the RENDERED widget names, so a click seats the caret
-     * where it landed rather than at one edge. Only the kind can map its render back to bytes (a
-     * KaTeX island paints glyphs, not source); null declines this point and keeps the fallback.
-     */
+    /** The `source` offset under a click, so the caret goes where the user clicked; only the kind
+     *  can map its render (KaTeX glyphs) back to bytes. Null keeps the fallback. */
     revealOffsetAtPoint?: (widgetEl: HTMLElement, source: string, clientX: number, clientY: number) => number | null;
     deleteGranularity?: (typeof DELETE_GRANULARITIES)[number];
     onEdge?: (typeof ON_EDGE_POLICIES)[number];
     onSelectedKey?: (e: KeyboardEvent, ctx: InlineWidgetEditingContext) => boolean;
     /** The widget's own component handles an activation click ({@link isWidgetActivationClick}),
-     *  so the surface stands its reveal down rather than unmounting the widget under it. */
+     *  so the editable element does not show the source, which would unmount the widget. */
     claimsActivationClick?: boolean;
 }
 export interface InlineWidgetEditingContext {
-    /** Bytes-readonly (G1.9); edits go through `updateContent`. */
+    /** Read-only, since an undo entry may share the node (G1.9); edit through `updateContent`. */
     node: NodeView;
     inline: InlineNode;
     widgetStart: number;
@@ -109,35 +97,26 @@ export interface InlineWidgetDescriptor {
     /** Omitted for a kind whose builder is injected per render (image) or that uses `component`. */
     buildWidget?(node: InlineNode, raw: string): HTMLElement;
     /** The recommended path, mutually exclusive with `buildWidget`: the render layer wraps it in
-     *  the atomic-island span and mounts it through the injected portal builder. */
+     *  the widget shell span and mounts it through the injected portal builder. */
     component?: Component<InlineWidgetComponentProps>;
     editing?: InlineWidgetEditingPolicy;
 }
 export declare function registerInlineWidgetKind(kind: AnyInlineKind, descriptor: InlineWidgetDescriptor): void;
-/**
- * Layer editing fields onto an already-registered kind. The editor-layer wire-up
- * (components/built-in-blocks.ts) attaches behavior here that would otherwise make a core
- * registration import a downstream layer. Throws for an unregistered kind.
- */
+/** Lets the editor layer (`components/built-in-blocks.ts`) attach editing behavior without a core
+ *  registration importing it. Throws for an unregistered kind. */
 export declare function augmentInlineWidgetKind(kind: AnyInlineKind, editing: Partial<InlineWidgetEditingPolicy>): void;
+/** Whether the kind renders as a widget under the editor's grammar, whatever one node's bytes. */
+export declare function isInlineWidgetKind(kind: AnyInlineKind, grammar: GrammarView): boolean;
 /** Kind-level recognition, independent of per-block render policy (renderImagesAsWidgets). */
-export declare function isInlineWidget(node: InlineNode, raw: string): boolean;
-export declare function getInlineWidgetEditing(kind: AnyInlineKind): InlineWidgetEditingPolicy | undefined;
-/** A kind the caret reads as one character: it steps over in one press, carries a column of its
- *  own, and a press ON its glyph names an edge rather than selecting the island whole. */
-export declare function isCharacterLikeWidget(kind: AnyInlineKind): boolean;
-export declare function getInlineWidgetComponent(kind: AnyInlineKind): Component<InlineWidgetComponentProps> | undefined;
-/**
- * Every live widget reachable from `nodes`, in document order. Descends so a widget nested in a
- * non-widget parent is found (the `image` inside `[![alt][ref]][repo]`), but never into a
- * widget's own children, which are atomic. `raw` is the enclosing block's source.
- */
-export declare function flattenInlineWidgets(nodes: ReadonlyArray<InlineNode>, raw: string): InlineNode[];
-/**
- * A `component` kind routes through the injected `buildPortalWidget` because the component layer
- * owns Svelte mounting and `core/` stays framework-free. Null when the node is not a widget, its
- * builder is injected per render (image), or the portal builder is absent or failed.
- */
-export declare function buildCoreInlineWidget(node: InlineNode, raw: string, buildPortalWidget?: (node: InlineNode, raw: string) => HTMLElement | null): HTMLElement | null;
-/** Test-only. Removes every plugin-registered inline-widget kind; built-ins survive. */
-export declare function __resetInlineWidgetsForTests(): void;
+export declare function isInlineWidget(node: InlineNode, raw: string, grammar: GrammarView): boolean;
+export declare function getInlineWidgetEditing(kind: AnyInlineKind, grammar: GrammarView): InlineWidgetEditingPolicy | undefined;
+/** A kind the caret treats as one character: it steps over in one keypress, has a column of its
+ *  own, and a click on its glyph names an edge rather than selecting the widget whole. */
+export declare function isCharacterLikeWidget(kind: AnyInlineKind, grammar: GrammarView): boolean;
+export declare function getInlineWidgetComponent(kind: AnyInlineKind, grammar: GrammarView): Component<InlineWidgetComponentProps> | undefined;
+/** Descends into non-widget parents (the `image` inside `[![alt][ref]][repo]`) but never into a
+ *  widget, whose children are atomic. `raw` is the enclosing block's source. */
+export declare function flattenInlineWidgets(nodes: ReadonlyArray<InlineNode>, raw: string, grammar: GrammarView): InlineNode[];
+/** A `component` kind mounts through the injected `buildPortalWidget`, keeping `core/` free of
+ *  Svelte. Null for a non-widget, an image (built per render), or a missing or failed portal. */
+export declare function buildCoreInlineWidget(node: InlineNode, raw: string, buildPortalWidget: ((node: InlineNode, raw: string) => HTMLElement | null) | undefined, grammar: GrammarView): HTMLElement | null;