@docx-editor.dev/core 2.10.0 → 2.11.0

package/dist/custom-node-writes-JfTn-Sy6.d.ts

@@ -0,0 +1,310 @@
+import { b as OoxmlPackage, O as OoxmlPart, a as OoxmlNode, r as TreeOpRejection } from './tree-op-types-DnzAOnc9.js';
+import { T as TreeModelChange, a as TreeDocumentStore } from './tree-store-CNZ3O83s.js';
+
+/** Which of a family's four faces an embedded font relationship supplies. */
+type FontStyleKey = 'regular' | 'bold' | 'italic' | 'boldItalic';
+/**
+ * One font whose bytes travel inside the package.
+ *
+ * The family name is the DOCUMENT's and is not validated — it is attacker-controlled, so it is
+ * escaped into CSS and never registered globally on `document.fonts`, where it would shadow the
+ * host application's own fonts.
+ */
+interface EmbeddedFont {
+    /** The family as the document names it. Not validated against anything. */
+    readonly family: string;
+    readonly style: FontStyleKey;
+    /** Deobfuscated bytes, ready to be offered to a font validator. */
+    readonly bytes: Uint8Array;
+    /** The part they came from, for diagnostics. */
+    readonly partName: string;
+}
+/**
+ * Undo Word's embedded-font obfuscation (ECMA-376 Part 4 §2.8.1).
+ *
+ * The key is the `w:fontKey` GUID's 16 bytes in REVERSED order — not the per-group
+ * little-endian reading a GUID usually gets. It is XORed over the first 32 bytes of the
+ * part, applied twice. Getting the order wrong produces a font that looks corrupt rather
+ * than obfuscated, which is indistinguishable from a damaged file at the point it fails.
+ *
+ * Pure XOR, so the same operation obfuscates and deobfuscates.
+ */
+declare function deobfuscateFont(bytes: Uint8Array, fontKey: string): Uint8Array | null;
+/** Limits and instrumentation for reading embedded fonts out of a package. */
+interface ReadEmbeddedFontsOptions {
+    /** Refuse a font part larger than this. Defaults to 16 MB. */
+    readonly maxFontBytes?: number;
+    /** Refuse more than this many fonts. Defaults to 64. */
+    readonly maxFonts?: number;
+}
+/**
+ * Every font the package embeds, deobfuscated.
+ *
+ * Silently skips anything malformed rather than rejecting the document: a broken font table
+ * is a reason to fall back to substitution, never a reason to refuse to open the file.
+ */
+declare function readEmbeddedFonts(pkg: OoxmlPackage, fontTable: OoxmlPart | undefined, options?: ReadEmbeddedFontsOptions): EmbeddedFont[];
+
+/** The two list kinds a toolbar offers. */
+type ListKind = 'bullet' | 'ordered';
+interface EnsuredListDefinition {
+    readonly pkg: OoxmlPackage;
+    /** The `w:numId` a paragraph's `w:numPr` should name. */
+    readonly numId: string;
+}
+/**
+ * Find or create a list definition of `kind`, returning the package that holds it.
+ *
+ * An existing abstract definition of the same kind is reused, but every disconnected list
+ * gets a fresh `w:num` instance. Counters belong to `w:num`, so reusing that instance would
+ * continue an earlier list. Returns null only when the part cannot be built at all.
+ */
+declare function ensureListDefinition(pkg: OoxmlPackage, kind: ListKind): EnsuredListDefinition | null;
+/**
+ * Declare `level` in the definition `numId` names, with Word's default format for that
+ * level, or refuse.
+ *
+ * Word never greys Increase Indent out on a list item: demoting past the deepest level a
+ * `w:abstractNum` declares makes Word DEFINE the level, cycling its stock bullets
+ * (Symbol •, Courier `o`, Wingdings ▪) or number formats (decimal, lowerLetter,
+ * lowerRoman) by depth. This is that write. An already-declared level returns the package
+ * unchanged, so callers may ask first and act second without a second lookup.
+ *
+ * A delegating definition (`w:numStyleLink`, 17.9.21) is refused: its levels live on the
+ * linked style's definition, and a `w:lvl` grafted here would be shadowed the moment the
+ * link resolves.
+ */
+declare function ensureNumberingLevel(pkg: OoxmlPackage, numId: string, level: number, kind: ListKind): OoxmlPackage | null;
+
+/** One bookmark's name and the range its marker pair currently encloses. */
+interface BookmarkAnchor {
+    readonly name: string;
+    /** Canonical node id of the paragraph the marker sits in. */
+    readonly paragraphId: string;
+    /** UTF-16 offset within that paragraph, in `paragraphTextOf`'s vocabulary. */
+    readonly offset: number;
+}
+/** Bookmarks by name. A name the document declares twice resolves to the first in order. */
+type BookmarkIndex = ReadonlyMap<string, BookmarkAnchor>;
+/**
+ * Build `name -> position` for every bookmark start in a part, in document order.
+ *
+ * FIRST IN DOCUMENT ORDER WINS on a duplicate name. Word treats a repeated bookmark name as
+ * the same bookmark and jumps to the first, and the alternative — last-wins — makes a jump
+ * target move when an edit far away happens to duplicate a name.
+ *
+ * The offset is measured the way the ops measure: text of the runs before the marker inside
+ * its own paragraph, hyperlink runs included, so the position a jump places the caret at is a
+ * position `setSelection` accepts.
+ */
+declare function buildBookmarkIndex(part: OoxmlPart): BookmarkIndex;
+
+/** What the document asks for. Every field defaults to "the document said nothing". */
+interface DocumentTrackingSettings {
+    /** `w:trackRevisions` — the document asks for edits to be tracked. */
+    readonly trackRevisions: boolean;
+    /**
+     * `w:documentProtection/@w:edit="trackedChanges"` — tracking may not be turned OFF.
+     *
+     * Advisory. Presenting it as enforcement would be a lie about a file anyone can edit.
+     */
+    readonly restrictedToTrackedChanges: boolean;
+    /** `w:doNotTrackMoves` — write a move as a delete and an insert. */
+    readonly doNotTrackMoves: boolean;
+    /** `w:doNotTrackFormatting` — apply formatting without recording a `w:rPrChange`. */
+    readonly doNotTrackFormatting: boolean;
+}
+/** The frozen "nothing is tracked" settings — what a document with no `w:trackChanges` gets. */
+declare const NO_TRACKING_SETTINGS: DocumentTrackingSettings;
+/** Read the tracking settings from a `settings.xml` root, or the defaults when it has none. */
+declare function readTrackingSettings(settingsRoot: OoxmlNode | null | undefined): DocumentTrackingSettings;
+
+/**
+ * The payload half of an insert: which store, which node, and what it holds.
+ *
+ * `data` is opaque here. The lane that owns a schema is the one that declared it, and a store
+ * that parsed payloads would be a second opinion about what a host's node means.
+ */
+interface CustomNodePayloadWrite {
+    /** Namespace of the store's root element — what identifies one store among several. */
+    readonly namespaceUri: string;
+    /** Local name of that root. An NCName; anything else refuses. */
+    readonly rootLocalName: string;
+    /** The node's own id, which the binding's xpath quotes. */
+    readonly nodeId: string;
+    /** The text the control shows. Word paints this from the store, so an empty one is an empty chip. */
+    readonly label: string;
+    /** The payload, serialized. JSON by convention; never parsed here. */
+    readonly data: string;
+}
+/** Where the control goes, what it says, and the payload it carries. */
+interface InsertCustomNodeWrite {
+    readonly paragraphId: string;
+    readonly offset: number;
+    /**
+     * Wrap rather than insert: the text from `offset` to here is removed first.
+     *
+     * The node's label REPLACES the words it covered, because that is what turning a stretch of a
+     * sentence into a citation means. Removed inside the same transaction, so a refused insert
+     * leaves the text where it was.
+     */
+    readonly replaceUntil?: number;
+    /**
+     * Rewrite an existing control: it and the payload it bound go first, in this transaction.
+     *
+     * An UPDATE is remove-and-reinsert, because the tag codec has no in-place rewrite and
+     * pretending it did would put a second write path beside this one. Doing both halves here is
+     * what keeps it one undo step, and what stops an update from leaving a label and a payload
+     * that disagree.
+     */
+    readonly replaceControlId?: string;
+    readonly tag: string;
+    readonly text: string;
+    readonly alias?: string;
+    /** Defaults to none. Callers that want Word's own "cannot type into it" pass `contentLocked`. */
+    readonly lock?: 'sdtLocked' | 'sdtContentLocked' | 'contentLocked';
+    /** Omitted authors an ordinary tagged control with no store — the pre-payload behaviour. */
+    readonly payload?: CustomNodePayloadWrite;
+}
+/**
+ * Why a payload write was refused.
+ *
+ * The tree rejections pass through unchanged, so a locked paragraph refuses a bound insert for
+ * the same named reason it refuses a plain one. The three added here are the payload's own.
+ */
+type CustomNodeWriteRejection = TreeOpRejection
+/** The id, root name or namespace cannot be spelled in an XPath, so no binding could name it. */
+ | 'unaddressable-payload'
+/** The store could not be authored — see `withCustomXmlDataPart` for every way that happens. */
+ | 'store-not-authored'
+/** The payload or the label is past the cap. */
+ | 'payload-too-large';
+type CustomNodeWriteResult = {
+    readonly ok: true;
+    readonly change: TreeModelChange | null;
+    /**
+     * The control this write authored, when it authored one. A rewrite replaces the control
+     * rather than editing it, so the id the caller passed in names nothing afterwards.
+     */
+    readonly nodeId?: string;
+} | {
+    readonly ok: false;
+    readonly reason: CustomNodeWriteRejection;
+    readonly detail?: string;
+};
+/**
+ * The largest payload one node may carry, in UTF-16 code units.
+ *
+ * Same figure as the read side's (`parseCustomNodeData`) and for the same reason: far past any
+ * legitimate chip, far short of anything that hurts. Checked on the WRITE too, so a document
+ * cannot be authored here holding a payload the reader will later refuse to parse.
+ */
+declare const MAX_CUSTOM_NODE_PAYLOAD_LENGTH: number;
+/** The longest label a binding may paint. Word renders it as the control's whole content. */
+declare const MAX_CUSTOM_NODE_LABEL_LENGTH = 4096;
+/**
+ * Insert one custom node, with its payload, as a single transaction.
+ *
+ * Answers the store transaction's own change so the caller can publish it — a payload write is a
+ * package write reaching through a story store, exactly as a comment is, and the coordinator
+ * needs the change to know which paragraphs went dirty.
+ */
+declare function insertCustomNodeWrite(store: TreeDocumentStore, write: InsertCustomNodeWrite, 
+/**
+ * The part the customXml store hangs off, defaulting to the story being written.
+ *
+ * A chip in a header is written against the HEADER store, but Word enumerates the data
+ * store from the main document part — a store authored off a header is one Word never
+ * sees. So the caller passes the main part while the control itself lands in the story.
+ */
+dataOwnerPartName?: string): CustomNodeWriteResult;
+/**
+ * Remove a control and, in the same transaction, the payload it bound.
+ *
+ * The sweep would collect the node eventually — that is what makes deletion in Word survivable —
+ * but "eventually" is the next open, and a document saved in between carries a payload for a
+ * chip that is gone. Doing it here means the ordinary case is exact and the sweep is a backstop.
+ */
+declare function removeCustomNodeWrite(store: TreeDocumentStore, controlNodeId: string): CustomNodeWriteResult;
+/**
+ * What one sweep collected, or why it collected nothing.
+ *
+ * `ok: false` is NOT "the document was already tidy" — that is `ok: true` with an empty
+ * `removed`. It means a store this sweep was asked to tidy refused the rewrite, which a caller
+ * that keeps saving into the same document should know about rather than silently retry forever.
+ */
+type CustomNodeSweepResult = {
+    readonly ok: true;
+    readonly pkg: OoxmlPackage;
+    /** Node ids removed, across every store swept. Empty means there were no orphans. */
+    readonly removed: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Drop every payload no control binds, in the stores whose namespaces a host claims.
+ *
+ * ON OPEN, NOT ON SAVE. A chip cut to the clipboard is unbound for as long as it sits there, so a
+ * save mid-cut would destroy the payload the user is about to paste. On open the only unbound
+ * nodes are ones a control genuinely lost — deleted here, or deleted in Word, which is the case
+ * nothing else can collect.
+ *
+ * `namespaces` is the claim, and it is what keeps this off other people's stores: Word's own Cover
+ * Page Properties store rides in most templates, and a sweep that walked every customXml part
+ * would be deleting from it on the strength of a name collision.
+ */
+declare function sweepCustomNodePayloads(pkg: OoxmlPackage, storyPartName: string, namespaces: readonly string[]): CustomNodeSweepResult;
+/** One control's payload, as the store holds it. Both strings are untrusted file input. */
+interface CustomNodePayloadRead {
+    /** The store node's own id. */
+    readonly nodeId: string;
+    /** The text Word paints the control from. */
+    readonly label: string;
+    /** The payload as authored. JSON by convention, unparsed here. */
+    readonly data: string;
+}
+/**
+ * The payload every control in a story binds to, keyed by the CONTROL's canonical node id.
+ *
+ * Keyed by the control rather than by the store node because that is the question a reader
+ * actually has — "what does this chip carry" — and because two stores may each hold a `cx1`.
+ * Resolved here rather than by a capability package: the stores are package parts, and a
+ * derivation that only gets story parts has no way to reach them.
+ *
+ * Every store the story relates to, so a document carrying two definitions' payloads answers
+ * for both without anyone naming a namespace.
+ */
+declare function customNodePayloadsByControl(pkg: OoxmlPackage, storyPartName: string, 
+/**
+ * The part that RELATES the customXml store, when it is not the story's own.
+ *
+ * Two different questions wear one name here: which part holds the CONTROLS, and which part
+ * relates the STORE they bind into. Word only reads a store hung off the main document part,
+ * so {@link writeCustomNode} already takes them separately — this read did not, and answered
+ * with the body's controls whatever story it was asked about. A chip in a header therefore
+ * read as having no payload at all, and an update that meant to keep the existing data
+ * dropped it.
+ */
+dataOwnerPartName?: string): ReadonlyMap<string, CustomNodePayloadRead>;
+/** Every payload one store holds, for a caller resolving a control's `data`. */
+declare function customNodePayloadsOf(pkg: OoxmlPackage, storyPartName: string, namespaceUri: string): ReadonlyMap<string, {
+    readonly label: string;
+    readonly data: string;
+}>;
+/**
+ * What the session answers for a sweep: the ids collected, or the reason none were.
+ *
+ * Narrower than {@link CustomNodeSweepResult}, which also carries the rewritten package — the
+ * session has already installed that, and handing it back would invite a caller to install it
+ * twice.
+ */
+type CustomNodeSweepOutcome = {
+    readonly ok: true;
+    readonly removed: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
+export { type BookmarkIndex as B, type CustomNodeWriteResult as C, type DocumentTrackingSettings as D, type EmbeddedFont as E, type FontStyleKey as F, type InsertCustomNodeWrite as I, type ListKind as L, MAX_CUSTOM_NODE_LABEL_LENGTH as M, NO_TRACKING_SETTINGS as N, type ReadEmbeddedFontsOptions as R, type CustomNodeSweepOutcome as a, type BookmarkAnchor as b, type CustomNodePayloadRead as c, type CustomNodePayloadWrite as d, type CustomNodeSweepResult as e, type CustomNodeWriteRejection as f, MAX_CUSTOM_NODE_PAYLOAD_LENGTH as g, buildBookmarkIndex as h, customNodePayloadsByControl as i, customNodePayloadsOf as j, deobfuscateFont as k, ensureListDefinition as l, ensureNumberingLevel as m, insertCustomNodeWrite as n, readTrackingSettings as o, removeCustomNodeWrite as p, readEmbeddedFonts as r, sweepCustomNodePayloads as s };

package/dist/document-properties-D6Ahr8D6.d.cts

@@ -0,0 +1,28 @@
+/**
+ * The document metadata Word's document-property fields render.
+ *
+ * Every member is optional: an absent part, an absent element, or an empty value all read as
+ * `undefined`, and a field over a missing property paints nothing. Keys are engine-internal
+ * names; the field → property mapping (`TITLE` → `title`, `AUTHOR` → `creator`, …) lives in
+ * `layout/field-doc-property.ts`.
+ */
+interface DocumentProperties {
+    /** `dc:title` — TITLE. */
+    readonly title?: string;
+    /** `dc:creator` — AUTHOR. */
+    readonly creator?: string;
+    /** `dc:subject` — SUBJECT. */
+    readonly subject?: string;
+    /** `cp:keywords` — KEYWORDS. */
+    readonly keywords?: string;
+    /** `cp:lastModifiedBy` — LASTSAVEDBY. */
+    readonly lastModifiedBy?: string;
+    /** `dc:description` — COMMENTS. */
+    readonly description?: string;
+    /** `Company` from `docProps/app.xml`. No field maps to it yet; carried for completeness. */
+    readonly company?: string;
+    /** `Manager` from `docProps/app.xml`. No field maps to it yet; carried for completeness. */
+    readonly manager?: string;
+}
+
+export type { DocumentProperties as D };

package/dist/document-properties-D6Ahr8D6.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The document metadata Word's document-property fields render.
+ *
+ * Every member is optional: an absent part, an absent element, or an empty value all read as
+ * `undefined`, and a field over a missing property paints nothing. Keys are engine-internal
+ * names; the field → property mapping (`TITLE` → `title`, `AUTHOR` → `creator`, …) lives in
+ * `layout/field-doc-property.ts`.
+ */
+interface DocumentProperties {
+    /** `dc:title` — TITLE. */
+    readonly title?: string;
+    /** `dc:creator` — AUTHOR. */
+    readonly creator?: string;
+    /** `dc:subject` — SUBJECT. */
+    readonly subject?: string;
+    /** `cp:keywords` — KEYWORDS. */
+    readonly keywords?: string;
+    /** `cp:lastModifiedBy` — LASTSAVEDBY. */
+    readonly lastModifiedBy?: string;
+    /** `dc:description` — COMMENTS. */
+    readonly description?: string;
+    /** `Company` from `docProps/app.xml`. No field maps to it yet; carried for completeness. */
+    readonly company?: string;
+    /** `Manager` from `docProps/app.xml`. No field maps to it yet; carried for completeness. */
+    readonly manager?: string;
+}
+
+export type { DocumentProperties as D };

package/dist/{editor-C0my6Uta.d.ts → editor-BogcVHXk.d.ts}

@@ -1,9 +1,9 @@
 import { DocEdits, DocQueries, DocQueryResults, ContentControlSummary } from './contracts/document.js';
-import { g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem } from './review-items-Dw-8a6Ie.js';
-import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-B6hFRQLy.js';
+import { g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem } from './review-items-CkYyXhXM.js';
+import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-COyhZ9WH.js';
+import { S as SourceCrop, D as DrawingKind, u as ImageWrapTarget, v as DrawingPositionInput, w as DrawingLocks, x as ImageResourceState, y as SupportedImageMime } from './tree-op-types-DnzAOnc9.js';
 import { ColorValue, ExecErrorCode, ParagraphFormatCommand, Watermark, DocAnchor, ExecResult, ContentControlFilter, DocRange, RunFormatting, Revision, Rect, SelectionPin, Unsubscribe } from './contracts/types.js';
-import { S as SourceCrop, b as ImageWrapTarget, c as SupportedImageMime, D as DrawingKind, d as DrawingPositionInput, e as DrawingLocks, f as ImageResourceState } from './tree-op-types-BuOfCrkp.js';
-import './tree-op-revision-attribution-CN06Xshv.js';
+import { C as CollaborationStatus } from './failure-BnGjoXf0.js';
 
 /**
  * `@docx-editor.dev/core/contracts/interaction` — semantic addressing and interaction outcomes.
@@ -247,6 +247,78 @@ interface EditorNoteCommands {
     };
 }
 
+/**
+ * Format painter commands for the Editor facade.
+ *
+ * Separated from `editor.ts` so the facade file stays under the max-lines gate while the
+ * painter keeps one cohesive vocabulary. Re-exported from `editor.ts`, so consumers keep
+ * importing `@docx-editor.dev/core/contracts/editor`.
+ */
+/**
+ * Word's Format Painter, as the two halves a keyboard user drives separately.
+ *
+ * The pair is deliberately NOT one command with a direction flag: `copyFormatting` reads
+ * and `pasteFormatting` writes, so they answer `can` differently — copying is allowed on a
+ * document open for viewing, and applying is not.
+ */
+interface EditorFormatPainterCommands {
+    /**
+     * Capture the formatting at the selection (Word's Ctrl+Shift+C).
+     *
+     * Reads the RESOLVED cascade rather than the direct run properties, so painting from a
+     * styled paragraph carries what the reader sees rather than the little the paragraph
+     * happens to state itself.
+     *
+     * The LEVEL follows the selection, as Word's does. A range inside one paragraph captures
+     * character formatting alone; a range that covers a paragraph mark — a whole paragraph, a
+     * multi-paragraph selection, or a collapsed caret — captures the paragraph style and its
+     * direct paragraph properties as well.
+     *
+     * Non-mutating: the capture lives on the editor, not in the document, and it survives
+     * until the next capture or until the editor is detached.
+     */
+    copyFormatting: Record<never, never>;
+    /**
+     * Apply the captured formatting to the current selection (Word's Ctrl+Shift+V).
+     *
+     * Refused with `no formatting has been copied` until `copyFormatting` has run. Paragraph
+     * formatting is applied only when the capture carries it; the text itself never moves.
+     *
+     * Three things stay on the TARGET rather than being painted over, because they are outside
+     * the property vocabulary an op may name — the same limit `clearFormatting` states:
+     * paragraph borders (`w:pBdr`), the run's character style (`w:rStyle`), and character
+     * shading (`w:rPr/w:shd`), which is resolved and painted but cannot be authored.
+     */
+    pasteFormatting: Record<never, never>;
+}
+/**
+ * How long the painter stays armed.
+ *
+ * Word's two gestures, named: a single press arms it for ONE application, a double press
+ * locks it on until the user presses `Esc`. `'off'` is the resting state.
+ */
+type FormatPainterMode = 'off' | 'once' | 'locked';
+/**
+ * What a capture carries.
+ *
+ * `'run'` is character formatting alone — the level a range INSIDE one paragraph copies.
+ * `'paragraph'` adds the paragraph style and its direct paragraph properties, which is what
+ * a selection covering a paragraph mark copies. `'none'` means nothing has been captured.
+ */
+type FormatPainterLevel = 'none' | 'run' | 'paragraph';
+/**
+ * Painter state, as the editor publishes it.
+ *
+ * Chrome state rather than document state, so it moves through the same report every other
+ * observable surface state uses — a toolbar's pressed state has one source. It lives in the
+ * CONTRACTS lane rather than beside the surface implementation because `EditorSnapshot`
+ * names it, and the contracts lane may not reach into the editor lane.
+ */
+interface FormatPainterSurfaceState {
+    readonly mode: FormatPainterMode;
+    readonly level: FormatPainterLevel;
+}
+
 /** Crop edge in UI percent (0–100). @public */
 interface ImageCropPercent {
     readonly left: number;
@@ -282,6 +354,58 @@ declare function cropPercentFromCropPermille(crop: ImageCropPermille): ImageCrop
  */
 declare function validateImageCropPercent(crop: ImageCropPercent): boolean;
 
+/**
+ * The selected-image read model, split out of `editor.ts`.
+ *
+ * Separated so the facade file stays under the max-lines gate while the image vocabulary
+ * stays one cohesive shape. Re-exported from `editor.ts`, so consumers keep importing
+ * `@docx-editor.dev/core/contracts/editor`.
+ */
+
+/**
+ * Canonical selected-image read model shared by {@link EditorSnapshot.image} and
+ * {@link Editor.getSelectedImage}.
+ *
+ * @public
+ */
+interface SelectedImageState {
+    readonly id: string;
+    readonly kind: DrawingKind;
+    readonly widthEmu: number;
+    readonly heightEmu: number;
+    /** Crop inset per edge in UI percent (0–100); OOXML stores permille (×1000). */
+    readonly crop: ImageCropPercent;
+    readonly rotationDegrees: number;
+    readonly wrap: ImageWrapTarget;
+    readonly position: DrawingPositionInput | null;
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly hyperlink: string | null;
+    readonly locks: DrawingLocks;
+    readonly hidden: boolean;
+    readonly resourceStatus: ImageResourceState['kind'];
+    readonly intrinsic: Readonly<{
+        readonly pixelWidth: number;
+        readonly pixelHeight: number;
+        readonly dpiX: number;
+        readonly dpiY: number;
+    }> | null;
+    readonly canResize: boolean;
+    readonly canMove: boolean;
+    readonly canChangeWrap: boolean;
+    readonly canCrop: boolean;
+}
+/**
+ * The selected image and what may be done to it — the `imageContext` query's answer.
+ *
+ * An alias of `SelectedImageState`, kept as its own name because it is the query's result type
+ * and chrome is written against it.
+ *
+ * @public
+ */
+type ImageContext = SelectedImageState;
+
 /** Which cell edges a table border command targets. */
 type TableBorderTarget = 'all' | 'outside' | 'inside' | 'none' | 'top' | 'bottom' | 'left' | 'right';
 /** Concrete scopes that apply a complete border spec. */
@@ -1147,7 +1271,7 @@ type DocumentEditingMode = 'editing' | 'suggesting' | 'viewing';
  * selection, view state, chrome modes, header/footer and note editing. An interface rather than a
  * closed union so an extension can widen it by declaration merging.
  */
-interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFooterCommands, EditorNoteCommands {
+interface EditorCommands extends EditorCommandShape<DocEdits>, EditorHeaderFooterCommands, EditorNoteCommands, EditorFormatPainterCommands {
     /** Switch how edits are written. A view command: it changes no document state. */
     setEditingMode: {
         mode: DocumentEditingMode;
@@ -1767,6 +1891,15 @@ interface EditorSnapshot {
      * vocabulary and memoized per revision.
      */
     readonly hasReviewContent?: boolean;
+    /**
+     * Lifecycle of the attached collaboration replica, or `'inactive'` when no
+     * collaboration module is registered.
+     *
+     * The free tier's honest upsell signal: a host can render from this value
+     * without importing `@docx-editor.dev/pro`. When a module is registered the
+     * field follows the session's `status()`.
+     */
+    readonly collaborationStatus: CollaborationStatus | 'inactive';
     /**
      * How edits are written right now.
      *
@@ -1791,50 +1924,13 @@ interface EditorSnapshot {
      * derived it; empty means every family resolved (or no document is loaded).
      */
     readonly fontSubstitutions?: readonly string[];
+    /**
+     * Format painter arming, and the level of what it holds. Here for the same reason
+     * `lastRejection` is: it moves no revision and no caret, so a mode the snapshot does not
+     * carry is a mode no toolbar can reflect. Optional and additive.
+     */
+    readonly formatPainter?: FormatPainterSurfaceState;
 }
-/**
- * Canonical selected-image read model shared by {@link EditorSnapshot.image} and
- * {@link Editor.getSelectedImage}.
- *
- * @public
- */
-interface SelectedImageState {
-    readonly id: string;
-    readonly kind: DrawingKind;
-    readonly widthEmu: number;
-    readonly heightEmu: number;
-    /** Crop inset per edge in UI percent (0–100); OOXML stores permille (×1000). */
-    readonly crop: ImageCropPercent;
-    readonly rotationDegrees: number;
-    readonly wrap: ImageWrapTarget;
-    readonly position: DrawingPositionInput | null;
-    readonly name: string;
-    readonly title: string;
-    readonly description: string;
-    readonly hyperlink: string | null;
-    readonly locks: DrawingLocks;
-    readonly hidden: boolean;
-    readonly resourceStatus: ImageResourceState['kind'];
-    readonly intrinsic: Readonly<{
-        readonly pixelWidth: number;
-        readonly pixelHeight: number;
-        readonly dpiX: number;
-        readonly dpiY: number;
-    }> | null;
-    readonly canResize: boolean;
-    readonly canMove: boolean;
-    readonly canChangeWrap: boolean;
-    readonly canCrop: boolean;
-}
-/**
- * The selected image and what may be done to it — the `imageContext` query's answer.
- *
- * An alias of `SelectedImageState`, kept as its own name because it is the query's result type
- * and chrome is written against it.
- *
- * @public
- */
-type ImageContext = SelectedImageState;
 /**
  * An error the engine raised, carrying a machine-readable `code` alongside the message.
  *
@@ -1859,4 +1955,4 @@ interface EditorEvents {
     error: (error: EditorError) => void;
 }
 
-export { type NotePropertiesState as $, type AuthoredNoteNumbering as A, type EditorHeaderFooterCommands as B, type CanResult as C, type DocumentSource as D, EditorFontError as E, type FontConfiguration as F, type EditorNoteCommands as G, type EditorPosition as H, type ImageContext as I, type EditorQueries as J, type EditorQuery as K, type EditorQueryResults as L, type EditorScope as M, type EditorSelection as N, type FurnitureVariant as O, type HeaderFooterSlotArgs as P, type HeaderFooterState as Q, type HyperlinkInfo as R, type SelectedImageState as S, type TableBorderEdgeTarget as T, type InteractionAffinity as U, type ViewScope as V, type InteractionOutcome as W, type InteractionOutcomeCode as X, type NoteKind as Y, type ZoomMode as Z, type NotePropertiesSide as _, type EditorSnapshot as a, type PageSetup as a0, type ResolvedNoteNumbering as a1, type ReviewActivationOptions as a2, type ReviewCommentPlacement as a3, type ReviewCustomPlacement as a4, type ReviewItemPlacement as a5, type ReviewItemPlacementBase as a6, type ReviewItemQuery as a7, type ReviewRevisionPlacement as a8, type SemanticIdentity as a9, type SemanticTarget as aa, type TableBorderTarget as ab, type TableCellVerticalAlignment as ac, type TableColumnDividerResizeTarget as ad, type TableColumnOccurrenceTarget as ae, type TableRightEdgeResizeTarget as af, type TableRowOccurrenceTarget as ag, type TextMatch as ah, type ZoomFitTarget as ai, type EditorCommand as b, type ImageCropPercent as c, type ImageCropPermille as d, cropPercentFromCropPermille as e, cropPercentFromPermille as f, cropPercentFromSourceCrop as g, cropPermilleFromCropPercent as h, cropPermilleFromPercent as i, type FontSource as j, type FontSourceSubstitution as k, type Editor as l, type FontFaceRequest as m, type TableBorderSpec as n, type TableBorderStyle as o, type TableContext as p, type DocumentChange as q, type DocumentEditingMode as r, sourceCropFromCropPercent as s, type DocumentHandle as t, type EditorCommandShape as u, validateImageCropPercent as v, type EditorCommands as w, type EditorError as x, type EditorEvents as y, type EditorFontErrorCode as z };
+export { type InteractionOutcome as $, type AuthoredNoteNumbering as A, type EditorFontErrorCode as B, type CanResult as C, type DocumentSource as D, EditorFontError as E, type FontConfiguration as F, type EditorFormatPainterCommands as G, type EditorHeaderFooterCommands as H, type ImageContext as I, type EditorNoteCommands as J, type EditorPosition as K, type EditorQueries as L, type EditorQuery as M, type EditorQueryResults as N, type EditorScope as O, type EditorSelection as P, type FormatPainterLevel as Q, type FormatPainterMode as R, type SelectedImageState as S, type TableBorderEdgeTarget as T, type FurnitureVariant as U, type ViewScope as V, type HeaderFooterSlotArgs as W, type HeaderFooterState as X, type HyperlinkInfo as Y, type ZoomMode as Z, type InteractionAffinity as _, type EditorSnapshot as a, type InteractionOutcomeCode as a0, type NoteKind as a1, type NotePropertiesSide as a2, type NotePropertiesState as a3, type PageSetup as a4, type ResolvedNoteNumbering as a5, type ReviewActivationOptions as a6, type ReviewCommentPlacement as a7, type ReviewCustomPlacement as a8, type ReviewItemPlacement as a9, type ReviewItemPlacementBase as aa, type ReviewItemQuery as ab, type ReviewRevisionPlacement as ac, type SemanticIdentity as ad, type SemanticTarget as ae, type TableBorderTarget as af, type TableCellVerticalAlignment as ag, type TableColumnDividerResizeTarget as ah, type TableColumnOccurrenceTarget as ai, type TableRightEdgeResizeTarget as aj, type TableRowOccurrenceTarget as ak, type TextMatch as al, type ZoomFitTarget as am, type EditorCommand as b, type ImageCropPercent as c, type ImageCropPermille as d, cropPercentFromCropPermille as e, cropPercentFromPermille as f, cropPercentFromSourceCrop as g, cropPermilleFromCropPercent as h, cropPermilleFromPercent as i, type FontSource as j, type FontSourceSubstitution as k, type Editor as l, type FormatPainterSurfaceState as m, type FontFaceRequest as n, type TableBorderSpec as o, type TableBorderStyle as p, type TableContext as q, type DocumentChange as r, sourceCropFromCropPercent as s, type DocumentEditingMode as t, type DocumentHandle as u, validateImageCropPercent as v, type EditorCommandShape as w, type EditorCommands as x, type EditorError as y, type EditorEvents as z };