@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/components/blocks/text/text-clipboard.d.ts

@@ -4,67 +4,58 @@
  */
 import type { BlockEditActions } from '../../../action-contracts';
 import type { NodeView } from '../../../core/node-views';
-import type { DocumentGetter, LinkReferenceResolverRef, PasteImageHook } from '../../../editor-keys';
+import type { DocumentGetter, PasteImageHook } from '../../../editor-keys';
 import type { EditorEvents } from '../../../editor-events';
 import type { WidgetSelectionState } from '../../image/widget-selection-state.svelte';
-import type { AmbientCursorIO } from '../../../ambient/ambient-cursor';
+import type { SurfaceBackend } from '../../../cursor/surface-backend';
 import type { CrossBlockHandlers } from '../../../selection/cross-block/dispatch';
 import type { PasteCommitCoordinator } from '../../../tree-operations/paste/paste-deps';
-import type { GrammarView } from '../../../schema/block-openers';
 import type { PluginActivation } from '../../../schema/plugin-activation';
 import type { SelectionState } from '../../../selection/selection-state.svelte';
-import type { StickyColumnState } from '../../../cursor/sticky-column';
-import type { EdgeAffinityState } from '../../../cursor/edge-affinity';
+import type { CaretMemory } from '../../../cursor/caret-memory';
 import { type ClipboardCaretIO, type ClipboardHandlers, type RevealFold } from '../editable-surface';
-import type { PresentationMode } from '../../../presentation-mode';
+import type { Reading } from '../../../schema/reading';
+import type { StoredAs } from '../../../schema/stored-as';
 export interface TextClipboardDeps {
     get node(): NodeView;
     get index(): number;
     get myPath(): number[];
-    /** Local caret reads go through `cursor`; `caret` is the narrower door the shared
-     *  clipboard seam anchors an image insertion with, a passthrough never read here. */
-    cursor: AmbientCursorIO;
+    /** Local caret reads go through `cursor`; `caret` is the narrower interface the shared
+     *  clipboard code anchors an image insertion with, passed through and never read here. */
+    cursor: SurfaceBackend;
     caret: ClipboardCaretIO;
     crossBlock: CrossBlockHandlers;
     events: EditorEvents;
     onPasteImage: PasteImageHook | undefined;
     selection: SelectionState;
-    stickyColumn: StickyColumnState;
-    edgeAffinity: EdgeAffinityState;
+    caretMemory: CaretMemory;
     blockEdit: BlockEditActions;
     pasteCoordinator: PasteCommitCoordinator;
-    /** The instance grammar, so an unlisted plugin's opener never claims pasted bytes here. */
-    grammar: GrammarView | undefined;
     /** The plugins this instance activated, so an unlisted plugin's paste transform stays out. */
     activePlugins: PluginActivation;
     getDoc: DocumentGetter;
     widgetSelection: WidgetSelectionState;
     setPendingCursor: (offset: number | null) => void;
-    /** Reading mode: cut degrades to copy, paste is inert. The events still fire
-     *  on a non-editable surface, so the gate lives in the handlers. */
+    /** Reading mode: cut becomes copy, paste does nothing. The events still fire
+     *  on a non-editable element, so the check lives in the handlers. */
     isReadOnly: () => boolean;
-    /** Fold a live source-reveal before a clipboard mutation, so cut/paste run against
-     *  a CST consistent with the swapped DOM. Null when no reveal was open. */
+    /** Hide a construct's shown source before a clipboard edit, so cut and paste run
+     *  against a CST that matches the DOM. Null when no source was showing. */
     foldRevealBeforeMutation: () => RevealFold | null;
-    /** True while an inline-widget source reveal is active on this block. */
+    /** True while an inline widget on this block is showing its source. */
     isRevealing: () => boolean;
-    /** The effective mode the cut's join seam answers to (live-mode.md § 4.5); `undefined` reads
-     *  as not-live. */
-    getPresentationMode: () => PresentationMode | undefined;
-    /** The container prefix this block renders under, which the cut's seam reads its candidate
-     *  back through — an item body the cut left starting with a space reloads under a wider marker. */
-    getAmbientPrefix: () => string;
-    /** The block's live DOM as raw text, so a copy over a revealed (uncommitted) edit
-     *  yields what the user sees rather than the stale raw slice. */
+    /** The block's live DOM as raw text, so a copy over an uncommitted edit yields what
+     *  the user sees rather than a stale slice of `node.raw`. */
     readRevealedText: () => string;
-    get linkRef(): LinkReferenceResolverRef | undefined;
+    /** How this editor reads its bytes: an unlisted plugin's opener never takes pasted bytes here,
+     *  and a cut is a join its mode decides the cleanup of (live-mode.md § 4.5). */
+    get reading(): Reading;
+    /** Where the block's bytes are stored, read when a cut writes. */
+    storedAs: () => StoredAs;
 }
 export interface TextClipboard extends ClipboardHandlers {
-    /**
-     * The block's own handler for a copy/cut/paste the editor root received: a selected widget
-     * clears the native selection, so a block with no text position for a caret to survive in
-     * gets its events at `<body>`, where no surface binding sees them.
-     */
+    /** The block's handler for a clipboard event the editor root received: a selected widget clears
+     *  the browser selection, so the event arrives at `<body>`, past the block's own binding. */
     claimRootClipboard(event: ClipboardEvent): void;
 }
 export declare function createTextClipboard(deps: TextClipboardDeps): TextClipboard;

package/dist/components/blocks/text/text-clipboard.js

@@ -6,7 +6,8 @@ import { resolvedInlineContent } from '../../../core/inline/inline-cache';
 import { isInlineWidget } from '../../../core/inline/inline-widgets';
 import { createClipboardHandlers } from '../editable-surface';
 import { pasteDispatch } from '../../../tree-operations/paste/dispatch';
-import { deleteRangeRaw } from './live-selection-edit';
+import { replaceRangeInLeaf } from '../../../tree-operations/leaf-range';
+import { replaceSelectedWidget } from './widget-interaction';
 export function createTextClipboard(deps) {
     function getSelectedTextFromRaw() {
         const offsets = deps.cursor.getRawSelection();
@@ -14,19 +15,18 @@ export function createTextClipboard(deps) {
             return '';
         return deps.node.raw.slice(offsets.start, offsets.end);
     }
-    // Null unless a widget on THIS block is selected and still present in the parsed
-    // inline content. Shared by copy, cut, and paste-over-widget.
+    // Null unless a widget on this block is selected and still present in the parsed
+    // inline content. Shared by copy, cut, and paste over a widget.
     function selectedWidgetOnThisBlock() {
         const selected = deps.widgetSelection.getSelected();
         if (selected === null || !deps.widgetSelection.isSelected(deps.myPath, selected.sourceStart)) {
             return null;
         }
-        const inline = resolvedInlineContent(deps.node, deps.linkRef).find((n) => isInlineWidget(n, deps.node.raw) && n.start === selected.sourceStart);
+        const inline = resolvedInlineContent(deps.node, deps.reading).find((n) => isInlineWidget(n, deps.node.raw, deps.reading.grammar) && n.start === selected.sourceStart);
         return inline ? { inline, preSelectOffset: selected.preSelectOffset } : null;
     }
     const handlers = createClipboardHandlers({
-        stickyColumn: deps.stickyColumn,
-        edgeAffinity: deps.edgeAffinity,
+        caretMemory: deps.caretMemory,
         selection: deps.selection,
         getDoc: deps.getDoc,
         crossBlock: deps.crossBlock,
@@ -44,8 +44,8 @@ export function createTextClipboard(deps) {
             e.clipboardData?.setData('text/plain', deps.node.raw.slice(widget.inline.start, widget.inline.end));
             return true;
         },
-        // A selection over an ACTIVE reveal covers uncommitted DOM, so slice the live text
-        // rather than the stale `node.raw`; copy must not fold, because folding mutates.
+        // A selection over a construct whose source is showing covers uncommitted DOM, so slice
+        // the live text rather than the stale `node.raw`; copy must not hide it, because that writes.
         copyTail: (e) => {
             e.preventDefault();
             if (deps.isRevealing()) {
@@ -62,9 +62,7 @@ export function createTextClipboard(deps) {
                 return false;
             const { inline, preSelectOffset } = widget;
             e.clipboardData?.setData('text/plain', deps.node.raw.slice(inline.start, inline.end));
-            const newRaw = deps.node.raw.slice(0, inline.start) + deps.node.raw.slice(inline.end);
-            void deps.blockEdit.updateBlockContent(deps.index, newRaw, preSelectOffset, inline.start);
-            deps.widgetSelection.clear();
+            void replaceSelectedWidget(deps, inline, preSelectOffset, '', 'literal');
             return true;
         },
         cutTail: (e) => {
@@ -75,37 +73,34 @@ export function createTextClipboard(deps) {
             const selOffsets = deps.cursor.getRawSelection();
             if (!selOffsets)
                 return;
-            // A cut is a delete, so it crosses the same join seam: in live the range can span
-            // delimiter runs the reader never saw, and a raw splice would print them.
-            const edit = deleteRangeRaw(deps.node, selOffsets, deps.getPresentationMode(), deps.linkRef, deps.getAmbientPrefix());
-            void deps.blockEdit.updateBlockContent(deps.index, edit.raw, selOffsets.start);
-            deps.setPendingCursor(edit.caret);
+            // A cut is a delete, so it goes through the same join rules: in live mode the range
+            // can span delimiter runs the user never saw, and a plain splice would print them.
+            const edit = replaceRangeInLeaf(deps.node, selOffsets, '', deps.storedAs());
+            const write = deps.blockEdit.updateBlockContent(deps.index, edit.raw, 'literal', selOffsets.start, edit.caret);
+            if (write.admitted)
+                deps.setPendingCursor(write.caret);
         },
         pasteTail: async (pastedText, foldedCaret) => {
+            // A selected widget is the selection a paste replaces, through the same route as any.
             const widget = selectedWidgetOnThisBlock();
-            if (widget !== null) {
-                const { inline, preSelectOffset } = widget;
-                const newRaw = deps.node.raw.slice(0, inline.start) + pastedText + deps.node.raw.slice(inline.end);
-                void deps.blockEdit.updateBlockContent(deps.index, newRaw, preSelectOffset, inline.start + pastedText.length);
+            if (widget !== null)
                 deps.widgetSelection.clear();
-                return;
-            }
-            // After a reveal fold the caret sits on the widget's element-level edge, where
-            // getRaw can read null; the committed caret is the correct landing offset.
+            // Once the widget's source is hidden again the caret sits on its element-level edge,
+            // where `getRaw` can read null; the committed caret is the right offset.
             const offset = deps.cursor.getRaw() ?? foldedCaret ?? 0;
-            const selOffsets = deps.cursor.getRawSelection();
+            const range = widget?.inline ?? deps.cursor.getRawSelection();
             const result = await pasteDispatch({
                 pastedText,
                 targetPath: deps.myPath,
-                offset: selOffsets ? selOffsets.start : offset,
-                preDelete: selOffsets ? { start: selOffsets.start, end: selOffsets.end } : undefined
+                offset: range ? range.start : offset,
+                preDelete: range ? { start: range.start, end: range.end } : undefined,
+                caretBefore: widget?.preSelectOffset
             }, {
                 doc: deps.getDoc(),
                 blockEdit: deps.blockEdit,
                 controller: deps.pasteCoordinator,
-                grammar: deps.grammar,
-                activePlugins: deps.activePlugins,
-                seam: { presentationMode: deps.getPresentationMode(), linkRef: deps.linkRef }
+                reading: deps.reading,
+                activePlugins: deps.activePlugins
             });
             // Pending, so the caret set and the raw mutation land in one reactive flush.
             if (result.inlineCaretOffset !== undefined) {
@@ -115,8 +110,8 @@ export function createTextClipboard(deps) {
     });
     return {
         ...handlers,
-        // Routed to the same arms the caret route reaches, so the reading gate, the reveal
-        // fold and the sticky reset come along rather than being re-carried here.
+        // Routed to the same handlers a caret-side event reaches, so the reading-mode check, the
+        // source hide and the sticky-column reset come along rather than being repeated here.
         claimRootClipboard(event) {
             if (selectedWidgetOnThisBlock() === null)
                 return;

package/dist/components/blocks/text/text-keydown.d.ts

@@ -1,45 +1,35 @@
 /**
- * Pure raw/caret transforms for TextEditableBlock's structural gestures — heading-level
- * swap, demotion to prose, hard-break insertion, literal-tab insertion. The component
- * owns the plumbing; these own the string math.
+ * Pure raw and caret transforms for TextEditableBlock's structural gestures: changing a
+ * heading's level, demoting it to prose, inserting a hard break, inserting a literal tab.
+ * The component owns the wiring; these own the string math.
  */
-import type { ContentRange } from '../../../core/inline';
+import { type ContentRange } from '../../../core/inline';
+import { type LineEnding } from '../../../core/lines';
 export interface TextEditResult {
     newRaw: string;
     caretOffset: number;
 }
 /**
- * Give up the block's own structural bytes, whichever end the kind keeps them at: a prefix for
- * ATX, an underline line for setext. Both sides read the kind's CONTENT RANGE and nothing else, so
- * a prefix rewrite cannot disagree with the gate that let the press through (`  ## x` is a heading
- * whose `#`s a `^#` regex never reaches). Null where the content IS the whole display.
+ * Drop the block's structure outside its content range, the same range the check that let the
+ * key through reads. Null where the content is the whole display.
  */
 export declare function demoteToParagraph(raw: string, content: ContentRange, preEditOffset: number): TextEditResult | null;
-/** Drop everything before `contentStart` — a heading's marker prefix and any spaces that precede
- *  it, which sit before every caret the content range admits. */
-export declare function dropStructuralPrefix(raw: string, contentStart: number, preEditOffset: number): TextEditResult;
-/** Drop everything past `contentEnd` but the block's own trailing line ending — the setext
- *  underline, which sits after every caret the content range admits. */
-export declare function dropStructuralSuffix(raw: string, contentEnd: number, preEditOffset: number): TextEditResult;
-/**
- * An ATX heading left with no text is a marker standing over nothing: unfocused it paints
- * nothing (the chrome-only stamp is focus-scoped), so the block would survive invisibly and
- * resurface as a `#` on the next click. On blur it becomes the empty paragraph it looks like.
- */
+/** An ATX heading with no text draws nothing when unfocused, so on blur it becomes the empty
+ *  paragraph it looks like rather than a `#` that reappears on the next click. */
 export declare function demoteEmptyAtxHeading(raw: string, content: ContentRange): TextEditResult | null;
-/**
- * Re-mark the block's CONTENT with an ATX prefix for `level`, replacing whatever structural bytes
- * the current kind keeps — the same content range {@link demoteToParagraph} reads, so an indented
- * `  ## x` or a setext underline is given up rather than left in the new heading's text.
- * `level === 0` IS the demotion, and null there means the content already is the whole display.
- * Idempotent, not a toggle: stripping is reached only by asking for level 0.
- */
+/** Re-mark the content with an ATX prefix for `level`, replacing the current kind's structural
+ *  bytes. Not a toggle: level 0 demotes, and null there means there was nothing to strip. */
 export declare function cycleHeading(raw: string, content: ContentRange, level: number, preEditOffset: number): TextEditResult | null;
 /**
- * Insert a GFM hard-break (a backslash at end of line) at `offset` within the display.
- * At end-of-display the break's own ending becomes the block's trailing ending, so the
- * break is transitional there until the next keystroke supplies its following line.
+ * Insert a GFM hard break (a backslash at end of line) at `offset`. At the content's end, the
+ * line ending after the content stands in for the break's own until the next key adds the line.
  */
-export declare function insertHardBreak(raw: string, offset: number): TextEditResult;
+export declare function insertHardBreak(raw: string, offset: number, ending: LineEnding, content: ContentRange): TextEditResult;
+/** The key typed after a hard break's backslash, opening the break's own line at `lineEnd` (past a
+ *  heading's closing run). Works on the display text, without its trailing line ending. */
+export declare function openHardBreakLine(display: string, lineEnd: number, ending: LineEnding, key: string): {
+    display: string;
+    caret: number;
+};
 /** Insert a literal tab character at `offset` within the display portion. */
 export declare function insertLiteralTab(raw: string, offset: number): TextEditResult;

package/dist/components/blocks/text/text-keydown.js

@@ -1,55 +1,36 @@
 /**
- * Pure raw/caret transforms for TextEditableBlock's structural gestures — heading-level
- * swap, demotion to prose, hard-break insertion, literal-tab insertion. The component
- * owns the plumbing; these own the string math.
+ * Pure raw and caret transforms for TextEditableBlock's structural gestures: changing a
+ * heading's level, demoting it to prose, inserting a hard break, inserting a literal tab.
+ * The component owns the wiring; these own the string math.
  */
+import { sameLineSuffixOf } from '../../../core/inline';
 import { displayLength, ownTrailingLineEnding, trailingLineEnding, trimTrailingLineEnding } from '../../../core/lines';
 /**
- * Give up the block's own structural bytes, whichever end the kind keeps them at: a prefix for
- * ATX, an underline line for setext. Both sides read the kind's CONTENT RANGE and nothing else, so
- * a prefix rewrite cannot disagree with the gate that let the press through (`  ## x` is a heading
- * whose `#`s a `^#` regex never reaches). Null where the content IS the whole display.
+ * Drop the block's structure outside its content range, the same range the check that let the
+ * key through reads. Null where the content is the whole display.
  */
 export function demoteToParagraph(raw, content, preEditOffset) {
-    if (content.start > 0)
-        return dropStructuralPrefix(raw, content.start, preEditOffset);
-    if (content.end < displayLength(raw))
-        return dropStructuralSuffix(raw, content.end, preEditOffset);
-    return null;
-}
-/** Drop everything before `contentStart` — a heading's marker prefix and any spaces that precede
- *  it, which sit before every caret the content range admits. */
-export function dropStructuralPrefix(raw, contentStart, preEditOffset) {
+    if (content.start === 0 && content.end === displayLength(raw))
+        return null;
+    const inContent = Math.min(Math.max(preEditOffset, content.start), content.end);
     return {
-        newRaw: raw.slice(contentStart),
-        caretOffset: Math.max(0, preEditOffset - contentStart)
+        newRaw: raw.slice(content.start, content.end) + endingPastContent(raw, content.end),
+        caretOffset: inContent - content.start
     };
 }
-/** Drop everything past `contentEnd` but the block's own trailing line ending — the setext
- *  underline, which sits after every caret the content range admits. */
-export function dropStructuralSuffix(raw, contentEnd, preEditOffset) {
-    return {
-        newRaw: raw.slice(0, contentEnd) + ownTrailingLineEnding(raw),
-        caretOffset: Math.min(preEditOffset, contentEnd)
-    };
+// The line ending the dropped structure ended in, a lone `\r` on a document's last line included.
+function endingPastContent(raw, contentEnd) {
+    return /(?:\r\n?|\n)$/.exec(raw.slice(contentEnd))?.[0] ?? '';
 }
-/**
- * An ATX heading left with no text is a marker standing over nothing: unfocused it paints
- * nothing (the chrome-only stamp is focus-scoped), so the block would survive invisibly and
- * resurface as a `#` on the next click. On blur it becomes the empty paragraph it looks like.
- */
+/** An ATX heading with no text draws nothing when unfocused, so on blur it becomes the empty
+ *  paragraph it looks like rather than a `#` that reappears on the next click. */
 export function demoteEmptyAtxHeading(raw, content) {
     if (content.start === 0 || content.end > content.start)
         return null;
     return demoteToParagraph(raw, content, 0);
 }
-/**
- * Re-mark the block's CONTENT with an ATX prefix for `level`, replacing whatever structural bytes
- * the current kind keeps — the same content range {@link demoteToParagraph} reads, so an indented
- * `  ## x` or a setext underline is given up rather than left in the new heading's text.
- * `level === 0` IS the demotion, and null there means the content already is the whole display.
- * Idempotent, not a toggle: stripping is reached only by asking for level 0.
- */
+/** Re-mark the content with an ATX prefix for `level`, replacing the current kind's structural
+ *  bytes. Not a toggle: level 0 demotes, and null there means there was nothing to strip. */
 export function cycleHeading(raw, content, level, preEditOffset) {
     if (level === 0)
         return demoteToParagraph(raw, content, preEditOffset);
@@ -57,28 +38,50 @@ export function cycleHeading(raw, content, level, preEditOffset) {
     const newDisplay = prefix + raw.slice(content.start, content.end);
     const inContent = Math.min(Math.max(preEditOffset, content.start), content.end);
     return {
-        newRaw: newDisplay + ownTrailingLineEnding(raw),
+        newRaw: newDisplay + endingPastContent(raw, content.end),
         caretOffset: prefix.length + (inContent - content.start)
     };
 }
 /**
- * Insert a GFM hard-break (a backslash at end of line) at `offset` within the display.
- * At end-of-display the break's own ending becomes the block's trailing ending, so the
- * break is transitional there until the next keystroke supplies its following line.
+ * Insert a GFM hard break (a backslash at end of line) at `offset`. At the content's end, the
+ * line ending after the content stands in for the break's own until the next key adds the line.
  */
-export function insertHardBreak(raw, offset) {
+export function insertHardBreak(raw, offset, ending, content) {
     const display = trimTrailingLineEnding(raw);
     const trailing = ownTrailingLineEnding(raw);
-    // The break carries the block's own ending (G4.20): CommonMark reads a backslash
-    // before either LF or CRLF as a hard break, so a CRLF block stays CRLF.
-    const breakBytes = '\\' + trailingLineEnding(raw);
-    const newDisplay = display.slice(0, offset) + breakBytes + display.slice(offset);
-    // At end-of-display the inserted ending is itself the trailing ending; reattaching
-    // the original would double it into a blank line and break list-item continuation.
-    const newRaw = offset >= display.length ? newDisplay : newDisplay + trailing;
+    if (offset === content.end && content.end < display.length) {
+        return {
+            newRaw: raw.slice(0, content.end) + '\\' + raw.slice(content.end),
+            caretOffset: content.end + 1
+        };
+    }
+    const lineTail = sameLineSuffixOf(raw, content.end);
+    if (offset >= content.start && offset < content.end && lineTail) {
+        return breakBeforeLine(display.slice(0, offset) + '\\' + lineTail, display.slice(offset, content.end) + display.slice(content.end + lineTail.length));
+    }
+    return breakBeforeLine(display.slice(0, offset) + '\\', display.slice(offset));
+    /** `head`, the break's line ending, then `rest` on the new line. */
+    function breakBeforeLine(head, rest) {
+        // The break carries the block's own ending, else the document's `ending`: CommonMark reads
+        // a backslash before either LF or CRLF as a hard break, so a CRLF block stays CRLF.
+        const breakEnding = trailingLineEnding(raw, ending);
+        const newDisplay = head + breakEnding + rest;
+        // With nothing after the break, the inserted ending is itself the trailing ending;
+        // reattaching the original would double it into a blank line and break list continuation.
+        const newRaw = rest === '' ? newDisplay : newDisplay + trailing;
+        return {
+            newRaw,
+            caretOffset: Math.min(head.length + breakEnding.length, displayLength(newRaw))
+        };
+    }
+}
+/** The key typed after a hard break's backslash, opening the break's own line at `lineEnd` (past a
+ *  heading's closing run). Works on the display text, without its trailing line ending. */
+export function openHardBreakLine(display, lineEnd, ending, key) {
+    const line = ending + key;
     return {
-        newRaw,
-        caretOffset: Math.min(offset + breakBytes.length, displayLength(newRaw))
+        display: display.slice(0, lineEnd) + line + display.slice(lineEnd),
+        caret: lineEnd + line.length
     };
 }
 /** Insert a literal tab character at `offset` within the display portion. */

package/dist/components/blocks/text/text-render.d.ts

@@ -1,14 +1,13 @@
 /**
- * DOM-build steps for TextEditableBlock's render $effect. The component owns the
- * effect and the `pendingCursorOffset` restore (those writes touch $state); this
- * factory owns the imperative inline-DOM construction and carries a live caret across
- * a decoration-driven rebuild the edit path's pending restore doesn't cover.
+ * DOM-building steps for TextEditableBlock's render effect. The component owns the effect
+ * and the `pendingCursorOffset` restore, since those writes touch `$state`; this factory
+ * builds the inline DOM and keeps a live caret across a rebuild a decoration caused, which
+ * the edit path's own restore does not cover.
  */
 import type { AmbientPrefix } from '../../../block-component';
 import type { DocumentView, NodeView } from '../../../core/node-views';
-import { type PresentationMode } from '../../../presentation-mode';
 import type { ResolveImageUrl, ResolveLinkUrl } from '../../../editor-keys';
-import type { LinkReferenceResolver } from '../../../core/inline/link-reference-resolver';
+import type { Reading } from '../../../schema/reading';
 import { type ImageLoadPolicy } from '../../../core/inline-render';
 import type { IndexedDecoration } from '../../../decorations/buckets';
 import type { ReplaceDecoration, WidgetDecoration } from '../../../decorations/types';
@@ -21,47 +20,38 @@ export interface TextRenderDeps {
     resolveImageUrl: ResolveImageUrl;
     resolveLinkUrl: ResolveLinkUrl;
     get imageLoadPolicy(): ImageLoadPolicy;
-    /** Effective mode. Read inside the render pass on purpose: the read is the
-     *  reactive dependency that re-renders every mounted block on a mode flip. */
-    get presentationMode(): PresentationMode;
-    /** The editor's theme name, forwarded to widgets. NOT a render-key term: this DOM is
-     *  themed by CSS, so only a widget whose engine paints its own colors reads it. */
-    getTheme?: () => string;
+    /** How the editor reads its bytes. Its mode is read inside the render pass on purpose: that read
+     *  is the reactive dependency that re-renders every mounted block when the mode changes. */
+    get reading(): Reading;
+    /** The editor's theme name, passed on to widgets. Not part of the render key: this DOM
+     *  is themed by CSS, so only a widget that draws its own colors reads it. */
+    getTheme: () => string;
     /** Live root document for widgets that derive from it. A getter, so a pooled widget
      *  re-reads the current document across edits rather than a mount-time snapshot. */
     getDocument: () => DocumentView | undefined;
-    /** The editor's content version, so a widget can memoize a document-wide derivation
-     *  on it. Absent in a bare harness. */
-    getContentVersion?: () => number;
-    /** The editor's navigation door, forwarded to widgets whose gesture jumps elsewhere. */
-    navigateTo?: (path: number[]) => Promise<boolean>;
-    get linkResolver(): LinkReferenceResolver | undefined;
-    /** A compact stamp changing exactly when the document's LRD signature does
-     *  (`link-reference-resolver.ts` mints it), so a reference-bearing block folds this
-     *  into its render key instead of a signature string that reaches ~MB scale. */
-    get linkStamp(): string;
-    /** Position-sorted islands. A getter read inside the render pass on purpose: that
-     *  read is the reactive dependency that re-renders the block on an island change. */
+    /** The editor's content version, so a widget can memoize a document-wide derivation on it. */
+    getContentVersion: () => number;
+    /** The editor's navigation call, passed on to widgets whose gesture jumps elsewhere. */
+    navigateTo: (path: number[]) => Promise<boolean>;
+    /** Decoration widgets, sorted by position. A getter read inside the render pass on
+     *  purpose: that read is the dependency that re-renders the block when one changes. */
     get islands(): IndexedDecoration<WidgetDecoration | ReplaceDecoration>[];
     brokenUrlCache: Set<string>;
-    /** A widget's synchronous mount throw goes to the editor's `error` channel. Absent →
-     *  unsurfaced; the widget still falls back to its raw source. */
-    reportRenderError?: (error: unknown) => void;
+    /** A widget that throws while mounting reports to the editor's `error` event, and still falls
+     *  back to its raw source. */
+    reportRenderError: (error: unknown) => void;
 }
 export interface TextRender {
-    /**
-     * Rebuild the block's children from current node state. Skips work on an unchanged
-     * render key unless `forceRebuild` — pass it when a pending cursor restore needs the
-     * DOM re-anchored. `carryCaret` re-anchors the caret; the edit path passes false.
-     */
+    /** Rebuild the block's children, skipped on an unchanged render key unless `forceRebuild` (a
+     *  pending cursor restore). `carryCaret` re-anchors the caret; the edit path passes false. */
     render(opts?: {
         forceRebuild?: boolean;
         carryCaret?: boolean;
     }): void;
-    /** Destroy every pooled widget instance — called when the block unmounts. */
+    /** Destroy every pooled widget instance, called when the block unmounts. */
     dispose(): void;
 }
-/** Which renderKey segment(s) differ — the interaction trace's rebuild cause. Pure over
- *  the key format, so the recorder never learns the NUL layout. */
+/** Which parts of the render key differ, which the interaction trace reports as the cause of
+ *  a rebuild. Pure over the key format, so the recorder never learns the NUL layout. */
 export declare function renderKeySegmentDiff(prev: string, next: string): string;
 export declare function createTextRender(deps: TextRenderDeps): TextRender;