@sofereditor/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,601 @@
+import * as Y from 'yjs';
+export { Y };
+
+/**
+ * Document-level page configuration: physical size and margins.
+ *
+ * Everything is stored in **CSS pixels @ 96dpi** for consistency with the
+ * pagination engine (`packages/react/src/usePagination.ts` reads these
+ * directly). Conversion helpers (`mmToPx`, `pxToMm`) round-trip with millimeter
+ * inputs from the UI and the OOXML twip values used by docx import/export.
+ */
+type PagePreset = "a4" | "letter" | "oficio" | "custom";
+interface PageSettings {
+    /** Page width in CSS px. */
+    width: number;
+    /** Page height in CSS px. */
+    height: number;
+    marginTop: number;
+    marginBottom: number;
+    marginLeft: number;
+    marginRight: number;
+    /**
+     * The preset whose size the geometry matches, with the ±0.5mm tolerance used
+     * by `detectPreset`. "custom" when the dimensions don't match any preset.
+     * This is purely a UI hint — it's recomputed from width/height when needed.
+     */
+    preset?: PagePreset;
+}
+/** Page sizes in CSS px @ 96dpi. */
+declare const PAGE_PRESETS: {
+    readonly a4: {
+        readonly width: 794;
+        readonly height: 1123;
+    };
+    readonly letter: {
+        readonly width: 816;
+        readonly height: 1056;
+    };
+    readonly oficio: {
+        readonly width: 816;
+        readonly height: 1248;
+    };
+};
+/** Margin presets in CSS px. Match common Word defaults. */
+declare const MARGIN_PRESETS: {
+    readonly normal: 96;
+    readonly narrow: 48;
+    readonly wide: 192;
+};
+declare const DEFAULT_PAGE_SETTINGS: PageSettings;
+declare function mmToPx(mm: number): number;
+declare function pxToMm(px: number): number;
+/**
+ * Detect which preset a (width, height) pair matches. Tolerance is ±0.5mm to
+ * absorb rounding from the twips↔px conversion used by docx round-trip.
+ */
+declare function detectPreset(width: number, height: number): PagePreset;
+/** Fill missing fields with the default. Useful when reading from a Y.Map that may be partially populated. */
+declare function withDefaults(partial: Partial<PageSettings> | undefined): PageSettings;
+
+/**
+ * Public type definitions for the document model.
+ * The runtime representation lives in Y.js (see document.ts);
+ * these types describe its shape for consumers.
+ */
+type BlockType = "paragraph" | "heading" | "blockquote" | "codeBlock" | "listItem" | "table";
+type AlignValue = "left" | "center" | "right" | "justify";
+type DirValue = "ltr" | "rtl";
+type ListKind = "bullet" | "ordered";
+/** Maximum supported list nesting (0 = top level). */
+declare const MAX_LIST_LEVEL = 5;
+interface BlockAttrs {
+    align?: AlignValue;
+    dir?: DirValue;
+    /** Only meaningful when `type === "heading"`. 1..6. */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Only meaningful when `type === "codeBlock"`. Free-form (CSS-style language hint). */
+    language?: string;
+    /** Only meaningful when `type === "listItem"`. */
+    listKind?: ListKind;
+    /** Only meaningful when `type === "listItem"`. 0..MAX_LIST_LEVEL. */
+    listLevel?: number;
+    /** Only meaningful when `type === "table"`. */
+    rows?: number;
+    /** Only meaningful when `type === "table"`. */
+    cols?: number;
+    /**
+     * Only meaningful when `type === "table"`. Per-column widths in CSS px.
+     * Length should equal `cols` when set; missing or short arrays fall back to
+     * an auto distribution at render time.
+     */
+    colWidths?: number[];
+}
+interface CellAttrs {
+    /**
+     * Number of rows this cell spans, starting at its row. Default 1.
+     * Only meaningful on REAL cells (not covered).
+     */
+    rowspan?: number;
+    /** Default 1. Only meaningful on REAL cells. */
+    colspan?: number;
+    /**
+     * `true` iff this cell is occluded by an owning cell with a `rowspan`/`colspan`
+     * spanning into this position. Covered cells do not render their own `<td>`,
+     * never accept input, and are skipped by Tab navigation.
+     *
+     * The cells array keeps `rows * cols` entries to preserve the row-major index
+     * scheme — covered cells are placeholders, not gaps.
+     */
+    covered?: true;
+}
+interface Position {
+    blockIndex: number;
+    /**
+     * When the caret is inside a table cell, identifies which cell within the
+     * table at `blockIndex`. Flat row-major index: `row * cols + col`.
+     * `undefined` means the position addresses the block's own text (or the block
+     * itself, for atomic blocks). Tables have no own text — every caret position
+     * inside a table block carries a defined `cellIndex`.
+     */
+    cellIndex?: number;
+    offset: number;
+}
+interface Selection {
+    anchor: Position;
+    focus: Position;
+}
+type MarkName = "bold" | "italic" | "underline" | "strike" | "color" | "fontFamily" | "fontSize" | "link" | "comment";
+interface LinkAttr {
+    href: string;
+    title?: string;
+}
+interface CommentAttr {
+    /** Identificador estável compartilhado com o backend (ProvaDocumentoComentario.markId). */
+    markId: string;
+}
+interface MarkAttrs {
+    bold?: true;
+    italic?: true;
+    underline?: true;
+    strike?: true;
+    color?: string;
+    fontFamily?: string;
+    fontSize?: string;
+    link?: LinkAttr;
+    comment?: CommentAttr;
+}
+type MarkValue<K extends MarkName = MarkName> = NonNullable<MarkAttrs[K]>;
+/**
+ * Visual layout mode for an image embed.
+ *
+ * - `inline` (default): part of the text run, flows like a character.
+ * - `wrap-left` / `wrap-right`: image floats to the named side of the anchor
+ *   paragraph (Word-style "wrap square"). Text in the paragraph wraps around it.
+ * - `behind`: image is absolutely positioned beneath the text (z-index < text).
+ * - `front`: image is absolutely positioned above the text (z-index > text).
+ *
+ * In every non-inline mode the embed remains in the Y.Text run at its offset —
+ * the offset is its **anchor** (it follows the paragraph during pagination
+ * and re-flows). Visual position is offset from the anchor block's content box.
+ */
+type ImageLayout = "inline" | "wrap-left" | "wrap-right" | "behind" | "front";
+interface ImageEmbed {
+    type: "image";
+    /** Data URL (base64) — self-contained so the embed travels with the Y.Doc. */
+    src: string;
+    /** Rendered CSS px (display size — may differ from intrinsic dimensions). */
+    width: number;
+    height: number;
+    /** When set (inline mode only), the image renders `display: block` with the matching margin auto. */
+    align?: "left" | "center" | "right";
+    /** Visual layout. Defaults to "inline" when omitted. */
+    layout?: ImageLayout;
+    /**
+     * Horizontal offset in CSS px from the anchor block's content box.
+     * - wrap-left: extra left margin from the paragraph's start edge.
+     * - wrap-right: extra right margin from the paragraph's end edge.
+     * - behind / front: `left` relative to the anchor block's padding-box.
+     * Ignored for `inline`.
+     */
+    offsetX?: number;
+    /**
+     * Vertical offset in CSS px from the anchor block's content box.
+     * - wrap-left / wrap-right: extra top margin pushing the float down inside
+     *   the paragraph.
+     * - behind / front: `top` relative to the anchor block's padding-box.
+     * Ignored for `inline`.
+     */
+    offsetY?: number;
+    /**
+     * Optional plain-text caption. Renders inside a `<figcaption>` beneath the
+     * image in any layout — the figure wraps the image so the caption travels
+     * with floats/anchors. Plain text only; rich marks are out of scope (we
+     * never want a sub-editor inside an inline embed).
+     */
+    caption?: string;
+    /**
+     * Text alignment for the caption. Defaults to "center" (Word/Google Docs
+     * default for figure captions). Only meaningful when `caption` is set.
+     * Note: DOCX export emits captions inside the host paragraph, so this
+     * setting only affects the editor and HTML/PDF exports — Word displays the
+     * caption using the paragraph's own alignment.
+     */
+    captionAlign?: "left" | "center" | "right";
+}
+type InsertContent = string | ImageEmbed;
+declare function isImageEmbed(v: unknown): v is ImageEmbed;
+interface DeltaOp {
+    insert: InsertContent;
+    attributes?: MarkAttrs;
+}
+interface SerializedCell {
+    /** Plain concatenated text. */
+    text: string;
+    /** Delta with marks. */
+    delta: DeltaOp[];
+    attrs: CellAttrs;
+}
+interface SerializedBlock {
+    type: BlockType;
+    /** Plain concatenated text (no marks). Kept for ergonomic equality checks. */
+    text: string;
+    /** Yjs delta — used by the renderer to draw mark-aware spans. */
+    delta: DeltaOp[];
+    /** Block-level attributes (align, dir, heading level, code language…). */
+    attrs: BlockAttrs;
+    /** Only present when `type === "table"`. Flat row-major list, length = rows * cols. */
+    cells?: SerializedCell[];
+}
+
+/**
+ * Document JSON shape used by `EditorDocument.toJSON` / `fromJSON`, the
+ * exporters and the importer. Until Fase 9.5 this was a bare `SerializedBlock[]`;
+ * Fase 9.6 promoted it to an object so per-document settings (page size,
+ * margins) can travel with the content.
+ *
+ * `fromJSON` still accepts a legacy array for backwards compatibility — see
+ * `isLegacySerializedDocument`.
+ */
+interface SerializedDocument {
+    blocks: SerializedBlock[];
+    /** Page settings. Optional; omitted means default A4 + 1" margins. */
+    pageSettings?: PageSettings;
+}
+/** A `SerializedDocument` produced before Fase 9.6 — just an array of blocks. */
+type LegacySerializedDocument = SerializedBlock[];
+declare function isLegacySerializedDocument(v: SerializedDocument | LegacySerializedDocument): v is LegacySerializedDocument;
+
+interface BlockSpec {
+    type: BlockType;
+    defaultAttrs: BlockAttrs;
+}
+declare const BLOCK_SPECS: Record<BlockType, BlockSpec>;
+declare function isKnownBlockType(t: string): t is BlockType;
+declare function defaultAttrsFor(type: BlockType): BlockAttrs;
+
+/**
+ * Y.js-backed document.
+ *
+ * Storage layout:
+ *   ydoc.getArray("blocks") : Y.Array<Y.Map>
+ *     each Y.Map ("block"):
+ *       - type:  string ("paragraph" | "heading" | "blockquote" | "codeBlock" | "listItem" | "table")
+ *       - text:  Y.Text  (NOT present on tables)
+ *       - attrs: Y.Map<unknown> (align, dir, level, language… plus rows/cols for tables)
+ *       - cells: Y.Array<Y.Map> (only on tables, length = rows * cols, row-major)
+ *           each cell map: { text: Y.Text, attrs: Y.Map<unknown> }
+ *
+ * Block-level attrs live inside a nested Y.Map so concurrent edits (e.g. two users
+ * changing alignment at once) reconcile through Yjs' last-write-wins per key.
+ */
+declare class EditorDocument {
+    readonly ydoc: Y.Doc;
+    readonly blocks: Y.Array<Y.Map<unknown>>;
+    /** Document-level settings (page size, margins). See `getPageSettings`. */
+    readonly docSettings: Y.Map<unknown>;
+    constructor(ydoc?: Y.Doc);
+    /**
+     * Returns the current page settings. Missing fields fall back to
+     * `DEFAULT_PAGE_SETTINGS`. The returned object is a fresh snapshot — mutating
+     * it does not write back to the Y.Doc. Use `setPageSettings` for that.
+     */
+    getPageSettings(): PageSettings;
+    /**
+     * Merge `partial` into the docSettings Y.Map. Runs in a `ydoc.transact` with
+     * origin `"pageSettings"` (NOT tracked by the UndoManager, mirroring the
+     * `"import"` convention from Fase 9.5).
+     */
+    setPageSettings(partial: Partial<PageSettings>): void;
+    /** Listen for page-settings changes. Returns an unsubscribe function. */
+    observePageSettings(cb: () => void): () => void;
+    getBlock(index: number): Y.Map<unknown> | undefined;
+    getBlockText(index: number): Y.Text | undefined;
+    getBlockType(index: number): BlockType | undefined;
+    getBlockAttrsMap(index: number): Y.Map<unknown> | undefined;
+    getBlockAttrs(index: number): BlockAttrs;
+    blockCount(): number;
+    isTable(index: number): boolean;
+    /** Returns rows/cols read from the block's attrs map. `{0,0}` for non-table blocks. */
+    getTableSize(index: number): {
+        rows: number;
+        cols: number;
+    };
+    getCells(index: number): Y.Array<Y.Map<unknown>> | undefined;
+    getCell(blockIndex: number, cellIndex: number): Y.Map<unknown> | undefined;
+    getCellText(blockIndex: number, cellIndex: number): Y.Text | undefined;
+    getCellAttrsMap(blockIndex: number, cellIndex: number): Y.Map<unknown> | undefined;
+    getCellAttrs(blockIndex: number, cellIndex: number): CellAttrs;
+    /**
+     * Returns the editable Y.Text targeted by a position:
+     * - When `cellIndex` is set: the cell's text (or the owner's text if the
+     *   target cell is covered by a span — we treat the covered position as
+     *   addressing the owner).
+     * - Otherwise: the block's own text.
+     */
+    textAt(blockIndex: number, cellIndex: number | undefined): Y.Text | undefined;
+    /**
+     * Returns the "real" (non-covered) cell index for a target cell. When the
+     * target is already a real cell, returns it unchanged. When covered, walks
+     * up-and-left to find the owner.
+     *
+     * The walk is robust to oversized or non-rectangular spans by skipping
+     * candidates whose declared span doesn't actually cover the target.
+     */
+    realCellIndex(blockIndex: number, cellIndex: number): number | undefined;
+    /**
+     * Replace the document contents with a `SerializedDocument`. Runs in a single
+     * `ydoc.transact` with origin `"import"` so the UndoManager can group or skip
+     * the operation as one step.
+     *
+     * Reuses `createBlock` / `createTableBlock` so every block ends up with the
+     * exact same Y.js shape produced by the rest of the editor.
+     */
+    loadFromJSON(serialized: SerializedDocument | LegacySerializedDocument): void;
+    /** Build a fresh `EditorDocument` from a `SerializedDocument`. */
+    static fromJSON(serialized: SerializedDocument | LegacySerializedDocument): EditorDocument;
+    toJSON(): SerializedDocument;
+}
+declare function createBlock(type: BlockType, initialText?: string, attrs?: BlockAttrs): Y.Map<unknown>;
+/**
+ * Build a table block with `rows × cols` empty cells.
+ * Cells are stored in row-major order: `cell[row * cols + col]`.
+ */
+declare function createTableBlock(rows: number, cols: number): Y.Map<unknown>;
+declare function createCell(attrs?: CellAttrs): Y.Map<unknown>;
+/** Coerce a `rowspan`/`colspan` attribute value into a positive integer. */
+declare function spanOf(value: unknown): number;
+
+declare function isCollapsed(sel: Selection): boolean;
+declare function positionsEqual(a: Position, b: Position): boolean;
+declare function comparePositions(a: Position, b: Position): number;
+declare function orderedRange(sel: Selection): {
+    start: Position;
+    end: Position;
+};
+declare function collapsedSelection(pos: Position): Selection;
+/**
+ * Two positions are in the same "editable run" (same Y.Text) when they share
+ * the block index AND the cellIndex (treating absent and present-with-undefined
+ * the same way: a non-table position has cellIndex === undefined for both).
+ */
+declare function sameTextRun(a: Position, b: Position): boolean;
+
+/**
+ * Returns the marks observed across `[start, end)`. For each mark name encountered:
+ *   - if every covered character has the same value, returns that value
+ *   - if values differ OR some characters lack the mark, returns "mixed"
+ */
+declare function getMarksInRange(yText: Y.Text, start: number, end: number): Partial<Record<MarkName, MarkAttrs[MarkName] | "mixed">>;
+declare function isMarkUniformInRange(yText: Y.Text, start: number, end: number, name: MarkName, value?: MarkAttrs[MarkName]): boolean;
+/** Total number of inserted characters. Embeds (non-string inserts) count as 1. */
+declare function deltaLength(delta: DeltaOp[]): number;
+/**
+ * Return the subset of `delta` covering `[start, end)` characters.
+ * Embeds are atomic length-1 ops: included whole if their slot intersects the range.
+ */
+declare function sliceDelta(delta: DeltaOp[], start: number, end: number): DeltaOp[];
+
+declare const COMMAND_ORIGIN: unique symbol;
+interface CommandContext {
+    doc: EditorDocument;
+    getSelection: () => Selection;
+    setSelection: (sel: Selection) => void;
+}
+/**
+ * Insert text at the current selection.
+ *
+ * `marks` is an explicit override map applied to the freshly inserted range.
+ * - Entry value: apply that mark value.
+ * - Entry value `null`: clear that mark (used when the UI just toggled it off
+ *   with a collapsed caret and the next typed char must NOT inherit the
+ *   surrounding run's attribute).
+ * - When `marks` is undefined, Y.Text's default inheritance applies (good for
+ *   normal typing inside a marked run).
+ */
+declare function insertText(ctx: CommandContext, text: string, marks?: Partial<Record<MarkName, MarkAttrs[MarkName] | null>>): void;
+declare function insertParagraph(ctx: CommandContext): void;
+declare function deleteBackward(ctx: CommandContext): void;
+declare function deleteForward(ctx: CommandContext): void;
+/**
+ * Toggle a mark across the current selection.
+ * - If the selection is collapsed: no-op (the UI layer handles pendingMarks).
+ * - Boolean marks (bold/italic/underline/strike): if every character already has
+ *   the mark, remove it; otherwise apply.
+ * - Parametric marks (color, fontFamily, fontSize, link): require `value` to apply;
+ *   when uniform with that value across the range, remove instead (acts like toggle).
+ */
+declare function toggleMark(ctx: CommandContext, name: MarkName, value?: MarkAttrs[MarkName]): void;
+declare function setMark(ctx: CommandContext, name: MarkName, value: MarkAttrs[MarkName]): void;
+declare function removeMark(ctx: CommandContext, name: MarkName): void;
+/**
+ * Change the type of every block covered by the current selection.
+ * When `attrs` is provided, merges those on top of the new type's defaults.
+ * Preserves `Y.Text` content (and therefore all inline marks) and the selection.
+ */
+declare function setBlockType(ctx: CommandContext, type: BlockType, attrs?: BlockAttrs): void;
+/**
+ * Set a single attribute on every block covered by the selection.
+ * Passing `value === null` deletes the key.
+ */
+declare function setBlockAttr<K extends keyof BlockAttrs>(ctx: CommandContext, key: K, value: BlockAttrs[K] | null): void;
+/**
+ * Convert every block in the selection to/from a `listItem` of `kind`.
+ * If every covered block is already a `listItem` of `kind` → convert them all to paragraphs.
+ * Otherwise → convert them all to `listItem` (keeping existing `listLevel` when already
+ * a listItem, defaulting to 0 otherwise).
+ */
+declare function toggleList(ctx: CommandContext, kind: ListKind): void;
+/** Increase nesting of every listItem in the selection (clamped to MAX_LIST_LEVEL). */
+declare function indentList(ctx: CommandContext): void;
+/**
+ * Decrease nesting of every listItem in the selection.
+ * When level was 0, demote to paragraph (escape from the list).
+ */
+declare function dedentList(ctx: CommandContext): void;
+/**
+ * Enter behavior inside a listItem.
+ * - Empty listItem at level > 0 → dedent (stays a listItem, one level out).
+ * - Empty listItem at level 0   → convert to paragraph (exit the list).
+ * - Non-empty                   → split: tail moves to a new listItem with same kind/level.
+ *
+ * Returns `true` when it handled the event; `false` to let the default `insertParagraph` run.
+ */
+declare function splitListItem(ctx: CommandContext): boolean;
+/**
+ * Insert a fresh `rows × cols` table after the block currently holding the
+ * caret (or at the end of the document if the selection is somehow invalid),
+ * and place the caret in the table's first cell.
+ *
+ * Sub-phase 4.1 doesn't try to be clever: it does NOT replace an empty
+ * preceding paragraph. Callers can clean that up themselves; an extra empty
+ * paragraph above a table is a small price for predictable behavior.
+ */
+declare function insertTable(ctx: CommandContext, rows: number, cols: number): void;
+/** Remove the entire table at `blockIndex` and place the caret at the start of the next block (or the previous one if removal would leave the doc empty). */
+declare function deleteTable(ctx: CommandContext, blockIndex: number): void;
+/**
+ * Sub-phase 4.1 has no rowspan/colspan, so row/col operations are pure splice
+ * on the flat `cells` array. The flat index of `(r, c)` is `r * cols + c`.
+ */
+interface TableLocation {
+    blockIndex: number;
+    row: number;
+    col: number;
+}
+/**
+ * Derive `{row, col}` from a position inside a table — always pointing at the
+ * owner of the targeted cell (covered cells redirect to their owner). Returns
+ * null when the position isn't inside a table cell.
+ */
+declare function tableLocationOf(doc: EditorDocument, pos: Position): TableLocation | null;
+/**
+ * Insert a fresh row above (`where === "before"`) or below (`"after"`) the
+ * given row. Spans that previously crossed the insertion boundary are extended
+ * by 1; the corresponding columns of the new row become `covered: true`.
+ */
+declare function insertTableRow(ctx: CommandContext, blockIndex: number, row: number, where: "before" | "after"): void;
+/**
+ * Remove `row` from the table. Spans that pass through the row are shortened
+ * by one; spans that START at the row are removed AND the cell at row R+1 (in
+ * each affected column) is promoted to be the new owner with `rowspan - 1`.
+ * When it was the last row, deletes the whole table.
+ */
+declare function deleteTableRow(ctx: CommandContext, blockIndex: number, row: number): void;
+/**
+ * Insert a fresh column to the left (`"before"`) or right (`"after"`) of `col`.
+ * Spans crossing the insertion column have `colspan += 1`; the new column's
+ * cells in covered rows are themselves `covered: true`.
+ *
+ * Also resizes `colWidths` (if defined) by inserting a default width.
+ */
+declare function insertTableColumn(ctx: CommandContext, blockIndex: number, col: number, where: "before" | "after"): void;
+/**
+ * Remove `col` from the table. Spans that pass through the column are
+ * shortened by one; spans that START at the column with `colspan > 1` get
+ * their owner promoted from (r, C+1) to take over with `colspan - 1`.
+ *
+ * Also shrinks `colWidths` (if defined). When it was the last column, deletes
+ * the whole table.
+ */
+declare function deleteTableColumn(ctx: CommandContext, blockIndex: number, col: number): void;
+interface TableRect {
+    blockIndex: number;
+    /** Inclusive bounds in OWNER coordinates. */
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+/**
+ * Interpret a `Selection` as a rectangular cell range when:
+ * - Both endpoints carry `cellIndex`.
+ * - They live in the same table block.
+ * - They point to DIFFERENT owner cells.
+ *
+ * The naive bounds are then EXPANDED until every span fully fits inside —
+ * essential so that operations like `mergeSelection` can never produce a
+ * non-rectangular shape, and so visual highlights always cover whole spans.
+ */
+declare function tableRectSelection(doc: EditorDocument, sel: Selection): TableRect | null;
+/**
+ * Grow a candidate rect until every owner whose span starts within the rect
+ * fits entirely, and every covered cell inside it has its owner inside too.
+ * Converges in O(rows × cols) iterations in the worst case (each pass either
+ * grows a bound or terminates).
+ */
+declare function expandTableRect(doc: EditorDocument, blockIndex: number, initTop: number, initLeft: number, initBottom: number, initRight: number): TableRect;
+/** Enumerate every cell-index (real or covered) contained in `rect`. */
+declare function cellsInRect(doc: EditorDocument, rect: TableRect): number[];
+/**
+ * Merge every cell in the current rectangular selection into one owner at the
+ * rect's top-left. The owner's text is the concatenation of all non-empty
+ * inner texts (space-separated, mark-preserving). Returns true on success, false
+ * when there is no rect selection.
+ */
+declare function mergeSelection(ctx: CommandContext): boolean;
+/**
+ * Clears the text of every cell in the current rectangular selection (no
+ * structural mutation — spans stay intact). Returns the collapsed selection
+ * at the rect's top-left when something was cleared, otherwise null.
+ */
+declare function clearRectCells(ctx: CommandContext): Selection | null;
+/**
+ * Merge the cell at `(row, col)` with its immediate right neighbor. The right
+ * neighbor must be a real cell with matching `rowspan` (otherwise the merge
+ * would form a non-rectangle). Returns true on success, false on shape
+ * mismatch or when there is no neighbor.
+ *
+ * After: the owner's `colspan` grows by the neighbor's `colspan`; the
+ * neighbor and all its formerly-covered cells in the merged rectangle are
+ * marked `covered: true`. The neighbor's text is appended to the owner with a
+ * single space delimiter (when both sides had content).
+ */
+declare function mergeRight(ctx: CommandContext, blockIndex: number, row: number, col: number): boolean;
+/** Merge with the immediate bottom neighbor. Mirror of `mergeRight`. */
+declare function mergeDown(ctx: CommandContext, blockIndex: number, row: number, col: number): boolean;
+/**
+ * Split a merged cell back into a `rowspan × colspan` grid of independent real
+ * cells. Each formerly-covered cell becomes empty and real. Returns true when
+ * something was split. No-op (returns false) on a cell with no spans.
+ */
+declare function splitCell(ctx: CommandContext, blockIndex: number, row: number, col: number): boolean;
+/** Set the width (in CSS px) of a specific column. Auto-initializes `colWidths`. */
+declare function setColumnWidth(ctx: CommandContext, blockIndex: number, col: number, widthPx: number): void;
+/**
+ * Move the caret to the next cell of the same table (Tab). At the last cell of
+ * the last row, creates a new row and lands in its first cell. Returns true
+ * when handled. Caret must be inside a table for this to act.
+ */
+declare function moveToNextCell(ctx: CommandContext): boolean;
+/** Move the caret to the previous cell (Shift+Tab). At the first cell, no-op (returns true). */
+declare function moveToPrevCell(ctx: CommandContext): boolean;
+/**
+ * Insert an inline image embed at the current selection. Embeds occupy 1 char
+ * in offset arithmetic (Y.Text treats them as length-1 inserts).
+ */
+declare function insertImage(ctx: CommandContext, embed: ImageEmbed): void;
+/**
+ * Update attributes of an existing image embed at `(blockIndex, embedOffset)`.
+ * Implementation: delete the 1-char slot and re-insert the merged embed in the
+ * SAME transaction — Y.UndoManager coalesces delete+insert in one transact, so
+ * undo treats it as a single step.
+ *
+ * If `newOffset` is provided and differs from `embedOffset`, the embed is moved
+ * to that offset within the same block/cell. Used by wrap-left/wrap-right
+ * layouts which must anchor the image at the block start so floated text wraps
+ * around it (CSS float only flows text that comes AFTER the float in DOM order).
+ */
+declare function setImageAttrs(ctx: CommandContext, blockIndex: number, embedOffset: number, partial: Partial<ImageEmbed>, cellIndex?: number, newOffset?: number): void;
+declare function isCommandOrigin(origin: unknown): boolean;
+declare const TRACKED_ORIGINS: Set<unknown>;
+
+declare class EditorHistory {
+    readonly undoManager: Y.UndoManager;
+    constructor(doc: EditorDocument);
+    undo(): boolean;
+    redo(): boolean;
+    destroy(): void;
+}
+
+export { type AlignValue, BLOCK_SPECS, type BlockAttrs, type BlockType, COMMAND_ORIGIN, type CellAttrs, type CommandContext, type CommentAttr, DEFAULT_PAGE_SETTINGS, type DeltaOp, type DirValue, EditorDocument, EditorHistory, type ImageEmbed, type ImageLayout, type InsertContent, type LegacySerializedDocument, type LinkAttr, type ListKind, MARGIN_PRESETS, MAX_LIST_LEVEL, type MarkAttrs, type MarkName, type MarkValue, PAGE_PRESETS, type PagePreset, type PageSettings, type Position, type Selection, type SerializedBlock, type SerializedCell, type SerializedDocument, TRACKED_ORIGINS, type TableLocation, type TableRect, cellsInRect, clearRectCells, collapsedSelection, comparePositions, createBlock, createCell, createTableBlock, dedentList, defaultAttrsFor, deleteBackward, deleteForward, deleteTable, deleteTableColumn, deleteTableRow, deltaLength, detectPreset, expandTableRect, getMarksInRange, indentList, insertImage, insertParagraph, insertTable, insertTableColumn, insertTableRow, insertText, isCollapsed, isCommandOrigin, isImageEmbed, isKnownBlockType, isLegacySerializedDocument, isMarkUniformInRange, mergeDown, mergeRight, mergeSelection, mmToPx, moveToNextCell, moveToPrevCell, orderedRange, positionsEqual, pxToMm, removeMark, sameTextRun, setBlockAttr, setBlockType, setColumnWidth, setImageAttrs, setMark, sliceDelta, spanOf, splitCell, splitListItem, tableLocationOf, tableRectSelection, toggleList, toggleMark, withDefaults };