@docx-editor.dev/core 2.17.0 → 2.19.0

package/dist/{tree-package-fragment-DRJkmfTW.d.ts → tree-package-fragment-1pdDnhZ_.d.ts}

@@ -1,6 +1,4 @@
-import { b as OoxmlPackage, y as SupportedImageMime, O as OoxmlPart, C as RevisionAttributionInput, E as ImageDecodePort, F as DrawingTreeDocOp, p as TreeOpRejection, T as TreeDocOp } from './tree-op-types-C71G7rIv.js';
-import { c as HeaderFooterKind, H as HeaderFooterVariant } from './hf-references-kSSFMq9X.js';
-import { N as NoteKind, T as TreeModelChange, a as TreeDocumentStore, b as TreeStoryRef, c as TransactionContext, d as TransactOptions, S as SelectionMark, e as TreeDocumentCheckpoint } from './tree-store-BRfhZceK.js';
+import { b as OoxmlPackage, p as SupportedImageMime, O as OoxmlPart, a as OoxmlNode, e as OoxmlElement, w as OoxmlParagraphNode, x as OoxmlNoteNode, y as OoxmlContinuationSeparatorNode, z as OoxmlEndnotesNode, B as OoxmlFootnotesNode, C as OoxmlNoteRefNode, E as OoxmlNoteReferenceNode, F as OoxmlSeparatorNode, u as RevisionAttributionInput, t as ImageDecodePort, G as DrawingTreeDocOp, H as ImpactClass, T as TreeDocOp, l as TreeOpRejection } from './tree-op-types-DbdM7fJV.js';
 
 /** A freshly allocated drawing property id, or the reason one could not be minted. */
 type DrawingPropertyIdResult = {
@@ -64,6 +62,73 @@ interface ExternalImageFetchPort {
     }>>;
 }
 
+/** `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. */
+type HeaderFooterKind = 'header' | 'footer';
+/**
+ * A section's resolved header and footer parts, by variant.
+ *
+ * The `even` variant is only honoured when `w:evenAndOddHeaders` is set in settings.xml —
+ * without it Word ignores an authored even header, and so does this.
+ */
+interface HeaderFooterParts {
+    readonly headers: ReadonlyMap<HeaderFooterVariant, OoxmlPart>;
+    readonly footers: ReadonlyMap<HeaderFooterVariant, OoxmlPart>;
+    /** `w:evenAndOddHeaders` in settings.xml — without it the `even` variant is ignored. */
+    readonly evenAndOddHeaders: boolean;
+    /** Whether this section enables first-page header/footer furniture (`w:titlePg`). */
+    readonly titlePage: boolean;
+}
+/**
+ * One resolved furniture slot with enough metadata for "Same as previous" chrome.
+ *
+ * `inherited: true` means this section has no declared reference for the slot and the
+ * part comes from a predecessor. The first section never reports inherited — omitting a
+ * ref there is blank furniture, not inheritance from a later section.
+ */
+interface HeaderFooterSlotMeta {
+    readonly part: OoxmlPart;
+    readonly partName: string;
+    readonly rId: string;
+    readonly inherited: boolean;
+}
+/** Per-section resolution including declared-vs-inherited metadata. */
+interface HeaderFooterSectionResolution {
+    readonly headers: ReadonlyMap<HeaderFooterVariant, HeaderFooterSlotMeta>;
+    readonly footers: ReadonlyMap<HeaderFooterVariant, HeaderFooterSlotMeta>;
+    readonly evenAndOddHeaders: boolean;
+    readonly titlePage: boolean;
+}
+/**
+ * `w:sectPr` nodes in section order, aligned with layout's `enumerateDocumentSections`.
+ *
+ * `null` means a section with no `w:sectPr` node (Word defaults, inherits HF from previous).
+ * Paragraph-level breaks first; the final entry covers remaining blocks (body-level or null).
+ */
+declare function collectSectionPropertyNodes(root: OoxmlNode): Array<OoxmlElement | null>;
+/**
+ * Resolve header/footer parts for every section with declared-vs-inherited metadata.
+ *
+ * Index aligns with `enumerateDocumentSections` in the layout package. Existing merged
+ * maps stay available via {@link resolveHeaderFooterPartsBySection}.
+ */
+declare function resolveHeaderFooterResolutionBySection(pkg: OoxmlPackage): readonly HeaderFooterSectionResolution[];
+/**
+ * Resolve header/footer parts for every section, applying OOXML inheritance.
+ *
+ * Index aligns with `enumerateDocumentSections` in the layout package.
+ */
+declare function resolveHeaderFooterPartsBySection(pkg: OoxmlPackage): readonly HeaderFooterParts[];
+/**
+ * Resolve the main-document header/footer references to their parts, gated by the
+ * settings the section actually declares.
+ *
+ * Returns the FINAL section's effective parts (after inheritance). Multi-section hosts
+ * should prefer `resolveHeaderFooterPartsBySection`.
+ */
+declare function resolveHeaderFooterParts(pkg: OoxmlPackage): HeaderFooterParts;
+
 /** Lifecycle impact — furniture always reaches multiple pages; never narrower than flow-structural. */
 type HeaderFooterLifecycleImpact = 'flow-structural' | 'global';
 /**
@@ -103,6 +168,13 @@ type HeaderFooterLifecycleOp = {
     readonly evenAndOddHeaders?: boolean;
     readonly headerDistanceTwips?: number;
     readonly footerDistanceTwips?: number;
+} | {
+    /**
+     * A `settings.xml` write like `evenAndOddHeaders`, so it rides the same package-level
+     * undo unit and the same routing rather than growing a second lifecycle lane.
+     */
+    readonly op: 'setDocumentProtection';
+    readonly enforce: boolean;
 };
 /** Why a header/footer lifecycle op was refused. */
 type HeaderFooterLifecycleRejection = 'invalidArgs' | 'tree-invariant';
@@ -128,6 +200,123 @@ 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.
+ *
+ * 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;
 /**
@@ -371,6 +560,302 @@ interface ApplyImagePropertiesInput {
     readonly hyperlink: string | null;
 }
 
+/** 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.
+     */
+    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;
+}
+/** 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;
+}
+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;
+}
+/** 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;
+}
+/**
+ * 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 readonly subscribers;
+    private readonly historyLimit;
+    /** See {@link TreeDocumentStoreOptions.settingsPart}. */
+    private readonly settingsPartOverride;
+    /** 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;
+    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;
+}
+
 /** Attribution stamped on one remote canonical publication. */
 interface RemotePackageAttribution {
     readonly origin: string;
@@ -599,31 +1084,14 @@ declare class TreePackageStore {
      * content-types mutate the package outside story trees.
      */
     replacePackageShell(pkg: OoxmlPackage): void;
-    /**
-     * Install a full package snapshot: body + opened story stores track the snapshot's parts.
-     * Stores whose parts disappeared stay parked (history identity preserved) so a later
-     * package undo can reconnect them; rId cache rebuilds from remaining relationships.
-     *
-     * Numbering / shell-minted hyperlink resources (via {@link replacePackageShell}) are merged
-     * onto the snapshot so lifecycle undo cannot orphan story `numId` / `r:id` references.
-     * Furniture and notes parts remain snapshot-owned; shell hyperlink `.rels` for those owners
-     * park when the part is temporarily absent and are pruned once history can no longer restore
-     * the owner. Lifecycle-cloned owned relationships are not shell-minted and GC with the part.
-     */
+    /** Restore snapshot stories while retaining history-reachable shell resources. */
     private installPackageSnapshotInternal;
     private openNotesPartStore;
     private openHeaderFooterStore;
     private storyRefForPart;
     private syncPackageFromStore;
     private pushUndoPointer;
-    /**
-     * Drop parked story stores that no current package part and no undo/redo pointer can
-     * restore. History-reachable identities stay so edit→delete→undo reconnects the same
-     * store; unreachable parked entries must not hold `maxEditableStoryParts` forever.
-     *
-     * Also prunes scoped hyperlink shell resources parked for owners that are no longer
-     * live and not history-reachable (see `pruneUnreachableHyperlinkShell`).
-     */
+    /** Keep history-reachable stories and prune unreachable shell hyperlink owners. */
     private evictUnreachableStories;
     private publish;
     private publishSynthetic;
@@ -663,4 +1131,4 @@ type FragmentPasteResult = (Extract<PackageTransactResult, {
  */
 declare function applyFragmentPaste(store: TreePackageStore, scope: StoryScope, input: FragmentPasteInput): FragmentPasteResult;
 
-export { type ApplyImagePropertiesInput as A, collectPackageNoteReferences as B, type CascadeDeletedNoteReferencesOptions as C, DEFAULT_MAX_EDITABLE_STORY_PARTS as D, createNoteReferenceScanBudget as E, type FragmentPasteInput as F, diagnoseNoteReferences as G, type HeaderFooterLifecycleImpact as H, type InsertImageInput as I, isHeaderFooterLifecycleOp as J, isNoteLifecycleOp as K, normalNoteIds as L, MAX_FRAGMENT_DECODED_BYTES as M, type NoteDiagnostic as N, notesPartHasId as O, type PackageTransactResult as P, resolveNotesPart as Q, type ReplaceImageOptions as R, type StoryScope as S, TreePackageStore as T, withBinaryPart as U, withEmbeddedImage as V, withoutUnreferencedImagePart as W, type StoryTargetRejection as a, type ImageIntentResult as b, type FragmentPasteResult as c, type DrawingPropertyIdResult as d, type HeaderFooterLifecycleOp as e, type HeaderFooterLifecycleRejection as f, type HeaderFooterLifecycleResult as g, MAX_NOTE_REFERENCE_PARTS as h, MAX_NOTE_REFERENCE_SCAN as i, type NoteDiagnosticCode as j, type NoteLifecycleImpact as k, type NoteLifecycleOp as l, type NoteLifecycleOptions as m, type NoteLifecycleRejection as n, type NoteLifecycleResult as o, type NoteReferenceHit as p, type NoteReferenceScanBudget as q, type RemotePackageAttribution as r, type StoryResolveResult as s, type TreePackageStoreOptions as t, allocateDrawingPropertyId as u, applyFragmentPaste as v, applyHeaderFooterLifecycleOp as w, applyNoteLifecycleOp as x, cascadeDeletedNoteReferences as y, collectNoteReferences as z };
+export { type TransactResult as $, type ApplyImagePropertiesInput as A, type NoteDiagnostic as B, type CascadeDeletedNoteReferencesOptions as C, DEFAULT_MAX_EDITABLE_STORY_PARTS as D, type NoteDiagnosticCode as E, type FragmentPasteInput as F, type NoteLifecycleImpact as G, type HeaderFooterVariant as H, type InsertImageInput as I, type NoteLifecycleOp as J, type NoteLifecycleOptions as K, type NoteLifecycleRejection as L, MAX_FRAGMENT_DECODED_BYTES as M, type NoteKind as N, type NoteLifecycleResult as O, type NoteReferenceHit as P, type NoteReferenceScanBudget as Q, type ReplaceImageOptions as R, type StoryScope as S, TreePackageStore as T, type NoteType as U, type PackageTransactResult as V, type RemotePackageAttribution as W, type StoryResolveResult as X, type TreeDocumentStoreOptions as Y, type TreePackageStoreOptions as Z, type TreeStoryRef as _, type StoryTargetRejection as a, type TransactionContext as a0, allocateDrawingPropertyId as a1, allocateNoteId as a2, applyFragmentPaste as a3, applyHeaderFooterLifecycleOp as a4, applyNoteLifecycleOp as a5, atomicNoteSpansOf as a6, cascadeDeletedNoteReferences as a7, collectNoteReferences as a8, collectPackageNoteReferences as a9, parseNoteScopeId as aA, resolveHeaderFooterParts as aB, resolveHeaderFooterPartsBySection as aC, resolveHeaderFooterResolutionBySection as aD, resolveNotesPart as aE, withBinaryPart as aF, withEmbeddedImage as aG, withoutUnreferencedImagePart as aH, collectSectionPropertyNodes as aa, createNoteReferenceScanBudget as ab, customMarkFollows as ac, diagnoseNoteReferences as ad, findNoteById as ae, formatNoteScopeId as af, isContinuationSeparatorNode as ag, isEndnotesNode as ah, isFootnotesNode as ai, isHeaderFooterLifecycleOp as aj, isNormalNote as ak, isNoteAtomNode as al, isNoteLifecycleOp as am, isNoteNode as an, isNoteRefNode as ao, isNoteReferenceNode as ap, isSeparatorNode as aq, normalNoteIds as ar, noteAtomText as as, noteIdOf as at, noteKindOf as au, noteRefKindOf as av, noteReferenceKindOf as aw, notesOf as ax, notesPartHasId as ay, parseNoteId as az, type TreeModelChange as b, type HeaderFooterParts as c, type HeaderFooterSectionResolution as d, TreeDocumentStore as e, type SelectionMark as f, type TransactOptions as g, type ImageIntentResult as h, type FragmentPasteResult as i, type AtomicNoteSpan as j, type DrawingPropertyIdResult as k, type HeaderFooterKind as l, type HeaderFooterLifecycleImpact as m, noteTypeOf as n, type HeaderFooterLifecycleOp as o, type HeaderFooterLifecycleRejection as p, type HeaderFooterLifecycleResult as q, type HeaderFooterSlotMeta as r, MAX_NOTES_PER_PART as s, MAX_NOTE_REFERENCE_PARTS as t, MAX_NOTE_REFERENCE_SCAN as u, NOTE_ATOM_CHAR as v, NOTE_CONTINUATION_SEPARATOR_ID as w, NOTE_ID_MAX as x, NOTE_ID_MIN as y, NOTE_SEPARATOR_ID as z };

package/dist/{tree-session-contract-Cp5W25RC.d.ts → tree-session-contract-Cgn6fQ-M.d.ts}

@@ -1,10 +1,8 @@
-import { S as StoryScope, a as StoryTargetRejection, I as InsertImageInput, b as ImageIntentResult, R as ReplaceImageOptions, A as ApplyImagePropertiesInput, F as FragmentPasteInput, c as FragmentPasteResult } from './tree-package-fragment-DRJkmfTW.js';
-import { T as TreeDocOp, O as OoxmlPart, a as OoxmlNode, b as OoxmlPackage, c as OoxmlElement, y as SupportedImageMime, E as ImageDecodePort, C as RevisionAttributionInput } from './tree-op-types-C71G7rIv.js';
-import { a as HeaderFooterParts, b as HeaderFooterSectionResolution } from './hf-references-kSSFMq9X.js';
-import { D as DocumentTrackingSettings, I as InsertCustomNodeWrite, C as CustomNodeWriteResult, a as CustomNodeSweepOutcome, E as EmbeddedFont, B as BookmarkIndex, L as ListKind } from './custom-node-writes-ClTkWM7s.js';
-import { H as HeadlessDocumentView, D as DocumentProperties } from './headless-document-view-BDSeMGoK.js';
-import { S as SelectionMark, d as TransactOptions, T as TreeModelChange } from './tree-store-BRfhZceK.js';
-import { a as ReviewItem } from './review-items-CiliAz8H.js';
+import { S as StoryScope, f as SelectionMark, g as TransactOptions, a as StoryTargetRejection, b as TreeModelChange, c as HeaderFooterParts, d as HeaderFooterSectionResolution, I as InsertImageInput, h as ImageIntentResult, R as ReplaceImageOptions, A as ApplyImagePropertiesInput, F as FragmentPasteInput, i as FragmentPasteResult } from './tree-package-fragment-1pdDnhZ_.js';
+import { T as TreeDocOp, O as OoxmlPart, a as OoxmlNode, b as OoxmlPackage, e as OoxmlElement, p as SupportedImageMime, t as ImageDecodePort, u as RevisionAttributionInput } from './tree-op-types-DbdM7fJV.js';
+import { D as DocumentTrackingSettings, I as InsertCustomNodeWrite, C as CustomNodeWriteResult, a as CustomNodeSweepOutcome, E as EmbeddedFont, B as BookmarkIndex, L as ListKind } from './custom-node-writes-BqIv94ei.js';
+import { H as HeadlessDocumentView, D as DocumentProperties } from './headless-document-view-C4ttQJ5H.js';
+import { a as ReviewItem } from './review-items-CJz-kAW8.js';
 import { Node } from 'prosemirror-model';
 import { CollaborationDocumentPort } from './collaboration/replication.js';
 import { V as ViewScope } from './editor-scope-DZJT4ukT.js';
@@ -67,8 +65,32 @@ declare function reconcileDoc(previousDoc: Node, part: OoxmlPart, change: {
     readonly splitJoin: readonly unknown[];
 } | null): Node;
 
+/**
+ * The faces a theme's font scheme offers, per script slot.
+ *
+ * Structurally satisfied by both lanes' theme-font shapes (`DocumentThemeFonts`,
+ * layout's `ThemeFonts`). The East Asian faces are optional so callers that have not
+ * harvested them yet still type-check; an absent face resolves to null, which every
+ * caller already treats as "fall back to the explicit attribute".
+ */
+interface ThemeSchemeFaces {
+    /** `a:majorFont` latin typeface — headings. */
+    readonly major: string | null;
+    /** `a:minorFont` latin typeface — body text. */
+    readonly minor: string | null;
+    /** `a:majorFont` east asian typeface (`a:ea`). */
+    readonly majorEastAsia?: string | null;
+    /** `a:minorFont` east asian typeface (`a:ea`). */
+    readonly minorEastAsia?: string | null;
+    /** Complex-script heading and body faces (`a:cs`). */
+    readonly majorBidi?: string | null;
+    readonly minorBidi?: string | null;
+    /** Language-specific theme faces, keyed by ISO 15924 script. */
+    readonly majorSupplemental?: Readonly<Record<string, string>>;
+    readonly minorSupplemental?: Readonly<Record<string, string>>;
+}
 /** The theme's font slots, fully resolved, for resolving `w:rFonts` theme attributes. */
-interface DocumentThemeFonts {
+interface DocumentThemeFonts extends ThemeSchemeFaces {
     /** `a:majorFont` latin typeface — headings. */
     readonly major: string | null;
     /** `a:minorFont` latin typeface — body text. */
@@ -233,7 +255,10 @@ interface TreeApplyResult {
     readonly reason?: TreeBindingRejection | StoryTargetRejection | string;
 }
 /** Optional collaboration attribution for a direct tree-op transaction. */
-type TreeApplyOptions = Pick<TransactOptions, 'origin' | 'actorId' | 'operationId' | 'recordsHistory'>;
+type TreeApplyOptions = Pick<TransactOptions, 'origin' | 'actorId' | 'operationId' | 'recordsHistory'> & {
+    /** Package resources committed in the same transaction as the tree operations. */
+    readonly packageEdits?: readonly ((pkg: OoxmlPackage) => OoxmlPackage)[];
+};
 /**
  * One open document: the canonical tree, and the only write path into it.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx-editor.dev/core",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "description": "Framework-agnostic core for docx-editor.dev: OOXML parse/serialize, the canonical document tree, layout and paint, and the Editor contract the adapters render.",
   "type": "module",
   "engines": {
@@ -105,12 +105,12 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@docx-editor.dev/i18n": "^2.17.0",
-    "bidi-js": "1.0.3",
+    "@docx-editor.dev/i18n": "^2.19.0",
+    "bidi-js": "1.1.0",
     "emf-converter": "2.0.2",
     "fast-xml-parser": "^5.10.1",
     "fflate": "^0.8.2",
-    "harfbuzzjs": "1.6.0",
+    "harfbuzzjs": "1.6.1",
     "prosemirror-commands": "^1.7.1",
     "prosemirror-keymap": "^1.2.3",
     "prosemirror-model": "^1.25.4",