@betteroffice/docx 0.0.1

package/dist/yrs/index.d.mts

@@ -0,0 +1,882 @@
+import { Document } from '../types/document.mjs';
+import '../content-sSHuWw49.mjs';
+import '../formatting-DoL7KBSL.mjs';
+import '../docx/wrapTypes.mjs';
+import '../styles-VxNcXLdi.mjs';
+import '../settingsParser-CcGvtmCK.mjs';
+
+/** 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;
+
+interface ResidentEngineWorkerFrame {
+    frame: Uint8Array;
+    updates: Uint8Array[];
+    engineMs: number;
+    workerTotalMs: number;
+    engineProfile?: YrsEngineApplyProfile;
+    replayMs: number;
+    replayedPages: number;
+    layoutRevision: number;
+}
+interface ResidentEngineOffscreenPage {
+    pageId: string;
+    canvas: OffscreenCanvas;
+}
+interface ResidentEngineWorkerApplyResult extends ResidentEngineWorkerFrame {
+    applied: true;
+}
+/** Dedicated-worker owner for resident input, pagination, and FrameDelta output. */
+declare class ResidentEngineWorkerClient {
+    private readonly worker;
+    private readonly pending;
+    private nextId;
+    private destroyed;
+    private ready;
+    private revision;
+    constructor();
+    isReady(): boolean;
+    layoutRevision(): number;
+    bootstrap(snapshot: YrsResidentWorkerSnapshot, extras: string): Promise<ResidentEngineWorkerFrame>;
+    sync(snapshot: YrsResidentWorkerSnapshot, extras: string, expectedFrameEpoch: number): Promise<ResidentEngineWorkerFrame>;
+    buildFrame(extras: string, expectedFrameEpoch: number): Promise<ResidentEngineWorkerFrame>;
+    applyInput(text: string, selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean): Promise<ResidentEngineWorkerApplyResult | {
+        applied: false;
+    }>;
+    applyDelete(direction: 'backward' | 'forward', selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean): Promise<ResidentEngineWorkerApplyResult | {
+        applied: false;
+    }>;
+    invalidate(update: Uint8Array, selection: YrsSelection | null): void;
+    attachCanvases(pages: ResidentEngineOffscreenPage[], activePageIds: string[], devicePixelRatio: number, zoom: number): Promise<void>;
+    destroy(): void;
+    private request;
+    private failAll;
+}
+declare function canUseResidentEngineWorker(): boolean;
+
+/**
+ * Direct Document -> yrs load projection.
+ *
+ * This is the Document-model twin of the coexistence seed path. It emits the
+ * same flat story vocabulary as `seedFromPm`, but never constructs a
+ * ProseMirror node: text becomes attributed Y.Text, paragraphs become pilcrow
+ * embeds, tables/block SDTs become structural embeds with child stories, and
+ * comments become root-story side-map entries.
+ */
+
+/**
+ * Seeds every yrs-owned editable story directly from a parsed Document.
+ *
+ * Stories are `body`, `hf:{rId}`, `fn:{id}`, and recursively generated table
+ * cell / block-SDT stories. The target session must not already contain any of
+ * those story ids.
+ *
+ * @public
+ */
+declare function documentToYrs(session: YrsSession, document: Document): void;
+
+/**
+ * yrs -> OOXML Document save projection.
+ *
+ * The yrs coexistence model stores each editable container as a flat story:
+ * text carries inline formatting attributes, pilcrows carry paragraph
+ * properties, and structural/inline atoms are map embeds. This module reads
+ * that representation directly and rebuilds the serializer-facing Document.
+ */
+
+/**
+ * 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>;
+}
+declare function yrsToDocument(session: YrsSession, base: Document, options?: YrsToDocumentOptions): Document;
+
+/**
+ * Typed facade over the Rust yrs editing core (`crates/docx-edit`).
+ *
+ * This module is the ONLY JS entry to that crate — the `docx/zipContainer.ts`
+ * facade precedent. It is types + JSON marshaling only; every editing
+ * semantic (pilcrow-as-character stories, explicit-attribute inserts,
+ * suggesting mode, sticky comment anchors) lives in Rust.
+ *
+ * `createYrsSession()` lazily loads the embedded wasm (`./wasm`) on first call.
+ *
+ * Addressing is the op-contract public vocabulary: a {@link YrsLoc} is
+ * `(story, paraId, offset)` with UTF-16 offsets scoped to one paragraph
+ * (`offset ∈ [0, paragraphLength]`; the paragraph's own pilcrow is excluded
+ * from its offset space). Story-global indices never cross this boundary.
+ */
+
+/** 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;
+}
+/** 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: '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[];
+}
+/** Snapshot of one paragraph from {@link YrsSession.paragraphs}. */
+interface YrsParagraph {
+    paraId: string;
+    text: string;
+    /** pStyle / alignment plus any op-set extras. */
+    properties: Record<string, unknown>;
+}
+/** 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;
+    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 stored on a structured document tag (content control). */
+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;
+}
+/**
+ * Receipt of {@link YrsSession.splitParagraph}. Under the S1 split 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;
+}
+/**
+ * One low-level story mirror operation for {@link YrsSession.applyRawOps}. The
+ * coexistence bridge lowers a ProseMirror transaction to a list of these and
+ * applies them in one yrs transaction. Indices are UTF-16 story units, each read
+ * against the story state after all prior ops in the batch.
+ */
+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>;
+} | {
+    op: 'insertEmbed';
+    index: number;
+    kind: string;
+    payload?: Record<string, unknown>;
+    attrs?: Record<string, unknown>;
+} | {
+    op: 'setEmbedAttr';
+    index: number;
+    key: string;
+    value: unknown;
+} | {
+    /**
+     * Upserts the side-map comment keyed by `id`, (re-)anchoring it to
+     * `ranges` — non-empty `[start, end)` story-unit spans in the batch's
+     * story (sticky `Assoc::After` starts / `Assoc::Before` ends). The
+     * coexistence bridge keys by the PM comment id so identity survives the
+     * mirror.
+     */
+    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 {
+    /** 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>;
+}
+/** Receipt of {@link YrsSession.addComment}. */
+interface YrsCommentReceipt {
+    commentId: string;
+}
+/**
+ * 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;
+}
+/** 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
+ */
+interface YrsResidentWorkerSnapshot {
+    clientId: number;
+    state: Uint8Array;
+    selection: YrsSelection | null;
+    fonts: Uint8Array[];
+    renderInputs: Array<{
+        story: string;
+        env: YrsRenderEnv;
+    }>;
+    measureInputs: string[];
+    layoutInput: string;
+    layoutRevision: number;
+}
+/** 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;
+    /** Uniform ASCII font family, or `null` when absent/mixed. */
+    fontFamily: string | null;
+    /** Uniform font size in half-points (the PM/OOXML `w:sz` unit). */
+    fontSize: number | null;
+    /** Uniform RGB hex or theme-color name, or `null` when absent/mixed. */
+    color: 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 PM
+     * 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, analogous to PM's
+ * `CellSelection` but independent of ProseMirror 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[];
+    newParaIds: string[];
+    deletedTable: boolean;
+    revisionIds: string[];
+}
+/**
+ * OOXML/PM-shaped cell border value passed through to `tcPr.borders`.
+ *
+ * @public
+ */
+interface YrsCellBorder {
+    style: string;
+    size?: number;
+    color?: {
+        rgb: string;
+    };
+}
+/**
+ * Complete per-side border object for {@link YrsSession.setCellBorders}.
+ *
+ * @public
+ */
+type YrsCellBorders = Partial<Record<'top' | 'bottom' | 'left' | 'right' | 'insideH' | 'insideV', YrsCellBorder>>;
+/**
+ * One live replica of the yrs editing model. Thin typed wrapper over the
+ * wasm `EditSession` — no editing logic on this side of the boundary.
+ */
+interface YrsSession {
+    /** 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;
+    /** 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;
+    /** 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;
+    /** 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;
+    /** 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): {
+        frame: Uint8Array;
+        profile: YrsEngineApplyProfile;
+    };
+    /** Snapshot the inputs needed to move resident layout ownership to a worker. */
+    residentWorkerSnapshot(): YrsResidentWorkerSnapshot | null;
+    /** Resident display-list hit/range queries; results are small JSON records. */
+    displayHitTestRegionsJson(pageIndex: number, x: number, y: 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;
+    /**
+     * Seeds stories from parsed content (S1 scaffold; the real
+     * `load(ParsedDocument)` lands with the ops track). Returns paraIds per
+     * story in document order.
+     */
+    loadStories(stories: readonly YrsStorySeed[]): Record<string, string[]>;
+    /** Full document state as one yrs v1 update (Yjs wire format). */
+    encodeState(): Uint8Array;
+    /** Applies a remote/incremental yrs v1 update. */
+    applyUpdate(update: Uint8Array): void;
+    /** Apply a same-user worker update under the local undo origin. @internal */
+    applyLocalUpdate(update: Uint8Array, story: string): void;
+    /**
+     * Subscribes to every committed transaction's v1 update (local AND
+     * applied-remote). Returns an unsubscribe function.
+     */
+    onUpdate(listener: (update: Uint8Array) => void): () => void;
+    /** 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;
+    /** 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;
+    /** Lazily begin local-origin undo capture after import/seeding has completed. */
+    beginUndoCapture(story: string, includeTableStories?: boolean): void;
+    /** Coalesce the stack entries added since `startDepth` into one host undo intent. */
+    markUndoGroup(startDepth: number): void;
+    /** Undo/redo only local-origin direct operations (never remote/system transactions). */
+    undo(): boolean;
+    redo(): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Current local undo/redo stack sizes (zero before tracking starts). */
+    undoDepth(): number;
+    redoDepth(): number;
+    /** 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/PM-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;
+    /** Replaces the complete selected-cell border property object. */
+    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): YrsRevisionReceipt;
+    /**
+     * 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 (PM toggleMark range semantics). */
+    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 authored value on a content-control embed addressed by stable payload id. */
+    setContentControlValue(embedId: string, value: YrsContentControlValue): void;
+    /** Sets a content-control value at a paragraph-keyed embed position. */
+    setContentControlValueAt(at: YrsLoc, value: YrsContentControlValue): void;
+    /** Removes the authored value from a content-control embed. */
+    clearContentControlValue(embedId: string): void;
+    /** Commits image size/wrapping/position fields in one transaction. */
+    setImageGeometry(embedId: string, 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 a batch of raw story mirror ops in one transaction — the coexistence
+     * bridge's mirror-into-yrs path (a faithful mirror of lowered PM state, not a
+     * user-intent op). Not for direct app use.
+     */
+    applyRawOps(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;
+    /**
+     * Accepts tracked changes (S4b): 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[];
+    /** Story ids in the document, sorted. */
+    storyIds(): string[];
+    /** Story length in UTF-16 units (every embed, pilcrows included, counts 1). */
+    storyLength(story: string): number;
+    /**
+     * The story's `canonical-stream-v1` FNV-1a checksum. The coexistence watchdog
+     * compares it against the PM projector's checksum after every mirrored edit.
+     */
+    storyChecksum(story: string): bigint;
+    /**
+     * Lowers a story straight to the renderer's `LayoutBlock[]` — the
+     * yrs-authoritative render path (the eventual replacement for
+     * `toLayoutBlocks(pmDoc)`). Throws with an unsupported-embed message on any
+     * non-native content (opaque blobs) until that class is promoted to native.
+     * The return is the layout pipeline's `LayoutBlock[]` (kept as `unknown[]` to
+     * keep this facade decoupled from the layout types).
+     */
+    yrsBlocksForStory(story: string, env?: YrsRenderEnv): unknown[];
+    /** Paragraph snapshots in document order. */
+    paragraphs(story: string): YrsParagraph[];
+    /** Paragraph ids and inline-unit lengths, resolved in one Rust story traversal. */
+    paragraphSpans(story: string): YrsParagraphLength[];
+    /** The raw formatted-segment view (the render bridge's input). */
+    storySegments(story: string): YrsStorySegment[];
+    /** A paragraph's story span (start unit, pilcrow index). */
+    locateParagraph(story: string, paraId: string): YrsParagraphSpan;
+    /** 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;
+}
+/**
+ * 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 CreateYrsSessionOptions, type ResidentEngineOffscreenPage, type ResidentEngineWorkerApplyResult, ResidentEngineWorkerClient, type ResidentEngineWorkerFrame, type YrsAuthor, type YrsCellBorder, type YrsCellBorders, type YrsCellLoc, type YrsChangeTarget, type YrsCommentReceipt, type YrsContentControlValue, type YrsEngineApplyProfile, type YrsHyperlinkAttrs, type YrsImageGeometry, type YrsInlineFormatDelta, type YrsInputParagraphSeed, type YrsInputParagraphSpan, type YrsInputPositionMap, type YrsLoc, type YrsNumberingProperties, type YrsParaOffset, type YrsParagraph, type YrsParagraphAttrs, type YrsParagraphLength, type YrsParagraphReceipt, type YrsParagraphSeed, type YrsParagraphSpan, type YrsParagraphTabStop, type YrsRawOp, type YrsRenderEnv, type YrsResidentWorkerSnapshot, type YrsResolveReceipt, type YrsResolvedCommentAnchor, type YrsRevisionInfo, type YrsRevisionReceipt, type YrsRunMark, type YrsSelection, type YrsSelectionContext, type YrsSession, type YrsSplitReceipt, type YrsStoryRange, type YrsStorySeed, type YrsStorySegment, type YrsTableLoc, type YrsTableRange, type YrsTableReceipt, type YrsTextColor, type YrsTriState, type YrsWatermark, canUseResidentEngineWorker, compareYrsLocs, createYrsInputPositionMap, createYrsSession, displayPositionToYrsLoc, documentToYrs, yrsLocToDisplayPosition, yrsToDocument };