@sobree/core 0.1.0

package/dist/editor/index.d.ts

@@ -0,0 +1,1078 @@
+import { BlobCache, BlobStore } from '../blob';
+import { BlockRef, EditError, EditResult, InlinePosition, Range as ApiRange, Selection } from '../doc/api';
+import { EmbedFontFaces, EmbedFontOptions } from '../fonts';
+import { RunPropertiesPatch } from '../doc/runs';
+import { Block, InlineRun, ParagraphAlignment, ParagraphProperties, SobreeDocument } from '../doc/types';
+import { BlockRegistry } from './internal/blockRegistry';
+import { countBlocks } from './internal/positionMap';
+import { EditorTable } from './table';
+import { History } from '../history';
+import * as Y from "yjs";
+export type { BlockRef, EditError, EditResult, InlinePosition, Selection };
+export type ApiRangeType = ApiRange;
+/**
+ * One logical tracked change — a maximal run of consecutive inline
+ * runs that all carry a `revision` marker by the same author.
+ * `getRevisions()` returns these; pass `range` straight to
+ * `acceptRevision` / `rejectRevision`.
+ *
+ * `kinds` is the set of revision types in the span: `["ins"]` or
+ * `["del"]` for a plain change, both for a delete-then-insert
+ * replacement (which accepts/rejects as a single unit).
+ */
+export interface RevisionSpan {
+    range: ApiRange;
+    author?: string;
+    kinds: ("ins" | "del")[];
+    /** ISO date of the span's first revision run, if recorded. */
+    date?: string;
+    /**
+     * Discriminator between revision levels:
+     *   `"inline"` (default for backwards compat) — the span covers
+     *     `ins`/`del` text runs inside a block. Pass `range` to
+     *     `acceptRevision` / `rejectRevision`.
+     *   `"paragraph"` — the span flags the *paragraph mark* itself on
+     *     `range.from.block`. The range covers offset `[0, length]` of
+     *     the block so it still selects the right element for UIs, but
+     *     accept/reject must go through `acceptParagraphRevision` /
+     *     `rejectParagraphRevision`.
+     *   `"format"` — the span flags a tracked format change
+     *     (`<w:rPrChange>`) on contiguous runs by the same author.
+     *     `kinds` always reports `["ins"]` (the marker is binary: a
+     *     format change exists or not). Pass `range` to
+     *     `acceptFormatRevision` / `rejectFormatRevision`.
+     */
+    level?: "inline" | "paragraph" | "format";
+}
+/**
+ * Track-changes mode. When `enabled` is true, the editor reinterprets
+ * authoring mutations as tracked revisions rather than direct edits:
+ *
+ *   - `insertRun` stamps `revision: { type: "ins", author }` on the
+ *     inserted run instead of merging it in plainly.
+ *   - `deleteRange` stamps `revision: { type: "del", author }` on the
+ *     plain text runs in range instead of dropping them. A run that's
+ *     already an `ins` *by the same author* is dropped instead — the
+ *     author cancelling their own pending insert — and runs already
+ *     carrying a peer's revision are left untouched (the API user must
+ *     resolve those via `acceptRevision` / `rejectRevision` first).
+ *   - All other mutations (`applyRunProperties`, block-level ops, etc.)
+ *     pass through unchanged in this first cut; format-change tracking
+ *     (`<w:rPrChange>`) and paragraph-mark tracking will land later.
+ *
+ * `author` is the human-readable name written into the revision
+ * marker. Optional — falls back to no `author` field, mirroring the
+ * Word semantics for anonymous-author tracked changes.
+ *
+ * This is the *authoring* side of the review feature. `getRevisions`
+ * / `acceptRevision` / `rejectRevision` are the *consumption* side
+ * and work the same regardless of this flag.
+ */
+export interface TrackChangesState {
+    enabled: boolean;
+    author?: string;
+}
+export type { CellRef, InsertAt, InsertColumnOpts, InsertRowOpts, MergeCellsOpts, } from './table';
+/**
+ * Payload delivered to `change` subscribers. Plain data — safe to
+ * JSON-stringify and ship over a wire. `rawParts` is stripped from
+ * `document` so the payload never carries binary Uint8Arrays.
+ */
+export interface ChangePayload {
+    doc: SobreeDocument;
+    /**
+     * @deprecated Use `doc` instead. This alias is kept for backwards
+     * compatibility within the pre-1.0 line and will be removed before
+     * v1. Same reference as `doc`.
+     */
+    document: SobreeDocument;
+    revision: number;
+    documentVersion: number;
+}
+/** Summary of a top-level block, for `getBlocks()` and list-style UIs. */
+export interface BlockInfo {
+    /** Current position in the body (unstable across edits). */
+    index: number;
+    /** Stable id — pair with `version` to form a `BlockRef`. */
+    id: string;
+    /** Bumps on every modification of this block. */
+    version: number;
+    kind: Block["kind"];
+    styleId?: string;
+    alignment?: ParagraphAlignment;
+    /** Plain-text preview. */
+    text: string;
+    /** Total character-length of the block's content (see `runsLength`). */
+    length: number;
+}
+/** Outline entry — one per heading in document order. */
+export interface OutlineItem {
+    level: number;
+    text: string;
+    blockIndex: number;
+    block: BlockRef;
+}
+export type ParagraphPropertiesPatch = {
+    [K in keyof ParagraphProperties]?: ParagraphProperties[K] | undefined;
+};
+export type WrapTag = "sup" | "sub" | "strong" | "em" | "u" | "s" | "mark";
+export type EditorEvent = "change" | "selection" | "keydown" | "track-changes-change";
+export type EditorEventPayload = {
+    change: ChangePayload;
+    selection: SelectionPayload;
+    keydown: KeyDownPayload;
+    "track-changes-change": TrackChangesState;
+};
+export type Unsubscribe = () => void;
+/**
+ * Payload delivered to `selection` subscribers. Fires whenever the live
+ * DOM selection changes — typing, clicking, arrow-key navigation, focus
+ * loss, programmatic restore. Subscribers should subscribe through the
+ * editor rather than `document.addEventListener("selectionchange")`
+ * directly so cleanup is centralised and the editor can later add
+ * dedup / throttling.
+ *
+ * `selection` is the model shape (`null` when focus is outside the
+ * editor). The convenience fields below mirror what `EditorSelection`
+ * exposes for ergonomics — read whichever one you need.
+ */
+export interface SelectionPayload {
+    selection: Selection;
+    range: ApiRange | null;
+    caret: InlinePosition | null;
+    block: BlockRef | null;
+}
+/**
+ * Payload delivered to `keydown` subscribers. Fires for every key press
+ * inside the editor host. The editor binds NO shortcuts itself —
+ * plugins map keys to API calls via `preventDefault()` (stops the
+ * browser's default action) and `stopPropagation()` (stops the chain
+ * of remaining subscribers). Subscribers fire in registration order.
+ */
+export interface KeyDownPayload {
+    /** `KeyboardEvent.key` — `"b"`, `"Enter"`, `"ArrowLeft"`, … (lowercased for letters). */
+    key: string;
+    /** `KeyboardEvent.code` — `"KeyB"`, `"Enter"`, `"ArrowLeft"`, … (layout-independent). */
+    code: string;
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    meta: boolean;
+    /** Stop the browser's default for this key (insertion, navigation, …). */
+    preventDefault(): void;
+    /** Stop further subscribers from receiving this key. */
+    stopPropagation(): void;
+    /** Underlying DOM event — for advanced needs (`isComposing`, repeat, …). */
+    originalEvent: KeyboardEvent;
+}
+/**
+ * A registered command — a named, callable unit of editor work that
+ * plugins coordinate around. Same definition gets reached by a
+ * keyboard shortcut, a toolbar click, a programmatic call from an
+ * agent, or an MCP request.
+ *
+ * The `run` function is the one place the work happens. `isActive` and
+ * `isAvailable` let UI plugins paint toggle / disabled state without
+ * understanding what the command actually does.
+ */
+export interface CommandDefinition<Args = void> {
+    /** Dotted, namespaced — `"mark.toggle.bold"`, `"section.insertBreak"`, … */
+    name: string;
+    /** Short human label for tooltips / command palettes. */
+    title?: string;
+    /** Perform the work. Should be idempotent w.r.t. selection (a second
+     *  invocation on an already-bold selection clears bold, etc.). */
+    run: (args: Args) => void;
+    /** True when the command represents an active state (mark already on,
+     *  block is already a heading, …). Drives toolbar `is-active`. */
+    isActive?: () => boolean;
+    /** False when the command can't run (e.g. selection is wrong shape).
+     *  Defaults to true. Drives toolbar `disabled`. */
+    isAvailable?: () => boolean;
+}
+/** Snapshot of one registered command — what `commands.list()` returns. */
+export interface CommandSnapshot {
+    name: string;
+    title: string;
+    isActive: boolean;
+    isAvailable: boolean;
+}
+/**
+ * Registry every plugin uses to talk to every other plugin. The
+ * editor owns it; plugins register commands on attach and unregister
+ * on detach. Keyboard plugins, toolbar plugins, and a future MCP
+ * adapter all share the same dispatch path: `editor.commands.execute(name)`.
+ */
+export interface CommandBus {
+    /** Register a command. Returns an unsubscribe that removes it. */
+    register<Args = void>(def: CommandDefinition<Args>): () => void;
+    /** Run a registered command. No-op (with a warning) if unknown. */
+    execute<Args = void>(name: string, args?: Args): void;
+    /** Snapshot every registered command — for command palettes,
+     *  toolbars rendering toggle states, accessibility audits. */
+    list(): CommandSnapshot[];
+    /** Whether the named command is currently registered. */
+    has(name: string): boolean;
+}
+export interface EditorOptions {
+    initialDocument?: SobreeDocument;
+    changeDebounceMs?: number;
+    /**
+     * Elements whose children are editable blocks, in document order. Called
+     * fresh each time — the list can grow/shrink (e.g. during pagination).
+     */
+    contentHosts?: () => HTMLElement[];
+    /**
+     * Y.Doc backing the document. Optional — if absent, the editor creates
+     * one internally. Embedders pass their own when they need to attach
+     * a provider (`y-websocket`, `y-indexeddb`, `y-webrtc`, …) for
+     * persistence or collaboration.
+     *
+     * When supplied, the editor checks whether the Y.Doc already has body
+     * content. If empty, it seeds from `initialDocument`. If non-empty
+     * (Phase 2+: a peer joined an active room), the existing Y.Doc state
+     * wins and `initialDocument` is ignored. See `editor.ydoc` for the
+     * public escape hatch.
+     */
+    ydoc?: Y.Doc;
+    /**
+     * Optional content-hashed `BlobStore` for binary parts (images, fonts).
+     *
+     * Without one (default): bytes live inline in the Y.Doc's `parts`
+     * Y.Map and replicate to every peer through Y updates. Fine for
+     * small docs.
+     *
+     * With one (Phase 3.2+): the editor hashes binary parts, uploads
+     * the bytes to the store, and writes only the hash into the Y.Doc's
+     * `partRefs` Y.Map. Y updates stay small regardless of image size.
+     * The editor maintains a local `BlobCache` that synchronously serves
+     * already-fetched bytes to the renderer; `editor.ensurePartsLoaded()`
+     * is the async hook for explicit pre-fetching (e.g. before
+     * `toDocx()`).
+     *
+     * See `@sobree/core/blob` for the interface + reference impls
+     * (`inMemoryBlobStore`, `fetchBlobStore`).
+     */
+    blobStore?: BlobStore;
+    /**
+     * Initial track-changes mode. When omitted, the editor starts in
+     * direct-edit mode (`{ enabled: false }`) and embedders can flip it
+     * later via `editor.setTrackChanges`. See `TrackChangesState`.
+     */
+    trackChanges?: TrackChangesState;
+}
+export { runsLength } from '../doc/runs';
+export type { RunPropertiesPatch };
+/**
+ * Public editor surface.
+ *
+ * Two entry points for every operation:
+ *   - Core methods take `BlockRef` / `InlinePosition` / `Range` and
+ *     return `EditResult`. These are the wire-callable API — same
+ *     contract for in-process toolbars, headless Y peers (HeadlessSobree),
+ *     and future MCP wrappers.
+ *   - "AtSelection" sugar reads the live DOM selection, builds the
+ *     position/range for you, and delegates to the core. Use these in
+ *     in-process UI code.
+ *
+ * Mutations enforce optimistic locking via block `version` numbers.
+ * Conflicts return `{ ok: false, error: { code: "optimistic-lock", … } }`
+ * rather than throwing.
+ */
+export declare class Editor {
+    readonly host: HTMLElement;
+    readonly selection: EditorSelection;
+    /**
+     * Ergonomic table operations — row/column insert-delete, cell merge /
+     * unmerge, cell-level properties. Every method returns an `EditResult`
+     * and inherits optimistic-lock checking via `replaceBlock`.
+     */
+    readonly table: EditorTable;
+    /**
+     * Named-command registry — the coordination point between plugins.
+     * Plugins register commands on attach and unregister on detach;
+     * keyboard / toolbar / agent / MCP all dispatch through `execute()`.
+     */
+    readonly commands: CommandBus;
+    /**
+     * Y.Doc backing the document. The Editor's `this.doc` field is a
+     * cached projection of this Y.Doc — every local mutation mirrors
+     * into the Y.Doc inside a transact (`origin: "local"`). Embedders
+     * read this for escape-hatch wiring (providers, dev tools, custom
+     * persistence).
+     *
+     * Phase 1a: Y.Doc is a faithful mirror of `this.doc` but the Editor
+     * still treats `this.doc` as the in-memory truth. Phase 1b inverts
+     * this — Y.Doc becomes the truth and `this.doc` becomes a pure
+     * cache invalidated by Y observers (which is what enables Phase 2
+     * providers to drive the editor from outside).
+     */
+    readonly ydoc: Y.Doc;
+    /**
+     * Optional content-hashed blob layer (Phase 3.2+). When set, binary
+     * parts (images, fonts) go through this rather than living inline
+     * in the Y.Doc. `null` means "use the inline parts path" — today's
+     * default. See `EditorOptions.blobStore`.
+     */
+    readonly blobStore: BlobStore | null;
+    /**
+     * Local cache for blob bytes — synchronously fetchable for the
+     * renderer, populated by `blobStore.put` (local writes) or
+     * `blobStore.get` (background fetches). `null` when no blobStore
+     * is configured.
+     */
+    readonly blobCache: BlobCache | null;
+    /** Most recent projection's partRefs map (path → hash). Used by
+     *  `ensurePartsLoaded` and by the `onResolved` callback to know
+     *  which paths reference a freshly-arrived blob. */
+    private lastPartRefs;
+    /**
+     * Part paths whose bytes are in flight to the BlobStore — the
+     * editor wrote them synchronously to `doc.rawParts` (so the local
+     * renderer has them), but the async hash + upload + partRef write
+     * is still pending. Mirror skips these so they don't end up inline
+     * in the Y.Doc.
+     */
+    private readonly pendingPartRefMigrations;
+    /** Listener that re-projects + re-renders on remote Y.Doc updates.
+     *  Removed on `destroy()`. */
+    private ydocUpdateListener;
+    private doc;
+    private readonly registry;
+    private readonly debounceMs;
+    private readonly getContentHosts;
+    private debounceHandle;
+    private detachImageResize;
+    private inputListener;
+    private beforeInputListener;
+    private pasteListener;
+    private dragOverListener;
+    private dropListener;
+    private revision;
+    private readonly listeners;
+    /**
+     * Authoring mode for revisions. Off by default — mutations apply
+     * plainly. On, `insertRun` / `deleteRange` route through
+     * `applyTrackChangesToInsert` / `applyTrackChangesToDelete`. See the
+     * `TrackChangesState` type docblock for the full semantics.
+     */
+    private trackChanges;
+    /**
+     * One-shot warning set for tracked-mode beforeinput types we don't
+     * (yet) route through the API — paragraph splits, paste, IME, etc.
+     * We let the browser handle them untracked rather than swallowing
+     * the keystroke, but log the inputType the first time we see it so
+     * the gap is visible during development.
+     */
+    private trackedInputWarned;
+    /**
+     * Active IME composition state (`compositionstart` → `compositionend`).
+     * `null` outside composition or in non-tracked mode.
+     *
+     * Snapshot-then-restore is the only practical way to track IME-typed
+     * text: we can't intercept `beforeinput` during composition without
+     * breaking input methods on most platforms, so we let the browser
+     * mutate the DOM natively during composition, then on `compositionend`
+     * we roll back to the pre-composition AST and re-insert the final
+     * composed string (`event.data`) through `insertRun` — which stamps
+     * the `revision: ins` marker per `TrackChangesState`.
+     */
+    private composition;
+    private compositionStartListener;
+    private compositionEndListener;
+    /** Document-level `selectionchange` listener. Funnels every cursor
+     *  movement (typing, click, arrows, programmatic restore) into the
+     *  `selection` event so plugins don't each register their own. */
+    private selectionChangeListener;
+    /** Host-level `keydown` listener. Funnels every key press into the
+     *  `keydown` event for plugins (mark shortcuts, navigation, etc.). */
+    private keydownListener;
+    /** Cached last-seen per-block JSON strings, for diff-based version bumps. */
+    private lastSerialisedBlocks;
+    /** Tracks `@font-face` registrations for the document's embedded fonts. */
+    private readonly fontFaces;
+    /**
+     * Undo / redo orchestrator. Snapshots the document at every commit
+     * + at the start of each typing session (coalesced). Memory-efficient:
+     * snapshots store doc references, not deep copies — the immutable-block
+     * model means consecutive snapshots share most blocks. Public API is
+     * `editor.history.undo() / redo() / clear() / depth() / on(...)`.
+     */
+    readonly history: History;
+    /**
+     * True when DOM mutations since the last sync were user-driven (typing,
+     * paste, drag-drop image). False right after we render from AST — the
+     * DOM is then a projection of `this.doc`, and reading it back can't
+     * tell us anything the AST doesn't already know, while losing any
+     * fidelity the serializer drops (column widths, vAlign, …). `getDocument`
+     * and `emitChangeNow` sync only when this flag is set.
+     */
+    private domDirty;
+    constructor(host: HTMLElement, options?: EditorOptions);
+    /**
+     * Re-project the Y.Doc into `this.doc`, sync the BlockRegistry to
+     * the projected ids, re-render the DOM, and fire `change`. Called
+     * when a remote provider applies an update we didn't initiate.
+     */
+    private adoptYDocState;
+    /**
+     * Resolve any `partRefs` hashes that are currently cached into the
+     * provided document's `rawParts`. In-place mutation — the document
+     * is owned by the caller. Missing hashes stay out of `rawParts`;
+     * the renderer handles missing parts gracefully (placeholder).
+     */
+    private resolveCachedPartRefsInto;
+    /**
+     * Callback fired by the BlobCache when a background fetch lands.
+     * Walks `lastPartRefs` to find which paths reference this hash,
+     * patches `this.doc.rawParts`, and re-renders so the user sees
+     * the part appear.
+     */
+    private onBlobResolved;
+    /**
+     * Wait for every currently-referenced binary part to be available
+     * in the local cache. Useful before `toDocx()` so the exported
+     * file contains all images / fonts.
+     *
+     * Returns a resolved Promise immediately when no `blobStore` is
+     * configured (today's default — bytes are always inline).
+     */
+    ensurePartsLoaded(): Promise<void>;
+    /**
+     * Current document as SobreeDocument.
+     *
+     * Syncs from the DOM only if the user typed since the last render. If
+     * the latest change came from an API call, returns the in-memory AST
+     * verbatim — the DOM is a projection of it and reading back would
+     * throw away properties the renderer doesn't surface.
+     */
+    getDocument(): SobreeDocument;
+    /** Replace the document. Fires `change` synchronously. */
+    setDocument(doc: SobreeDocument): void;
+    /**
+     * Internal apply path shared by `setDocument` and any other
+     * full-replace caller. The Y.Doc mirror produces tracked Y
+     * operations that Y.UndoManager turns into a single stack item.
+     */
+    private applyDocument;
+    /**
+     * Drop entries from `rawParts` that nothing in the AST references.
+     * Useful after deleting images (or font embeds — Phase 3) to keep the
+     * in-memory doc lean. Idempotent; reports the keys that were removed.
+     *
+     * Not auto-invoked — `exportDocx` already filters at packaging time,
+     * so callers only need this when they're keeping the doc around
+     * in-memory across many edits.
+     */
+    pruneUnusedParts(): {
+        kept: number;
+        pruned: string[];
+    };
+    /**
+     * Embed a TTF/OTF font into the document. Thin wrapper around
+     * `embedFontIntoDoc()` from the fonts module — handles the
+     * setDocument round so the renderer + `@font-face` registry pick
+     * up the new face automatically.
+     *
+     * Refuses (with a warning) when the font's OS/2 `fsType` field
+     * marks it as restricted, unless `opts.allowRestricted` is true.
+     * Pass any subset of {regular, bold, italic, boldItalic}; missing
+     * faces are simply not embedded.
+     */
+    embedFont(name: string, faces: EmbedFontFaces, opts?: EmbedFontOptions): {
+        warnings: string[];
+    };
+    /**
+     * Drop a font declaration by name. The associated font parts in
+     * `rawParts` aren't immediately removed — call `pruneUnusedParts()`
+     * (or just export) to GC them.
+     */
+    removeEmbeddedFont(name: string): void;
+    /** Monotonic counter bumped on each `change` event. */
+    getRevision(): number;
+    /** Monotonic document-wide version (bumps on any mutation). */
+    getDocumentVersion(): number;
+    /** Render current document to an HTML string. */
+    toHtml(): string;
+    getBlocks(): BlockInfo[];
+    getBlock(index: number): BlockInfo;
+    /** Same summary, looked up by stable id. Returns `null` if unknown. */
+    getBlockById(id: string): BlockInfo | null;
+    getOutline(): OutlineItem[];
+    /** Replace the block at `target`'s index with `block`. */
+    replaceBlock(target: BlockRef, block: Block): EditResult<BlockRef>;
+    /**
+     * Insert `block` before the target block. Returns the new ref.
+     *
+     * In track-changes mode (see `setTrackChanges`), if `block` is a
+     * paragraph it gets stamped with `revision: { type: "ins", author }`
+     * on its properties — the same paragraph-mark semantics as
+     * `splitBlock`. Non-paragraph blocks (table, section_break) don't
+     * carry the marker in v1 and insert plain.
+     */
+    insertBlockBefore(target: BlockRef, block: Block): EditResult<BlockRef>;
+    /**
+     * Insert `block` after the target block. Returns the new ref.
+     * Tracked-mode behaviour matches `insertBlockBefore`.
+     */
+    insertBlockAfter(target: BlockRef, block: Block): EditResult<BlockRef>;
+    /**
+     * Delete the target block.
+     *
+     * In track-changes mode, paragraph blocks aren't removed — their
+     * `properties.revision` is stamped `del` (the renderer shows the
+     * paragraph mark with a strikethrough ¶ glyph; the body text stays
+     * visible). If the paragraph carries the *current author's* pending
+     * `ins` marker (a paragraph the user themselves just created), the
+     * block is removed outright — cancelling an un-committed insert,
+     * matching the inline `deleteRange` semantics. Non-paragraph blocks
+     * (tables, section breaks) bypass tracking in v1 — they remove plainly.
+     */
+    deleteBlock(target: BlockRef): EditResult<void>;
+    /**
+     * Stamp `revision: ins` on a paragraph block if tracked mode is on
+     * and the block doesn't already carry one. Helper for
+     * `insertBlockBefore` / `insertBlockAfter`. Non-paragraph blocks
+     * pass through unchanged.
+     */
+    private stampInsertedBlockIfTracked;
+    /** Merge a patch into each target paragraph's properties. */
+    applyBlockProperties(targets: BlockRef[], patch: ParagraphPropertiesPatch): EditResult<void>;
+    /**
+     * Apply run-level properties across `range`.
+     *
+     * In track-changes mode (see `setTrackChanges`), each text run in
+     * `range` that doesn't already carry a `revisionFormat` snapshot
+     * gets one — capturing the run's properties *before* the patch is
+     * applied. Repeated tracked edits don't overwrite the snapshot, so
+     * a reject always returns the run to its pre-tracking state.
+     * Non-text runs and runs with no concrete properties pass through
+     * unchanged.
+     */
+    applyRunProperties(range: ApiRange, patch: RunPropertiesPatch, opts?: {
+        expect?: Record<string, number>;
+    }): EditResult<void>;
+    /** Wrap the runs in `range` with semantic formatting. */
+    wrapRange(range: ApiRange, tag: WrapTag, opts?: {
+        expect?: Record<string, number>;
+    }): EditResult<void>;
+    /**
+     * Insert a run at `at`. Splits the run list at the offset.
+     *
+     * In track-changes mode (see `setTrackChanges`), the run is stamped
+     * with `revision: { type: "ins", author }` before insertion (unless
+     * it already carries a `revision` — caller-provided revisions are
+     * never overwritten).
+     */
+    insertRun(at: InlinePosition, run: InlineRun): EditResult<BlockRef>;
+    /**
+     * Split a paragraph at `at`. The runs before the offset stay on the
+     * original block; the runs after move into a fresh paragraph that's
+     * inserted immediately after. The new block inherits the original
+     * paragraph's properties (alignment, style, indent, …) so the visual
+     * shape of the split is what the user expects from pressing Enter.
+     *
+     * In track-changes mode (see `setTrackChanges`), the new paragraph's
+     * `properties.revision` is stamped `{ type: "ins", author }` — the
+     * "this paragraph break is a tracked insert" marker. The original
+     * paragraph is left clean; only the *new* paragraph carries the mark,
+     * mirroring how Word stores `<w:rPr><w:ins/></w:rPr>` inside `<w:pPr>`.
+     *
+     * `at.offset` is clamped to `[0, block-length]`. A split at offset 0
+     * inserts an empty paragraph *before* the cursor; a split at the
+     * block's full length inserts an empty paragraph *after*.
+     *
+     * Returns the ref of the *new* (second) block — callers typically
+     * place the caret at its offset 0.
+     */
+    splitBlock(at: InlinePosition): EditResult<BlockRef>;
+    /**
+     * Insert an image at `at`. The bytes are stored in `doc.rawParts` under
+     * a fresh `word/media/imageN.{ext}` path; a `DrawingRun` referencing
+     * that path is inserted at the position.
+     *
+     * When a `blobStore` is configured (Phase 3.2+), the bytes also
+     * migrate in the background: hashed, uploaded to the store, and a
+     * `partRefs[partPath] = hash` entry written to the Y.Doc. Once the
+     * migration lands, the Y.Doc's inline `parts[partPath]` is cleared —
+     * so the bytes ride the side-channel, not the Y update stream.
+     * The local renderer keeps reading `doc.rawParts[partPath]`
+     * throughout (the value is stable from the moment `insertImage`
+     * returns).
+     */
+    insertImage(at: InlinePosition, bytes: Uint8Array, opts: {
+        mime: string;
+        widthPx?: number;
+        heightPx?: number;
+        altText?: string;
+    }): EditResult<BlockRef>;
+    /**
+     * Delete the content inside `range`. Supports both single-block and
+     * cross-paragraph ranges.
+     *
+     * In track-changes mode (see `setTrackChanges`), the deletion is
+     * *recorded* rather than applied:
+     *   - plain runs are stamped with `revision: { type: "del", author }`;
+     *   - a run already marked as the same author's pending `ins` is
+     *     dropped (the author cancelling their own un-committed insert
+     *     — no audit trail because it was never committed);
+     *   - runs carrying a peer's revision (any author other than the
+     *     current one) are left untouched: the API user should resolve
+     *     those via `acceptRevision` / `rejectRevision` first.
+     *
+     * **Cross-paragraph behaviour**: in tracked mode every paragraph
+     * *after* the first one in the range gets its paragraph-mark
+     * stamped `del` too, so `acceptAllRevisions` later collapses the
+     * range into a single paragraph. In non-tracked mode the
+     * intermediate paragraphs are removed outright and the first +
+     * last blocks merge into one.
+     */
+    deleteRange(range: ApiRange, opts?: {
+        expect?: Record<string, number>;
+    }): EditResult<void>;
+    /**
+     * Tracked cross-paragraph delete. Walks each paragraph in the range:
+     * stamps `del` on the affected runs (first-block tail / intermediate
+     * full / last-block head), and on every paragraph *after the first*
+     * stamps the paragraph-mark `del` so `acceptAllRevisions` later
+     * merges them all into the first block. Single commit.
+     */
+    private deleteRangeAcrossBlocksTracked;
+    /**
+     * Non-tracked cross-paragraph delete. Keeps the head of the first
+     * block + the tail of the last block, splices them into the first
+     * block as one paragraph, and removes everything in between.
+     */
+    private deleteRangeAcrossBlocksPlain;
+    /**
+     * Read the current track-changes mode. Defaults to `{ enabled: false }`
+     * — the editor mutates the document plainly. See `setTrackChanges`.
+     *
+     * Returns a fresh copy each call, so callers can mutate the returned
+     * object without affecting editor state.
+     */
+    getTrackChanges(): TrackChangesState;
+    /**
+     * Switch authoring mode. When `enabled`, subsequent `insertRun` and
+     * `deleteRange` calls produce tracked revisions instead of direct
+     * mutations (see `TrackChangesState`'s docblock for the full rules).
+     *
+     * Fires `track-changes-change` if the state actually changes
+     * (idempotent — re-setting the same enabled+author is a no-op).
+     * Listeners receive the new state; embedders typically forward it
+     * to a toolbar pill / mode badge.
+     */
+    setTrackChanges(state: TrackChangesState): void;
+    /**
+     * Route a tracked-mode `beforeinput` event through the typed API so
+     * the resulting runs carry revision markers. Returns `true` if the
+     * event was consumed (caller should `preventDefault`), `false` to
+     * let the browser handle it natively (untracked).
+     *
+     * **Handled inputTypes** (the 95% case — typing and deleting text):
+     *
+     *   - `insertText`, `insertReplacementText` — typed characters,
+     *     dictation / autocomplete replacements.
+     *   - `deleteContentBackward`, `deleteContentForward` — Backspace
+     *     and Delete keys, including over a selection.
+     *   - `deleteWordBackward`, `deleteWordForward` — Option-Backspace
+     *     style word deletions; the browser collapses to the right
+     *     selection range before firing, we just delete it.
+     *   - `deleteByCut` — Cmd-X. The clipboard side has already been
+     *     populated by the browser; we mark the source range deleted.
+     *
+     * **Unhandled** (return `false`, fall through, warn-once):
+     *
+     *   - `insertParagraph` / `insertLineBreak` — block split / soft
+     *     break. Word tracks these as `<w:ins>` on the paragraph mark;
+     *     the corresponding AST mutation (split-block as a tracked op)
+     *     hasn't landed yet.
+     *   - `insertFromPaste` — paste is handled at the `paste` event level
+     *     in `onPaste` (not here), where tracked-mode plain-text paste is
+     *     already routed through `insertRun` / `splitBlock`. Rich-paste
+     *     (HTML) in tracked mode falls back to plain text by design.
+     *   - `insertCompositionText` — handled separately via
+     *     `compositionstart` / `compositionend` listeners
+     *     (`handleCompositionStart` / `handleCompositionEnd`). We let the
+     *     IME render natively during composition, then on end we restore
+     *     the pre-composition AST and re-insert the final composed string
+     *     through this `insertRun` path.
+     *
+     * Falling through means the keystroke still works (no broken UX in
+     * tracked mode), it just doesn't get a revision marker. The console
+     * warning makes the gap visible.
+     *
+     * Caret restoration: after every routed mutation we set the model
+     * selection to where the caret would have ended up on the equivalent
+     * direct-edit operation. Because tracked-mode `deleteRange` leaves
+     * the runs in place (marked `del`), offsets don't shift — caret math
+     * is straightforward.
+     */
+    private handleTrackedInput;
+    /**
+     * Snapshot the pre-composition AST + caret so `handleCompositionEnd`
+     * can roll back the browser's native IME mutations and re-insert the
+     * final composed string through the tracked-mode `insertRun`. No-op
+     * when tracked mode is off — IME falls through to the browser as
+     * always (untracked, but functional).
+     */
+    private handleCompositionStart;
+    /**
+     * Commit a tracked IME composition. Restores the AST to its
+     * pre-composition snapshot, re-renders, then inserts `event.data`
+     * through `insertRun` at the captured caret — so the final composed
+     * string lands as a tracked `ins` instead of as plain text from the
+     * browser's native IME commit.
+     *
+     * Bails out (and clears state) if tracked mode was toggled off
+     * mid-composition or the snapshot is missing; the browser's native
+     * commit then stands as-is (untracked, but functional).
+     */
+    private handleCompositionEnd;
+    /**
+     * Resolve the position to insert at when the user types over the
+     * current selection. For a caret, that's the caret itself; for a
+     * range, we delete the range first (which in tracked mode marks the
+     * runs `del` but keeps them in place — so the `from` offset is still
+     * the right insertion point afterwards). Returns `null` if the
+     * selection spans blocks or the delete failed.
+     */
+    private markedRangeForReplace;
+    /**
+     * Range a Backspace-style key should delete. Range-selection wins
+     * if there is one (just delete the selection). Otherwise step one
+     * character left of the caret — at offset 0 we have nothing to do
+     * (and Word does nothing in that position too, in v1; cross-block
+     * backspace is a follow-up).
+     */
+    private rangeForBackwardDelete;
+    /** Forward-delete equivalent of `rangeForBackwardDelete`. */
+    private rangeForForwardDelete;
+    /** Re-lookup the block by id to get a fresh `BlockRef` (current version). */
+    private refreshedPosition;
+    /** Place the caret at `(blockId, offset)` using a fresh block ref. */
+    private placeCaret;
+    /**
+     * True when the current DOM selection's caret sits inside an `<ins>`,
+     * `<del>`, or `<span.sobree-revision-format>` wrapper — the markup
+     * the renderer emits for tracked revisions. Used by `beforeinput` in
+     * mode-off to detect when we have to take over the insert path: if
+     * we don't, the browser's contenteditable inserts the new character
+     * INSIDE the wrapper and the post-input DOM-sync stamps it with the
+     * wrapper's revision marker (an edit the user explicitly opted out
+     * of tracking).
+     *
+     * Returns `false` for a normal caret in plain text, in a `<strong>`
+     * / `<em>` / etc. — those wrappers *should* inherit (formatting),
+     * unlike revision wrappers which encode "edit history."
+     */
+    private caretInsideRevisionWrapper;
+    /**
+     * Accept the tracked changes inside `range`: insertions become
+     * permanent (the revision marker is stripped, text kept), deletions
+     * are applied (the deleted text is dropped). Runs in `range` with no
+     * revision marker pass through untouched, so it's safe to pass a
+     * range slightly wider than the change.
+     */
+    acceptRevision(range: ApiRange, opts?: {
+        expect?: Record<string, number>;
+    }): EditResult<void>;
+    /**
+     * Reject the tracked changes inside `range`: insertions are removed
+     * (the inserted text is dropped), deletions are restored (the
+     * revision marker is stripped, deleted text kept). The inverse of
+     * `acceptRevision`.
+     */
+    rejectRevision(range: ApiRange, opts?: {
+        expect?: Record<string, number>;
+    }): EditResult<void>;
+    /**
+     * Accept tracked format changes inside `range`: each text run with a
+     * `revisionFormat` snapshot drops the snapshot; the current
+     * `properties` stay. Runs without one pass through.
+     */
+    acceptFormatRevision(range: ApiRange, opts?: {
+        expect?: Record<string, number>;
+    }): EditResult<void>;
+    /**
+     * Reject tracked format changes inside `range`: each run reverts its
+     * `properties` to `revisionFormat.before`. Inverse of
+     * `acceptFormatRevision`.
+     */
+    rejectFormatRevision(range: ApiRange, opts?: {
+        expect?: Record<string, number>;
+    }): EditResult<void>;
+    /**
+     * Accept the paragraph-mark revision on `target`.
+     *
+     * Per the semantics in `ParagraphProperties.revision`'s docblock:
+     *   - `ins` → strip the marker; the paragraph break stays permanent.
+     *   - `del` → merge this paragraph's content into the *previous*
+     *     paragraph; the paragraph break is consumed.
+     *
+     * Returns `range-empty`-coded failure if the block has no paragraph
+     * revision, and `invalid-state` if a `del` accept would require
+     * merging with a non-paragraph (table, section break) — those merges
+     * aren't well-defined yet.
+     */
+    acceptParagraphRevision(target: BlockRef): EditResult<void>;
+    /**
+     * Reject the paragraph-mark revision on `target`.
+     *   - `ins` → merge this paragraph into the *previous* one (the split
+     *     introduced by the tracked Enter is undone).
+     *   - `del` → strip the marker; the paragraph break stays.
+     */
+    rejectParagraphRevision(target: BlockRef): EditResult<void>;
+    /**
+     * Concatenate `body[index]`'s runs onto the end of `body[index-1]`
+     * and remove `body[index]`. The previous block must be a paragraph;
+     * otherwise we bail with `invalid-state`. Used by accept/reject of
+     * paragraph-mark revisions where the decision means "this paragraph
+     * break should not exist".
+     */
+    private mergeWithPrevious;
+    /**
+     * Strip the `revision` marker from `body[index]`'s paragraph
+     * properties, leaving the block (and its content) in place.
+     * Fallback for merge-impossible cases — see `mergeWithPrevious`'s
+     * `index <= 0` branch and `applyAllRevisions`' second pass.
+     */
+    private stripParagraphMarker;
+    /**
+     * Flag `body[index]`'s paragraph break as a tracked deletion —
+     * stamp `properties.revision = { type: "del", author }`. Used by
+     * `handleTrackedInput` for the Backspace-at-start-of-paragraph
+     * keystroke.
+     *
+     * Two short-circuits:
+     *   - If the paragraph already carries the *same author's* pending
+     *     `ins` (the user is backspacing into a split they themselves
+     *     just made), drop the marker and merge into the previous
+     *     paragraph — cancelling an un-committed insert rather than
+     *     layering del on top of ins.
+     *   - If the paragraph carries some OTHER revision (peer's ins, an
+     *     existing del), leave it alone with a no-op success. The
+     *     reviewer should resolve those via accept/reject first.
+     */
+    private markParagraphBreakForDelete;
+    /**
+     * Enumerate every logical tracked change in the document.
+     *
+     * Consecutive revision-bearing runs by the same author coalesce into
+     * one `RevisionSpan` — so a delete-then-insert replacement is one
+     * span, and two unrelated insertions in a paragraph (separated by
+     * plain text) are two. Each span's `range` carries fresh, versioned
+     * `BlockRef`s, ready to hand to `acceptRevision` / `rejectRevision`.
+     *
+     * Call after each `change` — the ranges are positional, so re-query
+     * rather than caching across edits.
+     */
+    getRevisions(): RevisionSpan[];
+    /**
+     * Walk one paragraph and append its revision spans to `out`. Used by
+     * `getRevisions` for both top-level paragraphs (where `ref` is the
+     * paragraph's own BlockRef) and for paragraphs inside table cells
+     * (where `ref` is the *containing table's* BlockRef as a sentinel —
+     * cell paragraphs don't have their own registry entry yet).
+     *
+     * Emits the same three-level span shape as the inline walker:
+     * paragraph-mark first, then coalesced inline ins/del spans, then
+     * coalesced format-change spans.
+     */
+    private collectParagraphRevisions;
+    /**
+     * Accept every tracked change in the document. With `opts.author`,
+     * accept only that author's changes. One commit for the whole sweep.
+     */
+    acceptAllRevisions(opts?: {
+        author?: string;
+    }): EditResult<void>;
+    /** Reject every tracked change (optionally filtered by author). */
+    rejectAllRevisions(opts?: {
+        author?: string;
+    }): EditResult<void>;
+    private applyAllRevisions;
+    /**
+     * Walk a table's cell paragraphs and apply the accept/reject
+     * decision to inline + format + paragraph-mark revisions inside.
+     * Returns `{ next, changed }` so the caller knows whether to bump
+     * the table block. Paragraph-mark del within a cell falls back to
+     * strip-the-marker rather than attempting a cross-cell-paragraph
+     * merge — that structural edit is out of v1 scope for tables.
+     */
+    private sweepTableCellRevisions;
+    /** Mark comment `id` resolved (`Comment.done = true`). */
+    resolveComment(id: number): EditResult<void>;
+    /** Re-open a resolved comment `id` (`Comment.done = false`). */
+    reopenComment(id: number): EditResult<void>;
+    private setCommentDone;
+    setBlockPropertiesAtSelection(patch: ParagraphPropertiesPatch): EditResult<void>;
+    setRunPropertiesAtSelection(patch: RunPropertiesPatch): EditResult<void>;
+    wrapSelection(tag: WrapTag): EditResult<void>;
+    insertImageAtSelection(bytes: Uint8Array, opts: {
+        mime: string;
+        widthPx?: number;
+        heightPx?: number;
+        altText?: string;
+    }): EditResult<BlockRef>;
+    /**
+     * Unwrap span ancestors intersecting the selection, up to the block.
+     * Best-effort DOM-level cleanup — preserves the current in-place UX
+     * without re-rendering.
+     */
+    clearInlineFormattingAtSelection(): void;
+    on<E extends EditorEvent>(event: E, cb: (p: EditorEventPayload[E]) => void): Unsubscribe;
+    destroy(): void;
+    /** @internal */
+    _hosts(): HTMLElement[];
+    /** @internal */
+    _registry(): BlockRegistry;
+    /** @internal */
+    _blockElementAt(index: number): HTMLElement | null;
+    /**
+     * Parallel array of live block ids (same length as `doc.body`), used
+     * by the renderer to stamp `data-block-id` onto every block element.
+     * Lets external tools (block tools, embedders) locate a block's DOM
+     * element after the body is re-rendered from scratch.
+     */
+    private blockIdsArray;
+    private checkRefs;
+    private checkRange;
+    /**
+     * Apply a runs transform to the runs covered by `range`. Returns
+     * `EditResult<void>`. Handles both single- and multi-block ranges.
+     * Assumes locks have already been checked.
+     */
+    private mutateRunsInRange;
+    /**
+     * Apply a mutation to `this.doc`, update the registry, re-render, fire
+     * change. Returns the affected refs (post-bump).
+     */
+    private commit;
+    /**
+     * Ensure `this.doc` reflects the latest edits. If the DOM has been
+     * dirtied by user typing / paste / drop, pull the latest content out
+     * of it and bump affected block versions. If the last mutation came
+     * from the API, the AST is already current — skip the (lossy)
+     * DOM-to-AST round-trip.
+     */
+    private ensureCurrent;
+    private syncFromDom;
+    /**
+     * Schedule a DOM-driven change emit. Called from the `input` listener
+     * when the user types — the DOM is the source of truth and we sync the
+     * AST from it before notifying listeners.
+     */
+    private scheduleChange;
+    /**
+     * Emit a `change` event using the current in-memory AST verbatim. Do
+     * NOT sync from DOM — callers that need a DOM sync should call it
+     * explicitly (user-typing path does). API mutations have already
+     * rendered their AST into the DOM and must not let the lossy DOM-read
+     * overwrite properties the renderer doesn't surface
+     * (column widths, verticalAlign, table properties, …).
+     */
+    private emitChangeNow;
+    /**
+     * Snapshot of the live block ids in body order — used both as the
+     * input to `applyDocumentToYDoc` (so each Y.Map carries its stable
+     * id) and as the `blockIdsArray()` the renderer uses to set the
+     * `data-block-id` attribute.
+     */
+    private allBlockIds;
+    /**
+     * Mirror the current `this.doc` into the Y.Doc as a single
+     * transaction. The diff is performed by `applyDocumentToYDoc`,
+     * which matches blocks by id so concurrent edits to *different*
+     * blocks merge cleanly via the Y.Array CRDT.
+     *
+     * Origin is `"local"` so a future Y observer can distinguish locally-
+     * driven mutations (already rendered) from remote ones (need re-render).
+     */
+    private mirrorToYDoc;
+    /**
+     * Returns the set of part paths that mirror should NOT write
+     * inline — they're (or will soon be) tracked via the partRefs
+     * Y.Map instead. Returns `undefined` when there's nothing to skip
+     * (the common no-BlobStore case) so the mirror takes its
+     * fastest path.
+     */
+    private computePartPathSkipSet;
+    /**
+     * Background migrate inline part bytes into the BlobStore. Called
+     * by mutators (`insertImage`, `embedFont`) when a `BlobStore` is
+     * configured. The local `doc.rawParts` keeps its inline copy so
+     * the renderer stays synchronous; the Y.Doc gets a `partRefs`
+     * entry referencing the BlobStore content hash, and any stale
+     * `parts` entry is deleted.
+     *
+     * Robust against errors: an upload failure logs and leaves the
+     * path in the pending set so a future call can retry. The local
+     * renderer is unaffected (bytes are still in `doc.rawParts`).
+     */
+    private migratePartToBlobStore;
+    /**
+     * Compose the current selection into a {@link SelectionPayload} and
+     * dispatch to subscribers. Called from the document-level
+     * `selectionchange` listener attached in the constructor; safe to fire
+     * even when no subscribers exist (the early-return keeps it cheap).
+     */
+    private fireSelection;
+    /**
+     * Normalise a DOM `KeyboardEvent` into a {@link KeyDownPayload} and
+     * dispatch to subscribers in registration order. Subscribers can
+     * `preventDefault()` (browser default) and / or `stopPropagation()`
+     * (further subscribers). The editor itself binds no shortcuts —
+     * everything goes through plugins.
+     */
+    private fireKeyDown;
+    private summariseBlock;
+    private onPaste;
+    /**
+     * Insert `text` at the current selection in track-changes mode, with
+     * each `\n` becoming a `splitBlock`. Used by `onPaste` for plain-text
+     * paste; could be reused for tracked drop (a follow-up). Splits the
+     * line list once up-front and walks it so each insertRun lands at the
+     * caret of the *current* paragraph (which may be a fresh one from a
+     * preceding splitBlock).
+     */
+    private pasteTrackedText;
+    private onDragOver;
+    private onDrop;
+    private insertImageFromFile;
+}
+/**
+ * Read and write the caret / selection in model terms. Lives on
+ * `editor.selection`. Wraps `window.getSelection()` so callers never
+ * touch the DOM directly.
+ */
+export declare class EditorSelection {
+    private readonly editor;
+    constructor(editor: Editor);
+    /** Current selection as a model `Selection`. Returns `null` when focus is outside. */
+    get(): Selection;
+    /** Apply a model selection to the DOM. */
+    set(sel: Selection): boolean;
+    /** Shortcut: current selection as a `Range`, or `null` when collapsed/absent. */
+    currentRange(): ApiRange | null;
+    /** Shortcut: the caret position (collapses a range to its `from`). */
+    currentCaret(): InlinePosition | null;
+    /** Shortcut: ref of the block containing the caret. */
+    currentBlock(): BlockRef | null;
+    /** Legacy: current block index (for code still using indices). */
+    currentBlockIndex(): number | null;
+}
+/**
+ * Default {@link CommandBus} implementation. Plain in-memory map; no
+ * editor coupling beyond the closure plugins use when registering.
+ * Replacing it would mean swapping a field on Editor — the rest of
+ * the surface stays the same.
+ */
+export declare class EditorCommands implements CommandBus {
+    private readonly commands;
+    register<Args = void>(def: CommandDefinition<Args>): () => void;
+    execute<Args = void>(name: string, args?: Args): void;
+    list(): CommandSnapshot[];
+    has(name: string): boolean;
+}
+export { countBlocks };