@vscode/markdown-editor 0.0.2-2 → 0.0.2-21

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;
+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 | UnhandledBlockAstNode;
 
-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;
@@ -31,7 +48,7 @@ export declare abstract class AstNode {
      * instances — keeping this O(children), not O(subtree). Leaves have no
      * children, so {@link _localEquals} is their whole comparison.
      */
-    structurallyEqual(other: AstNode): boolean;
+    equalsShallow(other: AstNode): boolean;
     /** Compares only this node's own scalar fields (kind/length already match). */
     protected _localEquals(_other: this): boolean;
     /**
@@ -54,7 +71,40 @@ declare interface AstVisualizationNode {
     children?: AstVisualizationNode[];
 }
 
-export declare type BlockAstNode = HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | ThematicBreakAstNode | BlockQuoteAstNode | ListAstNode | TableAstNode;
+/**
+ * Strategy for hosts that never deliver native clipboard events to the editor
+ * — most importantly VS Code webviews, whose preload calls `preventDefault()`
+ * on the Ctrl/Cmd+C/X/V keydowns, so no `copy`/`cut`/`paste` event is ever
+ * dispatched. Here the keystrokes are the only signal, so this strategy
+ * listens for them directly and drives the async {@link Clipboard} API
+ * (`navigator.clipboard`), which webviews are granted.
+ *
+ * Cut deletes synchronously once the text is captured; the clipboard write is
+ * fire-and-forget. Paste must wait for the async read before inserting.
+ */
+export declare class AsyncClipboardStrategy implements IClipboardStrategy {
+    private readonly _clipboard;
+    constructor(_clipboard?: Clipboard);
+    connect(context: IClipboardContext): IDisposable;
+}
+
+export declare type BlockAstNode = HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | ThematicBreakAstNode | BlockQuoteAstNode | ListAstNode | TableAstNode | UnhandledBlockAstNode;
+
+/**
+ * A block-level node. Every block may carry a {@link leadingTrivia} glue — the
+ * whitespace that precedes it on its own line (a nested list's indentation, the
+ * leading space of a continued paragraph). It is owned by the block it precedes
+ * (not the one it trails), so the view reveals it exactly when *this* block is
+ * active, and it tiles at the block's front: {@link children} prepends it to the
+ * block's own content while `content` stays the block's real payload.
+ */
+declare abstract class BlockAstNodeBase extends AstNode {
+    abstract readonly leadingTrivia?: GlueAstNode;
+    /** This block with its leading trivia replaced — re-homes a leading glue onto it. */
+    abstract withLeadingTrivia(trivia: GlueAstNode | undefined): BlockAstNode;
+    /** Prepends {@link leadingTrivia}, if any, ahead of the block's own children. */
+    protected _withLeading(own: readonly AstNode[]): readonly AstNode[];
+}
 
 /**
  * One block's place in the rendered document.
@@ -79,13 +129,15 @@ export declare interface BlockMeasurement {
     readonly viewNode: ViewNode | undefined;
 }
 
-export declare class BlockQuoteAstNode extends AstNode {
+export declare class BlockQuoteAstNode extends BlockAstNodeBase {
     readonly content: readonly (MarkerAstNode | BlockAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "blockQuote";
-    constructor(content: readonly (MarkerAstNode | BlockAstNode | GlueAstNode)[]);
+    constructor(content: readonly (MarkerAstNode | BlockAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get blocks(): readonly BlockAstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): BlockQuoteAstNode;
 }
 
 declare class BlockQuoteViewData {
@@ -95,7 +147,7 @@ declare class BlockQuoteViewData {
     constructor(ast: BlockQuoteAstNode, content: readonly AnyViewData[]);
 }
 
-declare type BlockViewData = HeadingViewData | ParagraphViewData | CodeBlockViewData | MathBlockViewData | ThematicBreakViewData | BlockQuoteViewData | ListViewData | TableViewData;
+declare type BlockViewData = HeadingViewData | ParagraphViewData | CodeBlockViewData | MathBlockViewData | ThematicBreakViewData | BlockQuoteViewData | ListViewData | TableViewData | UnhandledBlockViewData;
 
 /**
  * Base view node for everything the editor renders, generic over the
@@ -116,6 +168,17 @@ export declare class BlockViewNode<T extends AnyViewData = AnyViewData> extends
     constructor(data: T, dom: globalThis.Node, children: readonly ViewNode[]);
     get block(): BlockAstNode;
     get element(): HTMLElement;
+    /**
+     * The horizontal scroll viewport for selection/caret clipping
+     * ({@link blockViewportClip}). For most blocks the scroller *is*
+     * {@link element} — a code / math / unhandled block's `element` is the very
+     * `overflow-x: auto` box that scrolls. A table is the exception: its
+     * `element` stays the inner `<table>` (so the active/markers classes and
+     * `.md-table` theme styling are unaffected), but the box that actually
+     * scrolls is the wrapping `.md-table-wrapper`, so {@link TableViewNode}
+     * overrides this to return that wrapper.
+     */
+    get scrollElement(): HTMLElement;
     /**
      * Whether this already-built node can stand in for `data` unchanged. The
      * builder preserves view-data identity for any subtree whose ast and
@@ -139,9 +202,10 @@ export declare interface BlockViewOptions {
     /**
      * Opens a link's URL. Called when the user activates a link: a plain click
      * while the link's block is inactive (rendered), or a Ctrl/Cmd+click while it
-     * is active (source shown). Defaults to `window.open(url, '_blank')`.
+     * is active (source shown). Return `false` to use the anchor's native
+     * navigation behavior.
      */
-    readonly onOpenLink?: (url: string, event: MouseEvent) => void;
+    readonly onOpenLink?: (url: string, event: MouseEvent) => false | void;
     /**
      * Colours fenced code blocks. When set, a code block's content is rendered
      * as a sequence of token spans instead of one plain text node. This is the
@@ -161,15 +225,32 @@ export declare interface BlockViewOptions {
      * `katexEditableIdentifiers.ts`).
      */
     readonly renderMath?: (request: MathRenderRequest) => MathRendering | undefined;
+    /**
+     * Pluggable factory for an in-place, interactive editor that replaces the
+     * *rendered* (inactive) form of a fenced code block — see
+     * {@link IEmbeddedCodeEditor}. When it returns an editor for the block's
+     * language, that editor's element is mounted instead of the highlighted
+     * code, and content flows both ways as string edits. Returning `undefined`
+     * falls back to the default rendering. EXPERIMENTAL.
+     */
+    readonly embeddedCodeEditorFactory?: IEmbeddedCodeEditorFactory;
+    /**
+     * Called when an {@link IEmbeddedCodeEditor} edits its content. `contentEdit`
+     * is in the block's *content* coordinates; the host translates it to a
+     * document edit (via {@link CodeBlockAstNode.codeOffset} and the block's
+     * offset) and applies it to the model.
+     */
+    readonly onEmbeddedCodeEditorEdit?: (block: CodeBlockAstNode, contentEdit: StringEdit) => void;
 }
 
-export declare class CodeBlockAstNode extends AstNode {
+export declare class CodeBlockAstNode extends BlockAstNodeBase {
     readonly language: string;
     readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "codeBlock";
     private _previous?;
     private _contentEdit?;
-    constructor(language: string, content: readonly (MarkerAstNode | GlueAstNode)[]);
+    constructor(language: string, content: readonly (MarkerAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get openFence(): MarkerAstNode | undefined;
     get closeFence(): MarkerAstNode | undefined;
@@ -177,6 +258,7 @@ export declare class CodeBlockAstNode extends AstNode {
     /** Relative start offset of the {@link code} marker within this block. */
     get codeOffset(): number;
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): CodeBlockAstNode;
     protected _localEquals(o: this): boolean;
     /**
      * A copy of this block carrying an incremental link to `previous`:
@@ -234,10 +316,241 @@ export declare class CodeBlockViewNode extends BlockViewNode<CodeBlockViewData>
      * its predecessor's subscription explicitly.
      */
     private _snapshotSub;
+    /**
+     * An in-place interactive editor (e.g. an iframe) mounted instead of the
+     * rendered code. Like {@link _session} it is adopted from `previous` across
+     * rebuilds so the underlying editor keeps its state, and must be disposed
+     * manually (a node reused as `previous` is never {@link dispose}d).
+     */
+    private _embeddedEditor;
     constructor(data: CodeBlockViewData, options: BlockViewOptions | undefined, previous: ViewNode | undefined);
     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 after the textarea changes size. */
+    readonly onDidChangeSize?: () => void;
+    /**
+     * 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 logical caret geometry remains available for anchoring in
+ *    read-only mode even though the painted caret is hidden. While the box has
+ *    focus, `.md-comment-active` also suppresses the painted caret in any mode.
+ */
+export declare class CommentModeController extends Disposable {
+    private readonly _model;
+    private readonly _view;
+    private readonly _options?;
+    private readonly _widget;
+    private readonly _gap;
+    private _visible;
+    private _anchorX;
+    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;
+    constructor(_model: EditorModel, _view: EditorView, _options?: CommentModeControllerOptions | undefined);
+    private _update;
+    private _show;
+    private _layoutHorizontally;
+    /** 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
@@ -301,6 +614,19 @@ export declare class CursorView extends Disposable {
 export declare interface CursorViewOptions {
     readonly offset: IObservable<SourceOffset | undefined>;
     readonly visualLineMap: IObservable<VisualLineMap>;
+    /**
+     * The mounted blocks, used to hide the caret when it sits at an offset that
+     * has been scrolled out of its (horizontally scrolling) block's viewport —
+     * matching how the selection is clipped there.
+     */
+    readonly blocks?: IObservable<readonly SelectionBlock[]>;
+    /**
+     * When set, the caret is drawn over the transient empty paragraph instead
+     * of at {@link offset} — its rect (in client coordinates) comes straight
+     * from that synthetic element's geometry, since it has no visual-line-map
+     * entry. Takes priority over the normal offset-based placement.
+     */
+    readonly pendingCaretRect?: IObservable<Rect2D | undefined>;
 }
 
 export declare class CursorViewRendering {
@@ -322,6 +648,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";
@@ -346,13 +740,21 @@ declare interface DocumentBlockViewData {
     readonly view: BlockViewData;
 }
 
-/** A mounted document child: a block or a run of inter-block glue. */
+/** 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: a neighbouring block is active. */
+    /** For a block: selection reaches it. For glue: always false (unowned, hidden). */
     readonly isActive: boolean;
-    readonly view: BlockViewData | GlueViewData;
-    readonly kind: 'block' | 'glue';
+    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';
 }
 
 /**
@@ -408,6 +810,8 @@ declare class DocumentViewData {
  */
 export declare class DocumentViewNode extends ViewNode {
     readonly blocks: readonly DocumentBlock[];
+    /** The transient empty-paragraph element, when one is armed. */
+    readonly pendingElement?: HTMLElement | undefined;
     static create(viewData: DocumentViewData, options: BlockViewOptions | undefined, previous: DocumentViewNode | undefined): DocumentViewNode;
     private constructor();
     /** The stable content element this document mounts its children into. */
@@ -437,14 +841,21 @@ export declare type EditCommand = (ctx: CursorCommandContext) => {
  *
  * Owns the only non-derivable controller state:
  * - `_desiredColumn` — sticky column for up/down navigation
+ * - `_clickCount` / `_lastPointerDown` — multi-click detection for pointer
+ *   input, since `pointerdown` events (unlike `mousedown`) don't populate
+ *   `detail` with a click count.
  */
 export declare class EditorController extends Disposable {
     private readonly _model;
     private readonly _view;
     private _desiredColumn;
-    constructor(_model: EditorModel, _view: EditorView);
+    /** Running click count for the current multi-click sequence (1, 2, 3, …). */
+    private _clickCount;
+    /** Timestamp and position of the previous pointer-down, for multi-click detection. */
+    private _lastPointerDown;
+    constructor(_model: EditorModel, _view: EditorView, options?: EditorControllerOptions);
     private readonly _handleTextUpdate;
-    private readonly _handleMouseDown;
+    private readonly _handlePointerDown;
     private _makeCursorContext;
     private _makeVisualCursorContext;
     private _executeCursorCommand;
@@ -454,11 +865,25 @@ export declare class EditorController extends Disposable {
     cursorDown(extend?: boolean): void;
     /** Move the cursor up one visual line (Arrow Up). */
     cursorUp(extend?: boolean): void;
-    private readonly _handleCopy;
-    private readonly _handleCut;
-    private readonly _handlePaste;
     private _selectedText;
+    private readonly _updateModifierState;
+    private readonly _clearModifierState;
     private readonly _handleKeyDown;
+    /**
+     * Context-aware Enter: splits / line-breaks via {@link insertSmartEnter}, or
+     * arms a transient empty paragraph when at the end of a paragraph.
+     */
+    private _smartEnter;
+}
+
+/** Options for an {@link EditorController}. */
+export declare interface EditorControllerOptions {
+    /**
+     * How copy/cut/paste is handled. Defaults to {@link NativeClipboardStrategy},
+     * which reads the browser's native clipboard events — pass a different
+     * strategy (e.g. `AsyncClipboardStrategy`) in hosts that swallow them.
+     */
+    readonly clipboardStrategy?: IClipboardStrategy;
 }
 
 export declare class EditorModel {
@@ -471,11 +896,43 @@ 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).
      */
     readonly selection: ISettableObservable<Selection_2 | undefined, void>;
+    /**
+     * Whether a Ctrl/Cmd modifier is currently held. Set by the controller from
+     * live keyboard state; the view reads it to show the link-open affordance
+     * (underline + pointer cursor) only while a Ctrl/Cmd+click would open a link
+     * whose block is active.
+     */
+    readonly ctrlOrMetaDown: ISettableObservable<boolean, void>;
+    /**
+     * Whether a pointer-driven selection drag is currently in progress. Set by
+     * the controller between the pointer-down that starts the drag and the
+     * pointer-up/cancel that ends it. Contributions read it to defer UI that
+     * would otherwise flicker mid-drag (e.g. the comment input box appears only
+     * once the drag ends).
+     */
+    readonly isSelecting: ISettableObservable<boolean, void>;
+    /**
+     * Gutter markers (source-control style change indicators) painted in the
+     * left gutter. Each entry maps a source {@link OffsetRange} to a change kind
+     * — see {@link GutterMarker}. Purely decorative: markers never affect the
+     * parsed {@link document}, selection, or layout. Empty by default.
+     */
+    readonly gutterMarkers: ISettableObservable<readonly GutterMarker[], void>;
     /**
      * Forces the rendered active-block set. `undefined` (the default)
      * derives the set from the current selection range (see
@@ -484,6 +941,13 @@ export declare class EditorModel {
      * collapsed/inactive rendering.
      */
     readonly activeBlocksOverride: ISettableObservable<readonly BlockAstNode[] | typeof NO_ACTIVE_BLOCKS | undefined, void>;
+    /**
+     * The transient empty-paragraph editing state, or `undefined` when none is
+     * armed. See {@link PendingParagraph}. This is *not* document data — it is
+     * cleared by any source edit and lives only between the Enter that armed it
+     * and the next keystroke.
+     */
+    readonly pendingParagraph: ISettableObservable<PendingParagraph | undefined, void>;
     readonly cursorOffset: IObservableWithChange<number | undefined, void>;
     /**
      * The parsed document. Threads the previous document into the parser so
@@ -507,6 +971,43 @@ 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
+     * applied — the blank line exists only in the view until it is materialized.
+     */
+    armPendingParagraph(req: {
+        anchorBlock: BlockAstNode;
+        replaceRange: OffsetRange;
+        atEof: boolean;
+    }): void;
+    /** Discard the pending paragraph (if any) without touching the source. */
+    cancelPendingParagraph(): void;
+    /**
+     * Turn the pending paragraph into real source: rewrite its gap so the typed
+     * `text` becomes its own paragraph, separated from its neighbours by blank
+     * lines, and place the caret after the inserted text.
+     */
+    materializePendingParagraph(text: string): void;
     applyEdit(edit: StringEdit): void;
     applyEditForSelection(edit: StringEdit): void;
 }
@@ -540,8 +1041,18 @@ export declare class EditorView extends Disposable {
     readonly element: HTMLElement;
     readonly editContext: EditContext;
     readonly measuredLayout: MeasuredLayoutModel;
+    /**
+     * Inner container that holds the rendered document and the cursor/selection
+     * overlays. The outer {@link element} spans the full width; this container
+     * is what limited-width mode caps and centers, so the overlays (which anchor
+     * to their parent's box) stay aligned with the content.
+     */
+    private readonly _contentContainer;
     private readonly _cursorView;
     private readonly _selectionView;
+    private readonly _gutterMarkersView;
+    private readonly _diffHighlightsView;
+    private _readonlyToggleButton;
     /**
      * The mounted block sequence, in source order. Rebuilt (not mutated) each
      * frame by {@link DocumentViewNode.create}; the view just swaps one
@@ -561,20 +1072,90 @@ export declare class EditorView extends Disposable {
     /** The current view-data tree (AST overlaid with selection flags), for debugging. */
     private readonly _viewData;
     get viewData(): IObservable<DocumentViewData | undefined>;
+    /**
+     * Caret rect (client coords) for the transient empty paragraph, or
+     * `undefined` when none is armed. Set each frame from the synthetic
+     * paragraph element's geometry and fed to the {@link CursorView}, which has
+     * no visual-line-map entry to place the caret from otherwise.
+     */
+    private readonly _pendingCaretRect;
     /**
      * The block cache projected for views (selection painting) that need to
      * react to mount/unmount. Derived from {@link _document}, so it stays in
      * 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
+     * `.md-mod-down` so CSS can show the link-open underline and pointer cursor
+     * only while a click would actually open the link: an inactive link opens on
+     * a plain click, but an active link only opens with the modifier held.
+     */
+    private _setupModifierTracking;
+    /**
+     * Renders the edit/read-only mode 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 inside the centered content container, so the
+     * lock follows the content's right edge and remains pinned as the document
+     * scrolls. The current mode is also mirrored onto the root as `.md-readonly`
+     * for any CSS hooks.
+     */
+    private _setupReadonlyToggle;
+    /** Draws attention to the mode toggle after text input is attempted while locked. */
+    showReadonlyEditingAttempt(): void;
     focus(): void;
+    /**
+     * Own point→offset resolution. When `true` (the default),
+     * {@link resolveOffsetFromPoint} ignores the platform DOM hit-test
+     * (`caretPositionFromPoint`) 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. It also lets a drag keep extending toward off-viewport points
+     * (e.g. the pointer leaving the window), which the platform hit-test cannot
+     * resolve. Set to `false` to fall back to the platform DOM hit-test.
+     */
+    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;
+    /**
+     * Resolve table-cell hits that have no measurable text run. Empty cells map
+     * from their own box instead of snapping to a neighboring cell; element-only
+     * content (for example an inactive image) maps through the hit element's view
+     * node. Text-bearing cells keep the normal pixel-precise line-map/DOM path.
+     */
+    private _resolveTableCellOffset;
     /**
      * Whether a client point falls on the rendered document content, as
      * opposed to the surrounding editor padding (the green area). Uses DOM
@@ -593,6 +1174,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 {
@@ -603,6 +1193,30 @@ export declare interface EditorViewOptions extends BlockViewOptions {
      * only) unless a theme class is supplied.
      */
     readonly classNames?: readonly string[];
+    /**
+     * Whether to render the sticky edit/read-only toggle at the top-right edge
+     * of the content. Defaults to `true`; set to `false` to omit it (e.g. in
+     * fixtures that focus on selection rendering).
+     */
+    readonly showReadonlyToggle?: boolean;
+    /**
+     * Controls "limited width mode". The observable yields the maximum content
+     * width in pixels, or `undefined` to let the content fill the available
+     * width. When the option is omitted, the width is capped at
+     * {@link DEFAULT_LIMITED_WIDTH}px (limited mode is on by default).
+     *
+     * The cap and centering apply to an inner content container; the editor
+     * 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 {
@@ -670,14 +1284,39 @@ declare class GlueViewData {
     decorateNewline: boolean);
 }
 
-export declare class HeadingAstNode extends AstNode {
+/**
+ * A single gutter marker: a source {@link OffsetRange} tagged with a
+ * {@link GutterMarkerType}. The view resolves the range to the visual lines it
+ * covers and paints a bar (or, for `deleted`, a wedge at the range position) in
+ * the left gutter.
+ *
+ * A `deleted` marker is normally an empty range (`range.isEmpty`) sitting at the
+ * boundary where the removed text used to be — there is nothing left to span,
+ * so it is drawn as a caret between lines rather than a bar.
+ */
+export declare interface GutterMarker {
+    readonly range: OffsetRange;
+    readonly type: GutterMarkerType;
+}
+
+/**
+ * The kind of change a gutter marker represents, mirroring the three states a
+ * source-control diff distinguishes (the git change markers in the editor
+ * gutter): a freshly inserted region, an edited region, and a point where
+ * content was removed.
+ */
+export declare type GutterMarkerType = 'added' | 'modified' | 'deleted';
+
+export declare class HeadingAstNode extends BlockAstNodeBase {
     readonly level: 1 | 2 | 3 | 4 | 5 | 6;
     readonly marker: MarkerAstNode;
     readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "heading";
-    constructor(level: 1 | 2 | 3 | 4 | 5 | 6, marker: MarkerAstNode, content: readonly (InlineAstNode | GlueAstNode)[]);
+    constructor(level: 1 | 2 | 3 | 4 | 5 | 6, marker: MarkerAstNode, content: readonly (InlineAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): HeadingAstNode;
     protected _localEquals(o: this): boolean;
 }
 
@@ -688,6 +1327,45 @@ declare class HeadingViewData {
     constructor(ast: HeadingAstNode, content: readonly AnyViewData[]);
 }
 
+/**
+ * The editor operations a clipboard strategy drives. The strategy never
+ * touches the model or the DOM directly — it asks through this seam, so the
+ * same strategy works regardless of how the editor is wired up.
+ */
+export declare interface IClipboardContext {
+    /** The element that owns focus and receives clipboard/keyboard events. */
+    readonly element: HTMLElement;
+    /** The selected source text, or `undefined` when the selection is empty. */
+    getSelectedText(): string | undefined;
+    /** Delete the current selection (the cut half of cut). */
+    deleteSelection(): void;
+    /** Insert text at the caret, replacing any selection (the paste action). */
+    insertText(text: string): void;
+}
+
+/**
+ * How copy/cut/paste intent reaches the editor. Host environments deliver it
+ * differently, so the controller owns no clipboard logic itself — it
+ * {@link connect}s a strategy and lets it install whatever listeners it needs.
+ *
+ * Two implementations ship:
+ * - {@link NativeClipboardStrategy} (default) reads the browser's native
+ *   `copy`/`cut`/`paste` events and their synchronous `clipboardData`.
+ * - {@link AsyncClipboardStrategy} drives the async `navigator.clipboard` API
+ *   from Ctrl/Cmd+C/X/V keystrokes, for hosts (e.g. VS Code webviews) that
+ *   swallow the native clipboard events before they reach the editor.
+ */
+export declare interface IClipboardStrategy {
+    /**
+     * Wire up clipboard handling against `context`. The returned disposable
+     * tears down every listener the strategy installed.
+     */
+    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;
@@ -699,6 +1377,55 @@ export declare interface IDefaultMonarchGrammars {
     shell: unknown;
 }
 
+/**
+ * A live editor embedded in place of a fenced code block's *rendered* form.
+ *
+ * This is the internal seam between the block view and a concrete embedded
+ * editor (e.g. an `<iframe>` speaking the web-editor protocol). The block view
+ * only speaks string edits: it pushes the block's content down via
+ * {@link setContent} and receives the editor's own changes back through
+ * {@link onEdit} (set by the block view on each (re)construction, so it always
+ * routes to the current AST node). The concrete implementation owns its DOM,
+ * transport, and lifecycle.
+ *
+ * A single instance is adopted across re-renders (like the highlighter session)
+ * so the underlying editor keeps its state across edits — see
+ * {@link CodeBlockViewNode}.
+ */
+declare interface IEmbeddedCodeEditor {
+    /** The element mounted as the block's rendered form. */
+    readonly element: HTMLElement;
+    /**
+     * Document → editor. The block's content changed (from any source). Must be
+     * idempotent: pushing the content the editor already holds is a no-op, which
+     * is how edits the editor itself originated are prevented from echoing back.
+     */
+    setContent(content: string): void;
+    /**
+     * Optional synchronous height (px) to reserve for `content` *before* the
+     * editor has laid out. Return `undefined` to let the editor size itself
+     * (the implementation may report its real height later). Lets a registration
+     * avoid a layout jump when it can cheaply estimate the size from content.
+     */
+    estimateHeight?(content: string): number | undefined;
+    /**
+     * Editor → document. Set by the block view on every (re)construction to
+     * route the editor's own edits, expressed in the block's *content*
+     * coordinates, to the current AST node.
+     */
+    onEdit?: (edit: StringEdit) => void;
+    dispose(): void;
+}
+
+/** Creates an {@link IEmbeddedCodeEditor} for a fenced block, or opts out. */
+declare interface IEmbeddedCodeEditorFactory {
+    /**
+     * Return an editor for a fenced block of `language`, or `undefined` to fall
+     * back to the default (highlighting / {@link BlockViewOptions.renderCustomCodeBlock}).
+     */
+    create(language: string, initialContent: string): IEmbeddedCodeEditor | undefined;
+}
+
 export declare class ImageAstNode extends AstNode {
     readonly alt: string;
     readonly url: string;
@@ -782,6 +1509,21 @@ export declare const insertLineBreak: EditCommand;
 
 export declare const insertParagraph: EditCommand;
 
+/**
+ * Context-aware Enter. The behaviour is chosen from the active block:
+ *  - paragraph / heading / thematic break — the "rich text" thing: at the
+ *    block's end arm a transient empty paragraph (see {@link SmartEnterResult});
+ *    elsewhere split into two paragraphs (`\n\n`).
+ *  - code block — insert a newline that preserves the current line's indentation,
+ *    staying inside the fence.
+ *  - block quote — continue the quote (`\n> `); an empty quote line exits it.
+ *  - list — continue the list with the next marker (incrementing ordered
+ *    numbers, re-emitting task checkboxes); an empty item exits the list.
+ * A non-collapsed selection, or any other block, falls back to a plain soft line
+ * break, preserving today's behaviour.
+ */
+export declare const insertSmartEnter: (ctx: CursorCommandContext) => SmartEnterResult;
+
 export declare function insertText(text: string): EditCommand;
 
 /**
@@ -886,14 +1628,16 @@ declare class LinkViewData {
     constructor(ast: LinkAstNode, content: readonly AnyViewData[]);
 }
 
-export declare class ListAstNode extends AstNode {
+export declare class ListAstNode extends BlockAstNodeBase {
     readonly ordered: boolean;
     readonly content: readonly (ListItemAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "list";
-    constructor(ordered: boolean, content: readonly (ListItemAstNode | GlueAstNode)[]);
+    constructor(ordered: boolean, content: readonly (ListItemAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get items(): readonly ListItemAstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): ListAstNode;
     protected _localEquals(o: this): boolean;
 }
 
@@ -907,6 +1651,7 @@ export declare class ListItemAstNode extends AstNode {
     get children(): readonly AstNode[];
     get blocks(): readonly BlockAstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): ListItemAstNode;
     protected _localEquals(o: this): boolean;
 }
 
@@ -960,13 +1705,15 @@ declare class MarkerViewData {
     constructor(ast: MarkerAstNode, visible: boolean);
 }
 
-export declare class MathBlockAstNode extends AstNode {
+export declare class MathBlockAstNode extends BlockAstNodeBase {
     readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "mathBlock";
-    constructor(content: readonly (MarkerAstNode | GlueAstNode)[]);
+    constructor(content: readonly (MarkerAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get code(): MarkerAstNode | undefined;
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): MathBlockAstNode;
 }
 
 declare class MathBlockViewData {
@@ -1129,6 +1876,26 @@ export declare class MonacoSyntaxHighlighter implements ISyntaxHighlighter {
     private _tokenizerFor;
 }
 
+/**
+ * Default strategy: handle the browser's native `copy`/`cut`/`paste` events,
+ * reading and writing the synchronous {@link ClipboardEvent.clipboardData}.
+ * This is the standard rich-editor approach and works wherever the browser
+ * actually dispatches those events to the focused element (e.g. a standalone
+ * web page).
+ */
+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).
@@ -1164,12 +1931,14 @@ export declare class OffsetRange {
     toString(): string;
 }
 
-export declare class ParagraphAstNode extends AstNode {
+export declare class ParagraphAstNode extends BlockAstNodeBase {
     readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "paragraph";
-    constructor(content: readonly (InlineAstNode | GlueAstNode)[]);
+    constructor(content: readonly (InlineAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): ParagraphAstNode;
 }
 
 declare class ParagraphViewData {
@@ -1179,6 +1948,45 @@ declare class ParagraphViewData {
     constructor(ast: ParagraphAstNode, content: readonly AnyViewData[]);
 }
 
+/**
+ * A *transient* editing state: the empty paragraph the user conjured by
+ * pressing Enter at the end of a paragraph. Markdown has no empty-paragraph
+ * node, so this never lives in {@link EditorModel.sourceText} or the parsed
+ * {@link EditorModel.document} — it is pure edit intent that the view renders
+ * as a synthetic blank line and that the controller either *materializes* (the
+ * user types) or *cancels* (the user navigates away / backspaces).
+ */
+declare interface PendingParagraph {
+    /** The paragraph the blank line is rendered directly after. */
+    readonly anchorBlock: BlockAstNode;
+    /**
+     * Source region rewritten when the pending paragraph is materialized — the
+     * gap between {@link anchorBlock}'s text and whatever follows it.
+     */
+    readonly replaceRange: OffsetRange;
+    /** Whether {@link replaceRange} ends at the end of the document. */
+    readonly atEof: boolean;
+    /**
+     * A throwaway AST node that exists only to give the synthetic view child a
+     * stable identity across render frames (the view pairs nodes by `ast.id`).
+     * It is never part of {@link document}.
+     */
+    readonly syntheticAst: ParagraphAstNode;
+}
+
+/**
+ * View-data for the transient empty paragraph (see `PendingParagraph` in the
+ * model). It carries only the throwaway {@link ParagraphAstNode} that gives the
+ * rendered blank line a stable identity across frames; it has no content and is
+ * never measured or part of the selection geometry — the caret is positioned
+ * over it via a dedicated rect, not via the visual-line map.
+ */
+declare class PendingParagraphViewData {
+    readonly ast: ParagraphAstNode;
+    readonly kind = "pendingParagraph";
+    constructor(ast: ParagraphAstNode);
+}
+
 /**
  * Immutable point in 2D space, in CSS-pixel client coordinates.
  */
@@ -1218,6 +2026,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;
@@ -1245,6 +2070,15 @@ export declare interface SelectionBlock {
     readonly absoluteStart: number;
     readonly viewNode: ViewNode;
     readonly element: HTMLElement;
+    /**
+     * The block's horizontal scroll viewport. Equal to {@link element} for every
+     * block whose element is itself the `overflow-x: auto` scroller (code, math,
+     * unhandled), but the wrapping `.md-table-wrapper` for a table, whose
+     * {@link element} is the content-sized inner `<table>`. Only
+     * {@link blockViewportClip} needs the scroll box; connector/rect geometry
+     * still uses {@link element}.
+     */
+    readonly scrollElement: HTMLElement;
 }
 
 export declare type SelectionCommand = (ctx: CursorCommandContext, offset: SourceOffset) => Selection_2;
@@ -1296,6 +2130,25 @@ export declare class SelectionViewRendering {
 
 export declare const selectWord: SelectionCommand;
 
+/**
+ * The outcome of {@link insertSmartEnter}: either a concrete source edit (the
+ * ordinary cases), or a request to arm a transient empty paragraph (Enter at
+ * the very end of a paragraph), which the controller turns into
+ * {@link EditorModel.armPendingParagraph} rather than a source edit. Modelling
+ * the empty paragraph as state instead of source keeps the document valid
+ * Markdown — which has no empty-paragraph node — until the user actually types.
+ */
+export declare type SmartEnterResult = {
+    readonly kind: 'edit';
+    readonly edit: StringEdit;
+    readonly selection: Selection_2;
+} | {
+    readonly kind: 'pending';
+    readonly anchorBlock: BlockAstNode;
+    readonly replaceRange: OffsetRange;
+    readonly atEof: boolean;
+};
+
 /**
  * A run of {@link Token}s together with the exact {@link OffsetRange} they
  * cover.
@@ -1311,6 +2164,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)[];
@@ -1381,16 +2254,18 @@ declare class StrongViewData {
     constructor(ast: StrongAstNode, content: readonly AnyViewData[]);
 }
 
-export declare class TableAstNode extends AstNode {
+export declare class TableAstNode extends BlockAstNodeBase {
     readonly content: readonly (TableRowAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "table";
-    constructor(content: readonly (TableRowAstNode | GlueAstNode)[]);
+    constructor(content: readonly (TableRowAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     private get _rows();
     get headerRow(): TableRowAstNode | undefined;
     get delimiterRow(): TableRowAstNode | undefined;
     get bodyRows(): readonly TableRowAstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): TableAstNode;
 }
 
 export declare class TableCellAstNode extends AstNode {
@@ -1472,13 +2347,15 @@ declare class TextViewData {
     constructor(ast: TextAstNode, showWhitespace: boolean, leftWordBoundary?: boolean, rightWordBoundary?: boolean);
 }
 
-export declare class ThematicBreakAstNode extends AstNode {
+export declare class ThematicBreakAstNode extends BlockAstNodeBase {
     readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "thematicBreak";
-    constructor(content: readonly (MarkerAstNode | GlueAstNode)[]);
+    constructor(content: readonly (MarkerAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get marker(): MarkerAstNode | undefined;
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): ThematicBreakAstNode;
 }
 
 declare class ThematicBreakViewData {
@@ -1511,6 +2388,47 @@ 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;
+}
+
+/**
+ * A block whose token type the parser does not understand (a setext heading, a
+ * frontmatter fence, any future/extension construct). Rather than dropping the
+ * span — which would demote its text to invisible glue — the parser captures the
+ * whole source range verbatim as a single {@link MarkerAstNode} of kind
+ * `content` and records the originating micromark {@link tokenType}, so the view
+ * can render it as raw, editable text with an "unhandled" affordance. Offsets
+ * stay sound: `content` tiles the block's full source span exactly.
+ */
+declare class UnhandledBlockAstNode extends BlockAstNodeBase {
+    readonly tokenType: string;
+    readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
+    readonly kind = "unhandledBlock";
+    constructor(tokenType: string, content: readonly (MarkerAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
+    get children(): readonly AstNode[];
+    get code(): MarkerAstNode | undefined;
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): UnhandledBlockAstNode;
+    protected _localEquals(o: this): boolean;
+}
+
+/**
+ * View-data for an {@link UnhandledBlockAstNode}. It has no active/inactive
+ * split — the raw source *is* both the source and the rendered form — so it
+ * carries no `showMarkup` flag; the renderer always shows the verbatim text.
+ */
+declare class UnhandledBlockViewData {
+    readonly ast: UnhandledBlockAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "unhandledBlock";
+    constructor(ast: UnhandledBlockAstNode, content: readonly AnyViewData[]);
+}
+
 /**
  * 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
@@ -1575,10 +2493,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;
     /**
@@ -1635,16 +2555,29 @@ export declare class VisualLine {
      */
     sourceDistanceTo(offset: SourceOffset): number;
     /**
-     * x of the caret position before `offset` on this line. When `offset`
-     * is past all runs (trailing whitespace / blank line), returns the
-     * right edge of the last run; when before all runs, returns the left
-     * edge of the first run.
+     * x of the caret position before `offset` on this line.
+     *
+     * The runs tile the source but are stored in paint order, not sorted by
+     * source offset (hidden-marker runs are appended last). So this scans all
+     * runs rather than assuming any ordering:
+     *
+     *  - If some run *covers* `offset`, its own geometry places the caret
+     *    (exact glyph boundary for text runs). In the active, markers-visible
+     *    form every offset is covered, so this branch keeps distinct offsets
+     *    distinct.
+     *  - Otherwise `offset` sits in a gap — a hidden inline marker such as the
+     *    `**` of `**bold**`, or before/after the painted text. It snaps to the
+     *    seam between the source-nearest runs on either side: the right edge of
+     *    the closest run ending at/before `offset`, else the left edge of the
+     *    closest run starting at/after it. A hidden marker collapses to zero
+     *    width, so both edges coincide at the seam.
      */
     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;
 }
@@ -1732,8 +2665,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;
@@ -1751,14 +2690,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;
@@ -1766,4 +2706,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 { }