@docx-editor.dev/core 2.9.2 → 2.11.0

package/dist/{index-wb-iOxfh.d.cts → index-Dn0lOp9Z.d.cts}

@@ -1,17 +1,19 @@
-import { T as TreeDocOp, d as DrawingPositionInput, m as DrawingTransform, i as DrawingTreeDocOp } from './tree-op-types-D1vNJ7XC.cjs';
-import { b as ImageDecodePort, S as SupportedImageMime } from './image-resources-BiA-IXgo.cjs';
-import { g as ReviewRevisionKind } from './review-items-B8tffIXj.cjs';
-import { EditorModule, ReviewModuleContribution } from './contracts/modules.cjs';
-import { j as FontSource, k as FontSourceSubstitution, F as FontConfiguration, D as DocumentSource, Z as ZoomMode, E as EditorFontError, l as Editor, b as EditorCommand, C as CanResult, S as SelectedImageState, V as ViewScope, m as FontFaceRequest, I as ImageContext, T as TableBorderEdgeTarget, n as TableBorderSpec, o as TableBorderStyle, p as TableContext } from './editor-cAEf1uXW.cjs';
-import { R as RevisionDisplayMode } from './revision-projection-Cc4wz30g.cjs';
-import { S as SemanticPosition, a as SemanticSelection, N as NavigationCommand } from './semantic-interaction-BfWDD_0V.cjs';
-import { c as RevisionStyles, R as ReviewAuthorInfo, b as RevisionAuthorStyle, F as FieldShadingMode, d as DrawingPaintStrings } from './semantic-paint-Bd7EqzXV.cjs';
-import { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties } from './note-properties-CQlxjic_.cjs';
-import { S as SemanticLayout, C as ContentControlBoundaryRecord, T as TextMeasurer } from './semantic-records-DadVT_E1.cjs';
-import { S as StoryScope, A as ApplyImagePropertiesInput, d as ImageIntentResult, c as InsertImageInput, B as BookmarkIndex } from './custom-node-writes-Dy3b20PS.cjs';
-import { C as CellSelection, S as SectionProperties } from './semantic-cell-selection-BPzx6DdT.cjs';
+import { T as TreeDocOp, C as ImageDecodePort, v as DrawingPositionInput, W as DrawingTransform, F as DrawingTreeDocOp, y as SupportedImageMime } from './tree-op-types-BPyXNxyL.cjs';
 import { Unsubscribe, ExecResult, ParagraphTabStop, IndentFormatting, ParagraphFlags, ParagraphDisagreements, SelectionPin } from './contracts/types.cjs';
-import { c as TreeDocxSessionView, a as TreeApplyResult } from './tree-session-Df02ajqc.cjs';
+import { g as ReviewRevisionKind } from './review-items-BdeLNRi2.cjs';
+import { EditorModule, ReviewModuleContribution } from './contracts/modules.cjs';
+import { j as FontSource, k as FontSourceSubstitution, F as FontConfiguration, D as DocumentSource, Z as ZoomMode, E as EditorFontError, l as Editor, b as EditorCommand, C as CanResult, S as SelectedImageState, m as FormatPainterSurfaceState, V as ViewScope, n as FontFaceRequest, I as ImageContext, T as TableBorderEdgeTarget, o as TableBorderSpec, p as TableBorderStyle, q as TableContext } from './editor-C8edZgy5.cjs';
+import { R as RevisionDisplayMode } from './revision-projection-C2S8PSQm.cjs';
+import { S as SemanticPosition, a as SemanticSelection, N as NavigationCommand } from './semantic-interaction-Cs2jErnt.cjs';
+import { EditorCollaborationSession, CollaborationRemoteSelection, CollaborationModuleContribution } from './collaboration.cjs';
+import { c as RevisionStyles, R as ReviewAuthorInfo, b as RevisionAuthorStyle, F as FieldShadingMode, d as DrawingPaintStrings } from './semantic-paint-UHaj3sBY.cjs';
+import { R as ResolvedFootnoteProperties, a as ResolvedEndnoteProperties, A as AuthoredNoteProperties } from './note-properties-BvGfHk5e.cjs';
+import { S as SemanticLayout, C as ContentControlBoundaryRecord, T as TextMeasurer } from './semantic-records-5AOQJmLX.cjs';
+import { B as BookmarkIndex } from './custom-node-writes-CwkYRw3V.cjs';
+import { I as InsertImageInput, S as StoryScope, A as ApplyImagePropertiesInput, d as ImageIntentResult } from './tree-package-fragment-BjZ3RWAS.cjs';
+import { C as CellSelection, S as SectionProperties } from './semantic-cell-selection-C0OFD4D9.cjs';
+import { T as TreeDocxSessionView, a as TreeApplyResult } from './tree-session-contract-BF2FVBOM.cjs';
+import { C as CollaborationStatus } from './failure-BnGjoXf0.cjs';
 import './contracts/document.cjs';
 
 /**
@@ -441,6 +443,16 @@ interface DocxEditorInstance extends Editor {
     setHyperlinkChrome(handlers: HyperlinkChromeHandlers): Unsubscribe;
     /** Wire the host equation popover to painted equation clicks. */
     setEquationChrome(handlers: EquationChromeHandlers): Unsubscribe;
+    /**
+     * Render the host's own component as the remote-caret label, or restore the default
+     * collaborator-name label with `null`. The engine keeps owning label geometry, class,
+     * and presence colour; the host owns the content of each published element.
+     *
+     * Instance-only, like `setHyperlinkChrome`: it is what a MOUNTING host needs. Tolerated
+     * before `attach` and after `detach` — the registration waits and applies on the next
+     * mount, and it survives a document reload the way the hyperlink chrome does.
+     */
+    setRemoteCaretLabelHost(host: RemoteCaretLabelHost | null): void;
     /**
      * Monotonic version of the observable editor state. Bumps whenever anything
      * `snapshot()` reports could have moved — a committed change, a selection move, zoom,
@@ -479,6 +491,26 @@ interface DocxEditorInstance extends Editor {
      * changes, so it is safe as a dependency; changes bump `stateVersion()`.
      */
     getReviewAuthors(): readonly ReviewAuthorInfo[];
+    /**
+     * The presence colour the engine paints for one display name — the answer the remote
+     * caret label takes, so chrome built on this cannot disagree with the painted caret.
+     *
+     * A name the review roster draws takes its resolved colour, sanitized exactly as the
+     * paint sink sanitizes it: a declared colour the paint refuses falls to the author's
+     * ramp-slot token. Any other name takes the next slot from the engine's stable
+     * allocator, in first-resolution order, and keeps it for the session. While no document
+     * is attached this returns `'var(--doc-accent)'`, the same default the overlay CSS
+     * falls back to.
+     */
+    presenceColorFor(name: string): string;
+    /**
+     * The live collaboration replica, or null when this editor is not in a room.
+     *
+     * Presence chrome reads it from here rather than being handed it: the editor already holds
+     * the session a `collaborationModule` contributed, so a host that threads it down to every
+     * avatar and caret consumer is passing something the tree below it can already see.
+     */
+    collaborationSession(): EditorCollaborationSession | null;
     /**
      * The configured author used when a comment or reply omits an explicit author.
      *
@@ -853,6 +885,15 @@ type SectionAnchor =
     readonly kind: 'unaddressable';
 };
 
+/**
+ * What a host may set on a surface image insert.
+ *
+ * The decode port and the collaboration actor are the SURFACE's to supply. An actor a host
+ * could pass would be a second identity for the same mint, which is the thing actor-scoped
+ * allocation exists to prevent.
+ */
+type SurfaceInsertImageInput = Omit<InsertImageInput, 'decodePort' | 'actorId'>;
+
 /**
  * Every field of the Paragraph dialog, in the units the rest of this contract uses:
  * points for spacing, TWIPS for indents.
@@ -894,13 +935,17 @@ interface ParagraphPropertyEdit {
 }
 
 /**
- * How an edit is written.
+ * Which review write is being committed through `commitReviewOps`.
  *
- * `'suggest'` is the one that changes what the ops MEAN: the same keystroke becomes a `w:ins`
- * and the same Backspace becomes a `w:del` over the words it would have removed. `'view'`
- * refuses edits outright.
+ * The callback that performs the write is opaque, so a lane deciding whether to allow it cannot
+ * tell an Accept from a comment delete. That mattered once a replica was attached: these paths
+ * reach the store directly rather than through `applyTreeOps`, and the ones that graft a package
+ * and swap the shell record no primitive effects — they replicate as NOTHING, leaving the peer a
+ * `commentReference` naming a comment it never received. Naming the write lets each be admitted
+ * only once a two-replica test proves it arrives whole.
  */
-type SurfaceEditingMode = 'edit' | 'suggest' | 'view';
+type ReviewWriteIntent = 'revision-resolve' | 'comment-add' | 'comment-reply' | 'comment-resolve' | 'comment-delete' | 'package-scoped';
+
 /**
  * Content-control interaction lane on the paginated surface.
  *
@@ -941,6 +986,132 @@ interface ContentControlOps {
      */
     disabledReason(controlId: string, action: 'edit' | 'remove'): string | null;
 }
+/**
+ * Content-control chrome the surface owns, not the document.
+ *
+ * Boundary furniture visibility and form-fill navigation are surface chrome, not model
+ * bytes — toggling them never reflows layout records.
+ */
+interface ContentControlSurfaceState {
+    /** Show boundary chrome for every control. */
+    readonly showAll: boolean;
+    /** Tab / Shift+Tab navigate between editable controls. */
+    readonly formFill: boolean;
+    /** Innermost control containing the caret, or null. */
+    readonly activeControlId: string | null;
+}
+
+/**
+ * What one paint did.
+ *
+ * Four answers rather than a boolean, because the two FAILURES are different problems with
+ * different words for the user: `'nothingToPaint'` says the selection holds nothing the
+ * capture can reach, and `'refused'` says the document would not take the write — a locked
+ * content control, a collaboration gate, a document open for viewing. Collapsed to false,
+ * a refused paint told the reader to select some text.
+ *
+ * `'armed'` is the collapsed-caret outcome: no text to paint, so the character half went to
+ * the stored-marks lane and the next characters typed will carry it.
+ */
+type FormatPainterPaintResult = 'painted' | 'armed' | 'nothingToPaint' | 'refused';
+/** Word's Format Painter over the surface. */
+interface FormatPainterOps {
+    state(): FormatPainterSurfaceState;
+    /**
+     * Capture the formatting at the selection. False when the selection resolves to no span
+     * the layout has published yet — there is nothing to read.
+     */
+    capture(): boolean;
+    /** Paint the captured formatting over the current selection. */
+    apply(): FormatPainterPaintResult;
+    /**
+     * One press of the painter control, with Word's meaning.
+     *
+     * A press while the painter is off captures and arms it for a single application. A press
+     * that lands within the double-press window locks it on. A press while it is armed and
+     * outside that window turns it off.
+     *
+     * The double-press window is the ENGINE's, deliberately: the alternative is each adapter
+     * binding its own `dblclick` beside its own `click`, which is two hosts deciding
+     * separately what a double-click means and drifting the moment one of them changes.
+     *
+     * False when there was nothing at the selection to capture, so a control can report a
+     * refusal rather than looking as though it armed.
+     */
+    press(): boolean;
+    /** Turn the painter off, keeping the capture. `Esc` and a finished single application. */
+    disarm(): void;
+}
+
+/**
+ * Where the last pass spent its time, and how much work it actually did.
+ *
+ * The durations are the surface's own three phases — layout, paint, selection sync — timed
+ * separately because they fail separately: a full relayout, a full repaint and a forced
+ * reflow each have a different fix. The counters come free from machinery that already
+ * exists: the layout session says how much was re-placed versus reused, and the scheduler
+ * says how often work was thrown away as stale. `placed` equal to `total` on every
+ * keystroke is the one-glance sign that incremental layout is not engaging.
+ */
+interface PaginatedSurfacePerf {
+    /** Time the last layout pass took, in milliseconds. */
+    readonly layoutMs: number;
+    /** Time the last paint took — building and swapping the page DOM. */
+    readonly paintMs: number;
+    /** Time the last selection sync took — writing the model selection into the browser. */
+    readonly selectionMs: number;
+    /** Paragraphs the last pass re-placed, against the number in the document. */
+    readonly placed: number;
+    readonly total: number;
+    /** Pages carried over from the previous layout without being rebuilt. */
+    readonly reusedPages: number;
+    /** Passes that could not resume and laid the document out from the top. */
+    readonly fullPasses: number;
+    /** Layouts discarded because the model had already moved on. */
+    readonly staleDiscards: number;
+    /** Cooperative runs abandoned mid-flight for a newer revision. */
+    readonly cancelledRuns: number;
+}
+
+/**
+ * One live remote-caret label the engine positioned. The host owns its content; the engine
+ * still owns the label's geometry, class, and presence colour, and rebuilds the labels
+ * wholesale on every repaint that moves them.
+ *
+ * @public
+ */
+interface RemoteCaretLabelAnchor {
+    readonly element: HTMLElement;
+    readonly selection: CollaborationRemoteSelection;
+}
+/**
+ * A host that renders its own content inside the engine's remote-caret labels.
+ *
+ * @public
+ */
+interface RemoteCaretLabelHost {
+    /**
+     * Called after every paint that rebuilt the labels, with the current anchors.
+     *
+     * A skipped paint (nothing moved) does not re-publish: the host keeps its last anchors
+     * until the next publish, and elements from a previous publish are dead after the next
+     * one. An empty array is a real publish — every remote caret left the screen.
+     *
+     * Never mutate editor state synchronously from `publish` — a mutation repaints, and the
+     * nested rebuild's publish would arrive before this one returned; only set host state.
+     */
+    publish(anchors: readonly RemoteCaretLabelAnchor[]): void;
+}
+
+/**
+ * How an edit is written.
+ *
+ * `'suggest'` is the one that changes what the ops MEAN: the same keystroke becomes a `w:ins`
+ * and the same Backspace becomes a `w:del` over the words it would have removed. `'view'`
+ * refuses edits outright.
+ */
+type SurfaceEditingMode = 'edit' | 'suggest' | 'view';
+
 /**
  * How a paginated surface opens. Every field is optional.
  *
@@ -948,6 +1119,12 @@ interface ContentControlOps {
  * on a server, or leave it off in a browser to get the canvas measurer.
  */
 interface PaginatedSurfaceOptions {
+    /**
+     * The collaboration module's replica for this surface's session. Absent,
+     * the surface does not attach, and local store history remains the undo
+     * authority.
+     */
+    readonly collaborationModel?: CollaborationModuleContribution;
     readonly measurer?: TextMeasurer;
     /** Ambient author for tracked edits. Required before suggesting can write anything. */
     readonly author?: string;
@@ -1113,35 +1290,6 @@ interface SurfaceFormatting {
      */
     readonly disagrees: ParagraphDisagreements;
 }
-/**
- * Where the last pass spent its time, and how much work it actually did.
- *
- * The durations are the surface's own three phases — layout, paint, selection sync — timed
- * separately because they fail separately: a full relayout, a full repaint and a forced
- * reflow each have a different fix. The counters come free from machinery that already
- * exists: the layout session says how much was re-placed versus reused, and the scheduler
- * says how often work was thrown away as stale. `placed` equal to `total` on every
- * keystroke is the one-glance sign that incremental layout is not engaging.
- */
-interface PaginatedSurfacePerf {
-    /** Time the last layout pass took, in milliseconds. */
-    readonly layoutMs: number;
-    /** Time the last paint took — building and swapping the page DOM. */
-    readonly paintMs: number;
-    /** Time the last selection sync took — writing the model selection into the browser. */
-    readonly selectionMs: number;
-    /** Paragraphs the last pass re-placed, against the number in the document. */
-    readonly placed: number;
-    readonly total: number;
-    /** Pages carried over from the previous layout without being rebuilt. */
-    readonly reusedPages: number;
-    /** Passes that could not resume and laid the document out from the top. */
-    readonly fullPasses: number;
-    /** Layouts discarded because the model had already moved on. */
-    readonly staleDiscards: number;
-    /** Cooperative runs abandoned mid-flight for a newer revision. */
-    readonly cancelledRuns: number;
-}
 /** How a reveal places its target in the viewport. */
 interface RevealOptions {
     /**
@@ -1189,6 +1337,11 @@ interface PaginatedSurfaceState {
     readonly cellSelection: CellSelection | null;
     readonly canUndo: boolean;
     readonly canRedo: boolean;
+    /**
+     * Lifecycle of the attached replica, or `'inactive'` when no collaboration
+     * module is registered on this surface.
+     */
+    readonly collaborationStatus: CollaborationStatus | 'inactive';
     readonly lastRejection: string | null;
     /**
      * The typing format armed at the caret (Word's stored marks), or null.
@@ -1216,23 +1369,26 @@ interface PaginatedSurfaceState {
      * This is how a host's context menu learns it. Surface chrome, not document state.
      */
     readonly contextTocId: string | null;
+    /**
+     * Format painter arming, and the level of what it holds.
+     *
+     * Surface chrome, not document bytes — the lane `contentControls` above sits in, reported
+     * through the same `onChange` so a toolbar's pressed state has exactly one source.
+     */
+    readonly formatPainter: FormatPainterSurfaceState;
     /** Timing and reuse counters for the last pass. Diagnostics, not document state. */
     readonly perf: PaginatedSurfacePerf;
 }
 /**
- * Observable content-control interaction state on the paginated surface.
+ * Where the section after an inserted break begins — Word's Layout > Breaks menu.
  *
- * Boundary furniture visibility and form-fill navigation are surface chrome, not model
- * bytes — toggling them never reflows layout records.
+ * The two the engine paginates. `evenPage` / `oddPage` are readable in a file but not
+ * offered here, because layout does not skip the blank sheet they need yet, and a menu
+ * entry that silently behaves like `nextPage` is the lie this vocabulary exists to avoid.
+ *
+ * @public
  */
-interface ContentControlSurfaceState {
-    /** Show boundary chrome for every control. */
-    readonly showAll: boolean;
-    /** Tab / Shift+Tab navigate between editable controls. */
-    readonly formFill: boolean;
-    /** Innermost control containing the caret, or null. */
-    readonly activeControlId: string | null;
-}
+type SectionBreakInsertType = 'nextPage' | 'continuous';
 /**
  * The mounted, painted, editable document — the layer `createDocxEditor` builds its contract on.
  *
@@ -1245,12 +1401,14 @@ interface ContentControlSurfaceState {
  */
 interface PaginatedSurface {
     readonly session: TreeDocxSessionView;
+    /** The collaboration replica a `collaborationModule` attached, or null. */
+    collaborationSession(): EditorCollaborationSession | null;
     storyScope(): StoryScope;
     imageDecodePort(): ImageDecodePort;
     applyDrawingOps(ops: readonly DrawingTreeDocOp[]): TreeApplyResult;
     applyImageProperties(input: ApplyImagePropertiesInput): ImageIntentResult;
     deleteImage(drawingNodeId: string): ImageIntentResult;
-    insertImage(input: Omit<InsertImageInput, 'decodePort'>): Promise<ImageIntentResult>;
+    insertImage(input: SurfaceInsertImageInput): Promise<ImageIntentResult>;
     replaceImage(drawingNodeId: string, bytes: Uint8Array, mime: SupportedImageMime, options: {
         readonly expectedPackageRevision: number;
         readonly commitGuard?: () => boolean;
@@ -1265,14 +1423,11 @@ interface PaginatedSurface {
     /**
      * Queue plain typed text for a batched commit at the caret.
      *
-     * The DOM input lane's entry: keystrokes arriving in a burst append here and land
-     * through ONE `type()` call — one transaction, one undo step, one layout flush —
-     * when the input queue drains. Every surface-level mutation, selection or scope
-     * move, geometry read, composition start and teardown flushes the buffer first.
-     * Code reading `session` directly (its text or its bytes) sits BELOW the buffer
-     * and must call {@link flushPendingInput} first, as the facade's save/detach
-     * paths do. `type()` itself stays synchronous; automation and commands should
-     * keep calling it directly.
+     * The DOM input lane's entry: a burst of keystrokes appends here and lands through ONE
+     * `type()` call — one transaction, one undo step, one layout flush — when the queue drains.
+     * Every surface mutation, selection or scope move, geometry read, composition start and
+     * teardown flushes first. Code reading `session` directly sits BELOW the buffer and must
+     * call {@link flushPendingInput}, as save/detach do. `type()` stays synchronous.
      */
     enqueueType(text: string): void;
     /**
@@ -1518,11 +1673,33 @@ interface PaginatedSurface {
         readonly anchorParagraphId?: string;
     }): boolean;
     /**
-     * Insert a next-page section break at the caret: the paragraph splits, and the head
-     * ends a new section cloning the governing section's page setup — Word's Layout >
-     * Breaks > Next Page. One undoable step. Returns whether the break committed.
+     * Insert a section break at the caret: the paragraph splits, and the head ends a new
+     * section cloning the governing section's page setup — Word's Layout > Breaks. One
+     * undoable step. Returns whether the break committed.
+     *
+     * `breakType` says where the section AFTER the break begins: `'nextPage'` (the default,
+     * Word's Next Page) starts a new sheet, `'continuous'` keeps it on the sheet the
+     * previous section ended, which is how a mid-page column or margin change is authored.
      */
-    insertSectionBreak(): boolean;
+    insertSectionBreak(breakType?: SectionBreakInsertType): boolean;
+    /**
+     * Why {@link insertSectionBreak} would refuse this kind right now, or `null`.
+     *
+     * THE authority for the BREAK's own questions, so `Editor.can` and the write cannot answer
+     * those differently. Both halves are things only the surface knows: the LIVE editing mode
+     * (a document that declares `w:trackRevisions` opens suggesting without anyone passing a
+     * mode, and Review > Track Changes moves it again afterwards), and the paragraph the break
+     * would actually land in — which for a range in suggesting mode is past the struck words,
+     * not the selection's head.
+     *
+     * NOT the deletion's questions. A break replaces the selection first, and that deletion can
+     * cross content a control holds or a region protected some other way; only the store sees
+     * that, and it sees it at write time. So a range whose landing is fine while its deletion
+     * is not answers `null` here and refuses at the press — as every other replacing command in
+     * the engine does, less loudly. Story scope is gated separately again, because a caret in a
+     * header refuses every break kind for a different reason.
+     */
+    sectionBreakRefusal(breakType?: SectionBreakInsertType): string | null;
     /** The layout session, so a host or a test can see how much work a pass actually did. */
     layoutSession(): {
         readonly stats: {
@@ -1547,6 +1724,8 @@ interface PaginatedSurface {
      * Show-all and form-fill are surface chrome and never reflow layout.
      */
     readonly contentControls: ContentControlOps;
+    /** Word's Format Painter: capture, apply, and the transient armed mode. */
+    readonly formatPainter: FormatPainterOps;
     /** Whether a `rows`×`cols` table can be inserted at the caret. */
     canInsertTable(rows: number, cols: number): boolean;
     /**
@@ -1602,11 +1781,24 @@ interface PaginatedSurface {
      * its identity.
      */
     revisionAuthors(): ReadonlyMap<string, number>;
+    /** The presence colour the caret paints for `name`, sanitized as the paint sink is. */
+    remotePresenceColor(name: string): string | undefined;
     /**
      * Replace how tracked changes are coloured, live. Paint-level: the pages repaint without
      * remeasuring a line, and the caret, selection and undo history stay where they are.
      */
     setRevisionStyles(colors: RevisionStyles | undefined): void;
+    /**
+     * Hand remote-caret label content to the host, or take it back with `null`.
+     *
+     * With a host set, the engine still creates and positions each label (same class, same
+     * presence colour) but leaves it empty, marks it `data-docx-remote-actor`, and calls
+     * {@link RemoteCaretLabelHost.publish} after every paint that rebuilt the labels.
+     * Registration and unregistration repaint immediately, so the first publish fires
+     * without waiting for awareness to move and unregistering restores the default
+     * collaborator-name labels.
+     */
+    setRemoteCaretLabelHost(host: RemoteCaretLabelHost | null): void;
     /**
      * Commit ops that came from automation, through the gate a keystroke goes through.
      *
@@ -1627,10 +1819,23 @@ interface PaginatedSurface {
      * target is one this engine will not author, and the write is refused having changed nothing.
      */
     applyAutomationOps(staged: (relate: (url: string) => string | null) => readonly TreeDocOp[] | null, scope?: StoryScope): TreeApplyResult;
+    /**
+     * Which revision halves this surface is SHOWING.
+     *
+     * Read by the automation adapter so the object model's formatting reaches the same runs the
+     * toolbar does. A range's offsets cover every revision half whatever the view does with
+     * them, so with markup on, a selection over a struck word means one thing to a reader and
+     * would mean another to a script that assumed the resolved result.
+     */
+    revisionDisplayMode(): RevisionDisplayMode;
     /**
      * Commit review ops — accept, reject, a new comment — through the SAME path a keystroke
      * takes: layout, paint, and a caret clamped to what the document now holds.
      *
+     * `intent` names WHICH review write this is, so a lane that judges them can tell them apart.
+     * The callback is opaque, and a replica admits only the writes proven to replicate — see
+     * {@link ReviewWriteIntent}.
+     *
      * Applying them straight to the session skipped all three. Rejecting an insertion left the
      * pages painting text the tree no longer had, every card anchored where it used to be, and
      * the caret past the end of the paragraph — after which every keystroke was refused with
@@ -1639,7 +1844,7 @@ interface PaginatedSurface {
     commitReviewOps(run: () => {
         readonly committed: boolean;
         readonly reason?: unknown;
-    }): void;
+    }, intent?: ReviewWriteIntent): void;
     /**
      * The layout as last PUBLISHED, without forcing pending work.
      *
@@ -1653,14 +1858,12 @@ interface PaginatedSurface {
     /**
      * How the current selection came to address a drawing, if it does at all.
      *
-     * Word's rule: a caret NEXT TO a floating object is a text caret, never an object
-     * selection — only clicking the object (or an explicit host selection write) selects it.
-     * The engine's selection is a caret at the drawing's anchor offset either way, so the
-     * offsets alone cannot tell the two apart; this is the discriminator. `none` for a fresh
-     * mount (a document must not open with an image selected — the initial caret routinely
-     * coincides with a drawing anchored at offset zero) and after typing, caret keys, or a
-     * pointer press on anything that is not a drawing. `pointer` names the drawing the press
-     * landed on, so a stale press can never claim a different drawing the caret later visits.
+     * Word's rule: a caret NEXT TO a floating object is a text caret, never an object selection —
+     * only clicking the object (or a host selection write) selects it. The engine's selection is a
+     * caret at the anchor offset either way, so offsets cannot tell them apart; this is the
+     * discriminator. `none` for a fresh mount (the initial caret routinely coincides with a drawing
+     * anchored at offset zero) and after typing, caret keys, or a press on a non-drawing. `pointer`
+     * names the drawing the press landed on, so a stale press cannot claim a later one.
      */
     drawingSelectionIntent(): DrawingSelectionIntent;
     /**
@@ -1732,6 +1935,25 @@ interface PaginatedSurface {
     bookmarks(): BookmarkIndex;
     /** The selected text, for copy and cut. */
     selectedText(): string;
+    /**
+     * Every clipboard flavour for the current selection: plain text, and the interop HTML
+     * carrying the embedded fragment when the selection is a body-story range. A cell
+     * rectangle answers grid text plus a flattened table; `html` is null where only plain
+     * text should be written.
+     */
+    copyFlavours(): {
+        readonly text: string;
+        readonly html: string | null;
+    };
+    /**
+     * Route one paste payload by fidelity: embedded fragment, then external HTML, then
+     * plain text — degrading on decode, read, or apply refusal. Suggesting mode, non-body
+     * stories and an armed force-plain all land on the plain lane. False when the payload
+     * landed on no lane at all (nothing to insert).
+     */
+    pasteRich(text: string, html: string | null): boolean;
+    /** The next paste routes plain, whatever its payload carries (Cmd+Shift+V). */
+    armForcePlainPaste(): void;
     /** Remove the selection, if any. Returns whether anything was deleted. */
     deleteSelection(): boolean;
     navigate(command: NavigationCommand, extend?: boolean): void;
@@ -2305,8 +2527,15 @@ declare const CHROME_GROUPS: readonly [{
     }];
 }, {
     readonly id: "format";
-    readonly labelKey: "formattingBar.clearFormatting";
+    readonly labelKey: "formattingBar.groups.format";
     readonly controls: readonly [{
+        readonly id: "painter";
+        readonly labelKey: "formattingBar.formatPainterShortcut";
+        readonly paths: readonly string[];
+        readonly state: {
+            readonly kind: "command";
+        };
+    }, {
         readonly id: "clear";
         readonly labelKey: "formattingBar.clearFormatting";
         readonly paths: readonly string[];
@@ -2587,7 +2816,7 @@ type ChromeGroupId = 'history' | 'zoom' | 'styles' | 'font' | 'text' | 'script'
  *
  * @public
  */
-type ChromeSlotId = 'history.undo' | 'history.redo' | 'zoom.level' | 'styles.style' | 'font.family' | 'font.size' | 'text.bold' | 'text.italic' | 'text.underline' | 'text.strike' | 'text.color' | 'text.highlight' | 'text.link' | 'script.super' | 'script.sub' | 'alignment.left' | 'alignment.center' | 'alignment.right' | 'alignment.justify' | 'list.bullet' | 'list.numbered' | 'list.outdent' | 'list.indent' | 'list.lineSpacing' | 'format.clear' | 'review.comments' | 'review.editingMode' | 'contentControl.showAll' | 'contentControl.formFill' | 'contentControl.inspector' | 'contentControl.remove' | 'image.insert' | 'image.properties' | 'image.wrap' | 'image.altText' | 'table.insert' | 'table.borderTarget' | 'table.borderColor' | 'table.borderStyle' | 'table.borderWidth' | 'table.cellFill' | 'file.open' | 'file.save' | 'paragraph.dialog' | 'file.pageSetup' | 'insert.footnote' | 'insert.endnote' | 'insert.pageNumber' | 'insert.totalPages' | 'insert.sectionPages' | 'insert.pageXofY' | 'insert.pageBreak' | 'insert.sectionBreakNextPage' | 'insert.sectionBreakContinuous' | 'insert.toc';
+type ChromeSlotId = 'history.undo' | 'history.redo' | 'zoom.level' | 'styles.style' | 'font.family' | 'font.size' | 'text.bold' | 'text.italic' | 'text.underline' | 'text.strike' | 'text.color' | 'text.highlight' | 'text.link' | 'script.super' | 'script.sub' | 'alignment.left' | 'alignment.center' | 'alignment.right' | 'alignment.justify' | 'list.bullet' | 'list.numbered' | 'list.outdent' | 'list.indent' | 'list.lineSpacing' | 'format.painter' | 'format.clear' | 'review.comments' | 'review.editingMode' | 'contentControl.showAll' | 'contentControl.formFill' | 'contentControl.inspector' | 'contentControl.remove' | 'image.insert' | 'image.properties' | 'image.wrap' | 'image.altText' | 'table.insert' | 'table.borderTarget' | 'table.borderColor' | 'table.borderStyle' | 'table.borderWidth' | 'table.cellFill' | 'file.open' | 'file.save' | 'paragraph.dialog' | 'file.pageSetup' | 'insert.footnote' | 'insert.endnote' | 'insert.pageNumber' | 'insert.totalPages' | 'insert.sectionPages' | 'insert.pageXofY' | 'insert.pageBreak' | 'insert.sectionBreakNextPage' | 'insert.sectionBreakContinuous' | 'insert.toc';
 /**
  * Every control id in the chrome, as a literal union. Unique WITHIN a group, not
  * globally (`image.insert` / `table.insert`) — key consumers on {@link ChromeSlotId}.
@@ -2619,9 +2848,9 @@ declare function chromeSlotId(group: {
 declare function defaultChromeGroups(): readonly ChromeGroup[];
 /**
  * The formatting-bar groups for one editor snapshot: the default bar, plus the
- * contextual `image` group when a drawing is selected. Insertion without a selection is
- * not in the packaged chrome at all — a host that wants it places `image.insert` itself,
- * through `DocxEditor.Toolbar.ImageInsert` or `DocxEditor.Menu.ImageInsert`.
+ * contextual `image` group when a drawing is selected. Insertion without a selection
+ * lives in the packaged Insert menu (`CHROME_MENUS`), not in the bar — a host that wants
+ * a bar button places `DocxEditor.Toolbar.ImageInsert` itself.
  *
  * @public
  */
@@ -2883,6 +3112,18 @@ declare function tableChromeToolbarState(editor: Editor | null, slot: TableChrom
  * @public
  */
 declare function toolbarCommandState(editor: Editor | null, id: ChromeSlotId): ToolbarCommandState;
+/**
+ * Whether a slot's control renders as a TOGGLE — pressed or not — so it carries
+ * `aria-pressed`.
+ *
+ * Shared rather than derived per adapter, because it is not derivable from the command table
+ * alone: the format painter has no fixed command (a press captures, arms, locks or stands
+ * down, which no single `EditorCommand` describes), so a rule that only read `commandForSlot`
+ * left it announcing nothing at all to a screen reader while it was armed.
+ *
+ * @public
+ */
+declare function chromeSlotIsToggle(slotId: ChromeSlotId): boolean;
 /**
  * Enabled state for several controls in one pass.
  *
@@ -2958,4 +3199,4 @@ declare function runTableCommand(editor: Editor | null, command: EditorCommand):
  */
 declare function createDocxEditor(config: DocxEditorConfig): DocxEditorInstance;
 
-export { type SectionAnchor as $, type AnchorFrameOrigin as A, type FontResolutionRequest as B, CHROME_GROUPS as C, type DocxEditorInstance as D, EMU_PER_POINT as E, type FinalizedImageOverlayInteraction as F, type FontResolver as G, type FontUrlSource as H, type HyperlinkActivation as I, type HyperlinkChromeHandlers as J, type HyperlinkOps as K, IMAGE_OVERLAY_NUDGE_PT as L, IMAGE_OVERLAY_NUDGE_SHIFT_PT as M, type ImageInteractionSession as N, type OpenPaginatedResult as O, type PaginatedSurfaceOptions as P, type ImageOverlayScrollPort as Q, type ImageResizeHandle as R, type ImageResizeResult as S, type TableCommandPlan as T, type LoadFontsRequest as U, type LoadFontsResult as V, MAX_RESOLVER_FAMILIES as W, type OverlayFrameRect as X, type PaginatedSurfaceState as Y, type ParagraphPropertyEdit as Z, type RunTableChromeCommandResult as _, type PaginatedSurface as a, tableChromeIconPaths as a$, type SelectedDrawingOverlayTarget as a0, type SurfaceEquation as a1, type SurfaceFormatting as a2, type SurfaceHyperlink as a3, type SurfaceNavigation as a4, type SurfaceOverlayCoordinates as a5, type SurfaceParagraphFormat as a6, TABLE_BORDER_STYLE_OPTIONS as a7, TABLE_BORDER_TARGET_OPTIONS as a8, TABLE_BORDER_WIDTH_OPTIONS as a9, createDocxEditor as aA, createFontSource as aB, createImageOverlayScrollPort as aC, cssPixelsToLayoutPoints as aD, defaultChromeGroups as aE, defaultTableLabel as aF, emuToOverlayPoints as aG, equationAtPosition as aH, executeImageCommand as aI, finalizeImageOverlayInteraction as aJ, formattingBarChromeGroups as aK, isStaleImageInteractionCommit as aL, isTableChromeSlot as aM, layoutPointsToCssPixels as aN, loadFonts as aO, overlayFrameToSheetCssPixels as aP, overlayHostOrigin as aQ, pointsToEmu as aR, probeTableChromeCommand as aS, resizePreservesAspect as aT, runSave as aU, runTableChromeCommand as aV, runTableCommand as aW, runToolbarCommand as aX, selectedDrawingOverlayTargetOf as aY, selectedImageStateOf as aZ, surfacePaintScale as a_, TABLE_CHROME_SLOT_IDS as aa, type TableBorderStyleOption as ab, type TableBorderTargetOption as ac, type TableBorderTargetValue as ad, type TableBorderWidthOption as ae, type TableChromeDraft as af, type TableChromePick as ag, type TableChromeSlotId as ah, type TableInteractionLabelKey as ai, type ToolbarCommandState as aj, WORD_DEFAULT_FONT as ak, applyTableChromePick as al, blankDocumentBytes as am, canExecuteImageCommand as an, captureImageMutationPreconditions as ao, chromeControlCount as ap, chromeMenuSlots as aq, chromeProbeForSlot as ar, chromeSlotId as as, commandForSlot as at, commandForSlotValue as au, commandForTableChromeSlotValue as av, composeFontConfiguration as aw, computeImageResizeResult as ax, computeMovedImagePosition as ay, computeResizedImageExtentEmu as az, CHROME_MENUS as b, tableChromeLabelKeyForTarget as b0, tableChromeToolbarState as b1, tableChromeVisible as b2, tableCommandToolbarState as b3, toolbarCommandState as b4, toolbarCommandStates as b5, CHROME_UNAVAILABLE_KEY as c, type ChromeControl as d, type ChromeControlId as e, type ChromeControlState as f, type ChromeGroup as g, type ChromeGroupId as h, type ChromeMenu as i, type ChromeMenuEntry as j, type ChromeMenuId as k, type ChromeMenuItemEntry as l, type ChromeMenuSeparatorEntry as m, type ChromeMenuSubmenuEntry as n, type ChromeSlotId as o, DEFAULT_TABLE_CHROME_DRAFT as p, type DocxEditorConfig as q, type DrawingSelectionIntent as r, type EquationActivation as s, type EquationChromeHandlers as t, type EquationOps as u, type FontConfigurationBase as v, type FontConfigurationFragment as w, type FontLoadFailure as x, type FontLoadFailureReason as y, type FontMeasurementState as z };
+export { type RemoteCaretLabelHost as $, type AnchorFrameOrigin as A, type FontResolutionRequest as B, CHROME_GROUPS as C, type DocxEditorInstance as D, EMU_PER_POINT as E, type FinalizedImageOverlayInteraction as F, type FontResolver as G, type FontUrlSource as H, type HyperlinkActivation as I, type HyperlinkChromeHandlers as J, type HyperlinkOps as K, IMAGE_OVERLAY_NUDGE_PT as L, IMAGE_OVERLAY_NUDGE_SHIFT_PT as M, type ImageInteractionSession as N, type OpenPaginatedResult as O, type PaginatedSurfaceOptions as P, type ImageOverlayScrollPort as Q, type ImageResizeHandle as R, type ImageResizeResult as S, type TableCommandPlan as T, type LoadFontsRequest as U, type LoadFontsResult as V, MAX_RESOLVER_FAMILIES as W, type OverlayFrameRect as X, type PaginatedSurfaceState as Y, type ParagraphPropertyEdit as Z, type RemoteCaretLabelAnchor as _, type PaginatedSurface as a, runTableChromeCommand as a$, type ReviewWriteIntent as a0, type RunTableChromeCommandResult as a1, type SectionAnchor as a2, type SectionBreakInsertType as a3, type SelectedDrawingOverlayTarget as a4, type SurfaceEquation as a5, type SurfaceFormatting as a6, type SurfaceHyperlink as a7, type SurfaceInsertImageInput as a8, type SurfaceNavigation as a9, commandForSlotValue as aA, commandForTableChromeSlotValue as aB, composeFontConfiguration as aC, computeImageResizeResult as aD, computeMovedImagePosition as aE, computeResizedImageExtentEmu as aF, createDocxEditor as aG, createFontSource as aH, createImageOverlayScrollPort as aI, cssPixelsToLayoutPoints as aJ, defaultChromeGroups as aK, defaultTableLabel as aL, emuToOverlayPoints as aM, equationAtPosition as aN, executeImageCommand as aO, finalizeImageOverlayInteraction as aP, formattingBarChromeGroups as aQ, isStaleImageInteractionCommit as aR, isTableChromeSlot as aS, layoutPointsToCssPixels as aT, loadFonts as aU, overlayFrameToSheetCssPixels as aV, overlayHostOrigin as aW, pointsToEmu as aX, probeTableChromeCommand as aY, resizePreservesAspect as aZ, runSave as a_, type SurfaceOverlayCoordinates as aa, type SurfaceParagraphFormat as ab, TABLE_BORDER_STYLE_OPTIONS as ac, TABLE_BORDER_TARGET_OPTIONS as ad, TABLE_BORDER_WIDTH_OPTIONS as ae, TABLE_CHROME_SLOT_IDS as af, type TableBorderStyleOption as ag, type TableBorderTargetOption as ah, type TableBorderTargetValue as ai, type TableBorderWidthOption as aj, type TableChromeDraft as ak, type TableChromePick as al, type TableChromeSlotId as am, type TableInteractionLabelKey as an, type ToolbarCommandState as ao, WORD_DEFAULT_FONT as ap, applyTableChromePick as aq, blankDocumentBytes as ar, canExecuteImageCommand as as, captureImageMutationPreconditions as at, chromeControlCount as au, chromeMenuSlots as av, chromeProbeForSlot as aw, chromeSlotId as ax, chromeSlotIsToggle as ay, commandForSlot as az, CHROME_MENUS as b, runTableCommand as b0, runToolbarCommand as b1, selectedDrawingOverlayTargetOf as b2, selectedImageStateOf as b3, surfacePaintScale as b4, tableChromeIconPaths as b5, tableChromeLabelKeyForTarget as b6, tableChromeToolbarState as b7, tableChromeVisible as b8, tableCommandToolbarState as b9, toolbarCommandState as ba, toolbarCommandStates as bb, CHROME_UNAVAILABLE_KEY as c, type ChromeControl as d, type ChromeControlId as e, type ChromeControlState as f, type ChromeGroup as g, type ChromeGroupId as h, type ChromeMenu as i, type ChromeMenuEntry as j, type ChromeMenuId as k, type ChromeMenuItemEntry as l, type ChromeMenuSeparatorEntry as m, type ChromeMenuSubmenuEntry as n, type ChromeSlotId as o, DEFAULT_TABLE_CHROME_DRAFT as p, type DocxEditorConfig as q, type DrawingSelectionIntent as r, type EquationActivation as s, type EquationChromeHandlers as t, type EquationOps as u, type FontConfigurationBase as v, type FontConfigurationFragment as w, type FontLoadFailure as x, type FontLoadFailureReason as y, type FontMeasurementState as z };

package/dist/index.cjs

@@ -1 +1 @@
-'use strict';var chunkKQGENNL5_cjs=require('./chunk-KQGENNL5.cjs');require('./chunk-7ETDCPF6.cjs'),require('./chunk-6KNLLEUW.cjs'),require('./chunk-H2656QDI.cjs'),require('./chunk-O4UULRAQ.cjs'),require('./chunk-7UU5YFCD.cjs'),require('./chunk-7ADTI533.cjs'),require('./chunk-YMYCPY5Y.cjs'),require('./chunk-7VQ7YLW3.cjs');Object.defineProperty(exports,"CHROME_GROUPS",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.va}});Object.defineProperty(exports,"CHROME_MENUS",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.za}});Object.defineProperty(exports,"WORD_DEFAULT_FONT",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.f}});Object.defineProperty(exports,"blankDocumentBytes",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.h}});Object.defineProperty(exports,"chromeMenuSlots",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.Aa}});Object.defineProperty(exports,"commandForSlot",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.ja}});Object.defineProperty(exports,"commandForSlotValue",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.la}});Object.defineProperty(exports,"composeFontConfiguration",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.g}});Object.defineProperty(exports,"createDocxEditor",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.Ma}});Object.defineProperty(exports,"createFontSource",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.k}});Object.defineProperty(exports,"loadFonts",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.j}});Object.defineProperty(exports,"runToolbarCommand",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.qa}});Object.defineProperty(exports,"toolbarCommandState",{enumerable:true,get:function(){return chunkKQGENNL5_cjs.na}});
+'use strict';var chunk5AVHO75P_cjs=require('./chunk-5AVHO75P.cjs');require('./chunk-ZKWRCLT2.cjs'),require('./chunk-JUQOPVSK.cjs'),require('./chunk-UQFOYZJO.cjs'),require('./chunk-EJATEGJZ.cjs'),require('./chunk-M6Z3KFXM.cjs'),require('./chunk-GRDFEH5Q.cjs'),require('./chunk-76Y3Y45J.cjs'),require('./chunk-BTQKU64Q.cjs'),require('./chunk-WPQMPHNR.cjs'),require('./chunk-GWV65NQW.cjs'),require('./chunk-OHJQ7GPZ.cjs');Object.defineProperty(exports,"CHROME_GROUPS",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.wa}});Object.defineProperty(exports,"CHROME_MENUS",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.Aa}});Object.defineProperty(exports,"WORD_DEFAULT_FONT",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.f}});Object.defineProperty(exports,"blankDocumentBytes",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.h}});Object.defineProperty(exports,"chromeMenuSlots",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.Ba}});Object.defineProperty(exports,"commandForSlot",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.ja}});Object.defineProperty(exports,"commandForSlotValue",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.la}});Object.defineProperty(exports,"composeFontConfiguration",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.g}});Object.defineProperty(exports,"createDocxEditor",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.Na}});Object.defineProperty(exports,"createFontSource",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.k}});Object.defineProperty(exports,"loadFonts",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.j}});Object.defineProperty(exports,"runToolbarCommand",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.ra}});Object.defineProperty(exports,"toolbarCommandState",{enumerable:true,get:function(){return chunk5AVHO75P_cjs.na}});