@betteroffice/docx 0.2.1 → 0.3.0

package/dist/{index-CHl2zLJ7.d.mts → index-BbZwdkPz.d.mts}

@@ -1,5 +1,8 @@
+import { C as ColorValue } from './formatting-gqLFeJ9X.mjs';
 import { Document } from './types/document.mjs';
-import { R as RetainedFrame } from './frameDelta-pA4jrQ1G.mjs';
+import { a0 as DocxReadParagraphsRequest, a1 as DocxReadParagraphsResult, a2 as DocxFindTextRequest, a3 as DocxFindTextResult, a4 as DocxEditRequest, a5 as DocxValidationResult, a6 as DocxEditResult, a7 as DocxTextTarget, a8 as DocxEditRefusal, a as DocxExportOptions, H as DocxExportResult, c as DocxStructuredContent, b as DocxMarkdownContent, d as DocxPageExportOptions, f as DocxPagedStructuredContent, i as DocxLayoutMap, g as DocxSnapshotLayoutMap, D as DocxExportFailure, V as DocxParagraphHeading, m as DocxContentControlsOptions, w as DocxContentControlsResult, l as DocxContentControlQuery } from './pagedExport-D3E4jZ-B.mjs';
+import { R as RetainedFrame } from './frameDelta-CVt5FAXT.mjs';
+import { R as RepackOptions } from './rezip-Bxiq4Z_R.mjs';
 
 type CollaborationUpdateOrigin = 'local' | 'remote';
 interface CollaborationReplica {
@@ -87,6 +90,157 @@ interface CollaborationPresence {
 type CollaborationStatusListener = (change: CollaborationStatusChange) => void;
 type CollaborationErrorListener = (error: CollaborationError) => void;
 
+/** Typed TypeScript boundary for the Rust package writer. */
+
+/**
+ * Paragraph IDs a session save applies: IDs for source paragraphs outside
+ * the edited stories by part and `w:p` occurrence, and parts written as their
+ * source bytes with only these IDs patched in.
+ */
+interface RustParagraphIds {
+    assignments: Array<{
+        part: string;
+        ordinal: number;
+        paraId: string;
+    }>;
+    patchedParts: Array<{
+        part: string;
+        paraIds: Array<[number, string]>;
+    }>;
+}
+
+/**
+ * Paragraph identity DTOs for `YrsSession` identity reads and saves.
+ *
+ * A session key (`YrsLoc.paraId`) addresses a paragraph in one collaborative
+ * document session. A Word paragraph ID (`w14:paraId`) is saved in the file;
+ * a paragraph has one once its source carried it, it was authored in a
+ * session, or the host called `YrsSession.persistParagraphIds()`.
+ */
+/** A Word story qualified by the package part it is read from. */
+type DocxSourceStory = {
+    partUri: string;
+    kind: 'body' | 'header' | 'footer';
+} | {
+    partUri: string;
+    kind: 'footnote' | 'endnote' | 'comment';
+    itemId: string;
+};
+/** A paragraph in one collaborative document session, on any of its replicas. */
+interface DocxSessionParagraphAnchor {
+    kind: 'session';
+    sessionId: string;
+    story: string;
+    paraId: string;
+}
+/**
+ * A `w:p` occurrence in the exact source package the session was opened
+ * from: its zero-based position among the part's paragraphs, nested ones
+ * included, as the source bytes hold them rather than as edited since.
+ */
+interface DocxSourceParagraphAnchor {
+    kind: 'source';
+    packageSha256: string;
+    /** OPC part name, such as `/word/document.xml`. */
+    partUri: string;
+    paragraphOrdinal: number;
+}
+/**
+ * A saved Word paragraph ID within its source story. It resolves after the
+ * saved file is reopened, but it is scoped to a document the host chose: an
+ * eight-digit ID is not a document identifier.
+ */
+interface DocxPersistedParagraphAnchor {
+    kind: 'persisted';
+    story: DocxSourceStory;
+    paraId: string;
+}
+type DocxParagraphAnchor = DocxSessionParagraphAnchor | DocxSourceParagraphAnchor | DocxPersistedParagraphAnchor;
+/** A paragraph a resolution, assignment or diagnostic names. */
+type DocxParagraphRef = DocxSessionParagraphAnchor | DocxSourceParagraphAnchor;
+/**
+ * Where a Word paragraph ID comes from: `source` IDs are already in the source
+ * package; the others are prepared by the session and appear on save.
+ */
+type DocxParagraphIdOrigin = 'source' | 'authored' | 'persisted' | 'repaired';
+/** Where a paragraph comes from; `synthetic` ones are editor-only until authored into. */
+type DocxParagraphOrigin = 'source' | 'authored' | 'synthetic';
+interface DocxParagraphIdentity {
+    /** `null` for a source paragraph outside the session stories. */
+    session: DocxSessionParagraphAnchor | null;
+    origin: DocxParagraphOrigin;
+    /** The Word paragraph ID the paragraph saves with, or `null` when it saves without one. */
+    ooxmlParaId: string | null;
+    idOrigin: DocxParagraphIdOrigin | null;
+    /** `null` without a Word paragraph ID or a source story. */
+    persisted: DocxPersistedParagraphAnchor | null;
+    /** `null` unless the paragraph occurs in the retained source package. */
+    source: DocxSourceParagraphAnchor | null;
+}
+/**
+ * Every paragraph's identities: session paragraphs with stories sorted and in
+ * document order, then source paragraphs outside the stories in package order.
+ */
+interface DocxParagraphIdentitySnapshot {
+    sessionId: string;
+    /** SHA-256 of the retained source package, or `null` without one. */
+    packageSha256: string | null;
+    paragraphs: DocxParagraphIdentity[];
+}
+/** A paragraph `YrsSession.persistParagraphIds()` gave a Word paragraph ID. */
+interface DocxParagraphIdAssignment {
+    paragraph: DocxParagraphRef;
+    /** The duplicate session key the paragraph carried before repair. */
+    replacedParaId: string | null;
+    /** The duplicate Word paragraph ID it replaces. */
+    previousOoxmlParaId: string | null;
+    ooxmlParaId: string;
+    idOrigin: 'persisted' | 'repaired';
+    /** `null` when the paragraph has no source story. */
+    persisted: DocxPersistedParagraphAnchor | null;
+}
+type DocxParagraphIdDiagnostic = {
+    /** Saved claims to one ID conflict; the paragraphs keep it and resolve as ambiguous. */
+    kind: 'conflicting-saved-ids';
+    ooxmlParaId: string;
+    paragraphs: DocxParagraphRef[];
+} | {
+    /** No retained source package, so source paragraphs outside the stories were not covered. */
+    kind: 'no-source-package';
+};
+/**
+ * Why `YrsSession.persistParagraphIds()` changed nothing: a duplicated
+ * comment paragraph ID the comment companion parts reference, where which
+ * comment they mean is ambiguous.
+ */
+interface DocxParagraphIdRefusal {
+    kind: 'ambiguous-comment-reference';
+    ooxmlParaId: string;
+    commentIds: string[];
+}
+type DocxParagraphIdentityReceipt = {
+    status: 'applied';
+    assignments: DocxParagraphIdAssignment[];
+    diagnostics: DocxParagraphIdDiagnostic[];
+} | {
+    status: 'refused';
+    refusal: DocxParagraphIdRefusal;
+};
+type DocxParagraphAnchorResult = {
+    status: 'found';
+    anchor: DocxParagraphRef;
+} | {
+    status: 'missing';
+} | {
+    status: 'ambiguous';
+    candidates: DocxParagraphRef[];
+} | {
+    status: 'unsupported';
+    reason: 'foreign-session' | 'foreign-package' | 'no-source-package';
+};
+/** The paragraph IDs a session save applies, as the package writer's `paragraphIds`. @internal */
+type DocxParagraphSavePlan = RustParagraphIds;
+
 /** One native paragraph in the yrs-backed display-position projection. */
 interface YrsInputParagraphSpan {
     paraId: string;
@@ -297,11 +451,11 @@ declare function canUseResidentEngineWorker(): boolean;
  *
  * Stories are `body`, `hf:{rId}`, `fn:{id}`, `en:{id}`, and recursively generated table
  * cell / block-SDT stories. The target session must not already contain any of
- * those story ids.
+ * those story ids. Seeding starts a new opening; see {@link YrsSession.beginOpening}.
  *
  * @public
  */
-declare function documentToYrs(session: YrsSession, document: Document): void;
+declare function documentToYrs(session: YrsSession, document: Document, options?: YrsOpeningOptions): void;
 
 /** yrs-to-OOXML save projection. */
 
@@ -315,24 +469,67 @@ interface YrsToDocumentOptions {
      * projection includes its nested table/content-control stories.
      */
     storyIds?: ReadonlySet<string>;
+    /**
+     * The session comment id of each comment in `base` whose OOXML id is not
+     * that id, such as one added with {@link YrsSession.addComment}. @internal
+     */
+    commentIds?: ReadonlyMap<number, string>;
 }
 declare function yrsToDocument(session: YrsSession, base: Document, options?: YrsToDocumentOptions): Document;
 
+/** Session save that reports where each saved paragraph can be found after reopening. */
+
+/** A saved paragraph's session anchor and the persisted anchor that resolves to it once reopened. */
+interface DocxSavedParagraph {
+    session: DocxSessionParagraphAnchor;
+    persisted: DocxPersistedParagraphAnchor;
+}
+interface DocxSavedDocument {
+    bytes: Uint8Array;
+    /**
+     * Every session paragraph the bytes hold with a Word paragraph ID, in
+     * document order. Stories that share a part are views of its paragraphs:
+     * each view the part holds is listed, and its persisted anchor resolves to
+     * the first story's view once reopened.
+     */
+    paragraphs: DocxSavedParagraph[];
+    /**
+     * Saved paragraphs whose Word paragraph ID the live session reassigned
+     * while the save was written, such as by a duplicate repair after a remote
+     * update: their persisted anchor finds them in these bytes, not in the
+     * live session.
+     */
+    conflicts: DocxSavedParagraph[];
+}
+/** The identities and paragraph ID plan a session save applies. @internal */
+interface DocxSessionSave {
+    identities: DocxParagraphIdentitySnapshot;
+    plan: DocxParagraphSavePlan;
+}
+/** Captures a save of `session`, in the task that projects the saved document. @internal */
+declare function captureSessionSave(session: YrsSession): DocxSessionSave;
 /**
- * Typed facade over the Rust yrs editing core (`crates/docx-edit`).
- *
- * This module is the ONLY JS entry to that crate — the `docx/zipContainer.ts`
- * facade precedent. It is types + JSON marshaling only; every editing
- * semantic (pilcrow-as-character stories, explicit-attribute inserts,
- * suggesting mode, sticky comment anchors) lives in Rust.
- *
- * `createYrsSession()` lazily loads the embedded wasm (`./wasm`) on first call.
- *
- * Addressing is the op-contract public vocabulary: a {@link YrsLoc} is
- * `(story, paraId, offset)` with UTF-16 offsets scoped to one paragraph
- * (`offset ∈ [0, paragraphLength]`; the paragraph's own pilcrow is excluded
- * from its offset space). Story-global indices never cross this boundary.
+ * Writes `document`, projected from `session` when `capture` was taken, and
+ * records the Word paragraph IDs the bytes hold as saved. `patches` selects
+ * the planned parts written as `originalBuffer`'s bytes with IDs patched in;
+ * it selects none unless `originalBuffer` is the session's source package.
+ * @internal
  */
+declare function writeSessionSave(session: YrsSession, document: Document, capture: DocxSessionSave, originalBuffer: ArrayBuffer, options?: RepackOptions, patches?: (part: string) => boolean): Promise<DocxSavedDocument>;
+/**
+ * Saves a session opened from DOCX bytes and reports each saved paragraph's
+ * persisted anchor, read from the same projection the bytes are written
+ * from and kept only where the written part holds its Word paragraph ID.
+ * Parts whose stories are unchanged since the session opened keep
+ * their source bytes, paragraph IDs aside. The comments the session holds
+ * are saved with their anchors, those added to it included; replies and
+ * resolution are saved as the source package has them. A source paragraph without a
+ * Word paragraph ID saves without one unless the host called
+ * `persistParagraphIds()` first; the IDs a save writes are recorded as
+ * saved, so they keep them against unsaved claims from other replicas, once
+ * reconciled with the live session.
+ */
+declare function saveYrsDocx(session: YrsSession, options?: RepackOptions): Promise<DocxSavedDocument>;
 
 interface YrsDocxHost {
     document: Document;
@@ -379,6 +576,10 @@ type YrsRunMark = {
     type: 'italic';
 } | {
     type: 'underline';
+} | {
+    type: 'superscript';
+} | {
+    type: 'subscript';
 } | {
     type: 'fontFamily';
     value: string;
@@ -443,13 +644,36 @@ interface YrsStorySeed {
     /** At least one paragraph. */
     paragraphs: readonly YrsParagraphSeed[];
 }
+/** How a seeding entry point starts its opening; see {@link YrsSession.beginOpening}. */
+interface YrsOpeningOptions {
+    /**
+     * A fixed opening generation, for a deterministic seed every replica loads
+     * as one session. Each opening mints a fresh one by default.
+     */
+    generation?: string;
+}
 /** Snapshot of one paragraph from {@link YrsSession.paragraphs}. */
 interface YrsParagraph {
+    /** Session key; not the paragraph's Word `w14:paraId`. */
     paraId: string;
     text: string;
     /** pStyle / alignment plus any op-set extras. */
     properties: Record<string, unknown>;
 }
+interface YrsTextSearchOptions {
+    /** Defaults to false. */
+    caseSensitive?: boolean;
+    /** Maximum matches; unlimited by default. */
+    limit?: number;
+}
+/** Paragraph-local UTF-16 offsets. */
+interface YrsTextMatch {
+    story: string;
+    paraId: string;
+    start: number;
+    end: number;
+    text: string;
+}
 /** One direct numbering reference (`w:numPr`) on a paragraph. */
 interface YrsNumberingProperties {
     numId?: number;
@@ -487,6 +711,9 @@ interface YrsParagraphAttrs {
     listMarkerHidden?: boolean | null;
     listMarkerFontFamily?: string | null;
     listMarkerFontSize?: number | null;
+    listMarkerBold?: boolean | null;
+    listMarkerItalic?: boolean | null;
+    listMarkerColor?: ColorValue | null;
     listMarkerSuffix?: 'tab' | 'space' | 'nothing' | null;
     listLevelNumFmts?: readonly string[] | null;
     listAbstractNumId?: number | null;
@@ -494,7 +721,11 @@ interface YrsParagraphAttrs {
     /** Passive pPr/model properties not covered by the typed fields. */
     other?: Readonly<Record<string, unknown | null>>;
 }
-/** Typed value stored on a structured document tag (content control). */
+/**
+ * Typed value for a content control. A string fills a plain- or rich-text control's content
+ * (as a `setContentControlText` edit step would); the objects set checkbox, dropdown and date
+ * controls.
+ */
 type YrsContentControlValue = {
     kind: 'dropdown';
     value: string;
@@ -616,6 +847,10 @@ type YrsRawOp = {
     len: number;
     attrs?: Record<string, unknown>;
 } | {
+    /**
+     * A pilcrow's `ooxmlParaId` binds its Word paragraph ID and is dropped
+     * when it is not one; `sourceParaId` and `paraOrigin` are seeding's to set.
+     */
     op: 'insertEmbed';
     index: number;
     kind: string;
@@ -643,6 +878,8 @@ type YrsRawOp = {
 interface YrsRenderEnv {
     tocStyleIds?: string[];
     paragraphSpacingLinePx?: number;
+    /** Section document-grid snap pitch in px (w:docGrid). The engine derives this from sections; hosts may omit it. */
+    docGridPitchPx?: number;
     defaultParagraphStyleId?: string;
     /** Theme color name → hex (`accent1` → `4472C4`), for theme-color resolution. */
     themeColors?: Record<string, string>;
@@ -659,6 +896,16 @@ interface YrsRenderEnv {
 interface YrsCommentReceipt {
     commentId: string;
 }
+/** A comment the session holds; see {@link YrsSession.listComments}. @internal */
+interface YrsCommentInfo {
+    id: string;
+    author: string;
+    date: string;
+    done: boolean;
+    parentId: string | null;
+    /** The body as it was given to {@link YrsSession.addComment} or `setComment`. */
+    body: unknown;
+}
 /**
  * Target of {@link YrsSession.acceptChange} / {@link YrsSession.rejectChange}:
  * one coalesced revision id (resolved at every site, in any story — the
@@ -713,6 +960,17 @@ interface YrsEngineApplyProfile {
  *
  * @internal
  */
+/**
+ * One resident font-store registration, in the order the main thread made it:
+ * raw bytes, or a measurement view of an earlier id. The worker replays the
+ * list to reproduce the same dense ids, so the order and the mix both matter.
+ *
+ * @internal
+ */
+type YrsResidentFontRegistration = Uint8Array | {
+    substituteOf: number;
+    family: string;
+};
 interface YrsResidentWorkerSnapshot {
     clientId: number;
     /** Full document state, or a state-vector diff when the caller supplied
@@ -721,7 +979,7 @@ interface YrsResidentWorkerSnapshot {
     selection: YrsSelection | null;
     /** Empty when the caller declared the worker's fonts current
      * (`knownFontsRevision` matches); the worker then keeps its registrations. */
-    fonts: Uint8Array[];
+    fonts: YrsResidentFontRegistration[];
     /** Monotonic revision of the resident font set (bumped by register/clear). */
     fontsRevision: number;
     renderInputs: Array<{
@@ -758,12 +1016,16 @@ interface YrsSelectionContext {
     italic: YrsTriState;
     underline: YrsTriState;
     strike: YrsTriState;
+    superscript: YrsTriState;
+    subscript: YrsTriState;
     /** Uniform ASCII font family, or `null` when absent/mixed. */
     fontFamily: string | null;
     /** Uniform font size in half-points (the OOXML `w:sz` unit). */
     fontSize: number | null;
     /** Uniform RGB hex or theme-color name, or `null` when absent/mixed. */
     color: string | null;
+    /** Uniform highlight name (`yellow`, …) or unmapped hex, or `null` when absent/mixed. */
+    highlight: string | null;
     /** Paragraph containing the range start. */
     paraId: string;
     styleId: string | null;
@@ -858,6 +1120,8 @@ interface YrsTableReceipt {
     columns: number;
     createdStoryIds: string[];
     deletedStoryIds: string[];
+    /** Existing stories whose content changed: the table's story, plus a merge's surviving cell. */
+    changedStoryIds: string[];
     newParaIds: string[];
     deletedTable: boolean;
     revisionIds: string[];
@@ -882,6 +1146,21 @@ interface YrsCellBorder {
  * @public
  */
 type YrsCellBorders = Partial<Record<'top' | 'bottom' | 'left' | 'right' | 'insideH' | 'insideV', YrsCellBorder | null>>;
+/** Undo grouping for tracked local transactions. */
+type YrsUndoCaptureMode = 'auto' | 'manual';
+/** Outcome of a target-resolving helper edit. @internal */
+type YrsTargetEditResult = {
+    ok: true;
+    version: string;
+} | DocxEditRefusal;
+/** Accepted-view texts around a selection; U+FFFC stands for each inline atom. @internal */
+interface YrsSelectionText {
+    paraId: string;
+    selectedText: string;
+    paragraphText: string;
+    before: string;
+    after: string;
+}
 /**
  * One live replica of the yrs editing model. Thin typed wrapper over the
  * wasm `EditSession` — no editing logic on this side of the boundary.
@@ -891,6 +1170,12 @@ interface YrsSession extends CollaborationReplica {
     readonly clientId: number;
     /** Register raw sfnt bytes in the session's measurement/display font store. */
     registerFont(bytes: Uint8Array): number;
+    /**
+     * Register a measurement view of `base` carrying the vertical metrics Word
+     * measures `family` with, for a face the host substituted; `base` when the
+     * engine knows no metrics for the family.
+     */
+    registerSubstituteFont(base: number, family: string): number;
     /** Clear the session's registered measurement/display fonts. */
     clearFonts(): void;
     /** Measure one paragraph through the session's resident text engine. */
@@ -946,13 +1231,26 @@ interface YrsSession extends CollaborationReplica {
     outlineGlyphJson(fontId: number, glyphId: number): string;
     /** Hydrates from an encoded yrs v1 update (typically a peer's {@link encodeState} output). */
     loadState(update: Uint8Array): void;
-    /** Parses a DOCX, seeds its stories, and returns thin host metadata. */
-    seedFromDocx(bytes: Uint8Array): YrsDocxHost;
-    /** Parses a DOCX and optionally seeds its stories. */
-    openDocx(bytes: Uint8Array, seedStories: boolean): YrsDocxHost;
+    /** Parses a DOCX, seeds its stories, and returns thin host metadata; see {@link openDocx}. */
+    seedFromDocx(bytes: Uint8Array, options?: YrsOpeningOptions): YrsDocxHost;
+    /**
+     * Parses a DOCX and optionally seeds its stories. Seeding starts a new
+     * opening, so its session anchors never resolve in another opening, even
+     * one seeded alike by the same client; see {@link beginOpening}.
+     */
+    openDocx(bytes: Uint8Array, seedStories: boolean, options?: YrsOpeningOptions): YrsDocxHost;
+    /**
+     * Starts a new opening of the document: its generation, replicated to
+     * every replica, becomes part of every session anchor. Every seeding entry
+     * point calls it; call it after building a document another way.
+     */
+    beginOpening(generation?: string): void;
     /** Materializes the retained canonical package for compatibility APIs. */
     materializeDocx(): Document | null;
-    /** Seeds stories and returns paragraph IDs in document order. */
+    /**
+     * Seeds stories and returns paragraph IDs in document order. Seeding a
+     * document that has no opening yet starts one; see {@link beginOpening}.
+     */
     loadStories(stories: readonly YrsStorySeed[]): Record<string, string[]>;
     /** Full document state as one yrs v1 update (Yjs wire format). */
     encodeState(): Uint8Array;
@@ -987,6 +1285,12 @@ interface YrsSession extends CollaborationReplica {
     cellSelection(): YrsTableRange | null;
     /** Begin local-origin undo capture once import/seeding has completed. */
     beginUndoCapture(): void;
+    /** Separates subsequent local edits from the current undo step; safe before capture starts. */
+    addUndoBoundary(): void;
+    /** Changes grouping policy, closing the current group while retaining history. */
+    setUndoCaptureMode(mode: YrsUndoCaptureMode): void;
+    /** Current grouping policy; defaults to auto. */
+    undoCaptureMode(): YrsUndoCaptureMode;
     /** Stories changed by the latest undo or redo, sorted. */
     historyStories(): string[];
     /** Undo/redo only local-origin direct operations (never remote/system transactions). */
@@ -1048,7 +1352,8 @@ interface YrsSession extends CollaborationReplica {
     mergeParagraphs(story: string, paraId: string, suggesting?: YrsAuthor): YrsRevisionReceipt;
     /**
      * Toggles one run mark across a range: removes it when every unit already
-     * carries it, otherwise adds it.
+     * carries it, otherwise adds it. Adding superscript clears subscript and
+     * vice versa.
      */
     toggleMark(range: YrsStoryRange, mark: YrsRunMark): void;
     /** Applies set-valued direct formatting; omitted fields are kept and `null` fields clear. */
@@ -1063,21 +1368,33 @@ interface YrsSession extends CollaborationReplica {
     setParagraphAttrs(range: YrsStoryRange, attrs: YrsParagraphAttrs, suggesting?: YrsAuthor): void;
     /** Inserts one inline image embed, optionally as a tracked insertion. */
     insertImage(at: YrsLoc, image: Readonly<Record<string, unknown>>, suggesting?: YrsAuthor): YrsRevisionReceipt;
-    /** Sets the authored value on a content-control embed addressed by stable payload id. */
+    /**
+     * Sets the value of a content-control embed addressed by stable payload id. A string fills a
+     * text control's content as one version-checked step and throws when the fill is refused.
+     */
     setContentControlValue(embedId: string, value: YrsContentControlValue): void;
-    /** Sets a content-control value at a paragraph-keyed embed position. */
+    /** {@link setContentControlValue} for the embed at a paragraph-keyed position. */
     setContentControlValueAt(at: YrsLoc, value: YrsContentControlValue): void;
-    /** Removes the authored value from a content-control embed. */
+    /**
+     * Removes an authored value from a content-control embed. It never erases a text control's
+     * text: fill it with `''` for that.
+     */
     clearContentControlValue(embedId: string): void;
     /** Commits image size/wrapping/position fields in one transaction. */
     setImageGeometry(embedId: string, geometry: YrsImageGeometry): void;
+    /** Commits image geometry at a paragraph-keyed position; reaches images that share an id. */
+    setImageGeometryAt(at: YrsLoc, geometry: YrsImageGeometry): void;
     /** Inserts a native page-break embed at a paragraph-keyed location. */
     insertPageBreak(at: YrsLoc): void;
     /** Inserts a native section-break embed at a paragraph-keyed location. */
     insertSectionBreak(at: YrsLoc, type: 'nextPage' | 'continuous' | 'oddPage' | 'evenPage'): void;
     /** Inserts a typed watermark embed at a paragraph-keyed location. */
     insertWatermark(at: YrsLoc, watermark: YrsWatermark): void;
-    /** Applies raw story operations in one transaction. */
+    /**
+     * Applies raw story operations in one transaction, then repairs any
+     * paragraph identity a pilcrow they insert or re-key duplicates and
+     * promotes an editor-only paragraph they author into.
+     */
     applyRawOps(story: string, ops: readonly YrsRawOp[]): void;
     /** Applies seed raw operations with deterministic item ordering. */
     applySeedRawOps(story: string, ops: readonly YrsRawOp[]): void;
@@ -1085,6 +1402,8 @@ interface YrsSession extends CollaborationReplica {
     setParagraphAttr(paraId: string, key: string, value: unknown): void;
     /** Adds a sticky-anchored comment over one or more ranges. */
     addComment(ranges: readonly YrsStoryRange[], author: string, date: string, body: unknown): YrsCommentReceipt;
+    /** Reanchors an existing comment with non-empty ranges; preserves metadata and joins local undo capture. */
+    setCommentRanges(commentId: string, ranges: readonly YrsStoryRange[]): void;
     /**
      * Accepts tracked changes: pending insertions become plain content,
      * pending deletions are carried out; a `pPrIns` paragraph mark clears (the
@@ -1105,6 +1424,8 @@ interface YrsSession extends CollaborationReplica {
     listRevisions(): YrsRevisionInfo[];
     /** Current offsets of a comment's sticky anchors. Throws when an anchor no longer resolves. */
     resolveComment(commentId: string): YrsResolvedCommentAnchor[];
+    /** Every comment the session holds, sorted by id. @internal */
+    listComments(): YrsCommentInfo[];
     /** Story ids in the document, sorted. */
     storyIds(): string[];
     /** Story length in UTF-16 units (every embed, pilcrows included, counts 1). */
@@ -1115,12 +1436,119 @@ interface YrsSession extends CollaborationReplica {
     yrsBlocksForStory(story: string, env?: YrsRenderEnv): unknown[];
     /** Paragraph snapshots in document order. */
     paragraphs(story: string): YrsParagraph[];
+    /** Literal search in document order. */
+    searchText(query: string, options?: YrsTextSearchOptions): YrsTextMatch[];
     /** Paragraph ids and inline-unit lengths, resolved in one Rust story traversal. */
     paragraphSpans(story: string): YrsParagraphLength[];
     /** The raw formatted-segment view (the render bridge's input). */
     storySegments(story: string): YrsStorySegment[];
     /** A paragraph's story span (start unit, pilcrow index). */
     locateParagraph(story: string, paraId: string): YrsParagraphSpan;
+    /**
+     * Session, persisted and source anchors of every paragraph, including the
+     * source package's paragraphs outside the stories, and the Word paragraph ID
+     * each saves with. Reads only.
+     */
+    paragraphIdentities(): DocxParagraphIdentitySnapshot;
+    /**
+     * Gives every paragraph that saves without a Word paragraph ID a fresh one,
+     * editor-only paragraphs excepted, and repairs duplicates, so persisted
+     * anchors survive save and reopen. Source IDs and saved claims keep their
+     * IDs over unsaved claims and copies. A replicated change outside undo
+     * history that later saves keep; a refusal changes nothing.
+     */
+    persistParagraphIds(): DocxParagraphIdentityReceipt;
+    /** Resolves an anchor to the paragraph that currently holds it. Reads only. */
+    resolveParagraphAnchor(anchor: DocxParagraphAnchor): DocxParagraphAnchorResult;
+    /** The Word paragraph ID each paragraph of a story saves with, in pilcrow order. @internal */
+    storyParagraphIds(story: string): Array<string | null>;
+    /** The paragraph IDs a save of the session applies. @internal */
+    paragraphSavePlan(): DocxParagraphSavePlan;
+    /**
+     * Publishes the `[owner, paraId]` pairs a save captured and returns those
+     * whose binding changed since. @internal
+     */
+    recordSavedParagraphIds(saved: ReadonlyArray<readonly [string, string]>): Array<[string, string]>;
+    /**
+     * The Word paragraph IDs a DOCX package holds, by part URI, in document
+     * order and upper case. Reads only. @internal
+     */
+    writtenParagraphIds(bytes: Uint8Array): Record<string, string[]>;
+    /**
+     * The session-scoped version token. It changes on every committed change, local or remote,
+     * and when the document is replaced; compare tokens only within this session.
+     */
+    version(): string;
+    /** Paragraph texts in one view, with the version they were read at. */
+    readParagraphs(request: DocxReadParagraphsRequest): DocxReadParagraphsResult;
+    /** Exact, case-sensitive, paragraph-local search; overlapping matches count separately. */
+    findText(request: DocxFindTextRequest): DocxFindTextResult;
+    /** Resolves and checks an edit batch without changing anything or reserving ids. */
+    validateEdits(request: DocxEditRequest): DocxValidationResult;
+    /**
+     * Applies every step or none, resolving all targets against `expectVersion`. Policy
+     * failures are returned; malformed requests throw.
+     */
+    applyEdits(request: DocxEditRequest): DocxEditResult;
+    /** Resolves a text target and formats it in one call. @internal */
+    formatTextTarget(target: DocxTextTarget, delta: YrsInlineFormatDelta): YrsTargetEditResult;
+    /** Resolves a text target and anchors side-map comment `id` over it in one call. @internal */
+    commentTextTarget(target: DocxTextTarget, comment: {
+        id: string;
+        author: string;
+        date: string;
+        body: unknown;
+    }): YrsTargetEditResult;
+    /** Accepted-view texts around a paragraph-keyed selection. @internal */
+    selectionText(range: YrsStoryRange): YrsSelectionText;
+    /**
+     * Exports the committed document as read-only structured content with the version it was read
+     * at; anchors resolve against that version. Nothing is committed, flushed or published.
+     * Unusable options are refused; malformed ones throw.
+     */
+    exportStructured(options: DocxExportOptions): DocxExportResult<DocxStructuredContent>;
+    /** {@link exportStructured} rendered as Markdown from the same read. */
+    exportMarkdown(options: DocxExportOptions): DocxExportResult<DocxMarkdownContent>;
+    /**
+     * {@link exportStructured} with the page map of the region layout this session retains. The
+     * layout must have lowered the current version from this session's stories with section,
+     * settings and note metadata that describe it, and measured every font the document uses
+     * with the fonts registered now; this call lays nothing out, flushes nothing and loads no
+     * font, and refuses a stale or incomplete layout.
+     */
+    exportStructuredWithPages(options: DocxPageExportOptions): DocxExportResult<DocxPagedStructuredContent<DocxLayoutMap>>;
+    /**
+     * {@link exportStructuredWithPages} for an editor: `currentRequest` is the region layout
+     * request it would lay the document out with now, and the retained layout must have used the
+     * same fonts, measurement defaults, render environment and pagination options. @internal
+     */
+    exportStructuredWithPagesFor(options: DocxPageExportOptions, currentRequest: string): DocxExportResult<DocxPagedStructuredContent<DocxLayoutMap>>;
+    /**
+     * Lays this private session out with `fonts` alone, in a measurement font store of its own,
+     * and exports it with snapshot anchors and a snapshot map. `fonts` holds the font files back
+     * to back and `fontLengths` their lengths; `request`'s font chains name them by index. Throws
+     * for a font the engine rejects. @internal
+     */
+    exportSnapshotWithPrivateFonts(fonts: Uint8Array, fontLengths: Uint32Array, request: string, options: DocxPageExportOptions): {
+        ok: true;
+        content: DocxPagedStructuredContent<DocxSnapshotLayoutMap>;
+    } | {
+        ok: false;
+        failure: DocxExportFailure;
+    };
+    /**
+     * The heading paragraphs of `story` in document order, classified as the structured export
+     * classifies them. Throws for an unknown story.
+     */
+    headings(story: string): DocxParagraphHeading[];
+    /**
+     * The content controls of the committed document with the version they were read at; control
+     * ids and anchors resolve against that version. Nothing is committed, flushed or published.
+     * Unusable options are refused; malformed ones throw.
+     */
+    listContentControls(options?: DocxContentControlsOptions): DocxContentControlsResult;
+    /** The controls {@link listContentControls} lists that match `query` exactly; none or several. */
+    findContentControls(query: DocxContentControlQuery, options?: DocxContentControlsOptions): DocxContentControlsResult;
     /** Drops the observer and frees the wasm-side replica. Idempotent. */
     destroy(): void;
 }
@@ -1139,4 +1567,4 @@ interface CreateYrsSessionOptions {
  */
 declare function createYrsSession(options?: CreateYrsSessionOptions): Promise<YrsSession>;
 
-export { type YrsParagraphSpan as $, type ResidentEngineWorkerFrame as A, ResidentWorkerFailureError as B, type CollaborationReplica as C, type YrsAuthor as D, type YrsCellBorder as E, type YrsCellBorders as F, type YrsCellLoc as G, type YrsChangeTarget as H, type YrsCommentReceipt as I, type YrsContentControlValue as J, type YrsDocxHost as K, type YrsEngineApplyProfile as L, type YrsHyperlinkAttrs as M, type YrsImageGeometry as N, type YrsInlineFormatDelta as O, type YrsInputParagraphSeed as P, type YrsInputParagraphSpan as Q, type ResidentCaretPaintStyle as R, type YrsInputPositionMap as S, type YrsNumberingProperties as T, type YrsParaOffset as U, type YrsParagraph as V, type YrsParagraphAttrs as W, type YrsParagraphLength as X, type YrsSession as Y, type YrsParagraphReceipt as Z, type YrsParagraphSeed as _, type YrsRenderEnv as a, type YrsParagraphTabStop as a0, type YrsRawOp as a1, type YrsResidentCaretRect as a2, type YrsResidentCaretSnapshot as a3, type YrsResidentWorkerSnapshot as a4, type YrsResidentWorkerSyncOptions as a5, type YrsResolveReceipt as a6, type YrsResolvedCommentAnchor as a7, type YrsRevisionReceipt as a8, type YrsRunMark as a9, type YrsSelectionContext as aa, type YrsSplitReceipt as ab, type YrsStickyPosition as ac, type YrsStoryRange as ad, type YrsStorySeed as ae, type YrsStorySegment as af, type YrsTableLoc as ag, type YrsTableRange as ah, type YrsTableReceipt as ai, type YrsTextColor as aj, type YrsTriState as ak, type YrsWatermark as al, canUseResidentEngineWorker as am, compareYrsLocs as an, createYrsInputPositionMap as ao, createYrsSession as ap, displayPositionToYrsLoc as aq, documentToYrs as ar, residentCaretDeviceRect as as, residentCaretSnapshotForFrame as at, sameYrsSelection as au, yrsLocToDisplayPosition as av, yrsToDocument as aw, type CollaborationTransport as b, type CollaborationProviderOptions as c, type CollaborationStatus as d, type CollaborationPeer as e, type CollaborationCursor as f, type CollaborationPeerListener as g, type CollaborationStatusListener as h, type CollaborationErrorListener as i, type YrsSelection as j, type CollaborationAwarenessState as k, CollaborationError as l, type CollaborationErrorCode as m, type CollaborationPresence as n, type CollaborationResolvedUser as o, type CollaborationStatusChange as p, type CollaborationTextInsertion as q, type CollaborationTransportEvent as r, type CollaborationUpdateOrigin as s, type CollaborationUser as t, type YrsLoc as u, type YrsRevisionInfo as v, type CreateYrsSessionOptions as w, type ResidentEngineOffscreenPage as x, type ResidentEngineWorkerApplyResult as y, ResidentEngineWorkerClient as z };
+export { type YrsCellLoc as $, type DocxParagraphIdOrigin as A, type DocxParagraphIdRefusal as B, type CollaborationReplica as C, type DocxParagraphAnchor as D, type DocxParagraphIdentity as E, type DocxParagraphIdentityReceipt as F, type DocxParagraphIdentitySnapshot as G, type DocxParagraphOrigin as H, type DocxParagraphRef as I, type DocxParagraphSavePlan as J, type DocxPersistedParagraphAnchor as K, type DocxSavedDocument as L, type DocxSavedParagraph as M, type DocxSessionParagraphAnchor as N, type DocxSessionSave as O, type DocxSourceParagraphAnchor as P, type DocxSourceStory as Q, type ResidentCaretPaintStyle as R, type ResidentEngineOffscreenPage as S, type ResidentEngineWorkerApplyResult as T, ResidentEngineWorkerClient as U, type ResidentEngineWorkerFrame as V, ResidentWorkerFailureError as W, type YrsAuthor as X, type YrsSession as Y, type YrsCellBorder as Z, type YrsCellBorders as _, type YrsRenderEnv as a, type YrsChangeTarget as a0, type YrsCommentInfo as a1, type YrsCommentReceipt as a2, type YrsContentControlValue as a3, type YrsDocxHost as a4, type YrsEngineApplyProfile as a5, type YrsHyperlinkAttrs as a6, type YrsImageGeometry as a7, type YrsInlineFormatDelta as a8, type YrsInputParagraphSeed as a9, type YrsStoryRange as aA, type YrsStorySeed as aB, type YrsStorySegment as aC, type YrsTableLoc as aD, type YrsTableRange as aE, type YrsTableReceipt as aF, type YrsTargetEditResult as aG, type YrsTextColor as aH, type YrsTextMatch as aI, type YrsTextSearchOptions as aJ, type YrsTriState as aK, type YrsUndoCaptureMode as aL, type YrsWatermark as aM, canUseResidentEngineWorker as aN, captureSessionSave as aO, compareYrsLocs as aP, createYrsInputPositionMap as aQ, createYrsSession as aR, displayPositionToYrsLoc as aS, documentToYrs as aT, residentCaretDeviceRect as aU, residentCaretSnapshotForFrame as aV, sameYrsSelection as aW, saveYrsDocx as aX, writeSessionSave as aY, yrsLocToDisplayPosition as aZ, yrsToDocument as a_, type YrsInputParagraphSpan as aa, type YrsInputPositionMap as ab, type YrsNumberingProperties as ac, type YrsOpeningOptions as ad, type YrsParaOffset as ae, type YrsParagraph as af, type YrsParagraphAttrs as ag, type YrsParagraphLength as ah, type YrsParagraphReceipt as ai, type YrsParagraphSeed as aj, type YrsParagraphSpan as ak, type YrsParagraphTabStop as al, type YrsRawOp as am, type YrsResidentCaretRect as an, type YrsResidentCaretSnapshot as ao, type YrsResidentFontRegistration as ap, type YrsResidentWorkerSnapshot as aq, type YrsResidentWorkerSyncOptions as ar, type YrsResolveReceipt as as, type YrsResolvedCommentAnchor as at, type YrsRevisionReceipt as au, type YrsRunMark as av, type YrsSelectionContext as aw, type YrsSelectionText as ax, type YrsSplitReceipt as ay, type YrsStickyPosition as az, type CollaborationTransport as b, type CollaborationProviderOptions as c, type CollaborationStatus as d, type CollaborationPeer as e, type CollaborationCursor as f, type CollaborationPeerListener as g, type CollaborationStatusListener as h, type CollaborationErrorListener as i, type YrsSelection as j, type CollaborationAwarenessState as k, CollaborationError as l, type CollaborationErrorCode as m, type CollaborationPresence as n, type CollaborationResolvedUser as o, type CollaborationStatusChange as p, type CollaborationTextInsertion as q, type CollaborationTransportEvent as r, type CollaborationUpdateOrigin as s, type CollaborationUser as t, type YrsLoc as u, type YrsRevisionInfo as v, type CreateYrsSessionOptions as w, type DocxParagraphAnchorResult as x, type DocxParagraphIdAssignment as y, type DocxParagraphIdDiagnostic as z };