@vscode/markdown-editor 0.0.2-3 → 0.0.2-30

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;
@@ -71,7 +88,7 @@ export declare class AsyncClipboardStrategy implements IClipboardStrategy {
     connect(context: IClipboardContext): IDisposable;
 }
 
-export declare type BlockAstNode = HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | ThematicBreakAstNode | BlockQuoteAstNode | ListAstNode | TableAstNode;
+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
@@ -92,7 +109,7 @@ declare abstract class BlockAstNodeBase extends AstNode {
 /**
  * One block's place in the rendered document.
  *
- * `height` is in CSS pixels. It is either a real DOM measurement
+ * Geometry is in editor-local CSS pixels. `height` is either a real DOM measurement
  * (`isMeasured: true`) or an estimate produced when the block is not
  * currently mounted (`isMeasured: false`). Estimates exist so virtual
  * rendering can size the scroll container without mounting every block.
@@ -107,6 +124,13 @@ export declare interface BlockMeasurement {
     readonly block: BlockAstNode;
     readonly absoluteStart: number;
     readonly height: number;
+    /** Local border box when mounted and measured. */
+    readonly rect: Rect2D | undefined;
+    /** Local horizontal padding-box clip when this block scrolls horizontally. */
+    readonly viewportClip: {
+        readonly left: number;
+        readonly right: number;
+    } | undefined;
     readonly isMeasured: boolean;
     readonly visualLineMap: VisualLineMap | undefined;
     readonly viewNode: ViewNode | undefined;
@@ -130,7 +154,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
@@ -151,6 +175,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
@@ -174,9 +209,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
@@ -196,6 +232,22 @@ 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 BlockAstNodeBase {
@@ -271,10 +323,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
@@ -292,6 +575,8 @@ export declare interface CursorCommandContext {
     readonly selection: Selection_2;
     readonly document: DocumentAstNode;
     readonly activeBlock: BlockAstNode | undefined;
+    readonly markerVisibleBlocks: ReadonlySet<BlockAstNode>;
+    readonly wordNavigationConfig: WordNavigationConfig;
 }
 
 export declare const cursorDocumentEnd: CursorCommand;
@@ -300,6 +585,8 @@ export declare const cursorDocumentStart: CursorCommand;
 
 export declare const cursorDown: VisualCursorCommand;
 
+export declare type CursorKeyboardAction = 'left' | 'right' | 'up' | 'down' | 'wordLeft' | 'wordRight' | 'visualLineStart' | 'visualLineEnd' | 'logicalLineStart' | 'logicalLineEnd' | 'documentStart' | 'documentEnd';
+
 export declare const cursorLeft: CursorCommand;
 
 export declare const cursorLineEnd: CursorCommand;
@@ -329,15 +616,27 @@ export declare const cursorUp: VisualCursorCommand;
  * derived subscribed.
  */
 export declare class CursorView extends Disposable {
-    private readonly _parent;
     readonly element: HTMLElement;
     readonly rendering: IObservable<CursorViewRendering>;
-    constructor(_parent: HTMLElement, options: CursorViewOptions);
+    constructor(options: CursorViewOptions);
 }
 
 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 editor-local rect 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 {
@@ -347,18 +646,98 @@ export declare class CursorViewRendering {
     constructor(offset: SourceOffset, visible: boolean, rect: Rect2D);
 }
 
+export declare const cursorVisualLineEnd: VisualCursorCommand;
+
+export declare const cursorVisualLineStart: VisualCursorCommand;
+
 export declare const cursorWordLeft: CursorCommand;
 
 export declare const cursorWordRight: CursorCommand;
 
+export declare const DEFAULT_WORD_NAVIGATION_CONFIG: WordNavigationConfig;
+
+export declare const DEFAULT_WORD_SEPARATORS = "`~!@#$%^&*()-=+[{]}\\|;:'\",.<>/?";
+
 export declare const deleteLeft: EditCommand;
 
+export declare const deleteLineLeft: EditCommand;
+
+export declare const deleteLineRight: EditCommand;
+
 export declare const deleteRight: EditCommand;
 
 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";
@@ -383,13 +762,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: 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';
 }
 
 /**
@@ -445,6 +832,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. */
@@ -466,6 +855,8 @@ export declare type EditCommand = (ctx: CursorCommandContext) => {
     readonly selection: Selection_2;
 } | undefined;
 
+export declare type EditKeyboardAction = 'deleteLeft' | 'deleteRight' | 'deleteWordLeft' | 'deleteWordRight' | 'deleteLineLeft' | 'deleteLineRight';
+
 /**
  * Translates raw browser input (mouse, keyboard, EditContext) into model
  * mutations. Knows about DOM event types but never reads/writes the DOM
@@ -474,14 +865,23 @@ 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;
+    private readonly _keyboardPlatform;
+    private readonly _keyboardProfile;
+    /** 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;
@@ -492,7 +892,34 @@ export declare class EditorController extends Disposable {
     /** Move the cursor up one visual line (Arrow Up). */
     cursorUp(extend?: boolean): void;
     private _selectedText;
+    private readonly _updateModifierState;
+    private readonly _clearModifierState;
+    /**
+     * Drop any native DOM selection over the rendered text.
+     *
+     * The editor paints selection from `model.selection`, so a browser
+     * selection there is always spurious: nothing reads it (copy/cut read the
+     * model, hit-testing uses the measured layout) and nothing clears it, so it
+     * lingers as a second highlight even after the caret moves away.
+     * {@link isCaretMotionKey} stops the common source synchronously; this is
+     * the backstop for the rest of the browser's editing commands, which are
+     * platform- and version-specific and cannot be enumerated (Shift+PageDown
+     * and macOS Shift+Ctrl+B both reach one today).
+     *
+     * Scoped twice so it only ever discards selections the editor owns: the
+     * range must touch the rendered text (overlays such as comment widgets sit
+     * beside it and stay selectable), and input focus must still be inside this
+     * editor (so a host find-in-page, which selects while its own input is
+     * focused, is left alone).
+     */
+    private readonly _discardNativeSelection;
     private readonly _handleKeyDown;
+    private _executeKeyboardAction;
+    /**
+     * 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}. */
@@ -503,8 +930,52 @@ export declare interface EditorControllerOptions {
      * strategy (e.g. `AsyncClipboardStrategy`) in hosts that swallow them.
      */
     readonly clipboardStrategy?: IClipboardStrategy;
+    readonly keyboardPlatform?: KeyboardPlatform;
+    readonly keyboardProfile?: KeyboardProfile;
 }
 
+/**
+ * The editor overlay's local CSS-pixel coordinate space.
+ *
+ * Browser geometry and pointer APIs expose viewport client coordinates. This
+ * boundary converts them immediately into the coordinate system shared by the
+ * editor content and its overlays. Range rectangles are axis-aligned, so the
+ * current implementation deliberately supports positive axis-aligned scale and
+ * translation only.
+ */
+export declare class EditorCoordinateSpace {
+    private readonly _getLocalToClientMatrix;
+    static forSvgOverlay(overlay: SVGSVGElement): EditorCoordinateSpace;
+    private constructor();
+    capture(): EditorCoordinateTransform;
+}
+
+/** A stable coordinate conversion captured for one measurement operation. */
+export declare class EditorCoordinateTransform {
+    private readonly _localToClient;
+    private readonly _clientToLocal;
+    constructor(_localToClient: DOMMatrix);
+    toLocalPoint(point: Pick<Point2D, 'x' | 'y'>): Point2D;
+    toClientPoint(point: Pick<Point2D, 'x' | 'y'>): Point2D;
+    toLocalRect(rect: Pick<DOMRectReadOnly, 'left' | 'top' | 'width' | 'height'>): Rect2D;
+    toClientRect(rect: Pick<Rect2D, 'left' | 'top' | 'width' | 'height'>): Rect2D;
+    private _convertRect;
+}
+
+export declare type EditorKeyboardAction = {
+    readonly kind: 'cursor';
+    readonly command: CursorKeyboardAction;
+    readonly extend: boolean;
+} | {
+    readonly kind: 'edit';
+    readonly command: EditKeyboardAction;
+} | {
+    readonly kind: 'selectAll';
+} | {
+    readonly kind: 'enter';
+    readonly command: 'smartEnter' | 'insertParagraph' | 'insertHardLineBreak';
+};
+
 export declare class EditorModel {
     private readonly _parser;
     /**
@@ -515,11 +986,44 @@ export declare class EditorModel {
      */
     private _pendingEdit;
     readonly sourceText: ISettableObservable<StringValue, void>;
+    readonly wordNavigationConfig: ISettableObservable<WordNavigationConfig, 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
@@ -528,6 +1032,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
@@ -551,7 +1062,45 @@ export declare class EditorModel {
      * collapsed this is a one-element set holding {@link activeBlock}.
      */
     readonly activeBlocks: IObservableWithChange<Set<BlockAstNode>, void>;
-    applyEdit(edit: StringEdit): 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>;
+    readonly markerVisibleBlocks: IObservableWithChange<Set<BlockAstNode>, 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, selection?: Selection_2): void;
     applyEditForSelection(edit: StringEdit): void;
 }
 
@@ -584,6 +1133,7 @@ export declare class EditorView extends Disposable {
     readonly element: HTMLElement;
     readonly editContext: EditContext;
     readonly measuredLayout: MeasuredLayoutModel;
+    readonly coordinateSpace: EditorCoordinateSpace;
     /**
      * Inner container that holds the rendered document and the cursor/selection
      * overlays. The outer {@link element} spans the full width; this container
@@ -593,6 +1143,9 @@ export declare class EditorView extends Disposable {
     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
@@ -612,20 +1165,117 @@ 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>;
+    /**
+     * Whether the editor is genuinely focused: focus rests somewhere inside the
+     * editor subtree *and* its window is focused. Mirrored onto the root as
+     * `.md-focused`, which gates the painted caret — the blinking cursor is only
+     * shown while this is `true`, so it never blinks in an unfocused editor or
+     * after the window loses focus. Only the caret's visibility is affected; the
+     * logical selection and caret geometry ({@link caretRect}) are unchanged.
+     */
+    private readonly _focused;
+    get focused(): IObservable<boolean>;
+    /**
+     * Caret rect (editor-local coordinates) 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;
+    /**
+     * Tracks whether the editor is genuinely focused and mirrors it onto the
+     * root as `.md-focused` so CSS can gate the painted caret. "Focused" means
+     * focus rests somewhere inside the editor subtree *and* the window itself is
+     * focused; either condition failing (focus moving elsewhere, or the window
+     * losing focus) hides the blinking caret while leaving the logical selection
+     * and caret geometry intact.
+     */
+    private _setupFocusTracking;
+    /**
+     * 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;
+    /**
+     * Focuses the editor when it opens, but only if doing so will not steal
+     * focus from an explicit user target: the window must already be focused and
+     * no other element may have claimed focus yet. Returns whether focus was
+     * taken. Intended for the single editable editor on open; a no-op for a
+     * background window or when the user has already focused something else.
+     */
+    tryAutoFocus(): boolean;
+    /**
+     * 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
@@ -635,6 +1285,13 @@ export declare class EditorView extends Disposable {
      * have `pointer-events: none`, so the hit-test sees through them.
      */
     isPointInContent(point: Point2D): boolean;
+    /**
+     * Whether `node` sits inside the rendered source text — the region whose
+     * selection this editor paints itself from `model.selection`. Overlays
+     * anchored beside the text (comment widgets and the like) are *not* part of
+     * it and keep their own native selection behaviour.
+     */
+    containsRenderedContent(node: Node | null | undefined): boolean;
     private readonly _renderAutorun;
     /** Current mounted blocks, or empty before the first render. */
     private get _blocks();
@@ -644,6 +1301,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 {
@@ -654,6 +1320,12 @@ 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
@@ -664,6 +1336,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 {
@@ -690,14 +1370,18 @@ declare class EmphasisViewData {
  */
 export declare function findNodeOffsetById(root: AstNode, target: AstNode): number | undefined;
 
-export declare function findWordAt(text: string, offset: number): {
+export declare function findWordAt(text: string, offset: number, config?: WordNavigationConfig): {
     start: number;
     end: number;
 };
 
-export declare function findWordBoundaryLeft(text: string, offset: number): number;
+export declare function findWordBoundaryLeft(text: string, offset: number, config?: WordNavigationConfig): number;
+
+export declare function findWordBoundaryRight(text: string, offset: number, config?: WordNavigationConfig): number;
 
-export declare function findWordBoundaryRight(text: string, offset: number): number;
+export declare function findWordDeleteBoundaryLeft(text: string, offset: number, config?: WordNavigationConfig): number;
+
+export declare function findWordDeleteBoundaryRight(text: string, offset: number, config?: WordNavigationConfig): number;
 
 export declare function getAnnotatedSource(node: AstNode, source: string, offset?: number): string;
 
@@ -731,6 +1415,29 @@ declare class GlueViewData {
     decorateNewline: boolean);
 }
 
+/**
+ * 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;
@@ -751,6 +1458,8 @@ declare class HeadingViewData {
     constructor(ast: HeadingAstNode, content: readonly AnyViewData[]);
 }
 
+export declare function hiddenCursorRanges(doc: DocumentAstNode, markerVisibleBlocks: ReadonlySet<BlockAstNode>, cursor: number): readonly OffsetRange[];
+
 /**
  * The editor operations a clipboard strategy drives. The strategy never
  * touches the model or the DOM directly — it asks through this seam, so the
@@ -787,6 +1496,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;
@@ -798,6 +1510,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;
@@ -881,6 +1642,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;
 
 /**
@@ -922,6 +1698,29 @@ export declare interface ISyntaxHighlighterDocument extends IDisposable {
     readonly snapshot: IObservableWithChange<ISyntaxHighlightedSnapshot, LengthEdit>;
 }
 
+export declare interface KeyboardBinding {
+    readonly key: string;
+    readonly modifiers?: KeyboardModifiers;
+    readonly platforms?: readonly KeyboardPlatform[];
+    readonly action: EditorKeyboardAction;
+}
+
+export declare interface KeyboardModifiers {
+    readonly shift?: boolean;
+    readonly alt?: boolean;
+    readonly ctrl?: boolean;
+    readonly meta?: boolean;
+}
+
+export declare type KeyboardPlatform = 'macos' | 'windows' | 'linux';
+
+export declare interface KeyboardProfile {
+    /**
+     * Bindings in priority order. The first exact key/modifier/platform match wins.
+     */
+    readonly bindings: readonly KeyboardBinding[];
+}
+
 declare abstract class LeafAstNode extends AstNode {
     abstract readonly content: string;
     get children(): readonly AstNode[];
@@ -1140,8 +1939,8 @@ export declare class MeasuredLayoutDebugRendering {
  * Exposes two DOM nodes the caller can place independently:
  *
  *  - {@link overlayElement} — absolutely positioned; the caller mounts it
- *    inside the editor element so dashed line-bands and run-boxes line up
- *    with the editor's client coordinates.
+ *    inside the editor overlay container so dashed line-bands and run-boxes
+ *    share the measured editor-local coordinates.
  *  - {@link infoElement} — block-flow; the caller mounts it as a sibling
  *    *below* the editor. Contains the per-block summary table that used
  *    to live on the overlay.
@@ -1152,7 +1951,6 @@ export declare class MeasuredLayoutDebugRendering {
  * the derived subscribed.
  */
 export declare class MeasuredLayoutDebugView extends Disposable {
-    private readonly _overlayParent;
     readonly overlayElement: HTMLElement;
     readonly infoElement: HTMLElement;
     readonly rendering: IObservable<MeasuredLayoutDebugRendering>;
@@ -1165,6 +1963,7 @@ export declare class MeasuredLayoutDebugView extends Disposable {
 
 export declare interface MeasuredLayoutDebugViewOptions {
     readonly model: MeasuredLayoutModel;
+    readonly coordinateSpace: EditorCoordinateSpace;
     /**
      * DEBUG ONLY. Maps an absolute source offset to a fill color for that
      * character's glyph rect. The fixture passes the same function to the
@@ -1199,10 +1998,9 @@ export declare interface MeasuredLayoutDebugViewOptions {
 export declare class MeasuredLayoutModel {
     readonly measurements: ISettableObservable<readonly BlockMeasurement[], void>;
     /**
-     * Concatenated visual line map across all mounted blocks. Lines are
-     * left in DOM (client-coordinate) y order — each per-block map already
-     * uses absolute client coordinates from `getClientRects()`, so the
-     * concatenation is well-formed without re-sorting.
+     * Concatenated visual line map across all mounted blocks. Every per-block
+     * map uses the same editor-local coordinate space, so concatenation is
+     * well-formed without translation or re-sorting.
      */
     readonly visualLineMap: IObservableWithChange<VisualLineMap, void>;
 }
@@ -1244,14 +2042,25 @@ 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).
  */
-export declare function nextCursorPosition(doc: DocumentAstNode, activeBlock: BlockAstNode | undefined, cursor: number, direction: 'left' | 'right'): number;
+export declare function nextCursorPosition(doc: DocumentAstNode, markerVisibleBlocks: ReadonlySet<BlockAstNode>, cursor: number, direction: 'left' | 'right'): number;
 
 declare const NO_ACTIVE_BLOCKS: unique symbol;
 
+export declare function normalizeCursorPosition(doc: DocumentAstNode, markerVisibleBlocks: ReadonlySet<BlockAstNode>, cursor: number, target: number, direction: 'left' | 'right', includeHiddenRangeBoundary?: boolean): number;
+
 export declare class OffsetRange {
     readonly start: number;
     readonly endExclusive: number;
@@ -1297,7 +2106,48 @@ declare class ParagraphViewData {
 }
 
 /**
- * Immutable point in 2D space, in CSS-pixel client coordinates.
+ * 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 a caller-defined 2D CSS-pixel coordinate space.
+ * Coordinate-owning APIs must document whether values are viewport-client or
+ * editor-local; values from different spaces must not be mixed.
  */
 export declare class Point2D {
     readonly x: number;
@@ -1308,8 +2158,8 @@ export declare class Point2D {
 }
 
 /**
- * Immutable axis-aligned rectangle in 2D space, in CSS-pixel client
- * coordinates. `x`/`y` is the top-left corner, growing right/down.
+ * Immutable axis-aligned rectangle in a caller-defined 2D CSS-pixel coordinate
+ * space. `x`/`y` is the top-left corner, growing right/down.
  *
  * Half-open in both dimensions: `right` and `bottom` are excluded.
  */
@@ -1335,6 +2185,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;
@@ -1360,8 +2227,13 @@ export { Selection_2 as Selection }
 export declare interface SelectionBlock {
     readonly block: BlockAstNode;
     readonly absoluteStart: number;
-    readonly viewNode: ViewNode;
-    readonly element: HTMLElement;
+    /** Block border box in editor-local coordinates. */
+    readonly rect: Rect2D;
+    /** Visible horizontal padding-box bounds for a scrolling block. */
+    readonly viewportClip: {
+        readonly left: number;
+        readonly right: number;
+    } | undefined;
 }
 
 export declare type SelectionCommand = (ctx: CursorCommandContext, offset: SourceOffset) => Selection_2;
@@ -1393,11 +2265,10 @@ export declare interface SelectionRect {
  * envelope shape used by IDE selection rendering.
  */
 export declare class SelectionView extends Disposable {
-    private readonly _parent;
     readonly element: SVGSVGElement;
     readonly rendering: IObservable<SelectionViewRendering>;
     private readonly _path;
-    constructor(_parent: HTMLElement, options: SelectionViewOptions);
+    constructor(options: SelectionViewOptions);
 }
 
 export declare interface SelectionViewOptions {
@@ -1413,6 +2284,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.
@@ -1428,6 +2318,29 @@ 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;
+    private _pendingRevealCommentId;
+    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;
+    revealComment(id: string): void;
+    private _reconcile;
+    private _relayout;
+    private _revealPendingComment;
+}
+
+/** 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)[];
@@ -1632,6 +2545,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
@@ -1696,10 +2650,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;
     /**
@@ -1756,23 +2712,37 @@ 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;
 }
 
 /**
  * Geometry of the rendered document, as a map from source offsets to 2D
- * positions and back.
+ * positions and back. All geometry is expressed in the editor overlay's local
+ * CSS-pixel coordinate space.
  *
  * Structure (top to bottom):
  *
@@ -1807,7 +2777,7 @@ export declare class VisualLineMap {
     static measure(blockViews: readonly {
         readonly absoluteStart: number;
         readonly viewNode: ViewNode;
-    }[]): VisualLineMap;
+    }[], coordinateSpace: EditorCoordinateSpace, transform?: EditorCoordinateTransform): VisualLineMap;
     constructor(lines: readonly VisualLine[]);
     get lineCount(): number;
     get isEmpty(): boolean;
@@ -1845,6 +2815,8 @@ export declare class VisualLineMap {
     offsetAtPoint(point: Point2D): SourceOffset;
     /** Snap `x` to the nearest offset on a specific line. */
     offsetInLineAtX(lineIndex: number, x: number): SourceOffset;
+    lineStartOffset(lineIndex: number): SourceOffset | undefined;
+    lineEndOffset(lineIndex: number): SourceOffset | undefined;
 }
 
 /**
@@ -1853,8 +2825,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;
@@ -1872,19 +2850,36 @@ 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;
     /** Offset within `textNode.data` corresponding to `sourceRange.start`. */
     readonly textNodeStart: number;
+    readonly coordinateSpace: EditorCoordinateSpace;
+}
+
+export declare const vscodeKeyboardProfile: KeyboardProfile;
+
+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 declare interface WordNavigationConfig {
+    readonly wordSeparators: string;
+    readonly wordSegmenterLocales: readonly string[];
 }
 
 export { }