@silurus/ooxml 0.69.0 → 0.70.0

package/dist/types/docx.d.ts

@@ -60,6 +60,10 @@ export declare type BodyElement = {
     headers?: HeadersFooters;
     footers?: HeadersFooters;
     titlePage?: boolean;
+    /** ECMA-376 §17.6.13 / §17.6.11 — this ENDING section's page geometry
+     *  (size + margins). Absent when the sectPr inherits both pgSz and pgMar
+     *  (the renderer then falls back to the body-level section geometry). */
+    geom?: SectionGeom;
 };
 
 export declare interface BorderSpec {
@@ -68,6 +72,24 @@ export declare interface BorderSpec {
     style: string;
 }
 
+/**
+ * Build the transparent text-selection overlay for a rendered docx page: one
+ * absolutely-positioned, color-transparent `<span>` per {@link DocxTextRunInfo}
+ * (emitted by `renderPage`'s `onTextRun`), so the browser's native selection
+ * lands on the drawn glyphs. Extracted verbatim from `DocxViewer._buildTextLayer`
+ * so both the pager (DocxViewer) and the continuous-scroll viewer (DocxScrollViewer)
+ * share one implementation; also public API for integrators building their own
+ * overlay (design §10). MAIN render mode only — `onTextRun` cannot cross the
+ * worker boundary.
+ *
+ * @param layer           the overlay div (position:relative parent expected).
+ * @param runs            per-run geometry from `renderPage({ onTextRun })`.
+ * @param canvasCssWidth  the rendered canvas's CSS width (e.g. `"700px"`), used
+ *                        to size the overlay to match the canvas.
+ * @param canvasCssHeight the rendered canvas's CSS height.
+ */
+export declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], canvasCssWidth: string, canvasCssHeight: string): void;
+
 export declare interface CellBorders {
     top: BorderSpec | null;
     bottom: BorderSpec | null;
@@ -343,6 +365,11 @@ export declare class DocxDocument {
      */
     getImage(imagePath: string, mimeType: string): Promise<Blob>;
     get pageCount(): number;
+    /** The render mode this engine was loaded with ('main' | 'worker'). A fact for
+     *  integrators and the scroll viewer: an injected engine's mode decides whether
+     *  pages render via renderPage (main) or renderPageToBitmap (worker) — no
+     *  probing (design §11: no silent mis-pathing). */
+    get mode(): 'main' | 'worker';
     /**
      * The raw parsed document model. Available only in `mode: 'main'`; in
      * `mode: 'worker'` the model stays in the worker and this throws.
@@ -372,6 +399,20 @@ export declare class DocxDocument {
      */
     get endnotes(): DocNote[];
     private _getPages;
+    /**
+     * ECMA-376 §17.6.13 / §17.6.11 — the page size (pt) of page `pageIndex`, per
+     * section (a mixed portrait/landscape document returns different sizes per page).
+     * Available in BOTH modes: worker mode reads the worker-built `pageSizes` meta;
+     * main mode reads the paginated pages' stamped geometry. Returns the body-level
+     * section size for an out-of-range index (clamped) or a page with no stamped
+     * geometry. `{ 0, 0 }` means "not loaded" (before `load()` resolves or after
+     * `destroy()`). Returns a fresh object per call — safe to mutate.
+     * The recommended way to ask "how big is page i?" for layout.
+     */
+    pageSize(pageIndex: number): {
+        widthPt: number;
+        heightPt: number;
+    };
     renderPage(target: HTMLCanvasElement | OffscreenCanvas, pageIndex: number, opts?: RenderPageOptions): Promise<void>;
     /**
      * Render a page and return it as an ImageBitmap. Works in both modes; in
@@ -437,6 +478,453 @@ export declare interface DocxRunBorder {
     space: number;
 }
 
+export declare class DocxScrollViewer {
+    private _doc;
+    private readonly _injected;
+    private readonly _opts;
+    private readonly _container;
+    private readonly _wrapper;
+    private readonly _scrollHost;
+    private readonly _spacer;
+    /** Resolved render mode. When an engine is injected the engine's own `mode`
+     *  is authoritative (design §11 — no silent mis-pathing / no probing); an
+     *  explicitly conflicting `opts.mode` is rejected at construction. When self-
+     *  loading, `opts.mode` decides and `load()` passes it to `DocxDocument.load`. */
+    private _mode;
+    /** px-per-pt zoom multiplier. Base fit maps the first page's width to the
+     *  container width (or opts.width). Zoom multiplies this (design §7). */
+    private _scale;
+    /** Whether the base fit scale has been established. Set true the first time
+     *  `relayout()` resolves a positive base scale. We use an explicit flag rather
+     *  than a `_scale === 1` sentinel because a fit scale of exactly 1 is a valid
+     *  established state (a 1× fit would otherwise be re-fit forever). */
+    private _scaleEstablished;
+    /** Live slots keyed by page index. */
+    private readonly _slots;
+    /** Recyclable detached slots (canvas + textLayer reused across pages). */
+    private readonly _free;
+    /** Cached per-page heights in px at the current scale (index-aligned). */
+    private _heights;
+    private _lastRange;
+    private _lastTopIndex;
+    private _scrollListener;
+    /** Set by `destroy()`. Async render callbacks (main + worker) check it before
+     *  reporting an error so a rejection that lands after teardown is swallowed
+     *  rather than surfaced to a `onError` on a dead viewer. */
+    private _destroyed;
+    /** Worker mode: page indices whose bitmap render is currently dispatched to the
+     *  engine. Coalesces a scroll storm — we never dispatch a second render for a
+     *  page whose first is still in flight — and lets us drop pages that scrolled
+     *  out of the window before dispatch (design §11 worker coalescing).
+     *
+     *  T4 ZOOM HAZARD (RESOLVED by the render epoch below): coalescing keys on page
+     *  INDEX only, with no notion of the scale a dispatch was made at. Once
+     *  `setScale` can change the zoom mid-flight, an in-flight bitmap dispatched at
+     *  the OLD scale can still pass the on-resolution identity check if the SAME
+     *  slot object is re-mounted for page `i` (the pool reuses slot objects, so
+     *  `_slots.get(i) === slot && slot.renderedPage === i` can hold for an old
+     *  dispatch), and get painted at the WRONG resolution. We fix this with a render
+     *  epoch (`_renderEpoch`): each dispatch captures the epoch, and on resolution a
+     *  moved epoch ⇒ STALE (close + re-dispatch the live slot). See
+     *  `_renderSlotBitmap`. */
+    private readonly _bitmapInFlight;
+    /** Render generation, bumped on every effective `setScale` (and the resize
+     *  re-fit in `_onResize`, which routes through `setScale`). Stamped into each async render
+     *  dispatch; a resolution whose captured epoch ≠ this value is STALE — its
+     *  pixels/geometry are at a superseded scale. Worker path: close the orphan
+     *  bitmap + re-dispatch the live slot. Main path: skip the (stale) text-layer
+     *  build; the engine's per-canvas token already discards the stale pixels. */
+    private _renderEpoch;
+    /** Pending settle-render timer handle (design §7 mechanism 2). Set by
+     *  `_scheduleSettle` after each `setScale`, reset on the next one so a burst
+     *  dispatches ONE settle at the end, and cleared in `destroy()`. `ReturnType`
+     *  of `setTimeout` (a number in the DOM, a Timeout object in node) so the type
+     *  is host-agnostic. */
+    private _settleTimer;
+    private _wheelListener;
+    /** One-shot latch for the worker-mode text-selection warning. The overlay is a
+     *  main-mode-only feature: in worker mode the per-run `onTextRun` geometry
+     *  cannot cross the worker boundary, so an `enableTextSelection` overlay stays
+     *  empty. We warn once (parity with `DocxViewer`) rather than per slot. */
+    private _warnedNoTextSelection;
+    /** Observes the container so a width change re-fits the base scale. Disconnected
+     *  in `destroy()`. */
+    private _resizeObserver;
+    /** The base fit scale at the last established/re-fit layout. `_onResize` divides
+     *  `_scale` by this to recover the current zoom multiplier so a width change
+     *  re-fits the base while preserving the user's zoom (design §11). */
+    private _prevBase;
+    /** The fit width (px) the base scale was last established at. Lets `_onResize`
+     *  skip the re-fit when only the height changed (a ResizeObserver fires on ANY
+     *  box change, but only a WIDTH change alters the fit-to-width base scale). */
+    private _lastFitWidth;
+    /** Resolved page-canvas `box-shadow` (design: the recipe drop shadow by
+     *  default). Resolved ONCE with `??` — NOT `||` — so `pageShadow: false`
+     *  survives as the "no shadow" sentinel (a `||` would treat `false` as absent
+     *  and wrongly re-apply the default). Applied by `_applyPageShadow` at EVERY
+     *  canvas-creation site (`_acquireSlot` and the double-buffer spare in
+     *  `_settleSlot`) so a recycled/re-mounted slot and a settle-swapped spare all
+     *  carry it. */
+    private readonly _pageShadow;
+    constructor(container: HTMLElement, opts?: DocxScrollViewerOptions);
+    /**
+     * Load a DOCX from URL or ArrayBuffer and render the first window.
+     * UNSUPPORTED when an engine was injected via `opts.document` (throws) — the
+     * caller already owns the parsed engine.
+     */
+    load(source: string | ArrayBuffer): Promise<void>;
+    get pageCount(): number;
+    /** CSS px width of page `i` at the current scale. */
+    private _pageWidthPx;
+    /** CSS px height of page `i` at the current scale. */
+    private _pageHeightPx;
+    /** The fit width (px), deferring when the container is unlaid-out. An EXPLICIT
+     *  `opts.width` is the page's CSS-width contract and is returned UNCHANGED (the
+     *  gutters still apply around placement, not to the width). The container-derived
+     *  default instead targets `containerWidth − padL − padR` so a page sits INSIDE
+     *  the horizontal gutters at 100%. A non-positive result (gutters wider than the
+     *  container) is treated as unlaid-out — the same deferral as a zero-width box. */
+    private _fitWidthPx;
+    /** Base scale: first page's width fit to the fit-width. Returns 0 when the
+     *  container has no width yet (deferral). */
+    private _baseScale;
+    /**
+     * Recompute per-page heights + the spacer and re-mount the visible window.
+     *
+     * The viewer already calls this automatically after `load()`, an injected
+     * engine, a container resize, and a zoom, so most integrations never need it.
+     * It is public as a deliberate escape hatch: if the host mutates the layout in
+     * a way the `ResizeObserver` cannot observe (e.g. a CSS change on an ancestor
+     * that resizes the container without a box-size event, or a font that finishes
+     * loading after first paint), call `relayout()` to force a re-fit. Idempotent —
+     * safe to call repeatedly, and a no-op while the container has zero width (the
+     * fit is deferred until width appears, design §11).
+     */
+    relayout(): void;
+    private _recomputeHeights;
+    private _gap;
+    private _overscan;
+    /** Desk padding fed to `computeVisibleRange`: `paddingTop`/`paddingBottom`,
+     *  each defaulting to `gap` (uniform rhythm). Resolved here (not stored) to
+     *  mirror `_gap()`/`_overscan()`, and consumed at EVERY `computeVisibleRange`
+     *  call site so the padded offsets are the single source of geometry. */
+    private _pad;
+    /** Horizontal desk gutters: `paddingLeft`/`paddingRight`, each defaulting to
+     *  `gap` (uniform rhythm — the horizontal gutters match the vertical padding).
+     *  Consumed by `_fitWidthPx` (to shrink the container-derived fit), by
+     *  `_positionSlot` (the flush-left floor), and by `_syncSpacer` (the spacer
+     *  width). Resolved here (not stored) to mirror `_gap()`/`_pad()`. */
+    private _padH;
+    private _range;
+    private _syncSpacer;
+    /** Horizontal scroll extent: the widest page (docx pages can differ in width)
+     *  plus both gutters. A spacer NARROWER than the container never creates a
+     *  scrollbar (scrollWidth = max(clientWidth, content)), so it is always safe to
+     *  set — it only matters when a zoomed-in page grows past the viewport, where it
+     *  gives the gutters something to scroll to on either side. Max over per-page
+     *  widths so the extent covers the widest page in the document. Called from
+     *  `_syncSpacer` and after every scale change (zoom / resize re-fit) so the
+     *  extent tracks the current page px width. */
+    private _syncSpacerWidth;
+    private _onScroll;
+    /** Mount/recycle slots for the current visible window. */
+    private _mountVisible;
+    /** Apply the resolved page-canvas shadow (design: recipe drop shadow by
+     *  default, `false` ⇒ none). Single source so `_acquireSlot` and the
+     *  double-buffer spare in `_settleSlot` stay in lock-step — a spare that missed
+     *  this would lose the shadow on the settle swap. `box-shadow` never affects
+     *  layout, so this is safe to (re)set on a live/pooled canvas without shifting
+     *  any offset. */
+    private _applyPageShadow;
+    private _acquireSlot;
+    private _recycleSlot;
+    private _positionSlot;
+    /** Device-pixel ratio for a render (opts override → window → 1). */
+    private _dpr;
+    /**
+     * Render page `i` into `slot`. Routes strictly on the constructor-resolved
+     * `_mode` (design §11 — no probing, no silent mis-pathing): `main` ⇒ paint the
+     * slot's canvas directly via `renderPage`; `worker` ⇒ transfer an ImageBitmap
+     * from `renderPageToBitmap`.
+     *
+     * Slot-identity guard: a slot recycled to a DIFFERENT page while a previous
+     * render is in flight must not repaint the stale page. `slot.renderedPage`
+     * tracks the page this slot is committed to; we stamp it up-front and bail on
+     * resolution if it changed (the engine's own token guard is per-canvas; this is
+     * the viewer's per-slot page-identity check).
+     *
+     * Render epoch (main path): pixel staleness after a mid-flight `setScale` is
+     * already handled by the engine's per-canvas token (the newer renderPage on the
+     * same canvas wins) — `setScale` recycles + re-mounts, and the re-mount always
+     * re-dispatches `renderPage` (renderedPage reset to -1), so a fresh render is
+     * always issued. But the viewer-side side effects of a STALE resolution — the
+     * text-layer build (its run geometry is at the OLD scale) and the renderedPage
+     * bookkeeping — must NOT run, or a superseded render would rebuild the overlay
+     * with stale x/y/w/h (the pool reuses slot objects, so the identity check alone
+     * can pass for an old-epoch resolution). We gate them on the captured epoch.
+     */
+    private _renderSlot;
+    /** Warn once when an `enableTextSelection` overlay was requested but the render
+     *  mode is `worker` (so the overlay stays empty). Same wording as
+     *  `DocxViewer._render` — one warning per viewer, not per slot. */
+    private _maybeWarnNoTextSelection;
+    /** Route an async render failure to `onError`, or `console.error` when none is
+     *  set (so failures are never fully silent), and never after teardown. */
+    private _reportRenderError;
+    /**
+     * Worker-mode slot render: dispatch `renderPageToBitmap`, transfer the result
+     * via a per-slot `bitmaprenderer` context, and manage the ImageBitmap lifecycle.
+     *
+     * Coalescing / drop-stale (design §11):
+     *  - Skip if page `i` is already in flight (a scroll storm won't double-dispatch).
+     *  - Skip if page `i` already left the mounted window before dispatch.
+     *  - On resolution, if `slot` is no longer THIS page's live slot (it recycled to
+     *    another page, or page `i` re-mounted onto a DIFFERENT slot while this render
+     *    was in flight), close the orphan bitmap and skip the paint. In that
+     *    re-mount case a live slot for `i` still awaits a render, so once we clear
+     *    the in-flight guard we re-dispatch it — a page that recycled and re-mounted
+     *    mid-flight must never stay blank.
+     *  - RENDER EPOCH: the dispatch captures `this._renderEpoch`. `setScale` bumps
+     *    the epoch, so a resolution whose captured epoch ≠ the live epoch is STALE
+     *    even when the SAME slot object is still mounted for page `i` (the pool
+     *    reuses slot objects, so the identity check alone can't catch a zoom that
+     *    happened mid-flight). A moved epoch ⇒ close the orphan + re-dispatch the
+     *    live slot at the new scale, never paint the old-scale bitmap.
+     */
+    private _renderSlotBitmap;
+    /**
+     * Set the absolute px-per-pt zoom scale, clamped inline to
+     * `[zoomMin ?? 0.1, zoomMax ?? 4]` (absolute bounds, XlsxViewer convention — NOT
+     * multiples of the base fit; design §3 keeps the clamp in the viewer, not core),
+     * then re-anchor VERTICALLY so the page currently under the viewport top stays
+     * fixed. A no-op when nothing is loaded or when the clamped scale is unchanged.
+     *
+     * FLICKER-FREE (design §7): this does NOT re-render the visible pages inline.
+     * It shows an immediate CSS preview (stretch the existing bitmaps, scale the
+     * overlays) and DEBOUNCES a full-resolution settle re-render for ZOOM_SETTLE_MS,
+     * so a wheel/pinch burst never blanks a page and coalesces into one crisp render.
+     *
+     * Re-anchor (written from scratch — XlsxViewer only re-anchors horizontally):
+     * capture `top = topIndex` and the intra-page fraction `intraFrac` from the
+     * CURRENT range BEFORE rescale; after recomputing heights at the new scale,
+     * `newScrollTop = offsets'[top] + intraFrac × heights'[top]`, clamped to
+     * `[0, totalHeight' − viewportHeight]`. Because a page's height scales linearly
+     * with `_scale`, the same fractional position maps exactly to the new geometry.
+     *
+     * CAVEAT — base fit below the floor: `relayout()` sets `_scale = base` WITHOUT
+     * clamping to `[zoomMin, zoomMax]`. If the base fit is below `zoomMin` (a wide
+     * page in a narrow container), the initial scale sits under the floor, but once
+     * the user zooms via `setScale` the clamp pins the minimum to `zoomMin`, so they
+     * can no longer return below the floor to the original base fit through this API.
+     */
+    setScale(scale: number): void;
+    /**
+     * CSS preview of the visible window at the current `_scale` (design §7
+     * mechanism 1), WITHOUT re-rendering. Slots leaving the window recycle normally;
+     * slots ENTERING the window mount fresh (rendered at the current scale directly,
+     * so they never need a preview); slots that STAY are repositioned and their
+     * canvas + text overlay are CSS-transformed to the new size (the device buffer
+     * is untouched — that is the whole point: no synchronous clear, no blank frame).
+     */
+    private _previewVisible;
+    /**
+     * CSS-preview a single already-mounted slot at the new geometry (design §7): the
+     * wrapper is repositioned + sized (via `_positionSlot`), the canvas bitmap is
+     * STRETCHED to the new CSS size (no `canvas.width` — the device buffer, and thus
+     * the drawn pixels, are left intact, just scaled by the browser), and the text
+     * overlay is scaled by `newScale / renderedScale` so it tracks the stretched
+     * page. `renderedScale <= 0` means the slot's first render hasn't resolved yet
+     * (nothing to stretch); the pending render captured the current scale, so it
+     * lands correct and no preview is needed.
+     */
+    private _previewSlot;
+    /** (Re)schedule the debounced settle re-render (design §7 mechanism 2). Resets
+     *  the timer on every call so a burst of `setScale` dispatches ONE settle
+     *  ZOOM_SETTLE_MS after the LAST call. Cleared in `destroy()`. */
+    private _scheduleSettle;
+    /** Full-resolution settle re-render of the visible window (design §7 mechanisms
+     *  2+3). Re-renders each mounted slot at the current scale via the double-buffer
+     *  swap (main) / same-canvas transfer (worker). Main mode also rebuilds the text
+     *  overlay and clears its preview transform; in worker mode the overlay is
+     *  permanently empty (text selection is main-mode-only), so the transform is
+     *  inert there and is reset on recycle. Dispatched at the CURRENT epoch; the
+     *  existing epoch gate discards it if a later `setScale` supersedes it
+     *  mid-render. */
+    private _settleRender;
+    /**
+     * Settle-render one slot at the current scale (design §7 mechanism 3).
+     *
+     * WORKER: re-dispatch the bitmap render into the SAME canvas. The worker path
+     * sizes the device buffer and `transferFromImageBitmap`s it in ONE synchronous
+     * step (no await between `canvas.width = …` and the transfer), so the browser
+     * never composites an intermediate blank frame — no spare canvas is needed. The
+     * `renderedScale === _scale` gate in `_settleRender` plus the epoch gate inside
+     * `_renderSlotBitmap` keep this correct and idempotent.
+     *
+     * MAIN: `renderPage` (via renderDocumentToCanvas) synchronously sets
+     * `canvas.width = …` (which CLEARS the backing store to blank) BEFORE its first
+     * await and paints AFTER — so rendering into the on-screen canvas would flash it
+     * white. Render into a SPARE off-DOM canvas instead; only once it resolves at the
+     * current epoch do we swap it into the wrapper (replacing the old canvas, which is
+     * DISCARDED — the pooled unit is the slot, not the canvas). The old canvas keeps
+     * showing the stretched preview until the instant of the swap — blank-free.
+     */
+    private _settleSlot;
+    /**
+     * Scroll so page `index`'s top edge sits at the viewport top. Clamps `index` to
+     * `[0, pageCount-1]` (the pager convention) and the resulting scrollTop to
+     * `[0, totalHeight − viewportHeight]` so the last pages don't scroll past the
+     * end. A no-op when nothing is loaded or the document is empty.
+     *
+     * `opts.behavior` ('auto' | 'smooth', default 'auto') is honoured via
+     * `scrollHost.scrollTo({ top, behavior })` when the host supports it (a real
+     * browser); the stub-DOM has no `scrollTo`, so the fallback sets `scrollTop`
+     * directly (which is what the tests assert). We then call `_mountVisible` once.
+     *
+     * MOUNTING CAVEAT: synchronous mounting of the target page is guaranteed only on
+     * the DEFAULT/'auto' path — there `scrollTop` has already jumped to `top`, so the
+     * `_mountVisible` call reads the final scroll position and the target page's slots
+     * exist immediately. With `behavior: 'smooth'` the scroll animates ASYNCHRONOUSLY:
+     * `scrollTop` is still near the old position when `_mountVisible` runs, so the
+     * target page mounts lazily via the animation's subsequent `scroll` events, not
+     * from this call.
+     */
+    scrollToPage(index: number, opts?: {
+        behavior?: 'auto' | 'smooth';
+    }): void;
+    /**
+     * Re-fit the base scale on a container resize while PRESERVING the current zoom
+     * multiplier (design §11), then re-anchor + re-render. A `ResizeObserver` fires
+     * on any box change, but only a WIDTH change alters the fit-to-width base scale;
+     * a height-only change skips the re-fit yet STILL re-mounts the visible window
+     * (via `_mountVisible`), because a taller viewport reveals rows that were below
+     * the fold and would otherwise stay blank until the next scroll. Empty/unloaded
+     * ⇒ no-op; a still-zero width ⇒ defer.
+     *
+     * Zero-width recovery: a container that was 0-wide at construction never
+     * established a scale (`_scaleEstablished` is false), so the first non-zero
+     * resize establishes it here via `relayout()` — completing the T2 deferral.
+     *
+     * Re-fit math (zoom multiplier preserved):
+     *   mult      = _scale / _prevBase            (the user's zoom over the old base)
+     *   newScale  = newBase × mult
+     * Routing through `setScale(newScale)` bumps `_renderEpoch` (resize IS an epoch
+     * event — T4 banner) and re-anchors + CSS-previews + debounces a settle re-render
+     * of every slot at the new geometry, exactly like a zoom (design §7 flicker-free
+     * path — a rapid ResizeObserver burst therefore also coalesces into one settle).
+     * `setScale`'s clamp/no-op guards apply: an unchanged newScale (identical width)
+     * is a no-op there — so we short-circuit BEFORE it when the fit-width is
+     * unchanged (mounting the revealed window without a needless re-render), and
+     * after it we call `_mountVisible` again to cover the case where the clamp made
+     * `setScale` no-op yet the viewport still grew.
+     */
+    private _onResize;
+    get topVisiblePage(): number;
+    /* Excluded from this release type: mountedPageIndicesForTest */
+    /* Excluded from this release type: scaleForTest */
+    /* Excluded from this release type: baseScaleForTest */
+    /* Excluded from this release type: renderEpochForTest */
+    /* Excluded from this release type: resizeForTest */
+    /**
+     * Tear down the viewer: remove the DOM subtree and (only for a self-loaded
+     * engine) destroy the engine. An injected engine is left intact — the caller
+     * owns its lifecycle. Per-slot worker ImageBitmaps are closed on recycle.
+     */
+    destroy(): void;
+}
+
+/**
+ * Options for {@link DocxScrollViewer}. Extends `RenderPageOptions` (per-page
+ * render knobs, minus `onTextRun`) and `LoadOptions` (parse/worker knobs). See
+ * design §8.1.
+ *
+ * `onTextRun` is omitted deliberately: the viewer drives it internally per
+ * mounted slot to build the optional per-page selection overlay (gated by
+ * `enableTextSelection`), so exposing it here would let a caller's callback be
+ * silently overridden.
+ */
+export declare interface DocxScrollViewerOptions extends Omit<RenderPageOptions, 'onTextRun'>, LoadOptions {
+    /** Base fit width in CSS px → base zoom scale. Default: the container's width
+     *  at first non-zero layout (design §7/§11 zero-width deferral). */
+    width?: number;
+    /** Vertical gap (px) between consecutive pages. Default 16. */
+    gap?: number;
+    /** Desk padding (px) ABOVE the FIRST page — the margin a PDF reader leaves
+     *  between the top of the scroll surface and the first sheet. Default: `gap`
+     *  (uniform desk rhythm — the first page sits the same distance from the top as
+     *  pages sit from each other). Pass `0` for a flush-top layout. */
+    paddingTop?: number;
+    /** Desk padding (px) BELOW the LAST page — the margin below the final sheet.
+     *  Default: `gap`. Pass `0` for a flush-bottom layout. */
+    paddingBottom?: number;
+    /** Desk gutter (px) to the LEFT of the pages — the horizontal margin between the
+     *  left edge of the scroll surface and a page sitting flush-left (i.e. once
+     *  zoomed wide enough that centering no longer applies). Default: `gap` (uniform
+     *  desk rhythm — the horizontal gutters match the vertical ones). It also shrinks
+     *  the container-derived FIT width so a page sits inside the gutters at 100%
+     *  (an EXPLICIT `opts.width` is the page's CSS-width contract and is NOT reduced;
+     *  the gutters still apply around placement). Pass `0` for a flush-left layout. */
+    paddingLeft?: number;
+    /** Desk gutter (px) to the RIGHT of the pages. Default: `gap`. Shrinks the
+     *  container-derived fit width symmetrically with `paddingLeft`. Pass `0` for a
+     *  flush-right layout. */
+    paddingRight?: number;
+    /** Pages kept mounted beyond the viewport on each side. Default 1. */
+    overscan?: number;
+    /** Per-page transparent text-selection overlay. MAIN render mode only:
+     *  in worker mode `onTextRun` cannot cross the worker boundary, so the overlay
+     *  stays empty and the viewer logs one warning (design §11). */
+    enableTextSelection?: boolean;
+    /** Minimum zoom scale (px-per-pt multiplier floor). Default 0.1. */
+    zoomMin?: number;
+    /** Maximum zoom scale. Default 4. */
+    zoomMax?: number;
+    /** Enable `Ctrl`/`Cmd`+wheel zoom. Default true. */
+    enableZoom?: boolean;
+    /**
+     * CSS `background` shorthand for the scroll surface (the "desk") visible
+     * behind and between pages — the gray a PDF reader paints around the sheet.
+     * Applied to the viewer-owned scroll host. The pages themselves are always
+     * drawn on the document's own white canvas and are unaffected. Default
+     * `undefined`: the scroll surface stays transparent so the host container's
+     * background shows through (non-breaking).
+     */
+    background?: string;
+    /**
+     * CSS `box-shadow` painted on every page CANVAS (not the wrapper — the
+     * text-selection overlay must not cast its own shadow). The soft drop shadow a
+     * PDF reader leaves under each sheet.
+     *
+     * - Default (`undefined`): `'0 1px 3px rgba(0,0,0,0.2)'` — the recipe look, so
+     *   the scroll viewer reproduces the Examples appearance with zero config.
+     * - `false`: NO shadow (flat pages).
+     * - A custom string is applied verbatim. A spread-only ring such as
+     *   `'0 0 0 1px #c8ccd0'` gives a crisp 1px BORDER look — and because
+     *   `box-shadow` never affects layout (unlike `border`, which would grow the
+     *   box and shift every offset), a border and a drop shadow are the SAME knob
+     *   here rather than two competing options.
+     */
+    pageShadow?: string | false;
+    /**
+     * Inject an already-loaded engine to share one parse across panes (design §14).
+     * When set: `load()` is unsupported (throws), the engine's own `mode` wins (an
+     * explicitly conflicting `opts.mode` throws at construction, design §11), and
+     * `destroy()` does NOT destroy this engine (the caller owns its lifecycle).
+     */
+    document?: DocxDocument;
+    /** Fires when the top-most visible page changes. `topIndex` from
+     *  `computeVisibleRange` (the first page intersecting the viewport top,
+     *  EXCLUDING overscan). */
+    onVisiblePageChange?: (topIndex: number, total: number) => void;
+    /** Error callback. When set, `load()` invokes it and resolves (otherwise the
+     *  error is rethrown — shared viewer error contract). It ALSO fires for async
+     *  per-slot render failures (both main `renderPage` and worker
+     *  `renderPageToBitmap` rejections); a failed page is left blank rather than
+     *  crashing the loop. Without an `onError`, render failures are logged via
+     *  `console.error` so they are never fully silent. */
+    onError?: (err: Error) => void;
+}
+
 export declare interface DocxTextRun {
     text: string;
     bold: boolean;
@@ -534,6 +1022,15 @@ export declare class DocxViewer {
     private _currentPage;
     private _canvas;
     private _wrapper;
+    /** The canvas's DOM position BEFORE the constructor reparented it into
+     *  {@link _wrapper}, captured so {@link destroy} can return the caller-owned
+     *  canvas to exactly where it was. `null` parent = canvas was passed
+     *  detached. */
+    private _originalParent;
+    private _originalNextSibling;
+    /** The canvas's inline `display` before the constructor forced `block`
+     *  (empty string if it was unset), restored on {@link destroy}. */
+    private _originalDisplay;
     private _textLayer;
     private _opts;
     private readonly _mode;
@@ -558,7 +1055,15 @@ export declare class DocxViewer {
     goToPage(index: number): Promise<void>;
     nextPage(): Promise<void>;
     prevPage(): Promise<void>;
-    /** Terminate the parser worker and release resources. */
+    /**
+     * Terminate the parser worker and release resources.
+     *
+     * The caller-owned `<canvas>` is returned to the DOM position it held before
+     * the constructor was called (same parent, same next-sibling) and its inline
+     * `display` is restored, so the canvas can be reused — e.g. to construct a new
+     * viewer on the same element. If the canvas was passed detached (no parent) it
+     * is simply removed from the internal wrapper. Safe to call more than once.
+     */
     destroy(): void;
     private _render;
     private _buildTextLayer;
@@ -821,6 +1326,21 @@ declare interface LoadOptions_2 {
      * via `@font-face` in your application CSS.
      */
     useGoogleFonts?: boolean;
+    /**
+     * Override the URL the parser worker fetches the WebAssembly module from.
+     *
+     * By default each format resolves the `.wasm` asset that ships next to its
+     * bundle (relative to the module URL), so no configuration is needed. Set
+     * this to serve the parser WASM from a CDN or a self-hosted path instead — a
+     * relative value is resolved against the current document URL. The same
+     * dependency-injection contract across docx / pptx / xlsx.
+     *
+     * The referenced file must be the matching format's `*_parser_bg.wasm`
+     * artifact (the one wasm-bindgen emitted for that parser); pointing it at a
+     * mismatched or missing file makes `load()` reject when the worker
+     * instantiates it.
+     */
+    wasmUrl?: string | URL;
     /**
      * Override the per-entry ZIP decompression cap (bytes) used by the zip-bomb
      * guard in the Rust parser. Defaults to 512 MiB. Raise it to load documents
@@ -828,6 +1348,16 @@ declare interface LoadOptions_2 {
      * untrusted input. Zero / negative values fall back to the default.
      */
     maxZipEntryBytes?: number;
+    /**
+     * Reject the parse request if the parser worker does not answer within this
+     * many milliseconds. Opt-in safety net for a wedged or crashed worker that
+     * would otherwise leave `load()` pending forever. **Default: unlimited** —
+     * parsing a large document with heavy embedded media can legitimately take
+     * tens of seconds, so no timeout is imposed unless you set one. A worker that
+     * throws or fails to load already rejects immediately regardless of this
+     * value; this bound only covers the "silent, never-responds" case.
+     */
+    workerTimeoutMs?: number;
     /**
      * Opt-in OMML equation engine (MathJax + STIX Two Math, ~3 MB). Inject it
      * **once** here and every render of this document / presentation / workbook
@@ -1070,7 +1600,11 @@ export declare type PathCmd = {
 };
 
 export declare interface RenderPageOptions {
-    /** Canvas CSS width in px; height is auto-computed from page aspect ratio */
+    /** Canvas CSS width in px; height is auto-computed from page aspect ratio.
+     *  Applies per CALL — pages of different physical widths (per-section pgSz,
+     *  §17.6.13) rendered at the same `width` get different px-per-pt scales.
+     *  For a uniform document scale, derive a per-page width from
+     *  `DocxDocument.pageSize(i)` instead of passing a constant. */
     width?: number;
     dpr?: number;
     defaultTextColor?: string;
@@ -1105,6 +1639,32 @@ export declare interface RunRevision {
     date?: string;
 }
 
+/** ECMA-376 §17.6.13 `<w:pgSz>` + §17.6.11 `<w:pgMar>` — a section's page
+ *  geometry: page size + margins + header/footer distances (pt). Mirrors the Rust
+ *  `SectionGeom`. Carried on a {@link BodyElement} `sectionBreak` arm (`geom`) so a
+ *  mid-body section keeps its own page size; the FINAL section's geometry lives on
+ *  {@link DocxDocumentModel.section}. Also stamped per {@link PaginatedBodyElement}
+ *  (`sectionGeom`) by the paginator so the renderer sizes each page from its own
+ *  section. `orient` is omitted — Word swaps w/h for landscape, so verbatim w/h
+ *  already give the correct dims.
+ *
+ *  ⚠ Spread over the body-level {@link SectionProps} in `renderDocumentToCanvas`
+ *  (`{ ...doc.section, ...pageGeom }`): only add per-section PAGE-BOX fields that
+ *  exist on `SectionProps` with the same name and semantics — an optional field
+ *  colliding with a non-geometry `SectionProps` name would silently override the
+ *  body-level value the renderer promises to preserve. */
+export declare interface SectionGeom {
+    pageWidth: number;
+    pageHeight: number;
+    /** §17.6.11 — top/bottom MAY be negative (ST_SignedTwipsMeasure); keep the sign. */
+    marginTop: number;
+    marginRight: number;
+    marginBottom: number;
+    marginLeft: number;
+    headerDistance: number;
+    footerDistance: number;
+}
+
 export declare interface SectionProps {
     pageWidth: number;
     pageHeight: number;
@@ -1235,6 +1795,12 @@ export declare interface ShapeRun {
     textBlocks?: ShapeText[];
     /** "t" | "ctr" | "b" — vertical anchor for the shape's text body (`<wps:bodyPr @anchor>`). */
     textAnchor?: string | null;
+    /** ECMA-376 §21.1.2.1.1 auto-fit mode from `<wps:bodyPr>`, normalized to the
+     *  shared core `autoFit` vocabulary (core `src/types/common.ts`): "none"
+     *  (`<a:noAutofit/>`, fixed box — overflowing text is CLIPPED to the box),
+     *  "sp" (`<a:spAutoFit/>`, box grows to text), or "norm" (`<a:normAutofit/>`,
+     *  text shrinks). Absent ⇒ overflow visible. */
+    textAutofit?: string | null;
     textInsetL?: number;
     textInsetT?: number;
     textInsetR?: number;
@@ -1261,6 +1827,12 @@ export declare interface ShapeText {
     /** ECMA-376 §17.3.1.33 `<w:spacing w:after>` of this text-box paragraph, in
      *  pt — reserved BELOW the paragraph. Absent/0 ⇒ no offset. */
     spaceAfter?: number;
+    /** ECMA-376 §17.3.1.33 line spacing value (style-chain resolved). Encoded per
+     *  {@link lineSpacingRule}: "auto" ⇒ a MULTIPLIER on the natural line box
+     *  (1.15 = 276/240), "exact"/"atLeast" ⇒ pt. Absent ⇒ single (natural). */
+    lineSpacingVal?: number;
+    /** "auto" | "exact" | "atLeast" — see {@link lineSpacingVal}. */
+    lineSpacingRule?: string;
     /** ECMA-376 §17.3.1.12 `<w:ind w:left/@start>` — paragraph left indent (pt).
      *  Absent/0 ⇒ flush to the box's inner left edge. */
     indentLeft?: number;
@@ -1273,6 +1845,18 @@ export declare interface ShapeText {
      *  applies a signed hanging first-line list-independently). Absent/0 ⇒ the
      *  first line aligns with the continuation lines. */
     indentFirst?: number;
+    /** ECMA-376 §17.3.1.37 `<w:tabs>` — explicit tab stops of this text-box
+     *  paragraph, resolved through the style chain like {@link DocParagraph.tabStops}.
+     *  Absent/empty ⇒ only the automatic default-tab grid applies. The renderer
+     *  feeds these to the SAME line engine the body uses so a `\t` inside a text box
+     *  advances to its stop (the old shape wrapper dropped tabs entirely). */
+    tabStops?: TabStop[];
+    /** ECMA-376 §17.3.1.6 `<w:bidi>` — right-to-left text-box paragraph, resolved
+     *  through the style chain like {@link DocParagraph.bidi}. `true` = RTL,
+     *  `false` = explicitly LTR, absent = unspecified. Consumed as the paragraph
+     *  base direction for the UAX#9 reordering pass (the body renderer reads the
+     *  identical field). */
+    bidi?: boolean;
     /** Zip path of an inline image inside this text-box paragraph
      *  (`<w:drawing><wp:inline><a:blip r:embed>`), e.g. `word/media/image1.emf`.
      *  Absent for a text-only paragraph. */