@betteroffice/docx 0.0.1

package/dist/displayListQueries-p-ijSzdh.d.mts

@@ -0,0 +1,222 @@
+import { I as ImagePrimitive, D as DisplayList, R as RustDisplayListQueryEngine } from './rustDisplayList-dqunvwxH.mjs';
+
+/**
+ * Locate an image primitive in a built DisplayList by its document position.
+ *
+ * The canvas image-selection overlay needs the selected image's page-local
+ * rect to place its resize handles, and on the canvas path the painted DOM
+ * image (`.layout-run-image`) is parked/hidden — its rect is unusable. The
+ * display list carries every inline image as an `ImagePrimitive` stamped with
+ * `docStart` (= the image atom's PM position, the same value the DOM path reads
+ * from `data-doc-start`), so the primitive found here is the geometry source
+ * that replaces `imageInfo.element.getBoundingClientRect()`.
+ *
+ * Body primitives only: header/footer image primitives carry doc positions in a
+ * different PM doc (the HF editor), so a body image pmPos must never match one.
+ *
+ * @experimental part of the rust-canvas-engine change; shape may evolve.
+ */
+
+type DisplayListImageRegion = 'body' | 'header' | 'footer';
+interface LocatedImagePrimitive {
+    primitive: ImagePrimitive;
+    /** page the primitive paints on (page-local px are relative to this page) */
+    pageIndex: number;
+    /** PM-document region containing the image. Undefined reads as body. */
+    region?: DisplayListImageRegion;
+    /** Header/footer relationship id when `region` is not body. */
+    rId?: string;
+}
+/**
+ * First body image primitive whose `docStart` equals `pos`, or null. `pos` is
+ * the image node's PM position (a NodeSelection's `from`, or the left edge of a
+ * one-atom TextSelection).
+ */
+declare function findImagePrimitiveByDocPos(list: DisplayList, pos: number, region?: DisplayListImageRegion, rId?: string): LocatedImagePrimitive | null;
+/** Topmost positioned image under a page-local point, or null. */
+declare function findImagePrimitiveAtPoint(list: DisplayList, pageIndex: number, x: number, y: number, region?: DisplayListImageRegion, rId?: string): LocatedImagePrimitive | null;
+/**
+ * Capture an inline body's authored anchor offsets from display-list geometry.
+ * Horizontal position is relative to the page content/column box; vertical
+ * position is relative to the containing paragraph fragment. Header/footer
+ * images deliberately return undefined until their paragraph/content-origin
+ * metadata is part of the display-list contract.
+ */
+declare function captureInlinePositionEmuFromDisplayList(queries: DisplayListQueries, pos: number): {
+    horizontalEmu: number;
+    verticalEmu: number;
+} | undefined;
+
+/**
+ * Synchronous query facade over a built DisplayList, backed by the Rust
+ * hit-testing module (`crates/docx-layout/src/hit.rs`).
+ *
+ * This is the sole pointer/selection geometry source for the canvas
+ * renderer (it replaced the deleted painted-DOM resolvers): geometry comes
+ * from the immutable display list, never from DOM rects.
+ *
+ * Perf model: when the embedded wasm carries the session-handle exports, this
+ * facade parses the display list into the Rust store exactly ONCE
+ * (`openDisplayList` → handle) and routes every hit-test / range-rect query
+ * through the by-handle exports — no per-query re-serialization or re-parse.
+ * When those exports are absent (before the integrator re-embeds the wasm) it
+ * falls back to the JSON-arg exports, stringifying the list once and reusing
+ * the string for every query. Either way the query RESULTS are byte-identical —
+ * the handle path is pure perf.
+ *
+ * Handle lifecycle: the handle is opened once per facade (per display-list
+ * build) and released by `dispose()`. Callers that drop the facade without
+ * disposing (e.g. a React `useMemo` replacement) are covered by a
+ * `FinalizationRegistry` that closes the handle when the facade is collected;
+ * the Rust store additionally caps live handles and evicts the oldest, so a
+ * missed finalize can never grow memory unbounded.
+ *
+ * Queries are synchronous; until the lazily-imported wasm module resolves they
+ * return `null`/`[]`. In practice the module is already loaded by the time a
+ * queries instance exists, because building the display list itself went
+ * through the same module (`loadRustDisplayListQueryEngine` shares the promise
+ * with `buildRustDisplayList`).
+ *
+ * @experimental part of the rust-canvas-engine change; shape may evolve.
+ */
+
+/** Query surface implemented by the editing wasm over its resident list. */
+interface ResidentDisplayListQueryEngine {
+    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;
+}
+/** which part of a page owns a hit — mirrors `HitRegion` in hit.rs */
+type DisplayListHitRegion = 'body' | 'header' | 'footer';
+/**
+ * Region-aware hit result. For `header`/`footer` the position refers to the
+ * HF ProseMirror doc identified by `rId`, NOT the body doc — the caller must
+ * route the selection to that HF editor, exactly like the DOM path scopes
+ * clicks to `.layout-page-header|footer`.
+ */
+interface DisplayListRegionHit {
+    region: DisplayListHitRegion;
+    rId?: string;
+    pos: number | null;
+}
+/** one highlight rectangle of a PM range, page-local px */
+interface DisplayListRect {
+    pageIndex: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Explicit lifecycle of the mandatory Rust query source. */
+type DisplayListQuerySourceState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+} | {
+    status: 'error';
+    error: Error;
+};
+/** One paragraph fragment box on one page, in page-local px. */
+interface DisplayListParagraphGeometry extends DisplayListRect {
+    from: number;
+    to: number;
+    blockId?: number | string;
+    paraId?: string;
+}
+/** One ordered visual line reconstructed from authoritative primitives. */
+interface DisplayListVisualLine extends DisplayListRect {
+    baseline: number;
+    from: number;
+    to: number;
+    blockId?: number | string;
+    paraId?: string;
+}
+/** Image primitive plus its explicit page/region geometry. */
+interface DisplayListImageGeometry extends LocatedImagePrimitive {
+    rect: DisplayListRect;
+    pos: number;
+}
+/**
+ * Sync query surface over one immutable DisplayList. A new instance is
+ * created per display-list build (the list never mutates in place).
+ */
+interface DisplayListQueries {
+    /** the list this instance queries (page sizes, region bands, …) */
+    readonly displayList: DisplayList;
+    /** false until the wasm module is loaded — queries return null/[] before */
+    isReady(): boolean;
+    /** Loading/ready/error state for hosts that must not silently fall back. */
+    sourceState(): DisplayListQuerySourceState;
+    /** Resolves when the Rust query engine is ready; rejects on load failure. */
+    whenReady(): Promise<void>;
+    pageCount(): number;
+    pageSize(pageIndex: number): {
+        width: number;
+        height: number;
+    } | null;
+    pageBounds(pageIndex: number): DisplayListRect | null;
+    contentBounds(pageIndex: number): DisplayListRect | null;
+    columnBounds(pageIndex: number): DisplayListRect[];
+    /** Body paragraph fragment boxes containing `pos`, including page splits. */
+    paragraphRects(pos: number): DisplayListParagraphGeometry[];
+    /** Ordered body visual lines across all pages. */
+    visualLines(): readonly DisplayListVisualLine[];
+    /** Visual line containing `pos`, or null. */
+    visualLineAtPosition(pos: number): DisplayListVisualLine | null;
+    /** Topmost image under a page-local point. Body by default. */
+    imageAtPoint(pageIndex: number, x: number, y: number, region?: DisplayListHitRegion, rId?: string): DisplayListImageGeometry | null;
+    /** Image whose atom starts at `pos`. Body by default. */
+    imageByPos(pos: number, region?: DisplayListHitRegion, rId?: string): DisplayListImageGeometry | null;
+    /** region-aware point → doc position (page-local coordinates) */
+    hitTestRegions(pageIndex: number, x: number, y: number): DisplayListRegionHit | null;
+    /** body PM range → highlight rects */
+    rangeRects(from: number, to: number): DisplayListRect[];
+    /**
+     * Header/footer PM range → highlight rects for the region's band. `region` is
+     * `'header' | 'footer'`; `rId` identifies the HF ProseMirror doc, and
+     * `from`/`to` are positions in THAT doc. The same HF doc paints on every page
+     * carrying the part, so this returns one rect-set per such page (each tagged
+     * with its `pageIndex`) — the caller picks the page it is editing. Returns
+     * `[]` until the region-aware exports are embedded (feature-detected).
+     */
+    hfRangeRects(region: 'header' | 'footer', rId: string, from: number, to: number): DisplayListRect[];
+    /**
+     * Caret geometry for a collapsed HF selection — the HF twin of `caretRect`.
+     * Resolves `[pos, pos+1)` in the HF doc (left edge is the caret), falling back
+     * to `[pos-1, pos)` (right edge) at end-of-line / end-of-doc. Returns one
+     * caret rect per page carrying the part; the caller picks the edited page.
+     */
+    hfCaretRects(region: 'header' | 'footer', rId: string, pos: number): DisplayListRect[];
+    /** Header/footer sidebar anchors, one per page carrying the part. */
+    hfAnchorRects(region: 'header' | 'footer', rId: string, pos: number): DisplayListRect[];
+    /**
+     * Caret geometry for a collapsed body selection: the collapsed-range rect.
+     * Resolves `[pos, pos+1)` first (rect's left edge is the caret), then falls
+     * back to `[pos-1, pos)` using the right edge (end-of-doc / end-of-line).
+     */
+    caretRect(pos: number): DisplayListRect | null;
+    /**
+     * Anchor geometry for sidebar markers: like `caretRect` but scans
+     * `[pos, pos+2)` forward first so *node* positions (paragraph/table
+     * markers carrying structural tracked-change attrs) resolve to their first
+     * content line instead of the previous block's tail.
+     */
+    anchorRect(pos: number): DisplayListRect | null;
+    /** Explicit body-sidebar alias retained alongside `anchorRect`. */
+    sidebarAnchorRect(pos: number): DisplayListRect | null;
+    /**
+     * Release the wasm session handle backing this facade. Idempotent; safe to
+     * call even when no handle was opened (JSON-arg fallback path). Callers that
+     * forget are covered by a `FinalizationRegistry`, but disposing eagerly frees
+     * the parsed display list in the Rust store immediately.
+     */
+    dispose(): void;
+}
+/**
+ * Build a query facade for one display list. The optional `engine` makes the
+ * facade synchronous and deterministic in tests; without it the shared wasm
+ * module is loaded lazily and queries no-op (`null`/`[]`) until it resolves.
+ */
+declare function createDisplayListQueries(list: DisplayList, engine?: RustDisplayListQueryEngine | ResidentDisplayListQueryEngine): DisplayListQueries;
+
+export { type DisplayListRect as D, type LocatedImagePrimitive as L, type ResidentDisplayListQueryEngine as R, type DisplayListQueries as a, type DisplayListRegionHit as b, type DisplayListHitRegion as c, type DisplayListImageGeometry as d, type DisplayListImageRegion as e, type DisplayListParagraphGeometry as f, type DisplayListQuerySourceState as g, type DisplayListVisualLine as h, captureInlinePositionEmuFromDisplayList as i, createDisplayListQueries as j, findImagePrimitiveAtPoint as k, findImagePrimitiveByDocPos as l };