@sobree/core 0.1.0

package/dist/editor/internal/blockRegistry.d.ts

@@ -0,0 +1,91 @@
+import { BlockRef } from '../../doc/api';
+/**
+ * Per-block identity + version tracking.
+ *
+ * The Editor owns one BlockRegistry for its lifetime. Every block in the
+ * current body has a stable `id` (sequential strings like `"b1"`, `"b2"`)
+ * and a `version` that bumps on every modification. Indices shift as
+ * blocks are inserted / removed, but `id` doesn't.
+ *
+ * The whole registry is reset on `setDocument` / `openDocx`. It is NOT
+ * persisted — versions are a runtime-only contract.
+ *
+ * Pure data + arithmetic; no DOM access.
+ */
+export interface BlockRegistryOptions {
+    /**
+     * Prefix for newly-allocated ids. Default `"b"` produces `b1`, `b2`,
+     * … — fine for single-peer use. Phase 1b+ embedders pass a
+     * peer-unique prefix (e.g. `${ydoc.clientID.toString(36)}_`) so two
+     * peers don't both mint `b5` for different blocks.
+     */
+    idPrefix?: string;
+}
+export declare class BlockRegistry {
+    /** Per-block state, parallel to the body array. */
+    private entries;
+    /** Fast lookup by id. Points at the same objects as `entries`. */
+    private byId;
+    /** Next numeric suffix to allocate. Monotonic across `reset()` calls
+     *  so an id minted before a reset never collides with one minted
+     *  after. */
+    private nextNum;
+    /** String prepended to every newly-minted id. Constant for the
+     *  lifetime of the registry. */
+    private readonly idPrefix;
+    /** Document-wide monotonic counter — bumps on any modification. */
+    private docVersion;
+    constructor(opts?: BlockRegistryOptions);
+    /** Replace the registry for a fresh document of `blockCount` blocks. */
+    reset(blockCount: number): void;
+    /**
+     * Replace the registry from an explicit id list — used when adopting
+     * an existing Y.Doc's body (Phase 1b: peer joining an active room).
+     * The supplied ids are kept verbatim; future inserts continue to use
+     * the registry's own `idPrefix` so peer-minted ids stay distinct from
+     * adopted-foreign ids.
+     *
+     * `nextNum` is advanced past any local-prefix collisions found in
+     * the adopted set, so a future local insert can't shadow an adopted
+     * id.
+     */
+    adoptIds(ids: readonly string[]): void;
+    /** Number of blocks currently tracked. */
+    length(): number;
+    /** Current document counter (monotonic across all edits). */
+    documentVersion(): number;
+    /** Ref for the block at `index`. Throws on out-of-range. */
+    refAt(index: number): BlockRef;
+    /** Ref by id, or `null` if the id isn't live. */
+    refById(id: string): BlockRef | null;
+    /** Current body-index of the given id, or `-1` if not found. */
+    indexOf(id: string): number;
+    /** Whether `id` is currently live (not deleted). */
+    has(id: string): boolean;
+    /**
+     * Bump the version of the block at `index`. Bumps doc version too.
+     * Returns the new ref for the caller to pass back in results.
+     */
+    bump(index: number): BlockRef;
+    /**
+     * Insert a fresh entry at `index`, shifting subsequent entries right.
+     * The new entry starts at version 0. Bumps doc version.
+     */
+    insert(index: number): BlockRef;
+    /**
+     * Remove the entry at `index`, shifting subsequent entries left.
+     * Bumps doc version.
+     */
+    remove(index: number): void;
+    /**
+     * Replace everything at once — used by `syncFromDom` when the rebuild
+     * preserves identity but content may have changed per-block. Pass a
+     * parallel array of "did this block change" booleans; true entries
+     * bump; the registry itself doesn't know what changed.
+     *
+     * Callers that know nothing about diffs should call `.reset(n)` instead.
+     */
+    bumpChanged(changed: readonly boolean[]): void;
+    private allocEntry;
+    private newEntry;
+}

package/dist/editor/internal/mutations.d.ts

@@ -0,0 +1,63 @@
+import { Block, ParagraphProperties, RunProperties, SectionProperties, SobreeDocument } from '../../doc/types';
+import { ParagraphPropertiesPatch, WrapTag } from '../index';
+import { RunPropertiesPatch } from '../../doc/runs';
+/**
+ * One registry-level operation produced by a mutation. The caller
+ * applies these to the BlockRegistry after committing the new doc:
+ * `insert` adds an id, `remove` drops one, `bump` keeps the same id
+ * but increments its version.
+ */
+export type Mutation = {
+    type: "bump";
+    index: number;
+} | {
+    type: "insert";
+    index: number;
+} | {
+    type: "remove";
+    index: number;
+};
+/**
+ * Index in `sections` of the section that ENDS at the section_break at
+ * `breakIndex`. Sections are 1:1 with section_breaks; the first
+ * section ends at the first break (or at the end of `body` if there's
+ * no break).
+ *
+ *   body = [p, p, break, p, break, p]
+ *   sections = [s0, s1, s2]
+ *
+ *   breakIndex = 2 → 0 (the first break ends section 0)
+ *   breakIndex = 4 → 1 (the second break ends section 1)
+ */
+export declare function removedSectionIndex(body: readonly Block[], breakIndex: number): number;
+/**
+ * Drop the section at `endingIndex + 1` from `sections` — that's the
+ * section the now-removed break STARTED. The section ENDED by the
+ * removed break (at `endingIndex`) absorbs whatever content used to
+ * belong to its successor. Properties of the surviving section are
+ * preserved verbatim; nothing about the removed section's settings is
+ * carried over.
+ *
+ * If `sections` doesn't have a successor (the removed break was the
+ * last one and there's only one section), the array is returned
+ * unchanged.
+ */
+export declare function mergeSectionsAcross(sections: readonly SectionProperties[], endingIndex: number): SectionProperties[];
+/**
+ * Merge a `ParagraphPropertiesPatch` into existing properties.
+ * `undefined` in the patch removes a field; everything else
+ * overwrites.
+ */
+export declare function mergeParagraphProps(prev: ParagraphProperties, patch: ParagraphPropertiesPatch): ParagraphProperties;
+/**
+ * Map a semantic "wrap" tag to the run-property patch that achieves it.
+ * Same mapping the browser editor uses for toolbar buttons.
+ */
+export declare function wrapTagToPatch(tag: WrapTag): RunPropertiesPatch;
+/** Map an image MIME type to a `.docx` part filename extension. */
+export declare function mimeToExtension(mime: string): string;
+/** Find the next free `word/media/imageN.<ext>` slot in `rawParts`. */
+export declare function allocateMediaPath(doc: SobreeDocument, ext: string): string;
+/** Convert pixels (CSS @ 96 dpi) to OOXML's EMU (914400 per inch). */
+export declare function pxToEmu(px: number): number;
+export type { RunProperties };

package/dist/editor/internal/positionMap.d.ts

@@ -0,0 +1,35 @@
+import { InlinePosition, Range as ApiRange, Selection } from '../../doc/api';
+import { BlockRegistry } from './blockRegistry';
+/**
+ * Resolve a DOM point `(node, offset)` to an `InlinePosition`, or null
+ * if the point is outside the editor's tracked blocks.
+ *
+ * For table cells, returns an InlinePosition at the table block with
+ * `offset = 0` — block-internal table addressing is a future extension.
+ */
+export declare function positionFromDomPoint(hosts: readonly HTMLElement[], registry: BlockRegistry, node: Node, domOffset: number): InlinePosition | null;
+/** Build an API `Range` from a live DOM `Range`. */
+export declare function rangeFromDomRange(hosts: readonly HTMLElement[], registry: BlockRegistry, range: Range): ApiRange | null;
+/** Read `window.getSelection()` as a model `Selection`. */
+export declare function selectionFromDom(hosts: readonly HTMLElement[], registry: BlockRegistry): Selection;
+/** Resolve an `InlinePosition` to a DOM `{ node, offset }` point. */
+export declare function domPointFromPosition(hosts: readonly HTMLElement[], registry: BlockRegistry, pos: InlinePosition): {
+    node: Node;
+    offset: number;
+} | null;
+/** Apply a model `Selection` to `window.getSelection()`. */
+export declare function applySelectionToDom(hosts: readonly HTMLElement[], registry: BlockRegistry, selection: Selection): boolean;
+/** Total character-count length of a block, per the counting rules above. */
+export declare function blockLength(blockEl: Element): number;
+/**
+ * Enumerate blocks across all content hosts in document order,
+ * expanding `<ul>`/`<ol>` children as one block each. Returns the
+ * total block count.
+ */
+export declare function countBlocks(hosts: readonly HTMLElement[]): number;
+/**
+ * Return the DOM element that hosts a given block index. For list-item
+ * blocks this is the `<li>`; for everything else it's the direct host
+ * child.
+ */
+export declare function blockElementAtIndex(hosts: readonly HTMLElement[], index: number): HTMLElement | null;

package/dist/editor/table.d.ts

@@ -0,0 +1,96 @@
+import { BlockRef, EditResult } from '../doc/api';
+import { SobreeDocument, Block, ParagraphAlignment, Table, TableCell, TableProperties } from '../doc/types';
+/**
+ * Minimal slice of `Editor` that `EditorTable` actually needs. Defining
+ * it here (rather than `import type { Editor } from "./"`) keeps this
+ * module a leaf in the editor/* import graph — no cycle with index.ts.
+ */
+export interface EditorTableHost {
+    getDocument(): SobreeDocument;
+    getBlockById(id: string): {
+        kind: string;
+        index: number;
+    } | null;
+    replaceBlock(target: BlockRef, block: Block): EditResult<BlockRef>;
+}
+/**
+ * Pointer to one cell inside a table. `row`/`col` are **visual** indices
+ * (after expanding `gridSpan`) — the grid the user actually sees. Not a
+ * stable handle: indices shift as rows/columns are added or removed.
+ */
+export interface CellRef {
+    table: BlockRef;
+    row: number;
+    col: number;
+}
+/** Where an insertion should land, relative to an anchor row/column. */
+export type InsertAt = "start" | "end" | "before" | "after";
+export interface InsertRowOpts {
+    at: InsertAt;
+    /** Required for `"before"` / `"after"`. Visual row index of the anchor. */
+    index?: number;
+    /** Custom cells. Defaults to empty paragraphs, one per grid column. */
+    cells?: TableCell[];
+}
+export interface InsertColumnOpts {
+    at: InsertAt;
+    /** Required for `"before"` / `"after"`. Visual column index of the anchor. */
+    index?: number;
+    /** Width of the new column in twips. Default: average of existing columns, or 2400. */
+    widthTwips?: number;
+    /**
+     * When the target column falls inside an existing `gridSpan` cell, the
+     * default is to **extend** the span (the existing merge grows). Pass
+     * `split: true` to split the merge and insert a fresh cell instead.
+     */
+    split?: boolean;
+}
+export interface MergeCellsOpts {
+    /** Visual coordinates of the merge region's top-left corner. */
+    row: number;
+    col: number;
+    /** Number of visual rows the merge should span. Defaults to 1. */
+    rowSpan?: number;
+    /** Number of visual columns the merge should span. Defaults to 1. */
+    colSpan?: number;
+}
+/**
+ * Ergonomic table mutation surface. Lives on `editor.table`.
+ *
+ * Every method does the same three steps under the hood:
+ *   1. Resolve the target table by `BlockRef` (inherits optimistic-lock
+ *      checking from `editor.replaceBlock`).
+ *   2. Clone and mutate the table immutably.
+ *   3. Delegate to `editor.replaceBlock(ref, nextTable)`.
+ *
+ * No new plumbing; lock semantics, affected-block tracking, and event
+ * emission come from the underlying core.
+ */
+export declare class EditorTable {
+    private readonly editor;
+    constructor(editor: EditorTableHost);
+    insertRow(ref: BlockRef, opts: InsertRowOpts): EditResult<BlockRef>;
+    deleteRow(ref: BlockRef, index: number): EditResult<BlockRef>;
+    insertColumn(ref: BlockRef, opts: InsertColumnOpts): EditResult<BlockRef>;
+    deleteColumn(ref: BlockRef, index: number): EditResult<BlockRef>;
+    mergeCells(ref: BlockRef, opts: MergeCellsOpts): EditResult<BlockRef>;
+    unmergeCell(cell: CellRef): EditResult<BlockRef>;
+    setCellContent(cell: CellRef, content: Block[]): EditResult<BlockRef>;
+    setCellProperties(cell: CellRef, patch: Partial<Omit<TableCell, "content">>): EditResult<BlockRef>;
+    setColumnWidth(ref: BlockRef, col: number, widthTwips: number): EditResult<BlockRef>;
+    toggleHeaderRow(ref: BlockRef, row: number): EditResult<BlockRef>;
+    setProperties(ref: BlockRef, patch: Partial<TableProperties>): EditResult<BlockRef>;
+    private getTable;
+    private updateCell;
+}
+/**
+ * Given a `(row, col)` in *visual* coordinates, find which TableCell in
+ * `row.cells` holds that position, accounting for `gridSpan`.
+ */
+export declare function cellAtVisual(table: Table, row: number, col: number): {
+    cellIndex: number;
+    cell: TableCell;
+    startCol: number;
+} | null;
+/** Used internally by alignment setters in the toolbar. */
+export type TableCellAlignment = ParagraphAlignment;

package/dist/editor/view/docRenderer/anchorLayer.d.ts

@@ -0,0 +1,26 @@
+import { AnchoredFrame, Block } from '../../../doc/types';
+export interface AnchorLayerContext {
+    /** Map ZIP-path → bytes, used to mint blob URLs for picture content. */
+    rawParts: Record<string, Uint8Array>;
+    /**
+     * Reuse picture URLs across calls so the same image isn't re-blobbed
+     * every render. The caller (PaperStack) owns the map.
+     */
+    pictureUrlCache: Map<string, string>;
+    /**
+     * Render a textbox's `Block[]` body into a host element. Injected by
+     * the caller (PaperStack wires in `renderBlocks`) so this module
+     * stays decoupled from the heavy block renderer — anchorLayer only
+     * knows the AnchoredFrame model + DOM, not the full paragraph/list/
+     * table pipeline. When absent, textbox bodies render as plain
+     * stacked text (test/headless fallback).
+     */
+    renderBody?: (blocks: Block[], host: HTMLElement) => void;
+}
+/**
+ * Build the per-page anchor layer. Returns a single `<div>` whose
+ * children are the frames — render order = z-stack order (later
+ * siblings paint on top). The wrapper itself is `position: absolute`
+ * inset:0 inside the paper-content area.
+ */
+export declare function renderAnchorLayer(frames: readonly AnchoredFrame[], ctx: AnchorLayerContext): HTMLElement;

package/dist/editor/view/docRenderer/block.d.ts

@@ -0,0 +1,13 @@
+import { Block, NamedStyle, NumberingDefinition, SectionProperties } from '../../../doc/types';
+/**
+ * Render a `Block[]` stream into `host`, grouping consecutive paragraphs
+ * that share a `numId` into a single `<ul>`/`<ol>` so the browser renders
+ * proper list markers.
+ *
+ * `numbering` maps `numId` → definition so we can decide ordered vs
+ * bulleted. Unknown numIds fall back to `<ul>`.
+ *
+ * `rawParts` is threaded to image rendering so `<img src>` can be
+ * populated from embedded bytes via a blob URL.
+ */
+export declare function renderBlocks(blocks: readonly Block[], host: HTMLElement, numbering: readonly NumberingDefinition[], styles?: readonly NamedStyle[], rawParts?: Record<string, Uint8Array>, blockIds?: readonly string[], sections?: readonly SectionProperties[]): void;

package/dist/editor/view/docRenderer/fontFallback.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Build a CSS `font-family` value with metric-compatible fallbacks.
+ *
+ * Why: when a docx specifies `font-family: "Bookman Old Style"` and
+ * the host machine doesn't have it installed, the browser picks an
+ * arbitrary system serif. The fallback may have a much taller natural
+ * ascender+descender than the requested font — and CSS's line-box
+ * height = `max(line-height, font-strut-height)`, so the line box
+ * inflates beyond the declared `line-height`. That cumulative inflation
+ * shifts pagination decisions (a single docx ends up taking more pages
+ * than Word produces).
+ *
+ * The fix: emit a fallback chain whose members have metrics close to
+ * the primary font. Georgia is metrically near Bookman; Helvetica Neue
+ * near Calibri; etc. The chain ends in a generic family so we never
+ * fall off the cliff into the browser's last-resort serif/sans pick.
+ *
+ * Diagnosis trail: per-block height inflation surfaced via
+ * `pnpm fixtures:compare --pages` on user-contract.docx (Bookman not
+ * installed on macOS by default). See [diagnosis notes].
+ */
+/**
+ * Wrap `fontFamily` in quotes if it contains spaces or unusual
+ * characters, and append a metric-compatible fallback chain. If the
+ * font already matches a curated entry, use that chain directly so the
+ * primary font isn't double-listed.
+ */
+export declare function withFallbacks(fontFamily: string): string;

package/dist/editor/view/docRenderer/index.d.ts

@@ -0,0 +1,18 @@
+import { SobreeDocument } from '../../../doc/types';
+/**
+ * Walk a SobreeDocument's body into `host`, replacing its existing
+ * children. List grouping, heading style mapping, and image resolution
+ * live downstream in `block.ts` / `inline.ts`.
+ *
+ * Footnotes (when present) render as an `<aside class="sobree-footnotes">`
+ * appended *after* the body content. True per-page pinning of footnotes
+ * is a paginator feature deferred until a fixture demands it; for now
+ * the references in body text link to footnote bodies at the doc end.
+ *
+ * Comments are NOT rendered here — core only emits the neutral inline
+ * `<span class="sobree-comment-range">` marks (in `inline.ts`). The
+ * `@sobree/review` plugin reads those marks + `doc.comments` to render
+ * the comment cards. Without the plugin, commented text is still
+ * highlighted; there's just no card surface.
+ */
+export declare function renderSobreeDocument(doc: SobreeDocument, host: HTMLElement, blockIds?: readonly string[]): void;

package/dist/editor/view/docRenderer/inline.d.ts

@@ -0,0 +1,15 @@
+import { InlineRun } from '../../../doc/types';
+/**
+ * Render a list of InlineRuns into DOM children of `parent`. Empty run
+ * lists produce a `<br>` placeholder so contenteditable can place a
+ * caret in the paragraph.
+ *
+ * `rawParts` is threaded through so `DrawingRun` can resolve its
+ * `partPath` to an `<img src>` via a blob URL / data URI.
+ */
+export declare function appendInlineRuns(parent: HTMLElement, runs: readonly InlineRun[], rawParts?: Record<string, Uint8Array>): void;
+/** Convert a raw part's bytes (from `doc.rawParts`) into a blob URL
+ *  the browser can render as `<img src>` / `background-image`. Exported
+ *  for the section-frame renderer in `block.ts` which paints the
+ *  `framePictures` background outside the inline-run code path. */
+export declare function partPathToUrl(partPath: string, rawParts: Record<string, Uint8Array>): string | null;

package/dist/editor/view/docRenderer/inlineFrame.d.ts

@@ -0,0 +1,4 @@
+import { Block, InlineFrame, NamedStyle, NumberingDefinition } from '../../../doc/types';
+/** The recursive block renderer, injected to break the import cycle. */
+export type RenderBody = (blocks: readonly Block[], host: HTMLElement, numbering: readonly NumberingDefinition[], styles: readonly NamedStyle[], rawParts: Record<string, Uint8Array>) => void;
+export declare function renderInlineFrameBlock(frame: InlineFrame, numbering: readonly NumberingDefinition[], styles: readonly NamedStyle[], rawParts: Record<string, Uint8Array>, renderBody: RenderBody): HTMLElement;

package/dist/editor/view/docRenderer/lists.d.ts

@@ -0,0 +1,28 @@
+import { Block, NumberingDefinition } from '../../../doc/types';
+export interface ListInfo {
+    numId: number;
+    ordered: boolean;
+    /** Effective left indent (text wrap position) for this list level,
+     *  in twips — from the numbering definition's `<w:lvl><w:pPr><w:ind>`.
+     *  Applied as `padding-left` on the OL / UL so wrapped text lands at
+     *  the right position and the marker hangs to its left. */
+    leftTwips?: number;
+    /** Twips the FIRST line hangs to the left of `leftTwips` (= `@w:hanging`).
+     *  The marker sits at `(leftTwips - hangingTwips)` from the content edge. */
+    hangingTwips?: number;
+    /** The level's lvlText glyph (post-Wingdings remapping), for bullets. */
+    bulletGlyph?: string;
+}
+/**
+ * Resolve a paragraph's list membership from the numbering table.
+ * Returns `null` for non-list paragraphs (no `numbering` property or
+ * a `numId` not present in `numbering`).
+ */
+export declare function paragraphListInfo(block: Block, numbering: readonly NumberingDefinition[]): ListInfo | null;
+/**
+ * Build the `<ol>` / `<ul>` container for a run of list items sharing
+ * a `numId`. Sets marker geometry (padding-left + hanging custom
+ * property) and bullet glyph (native CSS keyword where one exists,
+ * else a `::marker`-content custom property).
+ */
+export declare function createListContainer(info: ListInfo, sectionIndex: number): HTMLElement;

package/dist/editor/view/docRenderer/paragraph.d.ts

@@ -0,0 +1,2 @@
+import { NamedStyle, Paragraph } from '../../../doc/types';
+export declare function renderParagraph(p: Paragraph, styles: readonly NamedStyle[], rawParts: Record<string, Uint8Array>): HTMLElement;

package/dist/editor/view/docRenderer/properties.d.ts

@@ -0,0 +1,2 @@
+import { NamedStyle, ParagraphProperties } from '../../../doc/types';
+export declare function applyParagraphProps(el: HTMLElement, props: ParagraphProperties, styles?: readonly NamedStyle[]): void;

package/dist/editor/view/docRenderer/table.d.ts

@@ -0,0 +1,15 @@
+import { NamedStyle, NumberingDefinition, Table } from '../../../doc/types';
+/**
+ * Render a Table to a `<table>` element. `vMerge: "restart"` cells
+ * emit with `rowspan=N` computed from the following `"continue"` cells
+ * in the same column. `"continue"` cells render nothing — their column
+ * is covered by the spanned restart cell above.
+ *
+ * `styles` + `numbering` thread through so each cell's paragraphs go
+ * through the full cascade (line-height, spacing, alignment, font from
+ * style). Without this, table-cell paragraphs would render flat
+ * (visible bug: BodyText-styled paragraphs inside cells lost their
+ * 1.5× line-height because the cell's own renderer ignored per-paragraph
+ * properties).
+ */
+export declare function renderTable(table: Table, numbering?: readonly NumberingDefinition[], styles?: readonly NamedStyle[], rawParts?: Record<string, Uint8Array>): HTMLElement;

package/dist/editor/view/docRenderer/units.d.ts

@@ -0,0 +1,48 @@
+/**
+ * OOXML measurement units → CSS conversions, in one place.
+ *
+ * OOXML mixes three length units:
+ *   - EMU   (English Metric Units): 914400 per inch. Used by DrawingML
+ *           (`<a:off>`, `<a:ext>`, `<wp:extent>`, picture sizes).
+ *   - twips (twentieths of a point): 1440 per inch. Used by
+ *           WordprocessingML (`<w:ind>`, `<w:spacing>`, `<w:tblW>`).
+ *   - half-points / eighths-of-point: font + border sizes (handled
+ *           at their own call sites; not length conversions).
+ *
+ * Derived constants (all exact):
+ *   - 1 inch = 25.4 mm = 96 px (CSS reference pixel) = 914400 EMU = 1440 twips
+ *   - 914400 / 25.4 = 36000  EMU per mm
+ *   - 914400 / 96    = 9525   EMU per px
+ *
+ * Rounding is a SEPARATE concern from conversion. These helpers return
+ * exact values; call sites that want integer mm / px (e.g. for crisp
+ * image edges, or to match a historical snapshot) round explicitly.
+ */
+export declare const EMU_PER_INCH = 914400;
+export declare const TWIPS_PER_INCH = 1440;
+export declare const MM_PER_INCH = 25.4;
+export declare const PX_PER_INCH = 96;
+/** 914400 / 25.4 = 36000, pinned as an integer literal. Computing it
+ *  as `914400 / 25.4` risks float drift (25.4 isn't exactly
+ *  representable), which would change emitted CSS strings vs the
+ *  literal `36000` the renderer used before this module existed. */
+export declare const EMU_PER_MM = 36000;
+/** 914400 / 96 = 9525, exact. */
+export declare const EMU_PER_PX = 9525;
+/** EMU → millimetres, exact. */
+export declare function emuToMm(emu: number): number;
+/** EMU → CSS pixels, exact. */
+export declare function emuToPx(emu: number): number;
+/**
+ * Twips → millimetres, ROUNDED to the nearest whole millimetre.
+ *
+ * Word's body-geometry values (indents, spacing, column gaps) are
+ * authored in whole points / mm and survive a round-trip as twips;
+ * rounding to integer mm here keeps the emitted CSS stable (`5mm`,
+ * not `4.97mm`) and matches the renderer's long-standing output that
+ * the oracle snapshots are blessed against. Callers needing sub-mm
+ * precision should use `twipsToMmExact`.
+ */
+export declare function twipsToMm(twips: number): number;
+/** Twips → millimetres, exact (no rounding). */
+export declare function twipsToMmExact(twips: number): number;

package/dist/editor/view/docSerialize/block.d.ts

@@ -0,0 +1,14 @@
+import { Block, NumberingDefinition } from '../../../doc/types';
+export interface BlockSerializeContext {
+    /** Accumulated numbering definitions, one per encountered list. */
+    numbering: NumberingDefinition[];
+    /**
+     * Allocated numId for the CURRENT list stream. Reset to `null` by the
+     * caller between lists.
+     */
+    currentList: {
+        numId: number;
+        ordered: boolean;
+    } | null;
+}
+export declare function blocksFromNodes(nodes: readonly Node[], ctx: BlockSerializeContext): Block[];

package/dist/editor/view/docSerialize/index.d.ts

@@ -0,0 +1,8 @@
+import { SobreeDocument } from '../../../doc/types';
+/**
+ * Serialise DOM content across one or more host elements (in document
+ * order) into a SobreeDocument. Sections / headers / footers are NOT
+ * produced here — the Sobree façade injects those from its current page
+ * setup state before handing the document off to the exporter.
+ */
+export declare function serializeHostsToDocument(hosts: readonly HTMLElement[]): SobreeDocument;

package/dist/editor/view/docSerialize/inline.d.ts

@@ -0,0 +1,11 @@
+import { InlineRun } from '../../../doc/types';
+/**
+ * Serialise DOM children of `el` into a flat `InlineRun[]`. Nested
+ * formatting wrappers (`<strong><em>...`) are flattened — each leaf text
+ * node yields one `TextRun` whose `RunProperties` is the union of all
+ * formatting seen on the path from `el` to that text node.
+ *
+ * `<a>` elements produce a `HyperlinkRun` wrapping recursively-serialised
+ * children (their own flat run list).
+ */
+export declare function serializeInlineChildren(el: HTMLElement): InlineRun[];

package/dist/editor/view/docSerialize/table.d.ts

@@ -0,0 +1,12 @@
+import { Table } from '../../../doc/types';
+/**
+ * Convert a `<table>` back into a Table AST node.
+ *
+ * The AST mirrors OOXML's row/cell model: every visual cell, including
+ * cells occluded by a vertical merge above them, is represented as its
+ * own `TableCell` (with `vMerge: "continue"` for the occluded ones and
+ * `vMerge: "restart"` on the cell that spans them). The DOM's
+ * `rowspan` attribute collapses multiple rows into a single `<td>`; we
+ * synthesize the continuation cells back here.
+ */
+export declare function tableFromElement(el: HTMLElement): Table;

package/dist/editor/view/imageResize.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Click-to-select-and-drag-the-corner image resizing.
+ *
+ * Implementation:
+ *   - Listen for clicks inside the editor host. If an `<img>` was clicked,
+ *     mark it as selected (one image at a time) and show a single
+ *     bottom-right corner handle absolutely positioned over its corner.
+ *   - The handle is a sibling of the image (not a child — the image is
+ *     replaced/edited as content), tracked in a closure so we can move
+ *     it as the page scrolls or paginates.
+ *   - Dragging the handle updates the image's `width`/`height` styles in
+ *     real time, preserving aspect ratio (hold Shift to free).
+ *   - On mouseup we dispatch an `input` event on the host so the editor's
+ *     existing debounced change pipeline picks up the new dimensions.
+ */
+export declare function attachImageResize(host: HTMLElement): () => void;

package/dist/embed/floatingCorner.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared floating-corner stack — a flex container per (host, corner)
+ * that plugins append floating UIs to so multiple docks in the same
+ * corner stack predictably instead of overlapping.
+ *
+ * The problem this solves: `@sobree/zoom-controls`, `@sobree/review`'s
+ * dock, a future toast/notification plugin, etc. all want to anchor
+ * to a corner of the rendering area. Each appending directly to the
+ * host with `position: absolute` makes them collide.
+ *
+ * Each corner gets its own `<div class="sobree-floating-corner">`
+ * created on first use. The container's flex direction is chosen so
+ * the *first* item added sits hugging the corner, and subsequent
+ * items grow toward the centre:
+ *
+ *   top-right    →  flex-direction: column           (grows downward)
+ *   top-left     →  flex-direction: column           (grows downward)
+ *   bottom-right →  flex-direction: column-reverse   (grows upward)
+ *   bottom-left  →  flex-direction: column-reverse   (grows upward)
+ *
+ * This keeps the "primary" floating UI nearest the corner regardless
+ * of which side it lives on, which matches user intuition for a
+ * docked toolbar.
+ *
+ * The host must be `position: relative` (or otherwise establish a
+ * containing block); the corner container uses `position: absolute`
+ * to pin to the edge. The function does NOT modify the host's
+ * positioning — that's the host owner's responsibility.
+ */
+export type FloatingCornerPlacement = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/**
+ * Return the flex container for `placement` inside `host`, creating
+ * it on first call. Subsequent calls with the same `(host, placement)`
+ * pair return the same element — so plugins can `appendChild` their
+ * floating UI and trust they'll stack with other corner-residents
+ * rather than overlap them.
+ *
+ * The returned element's contents are managed by the appending
+ * plugins; this function only owns the container itself. To remove
+ * a floating UI, just `.remove()` it — the container stays alive for
+ * other tenants. Empty containers are inexpensive (4-byte `<div>` per
+ * corner per host) so we don't garbage-collect them.
+ */
+export declare function getFloatingCorner(host: HTMLElement, placement: FloatingCornerPlacement): HTMLElement;