@betteroffice/docx 0.2.1 → 0.4.0

package/dist/index-CHy6_Yuo.d.mts

@@ -0,0 +1,2026 @@
+import { C as ColorValue } from './formatting-gqLFeJ9X.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';
+interface CollaborationReplica {
+    readonly clientId: number;
+    encodeStateVector(): Uint8Array;
+    encodeStateAsUpdate(remoteStateVector?: Uint8Array): Uint8Array;
+    applyUpdate(update: Uint8Array): unknown;
+    onUpdate(listener: (update: Uint8Array, origin: CollaborationUpdateOrigin) => void): () => void;
+}
+type CollaborationTransportEvent = {
+    type: 'open';
+} | {
+    type: 'message';
+    data: Uint8Array;
+} | {
+    type: 'close';
+    reason?: string;
+} | {
+    type: 'error';
+    error: unknown;
+} | {
+    type: 'drain';
+};
+interface CollaborationTransport {
+    /** Starts one connection attempt; transports may also reopen while still subscribed. */
+    connect(): void | Promise<void>;
+    disconnect(): void | Promise<void>;
+    /** Returns true only when the owned frame was accepted; false requires a later drain event. */
+    send(data: Uint8Array): boolean;
+    onEvent(listener: (event: CollaborationTransportEvent) => void): () => void;
+}
+type CollaborationStatus = 'disconnected' | 'connecting' | 'connected' | 'destroyed';
+interface CollaborationStatusChange {
+    status: CollaborationStatus;
+    synced: boolean;
+}
+type CollaborationErrorCode = 'backpressure' | 'protocol' | 'replica' | 'transport';
+declare class CollaborationError extends Error {
+    readonly code: CollaborationErrorCode;
+    readonly cause: unknown;
+    constructor(code: CollaborationErrorCode, message: string, cause?: unknown);
+}
+interface CollaborationProviderOptions {
+    maxFrameBytes?: number;
+    maxMessagesPerFrame?: number;
+    maxPendingBytes?: number;
+    user?: CollaborationUser;
+}
+interface CollaborationUser {
+    name: string;
+    color?: string;
+}
+interface CollaborationResolvedUser {
+    name: string;
+    color: string;
+}
+interface CollaborationCursor {
+    story: string;
+    anchor: Uint8Array;
+    head: Uint8Array;
+}
+interface CollaborationTextInsertion {
+    clientId: number;
+    story: string;
+    paraId: string;
+    endOffset: number;
+}
+interface CollaborationAwarenessState {
+    clientId: number;
+    clock: number;
+    user: CollaborationResolvedUser;
+    cursor: CollaborationCursor | null;
+}
+interface CollaborationPeer extends CollaborationAwarenessState {
+    lastSeenAt: number;
+    cursorMovedAt: number;
+    inferredCursor: CollaborationTextInsertion | null;
+}
+type CollaborationPeerListener = (peers: readonly CollaborationPeer[]) => void;
+interface CollaborationPresence {
+    readonly peers: readonly CollaborationPeer[];
+    setCursor(cursor: CollaborationCursor | null, broadcast?: boolean): void;
+    onPeers(listener: CollaborationPeerListener): () => void;
+}
+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;
+
+/**
+ * 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;
+    /** Number of UTF-16/inline units before the paragraph's pilcrow. */
+    length: number;
+    /** Block start emitted by the yrs display-position projection. */
+    displayStart: number;
+}
+/**
+ * Live converter between display-list positions and public yrs Locs.
+ *
+ * A native paragraph of length N occupies N+2 display positions (open token,
+ * content, close token), so this map can be rebuilt directly from the live yrs
+ * paragraph spans after every structural edit.
+ */
+interface YrsInputPositionMap {
+    story: string;
+    paragraphs: readonly YrsInputParagraphSpan[];
+}
+interface YrsInputParagraphSeed {
+    paraId: string;
+    length: number;
+}
+declare function createYrsInputPositionMap(story: string, seeds: readonly YrsInputParagraphSeed[]): YrsInputPositionMap;
+/** Convert a live yrs location to the position used by display-list geometry. */
+declare function yrsLocToDisplayPosition(map: YrsInputPositionMap, loc: YrsLoc): number;
+/** Convert a display-list hit position to a paragraph-keyed yrs location. */
+declare function displayPositionToYrsLoc(map: YrsInputPositionMap, position: number): YrsLoc | null;
+/** Compare two Locs in document order using one live map. */
+declare function compareYrsLocs(map: YrsInputPositionMap, a: YrsLoc, b: YrsLoc): number;
+
+/** Resolved styling for the worker-painted caret (the worker cannot read CSS vars). */
+interface ResidentCaretPaintStyle {
+    color: string;
+    /** CSS-px stroke width, matching the DOM caret's un-zoomed width. */
+    width: number;
+}
+/** Device-px caret rect: geometry scales by dpr*zoom, stroke width by dpr only
+ * (the DOM caret keeps its CSS-px width across zoom levels). */
+declare function residentCaretDeviceRect(rect: Pick<YrsResidentCaretRect, 'x' | 'y' | 'height'>, style: ResidentCaretPaintStyle, devicePixelRatio: number, zoom: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+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';
+    snapshot: YrsResidentWorkerSnapshot;
+    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';
+    text: string;
+    selection: YrsSelection;
+    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';
+    update: Uint8Array;
+    selection: YrsSelection | null;
+} | {
+    id: number;
+    type: 'attachCanvases';
+    pages: Array<{
+        pageId: string;
+        canvas: OffscreenCanvas;
+    }>;
+    activePageIds: string[];
+    devicePixelRatio: number;
+    zoom: number;
+    caretStyle: ResidentCaretPaintStyle;
+} | {
+    id: number;
+    type: 'eraseCaret';
+} | {
+    id: number;
+    type: 'destroy';
+};
+type ResidentEngineWorkerResponse = ({
+    id: number;
+    ok: true;
+    frame?: ArrayBuffer;
+    updates?: ArrayBuffer[];
+    engineMs?: number;
+    workerTotalMs?: number;
+    engineProfile?: YrsEngineApplyProfile;
+    caret?: YrsResidentCaretSnapshot;
+    selection?: YrsSelection | null;
+    /** The presented frame carries the worker-painted caret line. */
+    caretPainted?: boolean;
+    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;
+    error: string;
+    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 {
+    frame: Uint8Array;
+    updates: Uint8Array[];
+    engineMs: number;
+    workerTotalMs: number;
+    engineProfile?: YrsEngineApplyProfile;
+    caret: YrsResidentCaretSnapshot;
+    selection: YrsSelection | null;
+    /** The presented frame carries the worker-painted caret line. */
+    caretPainted: boolean;
+    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;
+    canvas: OffscreenCanvas;
+}
+interface ResidentEngineWorkerApplyResult extends ResidentEngineWorkerFrame {
+    applied: true;
+}
+interface ResidentEngineWorkerPort {
+    onmessage: ((event: MessageEvent<ResidentEngineWorkerResponse>) => void) | null;
+    onerror: ((event: ErrorEvent) => void) | null;
+    onmessageerror: ((event: MessageEvent) => void) | null;
+    postMessage(message: ResidentEngineWorkerRequest, transfer?: Transferable[]): void;
+    terminate(): void;
+}
+/** Dedicated-worker owner for resident input, pagination, and FrameDelta output. */
+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;
+    /** 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, count?: number, displayWindow?: [number, number]): Promise<ResidentEngineWorkerApplyResult | {
+        applied: false;
+    }>;
+    /** Drop the worker-painted caret line by re-presenting the caret page's
+     * retained raster. Fire-and-forget and idempotent. */
+    eraseCaret(): void;
+    invalidate(update: Uint8Array, selection: YrsSelection | null): void;
+    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. */
+
+/**
+ * Seeds every yrs-owned editable story directly from a parsed Document.
+ *
+ * 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. Seeding starts a new opening; see {@link YrsSession.beginOpening}.
+ *
+ * @public
+ */
+declare function documentToYrs(session: YrsSession, document: Document, options?: YrsOpeningOptions): void;
+
+/** yrs-to-OOXML save projection. */
+
+/**
+ * Rebuild all yrs-owned editable stories into the serializer-facing Document
+ * while preserving every package part the editor does not own.
+ */
+interface YrsToDocumentOptions {
+    /**
+     * Root stories to project. Omit to rebuild every editable story. A `body`
+     * 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;
+/**
+ * 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;
+    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;
+}
+/** Durable authorship metadata for one suggested (tracked-change) operation. */
+interface YrsAuthor {
+    name: string;
+    /** ISO timestamp supplied by the host so all peers share one clock policy. */
+    date: string;
+}
+/** One position: `(story, paraId, offset)` — offsets are UTF-16 units within the paragraph. */
+interface YrsLoc {
+    story: string;
+    paraId: string;
+    offset: number;
+}
+/** One binary Yrs position that transforms with collaborative edits. */
+interface YrsStickyPosition {
+    story: string;
+    encoded: Uint8Array;
+}
+/** A paragraph-addressed position without the story (used inside {@link YrsStoryRange}). */
+interface YrsParaOffset {
+    paraId: string;
+    offset: number;
+}
+/**
+ * A half-open range `[start, end)` inside one story. Ends may sit in
+ * different paragraphs; the boundary pilcrows are then part of the range
+ * (deleting such a range merges paragraphs).
+ */
+interface YrsStoryRange {
+    story: string;
+    start: YrsParaOffset;
+    end: YrsParaOffset;
+}
+/** One run-level mark for {@link YrsSession.toggleMark}. */
+type YrsRunMark = {
+    type: 'bold';
+} | {
+    type: 'italic';
+} | {
+    type: 'underline';
+} | {
+    type: 'superscript';
+} | {
+    type: 'subscript';
+} | {
+    type: 'fontFamily';
+    value: string;
+} | {
+    type: 'fontSize';
+    value: number;
+} | {
+    type: 'color';
+    value: string;
+};
+/** A direct text color written by {@link YrsSession.formatRange}. */
+type YrsTextColor = {
+    rgb: string;
+    themeColor?: never;
+} | {
+    rgb?: never;
+    themeColor: string;
+};
+/**
+ * Set-valued inline formatting for {@link YrsSession.formatRange}. Omitted
+ * fields are left unchanged; `null` clears a field. Boolean `false` also
+ * clears the corresponding mark.
+ */
+interface YrsInlineFormatDelta {
+    bold?: boolean | null;
+    italic?: boolean | null;
+    underline?: boolean | {
+        style?: string;
+        color?: string;
+    } | null;
+    strike?: boolean | {
+        double?: boolean;
+    } | null;
+    color?: YrsTextColor | null;
+    highlight?: string | null;
+    /** Font size in points; Rust writes both OOXML half-point size fields. */
+    fontSize?: number | null;
+    fontFamily?: {
+        ascii: string;
+        hAnsi?: string;
+    } | null;
+    /** Passive run properties not covered by the typed fields. `null` clears. */
+    other?: Readonly<Record<string, unknown | null>>;
+}
+interface YrsHyperlinkAttrs {
+    href: string;
+    tooltip?: string | null;
+    rId?: string | null;
+}
+/** Seed shape for {@link YrsSession.loadStories}. */
+interface YrsParagraphSeed {
+    /** Paragraph text; must not contain paragraph breaks. */
+    text: string;
+    /** Defaults to `"Normal"`. */
+    pStyle?: string;
+    /** Defaults to `"left"`. */
+    alignment?: string;
+}
+/** One story to seed via {@link YrsSession.loadStories}. */
+interface YrsStorySeed {
+    storyId: string;
+    /** 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;
+    /**
+     * 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`. */
+    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;
+    ilvl?: number;
+}
+/** One paragraph tab stop, measured in twips from the left margin. */
+interface YrsParagraphTabStop {
+    position: number;
+    alignment: 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear' | 'num';
+    leader?: 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
+}
+/**
+ * Tri-state properties for {@link YrsSession.setParagraphAttrs}. Omitted
+ * fields are kept and `null` clears. Numeric spacing and indents are OOXML
+ * twips/line-spacing units, never CSS pixels.
+ */
+interface YrsParagraphAttrs {
+    alignment?: 'left' | 'center' | 'right' | 'both' | 'distribute' | 'mediumKashida' | 'highKashida' | 'lowKashida' | 'thaiDistribute' | null;
+    lineSpacing?: number | null;
+    lineSpacingRule?: 'auto' | 'exact' | 'atLeast' | null;
+    spaceBefore?: number | null;
+    spaceAfter?: number | null;
+    indentLeft?: number | null;
+    indentRight?: number | null;
+    indentFirstLine?: number | null;
+    hangingIndent?: boolean | null;
+    bidi?: boolean | null;
+    tabs?: readonly YrsParagraphTabStop[] | null;
+    defaultTextFormatting?: Readonly<Record<string, unknown>> | null;
+    numPr?: YrsNumberingProperties | null;
+    numPrFromStyle?: YrsNumberingProperties | null;
+    listNumFmt?: string | null;
+    listIsBullet?: boolean | null;
+    listMarker?: string | null;
+    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;
+    listStartOverride?: number | null;
+    /** Passive pPr/model properties not covered by the typed fields. */
+    other?: Readonly<Record<string, unknown | null>>;
+}
+/**
+ * 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;
+} | {
+    kind: 'checkbox';
+    checked: boolean;
+} | {
+    kind: 'date';
+    date: string;
+} | string;
+/** Image geometry authored in OOXML EMUs plus wrapping/position metadata. */
+interface YrsImageGeometry {
+    widthEmu: number;
+    heightEmu: number;
+    wrap?: 'inline' | 'square' | 'tight' | 'through' | 'topAndBottom' | 'behind' | 'inFront';
+    hOffsetEmu?: number | null;
+    vOffsetEmu?: number | null;
+    distTopEmu?: number | null;
+    distBottomEmu?: number | null;
+    distLeftEmu?: number | null;
+    distRightEmu?: number | null;
+    relativeFromHorizontal?: string | null;
+    relativeFromVertical?: string | null;
+    /** Additional image payload fields; `null` clears an existing field. */
+    other?: Readonly<Record<string, unknown | null>>;
+}
+/** A text or picture watermark payload for {@link YrsSession.insertWatermark}. */
+type YrsWatermark = {
+    kind: 'text';
+    text: string;
+    font: string;
+    color: string;
+    semitransparent: boolean;
+    layout: 'diagonal' | 'horizontal';
+    fontSize?: number;
+    decorative?: boolean;
+} | {
+    kind: 'picture';
+    relId?: string;
+    mediaPath?: string;
+    dataUrl?: string;
+    contentType?: string;
+    scale: number;
+    washout: boolean;
+    widthEmu?: number;
+    heightEmu?: number;
+    decorative?: boolean;
+};
+/**
+ * One formatted segment from {@link YrsSession.storySegments} — the render
+ * bridge's input. `attributes` carries run marks plus `ins` / `del` revision
+ * values (suggested deletions are retained text with a `del` attribute).
+ */
+type YrsStorySegment = {
+    kind: 'text';
+    text: string;
+    attributes: Record<string, unknown>;
+} | {
+    kind: 'pilcrow';
+    paraId: string;
+    properties: Record<string, unknown>;
+    attributes: Record<string, unknown>;
+} | {
+    kind: 'embed';
+    /** Map-backed embed discriminator (`table`, `noteRef`, `image`, …). */
+    embedKind: string;
+    /** Authored map entries excluding the discriminator. */
+    payload: Record<string, unknown>;
+    attributes: Record<string, unknown>;
+};
+/** Current offsets of one sticky comment anchor. */
+interface YrsResolvedCommentAnchor {
+    story: string;
+    start: number;
+    end: number;
+}
+/** A paragraph's story span; `end` is its pilcrow, so `end - start` is the paragraph length. */
+interface YrsParagraphSpan {
+    start: number;
+    end: number;
+}
+/** Compact paragraph entry used to build the live input-position projection. */
+interface YrsParagraphLength {
+    paraId: string;
+    /** UTF-16 text and inline embed units before the paragraph's pilcrow. */
+    length: number;
+}
+/** Receipt of an op that minted a paragraph id. */
+interface YrsParagraphReceipt {
+    paraId: string;
+}
+/** Receipt of an op that may have minted a tracked-change revision (suggesting mode). */
+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
+ * mode stamps a `pPrIns` revision on the first half.
+ */
+interface YrsSplitReceipt {
+    firstParaId: string;
+    secondParaId: string;
+    revisionId: string | null;
+}
+/** Low-level UTF-16 story operation for {@link YrsSession.applyRawOps}. */
+type YrsRawOp = {
+    op: 'insert';
+    index: number;
+    text: string;
+    attrs?: Record<string, unknown>;
+} | {
+    op: 'delete';
+    index: number;
+    len: number;
+} | {
+    op: 'format';
+    index: number;
+    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;
+    payload?: Record<string, unknown>;
+    attrs?: Record<string, unknown>;
+} | {
+    op: 'setEmbedAttr';
+    index: number;
+    key: string;
+    value: unknown;
+} | {
+    /** Upserts a side-map comment with sticky story-unit ranges. */
+    op: 'setComment';
+    id: string;
+    ranges: ReadonlyArray<readonly [number, number]>;
+    author?: string;
+    date?: string;
+    body?: unknown;
+} | {
+    /** Removes the side-map comment keyed by `id`; errors when missing. */
+    op: 'removeComment';
+    id: string;
+};
+/** 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. */
+    docGridPitchPx?: number;
+    defaultParagraphStyleId?: string;
+    /** Theme color name → hex (`accent1` → `4472C4`), for theme-color resolution. */
+    themeColors?: Record<string, string>;
+    /** The document default tab stop in twips. */
+    defaultTabStopTwips?: number | null;
+    /** Current page content height in CSS px, for proportional drawing constraints. */
+    pageContentHeight?: number | null;
+    /** yrs revision/paragraph id → dense numeric layout id (list markers, revisions). */
+    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 {
+    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
+ * `acceptChangeById` twin) or an explicit story range (the range-command twin;
+ * every tracked change overlapping the range resolves, no id filtering).
+ */
+type YrsChangeTarget = {
+    revisionId: string;
+} | YrsStoryRange;
+/** Receipt of {@link YrsSession.acceptChange} / {@link YrsSession.rejectChange}. */
+interface YrsResolveReceipt {
+    /** The revision ids resolved by the op (resolution order, deduplicated). */
+    revisionIds: string[];
+}
+/** This peer's awareness selection, resolved from two yrs sticky positions. */
+interface YrsSelection {
+    anchor: YrsLoc;
+    head: YrsLoc;
+}
+interface YrsResidentCaretRect {
+    pageIndex: number;
+    pageId: string;
+    x: number;
+    y: number;
+    height: number;
+}
+interface YrsResidentCaretSnapshot {
+    frameEpoch: number;
+    caretRect: YrsResidentCaretRect | null;
+    /** Selection the rect was computed for. Absent on raw engine snapshots. */
+    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;
+    editMs: number;
+    lowerMs: number;
+    measureMs: number;
+    paginateMs: number;
+    displayInputMs: number;
+    displayBuildMs: number;
+    displayFinalizeMs: number;
+    displayMs: number;
+    encodeMs: number;
+}
+/**
+ * Serializable bootstrap state for the dedicated resident-layout worker.
+ * The main-thread yrs replica records the inputs that established resident
+ * render, measurement, and pagination state; the worker replays them once and
+ * then owns every ordinary input-to-frame transaction.
+ *
+ * @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
+     * the worker's known vector — both apply through the same merge path. */
+    state: Uint8Array;
+    selection: YrsSelection | null;
+    /** Empty when the caller declared the worker's fonts current
+     * (`knownFontsRevision` matches); the worker then keeps its registrations. */
+    fonts: YrsResidentFontRegistration[];
+    /** Monotonic revision of the resident font set (bumped by register/clear). */
+    fontsRevision: number;
+    renderInputs: Array<{
+        story: string;
+        env: YrsRenderEnv;
+    }>;
+    measureInputs: string[];
+    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
+ * of the whole world.
+ *
+ * @internal
+ */
+interface YrsResidentWorkerSyncOptions {
+    /** The worker replica's last reported yrs state vector. */
+    knownStateVector?: Uint8Array | null;
+    /** The `fontsRevision` the worker last applied. */
+    knownFontsRevision?: number | null;
+}
+/** A range-aggregated toggle mark. @public */
+type YrsTriState = boolean | 'mixed';
+/**
+ * Read-only toolbar/a11y state aggregated from yrs over one story range.
+ * Toggle marks are tri-state; value marks are `null` when absent or mixed.
+ *
+ * @public
+ */
+interface YrsSelectionContext {
+    bold: YrsTriState;
+    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;
+    alignment: string | null;
+    /**
+     * Full authored pilcrow property bag. Known toolbar fields retain their
+     * names (`indentLeft`, `spaceBefore`, `lineSpacing`, `numPr`, and so on);
+     * paragraph style is stored as `pStyle`.
+     */
+    paragraphProperties: {
+        [key: string]: unknown;
+        pStyle?: string;
+        alignment?: string;
+        indentLeft?: number;
+        indentRight?: number;
+        indentFirstLine?: number;
+        hangingIndent?: boolean;
+        spaceBefore?: number;
+        spaceAfter?: number;
+        lineSpacing?: number;
+        lineSpacingRule?: string;
+        numPr?: {
+            numId?: number;
+            ilvl?: number;
+        };
+    };
+    hasSelection: boolean;
+    isMultiParagraph: boolean;
+    /** The range belongs to a table-cell story. */
+    inTable: boolean;
+    /** The range covers exactly one non-pilcrow embed unit. */
+    isSingleEmbed: boolean;
+    /** Embed discriminator (`image`, `drawing`, …), else `null`. */
+    embedKind: string | null;
+    /** Convenience flag for a single `image` embed selection. */
+    isImage: boolean;
+    inInsertion: boolean;
+    inDeletion: boolean;
+}
+/**
+ * One tracked insertion, deletion, or paragraph-mark revision read from yrs.
+ *
+ * @public
+ */
+interface YrsRevisionInfo {
+    revisionId: string;
+    author: string;
+    date: string;
+    kind: 'insertion' | 'deletion' | 'pPrIns' | 'pPrDel' | 'pPrChange' | 'trIns' | 'trDel' | 'tableIns' | 'tableDel';
+    story: string;
+    /** Raw affected text, capped at 80 Unicode code points. */
+    preview: string;
+    range: YrsStoryRange;
+}
+/**
+ * Story-local locator for one native table embed.
+ *
+ * @public
+ */
+interface YrsTableLoc {
+    story: string;
+    /** Zero-based table ordinal in the parent story. */
+    tableIndex: number;
+}
+/**
+ * One table cell addressed in the resolved rectangular grid.
+ *
+ * @public
+ */
+interface YrsCellLoc extends YrsTableLoc {
+    row: number;
+    column: number;
+}
+/**
+ * Anchor-cell to head-cell rectangular selection, addressed by grid
+ * coordinates rather than document positions.
+ *
+ * @public
+ */
+interface YrsTableRange {
+    anchor: YrsCellLoc;
+    head: YrsCellLoc;
+}
+/**
+ * Receipt shared by native table-structure and cell-format operations.
+ *
+ * @public
+ */
+interface YrsTableReceipt {
+    table: YrsTableLoc;
+    rows: number;
+    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[];
+}
+/**
+ * OOXML-shaped cell border value passed through to `tcPr.borders`.
+ *
+ * @public
+ */
+interface YrsCellBorder {
+    style: string;
+    size?: number;
+    color?: {
+        rgb: string;
+    };
+}
+/**
+ * Per-side border patch for {@link YrsSession.setCellBorders}. An omitted side
+ * is left alone, `style: 'none'` authors an explicit no-border, and `null`
+ * drops the authored side.
+ *
+ * @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.
+ */
+/** 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;
+    /** 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. */
+    measureParagraphJson(input: string): string;
+    /** Paginate and retain the measured input and Layout in the session. */
+    layoutDocumentJson(input: string): string;
+    /** Return the compact font requirements for resident region layout. */
+    layoutFontRequirementsJson(input: string): string;
+    /** Paginate and compose section/page regions in the resident engine. */
+    layoutDocumentWithRegionsJson(input: string): string;
+    /** 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 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, count?: number): {
+        frame: Uint8Array;
+        profile: YrsEngineApplyProfile;
+    };
+    /** Snapshot the inputs needed to move resident layout ownership to a worker. */
+    residentWorkerSnapshot(options?: YrsResidentWorkerSyncOptions): YrsResidentWorkerSnapshot | null;
+    /**
+     * Cheap worker-sync probe: the resident layout revision when a worker
+     * snapshot would be available, without encoding document state or copying
+     * font bytes. Steady-state frame builds consult this instead of building a
+     * full snapshot.
+     */
+    residentWorkerProbe(): {
+        layoutRevision: number;
+    } | null;
+    /** Resident display-list hit/range queries; results are small JSON records. */
+    displayHitTestRegionsJson(pageIndex: number, x: number, y: number): string;
+    displayVerticalMoveJson(position: number, direction: 'up' | 'down', goalX: number): string;
+    displayRangeRectsJson(from: number, to: number): string;
+    displayRangeRectsRegionJson(region: 'body' | 'header' | 'footer', rId: string, from: number, to: number): string;
+    /** Read a glyph outline from the session's resident font store. */
+    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; 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;
+    /**
+     * 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}.
+     */
+    loadStories(stories: readonly YrsStorySeed[]): Record<string, string[]>;
+    /** Full document state as one yrs v1 update (Yjs wire format). */
+    encodeState(): Uint8Array;
+    /** Current Yrs state vector in the Yjs v1 wire format. */
+    encodeStateVector(): Uint8Array;
+    /** Full state, or only the state missing from a peer vector. */
+    encodeStateAsUpdate(remoteStateVector?: Uint8Array): Uint8Array;
+    /** Applies a remote/incremental yrs v1 update. */
+    applyUpdate(update: Uint8Array): CollaborationTextInsertion | null;
+    /** Apply a same-user worker update under the local undo origin. @internal */
+    applyLocalUpdate(update: Uint8Array): void;
+    /**
+     * Subscribes to every committed transaction's v1 update (local AND
+     * applied-remote). Returns an unsubscribe function.
+     */
+    onUpdate(listener: (update: Uint8Array, origin: CollaborationUpdateOrigin) => void): () => void;
+    /** Encode one location as a binary Yrs sticky position. */
+    encodeStickyPosition(loc: YrsLoc): YrsStickyPosition;
+    /** Resolve a binary Yrs sticky position against this replica. */
+    resolveStickyPosition(position: YrsStickyPosition): YrsLoc | null;
+    /** Store this peer's awareness selection as sticky positions. */
+    setSelection(anchor: YrsLoc, head?: YrsLoc): void;
+    /** Resolve this peer's current sticky selection, or null before initialization. */
+    selection(): YrsSelection | null;
+    /** Encode the current selection as binary Yrs sticky indices. */
+    encodeSelection(): CollaborationCursor | null;
+    /** Resolve a peer's binary Yrs sticky indices against this replica. */
+    resolveSelection(cursor: CollaborationCursor): YrsSelection | null;
+    /** Store this peer's rectangular table selection outside the document. */
+    setCellSelection(range: YrsTableRange): void;
+    /** Resolve the current sticky cell selection, or null before initialization. */
+    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). */
+    undo(): boolean;
+    redo(): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Adds a story with one paragraph; the receipt carries its paraId. */
+    createStory(storyId: string, initialText: string, pStyle?: string, alignment?: string): YrsParagraphReceipt;
+    /** Removes a complete story (including an unreachable table-cell story). */
+    deleteStory(storyId: string): void;
+    /** Inserts a row above or below the cell that `at` resolves into. */
+    insertRow(at: YrsCellLoc, side: 'above' | 'below', suggesting?: YrsAuthor): YrsTableReceipt;
+    /** Inserts a rectangular structural table at a paragraph-keyed location. */
+    insertTable(at: YrsLoc, rows: number, columns: number, suggesting?: YrsAuthor): YrsTableReceipt;
+    /** Inserts a column left or right of the cell that `at` resolves into. */
+    insertColumn(at: YrsCellLoc, side: 'left' | 'right'): YrsTableReceipt;
+    /** Deletes every row covered by an explicit rectangular cell range. */
+    deleteRow(range: YrsTableRange, suggesting?: YrsAuthor): YrsTableReceipt;
+    /** Deletes every column covered by an explicit rectangular cell range. */
+    deleteColumn(range: YrsTableRange): YrsTableReceipt;
+    /** Removes a complete table plus its reachable cell stories. */
+    deleteTable(table: YrsTableLoc): YrsTableReceipt;
+    /** Merges a rectangular range into its top-left cell. */
+    mergeCells(range: YrsTableRange): YrsTableReceipt;
+    /** Splits the merged cell covering `at` into one cell per grid slot. */
+    splitCell(at: YrsCellLoc, rows?: number, columns?: number): YrsTableReceipt;
+    /** Sets or clears the selected cells' background color. */
+    setCellShading(range: YrsTableRange, color: string | null): YrsTableReceipt;
+    /**
+     * Merges an OOXML-shaped patch into selected cells' `tcPr`. JSON `null`
+     * clears a property; merge/split-owned span keys are rejected.
+     */
+    setCellTextFormat(range: YrsTableRange, patch: Readonly<Record<string, unknown>>): YrsTableReceipt;
+    /**
+     * Merges border sides into the selected cells. `insideH`/`insideV` resolve
+     * per cell to the physical edges interior to the selection.
+     */
+    setCellBorders(range: YrsTableRange, borders: YrsCellBorders): YrsTableReceipt;
+    /** Sets one authored grid-column width in twips. */
+    setColumnWidth(at: YrsCellLoc, widthTwips: number): YrsTableReceipt;
+    /** Sets the table-wide preferred width in twips. */
+    setTableWidth(table: YrsTableLoc, widthTwips: number): YrsTableReceipt;
+    /** Inserts paragraph-break-free text. Suggesting mode mints a revision. */
+    insertText(at: YrsLoc, text: string, suggesting?: YrsAuthor): YrsRevisionReceipt;
+    /**
+     * Deletes a range (plain) or marks it as a suggested deletion (suggesting).
+     * A range spanning paragraphs also merges them (pilcrow-as-character).
+     */
+    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): YrsReplaceReceipt;
+    /**
+     * Splits a paragraph by inserting one pilcrow. The FIRST half keeps the
+     * original paraId; the SECOND half is re-minted (`secondParaId`).
+     */
+    splitParagraph(at: YrsLoc, suggesting?: YrsAuthor): YrsSplitReceipt;
+    /** Merges `paraId` with the FOLLOWING paragraph. Errors on the final paragraph. */
+    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. 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. */
+    formatRange(range: YrsStoryRange, delta: YrsInlineFormatDelta): void;
+    /** Sets or clears the protected hyperlink attribute over a non-empty range. */
+    setHyperlink(range: YrsStoryRange, hyperlink: YrsHyperlinkAttrs | null): void;
+    /** Clears direct formatting while retaining hyperlinks and tracked-change stamps. */
+    clearFormatting(range: YrsStoryRange): void;
+    /** Applies a paragraph style id to every paragraph intersecting the range. */
+    applyParagraphStyle(range: YrsStoryRange, styleId: string, suggesting?: YrsAuthor): void;
+    /** Applies tri-state paragraph properties to every paragraph intersecting the range. */
+    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 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;
+    /** {@link setContentControlValue} for the embed at a paragraph-keyed position. */
+    setContentControlValueAt(at: YrsLoc, value: YrsContentControlValue): void;
+    /**
+     * 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, 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;
+    /** Sets one paragraph property (any JSON value). `paraId` is reserved. */
+    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
+     * split stays), a `pPrDel` mark joins with the following paragraph (whose
+     * pPr survives — Word's surviving-`w:p` rule). Resolving never stamps a new
+     * revision. Throws on an unknown revision id.
+     */
+    acceptChange(target: YrsChangeTarget): YrsResolveReceipt;
+    /**
+     * Rejects tracked changes — the inverse of {@link acceptChange}: pending
+     * insertions roll back, pending deletions restore their text; a `pPrIns`
+     * mark joins back with the following paragraph, a `pPrDel` mark clears.
+     */
+    rejectChange(target: YrsChangeTarget): YrsResolveReceipt;
+    /** Aggregate toolbar/a11y state from yrs over one paragraph-addressed range. */
+    selectionContext(range: YrsStoryRange): YrsSelectionContext;
+    /** Enumerate tracked changes across every story in deterministic order. */
+    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[];
+    /** 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. */
+    storyChecksum(story: string): bigint;
+    /** Lowers a story to layout blocks and rejects unsupported embeds. */
+    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[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     * 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;
+}
+/** Options for {@link createYrsSession}. */
+interface CreateYrsSessionOptions {
+    /**
+     * The yrs client id (non-negative safe integer). Omit to allocate a random
+     * 32-bit id, yjs-style.
+     */
+    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
+ * load it lazily so non-editor consumers avoid the wasm startup cost.
+ */
+declare function createYrsSession(options?: CreateYrsSessionOptions): Promise<YrsSession>;
+
+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 };