@docx-editor.dev/core 2.30.0 → 2.31.0

package/dist/{tree-package-store-DKhdEVym.d.ts → tree-package-store-B8l8DX3Z.d.ts}

@@ -1,152 +1,4 @@
-import { S as SupportedImageMime, c as ImageDecodePort } from './image-resources-Bipz8toD.js';
-import { O as OoxmlPart, ay as OoxmlInvariantIssue, N as OoxmlNode, ah as OoxmlElement, Q as OoxmlPackage, ax as RevisionAttributionInput, az as DrawingTreeDocOp, aA as OoxmlParagraphNode, aB as OoxmlNoteNode, aC as OoxmlContinuationSeparatorNode, aD as OoxmlEndnotesNode, aE as OoxmlFootnotesNode, aF as OoxmlNoteRefNode, aG as OoxmlNoteReferenceNode, aH as OoxmlSeparatorNode, aI as ImpactClass, ag as TreeDocOp, av as TreeOpRejection } from './types-barrel-CA0xB8kH.js';
-
-/**
- * How saved field results are addressed.
- *
- * - `atomic`: every closed field is one offset unit.
- * - `editable`: the results of CREATEDATE, DATE, FILENAME, FILLIN, HYPERLINK, MERGEFIELD,
- *   PRINTDATE, QUOTE, SAVEDATE, SEQ, and TIME fields are text when their results are unnested.
- *   Simple fields inside complex field results are not supported in this mode. Other nested
- *   results, other field types, and legacy FORMTEXT inputs keep their existing addressing.
- */
-type FieldResultsMode = 'atomic' | 'editable';
-
-/** An edited part, or the invariant violations that rejected the edit. */
-type OoxmlEditResult = {
-    readonly ok: true;
-    readonly part: OoxmlPart;
-} | {
-    readonly ok: false;
-    readonly issues: readonly OoxmlInvariantIssue[];
-};
-/**
- * An opt-in relaxation of `ST_Lock` for hosts that protect WHAT a control says, not how it looks.
- *
- * ECMA-376 `contentLocked` forbids editing the control's contents and Word reads formatting as
- * part of that, which is the default here. A host that puts protected text in a control (a
- * template placeholder the user must not retype) but lets authors style it sets
- * `allowFormattingInLockedContent`: a run-property write (bold, colour, font, size, highlight …),
- * on runs or on a paragraph mark, then passes the CONTENT half of the lock. The exception never
- * admits a property that hides text (`w:vanish`, `w:specVanish`, `w:webHidden`), which the
- * run-property vocabulary refuses today anyway. Text edits, deletion of the content, paragraph properties,
- * removal of a `sdtLocked` wrapper and `w:dataBinding` refusals are unchanged.
- *
- * @public
- */
-interface ContentLockPolicy {
-    /** Let run formatting pass a content lock; text and removal stay refused. Default `false`. */
-    readonly allowFormattingInLockedContent?: boolean;
-}
-/**
- * How an edit primitive validates its result.
- *
- * By default every primitive runs the full-part invariant validation before handing its
- * result back — the safe reading for an isolated call. A TRANSACTION applying many ops pays
- * that full-tree walk once per primitive, which is what made a hundred-paragraph paste
- * quadratic; it defers instead, and runs the same validation ONCE on the final tree before
- * anything is published. Deferring is only sound for a caller that owns a commit boundary:
- * nothing may escape between the unvalidated intermediate and the validated result.
- */
-interface EditOptions {
-    readonly deferValidation?: boolean;
-    /**
-     * How a content control's `w:lock` is read for ops that only restyle text. Absent means
-     * the default: `contentLocked` / `sdtContentLocked` refuse every write, formatting included.
-     */
-    readonly contentLockPolicy?: ContentLockPolicy;
-    /**
-     * A shared minter for `@w:id` on a NEW revision, for the ops of one transaction.
-     *
-     * `nextRevisionId` walks the whole part to find the highest id in use, and a formatting
-     * write emits one op per run — so a Select All + Bold in suggesting mode paid a
-     * document-wide walk thousands of times over. The transaction hands its ops one minter
-     * instead, and it is DROPPED the moment an op that can import foreign revision ids runs
-     * (a paste carries its own), because a stale minter would hand out an id the document had
-     * just started using — and two revisions sharing an address are one card in the pane.
-     *
-     * Absent means "mint your own": every applier falls back to its own walk, which is what a
-     * caller outside a transaction gets.
-     */
-    readonly revisionIds?: () => string;
-    /**
-     * The transaction's revision-id bookkeeping for the tracked TEXT ops, where `revisionIds`
-     * above hands the property ops one shared id for their whole group.
-     *
-     * Absent means "mint your own and remember nothing", which is what a caller outside a
-     * transaction gets: every applier falls back to its own walk of the part.
-     */
-    readonly trackedRevisionIds?: TransactionRevisionIds;
-    /**
-     * How the op addresses saved field results (`field-result-mode.ts`). Absent keeps the mode
-     * of the enclosing store call, which is `atomic` outside any editable transaction.
-     */
-    readonly fieldResults?: FieldResultsMode;
-}
-/**
- * What one transaction knows about the revision ids its tracked text ops write.
- *
- * TWO questions, and they are the same bookkeeping. `nextRevisionId` walks the whole part, so
- * a replacement — a `deleteText` and an `insertText` in one transaction — walked it twice, and
- * on a five-hundred-page document that doubled the cost of every one. And an insertion aimed
- * at the front edge of a deletion relocates past it only when that deletion is THIS
- * transaction's own: typing over a selection. Backspace, then a keystroke, is two
- * transactions, and there the typed text belongs in FRONT of the struck character, as Word
- * writes it. Adjacency alone cannot tell the two apart; the ids can.
- */
-interface TransactionRevisionIds {
-    /** A fresh `@w:id`, from this transaction's one walk of the part. */
-    mint(): string;
-    /**
-     * Record a wrapper this transaction wrote, by its FULL `CT_TrackChange` identity — id,
-     * author and date, as `revisionKey` spells it. Not by the id alone: that number comes out
-     * of the file, nothing makes it unique, and a strike joining `w:id="3"` in one paragraph
-     * would otherwise claim an unrelated `w:id="3"` elsewhere as this edit's own.
-     */
-    wrote(key: string): void;
-    /** Whether this transaction wrote a wrapper with that identity. */
-    wroteUnder(key: string): boolean;
-}
-/** Every node id currently present in the part. */
-declare function collectNodeIds(part: OoxmlPart): Set<string>;
-/**
- * Mint ids for nodes an edit introduces.
- *
- * Deterministic and collision-checked against the whole part: a structural-path id from the
- * original parse (`/word/document.xml#0.1.2`) and a minted one (`/word/document.xml#new:3`)
- * can never coincide, and the counter skips anything already taken so repeated edits in one
- * session stay unique.
- *
- * Allocators share reservations across edited roots and restored roots. Preview edits,
- * detached nodes, and undo branches must not reuse an identity that collaboration retains.
- *
- * Checks the part's node index directly rather than copying every id into a fresh set: the
- * copy was O(document) per op, and an allocator is created for every op.
- */
-declare function createNodeIdAllocator(part: OoxmlPart, family?: 'new' | 'paste'): () => string;
-/** Whether a node id exists in the part. */
-declare function hasNode(part: OoxmlPart, nodeId: string): boolean;
-/** Read a node back out of a part by id. */
-declare function findNode(part: OoxmlPart, nodeId: string): OoxmlNode | null;
-/** The element that holds a node, or null for the root and for unknown ids. */
-declare function parentNodeOf(part: OoxmlPart, nodeId: string): OoxmlElement | null;
-/** Replace one node's children wholesale. */
-declare function replaceChildren(part: OoxmlPart, nodeId: string, children: readonly OoxmlNode[], options?: EditOptions): OoxmlEditResult;
-/** Insert children into a node at `index` (clamped to the child list). */
-declare function insertChildren(part: OoxmlPart, nodeId: string, index: number, children: readonly OoxmlNode[], options?: EditOptions): OoxmlEditResult;
-/** Replace one node with another, keeping its position among its siblings. */
-declare function replaceNode(part: OoxmlPart, nodeId: string, replacement: OoxmlNode, options?: EditOptions): OoxmlEditResult;
-/** Remove a node and its subtree. */
-declare function removeNode(part: OoxmlPart, nodeId: string, options?: EditOptions): OoxmlEditResult;
-/**
- * Apply several primitives as ONE atomic step.
- *
- * Each edit runs against the result of the previous one, and the whole sequence is
- * validated once at the end. If any step fails, the ORIGINAL part is what the caller keeps
- * — there is no partially-edited intermediate to publish. This is the shape a multi-`DocOp`
- * store transaction needs.
- */
-declare function applyEdits(part: OoxmlPart, edits: readonly ((current: OoxmlPart) => OoxmlEditResult)[], options?: EditOptions): OoxmlEditResult;
+import { Q as OoxmlPackage, af as SupportedImageMime, O as OoxmlPart, N as OoxmlNode, ap as OoxmlElement, aH as PackageWatermarkWrite, aI as OoxmlInvariantIssue, aE as ImageDecodePort, aG as RevisionAttributionInput, aJ as DrawingTreeDocOp, aK as ImpactClass, ao as TreeDocOp, aC as TreeOpRejection, aL as OoxmlParagraphNode, aM as OoxmlNoteNode, aN as OoxmlContinuationSeparatorNode, aO as OoxmlEndnotesNode, aP as OoxmlFootnotesNode, aQ as OoxmlNoteRefNode, aR as OoxmlNoteReferenceNode, aS as OoxmlSeparatorNode } from './types-barrel-CkF2JbU4.js';
 
 /** A freshly allocated drawing property id, or the reason one could not be minted. */
 type DrawingPropertyIdResult = {
@@ -210,52 +62,6 @@ interface ExternalImageFetchPort {
     }>>;
 }
 
-interface InsertImageInput {
-    readonly paragraphId: string;
-    readonly offset: number;
-    readonly bytes: Uint8Array;
-    readonly mime: SupportedImageMime;
-    readonly widthPoints: number;
-    readonly heightPoints: number;
-    readonly decodePort: ImageDecodePort;
-    readonly expectedPackageRevision: number;
-    readonly commitGuard?: () => boolean;
-    readonly title?: string;
-    readonly description?: string;
-    readonly hyperlink?: string;
-    /** Present in suggesting mode: the inserted drawing's run goes into a `w:ins`. */
-    readonly revision?: RevisionAttributionInput;
-    /**
-     * Collaboration actor for the ids this insert mints — `wp:docPr/@id`, the image
-     * relationship, and a hyperlink relationship when one is asked for.
-     *
-     * EXPLICIT, and not the ambient `runWithTransactionActor` binding, because this entry is
-     * async: the mint runs after `await validateEmbeddedImageForCommit` and the ambient actor
-     * is synchronous-only. A wrap around the call would compile, read as correct, and be gone
-     * by the time the id is taken. Omitted (solo) keeps Word's dense `highest + 1` sequence.
-     */
-    readonly actorId?: string;
-}
-interface ReplaceImageOptions {
-    readonly expectedPackageRevision: number;
-    readonly commitGuard?: () => boolean;
-    /** Collaboration actor for the replacement's minted ids. See {@link InsertImageInput.actorId}. */
-    readonly actorId?: string;
-}
-type ImageIntentResult = (Extract<PackageTransactResult, {
-    ok: true;
-}> & {
-    readonly drawingNodeId?: string;
-    readonly mediaPartName?: string;
-}) | Extract<PackageTransactResult, {
-    ok: false;
-}>;
-interface ApplyImagePropertiesInput {
-    readonly drawingNodeId: string;
-    readonly ops: readonly DrawingTreeDocOp[];
-    readonly hyperlink: string | null;
-}
-
 /** `w:headerReference w:type` vocabulary (ECMA-376 §17.10.5): default, first page, even pages. */
 type HeaderFooterVariant = 'default' | 'first' | 'even';
 /** Header vs footer region kind for chrome and lifecycle ops. */
@@ -369,6 +175,13 @@ type HeaderFooterLifecycleOp = {
      */
     readonly op: 'setDocumentProtection';
     readonly enforce: boolean;
+} | {
+    /**
+     * Replace the document watermark in every header a section shows; null removes it.
+     * It may create a section's default header, so it rides this lane's package undo unit.
+     */
+    readonly op: 'setWatermark';
+    readonly watermark: PackageWatermarkWrite | null;
 };
 /** Why a header/footer lifecycle op was refused. */
 type HeaderFooterLifecycleRejection = 'invalidArgs' | 'tree-invariant';
@@ -394,42 +207,600 @@ declare function isHeaderFooterLifecycleOp(op: {
  */
 declare function applyHeaderFooterLifecycleOp(pkg: OoxmlPackage, op: HeaderFooterLifecycleOp): HeaderFooterLifecycleResult;
 
-/** UTF-16 placeholder for one atomic note unit in `paragraphTextOf` / segments. */
-declare const NOTE_ATOM_CHAR = "\uFFFC";
-/** Signed 32-bit Word-compatible note id range (positive allocation only). */
-declare const NOTE_ID_MIN = 1;
-/** Largest note id Word accepts — signed 32-bit. */
-declare const NOTE_ID_MAX = 2147483647;
-/** Reserved separator / continuation ids — never allocated for normal notes. */
-declare const NOTE_SEPARATOR_ID = -1;
-/** Reserved id of the continuation-separator entry. Never allocated to a real note. */
-declare const NOTE_CONTINUATION_SEPARATOR_ID = 0;
-/** Which notes part a note lives in. Decides both placement and numbering rules. */
-type NoteKind = 'footnote' | 'endnote';
-/** Authored `ST_FtnEdn` including explicit `normal`. Absent means Word default (normal). */
 /**
- * What a note entry IS.
+ * How saved field results are addressed.
  *
- * Only `normal` is a note a reader sees. The others are the furniture Word stores in the same
- * part — the rules and notices drawn around the note area — reached by reserved ids.
+ * - `atomic`: every closed field is one offset unit.
+ * - `editable`: the results of CREATEDATE, DATE, FILENAME, FILLIN, HYPERLINK, MERGEFIELD,
+ *   PRINTDATE, QUOTE, SAVEDATE, SEQ, and TIME fields are text when their results are unnested.
+ *   Simple fields inside complex field results are not supported in this mode. Other nested
+ *   results, other field types, and legacy FORMTEXT inputs keep their existing addressing.
  */
-type NoteType = 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
-/** Parse a signed decimal note id; reject non-integers and out-of-int32 values. */
-declare function parseNoteId(raw: string | undefined): number | null;
+type FieldResultsMode = 'atomic' | 'editable';
+
+/** An edited part, or the invariant violations that rejected the edit. */
+type OoxmlEditResult = {
+    readonly ok: true;
+    readonly part: OoxmlPart;
+} | {
+    readonly ok: false;
+    readonly issues: readonly OoxmlInvariantIssue[];
+};
 /**
- * Canonical `EditorScope { kind: 'note'; id }` encoding.
+ * An opt-in relaxation of `ST_Lock` for hosts that protect WHAT a control says, not how it looks.
  *
- * Footnote id `1` and endnote id `1` coexist, so the kind is part of the string:
- * `footnote:2` / `endnote:-1`. Do not invent a parallel scope union arm.
+ * ECMA-376 `contentLocked` forbids editing the control's contents and Word reads formatting as
+ * part of that, which is the default here. A host that puts protected text in a control (a
+ * template placeholder the user must not retype) but lets authors style it sets
+ * `allowFormattingInLockedContent`: a run-property write (bold, colour, font, size, highlight …),
+ * on runs or on a paragraph mark, then passes the CONTENT half of the lock. The exception never
+ * admits a property that hides text (`w:vanish`, `w:specVanish`, `w:webHidden`), which the
+ * run-property vocabulary refuses today anyway. Text edits, deletion of the content, paragraph properties,
+ * removal of a `sdtLocked` wrapper and `w:dataBinding` refusals are unchanged.
+ *
+ * @public
  */
-declare function formatNoteScopeId(noteKind: NoteKind, noteId: number): string;
+interface ContentLockPolicy {
+    /** Let run formatting pass a content lock; text and removal stay refused. Default `false`. */
+    readonly allowFormattingInLockedContent?: boolean;
+}
 /**
- * Parse {@link formatNoteScopeId}. Returns `null` for malformed / out-of-range ids.
- */
-declare function parseNoteScopeId(id: string): {
-    readonly noteKind: NoteKind;
-    readonly noteId: number;
-} | null;
+ * How an edit primitive validates its result.
+ *
+ * By default every primitive runs the full-part invariant validation before handing its
+ * result back — the safe reading for an isolated call. A TRANSACTION applying many ops pays
+ * that full-tree walk once per primitive, which is what made a hundred-paragraph paste
+ * quadratic; it defers instead, and runs the same validation ONCE on the final tree before
+ * anything is published. Deferring is only sound for a caller that owns a commit boundary:
+ * nothing may escape between the unvalidated intermediate and the validated result.
+ */
+interface EditOptions {
+    readonly deferValidation?: boolean;
+    /**
+     * How a content control's `w:lock` is read for ops that only restyle text. Absent means
+     * the default: `contentLocked` / `sdtContentLocked` refuse every write, formatting included.
+     */
+    readonly contentLockPolicy?: ContentLockPolicy;
+    /**
+     * A shared minter for `@w:id` on a NEW revision, for the ops of one transaction.
+     *
+     * `nextRevisionId` walks the whole part to find the highest id in use, and a formatting
+     * write emits one op per run — so a Select All + Bold in suggesting mode paid a
+     * document-wide walk thousands of times over. The transaction hands its ops one minter
+     * instead, and it is DROPPED the moment an op that can import foreign revision ids runs
+     * (a paste carries its own), because a stale minter would hand out an id the document had
+     * just started using — and two revisions sharing an address are one card in the pane.
+     *
+     * Absent means "mint your own": every applier falls back to its own walk, which is what a
+     * caller outside a transaction gets.
+     */
+    readonly revisionIds?: () => string;
+    /**
+     * The transaction's revision-id bookkeeping for the tracked TEXT ops, where `revisionIds`
+     * above hands the property ops one shared id for their whole group.
+     *
+     * Absent means "mint your own and remember nothing", which is what a caller outside a
+     * transaction gets: every applier falls back to its own walk of the part.
+     */
+    readonly trackedRevisionIds?: TransactionRevisionIds;
+    /**
+     * How the op addresses saved field results (`field-result-mode.ts`). Absent keeps the mode
+     * of the enclosing store call, which is `atomic` outside any editable transaction.
+     */
+    readonly fieldResults?: FieldResultsMode;
+}
+/**
+ * What one transaction knows about the revision ids its tracked text ops write.
+ *
+ * TWO questions, and they are the same bookkeeping. `nextRevisionId` walks the whole part, so
+ * a replacement — a `deleteText` and an `insertText` in one transaction — walked it twice, and
+ * on a five-hundred-page document that doubled the cost of every one. And an insertion aimed
+ * at the front edge of a deletion relocates past it only when that deletion is THIS
+ * transaction's own: typing over a selection. Backspace, then a keystroke, is two
+ * transactions, and there the typed text belongs in FRONT of the struck character, as Word
+ * writes it. Adjacency alone cannot tell the two apart; the ids can.
+ */
+interface TransactionRevisionIds {
+    /** A fresh `@w:id`, from this transaction's one walk of the part. */
+    mint(): string;
+    /**
+     * Record a wrapper this transaction wrote, by its FULL `CT_TrackChange` identity — id,
+     * author and date, as `revisionKey` spells it. Not by the id alone: that number comes out
+     * of the file, nothing makes it unique, and a strike joining `w:id="3"` in one paragraph
+     * would otherwise claim an unrelated `w:id="3"` elsewhere as this edit's own.
+     */
+    wrote(key: string): void;
+    /** Whether this transaction wrote a wrapper with that identity. */
+    wroteUnder(key: string): boolean;
+}
+/** Every node id currently present in the part. */
+declare function collectNodeIds(part: OoxmlPart): Set<string>;
+/**
+ * Mint ids for nodes an edit introduces.
+ *
+ * Deterministic and collision-checked against the whole part: a structural-path id from the
+ * original parse (`/word/document.xml#0.1.2`) and a minted one (`/word/document.xml#new:3`)
+ * can never coincide, and the counter skips anything already taken so repeated edits in one
+ * session stay unique.
+ *
+ * Allocators share reservations across edited roots and restored roots. Preview edits,
+ * detached nodes, and undo branches must not reuse an identity that collaboration retains.
+ *
+ * Checks the part's node index directly rather than copying every id into a fresh set: the
+ * copy was O(document) per op, and an allocator is created for every op.
+ */
+declare function createNodeIdAllocator(part: OoxmlPart, family?: 'new' | 'paste'): () => string;
+/** Whether a node id exists in the part. */
+declare function hasNode(part: OoxmlPart, nodeId: string): boolean;
+/** Read a node back out of a part by id. */
+declare function findNode(part: OoxmlPart, nodeId: string): OoxmlNode | null;
+/** The element that holds a node, or null for the root and for unknown ids. */
+declare function parentNodeOf(part: OoxmlPart, nodeId: string): OoxmlElement | null;
+/** Replace one node's children wholesale. */
+declare function replaceChildren(part: OoxmlPart, nodeId: string, children: readonly OoxmlNode[], options?: EditOptions): OoxmlEditResult;
+/** Insert children into a node at `index` (clamped to the child list). */
+declare function insertChildren(part: OoxmlPart, nodeId: string, index: number, children: readonly OoxmlNode[], options?: EditOptions): OoxmlEditResult;
+/** Replace one node with another, keeping its position among its siblings. */
+declare function replaceNode(part: OoxmlPart, nodeId: string, replacement: OoxmlNode, options?: EditOptions): OoxmlEditResult;
+/** Remove a node and its subtree. */
+declare function removeNode(part: OoxmlPart, nodeId: string, options?: EditOptions): OoxmlEditResult;
+/**
+ * Apply several primitives as ONE atomic step.
+ *
+ * Each edit runs against the result of the previous one, and the whole sequence is
+ * validated once at the end. If any step fails, the ORIGINAL part is what the caller keeps
+ * — there is no partially-edited intermediate to publish. This is the shape a multi-`DocOp`
+ * store transaction needs.
+ */
+declare function applyEdits(part: OoxmlPart, edits: readonly ((current: OoxmlPart) => OoxmlEditResult)[], options?: EditOptions): OoxmlEditResult;
+
+interface InsertImageInput {
+    readonly paragraphId: string;
+    readonly offset: number;
+    readonly bytes: Uint8Array;
+    readonly mime: SupportedImageMime;
+    readonly widthPoints: number;
+    readonly heightPoints: number;
+    readonly decodePort: ImageDecodePort;
+    readonly expectedPackageRevision: number;
+    readonly commitGuard?: () => boolean;
+    readonly title?: string;
+    readonly description?: string;
+    readonly hyperlink?: string;
+    /** Present in suggesting mode: the inserted drawing's run goes into a `w:ins`. */
+    readonly revision?: RevisionAttributionInput;
+    /**
+     * Collaboration actor for the ids this insert mints — `wp:docPr/@id`, the image
+     * relationship, and a hyperlink relationship when one is asked for.
+     *
+     * EXPLICIT, and not the ambient `runWithTransactionActor` binding, because this entry is
+     * async: the mint runs after `await validateEmbeddedImageForCommit` and the ambient actor
+     * is synchronous-only. A wrap around the call would compile, read as correct, and be gone
+     * by the time the id is taken. Omitted (solo) keeps Word's dense `highest + 1` sequence.
+     */
+    readonly actorId?: string;
+}
+interface ReplaceImageOptions {
+    readonly expectedPackageRevision: number;
+    readonly commitGuard?: () => boolean;
+    /** Collaboration actor for the replacement's minted ids. See {@link InsertImageInput.actorId}. */
+    readonly actorId?: string;
+}
+type ImageIntentResult = (Extract<PackageTransactResult, {
+    ok: true;
+}> & {
+    readonly drawingNodeId?: string;
+    readonly mediaPartName?: string;
+}) | Extract<PackageTransactResult, {
+    ok: false;
+}>;
+interface ApplyImagePropertiesInput {
+    readonly drawingNodeId: string;
+    readonly ops: readonly DrawingTreeDocOp[];
+    readonly hyperlink: string | null;
+}
+
+/** How one transaction behaves: its story scope, its attribution, and its selection marks. */
+interface TransactOptions {
+    readonly origin?: string;
+    /** Stable actor attribution for collaboration and audit correlation. */
+    readonly actorId?: string;
+    /** Stable constituent identity for collaboration duplicate correlation. */
+    readonly operationId?: string;
+    /**
+     * Whether this transaction enters the legacy snapshot undo stack.
+     *
+     * Collaboration commits set this to false because their actor-local undo authority is the
+     * CRDT undo manager. Omitted preserves the ordinary non-collaborative history behavior.
+     */
+    readonly recordsHistory?: boolean;
+    /**
+     * A COMMAND is one user intent that may need several ops (a toolbar click applying a
+     * property across a multi-run selection). It is still exactly one history entry, which is
+     * the same rule a plain transaction follows — the option exists to say so explicitly at
+     * the call site rather than leaving it implied.
+     */
+    readonly scope?: 'transaction' | 'command';
+    /**
+     * Floor on the published impact. Header/footer story edits use `global` so every page
+     * sharing the part invalidates rather than keeping stale furniture.
+     */
+    readonly minimumImpact?: ImpactClass;
+    /** Story identity stamped onto the published ModelChange (package-aware targeting). */
+    readonly story?: TreeStoryRef;
+    /**
+     * The gesture this transaction belongs to: consecutive transactions carrying the SAME
+     * token extend one history entry (package from before the first, selection after the
+     * latest). Another token, none, undo or redo closes the group. See {@link HistoryGroup}.
+     */
+    readonly historyGroup?: HistoryGroup;
+    /**
+     * How the transaction's ops address saved field results. `atomic` (the default) keeps
+     * every field one offset unit; `editable` addresses saved results as text. See
+     * `field-result-mode.ts`.
+     */
+    readonly fieldResults?: FieldResultsMode;
+}
+/** How a store is constructed: its limits, its history depth, and its identity source. */
+interface TreeDocumentStoreOptions {
+    /** Bound on retained history entries. Oldest entries drop first. */
+    readonly historyLimit?: number;
+    /**
+     * The document's `settings.xml`, for a store built from a PART rather than a package.
+     *
+     * Forms protection lives one part up from the op, and a store built from a part gets a
+     * synthetic one-part package that cannot see it — so `w:documentProtection w:edit="forms"`
+     * was enforced in the body and nowhere else, and a header, a footer or a note accepted every
+     * write a protected document is supposed to refuse. Read through a getter, not captured: a
+     * document can gain or lose protection while its stories stay open.
+     */
+    readonly settingsPart?: () => OoxmlPart | null | undefined;
+    /**
+     * Opt-in relaxation of `w:lock` for run-property writes. See {@link ContentLockPolicy};
+     * absent, `contentLocked` and `sdtContentLocked` refuse formatting like any other write.
+     */
+    readonly contentLockPolicy?: ContentLockPolicy;
+}
+
+/** A selection the caller wants restored when an entry is undone or redone. */
+/** A selection captured with a transaction, so undo restores where the caret was. */
+interface SelectionMark {
+    readonly paragraphId: string;
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Which editable story a ModelChange came from.
+ *
+ * Mirrors `EditorScope` for body and header/footer — `{ kind: 'headerFooter'; rId }` —
+ * so package-aware mutation and the public scope contract stay one vocabulary. Body
+ * commits omit `rId`; header/footer commits carry the relationship id that addressed
+ * the part. Notes parts use `{ kind: 'notesPart'; noteKind }` (one store per part).
+ */
+/** Which story a transaction targets: the body, a header/footer part, or a notes part. */
+type TreeStoryRef = {
+    readonly kind: 'body';
+    readonly partName: string;
+} | {
+    readonly kind: 'headerFooter';
+    readonly partName: string;
+    readonly rId: string;
+} | {
+    readonly kind: 'notesPart';
+    readonly partName: string;
+    readonly noteKind: 'footnote' | 'endnote';
+};
+/**
+ * What one committed transaction changed: the revision, the ids touched, and the impact class.
+ *
+ * The ids are what let layout and paint re-do only the affected blocks instead of the document.
+ */
+interface TreeModelChange {
+    readonly change: 'model-change';
+    readonly fromRevision: number;
+    readonly toRevision: number;
+    readonly commitId: string;
+    readonly origin: string;
+    /** Stable collaboration actor attribution, when the caller supplied it. */
+    readonly actorId?: string;
+    /** Stable collaboration operation identity, when the caller supplied it. */
+    readonly operationId?: string;
+    readonly dirty: readonly string[];
+    readonly created: readonly string[];
+    readonly deleted: readonly string[];
+    readonly splitJoin: readonly ({
+        readonly split: {
+            readonly from: string;
+            readonly tail: string;
+        };
+    } | {
+        readonly join: {
+            readonly kept: string;
+            readonly removed: string;
+        };
+    })[];
+    readonly dependencyKeys: readonly string[];
+    /** The widest impact among the transaction's ops — what layout must scope to. */
+    readonly impact: ImpactClass;
+    /**
+     * Story that published this change. Absent on body-only store publishes that predate
+     * package-aware targeting; `TreePackageStore` always sets it.
+     */
+    readonly story?: TreeStoryRef;
+    /**
+     * Committed collapsed caret for this transaction, when one exists.
+     * Matches history `selectionAfter` when that mark is collapsed; absent for explicit
+     * null, non-collapsed explicit selection, or when no caret was committed.
+     */
+    readonly caret?: SelectionMark;
+}
+/** Whether a transaction committed, or the typed reason it was refused. */
+type TransactResult = {
+    readonly ok: true;
+    readonly change: TreeModelChange | null;
+} | {
+    readonly ok: false;
+    readonly reason: TreeOpRejection;
+    readonly detail?: string;
+};
+/** What a transaction body is handed: the working tree, and the means to stage ops against it. */
+interface TransactionContext {
+    /** Stage one op against the STORY part. Returns false once the transaction has failed. */
+    apply(op: TreeDocOp): boolean;
+    /**
+     * Stage one op against a named part.
+     *
+     * A comment body lives in `comments.xml` and is edited by the same ops that edit the story,
+     * so this is `apply` with the target named rather than a second vocabulary.
+     */
+    applyTo(partName: string, op: TreeDocOp): boolean;
+    /**
+     * Stage a whole-package edit: a new part, a relationship, a content-type override.
+     *
+     * The edit is a pure function of the working package, so a rejected transaction discards it
+     * with everything else. Returning the SAME package is a no-op, not a failure — a primitive
+     * that finds nothing to do says so that way.
+     *
+     * Engine package edits refuse by throwing the internal `PackageEditRefusal`
+     * (`package-edit-refusal.ts`): the transaction is refused with its reason, `package-changed`
+     * by default, and nothing is applied. Any other throw escapes `transact` as a crash.
+     */
+    applyPackage(edit: (pkg: OoxmlPackage) => OoxmlPackage): boolean;
+    /** The selection to restore when this entry is undone. */
+    selectionBefore(selection: SelectionMark | null): void;
+    /** The selection to restore when this entry is redone. */
+    selectionAfter(selection: SelectionMark | null): void;
+}
+interface HistoryEntry {
+    /**
+     * The whole package as it was, not just the story part.
+     *
+     * Affordable for the same reason a part snapshot was: parts are immutable and deep-frozen, so
+     * a package snapshot is a Map of references and every part the transaction did not touch is
+     * object-identical to the one before it. Undo stays a pointer swap, and it now reverses every
+     * part one intent wrote rather than only the story.
+     */
+    readonly pkg: OoxmlPackage;
+    readonly revision: number;
+    readonly selectionBefore: SelectionMark | null;
+    readonly selectionAfter: SelectionMark | null;
+    /**
+     * The gesture this entry is still collecting, while it is the newest entry and nothing
+     * has closed it. Only ever set on the top of the undo stack: {@link closeHistoryGroup}
+     * strips it, and undo and redo never copy it onto the entries they push.
+     */
+    readonly group?: HistoryGroup;
+}
+/**
+ * Opaque document+history checkpoint for package-coordinator rollback.
+ * Used when a story mutation may promote to a package undo unit (note-ref cascade).
+ */
+/** A restorable point in history — one entry of the intent-scoped undo stack. */
+interface TreeDocumentCheckpoint {
+    /**
+     * The whole package, not one part. The store owns the package so a transaction spanning
+     * several parts is one publication — a checkpoint of only the story part could not roll
+     * back the comment or numbering part the same transaction wrote.
+     */
+    readonly pkg: OoxmlPackage;
+    readonly revision: number;
+    readonly undoStack: readonly HistoryEntry[];
+    readonly redoStack: readonly HistoryEntry[];
+    readonly composition: {
+        readonly entry: HistoryEntry;
+        readonly committed: boolean;
+    } | null;
+}
+/**
+ * The document store: one transaction is one atomic publication and one history entry.
+ *
+ * `apply` STAGES ops against a working part and nothing is visible until `transact` returns, so a
+ * batch rejected halfway leaves the revision, the tree, the indexes and every subscriber exactly
+ * as they were. That all-or-nothing property is what lets a caller compose ops without having to
+ * reason about partial application.
+ */
+declare class TreeDocumentStore {
+    private current;
+    /** The part `apply` targets and `part` returns: the story this store is editing. */
+    private readonly storyPartName;
+    private rev;
+    private commitCounter;
+    private readonly undoStack;
+    private readonly redoStack;
+    private pushCount;
+    private readonly subscribers;
+    private readonly historyLimit;
+    /** See {@link TreeDocumentStoreOptions.settingsPart}. */
+    private readonly settingsPartOverride;
+    /** See {@link TreeDocumentStoreOptions.contentLockPolicy}. */
+    private readonly contentLockPolicy;
+    /** Package-aware story tag applied to publishes (including undo/redo). */
+    private storyRef;
+    /** Open composition, if any. While set, transactions extend one entry (task 5.5). */
+    private composition;
+    /**
+     * Open a store over a package, editing the named story part.
+     *
+     * A bare part is accepted and wrapped in a single-part package, so callers that never open a
+     * real package — tests, headless tooling — are unaffected by the widening.
+     */
+    constructor(source: OoxmlPart | OoxmlPackage, storyPartNameOrOptions?: string | TreeDocumentStoreOptions, maybeOptions?: TreeDocumentStoreOptions);
+    /**
+     * Stamp story identity onto subsequent publishes for this store (including undo/redo).
+     * Used by the package coordinator so history navigation keeps the same scope tag.
+     */
+    setStoryRef(story: TreeStoryRef | null): void;
+    /** The story part being edited. Unchanged for every caller that predates the widening. */
+    get part(): OoxmlPart;
+    /** Every part, including the ones a multi-part transaction wrote. */
+    get package(): OoxmlPackage;
+    get revision(): number;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /** Retained entries — the unit `undo()` reverses, so tests can assert grouping. */
+    get historyDepth(): number;
+    /**
+     * How many entries this store has ever pushed. Monotonic, unlike `historyDepth`, which
+     * stands still at the history limit because the oldest entry is shifted out.
+     * @internal
+     */
+    get historyPushCount(): number;
+    get compositionActive(): boolean;
+    /**
+     * Replace the package OUTSIDE the transaction and history lanes.
+     *
+     * For package writes that are not a user intent and publish no revision: grafting
+     * `numbering.xml` into a document that never had one, which the caller performs as a
+     * precondition of the list op that follows. Those edits were previously kept in a package
+     * variable beside the store, which meant two owners of one value and, predictably, two
+     * values — a graft written to one and a save read from the other.
+     *
+     * Deliberately narrow and deliberately awkward to reach for: anything a user did belongs in
+     * `transact`, where it gets a revision, an undo entry and the invariant checks.
+     */
+    graftPackage(edit: (pkg: OoxmlPackage) => OoxmlPackage): void;
+    /**
+     * Replace the current part without recording history, but advance the revision so
+     * revision-keyed projections cannot survive a package snapshot install.
+     */
+    replacePart(part: OoxmlPart): void;
+    /**
+     * Snapshot part, revision, and undo/redo stacks so the package coordinator can roll
+     * back a story transaction that fails after commit (e.g. note-reference cascade) or
+     * discard a local history entry when promoting to a package undo unit.
+     */
+    checkpoint(): TreeDocumentCheckpoint;
+    /** Full restore — part, revision, history stacks, and composition. */
+    restoreCheckpoint(checkpoint: TreeDocumentCheckpoint): void;
+    /**
+     * Restore undo/redo stacks only, keeping the current part and revision.
+     * Used when a story mutation is promoted to a package history pointer so the local
+     * orphan entry does not steal a later undo.
+     */
+    restoreHistoryStacks(checkpoint: TreeDocumentCheckpoint): void;
+    subscribe(listener: (change: TreeModelChange) => void): () => void;
+    /**
+     * Run one atomic transaction.
+     *
+     * Ops are staged against a working copy. On the first rejection the whole transaction is
+     * abandoned: no revision, no history entry, no notification. On success exactly one
+     * revision is published and exactly one history entry is recorded — unless a composition
+     * is open, in which case the entry already exists and this transaction joins it.
+     */
+    transact(build: (ctx: TransactionContext) => void, options?: TransactOptions): TransactResult;
+    private commitTransaction;
+    /**
+     * Open one history entry for an IME composition.
+     *
+     * Everything committed until `endComposition` collapses into this single entry, which is
+     * what makes a composed word one undo step rather than one per intermediate transaction.
+     */
+    beginComposition(selectionBefore?: SelectionMark | null): void;
+    /** Close the composition, recording its entry only if anything actually committed. */
+    endComposition(): void;
+    /**
+     * Cancel an open composition without recording an entry, leaving whatever it committed
+     * in place. An IME cancel is not an undo request; the caller decides what to revert.
+     */
+    cancelComposition(): void;
+    /**
+     * Close the open history group, if any: the next transaction records its own entry.
+     * The store does this itself for another token, none, undo and redo; the package
+     * coordinator does it for history moving ABOVE the store (a package unit, another
+     * story's pointer), which the store cannot see.
+     */
+    closeHistoryGroup(): void;
+    undo(): TreeModelChange | null;
+    redo(): TreeModelChange | null;
+    /** The selection to restore for the entry `undo()` would reverse next. */
+    selectionForUndo(): SelectionMark | null;
+    /** The selection to restore for the entry `redo()` would reapply next. */
+    selectionForRedo(): SelectionMark | null;
+    /**
+     * Remove the newest undo entry and answer its selections, for the package coordinator
+     * when a package history group absorbs the story pointer that entry belonged to.
+     * @internal
+     */
+    discardNewestUndoEntry(): Pick<HistoryEntry, 'selectionBefore' | 'selectionAfter'> | null;
+    private pushUndo;
+    private publish;
+}
+
+/**
+ * The identity of one continuous user gesture, for history grouping.
+ *
+ * A live color picker, a font-size stepper or a spacing slider applies every intermediate
+ * value so the document updates under the pointer, and each of those writes is a
+ * transaction in its own right — it must render, and a collaborator must receive it. What
+ * they are NOT is separate undo steps. The caller mints one token when the gesture starts
+ * (`Symbol('color-drag')`) and passes it with every write until the gesture ends.
+ *
+ * A symbol rather than a string, so two unrelated callers cannot collide by naming their
+ * gesture the same way, and so a token cannot outlive its gesture by accident through
+ * serialization.
+ */
+type HistoryGroup = symbol;
+type HistoryCaptureKind = 'started' | 'extended' | 'split';
+type HistoryCaptureReason = 'package-unit' | 'composition';
+declare function observeHistoryGroup<T>(group: HistoryGroup, report: (kind: HistoryCaptureKind, reason?: HistoryCaptureReason) => void, run: () => T): T;
+declare function reportHistoryGroup(group: HistoryGroup | undefined, kind: HistoryCaptureKind, reason?: HistoryCaptureReason): void;
+
+/** UTF-16 placeholder for one atomic note unit in `paragraphTextOf` / segments. */
+declare const NOTE_ATOM_CHAR = "\uFFFC";
+/** Signed 32-bit Word-compatible note id range (positive allocation only). */
+declare const NOTE_ID_MIN = 1;
+/** Largest note id Word accepts — signed 32-bit. */
+declare const NOTE_ID_MAX = 2147483647;
+/** Reserved separator / continuation ids — never allocated for normal notes. */
+declare const NOTE_SEPARATOR_ID = -1;
+/** Reserved id of the continuation-separator entry. Never allocated to a real note. */
+declare const NOTE_CONTINUATION_SEPARATOR_ID = 0;
+/** Which notes part a note lives in. Decides both placement and numbering rules. */
+type NoteKind = 'footnote' | 'endnote';
+/** Authored `ST_FtnEdn` including explicit `normal`. Absent means Word default (normal). */
+/**
+ * What a note entry IS.
+ *
+ * Only `normal` is a note a reader sees. The others are the furniture Word stores in the same
+ * part — the rules and notices drawn around the note area — reached by reserved ids.
+ */
+type NoteType = 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
+/** Parse a signed decimal note id; reject non-integers and out-of-int32 values. */
+declare function parseNoteId(raw: string | undefined): number | null;
+/**
+ * Canonical `EditorScope { kind: 'note'; id }` encoding.
+ *
+ * Footnote id `1` and endnote id `1` coexist, so the kind is part of the string:
+ * `footnote:2` / `endnote:-1`. Do not invent a parallel scope union arm.
+ */
+declare function formatNoteScopeId(noteKind: NoteKind, noteId: number): string;
+/**
+ * Parse {@link formatNoteScopeId}. Returns `null` for malformed / out-of-range ids.
+ */
+declare function parseNoteScopeId(id: string): {
+    readonly noteKind: NoteKind;
+    readonly noteId: number;
+} | null;
 /** Whether a node is a `w:footnotes` part root. */
 declare function isFootnotesNode(node: OoxmlNode): node is OoxmlFootnotesNode;
 /** Whether a node is a `w:endnotes` part root. */
@@ -616,445 +987,97 @@ type NoteLifecycleOp = {
      */
     readonly revision?: RevisionAttributionInput;
 } | {
-    readonly op: 'deleteNote';
-    readonly noteKind: NoteKind;
-    readonly noteId: number;
-} | {
-    readonly op: 'convertNote';
-    readonly fromKind: NoteKind;
-    readonly noteId: number;
-} | {
-    /**
-     * Convert every normal note of `fromKind` in document order. One atomic package
-     * transaction / undo unit with the same validation as repeated `convertNote`.
-     */
-    readonly op: 'convertAllNotes';
-    readonly fromKind: NoteKind;
-} | {
-    readonly op: 'setNoteProperties';
-    readonly scope: 'document' | 'section';
-    readonly sectionIndex?: number;
-    readonly footnote?: {
-        readonly numFmt?: string;
-        readonly numRestart?: string;
-        readonly position?: string;
-        readonly numStart?: number;
-    };
-    readonly endnote?: {
-        readonly numFmt?: string;
-        readonly numRestart?: string;
-        readonly position?: string;
-        readonly numStart?: number;
-    };
-};
-/** Why a note lifecycle op was refused. */
-type NoteLifecycleRejection = 'invalidArgs' | 'invalid-property-value' | 'tree-invariant';
-/**
- * A new package, or a typed rejection.
- *
- * Application is PURE and all-or-nothing: there are no partial writes, so a refused op leaves the
- * caller's package untouched rather than half-migrated across four parts.
- */
-type NoteLifecycleResult = {
-    readonly ok: true;
-    readonly package: OoxmlPackage;
-    readonly impact: NoteLifecycleImpact;
-    readonly noteId?: number;
-    readonly noteKind?: NoteKind;
-    readonly createdPartName?: string;
-} | {
-    readonly ok: false;
-    readonly reason: NoteLifecycleRejection;
-    readonly detail?: string;
-};
-/** Whether an op is a note lifecycle op rather than a story-level one. */
-declare function isNoteLifecycleOp(op: {
-    readonly op: string;
-}): op is NoteLifecycleOp;
-/** Attribution and limits applied to one note lifecycle op. */
-interface NoteLifecycleOptions {
-    /**
-     * Shared part + visited-node budget for reference scans. When omitted a fresh default
-     * budget is used. Truncation rejects the op with the original package unchanged.
-     */
-    readonly scanBudget?: NoteReferenceScanBudget;
-}
-/**
- * Apply one note lifecycle op atomically. Rejected ops leave the input package untouched.
- */
-declare function applyNoteLifecycleOp(pkg: OoxmlPackage, op: NoteLifecycleOp, options?: NoteLifecycleOptions): NoteLifecycleResult;
-/**
- * How deleting text cascades into the notes it referenced.
- *
- * A note's body and the citation reaching it are one thing to a reader, so removing the reference
- * must remove the body too or the notes part keeps an entry nothing points at.
- */
-interface CascadeDeletedNoteReferencesOptions {
-    /**
-     * Independent full budgets per snapshot. When omitted each snapshot gets its own
-     * default budget — never share one counter across before/after walks.
-     */
-    readonly beforeBudget?: NoteReferenceScanBudget;
-    readonly afterBudget?: NoteReferenceScanBudget;
-}
-/**
- * Remove note bodies for references that disappeared between two package snapshots.
- * Used when `deleteText` or `deleteBlock` removes a `noteReference` atom so body+ref stay
- * one undo unit.
- *
- * Each snapshot gets an independent full visited/part budget. If either scan truncates
- * the cascade fails closed so a hostile package cannot skip body deletion silently —
- * without accidentally halving capacity by charging both walks to one counter.
- */
-declare function cascadeDeletedNoteReferences(before: OoxmlPackage, after: OoxmlPackage, options?: CascadeDeletedNoteReferencesOptions): OoxmlPackage | null;
-
-/**
- * The identity of one continuous user gesture, for history grouping.
- *
- * A live color picker, a font-size stepper or a spacing slider applies every intermediate
- * value so the document updates under the pointer, and each of those writes is a
- * transaction in its own right — it must render, and a collaborator must receive it. What
- * they are NOT is separate undo steps. The caller mints one token when the gesture starts
- * (`Symbol('color-drag')`) and passes it with every write until the gesture ends.
- *
- * A symbol rather than a string, so two unrelated callers cannot collide by naming their
- * gesture the same way, and so a token cannot outlive its gesture by accident through
- * serialization.
- */
-type HistoryGroup = symbol;
-type HistoryCaptureKind = 'started' | 'extended' | 'split';
-type HistoryCaptureReason = 'package-unit' | 'composition';
-declare function observeHistoryGroup<T>(group: HistoryGroup, report: (kind: HistoryCaptureKind, reason?: HistoryCaptureReason) => void, run: () => T): T;
-declare function reportHistoryGroup(group: HistoryGroup | undefined, kind: HistoryCaptureKind, reason?: HistoryCaptureReason): void;
-
-/** How one transaction behaves: its story scope, its attribution, and its selection marks. */
-interface TransactOptions {
-    readonly origin?: string;
-    /** Stable actor attribution for collaboration and audit correlation. */
-    readonly actorId?: string;
-    /** Stable constituent identity for collaboration duplicate correlation. */
-    readonly operationId?: string;
-    /**
-     * Whether this transaction enters the legacy snapshot undo stack.
-     *
-     * Collaboration commits set this to false because their actor-local undo authority is the
-     * CRDT undo manager. Omitted preserves the ordinary non-collaborative history behavior.
-     */
-    readonly recordsHistory?: boolean;
-    /**
-     * A COMMAND is one user intent that may need several ops (a toolbar click applying a
-     * property across a multi-run selection). It is still exactly one history entry, which is
-     * the same rule a plain transaction follows — the option exists to say so explicitly at
-     * the call site rather than leaving it implied.
-     */
-    readonly scope?: 'transaction' | 'command';
-    /**
-     * Floor on the published impact. Header/footer story edits use `global` so every page
-     * sharing the part invalidates rather than keeping stale furniture.
-     */
-    readonly minimumImpact?: ImpactClass;
-    /** Story identity stamped onto the published ModelChange (package-aware targeting). */
-    readonly story?: TreeStoryRef;
-    /**
-     * The gesture this transaction belongs to: consecutive transactions carrying the SAME
-     * token extend one history entry (package from before the first, selection after the
-     * latest). Another token, none, undo or redo closes the group. See {@link HistoryGroup}.
-     */
-    readonly historyGroup?: HistoryGroup;
-    /**
-     * How the transaction's ops address saved field results. `atomic` (the default) keeps
-     * every field one offset unit; `editable` addresses saved results as text. See
-     * `field-result-mode.ts`.
-     */
-    readonly fieldResults?: FieldResultsMode;
-}
-/** How a store is constructed: its limits, its history depth, and its identity source. */
-interface TreeDocumentStoreOptions {
-    /** Bound on retained history entries. Oldest entries drop first. */
-    readonly historyLimit?: number;
-    /**
-     * The document's `settings.xml`, for a store built from a PART rather than a package.
-     *
-     * Forms protection lives one part up from the op, and a store built from a part gets a
-     * synthetic one-part package that cannot see it — so `w:documentProtection w:edit="forms"`
-     * was enforced in the body and nowhere else, and a header, a footer or a note accepted every
-     * write a protected document is supposed to refuse. Read through a getter, not captured: a
-     * document can gain or lose protection while its stories stay open.
-     */
-    readonly settingsPart?: () => OoxmlPart | null | undefined;
-    /**
-     * Opt-in relaxation of `w:lock` for run-property writes. See {@link ContentLockPolicy};
-     * absent, `contentLocked` and `sdtContentLocked` refuse formatting like any other write.
-     */
-    readonly contentLockPolicy?: ContentLockPolicy;
-}
-
-/** A selection the caller wants restored when an entry is undone or redone. */
-/** A selection captured with a transaction, so undo restores where the caret was. */
-interface SelectionMark {
-    readonly paragraphId: string;
-    readonly start: number;
-    readonly end: number;
-}
-/**
- * Which editable story a ModelChange came from.
- *
- * Mirrors `EditorScope` for body and header/footer — `{ kind: 'headerFooter'; rId }` —
- * so package-aware mutation and the public scope contract stay one vocabulary. Body
- * commits omit `rId`; header/footer commits carry the relationship id that addressed
- * the part. Notes parts use `{ kind: 'notesPart'; noteKind }` (one store per part).
- */
-/** Which story a transaction targets: the body, a header/footer part, or a notes part. */
-type TreeStoryRef = {
-    readonly kind: 'body';
-    readonly partName: string;
-} | {
-    readonly kind: 'headerFooter';
-    readonly partName: string;
-    readonly rId: string;
-} | {
-    readonly kind: 'notesPart';
-    readonly partName: string;
-    readonly noteKind: 'footnote' | 'endnote';
-};
-/**
- * What one committed transaction changed: the revision, the ids touched, and the impact class.
- *
- * The ids are what let layout and paint re-do only the affected blocks instead of the document.
- */
-interface TreeModelChange {
-    readonly change: 'model-change';
-    readonly fromRevision: number;
-    readonly toRevision: number;
-    readonly commitId: string;
-    readonly origin: string;
-    /** Stable collaboration actor attribution, when the caller supplied it. */
-    readonly actorId?: string;
-    /** Stable collaboration operation identity, when the caller supplied it. */
-    readonly operationId?: string;
-    readonly dirty: readonly string[];
-    readonly created: readonly string[];
-    readonly deleted: readonly string[];
-    readonly splitJoin: readonly ({
-        readonly split: {
-            readonly from: string;
-            readonly tail: string;
-        };
-    } | {
-        readonly join: {
-            readonly kept: string;
-            readonly removed: string;
-        };
-    })[];
-    readonly dependencyKeys: readonly string[];
-    /** The widest impact among the transaction's ops — what layout must scope to. */
-    readonly impact: ImpactClass;
-    /**
-     * Story that published this change. Absent on body-only store publishes that predate
-     * package-aware targeting; `TreePackageStore` always sets it.
-     */
-    readonly story?: TreeStoryRef;
+    readonly op: 'deleteNote';
+    readonly noteKind: NoteKind;
+    readonly noteId: number;
+} | {
+    readonly op: 'convertNote';
+    readonly fromKind: NoteKind;
+    readonly noteId: number;
+} | {
     /**
-     * Committed collapsed caret for this transaction, when one exists.
-     * Matches history `selectionAfter` when that mark is collapsed; absent for explicit
-     * null, non-collapsed explicit selection, or when no caret was committed.
+     * Convert every normal note of `fromKind` in document order. One atomic package
+     * transaction / undo unit with the same validation as repeated `convertNote`.
      */
-    readonly caret?: SelectionMark;
-}
-/** Whether a transaction committed, or the typed reason it was refused. */
-type TransactResult = {
+    readonly op: 'convertAllNotes';
+    readonly fromKind: NoteKind;
+} | {
+    readonly op: 'setNoteProperties';
+    readonly scope: 'document' | 'section';
+    readonly sectionIndex?: number;
+    readonly footnote?: {
+        readonly numFmt?: string;
+        readonly numRestart?: string;
+        readonly position?: string;
+        readonly numStart?: number;
+    };
+    readonly endnote?: {
+        readonly numFmt?: string;
+        readonly numRestart?: string;
+        readonly position?: string;
+        readonly numStart?: number;
+    };
+};
+/** Why a note lifecycle op was refused. */
+type NoteLifecycleRejection = 'invalidArgs' | 'invalid-property-value' | 'tree-invariant';
+/**
+ * A new package, or a typed rejection.
+ *
+ * Application is PURE and all-or-nothing: there are no partial writes, so a refused op leaves the
+ * caller's package untouched rather than half-migrated across four parts.
+ */
+type NoteLifecycleResult = {
     readonly ok: true;
-    readonly change: TreeModelChange | null;
+    readonly package: OoxmlPackage;
+    readonly impact: NoteLifecycleImpact;
+    readonly noteId?: number;
+    readonly noteKind?: NoteKind;
+    readonly createdPartName?: string;
 } | {
     readonly ok: false;
-    readonly reason: TreeOpRejection;
+    readonly reason: NoteLifecycleRejection;
     readonly detail?: string;
 };
-/** What a transaction body is handed: the working tree, and the means to stage ops against it. */
-interface TransactionContext {
-    /** Stage one op against the STORY part. Returns false once the transaction has failed. */
-    apply(op: TreeDocOp): boolean;
-    /**
-     * Stage one op against a named part.
-     *
-     * A comment body lives in `comments.xml` and is edited by the same ops that edit the story,
-     * so this is `apply` with the target named rather than a second vocabulary.
-     */
-    applyTo(partName: string, op: TreeDocOp): boolean;
-    /**
-     * Stage a whole-package edit: a new part, a relationship, a content-type override.
-     *
-     * The edit is a pure function of the working package, so a rejected transaction discards it
-     * with everything else. Returning the SAME package is a no-op, not a failure — a primitive
-     * that finds nothing to do says so that way.
-     */
-    applyPackage(edit: (pkg: OoxmlPackage) => OoxmlPackage): boolean;
-    /** The selection to restore when this entry is undone. */
-    selectionBefore(selection: SelectionMark | null): void;
-    /** The selection to restore when this entry is redone. */
-    selectionAfter(selection: SelectionMark | null): void;
-}
-interface HistoryEntry {
-    /**
-     * The whole package as it was, not just the story part.
-     *
-     * Affordable for the same reason a part snapshot was: parts are immutable and deep-frozen, so
-     * a package snapshot is a Map of references and every part the transaction did not touch is
-     * object-identical to the one before it. Undo stays a pointer swap, and it now reverses every
-     * part one intent wrote rather than only the story.
-     */
-    readonly pkg: OoxmlPackage;
-    readonly revision: number;
-    readonly selectionBefore: SelectionMark | null;
-    readonly selectionAfter: SelectionMark | null;
+/** Whether an op is a note lifecycle op rather than a story-level one. */
+declare function isNoteLifecycleOp(op: {
+    readonly op: string;
+}): op is NoteLifecycleOp;
+/** Attribution and limits applied to one note lifecycle op. */
+interface NoteLifecycleOptions {
     /**
-     * The gesture this entry is still collecting, while it is the newest entry and nothing
-     * has closed it. Only ever set on the top of the undo stack: {@link closeHistoryGroup}
-     * strips it, and undo and redo never copy it onto the entries they push.
+     * Shared part + visited-node budget for reference scans. When omitted a fresh default
+     * budget is used. Truncation rejects the op with the original package unchanged.
      */
-    readonly group?: HistoryGroup;
+    readonly scanBudget?: NoteReferenceScanBudget;
 }
 /**
- * Opaque document+history checkpoint for package-coordinator rollback.
- * Used when a story mutation may promote to a package undo unit (note-ref cascade).
+ * Apply one note lifecycle op atomically. Rejected ops leave the input package untouched.
  */
-/** A restorable point in history — one entry of the intent-scoped undo stack. */
-interface TreeDocumentCheckpoint {
-    /**
-     * The whole package, not one part. The store owns the package so a transaction spanning
-     * several parts is one publication — a checkpoint of only the story part could not roll
-     * back the comment or numbering part the same transaction wrote.
-     */
-    readonly pkg: OoxmlPackage;
-    readonly revision: number;
-    readonly undoStack: readonly HistoryEntry[];
-    readonly redoStack: readonly HistoryEntry[];
-    readonly composition: {
-        readonly entry: HistoryEntry;
-        readonly committed: boolean;
-    } | null;
-}
+declare function applyNoteLifecycleOp(pkg: OoxmlPackage, op: NoteLifecycleOp, options?: NoteLifecycleOptions): NoteLifecycleResult;
 /**
- * The document store: one transaction is one atomic publication and one history entry.
+ * How deleting text cascades into the notes it referenced.
  *
- * `apply` STAGES ops against a working part and nothing is visible until `transact` returns, so a
- * batch rejected halfway leaves the revision, the tree, the indexes and every subscriber exactly
- * as they were. That all-or-nothing property is what lets a caller compose ops without having to
- * reason about partial application.
+ * A note's body and the citation reaching it are one thing to a reader, so removing the reference
+ * must remove the body too or the notes part keeps an entry nothing points at.
  */
-declare class TreeDocumentStore {
-    private current;
-    /** The part `apply` targets and `part` returns: the story this store is editing. */
-    private readonly storyPartName;
-    private rev;
-    private commitCounter;
-    private readonly undoStack;
-    private readonly redoStack;
-    private readonly subscribers;
-    private readonly historyLimit;
-    /** See {@link TreeDocumentStoreOptions.settingsPart}. */
-    private readonly settingsPartOverride;
-    /** See {@link TreeDocumentStoreOptions.contentLockPolicy}. */
-    private readonly contentLockPolicy;
-    /** Package-aware story tag applied to publishes (including undo/redo). */
-    private storyRef;
-    /** Open composition, if any. While set, transactions extend one entry (task 5.5). */
-    private composition;
-    /**
-     * Open a store over a package, editing the named story part.
-     *
-     * A bare part is accepted and wrapped in a single-part package, so callers that never open a
-     * real package — tests, headless tooling — are unaffected by the widening.
-     */
-    constructor(source: OoxmlPart | OoxmlPackage, storyPartNameOrOptions?: string | TreeDocumentStoreOptions, maybeOptions?: TreeDocumentStoreOptions);
-    /**
-     * Stamp story identity onto subsequent publishes for this store (including undo/redo).
-     * Used by the package coordinator so history navigation keeps the same scope tag.
-     */
-    setStoryRef(story: TreeStoryRef | null): void;
-    /** The story part being edited. Unchanged for every caller that predates the widening. */
-    get part(): OoxmlPart;
-    /** Every part, including the ones a multi-part transaction wrote. */
-    get package(): OoxmlPackage;
-    get revision(): number;
-    get canUndo(): boolean;
-    get canRedo(): boolean;
-    /** Retained entries — the unit `undo()` reverses, so tests can assert grouping. */
-    get historyDepth(): number;
-    get compositionActive(): boolean;
-    /**
-     * Replace the package OUTSIDE the transaction and history lanes.
-     *
-     * For package writes that are not a user intent and publish no revision: grafting
-     * `numbering.xml` into a document that never had one, which the caller performs as a
-     * precondition of the list op that follows. Those edits were previously kept in a package
-     * variable beside the store, which meant two owners of one value and, predictably, two
-     * values — a graft written to one and a save read from the other.
-     *
-     * Deliberately narrow and deliberately awkward to reach for: anything a user did belongs in
-     * `transact`, where it gets a revision, an undo entry and the invariant checks.
-     */
-    graftPackage(edit: (pkg: OoxmlPackage) => OoxmlPackage): void;
-    /**
-     * Replace the current part without recording history, but advance the revision so
-     * revision-keyed projections cannot survive a package snapshot install.
-     */
-    replacePart(part: OoxmlPart): void;
-    /**
-     * Snapshot part, revision, and undo/redo stacks so the package coordinator can roll
-     * back a story transaction that fails after commit (e.g. note-reference cascade) or
-     * discard a local history entry when promoting to a package undo unit.
-     */
-    checkpoint(): TreeDocumentCheckpoint;
-    /** Full restore — part, revision, history stacks, and composition. */
-    restoreCheckpoint(checkpoint: TreeDocumentCheckpoint): void;
-    /**
-     * Restore undo/redo stacks only, keeping the current part and revision.
-     * Used when a story mutation is promoted to a package history pointer so the local
-     * orphan entry does not steal a later undo.
-     */
-    restoreHistoryStacks(checkpoint: TreeDocumentCheckpoint): void;
-    subscribe(listener: (change: TreeModelChange) => void): () => void;
-    /**
-     * Run one atomic transaction.
-     *
-     * Ops are staged against a working copy. On the first rejection the whole transaction is
-     * abandoned: no revision, no history entry, no notification. On success exactly one
-     * revision is published and exactly one history entry is recorded — unless a composition
-     * is open, in which case the entry already exists and this transaction joins it.
-     */
-    transact(build: (ctx: TransactionContext) => void, options?: TransactOptions): TransactResult;
-    private commitTransaction;
-    /**
-     * Open one history entry for an IME composition.
-     *
-     * Everything committed until `endComposition` collapses into this single entry, which is
-     * what makes a composed word one undo step rather than one per intermediate transaction.
-     */
-    beginComposition(selectionBefore?: SelectionMark | null): void;
-    /** Close the composition, recording its entry only if anything actually committed. */
-    endComposition(): void;
-    /**
-     * Cancel an open composition without recording an entry, leaving whatever it committed
-     * in place. An IME cancel is not an undo request; the caller decides what to revert.
-     */
-    cancelComposition(): void;
+interface CascadeDeletedNoteReferencesOptions {
     /**
-     * Close the open history group, if any: the next transaction records its own entry.
-     * The store does this itself for another token, none, undo and redo; the package
-     * coordinator does it for history moving ABOVE the store (a package unit, another
-     * story's pointer), which the store cannot see.
+     * Independent full budgets per snapshot. When omitted each snapshot gets its own
+     * default budget — never share one counter across before/after walks.
      */
-    closeHistoryGroup(): void;
-    undo(): TreeModelChange | null;
-    redo(): TreeModelChange | null;
-    /** The selection to restore for the entry `undo()` would reverse next. */
-    selectionForUndo(): SelectionMark | null;
-    /** The selection to restore for the entry `redo()` would reapply next. */
-    selectionForRedo(): SelectionMark | null;
-    private pushUndo;
-    private publish;
+    readonly beforeBudget?: NoteReferenceScanBudget;
+    readonly afterBudget?: NoteReferenceScanBudget;
 }
+/**
+ * Remove note bodies for references that disappeared between two package snapshots.
+ * Used when `deleteText` or `deleteBlock` removes a `noteReference` atom so body+ref stay
+ * one undo unit.
+ *
+ * Each snapshot gets an independent full visited/part budget. If either scan truncates
+ * the cascade fails closed so a hostile package cannot skip body deletion silently —
+ * without accidentally halving capacity by charging both walks to one counter.
+ */
+declare function cascadeDeletedNoteReferences(before: OoxmlPackage, after: OoxmlPackage, options?: CascadeDeletedNoteReferencesOptions): OoxmlPackage | null;
 
 /** Decoded fragment payloads above this cap are refused before any package work. */
 declare const MAX_FRAGMENT_DECODED_BYTES: number;
@@ -1170,6 +1193,7 @@ declare class TreePackageStore {
     private readonly rIdToPartName;
     private readonly undoOrder;
     private readonly redoOrder;
+    private readonly historyGroups;
     private readonly subscribers;
     private readonly historyLimit;
     private readonly contentLockPolicy;
@@ -1254,6 +1278,8 @@ declare class TreePackageStore {
      */
     applyLifecycleOp(op: HeaderFooterLifecycleOp | NoteLifecycleOp | TreeDocOp, options?: {
         readonly actorId?: string;
+        /** @internal */
+        readonly historyGroup?: HistoryGroup;
     }): PackageTransactResult;
     private commitLifecycleOp;
     undo(): TreeModelChange | null;
@@ -1324,6 +1350,8 @@ declare class TreePackageStore {
      * started from to this instead, the same promotion the note cascade does.
      */
     adoptPackageUnit(before: OoxmlPackage): void;
+    /** {@link adoptPackageUnit} as a frame of a history group. @internal */
+    adoptGroupedPackageUnit(before: OoxmlPackage, historyGroup: HistoryGroup | undefined): void;
     /** Install a full package snapshot (public seam for post-fetch cleanup). */
     installPackageSnapshot(snapshot: OoxmlPackage): void;
     /**
@@ -1344,6 +1372,8 @@ declare class TreePackageStore {
     private openHeaderFooterStore;
     private storyRefForPart;
     private syncPackageFromStore;
+    /** Close every open history group: the story stores' and the coordinator's. */
+    private closeHistoryGroups;
     private pushUndoPointer;
     /** Keep history-reachable stories and prune unreachable shell hyperlink owners. */
     private evictUnreachableStories;