@forevka/wordcanvas 0.8.1 → 0.9.0

package/dist-node/{engine-46GL2RKU.js → engine-QKH45ZHY.js}

@@ -5,11 +5,12 @@ const require = __createRequire(import.meta.url);
 const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import {
-  createLayoutEngine,
+  createLayoutEngine
+} from "./chunk-VNDCELYX.js";
+import {
   effectiveSection,
   resolveSections
-} from "./chunk-KZHUXFDE.js";
-import "./chunk-HMBQQDXD.js";
+} from "./chunk-TLGEFCLV.js";
 import "./chunk-K43IQCP2.js";
 import "./chunk-XSRSBST2.js";
 export {
@@ -17,4 +18,4 @@ export {
   effectiveSection,
   resolveSections
 };
-//# sourceMappingURL=engine-46GL2RKU.js.map
+//# sourceMappingURL=engine-QKH45ZHY.js.map

package/dist-node/export.js

@@ -45,7 +45,7 @@ import {
 } from "./chunk-5PUCGN47.js";
 import {
   createLayoutEngine
-} from "./chunk-KZHUXFDE.js";
+} from "./chunk-VNDCELYX.js";
 import {
   DEFAULT_CHAR_STYLE,
   detectTocHeadings,
@@ -53,7 +53,7 @@ import {
   parseTocInstruction,
   styleType,
   textOfRuns
-} from "./chunk-HMBQQDXD.js";
+} from "./chunk-TLGEFCLV.js";
 import {
   ARABIC_FONT_FAMILY,
   CJK_FONT_FAMILY,
@@ -24725,7 +24725,7 @@ async function renderPdf(doc, opts = {}) {
 }
 async function renderPdfInner(doc, opts, fontReg) {
   await installMeasureHost();
-  const { createLayoutEngine: createLayoutEngine2 } = await import("./engine-46GL2RKU.js");
+  const { createLayoutEngine: createLayoutEngine2 } = await import("./engine-QKH45ZHY.js");
   const tree = createLayoutEngine2(fontReg, opts.cjk).layout(doc);
   const warnings = new WarningSink();
   const images = opts.images ?? {};

package/dist-node/generate-toc.js

@@ -6,7 +6,7 @@ const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import {
   runImport
-} from "./chunk-JVSPB6WM.js";
+} from "./chunk-A53KB3BE.js";
 import {
   el,
   escapeText,
@@ -28,14 +28,14 @@ import {
 } from "./chunk-5PUCGN47.js";
 import {
   createLayoutEngine
-} from "./chunk-KZHUXFDE.js";
+} from "./chunk-VNDCELYX.js";
 import {
   detectTocHeadings,
   inRange,
   parseTocInstruction,
   textOfRuns,
   tocEntryStyle
-} from "./chunk-HMBQQDXD.js";
+} from "./chunk-TLGEFCLV.js";
 import "./chunk-K43IQCP2.js";
 import "./chunk-XSRSBST2.js";
 

package/dist-node/import.js

@@ -6,10 +6,10 @@ const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import {
   runImport
-} from "./chunk-JVSPB6WM.js";
+} from "./chunk-A53KB3BE.js";
 import "./chunk-5I6FZZ5U.js";
 import "./chunk-5PUCGN47.js";
-import "./chunk-HMBQQDXD.js";
+import "./chunk-TLGEFCLV.js";
 import "./chunk-XSRSBST2.js";
 export {
   runImport

package/dist-node/recalc-docx.js

@@ -18,8 +18,8 @@ import {
 } from "./chunk-5PUCGN47.js";
 import {
   createLayoutEngine
-} from "./chunk-KZHUXFDE.js";
-import "./chunk-HMBQQDXD.js";
+} from "./chunk-VNDCELYX.js";
+import "./chunk-TLGEFCLV.js";
 import "./chunk-K43IQCP2.js";
 import "./chunk-XSRSBST2.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forevka/wordcanvas",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
   "description": "Open-source embeddable Word-style document editor: canvas-rendered, with live collaboration, track changes & comments, and DOCX/PDF import & export. A lightweight alternative to Syncfusion, OnlyOffice, and DevExpress document editors. Self-contained, zero runtime dependencies.",
   "license": "MIT",
@@ -39,7 +39,7 @@
   ],
   "module": "./dist-lib/wordcanvas.js",
   "types": "./types/wordcanvas.d.ts",
-  "//exports": "Dual-target, all compiled — no raw src ships. `.`/`./builder` are the browser editor (Vite → dist-lib). The headless pipelines (import/export/measure/recalc-docx/generate-toc) are isomorphic and exposed via conditional exports: the `node` condition resolves a self-contained, Node-targeted bundle (scripts/build-node.mjs → dist-node, with disk fonts + bundled pdfkit) for server/headless use; the `default` condition resolves the browser variant (Vite → dist-lib). Hand-written types/ keeps the published .d.ts self-contained (no @cw/shared import). The in-repo backend consumes the `node` build through this map (no tsconfig path aliases).",
+  "//exports": "Dual-target, all compiled — no raw src ships. `.`/`./builder`/`./query` are the browser editor (Vite → dist-lib); `./query` is the document query + edit + page API. The headless pipelines (import/export/measure/recalc-docx/generate-toc) are isomorphic and exposed via conditional exports: the `node` condition resolves a self-contained, Node-targeted bundle (scripts/build-node.mjs → dist-node, with disk fonts + bundled pdfkit) for server/headless use; the `default` condition resolves the browser variant (Vite → dist-lib). Hand-written types/ keeps the published .d.ts self-contained (no @cw/shared import). The in-repo backend consumes the `node` build through this map (no tsconfig path aliases).",
   "exports": {
     ".": {
       "types": "./types/wordcanvas.d.ts",
@@ -49,6 +49,10 @@
       "types": "./types/builder.d.ts",
       "import": "./dist-lib/builder.js"
     },
+    "./query": {
+      "types": "./types/query.d.ts",
+      "import": "./dist-lib/query.js"
+    },
     "./import": {
       "types": "./types/import.d.ts",
       "node": "./dist-node/import.js",

package/types/builder.d.ts

@@ -9,7 +9,7 @@
 // Works in the browser (live preview via WordCanvas.setDocument) and in Node
 // (server-side DOCX/PDF generation via the export subpath).
 
-import type { CellBorders, CellMargin, CharStyle, Document, NamedStyle, ParaBorders, ParaStyle, Stylesheet, TableCondOverrides, TableStyle, TabStop } from "./model";
+import type { CellBorders, CellMargin, CharStyle, Document, NamedStyle, PageNumFmt, ParaBorders, ParaStyle, SdtProps, Stylesheet, TableCondOverrides, TableStyle, TabStop } from "./model";
 
 export type { Block, CharStyle, Document, NamedStyle, ParaStyle, Stylesheet, TableCondOverrides, TableStyle, TabStop } from "./model";
 
@@ -204,6 +204,48 @@ export declare class ParagraphBuilder<P extends StoryBuilder> {
   inlineEquation(latex: string, style?: Partial<CharStyle>): this;
   /** Append an inline equation from a presentation-MathML string. */
   inlineEquationMathml(mathml: string, style?: Partial<CharStyle>): this;
+  // ---- inline content controls (OOXML w:sdt) ----
+  /** Append an inline content control wrapping `text` with explicit properties. */
+  contentControl(props: SdtProps, text: string, style?: Partial<CharStyle>): this;
+  /** A rich-text content control. */
+  richTextControl(text: string, opts?: { alias?: string; tag?: string }): this;
+  /** A plain-text content control. */
+  plainTextControl(text: string, opts?: { alias?: string; tag?: string }): this;
+  /** A checkbox content control (☒/☐). */
+  checkbox(checked: boolean, opts?: { alias?: string; tag?: string }): this;
+  /** A drop-down content control (fixed list of `{ display, value }` items). */
+  dropDown(selected: string, items: { display: string; value: string }[], opts?: { alias?: string; tag?: string }): this;
+  /** A combo-box content control (list + free text). */
+  comboBox(selected: string, items: { display: string; value: string }[], opts?: { alias?: string; tag?: string }): this;
+  /** A date-picker content control. */
+  dateControl(text: string, dateFormat?: string, opts?: { alias?: string; tag?: string }): this;
+  // ---- inline fields (OOXML complex fields) ----
+  /** The current page number (PAGE field), resolved at layout. */
+  pageField(numFmt?: PageNumFmt): this;
+  /** The total page count (NUMPAGES field), resolved at layout. */
+  numPagesField(numFmt?: PageNumFmt): this;
+  /** A DATE field with a Word/.NET-style format (default "M/d/yyyy"). */
+  dateField(format?: string): this;
+  /** A TIME field with a Word/.NET-style format (default "h:mm AM/PM"). */
+  timeField(format?: string): this;
+  /** A custom (host-resolved) field: verbatim instruction + cached result text. */
+  customField(instruction: string, resultText: string): this;
+  /** A conditional (IF) field — branch text by comparing two operands. */
+  ifField(operandA: string, op: "=" | "<>" | "<" | "<=" | ">" | ">=", operandB: string, ifTrue: string, ifFalse: string): this;
+  /** A cross-reference to a bookmark (REF, or PAGEREF when `pageRef`). */
+  crossReference(bookmarkName: string, opts?: { kind?: "ref" | "pageRef" }): this;
+  // ---- bookmarks + notes ----
+  /** Append text and bookmark exactly that run's range. */
+  bookmark(name: string, text: string, style?: Partial<CharStyle>): this;
+  /** Append an auto-numbered footnote (single-paragraph body, or built via callback). */
+  footnote(text: string): this;
+  footnote(build: (s: StoryBuilder) => void): this;
+  /** Append an auto-numbered endnote (collected at the document end). */
+  endnote(text: string): this;
+  endnote(build: (s: StoryBuilder) => void): this;
+  /** Sub/superscript (measured smaller, baseline-shifted). */
+  superscript(on?: boolean): this;
+  subscript(on?: boolean): this;
   align(align: ParaStyle["align"]): this;
   spacing(opts: SpacingOptions): this;
   indent(opts: IndentOptions): this;
@@ -252,8 +294,11 @@ export declare class TableBuilder {
 }
 
 export declare class RowBuilder {
-  cell(content: CellContent, opts?: CellOptions): this;
+  // The build (callback) overload is listed FIRST so a `(s) => …` arrow binds to it
+  // and `s` types as StoryBuilder — CellSpec's fields are all optional, so a function
+  // would otherwise match the `content: CellContent` overload and shadow the callback.
   cell(build: (s: StoryBuilder) => void, opts?: CellOptions): this;
+  cell(content: CellContent, opts?: CellOptions): this;
 }
 
 /** Root of the fluent builder. Produces the same plain-data Document the

package/types/model.d.ts

@@ -323,11 +323,45 @@ export interface DocPosition {
   offset: number;
 }
 
+export interface DocSelection {
+  anchor: DocPosition;
+  focus: DocPosition;
+  /** Preserved X column for Up/Down caret movement. */
+  goalX?: number;
+}
+
 export interface BookmarkRange {
   start: DocPosition;
   end: DocPosition;
 }
 
+/** OOXML page-number / list format (the field `\* <fmt>` switch). */
+export type PageNumFmt = "arabic" | "roman" | "Roman" | "alpha" | "Alpha";
+/** IF-field comparison operators. */
+export type IfOp = "=" | "<>" | "<" | ">" | "<=" | ">=";
+
+/** Typed, parsed form of a BUILT-IN field's definition (drives the field UI + the
+ *  evaluator). TOC keeps its own path and is not here. */
+export type FieldSpec =
+  | { type: "PAGE"; numFmt?: PageNumFmt }
+  | { type: "NUMPAGES"; numFmt?: PageNumFmt }
+  | { type: "DATE"; format: string }
+  | { type: "TIME"; format: string }
+  | { type: "IF"; operandA: string; op: IfOp; operandB: string; trueRuns: Run[]; falseRuns: Run[] };
+
+/** A generic OOXML field tracked in the model (custom host-resolved + built-in).
+ *  Its result is the blocks/runs carrying its `id` as `fieldId`. */
+export interface FieldDef {
+  id: string;
+  /** Verbatim w:instrText, re-emitted on export. */
+  instruction: string;
+  /** Field keyword, uppercased (the first instruction token). */
+  name: string;
+  kind: "builtin" | "custom";
+  /** Parsed spec for built-ins the editor understands; absent for opaque fields. */
+  spec?: FieldSpec;
+}
+
 export type SdtType = "richText" | "plainText" | "checkbox" | "dropDown" | "comboBox" | "date";
 
 export interface SdtProps {

package/types/query.d.ts

@@ -0,0 +1,416 @@
+// Public type surface for @forevka/wordcanvas/query — the document query + edit
+// API (the rough analog of .NET's WordprocessingDocument access). Hand-written,
+// self-contained (model types come from ./model, shared with wordcanvas.d.ts).
+//
+//   import { findParagraphs, DocumentEditor, getPages } from "@forevka/wordcanvas/query";
+//   const ed = new DocumentEditor(doc);
+//   for (const m of findParagraphs(ed.doc, "DRAFT")) ed.setParagraphText(m.paragraph.id, "FINAL");
+
+import type {
+  BandContainer,
+  Block,
+  BookmarkRange,
+  CharStyle,
+  Document,
+  DocPosition,
+  DocSelection,
+  FieldDef,
+  ImageBlock,
+  NamedStyle,
+  Paragraph,
+  ParaStyle,
+  Run,
+  SdtProps,
+  SectionProps,
+  TableBlock,
+} from "./model";
+
+export type {
+  BandContainer,
+  Block,
+  BookmarkRange,
+  CharStyle,
+  Document,
+  DocPosition,
+  DocSelection,
+  EquationBlock,
+  FieldDef,
+  FieldSpec,
+  ImageBlock,
+  NamedStyle,
+  Paragraph,
+  ParaStyle,
+  Run,
+  SdtProps,
+  SdtType,
+  SectionProps,
+  TableBlock,
+} from "./model";
+
+// ---------------------------------------------------------------------------
+// Traversal / query
+
+/** A top-level story: the body or one of the six header/footer band stories.
+ *  Note bodies report `"body"` and set `note` instead. */
+export type Container = "body" | BandContainer;
+
+/** A table cell coordinate. */
+export interface CellRef {
+  tableId: string;
+  row: number;
+  col: number;
+}
+
+/** Where a visited block sits. `cell`/`note` are set when the block is nested
+ *  below the top level of its story. */
+export interface BlockContext {
+  container: Container;
+  /** Set when the block lives inside a table cell (innermost cell if nested). */
+  cell?: CellRef;
+  /** Full cell ancestry outer→inner, present only for a block nested ≥2 cells deep
+   *  (a table within a cell); single-cell blocks keep the simple `{ cell }` shape. */
+  cellPath?: CellRef[];
+  /** Set when the block belongs to a footnote/endnote body. */
+  note?: { kind: "footnote" | "endnote"; id: string };
+}
+
+export type BlockVisitor = (block: Block, ctx: BlockContext) => void;
+
+/** Where a visited run sits: its paragraph context plus the paragraph, run index,
+ *  and full enclosing content-control chain (outer→inner). */
+export interface RunContext extends BlockContext {
+  block: Paragraph;
+  runIndex: number;
+  sdtChain: string[];
+}
+export type RunVisitor = (run: Run, ctx: RunContext) => void;
+
+/** Which stories `walk` descends into. All default to `true`. */
+export interface WalkOptions {
+  bands?: boolean;
+  notes?: boolean;
+  cells?: boolean;
+}
+
+export interface ParagraphMatch {
+  paragraph: Paragraph;
+  /** The paragraph's concatenated run text (what was tested). */
+  text: string;
+  context: BlockContext;
+}
+
+export interface ResolvedSection {
+  index: number;
+  props: SectionProps;
+  startBlock: number;
+  endBlock: number;
+  breakType: "nextPage" | "evenPage" | "oddPage";
+}
+
+/** Visit every block, descending (by default) into table cells, header/footer
+ *  bands, and note bodies. */
+export declare function walk(doc: Document, visit: BlockVisitor, options?: WalkOptions): void;
+/** Visit every run (paragraphs only) with its paragraph context + full sdt chain. */
+export declare function walkRuns(doc: Document, visit: RunVisitor, options?: WalkOptions): void;
+/** Plain text of a block (tables join cells with tabs, rows with newlines). */
+export declare function textOf(block: Block): string;
+export declare function getParagraphs(doc: Document, options?: WalkOptions): Paragraph[];
+export declare function getTables(doc: Document, options?: WalkOptions): TableBlock[];
+export declare function getImages(doc: Document, options?: WalkOptions): ImageBlock[];
+/** Find paragraphs by substring or RegExp; each match carries its context. */
+export declare function findParagraphs(doc: Document, pattern: string | RegExp, options?: WalkOptions): ParagraphMatch[];
+export declare function getBlockById(doc: Document, id: string, options?: WalkOptions): Block | undefined;
+export declare function getParagraphById(doc: Document, id: string, options?: WalkOptions): Paragraph | undefined;
+export declare function getTableById(doc: Document, id: string, options?: WalkOptions): TableBlock | undefined;
+export declare function getImageById(doc: Document, id: string, options?: WalkOptions): ImageBlock | undefined;
+/** Enumerate sections (page geometry + the block range each covers). */
+export declare function getSections(doc: Document): ResolvedSection[];
+export declare function resolveSections(doc: Document): ResolvedSection[];
+
+// ---------------------------------------------------------------------------
+// Content controls (SDTs) — the primary templating surface. Membership is an
+// ordered ancestry path, so controls nest; these expose the flat list (by
+// id/tag/alias), the nesting tree, and the wrapped blocks/text.
+
+/** A content control's id paired with its properties. */
+export interface SdtMatch {
+  id: string;
+  props: SdtProps;
+}
+
+/** A content control as a node in the nesting tree. */
+export interface SdtNode extends SdtMatch {
+  /** The control directly wrapping this one, or undefined for a top-level control. */
+  parentId?: string;
+  /** Direct child controls, in first-appearance order. */
+  childIds: string[];
+  /** Full ancestry outer→inner ending at this id (`[this]` for a root). */
+  path: string[];
+  /** Nesting depth: 0 for a root (== path.length - 1). */
+  depth: number;
+}
+
+/** A content control's properties by id, or undefined. */
+export declare function getSdt(doc: Document, id: string): SdtProps | undefined;
+/** Every content control, as `{ id, props }`, in `doc.sdts` insertion order. */
+export declare function getSdts(doc: Document): SdtMatch[];
+/** Controls whose machine-readable tag (w:tag) equals `tag` (a tag is not unique). */
+export declare function getSdtsByTag(doc: Document, tag: string): SdtMatch[];
+/** Controls whose title/alias (w:alias) equals `alias`. */
+export declare function getSdtsByAlias(doc: Document, alias: string): SdtMatch[];
+/** Every content control as a tree node (parent/child links, path, depth). */
+export declare function getSdtNodes(doc: Document): SdtNode[];
+/** The top-level controls — those not nested inside any other. */
+export declare function getSdtRoots(doc: Document): SdtNode[];
+/** The controls nested directly (one level) inside `id`. */
+export declare function getSdtChildren(doc: Document, id: string): SdtNode[];
+/** The controls wrapping `id`, outermost→innermost (excluding `id`). */
+export declare function getSdtAncestors(doc: Document, id: string): SdtNode[];
+/** Every control nested anywhere below `id` (depth-first, pre-order). */
+export declare function getSdtDescendants(doc: Document, id: string): SdtNode[];
+/** The blocks a block-level control wraps (their `sdtPath` includes `id`). */
+export declare function getSdtBlocks(doc: Document, id: string, options?: WalkOptions): Block[];
+/** The plain text a control encloses (block-level whole blocks + inline runs;
+ *  nested controls' text included). Blocks join with newlines. */
+export declare function sdtText(doc: Document, id: string, options?: WalkOptions): string;
+
+/** A content control's value in the shape its `type` implies. `text` is always the
+ *  enclosed text; `checked` is set for checkboxes; `selected` for dropDown/comboBox
+ *  (the VALUE of the matching listItem, or the raw text for combo free entry). */
+export interface SdtValue {
+  type: SdtProps["type"];
+  text: string;
+  checked?: boolean;
+  selected?: string;
+}
+/** Read a control's typed value, or undefined if it does not exist. */
+export declare function getSdtValue(doc: Document, id: string): SdtValue | undefined;
+
+// ---------------------------------------------------------------------------
+// Fields / bookmarks / notes / lists / styles / block location
+
+/** A field definition by id, or undefined. */
+export declare function getField(doc: Document, id: string): FieldDef | undefined;
+/** Every tracked field (custom + built-in), in document order. */
+export declare function getFields(doc: Document): FieldDef[];
+/** Fields whose keyword matches `name`, case-insensitively. */
+export declare function getFieldsByName(doc: Document, name: string): FieldDef[];
+/** The blocks forming a region field's result (their `fieldId` === id). */
+export declare function getFieldBlocks(doc: Document, id: string, options?: WalkOptions): Block[];
+
+export interface BookmarkEntry {
+  name: string;
+  range: BookmarkRange;
+}
+/** A bookmark's character range by name, or undefined. */
+export declare function getBookmark(doc: Document, name: string): BookmarkRange | undefined;
+/** Every bookmark as `{ name, range }`. */
+export declare function getBookmarks(doc: Document): BookmarkEntry[];
+
+export interface NoteStory {
+  id: string;
+  paragraphs: Paragraph[];
+}
+/** Footnote stories keyed by ref id. */
+export declare function getFootnotes(doc: Document): NoteStory[];
+/** Endnote stories keyed by ref id. */
+export declare function getEndnotes(doc: Document): NoteStory[];
+
+export interface ListItem {
+  paragraph: Paragraph;
+  /** 0-based list level (OOXML w:ilvl). */
+  level: number;
+  /** Resolved marker text ("1.", "a.", "•", …); "" for a markerless/unknown list. */
+  marker: string;
+  context: BlockContext;
+}
+/** Paragraphs bound to a list definition, in body reading order, each with its
+ *  resolved marker (mirrors the layout engine's numbering pass, body-only). */
+export declare function getListItems(doc: Document, listId: string): ListItem[];
+
+/** Enumerate the stylesheet (Word's style gallery). */
+export declare function getStyles(doc: Document): NamedStyle[];
+/** A named style by id, or undefined. */
+export declare function getStyleById(doc: Document, styleId: string): NamedStyle | undefined;
+
+/** "Where is this block?" — the resolved container/cell/note context of a block by
+ *  id, or undefined if no block carries the id. */
+export declare function blockPath(doc: Document, id: string, options?: WalkOptions): BlockContext | undefined;
+
+// ---------------------------------------------------------------------------
+// Range / text addressing
+
+/** The text a selection covers. A collapsed/single-block selection slices that
+ *  block's text (any story); a multi-block selection is supported across top-level
+ *  body blocks (joined by newlines), else "". Endpoints are ordered automatically. */
+export declare function rangeText(doc: Document, selection: DocSelection): string;
+/** The first `DocPosition` where `needle` appears in a paragraph's text (reading
+ *  order), or undefined — target an edit without computing offsets by hand. */
+export declare function positionOfText(doc: Document, needle: string, options?: WalkOptions): DocPosition | undefined;
+
+// ---------------------------------------------------------------------------
+// Edit facade
+
+export interface InsertParagraphOptions {
+  position?: "before" | "after";
+  style?: ParaStyle;
+  runStyle?: CharStyle;
+}
+
+// ---------------------------------------------------------------------------
+// Merge / append documents
+
+/** How colliding named / table styles reconcile with the destination. */
+export type StyleMergeMode = "useDestination" | "keepSource";
+/** The section seam inserted between the destination and the appended source. */
+export type MergeSectionBreak = "nextPage" | "evenPage" | "oddPage" | "continuous" | "none";
+
+export interface MergeOptions {
+  styles?: StyleMergeMode;
+  sectionBreak?: MergeSectionBreak;
+  renameBookmarksOnCollision?: boolean;
+}
+
+/** old→new id per space, for every source id that changed or was repointed. */
+export interface MergeIdMap {
+  blocks: Record<string, string>;
+  styles: Record<string, string>;
+  lists: Record<string, string>;
+  tableStyles: Record<string, string>;
+  sdts: Record<string, string>;
+  fields: Record<string, string>;
+  footnotes: Record<string, string>;
+  endnotes: Record<string, string>;
+  bookmarks: Record<string, string>;
+}
+
+export interface MergeWarning {
+  code: string;
+  detail?: string;
+}
+
+export interface MergeResult {
+  doc: Document;
+  idMap: MergeIdMap;
+  warnings: MergeWarning[];
+}
+
+/** Append `source` after `dest`, reconciling every id space. Pure — returns a new
+ *  document; the inputs are not mutated. */
+export declare function mergeDocuments(dest: Document, source: Document, opts?: MergeOptions): MergeResult;
+
+/** Fold N documents left-to-right: mergeAll([a, b, c]) ≡ merge(merge(a, b), c). */
+export declare function mergeAll(docs: Document[], opts?: MergeOptions): MergeResult;
+
+/** Ergonomic, headless editing facade over the operation engine, with undo/redo.
+ *  Every edit swaps `doc` for a new immutable value (structural sharing). */
+export declare class DocumentEditor {
+  constructor(doc: Document);
+  get doc(): Document;
+  get canUndo(): boolean;
+  get canRedo(): boolean;
+  get lastInsertedId(): string | null;
+
+  setParagraphText(blockId: string, text: string, style?: CharStyle): this;
+  insertText(blockId: string, offset: number, text: string, style?: CharStyle): this;
+  deleteText(blockId: string, start: number, end: number): this;
+  replaceText(blockId: string, start: number, end: number, text: string, style?: CharStyle): this;
+  setParagraphStyle(blockId: string, patch: Partial<ParaStyle>): this;
+  removeBlock(blockId: string): this;
+  insertParagraph(refBlockId: string, text: string, options?: InsertParagraphOptions): this;
+
+  /** Merge a patch onto a content control's properties (the control must exist).
+   *  The control `type` is not patchable — it is always preserved. */
+  setSdtProps(id: string, patch: Partial<Omit<SdtProps, "type">>): this;
+  /** Set a checkbox control's state (throws if `id` is not a checkbox). */
+  setCheckbox(id: string, checked: boolean): this;
+  /** Fill a single-paragraph content control's text (inline or block-level),
+   *  preserving nesting and clearing any placeholder. */
+  setSdtText(id: string, text: string): this;
+  /** Select a value on a dropDown/comboBox control (by listItem value then display;
+   *  comboBox allows free text). Throws for other control kinds. */
+  setSdtValue(id: string, value: string): this;
+  /** Remove a content control, unwrapping it (strip its id from member paths and
+   *  delete its props; nested controls survive). `deleteContents` removes the
+   *  wrapped content too. Block-level members outside the top-level body throw. */
+  removeSdt(id: string, options?: { deleteContents?: boolean }): this;
+
+  /** Find/replace across every paragraph as one undoable step. A string replaces
+   *  all occurrences; a RegExp is applied per run. Matches spanning a style
+   *  boundary are not replaced (run styling is always preserved). */
+  replaceAllText(pattern: string | RegExp, replacement: string): this;
+  /** Apply a named paragraph style by its human name (resolving to a styleId and
+   *  baking the resolved formatting + setting the reference). Throws if unknown. */
+  setStyleByName(blockId: string, styleName: string): this;
+  /** Move a top-level body block to a new index among the body blocks (clamped),
+   *  as one undoable step. Throws if it is not a top-level body block. */
+  moveBlock(blockId: string, toIndex: number): this;
+  /** Insert a row into a table at `rowIndex` (clamped); `cellTexts` fills cells
+   *  left-to-right (padded/trimmed to the column count). Throws if unknown. */
+  insertTableRowAt(tableId: string, rowIndex: number, cellTexts?: string[]): this;
+  /** Delete the column whose first-row cell text equals `headerText`. Throws if the
+   *  table or a matching header is not found. */
+  deleteColumnByHeader(tableId: string, headerText: string): this;
+
+  /** Append another document's content after this one (Word's "insert file at
+   *  end"), reconciling every id space (see mergeDocuments) as ONE undoable step.
+   *  Returns the merge's id map + warnings; the merged document becomes `doc`. */
+  append(source: Document, options?: MergeOptions): MergeResult;
+
+  /** Replace a block-level content control's entire content with another document
+   *  (the templating primitive): reconciles every id space and preserves the control's
+   *  ancestry (the source's own nested controls survive inside it). One undoable step.
+   *  The control must be block-level at the top level of the body — an inline control,
+   *  or one in a table cell / band / note, throws (use setSdtText for inline). */
+  replaceSdtContent(sdtId: string, source: Document, options?: MergeOptions): MergeResult;
+
+  /** Set (or clear, with `null`) a header/footer band on a specific section by index
+   *  (see getSections). The final/body section stores bands on the document; a
+   *  mid-document section on its break paragraph. Throws if the index is out of range. */
+  setSectionBand(sectionIndex: number, band: BandContainer, blocks: Block[] | null): this;
+  /** Set (or clear) a section's default footer band. See setSectionBand. */
+  setSectionFooter(sectionIndex: number, blocks: Block[] | null): this;
+  /** Set (or clear) a section's default header band. See setSectionBand. */
+  setSectionHeader(sectionIndex: number, blocks: Block[] | null): this;
+
+  undo(): boolean;
+  redo(): boolean;
+
+  find(pattern: string | RegExp): ParagraphMatch[];
+  getParagraph(blockId: string): Paragraph | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Page query (layout-backed)
+
+export interface PageInfo {
+  index: number;
+  number: number;
+  widthPx: number;
+  heightPx: number;
+  marginPx: { top: number; right: number; bottom: number; left: number };
+  contentTopPx: number;
+  contentBottomPx: number;
+  pageColorHex?: string;
+  blockIds: string[];
+}
+
+export interface GetPagesOptions {
+  fontRegistry?: unknown;
+  engineOptions?: {
+    cjkFallback?: string | null;
+    cjkLocale?: string;
+    arabicFallback?: string | null;
+    hebrewFallback?: string | null;
+  };
+}
+
+/** Lay the document out and return a serializable per-page map. Page numbers can
+ *  shift after edits, so re-run after mutating. Requires text measurement
+ *  (pretext) to be initialized, like rendering/export. */
+export declare function getPages(doc: Document, options?: GetPagesOptions): PageInfo[];
+/** The displayed page number a top-level block first appears on, or null. */
+export declare function pageOfBlock(doc: Document, blockId: string, options?: GetPagesOptions): number | null;
+/** Where a top-level block sits in a `getPages` map: its page `index` and 0-based
+ *  `order` among that page's block ids, or null. Pure over the page map (no layout). */
+export declare function indexOnPage(pages: PageInfo[], blockId: string): { index: number; order: number } | null;