@docx-editor.dev/core 2.29.0 → 2.31.0

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

@@ -1,16 +1,4 @@
-import { S as SupportedImageMime, c as ImageDecodePort } from './image-resources-tXLQShoC.js';
-import { Q as OoxmlPackage, ax as RevisionAttributionInput, ay as DrawingTreeDocOp, O as OoxmlPart, N as OoxmlNode, ak as OoxmlElement, az as OoxmlParagraphNode, aA as OoxmlNoteNode, aB as OoxmlContinuationSeparatorNode, aC as OoxmlEndnotesNode, aD as OoxmlFootnotesNode, aE as OoxmlNoteRefNode, aF as OoxmlNoteReferenceNode, aG as OoxmlSeparatorNode, aH as ImpactClass, ag as TreeDocOp, av as TreeOpRejection } from './types-barrel-DuC5QBNC.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';
+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 = {
@@ -74,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. */
@@ -233,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';
@@ -258,338 +207,198 @@ 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.
- */
-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. */
-declare function isEndnotesNode(node: OoxmlNode): node is OoxmlEndnotesNode;
-/** Whether a node is a `w:footnote` or `w:endnote` body. */
-declare function isNoteNode(node: OoxmlNode): node is OoxmlNoteNode;
-/** Whether a node is a body-side `w:footnoteReference` / `w:endnoteReference`. */
-declare function isNoteReferenceNode(node: OoxmlNode): node is OoxmlNoteReferenceNode;
-/** Whether a node is the `w:footnoteRef` / `w:endnoteRef` mark inside a note's own body. */
-declare function isNoteRefNode(node: OoxmlNode): node is OoxmlNoteRefNode;
-/** Whether a node is the `w:separator` rule drawn above the note area. */
-declare function isSeparatorNode(node: OoxmlNode): node is OoxmlSeparatorNode;
-/** Whether a node is the `w:continuationSeparator` rule used on continuation pages. */
-declare function isContinuationSeparatorNode(node: OoxmlNode): node is OoxmlContinuationSeparatorNode;
-/** Typed or generic `w:footnote` / `w:endnote`. */
-declare function noteKindOf(node: OoxmlNode): NoteKind | null;
-/** Authored `@w:id` on a note or noteReference when parseable. */
-declare function noteIdOf(node: OoxmlNode): number | null;
-/** Authored `@w:type` (`ST_FtnEdn`) when present and schema-legal; else `undefined`. */
-declare function noteTypeOf(node: OoxmlNode): NoteType | undefined;
-/** Whether a note is a normal (body) note — absent type and explicit `normal` both count. */
-declare function isNormalNote(node: OoxmlNode): boolean;
-/** Typed or generic footnote/endnote reference kind. */
-declare function noteReferenceKindOf(node: OoxmlNode): NoteKind | null;
-/** Typed or generic `w:footnoteRef` / `w:endnoteRef`. */
-declare function noteRefKindOf(node: OoxmlNode): NoteKind | null;
-/**
- * Read `@w:customMarkFollows` on a note reference.
- * Returns `undefined` when absent; otherwise the OOXML on/off interpretation.
- */
-declare function customMarkFollows(node: OoxmlNode): boolean | undefined;
-/** Model text contributed by one atomic note unit. */
-declare function noteAtomText(): typeof NOTE_ATOM_CHAR;
-/**
- * True when a run-inner node is a typed note atom that contributes one UTF-16 unit.
- * Demoted/malformed known locals stay generic and contribute nothing.
+ * 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 isNoteAtomNode(node: OoxmlNode): boolean;
+interface ContentLockPolicy {
+    /** Let run formatting pass a content lock; text and removal stay refused. Default `false`. */
+    readonly allowFormattingInLockedContent?: boolean;
+}
 /**
- * One atomic note span inside a paragraph for caret / delete / selection.
+ * How an edit primitive validates its result.
  *
- * Each typed note atom is a single-node span (`removeNodeIds` = that node).
+ * 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 AtomicNoteSpan {
-    readonly kind: 'noteReference' | 'noteRef' | 'separator' | 'continuationSeparator';
-    readonly node: OoxmlNode;
-    readonly runId: string;
-    readonly removeNodeIds: readonly string[];
+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;
 }
 /**
- * Collect typed note atoms in document order (one segment each).
+ * What one transaction knows about the revision ids its tracked text ops write.
  *
- * Walks the same paragraph-inline surface as `segmentsOf` / `walkParagraphInline`:
- * hyperlinks and content controls flatten; only direct run children contribute atoms.
- * A demoted run-inner SDT husk stays opaque — no phantom addressable hit.
+ * 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.
  */
-declare function atomicNoteSpansOf(paragraph: OoxmlParagraphNode): readonly AtomicNoteSpan[];
-/** Cap on notes scanned when allocating / indexing a notes part. */
-declare const MAX_NOTES_PER_PART = 10000;
+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>;
 /**
- * Allocate the next positive signed 32-bit note id for a notes-part root.
+ * Mint ids for nodes an edit introduces.
  *
- * Solo: `max(existing)+1`, the dense sequence Word writes. `null` on exhaustion, so the
- * caller refuses rather than wrapping onto an id a note already holds.
+ * 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.
  *
- * With a collaboration actor bound — explicit argument, or the open store transaction — the
- * id is the next unused value in that actor's stripe. Two peers each adding their first
- * footnote from one snapshot otherwise both mint `w:id="1"`: the merge keeps both bodies
- * under one id, both `w:footnoteReference` marks resolve to the first, and one author's note
- * becomes unreachable.
+ * Allocators share reservations across edited roots and restored roots. Preview edits,
+ * detached nodes, and undo branches must not reuse an identity that collaboration retains.
  *
- * The reserved ids stay reserved either way. `0` (continuation separator) is seeded as used,
- * so a residue of 0 advances one class instead of taking Word's furniture, and a stripe walk
- * only ever climbs from a non-negative residue, so `-1` (separator) is unreachable.
- */
-declare function allocateNoteId(notesRoot: OoxmlNode, actorId?: string): number | null;
-/** Collect note bodies from a footnotes/endnotes root, bounded. */
-declare function notesOf(root: OoxmlNode): readonly OoxmlNoteNode[];
-/** Find a typed note by id inside a notes-part root. */
-declare function findNoteById(root: OoxmlNode, noteId: number): OoxmlNoteNode | undefined;
-
-/** Cap on nodes visited while scanning for note references across stories. */
-declare const MAX_NOTE_REFERENCE_SCAN = 20000;
-/**
- * Cap on XML parts walked in one package-wide note-reference scan (N/N+1 gate).
- * Soft targets are not allowed: exceeding this marks the shared budget truncated.
+ * 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 const MAX_NOTE_REFERENCE_PARTS = 256;
+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;
 /**
- * A load-time note problem worth reporting.
+ * Apply several primitives as ONE atomic step.
  *
- * `dangling-note-reference` is a citation pointing at no note; `note-reference-scan-truncated`
- * says the scan hit its budget, so absence of further diagnostics is not proof of correctness.
- */
-type NoteDiagnosticCode = 'dangling-note-reference' | 'note-reference-scan-truncated';
-/**
- * Load-time note diagnostics. Array API preserved; truncation is signaled as a typed
- * entry rather than by throwing or rejecting the package.
+ * 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.
  */
-type NoteDiagnostic = {
-    readonly code: 'dangling-note-reference';
-    readonly noteKind: NoteKind;
-    readonly noteId: number;
-    /** Paragraph / container node id when known. */
-    readonly sourceNodeId?: string;
-} | {
-    /** Hard visited/part budget or soft hit cap stopped the scan before full coverage. */
-    readonly code: 'note-reference-scan-truncated';
-};
-/** One note reference found in a story, with where it sits. */
-interface NoteReferenceHit {
-    readonly noteKind: NoteKind;
-    readonly noteId: number;
-    readonly nodeId: string;
+declare function applyEdits(part: OoxmlPart, edits: readonly ((current: OoxmlPart) => OoxmlEditResult)[], options?: EditOptions): OoxmlEditResult;
+
+interface InsertImageInput {
     readonly paragraphId: string;
-    /** Canonical UTF-16 atom offset within {@link paragraphId} (U+FFFC model). */
-    readonly atomOffset: number;
-    readonly customMarkFollows: boolean;
-    /** Canonical part name that owns this reference. */
-    readonly partName: 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;
 }
-/** Mutable visited-node + part budget shared across parts / package snapshots. */
-interface NoteReferenceScanBudget {
-    visited: number;
-    readonly maxVisited: number;
-    parts: number;
-    readonly maxParts: number;
-    /** Set when a walk stops before finishing because a cap was hit. */
-    truncated: boolean;
-}
-/** A bounded budget for scanning note references, so a crafted document cannot stall a load. */
-declare function createNoteReferenceScanBudget(maxVisited?: number, maxParts?: number): NoteReferenceScanBudget;
-/**
- * Resolve the footnotes or endnotes part via safe Internal document relationships.
- *
- * Unusable matching relationships (External, unsafe target, missing part, wrong root)
- * are skipped — never fetched, never accepted — so a decoy first match cannot hide a
- * later usable Internal notes part (same continue-past-bad pattern as settingsPartOf).
- */
-declare function resolveNotesPart(pkg: OoxmlPackage, noteKind: NoteKind): OoxmlPart | null;
-/** Walk a part without applying a layout projection. */
-declare function collectNoteReferences(part: OoxmlPart, options?: {
-    readonly maxHits?: number;
-    readonly budget?: NoteReferenceScanBudget;
-}): readonly NoteReferenceHit[];
-/** Collect references across every XML part under one shared part + visited-node budget. */
-declare function collectPackageNoteReferences(pkg: OoxmlPackage, options?: {
-    readonly budget?: NoteReferenceScanBudget;
-    /** Soft hit cap for diagnostics. Omit / Infinity for mutation scans. */
-    readonly maxHits?: number;
-}): readonly NoteReferenceHit[];
-/**
- * Load diagnostics for dangling note references. Fail-open: never throws or mutates;
- * returns diagnostics for callers to surface. Does not invent missing note bodies.
- *
- * When the hard visited/part budget truncates or the soft hit cap binds, appends a single
- * `note-reference-scan-truncated` entry so incomplete coverage is visible without breaking
- * consumers that filter on `dangling-note-reference`.
- */
-declare function diagnoseNoteReferences(pkg: OoxmlPackage): readonly NoteDiagnostic[];
-/** Whether a notes-part root contains a note with the given id (any type). */
-declare function notesPartHasId(part: OoxmlPart, noteId: number): boolean;
-/** List normal (body) note ids in document order, bounded. */
-declare function normalNoteIds(part: OoxmlPart): readonly number[];
-
-/** How far a note lifecycle op reaches — which parts a caller must expect to have changed. */
-type NoteLifecycleImpact = 'flow-structural' | 'global';
-/**
- * A note lifecycle mutation: insert, delete, convert, or set properties.
- *
- * Package-level rather than story-level, because every one of these touches the main document,
- * the notes part, the document relationships AND `[Content_Types].xml` together.
- */
-type NoteLifecycleOp = {
-    readonly op: 'insertNote';
-    readonly noteKind: NoteKind;
-    readonly paragraphId: string;
-    readonly offset: number;
-    /**
-     * Write the citing reference as a TRACKED insertion: the reference run goes inside a
-     * `w:ins` carrying this attribution. The note body stays plain — rejecting the
-     * reference removes it, and the orphaned body is swept by the same cascade an
-     * untracked reference deletion triggers.
-     */
-    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;
+interface ReplaceImageOptions {
+    readonly expectedPackageRevision: number;
+    readonly commitGuard?: () => boolean;
+    /** Collaboration actor for the replacement's minted ids. See {@link InsertImageInput.actorId}. */
+    readonly actorId?: string;
 }
-/**
- * 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;
+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;
 }
-/**
- * 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 {
@@ -646,6 +455,11 @@ interface TreeDocumentStoreOptions {
      * 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. */
@@ -746,6 +560,10 @@ interface TransactionContext {
      * 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. */
@@ -809,10 +627,13 @@ declare class TreeDocumentStore {
     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). */
@@ -838,6 +659,12 @@ declare class TreeDocumentStore {
     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.
@@ -909,73 +736,412 @@ declare class TreeDocumentStore {
     selectionForUndo(): SelectionMark | null;
     /** The selection to restore for the entry `redo()` would reapply next. */
     selectionForRedo(): SelectionMark | null;
-    private pushUndo;
-    private publish;
-}
-
-/** Decoded fragment payloads above this cap are refused before any package work. */
-declare const MAX_FRAGMENT_DECODED_BYTES: number;
-interface FragmentPasteInput {
-    readonly paragraphId: string;
-    readonly offset: number;
-    /** The fragment package zip (from the clipboard codec or the HTML projection). */
-    readonly fragmentBytes: Uint8Array;
-    readonly lastMarkCovered: boolean;
-    /** Ops that clear the current selection first (the surface's deleteSelectionPlan). */
-    readonly priorOps?: readonly TreeDocOp[];
     /**
-     * Collaboration actor for the ids this paste mints.
-     *
-     * A paste freshens three package-wide namespaces — bookmark `@w:id`, revision `@w:id` and
-     * `wp:docPr/@id` — and the merge reads the actor off the open transaction. Without one, two
-     * replicas pasting the same fragment from one snapshot mint the same numbers, and only the
-     * merged document shows it. Omitted (solo) keeps Word's dense sequences.
+     * 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
      */
-    readonly actorId?: string;
-}
-type FragmentPasteResult = (Extract<PackageTransactResult, {
-    ok: true;
-}> & {
-    readonly blockCount: number;
-}) | Extract<PackageTransactResult, {
-    ok: false;
-}>;
-/**
- * Read the fragment through the bounded file-open trust boundary, merge its resources,
- * and land its blocks — all inside one transaction. Any refusal leaves the document
- * exactly as it was; the caller (the paste router) degrades to the next flavour.
- */
-declare function applyFragmentPaste(store: TreePackageStore, scope: StoryScope, input: FragmentPasteInput): FragmentPasteResult;
-
-/** Attribution stamped on one remote canonical publication. */
-interface RemotePackageAttribution {
-    readonly origin: string;
-    readonly actorId?: string;
-    readonly operationId?: string;
+    discardNewestUndoEntry(): Pick<HistoryEntry, 'selectionBefore' | 'selectionAfter'> | null;
+    private pushUndo;
+    private publish;
 }
 
-type NoteCascadeFn = (before: OoxmlPackage, after: OoxmlPackage) => OoxmlPackage | null;
 /**
- * Editable story target.
+ * The identity of one continuous user gesture, for history grouping.
  *
- * Body and headerFooter mirror `EditorScope`. Notes use one lazy store per notes part
- * (`notesPart`) — not one store per note — resolved through safe document relationships.
- */
-type StoryScope = {
-    readonly kind: 'body';
-} | {
-    readonly kind: 'headerFooter';
-    readonly rId: string;
-} | {
-    readonly kind: 'notesPart';
-    readonly noteKind: NoteKind;
-};
-/**
- * Why a story scope could not be resolved to a part.
+ * 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.
  *
- * Several of these are FILE-hostile shapes rather than caller mistakes:
- * `external-relationship` and `bad-relationship-target` are how a crafted document tries to
- * point a story at something outside the package, and both are refused rather than followed.
+ * 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. */
+declare function isEndnotesNode(node: OoxmlNode): node is OoxmlEndnotesNode;
+/** Whether a node is a `w:footnote` or `w:endnote` body. */
+declare function isNoteNode(node: OoxmlNode): node is OoxmlNoteNode;
+/** Whether a node is a body-side `w:footnoteReference` / `w:endnoteReference`. */
+declare function isNoteReferenceNode(node: OoxmlNode): node is OoxmlNoteReferenceNode;
+/** Whether a node is the `w:footnoteRef` / `w:endnoteRef` mark inside a note's own body. */
+declare function isNoteRefNode(node: OoxmlNode): node is OoxmlNoteRefNode;
+/** Whether a node is the `w:separator` rule drawn above the note area. */
+declare function isSeparatorNode(node: OoxmlNode): node is OoxmlSeparatorNode;
+/** Whether a node is the `w:continuationSeparator` rule used on continuation pages. */
+declare function isContinuationSeparatorNode(node: OoxmlNode): node is OoxmlContinuationSeparatorNode;
+/** Typed or generic `w:footnote` / `w:endnote`. */
+declare function noteKindOf(node: OoxmlNode): NoteKind | null;
+/** Authored `@w:id` on a note or noteReference when parseable. */
+declare function noteIdOf(node: OoxmlNode): number | null;
+/** Authored `@w:type` (`ST_FtnEdn`) when present and schema-legal; else `undefined`. */
+declare function noteTypeOf(node: OoxmlNode): NoteType | undefined;
+/** Whether a note is a normal (body) note — absent type and explicit `normal` both count. */
+declare function isNormalNote(node: OoxmlNode): boolean;
+/** Typed or generic footnote/endnote reference kind. */
+declare function noteReferenceKindOf(node: OoxmlNode): NoteKind | null;
+/** Typed or generic `w:footnoteRef` / `w:endnoteRef`. */
+declare function noteRefKindOf(node: OoxmlNode): NoteKind | null;
+/**
+ * Read `@w:customMarkFollows` on a note reference.
+ * Returns `undefined` when absent; otherwise the OOXML on/off interpretation.
+ */
+declare function customMarkFollows(node: OoxmlNode): boolean | undefined;
+/** Model text contributed by one atomic note unit. */
+declare function noteAtomText(): typeof NOTE_ATOM_CHAR;
+/**
+ * True when a run-inner node is a typed note atom that contributes one UTF-16 unit.
+ * Demoted/malformed known locals stay generic and contribute nothing.
+ */
+declare function isNoteAtomNode(node: OoxmlNode): boolean;
+/**
+ * One atomic note span inside a paragraph for caret / delete / selection.
+ *
+ * Each typed note atom is a single-node span (`removeNodeIds` = that node).
+ */
+interface AtomicNoteSpan {
+    readonly kind: 'noteReference' | 'noteRef' | 'separator' | 'continuationSeparator';
+    readonly node: OoxmlNode;
+    readonly runId: string;
+    readonly removeNodeIds: readonly string[];
+}
+/**
+ * Collect typed note atoms in document order (one segment each).
+ *
+ * Walks the same paragraph-inline surface as `segmentsOf` / `walkParagraphInline`:
+ * hyperlinks and content controls flatten; only direct run children contribute atoms.
+ * A demoted run-inner SDT husk stays opaque — no phantom addressable hit.
+ */
+declare function atomicNoteSpansOf(paragraph: OoxmlParagraphNode): readonly AtomicNoteSpan[];
+/** Cap on notes scanned when allocating / indexing a notes part. */
+declare const MAX_NOTES_PER_PART = 10000;
+/**
+ * Allocate the next positive signed 32-bit note id for a notes-part root.
+ *
+ * Solo: `max(existing)+1`, the dense sequence Word writes. `null` on exhaustion, so the
+ * caller refuses rather than wrapping onto an id a note already holds.
+ *
+ * With a collaboration actor bound — explicit argument, or the open store transaction — the
+ * id is the next unused value in that actor's stripe. Two peers each adding their first
+ * footnote from one snapshot otherwise both mint `w:id="1"`: the merge keeps both bodies
+ * under one id, both `w:footnoteReference` marks resolve to the first, and one author's note
+ * becomes unreachable.
+ *
+ * The reserved ids stay reserved either way. `0` (continuation separator) is seeded as used,
+ * so a residue of 0 advances one class instead of taking Word's furniture, and a stripe walk
+ * only ever climbs from a non-negative residue, so `-1` (separator) is unreachable.
+ */
+declare function allocateNoteId(notesRoot: OoxmlNode, actorId?: string): number | null;
+/** Collect note bodies from a footnotes/endnotes root, bounded. */
+declare function notesOf(root: OoxmlNode): readonly OoxmlNoteNode[];
+/** Find a typed note by id inside a notes-part root. */
+declare function findNoteById(root: OoxmlNode, noteId: number): OoxmlNoteNode | undefined;
+
+/** Cap on nodes visited while scanning for note references across stories. */
+declare const MAX_NOTE_REFERENCE_SCAN = 20000;
+/**
+ * Cap on XML parts walked in one package-wide note-reference scan (N/N+1 gate).
+ * Soft targets are not allowed: exceeding this marks the shared budget truncated.
+ */
+declare const MAX_NOTE_REFERENCE_PARTS = 256;
+/**
+ * A load-time note problem worth reporting.
+ *
+ * `dangling-note-reference` is a citation pointing at no note; `note-reference-scan-truncated`
+ * says the scan hit its budget, so absence of further diagnostics is not proof of correctness.
+ */
+type NoteDiagnosticCode = 'dangling-note-reference' | 'note-reference-scan-truncated';
+/**
+ * Load-time note diagnostics. Array API preserved; truncation is signaled as a typed
+ * entry rather than by throwing or rejecting the package.
+ */
+type NoteDiagnostic = {
+    readonly code: 'dangling-note-reference';
+    readonly noteKind: NoteKind;
+    readonly noteId: number;
+    /** Paragraph / container node id when known. */
+    readonly sourceNodeId?: string;
+} | {
+    /** Hard visited/part budget or soft hit cap stopped the scan before full coverage. */
+    readonly code: 'note-reference-scan-truncated';
+};
+/** One note reference found in a story, with where it sits. */
+interface NoteReferenceHit {
+    readonly noteKind: NoteKind;
+    readonly noteId: number;
+    readonly nodeId: string;
+    readonly paragraphId: string;
+    /** Canonical UTF-16 atom offset within {@link paragraphId} (U+FFFC model). */
+    readonly atomOffset: number;
+    readonly customMarkFollows: boolean;
+    /** Canonical part name that owns this reference. */
+    readonly partName: string;
+}
+/** Mutable visited-node + part budget shared across parts / package snapshots. */
+interface NoteReferenceScanBudget {
+    visited: number;
+    readonly maxVisited: number;
+    parts: number;
+    readonly maxParts: number;
+    /** Set when a walk stops before finishing because a cap was hit. */
+    truncated: boolean;
+}
+/** A bounded budget for scanning note references, so a crafted document cannot stall a load. */
+declare function createNoteReferenceScanBudget(maxVisited?: number, maxParts?: number): NoteReferenceScanBudget;
+/**
+ * Resolve the footnotes or endnotes part via safe Internal document relationships.
+ *
+ * Unusable matching relationships (External, unsafe target, missing part, wrong root)
+ * are skipped — never fetched, never accepted — so a decoy first match cannot hide a
+ * later usable Internal notes part (same continue-past-bad pattern as settingsPartOf).
+ */
+declare function resolveNotesPart(pkg: OoxmlPackage, noteKind: NoteKind): OoxmlPart | null;
+/** Walk a part without applying a layout projection. */
+declare function collectNoteReferences(part: OoxmlPart, options?: {
+    readonly maxHits?: number;
+    readonly budget?: NoteReferenceScanBudget;
+}): readonly NoteReferenceHit[];
+/** Collect references across every XML part under one shared part + visited-node budget. */
+declare function collectPackageNoteReferences(pkg: OoxmlPackage, options?: {
+    readonly budget?: NoteReferenceScanBudget;
+    /** Soft hit cap for diagnostics. Omit / Infinity for mutation scans. */
+    readonly maxHits?: number;
+}): readonly NoteReferenceHit[];
+/**
+ * Load diagnostics for dangling note references. Fail-open: never throws or mutates;
+ * returns diagnostics for callers to surface. Does not invent missing note bodies.
+ *
+ * When the hard visited/part budget truncates or the soft hit cap binds, appends a single
+ * `note-reference-scan-truncated` entry so incomplete coverage is visible without breaking
+ * consumers that filter on `dangling-note-reference`.
+ */
+declare function diagnoseNoteReferences(pkg: OoxmlPackage): readonly NoteDiagnostic[];
+/** Whether a notes-part root contains a note with the given id (any type). */
+declare function notesPartHasId(part: OoxmlPart, noteId: number): boolean;
+/** List normal (body) note ids in document order, bounded. */
+declare function normalNoteIds(part: OoxmlPart): readonly number[];
+
+/** How far a note lifecycle op reaches — which parts a caller must expect to have changed. */
+type NoteLifecycleImpact = 'flow-structural' | 'global';
+/**
+ * A note lifecycle mutation: insert, delete, convert, or set properties.
+ *
+ * Package-level rather than story-level, because every one of these touches the main document,
+ * the notes part, the document relationships AND `[Content_Types].xml` together.
+ */
+type NoteLifecycleOp = {
+    readonly op: 'insertNote';
+    readonly noteKind: NoteKind;
+    readonly paragraphId: string;
+    readonly offset: number;
+    /**
+     * Write the citing reference as a TRACKED insertion: the reference run goes inside a
+     * `w:ins` carrying this attribution. The note body stays plain — rejecting the
+     * reference removes it, and the orphaned body is swept by the same cascade an
+     * untracked reference deletion triggers.
+     */
+    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;
+
+/** Decoded fragment payloads above this cap are refused before any package work. */
+declare const MAX_FRAGMENT_DECODED_BYTES: number;
+interface FragmentPasteInput {
+    readonly paragraphId: string;
+    readonly offset: number;
+    /** The fragment package zip (from the clipboard codec or the HTML projection). */
+    readonly fragmentBytes: Uint8Array;
+    readonly lastMarkCovered: boolean;
+    /** Ops that clear the current selection first (the surface's deleteSelectionPlan). */
+    readonly priorOps?: readonly TreeDocOp[];
+    /**
+     * Collaboration actor for the ids this paste mints.
+     *
+     * A paste freshens three package-wide namespaces — bookmark `@w:id`, revision `@w:id` and
+     * `wp:docPr/@id` — and the merge reads the actor off the open transaction. Without one, two
+     * replicas pasting the same fragment from one snapshot mint the same numbers, and only the
+     * merged document shows it. Omitted (solo) keeps Word's dense sequences.
+     */
+    readonly actorId?: string;
+}
+type FragmentPasteResult = (Extract<PackageTransactResult, {
+    ok: true;
+}> & {
+    readonly blockCount: number;
+}) | Extract<PackageTransactResult, {
+    ok: false;
+}>;
+/**
+ * Read the fragment through the bounded file-open trust boundary, merge its resources,
+ * and land its blocks — all inside one transaction. Any refusal leaves the document
+ * exactly as it was; the caller (the paste router) degrades to the next flavour.
+ */
+declare function applyFragmentPaste(store: TreePackageStore, scope: StoryScope, input: FragmentPasteInput): FragmentPasteResult;
+
+/** Attribution stamped on one remote canonical publication. */
+interface RemotePackageAttribution {
+    readonly origin: string;
+    readonly actorId?: string;
+    readonly operationId?: string;
+}
+
+type NoteCascadeFn = (before: OoxmlPackage, after: OoxmlPackage) => OoxmlPackage | null;
+/**
+ * Editable story target.
+ *
+ * Body and headerFooter mirror `EditorScope`. Notes use one lazy store per notes part
+ * (`notesPart`) — not one store per note — resolved through safe document relationships.
+ */
+type StoryScope = {
+    readonly kind: 'body';
+} | {
+    readonly kind: 'headerFooter';
+    readonly rId: string;
+} | {
+    readonly kind: 'notesPart';
+    readonly noteKind: NoteKind;
+};
+/**
+ * Why a story scope could not be resolved to a part.
+ *
+ * Several of these are FILE-hostile shapes rather than caller mistakes:
+ * `external-relationship` and `bad-relationship-target` are how a crafted document tries to
+ * point a story at something outside the package, and both are refused rather than followed.
  */
 type StoryTargetRejection = 'unknown-scope' | 'dangling-relationship' | 'wrong-relationship-type' | 'external-relationship' | 'bad-relationship-target' | 'missing-part' | 'not-a-story-part' | 'too-many-story-stores';
 /** A story scope resolved to a part, or the typed reason it could not be. */
@@ -1002,6 +1168,8 @@ declare const DEFAULT_MAX_EDITABLE_STORY_PARTS = 64;
 /** How a package store is constructed: limits, history depth, and review contributions. */
 interface TreePackageStoreOptions {
     readonly historyLimit?: number;
+    /** Opt-in relaxation of `w:lock` for run-property writes, for the body and every story store. */
+    readonly contentLockPolicy?: ContentLockPolicy;
     /** Bound on opened story stores; defaults to {@link DEFAULT_MAX_EDITABLE_STORY_PARTS}. */
     readonly maxEditableStoryParts?: number;
     /**
@@ -1025,8 +1193,10 @@ declare class TreePackageStore {
     private readonly rIdToPartName;
     private readonly undoOrder;
     private readonly redoOrder;
+    private readonly historyGroups;
     private readonly subscribers;
     private readonly historyLimit;
+    private readonly contentLockPolicy;
     private readonly maxEditableStoryParts;
     private readonly cascadeNoteReferences;
     private lastChange;
@@ -1051,6 +1221,14 @@ declare class TreePackageStore {
      * a matching tuple proves the snapshot cannot differ; nothing invalidates explicitly.
      */
     private currentPackageMemo;
+    /**
+     * What the body and every story store open with. `settingsPart` is the SAME live getter for
+     * all of them: a story store is built from a PART, whose synthetic package holds no
+     * `settings.xml`, and a store keeps its own working copy, so a replaced `settings.xml` left one
+     * story reading stale protection. Protection that holds in a header but not the body is worse
+     * than none: it looks enforced. The lock policy reaches every story for the same reason.
+     */
+    private storyStoreOptions;
     constructor(pkg: OoxmlPackage, main: OoxmlPart, options?: TreePackageStoreOptions);
     get packageRevision(): number;
     get canUndo(): boolean;
@@ -1100,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;
@@ -1170,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;
     /**
@@ -1190,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;
@@ -1197,5 +1381,5 @@ declare class TreePackageStore {
     private publishSynthetic;
 }
 
-export { NOTE_ID_MAX as B, DEFAULT_MAX_EDITABLE_STORY_PARTS as D, NOTE_ID_MIN as E, NOTE_SEPARATOR_ID as G, MAX_FRAGMENT_DECODED_BYTES as M, TreePackageStore as T, allocateDrawingPropertyId as a4, allocateNoteId as a5, applyFragmentPaste as a6, applyHeaderFooterLifecycleOp as a7, applyNoteLifecycleOp as a8, atomicNoteSpansOf as a9, noteTypeOf as aA, notesOf as aB, notesPartHasId as aC, observeHistoryGroup as aD, parseNoteId as aE, parseNoteScopeId as aF, resolveHeaderFooterParts as aG, resolveHeaderFooterPartsBySection as aH, resolveHeaderFooterResolutionBySection as aI, resolveNotesPart as aJ, withBinaryPart as aK, withEmbeddedImage as aL, withoutUnreferencedImagePart as aM, cascadeDeletedNoteReferences as aa, collectNoteReferences as ab, collectPackageNoteReferences as ac, collectSectionPropertyNodes as ad, createNoteReferenceScanBudget as ae, customMarkFollows as af, diagnoseNoteReferences as ag, findNoteById as ah, formatNoteScopeId as ai, isContinuationSeparatorNode as aj, isEndnotesNode as ak, isFootnotesNode as al, isHeaderFooterLifecycleOp as am, isNormalNote as an, isNoteAtomNode as ao, isNoteLifecycleOp as ap, isNoteNode as aq, isNoteRefNode as ar, isNoteReferenceNode as as, isSeparatorNode as at, normalNoteIds as au, noteAtomText as av, noteIdOf as aw, noteKindOf as ax, noteRefKindOf as ay, noteReferenceKindOf as az, TreeDocumentStore as f, reportHistoryGroup as r, MAX_NOTES_PER_PART as v, MAX_NOTE_REFERENCE_PARTS as w, MAX_NOTE_REFERENCE_SCAN as x, NOTE_ATOM_CHAR as y, NOTE_CONTINUATION_SEPARATOR_ID as z };
-export type { TreeDocumentStoreOptions as $, ApplyImagePropertiesInput as A, CascadeDeletedNoteReferencesOptions as C, FieldResultsMode as F, HeaderFooterParts as H, InsertImageInput as I, NoteDiagnostic as J, NoteDiagnosticCode as K, NoteLifecycleImpact as L, NoteKind as N, NoteLifecycleOp as O, NoteLifecycleOptions as P, NoteLifecycleRejection as Q, ReplaceImageOptions as R, StoryScope as S, NoteLifecycleResult as U, NoteReferenceHit as V, NoteReferenceScanBudget as W, NoteType as X, PackageTransactResult as Y, RemotePackageAttribution as Z, StoryResolveResult as _, StoryTargetRejection as a, TreePackageStoreOptions as a0, TreeStoryRef as a1, TransactResult as a2, TransactionContext as a3, HeaderFooterSectionResolution as b, HeaderFooterVariant as c, HistoryGroup as d, TreeModelChange as e, SelectionMark as g, TransactOptions as h, ImageIntentResult as i, FragmentPasteInput as j, FragmentPasteResult as k, AtomicNoteSpan as l, DrawingPropertyIdResult as m, HeaderFooterKind as n, HeaderFooterLifecycleImpact as o, HeaderFooterLifecycleOp as p, HeaderFooterLifecycleRejection as q, HeaderFooterLifecycleResult as s, HeaderFooterSlotMeta as t, HistoryCaptureKind as u };
+export { NOTE_CONTINUATION_SEPARATOR_ID as B, DEFAULT_MAX_EDITABLE_STORY_PARTS as D, NOTE_ID_MAX as G, NOTE_ID_MIN as J, NOTE_SEPARATOR_ID as K, MAX_FRAGMENT_DECODED_BYTES as M, TreePackageStore as T, allocateDrawingPropertyId as a8, allocateNoteId as a9, isNoteNode as aA, isNoteRefNode as aB, isNoteReferenceNode as aC, isSeparatorNode as aD, normalNoteIds as aE, noteAtomText as aF, noteIdOf as aG, noteKindOf as aH, noteRefKindOf as aI, noteReferenceKindOf as aJ, noteTypeOf as aK, notesOf as aL, notesPartHasId as aM, observeHistoryGroup as aN, parentNodeOf as aO, parseNoteId as aP, parseNoteScopeId as aQ, removeNode as aR, replaceChildren as aS, replaceNode as aT, resolveHeaderFooterParts as aU, resolveHeaderFooterPartsBySection as aV, resolveHeaderFooterResolutionBySection as aW, resolveNotesPart as aX, withBinaryPart as aY, withEmbeddedImage as aZ, withoutUnreferencedImagePart as a_, applyEdits as aa, applyFragmentPaste as ab, applyHeaderFooterLifecycleOp as ac, applyNoteLifecycleOp as ad, atomicNoteSpansOf as ae, cascadeDeletedNoteReferences as af, collectNodeIds as ag, collectNoteReferences as ah, collectPackageNoteReferences as ai, collectSectionPropertyNodes as aj, createNodeIdAllocator as ak, createNoteReferenceScanBudget as al, customMarkFollows as am, diagnoseNoteReferences as an, findNode as ao, findNoteById as ap, formatNoteScopeId as aq, hasNode as ar, insertChildren as as, isContinuationSeparatorNode as at, isEndnotesNode as au, isFootnotesNode as av, isHeaderFooterLifecycleOp as aw, isNormalNote as ax, isNoteAtomNode as ay, isNoteLifecycleOp as az, TreeDocumentStore as f, reportHistoryGroup as r, MAX_NOTES_PER_PART as w, MAX_NOTE_REFERENCE_PARTS as x, MAX_NOTE_REFERENCE_SCAN as y, NOTE_ATOM_CHAR as z };
+export type { PackageTransactResult as $, ApplyImagePropertiesInput as A, ContentLockPolicy as C, EditOptions as E, FieldResultsMode as F, HeaderFooterParts as H, InsertImageInput as I, NoteDiagnostic as L, NoteKind as N, NoteDiagnosticCode as O, NoteLifecycleImpact as P, NoteLifecycleOp as Q, ReplaceImageOptions as R, StoryScope as S, NoteLifecycleOptions as U, NoteLifecycleRejection as V, NoteLifecycleResult as W, NoteReferenceHit as X, NoteReferenceScanBudget as Y, NoteType as Z, OoxmlEditResult as _, HeaderFooterSectionResolution as a, RemotePackageAttribution as a0, StoryResolveResult as a1, TransactionRevisionIds as a2, TreeDocumentStoreOptions as a3, TreePackageStoreOptions as a4, TreeStoryRef as a5, TransactResult as a6, TransactionContext as a7, StoryTargetRejection as b, HeaderFooterVariant as c, HistoryGroup as d, TreeModelChange as e, SelectionMark as g, TransactOptions as h, ImageIntentResult as i, FragmentPasteInput as j, FragmentPasteResult as k, AtomicNoteSpan as l, CascadeDeletedNoteReferencesOptions as m, DrawingPropertyIdResult as n, HeaderFooterKind as o, HeaderFooterLifecycleImpact as p, HeaderFooterLifecycleOp as q, HeaderFooterLifecycleRejection as s, HeaderFooterLifecycleResult as t, HeaderFooterSlotMeta as u, HistoryCaptureKind as v };