wordinweb 0.1.7 → 0.1.8

package/README.md

@@ -67,7 +67,7 @@ export function Editor() {
 
   return (
     <div>
-      {api && <DocxToolbar api={api} onSave={download} />}
+      {api && <DocxToolbar api={api} mode="advanced" onSave={download} />}
       <DocxView
         source="/report.docx"
         editable
@@ -116,19 +116,36 @@ The object passed to `onReady`. Every command operates on the current selection
 **Page layout**
 - `setPageLayout(patch, scope?)` — margins, page size, orientation, columns, page borders. `scope` = `"document"` (all sections) or `"section"` (the caret's).
 - `insertBreak("page" | "column" | "sectionNextPage" | "sectionContinuous")`.
+- `insertBlankPage()` — inserts a complete blank page at the caret.
+- `insertCoverPage({ title, subtitle?, author? })` — prepends an editable, styled cover page.
 - `setLineNumbering(patch, scope?)`, `getLineNumbering()`.
+- `openHeaderFooter("header" | "footer")`, `closeHeaderFooter()` — create or directly enter page header/footer editing; Escape closes it.
 
 **Tables**
 - `insertTable(rows, cols)`.
 - `tableOp(op)` — insert/delete row/column, merge/split cells, cell vertical align, cell shading, delete table.
 
 **Images**
-- `insertImage(file)` — inserts a `Blob`/`File` inline at the caret, clamped to the column width (TIFF/WMF/EMF are decoded to something the browser can paint).
+- `insertImage(file)` — inserts a raster image or editable SVG icon inline at the caret, clamped to the column width (TIFF/WMF/EMF are decoded to something the browser can paint).
+- `insertScreenshot()` — opens the browser screen/window/tab picker and inserts the captured frame as an editable PNG picture.
+- `insertModel3D(file, poster?)` — packages a GLB as a native Office 3D model with an editable poster fallback.
+- `insertOnlineVideo(url)` — inserts Word online-video metadata with a safe browser poster; double-click opens the validated HTTP(S) URL.
+- `insertEmbeddedObject(file, filename?)` — embeds any file as a native OLE Package; double-click safely downloads the original file in the browser.
 
-**Comments, footnotes & fields**
+**Comments, footnotes & Insert content**
 - `addComment(text)` — comment on the selection (`false` if nothing is selected).
 - `addFootnote(text)` — footnote at the caret.
 - `insertPageNumber("page" | "pageOfTotal")` — dynamic `PAGE` / `Page X of Y` field.
+- `insertField(instruction, cachedResult?)`, `insertDateTime("date" | "time", picture?)` — live Word fields.
+- `addBookmark(name)`, `listBookmarks()`, `insertCrossReference(name, "text" | "page")` — named bookmark targets and live `REF` / `PAGEREF` fields.
+- `insertEquation(linear)`, `insertSymbol(symbol)` — native editable OMML equations and arbitrary Unicode symbols.
+- `insertShape(preset, text?)` — floating editable DrawingML rectangles, rounded rectangles, ellipses, diamonds, and text boxes. Advanced mode also exposes Text Box as its own Insert control.
+- `insertWordArt(text, preset?)` — editable DrawingML WordArt with plain, arch, wave, and chevron presets.
+- `insertChart(data)`, `updateSelectedChart(data)` — native editable ChartML with its embedded workbook.
+- `insertSmartArt(data)`, `updateSelectedSmartArt(data)` — native editable SmartArt data, layout, style, colors, and cached drawing parts.
+- `setDrawingTool({ kind: "pen", color, width } | { kind: "eraser", size } | { kind: "lasso" } | null)`, `getDrawingTool()` — draw, erase, or lasso-select movable DrawingML ink.
+- `arrangeObject(action)` — align the selected image, shape, or ink group to the page; rotate it 90°; or bring it to the front/send it to the back. Arrow keys nudge selected floating objects by 1px (`Shift` = 10px).
+- `setDropCap("drop" | "margin" | null, lines?)` — apply, change, or remove a native Word drop cap on the caret paragraph.
 
 **Suggesting mode (tracked changes)**
 - `setSuggesting(on, author?)` — when on, edits record as OOXML `w:ins`/`w:del` instead of mutating text directly, and the view switches to markup.
@@ -144,16 +161,18 @@ The object passed to `onReady`. Every command operates on the current selection
 - `undo()`, `redo()`, `canUndo()`, `canRedo()`.
 - `save()` → edited `.docx` bytes (`Uint8Array`). Everything the model doesn't touch round-trips byte-for-byte.
 - `print()` — browser print dialog / save-as-PDF of the rendered pages.
-- `pageCount()`, `closeHeaderFooter()`, and `document` (the parsed `DocxDocument`).
+- `pageCount()` and `document` (the parsed `DocxDocument`).
 
 ### `DocxToolbar`
 
-A ready-made formatting toolbar for an editable `DocxView`. Ribbon-style tabs (Home / Insert / Layout) wired to the `api`.
+A ready-made formatting toolbar for an editable `DocxView`. Use `mode="simple"` for the basic Home editing strip or `mode="advanced"` for the full Home / Insert / Draw / Layout ribbon supported by the installed version.
+Layout includes Word-style paper presets plus a custom width/height dialog; both document and current-section scope emit native page-size properties.
 
 | Prop | Type | What it does |
 | --- | --- | --- |
 | `api` | `DocxViewApi \| null` | The api from `onReady`. |
 | `onSave` | `(bytes: Uint8Array) => void` | Adds a Download button; receives `api.save()` bytes. |
+| `mode` | `"simple" \| "advanced"` | Editing surface. Defaults to `"advanced"`; simple omits the Insert, Draw, and Layout ribbons. |
 | `features` | `Partial<Record<ToolbarFeature, boolean>>` | Per-group toggles; every group defaults on. Set one `false` to hide it (e.g. `{ table: false, image: false }`). |
 | `className` | `string` | Class on the toolbar root — handy as a scope for CSS-variable overrides. |
 | `style` | `React.CSSProperties` | Inline overrides merged onto the toolbar root. |
@@ -168,6 +187,7 @@ Every color the chrome paints — the toolbar, comment cards, selection, caret,
 | `--dxw-toolbar-fg` | `#3c4043` | Toolbar text & icons (icons use `currentColor`) |
 | `--dxw-toolbar-border` | `#dadce0` | Toolbar borders & separators |
 | `--dxw-toolbar-muted` | `#5f6368` | Secondary/label text |
+| `--dxw-toolbar-z-index` | `100` | Toolbar and open-menu stacking level |
 | `--dxw-accent` | `#1a73e8` | Primary accent (active tab, pills, focus rings) |
 | `--dxw-accent-fg` | `#fff` | Text/icon on an accent fill |
 | `--dxw-btn-active-bg` | `#dfe7f5` | Toggled button background |
@@ -175,6 +195,9 @@ Every color the chrome paints — the toolbar, comment cards, selection, caret,
 | `--dxw-tab-active-bg` | `#e8f0fe` | Active ribbon-tab background |
 | `--dxw-popover-bg` | `#fff` | Dropdown / popover surface |
 | `--dxw-popover-shadow` | `0 4px 16px rgba(0,0,0,.15)` | Popover shadow |
+| `--dxw-layout-menu-width` | `304px` | Layout option-menu width |
+| `--dxw-layout-menu-max-height` | `480px` | Layout option-menu scroll limit |
+| `--dxw-layout-preview-bg` | `#fff` | Paper fill in Layout option previews |
 | `--dxw-canvas-bg` | `#e8eaed` | Scroll area behind the pages |
 | `--dxw-page-bg` | `#ffffff` | Page paper |
 | `--dxw-page-shadow` | `0 1px 3px …, 0 4px 14px …` | Page drop shadow |
@@ -215,6 +238,12 @@ Or in a stylesheet:
 .dxw-dark { --dxw-toolbar-bg: #1f2937; --dxw-toolbar-fg: #e5e7eb; /* … */ }
 ```
 
+Layout controls also expose stable `.dxw-layout-ribbon`, `.dxw-layout-menu-trigger`,
+`.dxw-layout-menu`, `.dxw-layout-menu-item`, and `.dxw-layout-preview` classes.
+Their `data-dxw-layout-menu`, `data-dxw-layout-option`, and
+`data-dxw-layout-preview` attributes identify each menu, action, and diagram
+when a host needs a narrowly scoped style override.
+
 ## How it works
 
 WordInWeb never converts the document to flowing HTML. It parses the OOXML into a typed model, runs a layout engine that breaks lines with real canvas metrics and paginates like Word, and renders each primitive as one absolutely-positioned element, so the browser does zero reflow. Editing mutates the retained XML tree and re-serializes only the parts it models, leaving everything else byte-for-byte intact.

package/dist/index.d.ts

@@ -16,6 +16,8 @@ interface XmlElement {
     children: XmlElement[];
     /** Concatenated character data directly inside this element. */
     text: string;
+    /** Editor placeholder retained in memory but omitted from XML while empty. */
+    omitWhenEmpty?: boolean;
 }
 
 /**
@@ -272,6 +274,27 @@ interface ImageContent {
     };
     /** Source w:drawing (or pict) element, for resize/move editing. */
     srcDrawing?: XmlElement;
+    /** Native Office 3D model shown through its saved poster raster. */
+    model3D?: Model3DReference;
+    /** Word online-video metadata shown through its saved poster raster. */
+    webVideo?: WebVideoReference;
+    /** Embedded OLE package activated as a safe download in the browser. */
+    embeddedObject?: EmbeddedObjectReference;
+}
+interface Model3DReference {
+    part: string;
+    posterPart: string;
+}
+interface WebVideoReference {
+    url: string;
+    embeddedHtml: string;
+    width: number;
+    height: number;
+}
+interface EmbeddedObjectReference {
+    part: string;
+    filename: string;
+    progId: string;
 }
 /** OMML equation node (subset: runs, scripts, fractions, radicals). */
 type MathNode = {
@@ -466,6 +489,10 @@ interface ShapeTextbox {
      * be an interactive hit target (select the shape instead of the body text
      * behind it). */
     srcDrawing?: XmlElement;
+    /** Header/footer-owned textbox whose text is edited as an independent story. */
+    textboxStory?: boolean;
+    /** DrawingML WordArt, including the identity textNoShape preset. */
+    wordArt?: boolean;
     /** bodyPr a:prstTxWarp preset name (textArchUp, textWave1, textChevron,
      * textCirclePour, …): the shape's text is bent onto the preset's envelope
      * rather than flowed as ordinary lines. "textNoShape" (no warp) is dropped. */
@@ -509,6 +536,8 @@ interface ShapeWordArt {
 interface ShapeArt {
     type: "art";
     srcDrawing?: XmlElement;
+    /** A freehand stroke, selectable by the Draw ribbon's stroke eraser. */
+    ink?: boolean;
     x: number;
     y: number;
     /** Percent-of-page offsets (wp14:pctPos*Offset), 0..1. */
@@ -519,7 +548,10 @@ interface ShapeArt {
     hRel: AnchorRel;
     vRel: AnchorRel;
     hAlign?: "left" | "center" | "right";
+    vAlign?: "top" | "center" | "bottom";
     behind?: boolean;
+    /** a:xfrm rotation, degrees clockwise. */
+    rotation?: number;
     lines: DrawingLine[];
     images: DrawingImage[];
     paths: DrawingPath[];
@@ -566,8 +598,14 @@ interface ShapeImage {
     };
     /** Source w:drawing element (editing). */
     srcDrawing?: XmlElement;
+    model3D?: Model3DReference;
+    webVideo?: WebVideoReference;
+    embeddedObject?: EmbeddedObjectReference;
 }
-type Shape = ShapeLine | ShapeTextbox | ShapeImage | ShapeArt | ShapeWordArt;
+type Shape = (ShapeLine | ShapeTextbox | ShapeImage | ShapeArt | ShapeWordArt) & {
+    /** wp:anchor relativeHeight, used for object stacking order. */
+    z?: number;
+};
 /**
  * Floating/anchored object: does not occupy inline space; positioned against
  * page/margin/paragraph during layout. (How classic pleading paper draws its
@@ -615,6 +653,10 @@ interface DrawingContent {
     height: number;
     lines: DrawingLine[];
     images: DrawingImage[];
+    /** Native ChartML chart data resolved from the related chart part. */
+    chart?: ChartData;
+    /** Native SmartArt diagram data resolved from its diagram parts. */
+    smartArt?: SmartArtData;
     /** Freeform vector shapes (a:custGeom), as SVG path data. */
     paths?: DrawingPath[];
     /** An INLINE wps text box (wp:inline wps:txbx): a fixed-extent box that
@@ -642,6 +684,22 @@ interface DrawingContent {
      * SmartArt cached-drawing shapes). Painted above lines/paths. */
     texts?: DrawingTextShape[];
 }
+type ChartType = "column" | "bar" | "line" | "pie";
+interface ChartSeries {
+    name: string;
+    values: number[];
+}
+interface ChartData {
+    type: ChartType;
+    title?: string;
+    categories: string[];
+    series: ChartSeries[];
+}
+type SmartArtLayout = "process" | "cycle" | "hierarchy" | "list";
+interface SmartArtData {
+    layout: SmartArtLayout;
+    items: string[];
+}
 /** A text body positioned inside a composite drawing (a wps textbox in a
  * group, or a SmartArt dsp:sp txBody), px relative to the drawing's box. */
 interface DrawingTextShape {
@@ -681,6 +739,7 @@ interface DrawingPath {
     stroke?: {
         color: string;
         width: number;
+        opacity?: number;
     };
 }
 /**
@@ -1064,7 +1123,10 @@ declare class DocxDocument {
     /** Changes whenever refresh() rebuilds the parsed model. Plain in-place text
      * edits can keep this stable so incremental layout reuses model-only caches. */
     private _modelVersion;
+    private _packageResourceVersion;
     get modelVersion(): number;
+    /** Invalidate layout derived from related parts such as ChartML. */
+    markPackageResourceChanged(): void;
     readonly pkg: Package;
     readonly theme: Theme;
     styles: Styles;
@@ -1137,6 +1199,11 @@ declare class DocxDocument {
     private commentsDirty;
     /** Retained XML roots — source of truth for editing and save(). */
     private readonly docPart;
+    /** Retained settings.xml tree. A synthetic empty root keeps history root
+     * indices stable for documents that did not originally contain the part. */
+    private readonly settingsPart;
+    private readonly settingsRoot;
+    private settingsDirty;
     /** Parsed document.xml root (read-only outside the class; the layout engine
      * scans it for incremental-reuse eligibility, tests walk it). */
     readonly docRoot: XmlElement;
@@ -1147,6 +1214,10 @@ declare class DocxDocument {
     private readonly relsPath;
     private relsRoot;
     private contentTypesRoot;
+    /** Canonical XML as first parsed from each always-modeled package part.
+     * If the retained tree still matches on save, keep the part's original
+     * bytes instead of replacing producer formatting such as CRLF line ends. */
+    private readonly originalModeledXml;
     private nextDocPrId;
     /** Transient layout state: set by the engine while laying out a docGrid
      * type="charsAndLines" section so line measurement can give East-Asian
@@ -1155,6 +1226,8 @@ declare class DocxDocument {
      * single-threaded and sequential per section. */
     charGridEa: boolean;
     private constructor();
+    /** Repair only objects emitted by older WordInWeb builds that Word rejects. */
+    private repairLegacyWordInWebObjects;
     /**
      * Re-derive the document model from the retained XML trees. Called after
      * edit commands mutate the XML.
@@ -1172,6 +1245,16 @@ declare class DocxDocument {
      * stable across a plain text edit). */
     layoutGlobalSig(): string;
     refresh(): void;
+    /**
+     * Reparse the two direct body paragraphs created by Enter without rebuilding
+     * the complete document model. This deliberately covers only the simple
+     * single-section body case used by incremental pagination; structural
+     * containers, revisions, bookmarks, and section breaks use refresh().
+     */
+    reparseDirectBodyParagraphSplit(beforeSource: XmlElement, afterSource: XmlElement): {
+        before: Paragraph;
+        after: Paragraph;
+    } | null;
     private deriveComments;
     /** Retained comments tree for edit commands (null when the doc has none). */
     /**
@@ -1222,13 +1305,16 @@ declare class DocxDocument {
      * nearest preceding w:t.
      */
     commentAnchors(): Map<string, XmlElement[]>;
-    /** The mutable XML roots (document body, header/footer parts, comments).
-     * The comments root is last so history snapshot indices stay stable. */
     /** Flag the footnotes part dirty when `t` lives inside it, so save()
      * re-serializes footnotes.xml. Called by the editor after a text edit; a
      * no-op for body/header/footer targets. */
     markDirtyIfFootnote(t: XmlElement): void;
+    /** The mutable XML roots (document body, related modeled parts, settings).
+     * settingsRoot is always second and always present so its history snapshot
+     * index stays stable even when optional related roots are created later. */
     editableRoots(): XmlElement[];
+    /** Toggle the document-global facing-page margin mode in settings.xml. */
+    setMirrorMargins(enabled: boolean): void;
     /**
      * Find the parent element of `target` in any modeled XML tree (document
      * body, headers, footers). Linear scan — documents are small and this only
@@ -1242,6 +1328,8 @@ declare class DocxDocument {
      * XML parts we model are re-serialized; every other part round-trips
      * byte-for-byte.
      */
+    private rememberOriginalXml;
+    private writeModeledXml;
     save(): Uint8Array;
     /** Fresh unique docPr id for inserted drawings. */
     nextDrawingId(): number;
@@ -1260,6 +1348,34 @@ declare class DocxDocument {
     /** Retarget an existing external relationship (hyperlink href edit). */
     setRelTarget(relId: string, url: string): boolean;
     addImageResource(bytes: Uint8Array, ext: string): string;
+    /** Add a GLB model part and its Office 2019 model3d relationship. */
+    addModel3DResource(bytes: Uint8Array): {
+        relId: string;
+        part: string;
+    };
+    /** Add an OLE package part used by a Word w:object. */
+    addEmbeddedObjectResource(bytes: Uint8Array): {
+        relId: string;
+        part: string;
+    };
+    /** Add a DOCX package embedded as an activatable Word.Document.12 object. */
+    addEmbeddedWordDocumentResource(bytes: Uint8Array): {
+        relId: string;
+        part: string;
+    };
+    /** Add a native ChartML part and its embedded editable workbook. */
+    addChartResource(chartXml: string, workbook: Uint8Array): {
+        relId: string;
+        part: string;
+    };
+    /** Add the SmartArt data/layout/style/color parts and its cached diagram drawing. */
+    addSmartArtResources(layoutXml: string, styleXml: string, colorsXml: string, drawingXml: string, dataXml: (drawingRelId: string) => string): {
+        dataRelId: string;
+        layoutRelId: string;
+        styleRelId: string;
+        colorsRelId: string;
+        drawingRelId: string;
+    };
     static load(data: ArrayBuffer | Uint8Array): DocxDocument;
     media(part: string): Uint8Array | undefined;
     /** Effective paragraph properties: docDefaults → table style → style chain → direct. */
@@ -1321,10 +1437,17 @@ interface PathItem {
     stroke?: {
         color: string;
         width: number;
+        opacity?: number;
+    };
+    rotate?: {
+        deg: number;
+        ox: number;
+        oy: number;
     };
     /** Paint under / over the body text (anchored-shape layering). */
     behind?: boolean;
     front?: boolean;
+    z?: number;
 }
 interface TextItem {
     kind: "text";
@@ -1366,6 +1489,9 @@ interface TextItem {
     href?: string;
     /** Present for editable text (absent on numbering labels etc.). */
     src?: TextSource;
+    /** Source drawing when this text belongs to an independently editable
+     * text-box story. */
+    textboxStory?: XmlElement;
     /** Rotate about a point (px, relative to this item's top-left). */
     rotate?: {
         deg: number;
@@ -1377,6 +1503,7 @@ interface TextItem {
     /** Paint over the body text (non-behindDoc anchored shape content: Word
      * layers in-front shapes above the text layer). */
     front?: boolean;
+    z?: number;
     /** Right-to-left run: renderer sets direction:rtl so the browser shapes and
      * orders the (Arabic/Hebrew) glyphs within the span box. */
     rtl?: boolean;
@@ -1407,6 +1534,7 @@ interface RectItem {
     behind?: boolean;
     /** Paint over the body text (non-behindDoc anchored shape fill). */
     front?: boolean;
+    z?: number;
 }
 interface LineEdgeItem {
     kind: "edge";
@@ -1425,6 +1553,7 @@ interface LineEdgeItem {
     };
     /** Paint over the body text (non-behindDoc anchored shape border). */
     front?: boolean;
+    z?: number;
 }
 interface ImageItem {
     kind: "image";
@@ -1442,6 +1571,12 @@ interface ImageItem {
         b: number;
     };
     rotation?: number;
+    /** Whole-group rotation about an external origin. */
+    rotate?: {
+        deg: number;
+        ox: number;
+        oy: number;
+    };
     /** Picture-watermark "washout" (VML v:imagedata gain/blacklevel, 0..1
      * fractions). Per-channel linear recolor, measured against Word's PDF of
      * probe2-picture-watermark (gain 0.3, blacklevel 0.35: source 32 -> 215,
@@ -1462,8 +1597,20 @@ interface ImageItem {
      * (Word's z-order; without this, later-emitted text spans cover the image
      * and it neither shows in front nor receives clicks/drags). */
     front?: boolean;
+    z?: number;
     /** Source w:drawing element (for interactive resize/move). */
     src?: XmlElement;
+    model3D?: Model3DReference;
+    webVideo?: WebVideoReference;
+    embeddedObject?: EmbeddedObjectReference;
+}
+interface ChartItem {
+    kind: "chart";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    data: ChartData;
 }
 /** Interactive resize zone over a table boundary (column or row). */
 interface DrawingHitItem {
@@ -1476,16 +1623,28 @@ interface DrawingHitItem {
     src: XmlElement;
     /** Anchored drawings drag by offset; inline ones re-anchor into text. */
     anchored: boolean;
+    /** Freehand stroke that may be removed with the Draw ribbon's eraser. */
+    ink?: boolean;
+    /** Native SmartArt diagram selection target. */
+    smartArt?: boolean;
     /** A shape fill hit that sits UNDER the shape's own text spans (same z): a
-     * click on bare fill selects the shape, but clicks on the text glyphs still
-     * reach the text for editing. Such hits select only (never drag-move). */
+     * click on bare fill selects or drags the shape, while clicks on its text
+     * glyphs still reach the text editor. */
     belowText?: boolean;
+    /** The drawing owns an independently editable text-box story. */
+    textboxStory?: boolean;
+    rotate?: {
+        deg: number;
+        ox: number;
+        oy: number;
+    };
+    z?: number;
 }
 interface GripItem {
     kind: "grip";
     /** "col": vertical zone at x spanning y1..y2. "row": horizontal zone at y1
-     * spanning x..x2. */
-    axis: "col" | "row";
+     * spanning x..x2. "move": table bounds x..x2, y1..y2. */
+    axis: "col" | "row" | "move";
     x: number;
     y1: number;
     y2: number;
@@ -1545,10 +1704,16 @@ interface WarpTextItem {
     fill: string;
     /** Preset name (textArchUp, textWave1, textChevron, textCirclePour, …). */
     warp: string;
+    rotate?: {
+        deg: number;
+        ox: number;
+        oy: number;
+    };
     behind?: boolean;
     front?: boolean;
+    z?: number;
 }
-type PageItem = TextItem | PathItem | RectItem | LineEdgeItem | ImageItem | DrawingHitItem | GripItem | WordArtItem | WarpTextItem;
+type PageItem = TextItem | PathItem | RectItem | LineEdgeItem | ImageItem | ChartItem | DrawingHitItem | GripItem | WordArtItem | WarpTextItem;
 interface LaidOutPage {
     width: number;
     height: number;
@@ -1570,6 +1735,13 @@ interface LayoutResult {
      * back as LayoutOptions.prev to enable incremental relayout. Not part of the
      * rendered output and ignored by the equivalence harness. */
     _incr?: unknown;
+    /** Internal marker: unchanged pages in this result retain exact object
+     * identity from the previous layout, so the DOM diff can use identity
+     * instead of structurally walking a dense changed page. */
+    _incremental?: boolean;
+    /** Exclusive global page index through which an incremental render may run
+     * pageEq before the page containing the exact dirty text source. */
+    _incrementalStructuralPrefixEnd?: number;
     /** Opaque page state used to refresh headers/footers without repaginating
      * the body when their measured geometry is unchanged. */
     _hf?: unknown;
@@ -1625,6 +1797,9 @@ interface LayoutOptions {
      * multi-block edits (paste, paragraph split/merge, undo/redo, structural ops),
      * which take the full scan. */
     dirtyHint?: XmlElement;
+    /** Exact retained text element changed by a local edit. Used only to bound
+     * structural page comparison before the first actually dirty page. */
+    dirtySource?: XmlElement;
 }
 declare function layoutDocument(doc: DocxDocument, options?: LayoutOptions): LayoutResult;
 
@@ -1762,6 +1937,25 @@ interface SelectionFormat {
     verticalAlign?: "superscript" | "subscript";
 }
 
+type ShapePreset = "rectangle" | "roundedRectangle" | "ellipse" | "diamond" | "textBox";
+type WordArtPreset = "plain" | "archUp" | "archDown" | "wave" | "chevron";
+type DrawingTool = {
+    kind?: "pen";
+    color: string;
+    width: number;
+} | {
+    kind: "highlighter";
+    color: string;
+    width: number;
+} | {
+    kind: "eraser";
+    size: number;
+} | {
+    kind: "lasso";
+};
+
+type ObjectArrangeAction = "alignLeft" | "alignCenter" | "alignRight" | "alignTop" | "alignMiddle" | "alignBottom" | "rotateLeft" | "rotateRight" | "bringToFront" | "sendToBack";
+
 type ParagraphAlignment = "left" | "center" | "right" | "justify";
 interface PageLayoutPatch {
     /** Margins in inches. */
@@ -1771,6 +1965,8 @@ interface PageLayoutPatch {
         bottom?: number;
         left?: number;
     };
+    /** Document-global facing-page mode (settings.xml w:mirrorMargins). */
+    mirrorMargins?: boolean;
     /** Page size in inches (before orientation). */
     size?: {
         width: number;
@@ -1802,6 +1998,11 @@ type TableOp = "rowAbove" | "rowBelow" | "deleteRow" | "colLeft" | "colRight" |
     v: "top" | "center" | "bottom";
 };
 
+interface CoverPageContent {
+    title: string;
+    subtitle?: string;
+    author?: string;
+}
 interface LineNumberingPatch {
     /** Turn margin line numbering on/off for the target section(s). */
     enabled: boolean;
@@ -1821,17 +2022,21 @@ interface MissingFont {
 }
 
 /** Toolbar control groups a host can disable via the `features` prop. */
-type ToolbarFeature = "history" | "styles" | "font" | "size" | "format" | "color" | "highlight" | "alignment" | "indent" | "spacing" | "link" | "lists" | "table" | "image" | "comment" | "footnote" | "layout" | "download";
-declare function DocxToolbar({ api, onSave, features, className, style, }: {
+type ToolbarFeature = "history" | "styles" | "font" | "size" | "format" | "color" | "highlight" | "alignment" | "indent" | "spacing" | "link" | "lists" | "table" | "image" | "icon" | "screenshot" | "model3D" | "media" | "object" | "chart" | "smartArt" | "comment" | "footnote" | "bookmark" | "crossReference" | "dateTime" | "field" | "equation" | "symbol" | "shape" | "textBox" | "wordArt" | "drawing" | "arrange" | "dropCap" | "headerFooter" | "coverPage" | "pageNumber" | "break" | "layout" | "download";
+type ToolbarMode = "simple" | "advanced";
+interface DocxToolbarProps {
     api: DocxViewApi | null;
     onSave?: (bytes: Uint8Array) => void;
+    /** Simple shows basic Home editing; advanced adds the Insert, Draw, and Layout ribbons. */
+    mode?: ToolbarMode;
     /** Per-group overrides; every group defaults to enabled. */
     features?: Partial<Record<ToolbarFeature, boolean>>;
     /** Extra class on the toolbar root (e.g. a scope for CSS-variable overrides). */
     className?: string;
     /** Inline overrides merged onto the toolbar root; wins over the defaults. */
     style?: React.CSSProperties;
-}): react.JSX.Element;
+}
+declare function DocxToolbar({ api, onSave, mode, features, className, style, }: DocxToolbarProps): react.JSX.Element;
 
 interface DocxViewApi {
     /** Apply character formatting to the current browser selection. */
@@ -1842,6 +2047,44 @@ interface DocxViewApi {
     addFootnote(text: string): boolean;
     /** Insert a dynamic page-number field at the caret (body, header or footer). */
     insertPageNumber(kind?: "page" | "pageOfTotal"): boolean;
+    /** Insert any Word field instruction supported by the renderer. */
+    insertField(instruction: string, cachedResult?: string): boolean;
+    /** Insert a live DATE or TIME field with an optional Word date picture. */
+    insertDateTime(kind: "date" | "time", picture?: string): boolean;
+    /** Named bookmarks in document order. */
+    listBookmarks(): string[];
+    /** Add a bookmark around the selection, or a zero-length bookmark at the caret. */
+    addBookmark(name: string): boolean;
+    /** Insert a live text or page reference to a bookmark. */
+    insertCrossReference(bookmark: string, kind: "text" | "page"): boolean;
+    /** Insert an editable inline equation from WordInWeb's linear math syntax. */
+    insertEquation(linear: string): boolean;
+    /** Insert a Unicode symbol through the normal undo/suggestion-aware typing path. */
+    insertSymbol(symbol: string): boolean;
+    /** Insert a floating editable DrawingML shape at the caret. */
+    insertShape(preset: ShapePreset, text?: string): boolean;
+    /** Insert editable DrawingML WordArt at the caret. */
+    insertWordArt(text: string, preset?: WordArtPreset): boolean;
+    /** Insert a native editable ChartML chart at the caret. */
+    insertChart(data: ChartData): boolean;
+    /** Replace the selected native chart's type and data. */
+    updateSelectedChart(data: ChartData): boolean;
+    /** Insert a native editable SmartArt diagram at the caret. */
+    insertSmartArt(data: SmartArtData): boolean;
+    /** Replace the selected native SmartArt diagram's layout and node text. */
+    updateSelectedSmartArt(data: SmartArtData): boolean;
+    /** Insert a native Office 3D model with an optional custom poster image. */
+    insertModel3D(file: Blob, poster?: Blob): Promise<boolean>;
+    /** Insert Word online-video metadata with a browser-safe poster. */
+    insertOnlineVideo(url: string): Promise<boolean>;
+    /** Embed an arbitrary file as a native OLE Package object. */
+    insertEmbeddedObject(file: Blob, filename?: string): Promise<boolean>;
+    /** Activate a freehand pen, or return to selection mode with null. */
+    setDrawingTool(tool: DrawingTool | null): void;
+    /** Current freehand pen, or null while in selection mode. */
+    getDrawingTool(): DrawingTool | null;
+    /** Align, rotate, or reorder the selected image, shape, or ink group. */
+    arrangeObject(action: ObjectArrangeAction): boolean;
     undo(): void;
     redo(): void;
     canUndo(): boolean;
@@ -1852,6 +2095,8 @@ interface DocxViewApi {
     tableOp(op: TableOp): void;
     /** Insert an image file at the caret (inline, natural size clamped to column). */
     insertImage(file: Blob): Promise<void>;
+    /** Capture a screen, window, or browser tab and insert the current frame as a PNG picture. */
+    insertScreenshot(): Promise<ScreenshotInsertResult>;
     /** Align the paragraph(s) under the caret or selection. */
     setAlignment(align: ParagraphAlignment): void;
     /** Apply a named paragraph style (null clears back to Normal). */
@@ -1872,6 +2117,8 @@ interface DocxViewApi {
         beforePt?: number | null;
         afterPt?: number | null;
     }): void;
+    /** Apply or remove a native Word drop cap on the caret paragraph. */
+    setDropCap(mode: "drop" | "margin" | null, lines?: number): boolean;
     /** Remove direct character formatting from the selection. */
     clearFormatting(): void;
     /** Change the selection's case. */
@@ -1897,6 +2144,10 @@ interface DocxViewApi {
     setPageLayout(patch: PageLayoutPatch, scope?: "document" | "section"): void;
     /** Insert a page/column break or a section break at the caret. */
     insertBreak(kind: "page" | "column" | "sectionNextPage" | "sectionContinuous"): boolean;
+    /** Insert a full blank page at the caret (two consecutive page breaks). */
+    insertBlankPage(): boolean;
+    /** Insert an editable cover page before the current document. */
+    insertCoverPage(content: CoverPageContent): boolean;
     /** Toggle/configure margin line numbers (Word's Layout > Line Numbers).
      * scope "section" targets the caret's section; "document" every section. */
     setLineNumbering(patch: LineNumberingPatch, scope?: "document" | "section"): void;
@@ -1908,6 +2159,8 @@ interface DocxViewApi {
     } | null;
     /** Leave header/footer editing mode. */
     closeHeaderFooter(): void;
+    /** Enter and, if needed, create the header or footer on the caret's page. */
+    openHeaderFooter(kind: "header" | "footer"): boolean;
     /** Effective formatting of the current selection (toolbar state), or null. */
     getSelectionFormat(): SelectionFormat | null;
     /** Print the rendered pages (browser print dialog / save as PDF). */
@@ -1936,6 +2189,7 @@ interface DocxViewApi {
     rejectAllRevisions(): number;
     document: DocxDocument;
 }
+type ScreenshotInsertResult = "inserted" | "unsupported" | "cancelled" | "error" | "no-caret";
 interface DocxViewProps {
     /** The document: raw bytes, a File/Blob, or a URL to fetch. */
     source: ArrayBuffer | Uint8Array | Blob | string;
@@ -1990,4 +2244,4 @@ interface DocxViewProps {
  */
 declare function DocxView({ source, zoom, fitWidth, narrowWidth, editable, className, style, onLoad, onReady, onError, commentAuthor, showComments, revisions, onMissingFonts, }: DocxViewProps): react.JSX.Element;
 
-export { DocxDocument, DocxToolbar, DocxView, type DocxViewApi, type DocxViewProps, type LineNumberingPatch, type PageLayoutPatch, type ParagraphAlignment, type RunFormatPatch, type SelectionFormat, layoutDocument, printPages, renderToDom };
+export { type CoverPageContent, DocxDocument, DocxToolbar, type DocxToolbarProps, DocxView, type DocxViewApi, type DocxViewProps, type DrawingTool, type LineNumberingPatch, type PageLayoutPatch, type ParagraphAlignment, type RunFormatPatch, type ScreenshotInsertResult, type SelectionFormat, type ShapePreset, type ToolbarFeature, type ToolbarMode, layoutDocument, printPages, renderToDom };