@betteroffice/docx 0.3.0 → 0.4.0

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

@@ -1,7 +1,8 @@
 import { C as ColorValue } from './formatting-gqLFeJ9X.mjs';
-import { Document } from './types/document.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 { Document, CompatibilityFlags } from './types/document.mjs';
+import { a0 as DocxEditSuggestion, a1 as DocxEditFailure, a2 as DocxEditFailureCode, a3 as DocxReadParagraphsRequest, a4 as DocxReadParagraphsResult, a5 as DocxFindTextRequest, a6 as DocxFindTextResult, a7 as DocxEditRequest, a8 as DocxValidationResult, a9 as DocxEditResult, aa as DocxTextTarget, ab 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---0Dlmzo.mjs';
+import { R as RetainedFrame } from './frameDelta-ByU7HBuB.mjs';
+import { a as WasmModuleMemory } from './loadWasmAsset-Cr95TImt.mjs';
 import { R as RepackOptions } from './rezip-Bxiq4Z_R.mjs';
 
 type CollaborationUpdateOrigin = 'local' | 'remote';
@@ -241,6 +242,84 @@ type DocxParagraphAnchorResult = {
 /** The paragraph IDs a session save applies, as the package writer's `paragraphIds`. @internal */
 type DocxParagraphSavePlan = RustParagraphIds;
 
+/**
+ * Host proposals: tracked changes a host proposes by paragraph anchor and search, grouped by the
+ * host's proposal ids. A round resolves against one version and applies as one atomic batch
+ * outside undo history. Decisions only change how the proposals' revisions render: the
+ * revisions stay in the document, and the document version and history are untouched until the
+ * host withdraws the proposals.
+ */
+
+type DocxProposalState = 'proposed' | 'accepted' | 'rejected';
+/** Which non-overlapping matches of a search a proposal replaces; numbers count from 1. */
+type DocxOccurrence = 'first' | 'all' | number;
+/**
+ * One proposal. `replaceText` with `replaceWith: ''` deletes; with `search: ''` it fills a
+ * paragraph whose accepted text is empty (an inline atom counts as text), where the empty search
+ * matches once, at offset 0. `insertText` offsets are UTF-16 units of the paragraph's accepted
+ * text.
+ */
+type DocxProposalInput = {
+    id: string;
+    paragraph: DocxParagraphAnchor;
+    suggest: DocxEditSuggestion;
+} & ({
+    op: 'replaceText';
+    search: string;
+    replaceWith: string;
+    occurrence?: DocxOccurrence;
+} | {
+    op: 'insertText';
+    at: 'start' | 'end' | {
+        offset: number;
+    };
+    text: string;
+});
+interface DocxProposalRequest {
+    expectVersion: string;
+    proposals: readonly DocxProposalInput[];
+}
+interface DocxProposalRecord {
+    id: string;
+    state: DocxProposalState;
+    paragraph: DocxSessionParagraphAnchor;
+    revisionIds: readonly string[];
+    changed: boolean;
+}
+interface DocxProposalSnapshot {
+    version: string;
+    /** Increments whenever a decision changes. */
+    previewVersion: number;
+    proposals: readonly DocxProposalRecord[];
+}
+type DocxProposalFailure = Omit<DocxEditFailure, 'code'> & {
+    code: DocxEditFailureCode | 'stale-preview' | 'unknown-proposal' | 'proposal-id-conflict';
+    proposalId?: string;
+};
+type DocxProposalResult = {
+    ok: true;
+    snapshot: DocxProposalSnapshot;
+} | {
+    ok: false;
+    version: string;
+    failure: DocxProposalFailure;
+};
+/** Ids that name no proposal are ignored, so a retried withdrawal changes nothing. */
+interface DocxProposalWithdrawRequest {
+    expectVersion: string;
+    ids: readonly string[];
+}
+interface DocxProposalStateRequest {
+    expectVersion: string;
+    expectPreviewVersion: number;
+    changes: readonly {
+        id: string;
+        state: DocxProposalState;
+    }[];
+}
+/** The revision decisions a snapshot shows, for `YrsRenderEnv.revisionPreview`. */
+declare function proposalRevisionPreview(snapshot: DocxProposalSnapshot): Readonly<Record<string, 'accepted' | 'rejected'>> | undefined;
+
 /** One native paragraph in the yrs-backed display-position projection. */
 interface YrsInputParagraphSpan {
     paraId: string;
@@ -289,11 +368,49 @@ declare function residentCaretDeviceRect(rect: Pick<YrsResidentCaretRect, 'x' |
 declare function residentCaretSnapshotForFrame(snapshot: YrsResidentCaretSnapshot, frame: RetainedFrame): YrsResidentCaretSnapshot | null;
 
 type ResidentEngineWorkerRequest = {
+    id: number;
+    type: 'warm';
+} | {
     id: number;
     type: 'bootstrap';
     snapshot: YrsResidentWorkerSnapshot;
     extras: string;
     expectedFrameEpoch: number;
+    layoutExtras?: string;
+    /** Pages `[start, end)` a full build compiles; the rest stay unbuilt. */
+    displayWindow?: [number, number];
+    retainBuiltPages?: boolean;
+    /**
+     * Lay out only as much of the body as fills this many pages; a reply
+     * marked `layoutProvisional` is finished by `completeLayout`.
+     */
+    provisionalPages?: number;
+    /**
+     * The document replaces the one this worker showed, which the host
+     * hands over from: keep the attached page surfaces for its pages.
+     */
+    keepSurfaces?: boolean;
+    /** Lay out the document `open` seeded here, not the snapshot's state. */
+    opened?: boolean;
+    /** The most the worker's editing core may allocate at once. */
+    heapLimitBytes?: number;
+} | {
+    id: number;
+    type: 'open';
+    /** The DOCX package, parsed and seeded in a fresh session here. */
+    bytes: ArrayBuffer;
+    /** The package's SHA-256, when the caller already took it. */
+    digest?: string;
+    generation?: string;
+    /** The most the worker's editing core may allocate at once. */
+    heapLimitBytes?: number;
+} | {
+    id: number;
+    type: 'fontRequirements';
+    layoutInput: string;
+} | {
+    id: number;
+    type: 'encodeState';
 } | {
     id: number;
     type: 'sync';
@@ -301,12 +418,38 @@ type ResidentEngineWorkerRequest = {
     extras: string;
     expectedFrameEpoch: number;
     paintCaret: boolean;
+    /**
+     * Display extras without the header/footer payload. When present, the
+     * snapshot's layout is authoritative: the worker completes the extras
+     * from the layout it runs and returns that layout as `layoutJson`.
+     */
+    layoutExtras?: string;
+    displayWindow?: [number, number];
+    retainBuiltPages?: boolean;
+} | {
+    id: number;
+    type: 'buildPages';
+    pages: number[];
+    expectedFrameEpoch: number;
+    paintCaret: boolean;
+} | {
+    id: number;
+    type: 'completeLayout';
+    expectedFrameEpoch: number;
+    paintCaret: boolean;
+    /**
+     * Measure the rest this many body blocks a step to start with, letting
+     * requests that arrive meanwhile run between steps; absent, in one step.
+     */
+    sliceBlocks?: number;
 } | {
     id: number;
     type: 'buildFrame';
     extras: string;
     expectedFrameEpoch: number;
     paintCaret: boolean;
+    displayWindow?: [number, number];
+    retainBuiltPages?: boolean;
 } | {
     id: number;
     type: 'applyInput';
@@ -315,14 +458,19 @@ type ResidentEngineWorkerRequest = {
     expectedFrameEpoch: number;
     profile: boolean;
     paintCaret: boolean;
+    displayWindow?: [number, number];
+    retainBuiltPages?: boolean;
 } | {
     id: number;
     type: 'applyDelete';
     direction: 'backward' | 'forward';
+    count: number;
     selection: YrsSelection;
     expectedFrameEpoch: number;
     profile: boolean;
     paintCaret: boolean;
+    displayWindow?: [number, number];
+    retainBuiltPages?: boolean;
 } | {
     id: number;
     type: 'applyUpdate';
@@ -346,7 +494,7 @@ type ResidentEngineWorkerRequest = {
     id: number;
     type: 'destroy';
 };
-type ResidentEngineWorkerResponse = {
+type ResidentEngineWorkerResponse = ({
     id: number;
     ok: true;
     frame?: ArrayBuffer;
@@ -361,9 +509,21 @@ type ResidentEngineWorkerResponse = {
     replayMs?: number;
     replayedPages?: number;
     layoutRevision?: number;
+    /** Characters an applyDelete removed. */
+    deletedUnits?: number;
     /** The worker replica's yrs state vector after this operation, so the
      * next sync can ship a diff instead of the whole document state. */
     stateVector?: ArrayBuffer;
+    /** The region layout the worker ran, for a request carrying `layoutExtras`. */
+    layoutJson?: string;
+    /** `layoutJson` covers only the first pages of the body. */
+    layoutProvisional?: boolean;
+    /** An `open` reply: the opened package's host metadata JSON. */
+    hostJson?: string;
+    /** A `fontRequirements` reply. */
+    requirementsJson?: string;
+    /** An `encodeState` reply: the document state as one yrs v1 update. */
+    state?: ArrayBuffer;
 } | {
     id: number;
     ok: false;
@@ -371,6 +531,11 @@ type ResidentEngineWorkerResponse = {
     residentUnavailable?: boolean;
     /** A wasm trap poisoned the worker; it refuses every later request. */
     terminal?: boolean;
+    /** The trap followed an allocation the worker's memory could not satisfy. */
+    outOfMemory?: boolean;
+}) & {
+    /** The worker's wasm memories as the reply left. */
+    memory?: WasmModuleMemory[];
 };
 
 interface ResidentEngineWorkerFrame {
@@ -386,6 +551,42 @@ interface ResidentEngineWorkerFrame {
     replayMs: number;
     replayedPages: number;
     layoutRevision: number;
+    /** Characters an applyDelete removed. */
+    deletedUnits: number;
+    /** The region layout the worker ran, when the request handed it the layout. */
+    layoutJson?: string;
+    /** `layoutJson` covers only the first pages; `completeLayout` finishes it. */
+    layoutProvisional?: boolean;
+}
+/** A bootstrap/sync whose snapshot layout the worker runs as the only layout. */
+interface ResidentEngineWorkerLayoutOptions {
+    /** Display extras minus the header/footer payload the worker's layout supplies. */
+    layoutExtras?: string;
+    /** The host state vector the snapshot brings the worker to. */
+    stateVector?: Uint8Array;
+    /** Bootstrap only: lay out just the body's first pages before replying. */
+    provisionalPages?: number;
+    /** Bootstrap only: lay out the document {@link ResidentEngineWorkerClient.open} opened. */
+    opened?: boolean;
+    /** Bootstrap only: the epoch of the frame the host shows; the worker's frames follow it. */
+    frameEpoch?: number;
+    /**
+     * Bootstrap only: the most the worker's editing core may allocate at once.
+     * An allocation past it stops the worker with {@link ResidentWorkerOutOfMemoryError}.
+     */
+    heapLimitBytes?: number;
+}
+/** What an {@link ResidentEngineWorkerClient.open} seeded in the worker. */
+interface ResidentEngineWorkerOpened {
+    /** The package's host metadata JSON, for `decodeDocxHostJson`. */
+    hostJson: string;
+    /** The worker replica's state vector once seeded. */
+    stateVector: Uint8Array;
+}
+/** How a bootstrap or sync builds its frame. */
+interface ResidentEngineWorkerSnapshotOptions {
+    /** Pages `[start, end)` the frame builds; the rest stay unbuilt. */
+    displayWindow?: [number, number];
 }
 interface ResidentEngineOffscreenPage {
     pageId: string;
@@ -405,26 +606,78 @@ interface ResidentEngineWorkerPort {
 declare class ResidentEngineWorkerClient {
     private readonly worker;
     private readonly pending;
+    private watchdog;
     private nextId;
     private terminalError;
     private ready;
     private revision;
     private remoteVector;
     private appliedFontsRevision;
+    private bootstrapped;
+    /** Set once `open` is sent, with the heap limit it opened under. */
+    private openedHeapLimit;
+    private bootstraps;
+    /** Id of the last snapshot request sent; replies to earlier requests must
+     * not replace the state it recorded. */
+    private lastSnapshotId;
+    private keepSurfaces;
+    private lastMemory;
+    private answeredFrameEpoch;
+    private retainBuiltPages;
     constructor(worker?: ResidentEngineWorkerPort);
     isReady(): boolean;
+    /** @internal */
+    hasFailed(): boolean;
+    /** The worker's wasm memories as of its latest reply; null before one. */
+    memory(): WasmModuleMemory[] | null;
     layoutRevision(): number;
+    /** @internal The newest frame epoch a reply carried; 0 before any frame. */
+    answeredFrame(): number;
+    /** @internal */
+    setRetainBuiltPages(retain: boolean): void;
+    /** @internal Whether a frame request other than `buildPages` awaits its reply. */
+    frameRequestPending(): boolean;
     /** The worker replica's last reported yrs state vector (null before any). */
     remoteStateVector(): Uint8Array | null;
     /** The fonts revision this worker last applied (null before bootstrap). */
     syncedFontsRevision(): number | null;
-    bootstrap(snapshot: YrsResidentWorkerSnapshot, extras: string): Promise<ResidentEngineWorkerFrame>;
-    sync(snapshot: YrsResidentWorkerSnapshot, extras: string, expectedFrameEpoch: number, paintCaret?: boolean): Promise<ResidentEngineWorkerFrame>;
-    buildFrame(extras: string, expectedFrameEpoch: number, paintCaret?: boolean): Promise<ResidentEngineWorkerFrame>;
-    applyInput(text: string, selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean, paintCaret?: boolean): Promise<ResidentEngineWorkerApplyResult | {
+    /** A bootstrap was sent; later snapshots go as syncs queued behind it. */
+    bootstrapSent(): boolean;
+    /**
+     * Starts over with another document in the same worker: the next request
+     * is a bootstrap, which keeps the page surfaces already attached so the
+     * new document's pages paint where the old ones were.
+     */
+    rebootstrap(): void;
+    /**
+     * Parses and seeds a DOCX in the worker, which then holds the document:
+     * its first layout is a bootstrap with `opened`, and the main replica loads
+     * {@link encodeState}. A copy of `bytes` is transferred.
+     */
+    open(bytes: Uint8Array, options?: {
+        digest?: string;
+        generation?: string;
+        heapLimitBytes?: number;
+    }): Promise<ResidentEngineWorkerOpened>;
+    /** The font requirements of a region layout request, read from the opened document. */
+    fontRequirements(layoutInput: string): Promise<string>;
+    /** The worker's whole document state as one yrs v1 update. */
+    encodeState(): Promise<Uint8Array>;
+    warm(): Promise<void>;
+    bootstrap(snapshot: YrsResidentWorkerSnapshot, extras: string, options?: ResidentEngineWorkerLayoutOptions & ResidentEngineWorkerSnapshotOptions): Promise<ResidentEngineWorkerFrame>;
+    sync(snapshot: YrsResidentWorkerSnapshot, extras: string, expectedFrameEpoch: number, paintCaret?: boolean, options?: ResidentEngineWorkerLayoutOptions & ResidentEngineWorkerSnapshotOptions): Promise<ResidentEngineWorkerFrame>;
+    /**
+     * Lay out the rest of a provisional bootstrap layout: its frame and full
+     * layout, or null when a later snapshot already replaced it.
+     */
+    completeLayout(expectedFrameEpoch: number, paintCaret?: boolean, sliceBlocks?: number): Promise<ResidentEngineWorkerFrame | null>;
+    buildFrame(extras: string, expectedFrameEpoch: number, paintCaret?: boolean, displayWindow?: [number, number]): Promise<ResidentEngineWorkerFrame>;
+    /** Build unbuilt display pages; the reply frame carries them. */
+    buildPages(pages: number[], expectedFrameEpoch: number, paintCaret?: boolean): Promise<ResidentEngineWorkerFrame>;
+    applyInput(text: string, selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean, paintCaret?: boolean, displayWindow?: [number, number]): Promise<ResidentEngineWorkerApplyResult | {
         applied: false;
     }>;
-    applyDelete(direction: 'backward' | 'forward', selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean, paintCaret?: boolean): Promise<ResidentEngineWorkerApplyResult | {
+    applyDelete(direction: 'backward' | 'forward', selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean, paintCaret?: boolean, count?: number, displayWindow?: [number, number]): Promise<ResidentEngineWorkerApplyResult | {
         applied: false;
     }>;
     /** Drop the worker-painted caret line by re-presenting the caret page's
@@ -434,15 +687,46 @@ declare class ResidentEngineWorkerClient {
     attachCanvases(pages: ResidentEngineOffscreenPage[], activePageIds: string[], devicePixelRatio: number, zoom: number, caretStyle: ResidentCaretPaintStyle): Promise<void>;
     destroy(): void;
     private request;
+    /**
+     * Requests run in order, so once a snapshot is sent every later request
+     * finds its state and fonts in the worker: the next sync can diff against
+     * them before this one answers.
+     */
+    private recordSent;
+    /** Restarted by every message, so a queue of slow but answered requests never trips it. */
+    private armWatchdog;
+    private disarmWatchdog;
     /** Record a successfully applied bootstrap/sync payload's fonts revision.
      * The state vector is tracked centrally in `onmessage`. */
     private recordSync;
     private fail;
 }
+declare class ResidentWorkerUnavailableError extends Error {
+}
 /** The worker itself failed (crash, timeout, torn-down, corrupt reply). */
 declare class ResidentWorkerFailureError extends Error {
 }
+/** The worker trapped because its wasm memory could not grow any further. */
+declare class ResidentWorkerOutOfMemoryError extends ResidentWorkerUnavailableError {
+    /** The worker's wasm memories when it trapped. */
+    readonly memory: WasmModuleMemory[];
+    constructor(message: string, 
+    /** The worker's wasm memories when it trapped. */
+    memory: WasmModuleMemory[]);
+}
 declare function canUseResidentEngineWorker(): boolean;
+/** @internal */
+declare function preloadResidentEngineWorker(): Promise<void>;
+/** @internal */
+declare function retainPreloadedResidentEngineWorker(): () => void;
+/** @internal */
+declare function takePreloadedResidentEngineWorker(): ResidentEngineWorkerClient | null;
+
+/**
+ * Preload the editing engine and one spare resident worker. Opt-in.
+ * @experimental
+ */
+declare function preloadDocxEngine(): Promise<void>;
 
 /** Direct Document-to-yrs load projection. */
 
@@ -534,6 +818,13 @@ declare function saveYrsDocx(session: YrsSession, options?: RepackOptions): Prom
 interface YrsDocxHost {
     document: Document;
     referencedFonts: string[];
+    /**
+     * The `referencedFonts` a document seeded from its package names only for
+     * East Asian or complex-script text it does not contain, so no text is
+     * measured or drawn with them. Empty when its stories were not seeded; a
+     * preview's cover only its own first pages.
+     */
+    unusedScriptFonts?: string[];
     embeddedFonts: Map<string, ArrayBuffer>;
     fontTableRelationshipsXml?: string;
 }
@@ -651,7 +942,23 @@ interface YrsOpeningOptions {
      * as one session. Each opening mints a fresh one by default.
      */
     generation?: string;
+    /**
+     * Seeds images as `media:{n}` tokens naming their part of the package,
+     * instead of `data:` URLs, keeping them out of the document state. Only a
+     * replica opened from the same package on a version that reads tokens
+     * shows them, so every client of a shared room must be one. Off by default.
+     */
+    mediaTokens?: boolean;
 }
+/**
+ * A copy of `bytes` whose SHA-256 the platform takes off the calling thread,
+ * where it has Web Crypto. Opening that copy unchanged skips hashing the
+ * package on the calling thread; any other bytes open as before.
+ * @internal
+ */
+declare function prepareDocxBytes(bytes: Uint8Array): Promise<Uint8Array>;
+/** The SHA-256 {@link prepareDocxBytes} took of `bytes`, if it took one. @internal */
+declare function preparedDocxDigest(bytes: Uint8Array): string | undefined;
 /** Snapshot of one paragraph from {@link YrsSession.paragraphs}. */
 interface YrsParagraph {
     /** Session key; not the paragraph's Word `w14:paraId`. */
@@ -821,6 +1128,10 @@ interface YrsParagraphReceipt {
 interface YrsRevisionReceipt {
     revisionId: string | null;
 }
+/** Where the replacement text landed; after the struck-out text when suggesting. */
+interface YrsReplaceReceipt extends YrsRevisionReceipt {
+    range?: YrsStoryRange;
+}
 /**
  * Receipt of {@link YrsSession.splitParagraph}. The first half keeps the
  * original paraId and the second half is re-minted; suggesting
@@ -876,6 +1187,7 @@ type YrsRawOp = {
 };
 /** Host context for {@link YrsSession.yrsBlocksForStory} (theme + list numbering). */
 interface YrsRenderEnv {
+    compatibilityFlags?: Partial<CompatibilityFlags>;
     tocStyleIds?: string[];
     paragraphSpacingLinePx?: number;
     /** Section document-grid snap pitch in px (w:docGrid). The engine derives this from sections; hosts may omit it. */
@@ -891,6 +1203,13 @@ interface YrsRenderEnv {
     numericIds?: Record<string, number>;
     /** Include hidden text in visible layout without changing the document. */
     showHiddenText?: boolean;
+    /** Revision id → decision shown in layout; unlisted revisions render as tracked changes. */
+    revisionPreview?: Readonly<Record<string, 'accepted' | 'rejected'>>;
+    /**
+     * Lay the opened package's images out as `media:{n}` tokens, which a
+     * resolver given the session's `mediaSource` reads. @internal
+     */
+    mediaTokens?: boolean;
 }
 /** Receipt of {@link YrsSession.addComment}. */
 interface YrsCommentReceipt {
@@ -939,6 +1258,13 @@ interface YrsResidentCaretSnapshot {
     selection?: YrsSelection | null;
 }
 declare function sameYrsSelection(left: YrsSelection | null, right: YrsSelection | null): boolean;
+/** How far a region layout begun with {@link YrsSession.beginRegionLayout} has come. */
+interface YrsRegionLayoutProgress {
+    measuredBlocks: number;
+    bodyBlocks: number;
+    /** The retained region layout reply, once the pass is complete. */
+    layoutJson?: string;
+}
 /** Opt-in internal stage timings for one resident engine input. @internal */
 interface YrsEngineApplyProfile {
     selectionMs: number;
@@ -990,6 +1316,10 @@ interface YrsResidentWorkerSnapshot {
     layoutInput: string;
     layoutWithRegions: boolean;
     layoutRevision: number;
+    /** The document is a preview's cut of a package: its layouts render NUMPAGES empty. */
+    partialDocument?: boolean;
+    /** Which seeded `data:` image sources lay out as `media:{n}` tokens. @internal */
+    mediaSources?: string;
 }
 /**
  * What the sync target already holds, so a snapshot can ship deltas instead
@@ -1165,6 +1495,11 @@ interface YrsSelectionText {
  * One live replica of the yrs editing model. Thin typed wrapper over the
  * wasm `EditSession` — no editing logic on this side of the boundary.
  */
+/** An embedded image's bytes, as its `media:{n}` source displays them. */
+interface YrsMediaSource {
+    bytes: Uint8Array;
+    mimeType: string;
+}
 interface YrsSession extends CollaborationReplica {
     /** The yrs client id this replica writes with. */
     readonly clientId: number;
@@ -1189,25 +1524,59 @@ interface YrsSession extends CollaborationReplica {
     /** Same pass, but the reply omits the measured arena (fetch it on demand
      * through {@link YrsSession.retainedKernelInputsJson}). */
     layoutDocumentWithRegionsRetainedJson(input: string): string;
+    /**
+     * {@link YrsSession.layoutDocumentWithRegionsRetainedJson} a step at a time:
+     * this lowers the body, and each {@link YrsSession.resumeRegionLayout}
+     * measures up to `blocks` more body blocks. `layoutJson` arrives with the
+     * step that completes the pass, equal to the one-call reply. A document
+     * change, a font registration or another layout in between abandons the
+     * pass, and resuming it then throws.
+     */
+    beginRegionLayout(input: string): YrsRegionLayoutProgress;
+    resumeRegionLayout(blocks: number): YrsRegionLayoutProgress;
     /** Retained `{ measured, options }` for the main-thread display fallback. */
     retainedKernelInputsJson(expectedLayoutRevision: number): string;
+    /**
+     * Record region layout `input` as the resident layout without running it
+     * here: a resident worker replica runs it, and snapshots carry it there.
+     * Returns the new layout revision. @internal
+     */
+    adoptResidentWorkerLayout?(input: string): number;
+    /** The current resident layout ran only in a worker replica. @internal */
+    residentLayoutInWorker?(): boolean;
     /** Build display primitives against the session's resident font store. */
     buildDisplayListJson(input: string): string;
     /** Build a binary FrameDelta v1 against the last host-applied frame. */
     buildDisplayListFrame(input: string, expectedFrameEpoch: number): Uint8Array;
+    /**
+     * Limit full display builds to pages `start..end` plus the pages already
+     * built; the rest stay unbuilt placeholders carrying their geometry. @internal
+     */
+    setDisplayWindow(start: number, end: number): void;
+    /** Keep every previously built page while windowed builds are on. @internal */
+    setDisplayRetainBuiltPages(retain: boolean): void;
+    /** Build the listed unbuilt pages into a FrameDelta v1. @internal */
+    buildDisplayPagesFrame(pages: readonly number[], expectedFrameEpoch: number): Uint8Array;
+    /** Make the next frame a full one, for a host taking over from another engine; no-op once destroyed. */
+    resetFrameBase(): void;
     /** Caret geometry from the current resident display frame. */
     residentCaretSnapshot(): YrsResidentCaretSnapshot;
     /** Apply a collapsed plain-text insertion and return its resident FrameDelta. */
     applyInput(text: string, expectedFrameEpoch: number): Uint8Array;
-    /** Apply a collapsed character deletion/paragraph merge and return its resident FrameDelta. */
-    applyDelete(direction: 'backward' | 'forward', expectedFrameEpoch: number): Uint8Array;
+    /**
+     * Apply up to `count` (default 1) collapsed character deletions/paragraph
+     * merges, lay out once, and return the resident FrameDelta.
+     */
+    applyDelete(direction: 'backward' | 'forward', expectedFrameEpoch: number, count?: number): Uint8Array;
+    /** Characters the last resident deletion removed; fewer than asked at a document boundary. */
+    residentDeletedUnits(): number;
     /** Instrumented apply used only by opt-in browser performance traces. */
     applyInputProfiled(text: string, expectedFrameEpoch: number): {
         frame: Uint8Array;
         profile: YrsEngineApplyProfile;
     };
     /** Instrumented deletion used only by opt-in browser performance traces. */
-    applyDeleteProfiled(direction: 'backward' | 'forward', expectedFrameEpoch: number): {
+    applyDeleteProfiled(direction: 'backward' | 'forward', expectedFrameEpoch: number, count?: number): {
         frame: Uint8Array;
         profile: YrsEngineApplyProfile;
     };
@@ -1239,14 +1608,51 @@ interface YrsSession extends CollaborationReplica {
      * one seeded alike by the same client; see {@link beginOpening}.
      */
     openDocx(bytes: Uint8Array, seedStories: boolean, options?: YrsOpeningOptions): YrsDocxHost;
+    /**
+     * Opens a DOCX for display only, from the body's first `blocks` blocks:
+     * enough to lay out its first pages with a prefix pass before the whole
+     * document is opened. The session cannot save. `null`, opening nothing,
+     * for a document with a float placed from outside the text or a section
+     * with columns, which no cut of the body lays out like the whole: open it
+     * with {@link openDocx}. @internal
+     */
+    openDocxPreview(bytes: Uint8Array, blocks: number): YrsDocxHost | null;
+    /** Opened by {@link openDocxPreview}: its document refuses every change. @internal */
+    isDisplayOnly(): boolean;
+    /**
+     * Marks whether the document is a preview's, as a replica of one is: its
+     * layouts render NUMPAGES empty. @internal
+     */
+    setPartialDocument(partial: boolean): void;
+    /**
+     * The region layout of only as much of the body as fills `pages` pages;
+     * a reply marked `provisional` covers a prefix. @internal
+     */
+    layoutDocumentWithRegionsPrefixRetainedJson(input: string, pages: number): string;
     /**
      * 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;
+    /** Unions seeded opaque sequence names into document state. @internal */
+    seedOpaqueSequences(names: readonly string[]): void;
     /** Materializes the retained canonical package for compatibility APIs. */
     materializeDocx(): Document | null;
+    /**
+     * The displayed bytes and media type of the package part a `media:{n}`
+     * image source names, or `null` for any other source or a destroyed session.
+     */
+    mediaSource(token: string): YrsMediaSource | null;
+    /** Changes on package opening and session destruction. */
+    mediaScope(): number;
+    /** The `data:` URL a token stands for, or `null` when unavailable or destroyed. */
+    mediaDataUrl(token: string): string | null;
+    /**
+     * Lays this replica's `data:` image sources out as the `media:{n}` tokens a
+     * snapshot's `mediaSources` names. @internal
+     */
+    loadMediaSources(json: string): void;
     /**
      * Seeds stories and returns paragraph IDs in document order. Seeding a
      * document that has no opening yet starts one; see {@link beginOpening}.
@@ -1342,7 +1748,7 @@ interface YrsSession extends CollaborationReplica {
      */
     deleteRange(range: YrsStoryRange, suggesting?: YrsAuthor): YrsRevisionReceipt;
     /** Replaces a range with text in one transaction (one shared revision when suggesting). */
-    replaceRange(range: YrsStoryRange, text: string, suggesting?: YrsAuthor): YrsRevisionReceipt;
+    replaceRange(range: YrsStoryRange, text: string, suggesting?: YrsAuthor): YrsReplaceReceipt;
     /**
      * Splits a paragraph by inserting one pilcrow. The FIRST half keeps the
      * original paraId; the SECOND half is re-minted (`secondParaId`).
@@ -1428,6 +1834,8 @@ interface YrsSession extends CollaborationReplica {
     listComments(): YrsCommentInfo[];
     /** Story ids in the document, sorted. */
     storyIds(): string[];
+    /** Whether the document has a story with this id, without listing them all. */
+    hasStory(story: string): boolean;
     /** Story length in UTF-16 units (every embed, pilcrows included, counts 1). */
     storyLength(story: string): number;
     /** Returns the story's canonical-stream checksum. */
@@ -1442,6 +1850,27 @@ interface YrsSession extends CollaborationReplica {
     paragraphSpans(story: string): YrsParagraphLength[];
     /** The raw formatted-segment view (the render bridge's input). */
     storySegments(story: string): YrsStorySegment[];
+    /**
+     * The current story revision and the sorted ids of the stories created,
+     * edited, or deleted after revision `since` (0 lists every story).
+     */
+    storiesChangedSince(since: number): {
+        revision: number;
+        stories: string[];
+    };
+    /**
+     * One digest per unit of {@link YrsSession.storySegments}, split after each
+     * pilcrow. Equal digests mean equal segments.
+     */
+    storySegmentUnitDigests(story: string): string[];
+    /** The segments of the listed units, each as {@link YrsSession.storySegments} gives them. */
+    storySegmentUnits(story: string, units: readonly number[]): YrsStorySegment[][];
+    /**
+     * The payload of the story's `tableIndex`-th table embed, as
+     * {@link YrsSession.storySegments} gives it, or null when there is no such
+     * table. Reads the one table rather than the whole story.
+     */
+    tablePayload(story: string, tableIndex: number): Record<string, unknown> | null;
     /** A paragraph's story span (start unit, pilcrow index). */
     locateParagraph(story: string, paraId: string): YrsParagraphSpan;
     /**
@@ -1501,6 +1930,28 @@ interface YrsSession extends CollaborationReplica {
     }): YrsTargetEditResult;
     /** Accepted-view texts around a paragraph-keyed selection. @internal */
     selectionText(range: YrsStoryRange): YrsSelectionText;
+    /**
+     * Proposes a round of tracked changes: every new proposal resolves against `expectVersion` and
+     * the round applies as one batch outside undo history, or nothing changes. A retried id with
+     * the same edit is a no-op; the same id with another edit refuses. Opening another document
+     * forgets every proposal.
+     */
+    proposeChanges(request: DocxProposalRequest): DocxProposalResult;
+    /**
+     * Sets how proposals render. Decisions change neither the document, its version nor undo
+     * history; each call that changes one increments `previewVersion`.
+     */
+    setProposalStates(request: DocxProposalStateRequest): DocxProposalResult;
+    /**
+     * Withdraws proposals, settling each as its decision previews it: accepted ones apply for good,
+     * rejected and undecided ones are removed. The settlement is one change against `expectVersion`
+     * outside undo history, so a later round resolves against the text the preview showed.
+     */
+    withdrawProposals(request: DocxProposalWithdrawRequest): DocxProposalResult;
+    /** The proposals in the order they were made. */
+    getProposals(): DocxProposalSnapshot;
+    /** Listens for new proposals, decisions and a forgotten registry. Returns the unsubscribe. */
+    onProposalChange(listener: (snapshot: DocxProposalSnapshot) => void): () => void;
     /**
      * 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.
@@ -1560,6 +2011,11 @@ interface CreateYrsSessionOptions {
      */
     clientId?: number;
 }
+/**
+ * Decodes the host metadata a resident worker's `open` replied with, for the
+ * package `source` it opened. @internal
+ */
+declare function decodeDocxHostJson(json: string, source: Uint8Array): YrsDocxHost;
 /**
  * Creates a yrs editing replica. The first call dynamically imports and
  * initializes the embedded docx-edit wasm (~440KB base64) — callers must
@@ -1567,4 +2023,4 @@ interface CreateYrsSessionOptions {
  */
 declare function createYrsSession(options?: CreateYrsSessionOptions): Promise<YrsSession>;
 
-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 };
+export { type DocxSourceStory as $, type DocxParagraphIdDiagnostic as A, type DocxParagraphIdOrigin as B, type CollaborationReplica as C, type DocxOccurrence as D, type DocxParagraphIdRefusal as E, type DocxParagraphIdentity as F, type DocxParagraphIdentityReceipt as G, type DocxParagraphIdentitySnapshot as H, type DocxParagraphOrigin as I, type DocxParagraphRef as J, type DocxParagraphSavePlan as K, type DocxPersistedParagraphAnchor as L, type DocxProposalFailure as M, type DocxProposalInput as N, type DocxProposalRecord as O, type DocxProposalRequest as P, type DocxProposalResult as Q, type DocxProposalSnapshot as R, type DocxProposalState as S, type DocxProposalStateRequest as T, type DocxProposalWithdrawRequest as U, type DocxSavedDocument as V, type DocxSavedParagraph as W, type DocxSessionParagraphAnchor as X, type YrsSession as Y, type DocxSessionSave as Z, type DocxSourceParagraphAnchor as _, type YrsRenderEnv as a, type YrsWatermark as a$, type ResidentCaretPaintStyle as a0, type ResidentEngineOffscreenPage as a1, type ResidentEngineWorkerApplyResult as a2, ResidentEngineWorkerClient as a3, type ResidentEngineWorkerFrame as a4, type ResidentEngineWorkerOpened as a5, ResidentWorkerFailureError as a6, ResidentWorkerOutOfMemoryError as a7, type YrsAuthor as a8, type YrsCellBorder as a9, type YrsRegionLayoutProgress as aA, type YrsReplaceReceipt as aB, type YrsResidentCaretRect as aC, type YrsResidentCaretSnapshot as aD, type YrsResidentFontRegistration as aE, type YrsResidentWorkerSnapshot as aF, type YrsResidentWorkerSyncOptions as aG, type YrsResolveReceipt as aH, type YrsResolvedCommentAnchor as aI, type YrsRevisionReceipt as aJ, type YrsRunMark as aK, type YrsSelectionContext as aL, type YrsSelectionText as aM, type YrsSplitReceipt as aN, type YrsStickyPosition as aO, type YrsStoryRange as aP, type YrsStorySeed as aQ, type YrsStorySegment as aR, type YrsTableLoc as aS, type YrsTableRange as aT, type YrsTableReceipt as aU, type YrsTargetEditResult as aV, type YrsTextColor as aW, type YrsTextMatch as aX, type YrsTextSearchOptions as aY, type YrsTriState as aZ, type YrsUndoCaptureMode as a_, type YrsCellBorders as aa, type YrsCellLoc as ab, type YrsChangeTarget as ac, type YrsCommentInfo as ad, type YrsCommentReceipt as ae, type YrsContentControlValue as af, type YrsDocxHost as ag, type YrsEngineApplyProfile as ah, type YrsHyperlinkAttrs as ai, type YrsImageGeometry as aj, type YrsInlineFormatDelta as ak, type YrsInputParagraphSeed as al, type YrsInputParagraphSpan as am, type YrsInputPositionMap as an, type YrsMediaSource as ao, type YrsNumberingProperties as ap, type YrsOpeningOptions as aq, type YrsParaOffset as ar, type YrsParagraph as as, type YrsParagraphAttrs as at, type YrsParagraphLength as au, type YrsParagraphReceipt as av, type YrsParagraphSeed as aw, type YrsParagraphSpan as ax, type YrsParagraphTabStop as ay, type YrsRawOp as az, type CollaborationTransport as b, canUseResidentEngineWorker as b0, captureSessionSave as b1, compareYrsLocs as b2, createYrsInputPositionMap as b3, createYrsSession as b4, decodeDocxHostJson as b5, displayPositionToYrsLoc as b6, documentToYrs as b7, preloadDocxEngine as b8, preloadResidentEngineWorker as b9, prepareDocxBytes as ba, preparedDocxDigest as bb, proposalRevisionPreview as bc, residentCaretDeviceRect as bd, residentCaretSnapshotForFrame as be, retainPreloadedResidentEngineWorker as bf, sameYrsSelection as bg, saveYrsDocx as bh, takePreloadedResidentEngineWorker as bi, writeSessionSave as bj, yrsLocToDisplayPosition as bk, yrsToDocument as bl, 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 DocxParagraphAnchor as x, type DocxParagraphAnchorResult as y, type DocxParagraphIdAssignment as z };