@vscode/markdown-editor 0.0.2-12 → 0.0.2-14

package/dist/index.d.ts

@@ -6,10 +6,27 @@ import { ISettableObservable } from './_observables/index';
 import { ITransaction } from './_observables/index';
 import { MonarchTokenizer } from 'monaco-editor/esm/vs/editor/standalone/common/monarch/monarchLexer.js';
 
+declare interface AddedItem {
+    readonly kind: 'added';
+    readonly node: AstNode;
+    readonly modifiedStart: number;
+    readonly insertedLocal: readonly AnnotatedRange[];
+}
+
+/**
+ * A word/character-level highlight inside a single block, in that block's
+ * *local* coordinate space (`0` = block start). `inserted` ranges live on a
+ * modified/added block, `deleted` ranges on an original/removed block.
+ */
+declare interface AnnotatedRange {
+    readonly range: OffsetRange;
+    readonly kind: 'inserted' | 'deleted';
+}
+
 /** Every concrete node kind, for exhaustive consumer-side dispatch. */
 export declare type AnyAstNode = TextAstNode | MarkerAstNode | GlueAstNode | ThematicBreakAstNode | StrongAstNode | EmphasisAstNode | StrikethroughAstNode | InlineCodeAstNode | InlineMathAstNode | LinkAstNode | ImageAstNode | HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | BlockQuoteAstNode | ListAstNode | ListItemAstNode | TableAstNode | TableRowAstNode | TableCellAstNode | DocumentAstNode;
 
-declare type AnyViewData = DocumentViewData | BlockViewData | InlineViewData | ListItemViewData | TableRowViewData | TableCellViewData | MarkerViewData | GlueViewData;
+declare type AnyViewData = DocumentViewData | BlockViewData | InlineViewData | ListItemViewData | TableRowViewData | TableCellViewData | MarkerViewData | GlueViewData | DiffHunkViewData | DiffDecorationViewData;
 
 export declare abstract class AstNode {
     abstract readonly kind: string;
@@ -275,6 +292,228 @@ export declare class CodeBlockViewNode extends BlockViewNode<CodeBlockViewData>
     dispose(): void;
 }
 
+/** A persistent comment anchored to a source range. */
+declare interface Comment_2 {
+    readonly id: string;
+    /** Source range the comment refers to (its highlighted region). */
+    readonly range: OffsetRange;
+    /** The comment text. */
+    readonly body: string;
+    /** Display name of the author, if any. */
+    readonly author?: string;
+    /** Creation time (epoch ms), used to render a relative timestamp. */
+    readonly createdAt?: number;
+}
+export { Comment_2 as Comment }
+
+/**
+ * A self-contained comment input box — a rounded panel with an auto-growing
+ * textarea and a send button, styled after the gdocs/Word "add a comment"
+ * affordance.
+ *
+ * This widget is *positioning-agnostic*: it only owns its own DOM and state.
+ * A host (the comment-mode controller, or a fixture) mounts {@link element}
+ * wherever it likes and is responsible for placing it relative to a selection.
+ *
+ * State is observable-driven (no framework): {@link value} reflects the live
+ * textarea content; submit/cancel are reported through the option callbacks.
+ */
+export declare class CommentInputWidget extends Disposable {
+    private readonly _options?;
+    readonly element: HTMLElement;
+    private readonly _textarea;
+    private readonly _measure;
+    private readonly _submitButton;
+    private readonly _value;
+    /** Live, untrimmed textarea content. */
+    get value(): IObservable<string>;
+    /** The raw textarea, exposed so a host can move focus into it (e.g. on Tab). */
+    get inputElement(): HTMLTextAreaElement;
+    constructor(_options?: CommentInputWidgetOptions | undefined);
+    /** Move focus into the textarea (caret at the end). */
+    focus(): void;
+    /** Replace the textarea content. */
+    setText(text: string): void;
+    /** Clear the textarea. */
+    clear(): void;
+    private _submit;
+    private _autoSize;
+}
+
+export declare interface CommentInputWidgetOptions {
+    /** Placeholder shown while the textarea is empty. Defaults to "Add Comment". */
+    readonly placeholder?: string;
+    /**
+     * Called when the user submits a non-empty comment (Enter or the send
+     * button). The text is trimmed; never called with an empty string.
+     */
+    readonly onSubmit?: (text: string) => void;
+    /** Called when the user dismisses the input (Escape). */
+    readonly onCancel?: () => void;
+}
+
+/**
+ * Comment mode — a gdocs/Word-style "add a comment" affordance layered on top of
+ * the editor *without modifying it*. It reads the editor's public observables
+ * ({@link EditorModel.readonlyMode}, {@link EditorModel.selection}) and the
+ * exposed {@link EditorView.caretRect} geometry, and mounts a
+ * {@link CommentInputWidget} into {@link EditorView.overlayContainer}.
+ *
+ * Behaviour:
+ *  - Only active in read-only mode (the "review" view).
+ *  - When the selection is non-empty, the input box appears next to the caret
+ *    (the selection's active end) but does NOT take focus, so keyboard selection
+ *    keeps working. Press Tab to move focus into the box, then type.
+ *  - The box appears on mouse-up, not mid-drag, so it doesn't flicker/jump
+ *    while a selection is being dragged out (keyboard selection shows at once).
+ *  - While the box has focus or holds a draft it is frozen in place (selection
+ *    changes, drags and clicks no longer move it). It is dismissed by Escape,
+ *    by submitting, or by blurring an empty box.
+ *  - The editor's painted caret is hidden only while the box has focus (the
+ *    blinking caret then belongs to the comment input); it stays visible while
+ *    the box is merely shown, so keyboard selection remains visible.
+ */
+export declare class CommentModeController extends Disposable {
+    private readonly _model;
+    private readonly _view;
+    private readonly _options?;
+    private readonly _widget;
+    private readonly _gap;
+    private _visible;
+    private _pinnedRange;
+    /**
+     * The range a comment was just submitted for. The box stays hidden for it
+     * until the selection changes, so submitting doesn't immediately re-summon an
+     * empty box on the still-selected text.
+     */
+    private _submittedRange;
+    /** True while a mouse button is held over the editor (a selection drag in progress). */
+    private readonly _mouseDown;
+    constructor(_model: EditorModel, _view: EditorView, _options?: CommentModeControllerOptions | undefined);
+    private _update;
+    private _show;
+    /** Force-hide and clear the box (used by Escape and submit). */
+    private _hide;
+    /**
+     * Hide unless the user is engaged with the box: it has focus or holds a
+     * non-empty draft. This preserves in-progress text and keeps a focused box
+     * open (it is dismissed explicitly via Escape/submit, or by blurring it).
+     */
+    private _autoHide;
+    private _widgetHasFocus;
+    /**
+     * The visible viewport (client coords) used for the flip-above decision: the
+     * nearest scrollable ancestor of the editor. `.md-editor` itself spans the
+     * full document height and never clips, so measuring against it would always
+     * report room below. Falls back to the window when nothing scrolls.
+     */
+    private _getViewportRect;
+    private _hideAndRefocus;
+    private _submit;
+}
+
+export declare interface CommentModeControllerOptions {
+    /** Called when the user submits a comment for the current selection. */
+    readonly onSubmit?: (submission: CommentSubmission) => void;
+    /** Gap (px) between the bottom of the selection and the top of the input box. */
+    readonly gap?: number;
+}
+
+/** Human-readable labels (for pickers / dropdowns). */
+export declare const COMMENTS_DESIGN_LABELS: Record<CommentsDesign, string>;
+
+/** design id → presenter factory over a shared CommentsModel + EditorView. */
+export declare const COMMENTS_DESIGNS: Record<CommentsDesign, CommentsPresenterFactory>;
+
+/** The available comment rendering designs. */
+export declare type CommentsDesign = 'connected' | 'vscode' | 'vscode-v2';
+
+/**
+ * Seedable store of {@link Comment}s for the comment-mode contribution. Owns the
+ * comment list and the shared hover state; it has no opinion on rendering or
+ * persistence — a host seeds it via {@link set}/{@link add} and observes
+ * {@link comments}.
+ */
+export declare class CommentsModel {
+    private readonly _comments;
+    /** Monotonic counter for ids of comments created via {@link create}. */
+    private _sequence;
+    /** The current comments, in insertion order. */
+    get comments(): IObservable<readonly Comment_2[]>;
+    /**
+     * The comment currently hovered (by its card or its highlight), or
+     * `undefined`. Shared so the card and the highlight can react together.
+     */
+    readonly hoveredId: ISettableObservable<string | undefined>;
+    /** Replace the whole comment set. */
+    set(comments: readonly Comment_2[]): void;
+    /**
+     * Create a comment from a user submission and append it, generating its `id`
+     * and `createdAt` here so id/time allocation stays the store's concern (the
+     * UI only supplies the range and text). Returns the created comment.
+     */
+    create(input: {
+        range: OffsetRange;
+        body: string;
+        author?: string;
+    }): Comment_2;
+    /** Append a comment. */
+    add(comment: Comment_2): void;
+    /** Remove a comment by id. */
+    remove(id: string): void;
+}
+
+/** Optional, design-specific context a presenter may use (ignored by others). */
+export declare interface CommentsPresenterContext {
+    /** Light/dark hint for the token-wrapped VS Code widget designs. */
+    readonly theme?: 'light' | 'dark';
+    /**
+     * Resolves a source offset to a 1-based line number, for designs that show
+     * line info (the VS Code V1 card). Optional because the model itself carries
+     * no text; the host (which owns the source) supplies it.
+     */
+    readonly resolveLine?: (offset: number) => number;
+}
+
+/** Builds a presenter for a given model + editor view. */
+export declare type CommentsPresenterFactory = (model: CommentsModel, view: EditorView, context?: CommentsPresenterContext) => ICommentsPresenter;
+
+/** A comment the user submitted, with the source range it was anchored to. */
+export declare interface CommentSubmission {
+    readonly text: string;
+    readonly range: OffsetRange;
+}
+
+/**
+ * Renders persistent comments as a gdocs-style side rail: each comment's range
+ * is highlighted (reusing the editor's selection geometry via
+ * {@link EditorView.rangeRects}), a leader line curves from the bottom of that
+ * highlight to a card stacked in the right rail, and cards never overlap.
+ *
+ * Everything is mounted into {@link EditorView.overlayContainer} so it shares
+ * the selection/caret coordinate space and scrolls with the document. When the
+ * editor's natural right margin is too narrow for the rail, the view reserves
+ * proportional space by padding the editor on the right — but only while there
+ * are comments.
+ */
+export declare class CommentsView extends Disposable {
+    private readonly _model;
+    private readonly _view;
+    private readonly _layer;
+    private readonly _entries;
+    constructor(_model: CommentsModel, _view: EditorView);
+    private _createLayer;
+    private _update;
+    /** Create/update/remove per-comment DOM to match `comments`. */
+    private _reconcile;
+    private _createEntry;
+    private _fillCard;
+    private _disposeEntry;
+    /** Position highlights, cards (stacked) and leader lines. */
+    private _layout;
+    private _applyHover;
+}
+
 /**
  * A {@link MonacoSyntaxHighlighter} preloaded with a handful of common Monarch
  * grammars (plus the usual short aliases). Unknown languages fall back to an
@@ -366,6 +605,74 @@ export declare const deleteWordLeft: EditCommand;
 
 export declare const deleteWordRight: EditCommand;
 
+/**
+ * A read-only "removed" decoration: an original block rendered (red) above its
+ * place in the modified document, occupying vertical space like a view-zone but
+ * contributing **zero** source length, so the editor's source mapping stays the
+ * modified document and editing is unaffected. Used for `removed` and the
+ * original side of a `replaced` block in editor diff mode.
+ */
+declare class DiffDecorationViewData {
+    readonly ast: AstNode;
+    readonly side: BlockViewData;
+    readonly deletedRanges: readonly DiffHighlightRange[];
+    /** True when the whole block was removed: solid red band, no word rects. */
+    readonly whole: boolean;
+    /** Absolute offset of this block in the *original* document. */
+    readonly originalStart: number;
+    readonly kind = "diffDecoration";
+    constructor(ast: AstNode, side: BlockViewData, deletedRanges: readonly DiffHighlightRange[], 
+    /** True when the whole block was removed: solid red band, no word rects. */
+    whole: boolean, 
+    /** Absolute offset of this block in the *original* document. */
+    originalStart: number);
+}
+
+/** A word/character highlight inside one diff side, in block-local coords. */
+declare interface DiffHighlightRange {
+    readonly range: OffsetRange;
+    readonly kind: 'inserted' | 'deleted';
+}
+
+/**
+ * A changed block rendered as its original form stacked over its modified form
+ * (either side may be absent for a pure deletion/insertion). It is itself a
+ * document child the renderer mounts like a block; its {@link ast} is the
+ * surviving side's ast, used only for view-node identity/reuse.
+ */
+declare class DiffHunkViewData {
+    readonly ast: AstNode;
+    readonly original: DiffSideViewData | undefined;
+    readonly modified: DiffSideViewData | undefined;
+    readonly kind = "diffHunk";
+    constructor(ast: AstNode, original: DiffSideViewData | undefined, modified: DiffSideViewData | undefined);
+}
+
+/**
+ * The recursive classification of a diff. Each item describes one aligned
+ * position in the merged document:
+ *
+ * - `unchanged` — render the (modified) node once, neutral.
+ * - `added`     — exists only in the modified document (green).
+ * - `removed`   — exists only in the original document (red).
+ * - `replaced`  — a *leaf* block changed in place → render original over
+ *                 modified, with word-level {@link AnnotatedRange}s on each.
+ * - `nested`    — a *container* changed → render it once and diff its
+ *                 {@link NestedItem.children} recursively.
+ *
+ * Offsets ({@link UnchangedItem.modifiedStart} etc.) are absolute in their
+ * respective documents, so a renderer/visualizer can slice the source text.
+ */
+declare type DiffItem = UnchangedItem | AddedItem | RemovedItem | ReplacedItem | NestedItem;
+
+/** One side (original or modified) of a {@link DiffHunkViewData}. */
+declare interface DiffSideViewData {
+    readonly view: BlockViewData;
+    /** Render in active form (markers/whitespace visible). */
+    readonly active: boolean;
+    readonly ranges: readonly DiffHighlightRange[];
+}
+
 export declare class DocumentAstNode extends AstNode {
     readonly content: readonly (BlockAstNode | GlueAstNode)[];
     readonly kind = "document";
@@ -390,14 +697,21 @@ declare interface DocumentBlockViewData {
     readonly view: BlockViewData;
 }
 
-/** A mounted document child: a block, a run of inter-block glue, or the
- * transient empty paragraph (see {@link PendingParagraphViewData}). */
+/** A mounted document child: a block, a run of inter-block glue, the
+ * transient empty paragraph (see {@link PendingParagraphViewData}), or a
+ * {@link DiffHunkViewData diff hunk} (stacked original/modified blocks). */
 declare interface DocumentChildViewData {
     readonly absoluteStart: number;
     /** For a block: selection reaches it. For glue: always false (unowned, hidden). */
     readonly isActive: boolean;
-    readonly view: BlockViewData | GlueViewData | PendingParagraphViewData;
-    readonly kind: 'block' | 'glue' | 'pendingParagraph';
+    readonly view: BlockViewData | GlueViewData | PendingParagraphViewData | DiffHunkViewData | DiffDecorationViewData;
+    readonly kind: 'block' | 'glue' | 'pendingParagraph' | 'diffHunk' | 'diffDecoration';
+    /**
+     * Diff mode: how this (modified) block changed. `added` = a whole new block
+     * (strong green band, no inline rects); `modified` = a partial change (light
+     * band + inline rects on the changed words).
+     */
+    readonly diffKind?: 'added' | 'modified';
 }
 
 /**
@@ -532,6 +846,16 @@ export declare class EditorModel {
      */
     private _pendingEdit;
     readonly sourceText: ISettableObservable<StringValue, void>;
+    /**
+     * Read-only mode. When `true`, the editor never reveals a block's source
+     * markers (markdown special characters like `**`, `#`, list bullets, code
+     * fences, `$…$`) — every block stays in its clean rendered form regardless
+     * of where the caret/selection is — and source-mutating edits are ignored.
+     * Plain text selection still works everywhere (so the user can copy). The
+     * default (`false`) is the normal editing mode where the active block
+     * reveals its markers.
+     */
+    readonly readonlyMode: ISettableObservable<boolean, void>;
     /**
      * The current selection, or `undefined` when the editor has no caret
      * (e.g. an inactive/unfocused rendering).
@@ -589,6 +913,25 @@ export declare class EditorModel {
      * collapsed this is a one-element set holding {@link activeBlock}.
      */
     readonly activeBlocks: IObservableWithChange<Set<BlockAstNode>, void>;
+    /**
+     * The baseline document to diff against. When set, the editor renders in
+     * diff mode: the modified document ({@link document}) stays editable, while
+     * the baseline's removed/changed blocks are shown as read-only decorations.
+     * `undefined` (the default) renders normally.
+     */
+    readonly baseline: ISettableObservable<StringValue | undefined, void>;
+    private readonly _baselineDocument;
+    /**
+     * The diff of {@link baseline} → {@link document}, or `undefined` when no
+     * baseline is set. The view renders the {@link DiffItem}s as stacked
+     * decorations; `insertedRanges` (modified-side change spans) drive the green
+     * word-level highlight.
+     */
+    readonly diff: IObservableWithChange<    {
+    items: DiffItem[];
+    insertedRanges: OffsetRange[];
+    changedBlocks: Set<BlockAstNode>;
+    } | undefined, void>;
     /**
      * Arm a {@link PendingParagraph} at the given gap, minting a fresh synthetic
      * AST node for it, and park the caret at the gap start. No source edit is
@@ -650,6 +993,7 @@ export declare class EditorView extends Disposable {
     private readonly _cursorView;
     private readonly _selectionView;
     private readonly _gutterMarkersView;
+    private readonly _diffHighlightsView;
     /**
      * The mounted block sequence, in source order. Rebuilt (not mutated) each
      * frame by {@link DocumentViewNode.create}; the view just swaps one
@@ -682,6 +1026,29 @@ export declare class EditorView extends Disposable {
      * lock-step without any manual bookkeeping.
      */
     private readonly _selectionBlocksObs;
+    /**
+     * The caret rect (zero width) at the selection's active end, in
+     * {@link overlayContainer}-local coordinates, or `undefined` when there is no
+     * caret. This is the same geometry the editor paints its cursor from, so
+     * contributions (e.g. comment mode) can anchor an overlay to the active end of
+     * the selection — where the user's cursor is — without re-deriving geometry.
+     */
+    private readonly _caretRect;
+    get caretRect(): IObservable<Rect2D | undefined>;
+    /**
+     * The container that establishes the positioning context for the editor's
+     * overlays (cursor, selection, gutter). Contributions mount their own
+     * absolutely-positioned overlays here so they share the coordinate space of
+     * {@link caretRect}.
+     */
+    get overlayContainer(): HTMLElement;
+    /**
+     * Selection-style rectangles covering `range`, in {@link overlayContainer}-
+     * local coordinates — the same geometry the live selection paints. Exposed so
+     * contributions (e.g. persistent comments) can highlight arbitrary ranges and
+     * anchor overlays to them. Recomputes when the measured layout changes.
+     */
+    rangeRects(range: OffsetRange): IObservable<readonly SelectionRect[]>;
     constructor(_model: EditorModel, _options?: EditorViewOptions | undefined);
     /**
      * Mirrors the model's live Ctrl/Cmd state onto the editor root as
@@ -690,11 +1057,33 @@ export declare class EditorView extends Disposable {
      * a plain click, but an active link only opens with the modifier held.
      */
     private _setupModifierTracking;
+    /**
+     * Renders the edit/read-only lock toggle. It flips the model's
+     * {@link EditorModel.readonlyMode}: when locked (read-only) every block stays
+     * in its clean rendered form (no markdown markers revealed) and edits are
+     * ignored, while text selection still works. The control lives in a
+     * zero-height *sticky* host so the lock stays pinned to the top-right corner
+     * of the scroll container as the document scrolls. The current mode is also
+     * mirrored onto the root as `.md-readonly` for any CSS hooks.
+     */
+    private _setupReadonlyToggle;
     focus(): void;
+    /**
+     * Opt-in "own" point→offset resolution (a debug/experimental flag). When
+     * `false` (default), {@link resolveOffsetFromPoint} uses the platform DOM
+     * hit-test (`caretPositionFromPoint`). When `true`, it ignores the DOM
+     * hit-test and snaps the point to the nearest offset purely from the
+     * rendered {@link VisualLineMap} geometry — picking the nearest visual line
+     * by `y`, then the nearest offset on it by `x`. Because a table row's cells
+     * share one horizontal line band, this makes the whole width of a row
+     * resolve into that row (rather than only the cell boxes), with no visible
+     * layout change.
+     */
+    readonly geometricHitTest: ISettableObservable<boolean, void>;
     /**
      * Client coordinates → absolute source offset (any block). Used during
      * drag to keep extending the selection even when the pointer leaves the
-     * original block.
+     * original block. Honours {@link geometricHitTest}.
      */
     resolveOffsetFromPoint(point: Point2D): SourceOffset | undefined;
     /**
@@ -715,6 +1104,15 @@ export declare class EditorView extends Disposable {
      * is not read here, so there is no feedback loop into the render autorun.
      */
     private _publishMeasurements;
+    /**
+     * Paint the diff highlights via the CSS Custom Highlight API: green over the
+     * inserted/changed modified ranges (mapped on the document's own DOM), and
+     * red over each {@link DiffDecorationViewNode}'s deleted ranges (mapped on
+     * the decoration's own subtree). No DOM is mutated, so reconciliation and
+     * editing are unaffected.
+     */
+    private _paintDiff;
+    private _clearDiff;
 }
 
 export declare interface EditorViewOptions extends BlockViewOptions {
@@ -735,6 +1133,14 @@ export declare interface EditorViewOptions extends BlockViewOptions {
      * root ({@link element}) always spans the full available width.
      */
     readonly limitedWidth?: IObservable<number | undefined>;
+    /**
+     * Diff mode only: render every read-only original decoration in active
+     * (source) form, so even whole-block removals expose their markdown markers
+     * as real text. Used by the diff-coverage fixture to verify that every
+     * changed original character is rendered somewhere; off in normal use, where
+     * whole removals show a clean solid band.
+     */
+    readonly diffDecorationsActive?: boolean;
 }
 
 export declare class EmphasisAstNode extends AstNode {
@@ -881,6 +1287,9 @@ export declare interface IClipboardStrategy {
     connect(context: IClipboardContext): IDisposable;
 }
 
+/** A live rendering of a {@link CommentsModel}. Dispose to unmount it. */
+export declare type ICommentsPresenter = IDisposable;
+
 /** The Monarch language definitions the default highlighter wires up. */
 export declare interface IDefaultMonarchGrammars {
     typescript: unknown;
@@ -1353,6 +1762,15 @@ export declare class NativeClipboardStrategy implements IClipboardStrategy {
     connect(context: IClipboardContext): IDisposable;
 }
 
+declare interface NestedItem {
+    readonly kind: 'nested';
+    readonly original: AstNode;
+    readonly originalStart: number;
+    readonly modified: AstNode;
+    readonly modifiedStart: number;
+    readonly children: readonly DiffItem[];
+}
+
 /**
  * Move the cursor one position left or right, skipping over hidden marker
  * ranges in inactive blocks (and inactive items of an active list).
@@ -1483,6 +1901,23 @@ export declare class Rect2D {
     translate(dx: number, dy: number): Rect2D;
 }
 
+declare interface RemovedItem {
+    readonly kind: 'removed';
+    readonly node: AstNode;
+    readonly originalStart: number;
+    readonly deletedLocal: readonly AnnotatedRange[];
+}
+
+declare interface ReplacedItem {
+    readonly kind: 'replaced';
+    readonly original: AstNode;
+    readonly originalStart: number;
+    readonly modified: AstNode;
+    readonly modifiedStart: number;
+    readonly insertedLocal: readonly AnnotatedRange[];
+    readonly deletedLocal: readonly AnnotatedRange[];
+}
+
 export declare const selectAll: SelectionCommand;
 
 export declare function selectBlock(ctx: CursorCommandContext, blockRange: OffsetRange): Selection_2;
@@ -1595,6 +2030,26 @@ export declare interface SnapshotTokens {
 
 export declare type SourceOffset = number;
 
+export declare abstract class StackedCommentsPresenter extends Disposable implements ICommentsPresenter {
+    protected readonly model: CommentsModel;
+    protected readonly view: EditorView;
+    protected readonly context?: CommentsPresenterContext | undefined;
+    private readonly _layer;
+    private readonly _entries;
+    private _order;
+    constructor(model: CommentsModel, view: EditorView, context?: CommentsPresenterContext | undefined);
+    /** Build the card DOM for a comment. Called once per new comment. */
+    protected abstract createWidget(comment: Comment_2): StackWidget;
+    private _reconcile;
+    private _relayout;
+}
+
+/** The minimal widget contract a subclass must produce. */
+export declare interface StackWidget {
+    readonly element: HTMLElement;
+    dispose(): void;
+}
+
 export declare class StrikethroughAstNode extends AstNode {
     readonly openMarker: MarkerAstNode;
     readonly content: readonly (InlineAstNode | GlueAstNode)[];
@@ -1799,6 +2254,13 @@ export declare class Token {
     className: string | undefined);
 }
 
+declare interface UnchangedItem {
+    readonly kind: 'unchanged';
+    /** The modified-side node (identical in content to the original). */
+    readonly node: AstNode;
+    readonly modifiedStart: number;
+}
+
 /**
  * Immutable view of an AST node. Pairs `ast` with its rendered `dom` and a
  * mirror of `ast.children` as ViewNode children. Source offsets are NEVER
@@ -1863,10 +2325,12 @@ export declare class ViewNode extends Disposable {
     /**
      * Map a DOM hit that lands on THIS node's own representation into a source
      * range in this node's local space `[0, ast.length)`. Polymorphic: a text
-     * leaf maps the caret offset 1:1; an element-only node (KaTeX math, `<hr>`,
-     * an image, a hidden marker) has no internal text mapping and snaps to its
-     * start by default — subclasses may override (e.g. to snap to the nearer
-     * edge by x).
+     * leaf maps the caret offset 1:1. For an element hit — an element-only node
+     * (KaTeX math, `<hr>`, an image, a hidden marker) or a wrapper/container
+     * element — the platform reports a child-index offset, not a text caret, so
+     * there is no internal mapping to honour: it snaps to the node's nearer
+     * edge, `offset 0` (the "before" side) → start, any `offset >= 1` (the
+     * "after" side) → end. Subclasses may override for finer control.
      */
     getLocalSourceRange(pos: DomPosition): OffsetRange;
     /**
@@ -1931,8 +2395,9 @@ export declare class VisualLine {
     xAtOffset(offset: SourceOffset): number;
     /**
      * Snap `x` to the nearest offset on this line. If `x` falls inside a
-     * run, the offset is interpolated by character fraction; otherwise it
-     * snaps to the closer edge of the nearest run.
+     * run, the run resolves the offset (exact glyph boundary for text runs,
+     * nearer edge for source-less runs); otherwise it snaps to the closer
+     * edge of the nearest run.
      */
     offsetAtX(x: number): SourceOffset;
 }
@@ -2020,8 +2485,14 @@ export declare class VisualLineMap {
  * When constructed with a {@link VisualRunSource}, `xAtOffset` returns the
  * pixel-exact x of the caret before character `offset` by measuring the
  * prefix `[textNodeStart, textNodeStart + (offset - sourceStart))` with a
- * DOM `Range`. Without a source it falls back to linear interpolation
- * across `rect.width`.
+ * DOM `Range`.
+ *
+ * A source-less run has no per-offset geometry: it either represents an
+ * element-only block (KaTeX math, a mermaid/custom diagram, an image, an
+ * inactive `<hr>`) whose box does not correspond to source offsets, or a
+ * hand-built run in a test. Either way it maps between offsets and x by
+ * snapping to the nearer edge of {@link rect} rather than fabricating
+ * interior positions.
  */
 export declare class VisualRun {
     readonly sourceRange: OffsetRange;
@@ -2039,14 +2510,15 @@ export declare class VisualRun {
 
 /**
  * The DOM source of a {@link VisualRun}. When set, `xAtOffset` and
- * `offsetAtX` measure exact glyph positions via `Range.getBoundingClientRect`
- * instead of linear interpolation across the run's rect. This matters for
- * proportional fonts where character widths differ a lot (e.g. `m` vs `i`)
- * and a caret placed by interpolation lands several pixels inside the
- * wrong character.
+ * `offsetAtX` measure exact glyph positions via `Range.getBoundingClientRect`.
+ * This matters for proportional fonts where character widths differ a lot
+ * (e.g. `m` vs `i`): a caret placed by anything coarser than real glyph
+ * measurement lands several pixels inside the wrong character.
  *
- * Hand-built runs (tests) omit this; their `xAtOffset` falls back to
- * linear interpolation.
+ * A run without a source has no per-offset geometry, so it maps between
+ * offsets and x by snapping to the nearer run edge. Real text runs always
+ * carry a source; source-less runs are element-only blocks (see
+ * {@link _appendElementBlockRun}) and hand-built runs in tests.
  */
 declare interface VisualRunSource {
     readonly textNode: Text;
@@ -2054,4 +2526,12 @@ declare interface VisualRunSource {
     readonly textNodeStart: number;
 }
 
+export declare class VscodeStackedCommentsView extends StackedCommentsPresenter {
+    protected createWidget(comment: Comment_2): StackWidget;
+}
+
+export declare class VsCodeV2CommentsView extends StackedCommentsPresenter {
+    protected createWidget(comment: Comment_2): StackWidget;
+}
+
 export { }