@paged-media/idml-viewer 0.1.0-canary.0

package/README.md

@@ -0,0 +1,52 @@
+# @paged-media/idml-viewer
+
+Standalone IDML viewer for the browser — camera, pages, input lanes and
+events over the `@paged-media/sdk` WebGPU `ViewerSession`. Rendering is
+WebGPU-only (the session rejects without `navigator.gpu`).
+
+```ts
+import { createViewer, createSessionFromBundledWasm } from "@paged-media/idml-viewer";
+
+const viewer = await createViewer({
+  canvas: document.querySelector("canvas")!,
+  session: createSessionFromBundledWasm, // wasm ships inside this package
+});
+
+viewer.on("pageChanged", ({ page }) => console.log("page", page + 1));
+await viewer.load("/files/brochure.idml"); // URL | ArrayBuffer | Uint8Array | Blob
+```
+
+## Surface
+
+- **Load** — `load(source)`, repeatable; failures throw a `ViewerError`
+  with `code: "PARSE_ERROR" | "UNSUPPORTED" | "GPU_UNAVAILABLE"` and the
+  engine's structured diagnostics attached.
+- **Camera** — `zoom`, `setZoom(z, { anchor })`, `zoomIn/zoomOut`,
+  `fit("page" | "width")`, `minZoom/maxZoom`, `scroll`, `scrollTo`,
+  `scrollBy`. Zooming about an anchor keeps the document point under it
+  fixed.
+- **Pages** — `pageCount`, `currentPage`, `goToPage(n)`,
+  `layoutMode("single" | "continuous")`,
+  `renderPageThumbnail(n, { width })` (RGBA8 readback).
+- **Events** — `on("loaded" | "pageChanged" | "zoomChanged" |
+  "scrollChanged" | "error", cb)` → unsubscribe function.
+- **Input** — wheel/pinch zoom-to-cursor, drag-pan, double-click zoom,
+  keyboard (`+`/`-`/`0`, arrows, PgUp/PgDn, Home/End); each lane
+  disableable via `input: {...}`.
+- **Teardown** — `dispose()` detaches all listeners and frees the wasm
+  session.
+
+Fonts: register faces on the session before `load`
+(`session.register_font(family, style, bytes)`) — same contract as
+`paged-inspect --font-family`.
+
+## Embedding your own session
+
+`createViewer` takes any object satisfying `ViewerSessionLike` (the
+typed contract of the wasm session), so you can init the wasm yourself
+— e.g. from a custom URL or a worker — and hand it in. Tests do exactly
+this with a fake.
+
+## License
+
+MPL-2.0 OR LicenseRef-PMEL — see the repository `LICENSE.md`.

package/dist/bootstrap.d.ts

@@ -0,0 +1,11 @@
+import type { ViewerSessionLike } from "./session.js";
+/**
+ * Create a `ViewerSession` from the wasm bundled with the PUBLISHED
+ * package (`wasm/paged_sdk.js` + `wasm/paged_sdk_bg.wasm`, placed by
+ * the publish workflow — absent in a source checkout, where embedders
+ * inject a session built via `viewer/build-wasm.sh` instead).
+ *
+ * `wasmUrl` overrides the `.wasm` location for bundlers that move
+ * assets; default resolves next to the glue file.
+ */
+export declare function createSessionFromBundledWasm(wasmUrl?: string): Promise<ViewerSessionLike>;

package/dist/bootstrap.js

@@ -0,0 +1,30 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * This file is part of paged (https://paged.media) and is additionally
+ * available under the Paged Media Enterprise License (PMEL). Full
+ * copyright and license information is available in LICENSE.md which is
+ * distributed with this source code.
+ *
+ *  @copyright  Copyright (c) And The Next GmbH
+ *  @license    MPL-2.0 OR Paged Media Enterprise License (PMEL)
+ */
+/**
+ * Create a `ViewerSession` from the wasm bundled with the PUBLISHED
+ * package (`wasm/paged_sdk.js` + `wasm/paged_sdk_bg.wasm`, placed by
+ * the publish workflow — absent in a source checkout, where embedders
+ * inject a session built via `viewer/build-wasm.sh` instead).
+ *
+ * `wasmUrl` overrides the `.wasm` location for bundlers that move
+ * assets; default resolves next to the glue file.
+ */
+export async function createSessionFromBundledWasm(wasmUrl) {
+    const glueUrl = new URL("../wasm/paged_sdk.js", import.meta.url).href;
+    // Dynamic, computed import — left untouched by TS and bundlers so
+    // the glue resolves at runtime inside the published package.
+    const mod = (await import(/* @vite-ignore */ glueUrl));
+    await mod.default(wasmUrl ? { module_or_path: wasmUrl } : undefined);
+    return mod.ViewerSession["new"]();
+}

package/dist/camera.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure camera math over the continuous page stack. Doc space is pt
+ * (pages stacked vertically per `page_layout()`); the camera maps a
+ * doc point `p` to viewport CSS px as `scroll + p * zoom`. Everything
+ * here is side-effect-free so the invariants (zoom-to-anchor, fit,
+ * clamps, current-page) are unit-testable without a canvas.
+ */
+import type { SessionPagesLayout } from "./session.js";
+export interface Camera {
+    /** CSS px per pt. */
+    zoom: number;
+    /** Doc origin in viewport CSS px. */
+    x: number;
+    y: number;
+}
+export interface Viewport {
+    /** CSS px. */
+    width: number;
+    height: number;
+}
+export interface ZoomLimits {
+    min: number;
+    max: number;
+}
+/** Default page-fit margin — matches the wasm fit-page present. */
+export declare const FIT_MARGIN = 0.95;
+export declare function clampZoom(zoom: number, limits: ZoomLimits): number;
+/** Total doc-space extents of the continuous stack (pt). */
+export declare function contentExtent(layout: SessionPagesLayout): {
+    width: number;
+    height: number;
+};
+/**
+ * Zoom about an anchor point (viewport CSS px): the doc point under
+ * the anchor stays under it. With no anchor, zoom about the viewport
+ * centre.
+ */
+export declare function zoomAt(camera: Camera, nextZoom: number, limits: ZoomLimits, viewport: Viewport, anchor?: {
+    x: number;
+    y: number;
+}): Camera;
+/**
+ * Keep content on screen: per axis, content smaller than the viewport
+ * centres; larger content clamps so no blank gap opens at either edge.
+ */
+export declare function clampScroll(camera: Camera, layout: SessionPagesLayout, viewport: Viewport): Camera;
+/**
+ * Fit a page: `"page"` fits both dimensions, `"width"` fits the page
+ * width (top-aligned to the page). Returns the camera centred on the
+ * page in continuous coordinates; single-page mode passes a layout
+ * containing just that page at `yPt: 0`.
+ */
+export declare function fitPage(layout: SessionPagesLayout, pageIndex: number, mode: "page" | "width", viewport: Viewport, limits: ZoomLimits): Camera;
+/**
+ * The page whose band contains the viewport-centre line (continuous
+ * mode). Falls back to the nearest band when the centre sits in a gap.
+ */
+export declare function currentPageAt(camera: Camera, layout: SessionPagesLayout, viewport: Viewport): number;
+/** Scroll that brings `pageIndex`'s top into view (continuous mode). */
+export declare function scrollToPage(camera: Camera, layout: SessionPagesLayout, pageIndex: number, viewport: Viewport): Camera;

package/dist/camera.js

@@ -0,0 +1,113 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * This file is part of paged (https://paged.media) and is additionally
+ * available under the Paged Media Enterprise License (PMEL). Full
+ * copyright and license information is available in LICENSE.md which is
+ * distributed with this source code.
+ *
+ *  @copyright  Copyright (c) And The Next GmbH
+ *  @license    MPL-2.0 OR Paged Media Enterprise License (PMEL)
+ */
+/** Default page-fit margin — matches the wasm fit-page present. */
+export const FIT_MARGIN = 0.95;
+export function clampZoom(zoom, limits) {
+    return Math.min(limits.max, Math.max(limits.min, zoom));
+}
+/** Total doc-space extents of the continuous stack (pt). */
+export function contentExtent(layout) {
+    let width = 0;
+    let height = 0;
+    for (const p of layout.pages) {
+        width = Math.max(width, p.widthPt);
+        height = Math.max(height, p.yPt + p.heightPt);
+    }
+    return { width, height };
+}
+/**
+ * Zoom about an anchor point (viewport CSS px): the doc point under
+ * the anchor stays under it. With no anchor, zoom about the viewport
+ * centre.
+ */
+export function zoomAt(camera, nextZoom, limits, viewport, anchor) {
+    const z = clampZoom(nextZoom, limits);
+    const ax = anchor?.x ?? viewport.width / 2;
+    const ay = anchor?.y ?? viewport.height / 2;
+    const docX = (ax - camera.x) / camera.zoom;
+    const docY = (ay - camera.y) / camera.zoom;
+    return { zoom: z, x: ax - docX * z, y: ay - docY * z };
+}
+/**
+ * Keep content on screen: per axis, content smaller than the viewport
+ * centres; larger content clamps so no blank gap opens at either edge.
+ */
+export function clampScroll(camera, layout, viewport) {
+    const { width, height } = contentExtent(layout);
+    const w = width * camera.zoom;
+    const h = height * camera.zoom;
+    const clampAxis = (pos, content, view) => content <= view
+        ? (view - content) / 2
+        : Math.min(0, Math.max(view - content, pos));
+    return {
+        zoom: camera.zoom,
+        x: clampAxis(camera.x, w, viewport.width),
+        y: clampAxis(camera.y, h, viewport.height),
+    };
+}
+/**
+ * Fit a page: `"page"` fits both dimensions, `"width"` fits the page
+ * width (top-aligned to the page). Returns the camera centred on the
+ * page in continuous coordinates; single-page mode passes a layout
+ * containing just that page at `yPt: 0`.
+ */
+export function fitPage(layout, pageIndex, mode, viewport, limits) {
+    const page = layout.pages[pageIndex] ?? layout.pages[0];
+    if (!page)
+        return { zoom: 1, x: 0, y: 0 };
+    const pw = Math.max(page.widthPt, 1);
+    const ph = Math.max(page.heightPt, 1);
+    const zoom = clampZoom(mode === "page"
+        ? Math.min(viewport.width / pw, viewport.height / ph) * FIT_MARGIN
+        : (viewport.width / pw) * FIT_MARGIN, limits);
+    const x = (viewport.width - pw * zoom) / 2;
+    const y = mode === "page"
+        ? (viewport.height - ph * zoom) / 2 - page.yPt * zoom
+        : (viewport.height - ph * zoom) / 2 -
+            page.yPt * zoom +
+            Math.max(0, (ph * zoom - viewport.height) / 2);
+    return { zoom, x, y };
+}
+/**
+ * The page whose band contains the viewport-centre line (continuous
+ * mode). Falls back to the nearest band when the centre sits in a gap.
+ */
+export function currentPageAt(camera, layout, viewport) {
+    if (layout.pages.length === 0)
+        return 0;
+    const centreDocY = (viewport.height / 2 - camera.y) / camera.zoom;
+    let best = 0;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const p of layout.pages) {
+        if (centreDocY >= p.yPt && centreDocY <= p.yPt + p.heightPt)
+            return p.index;
+        const mid = p.yPt + p.heightPt / 2;
+        const dist = Math.abs(mid - centreDocY);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = p.index;
+        }
+    }
+    return best;
+}
+/** Scroll that brings `pageIndex`'s top into view (continuous mode). */
+export function scrollToPage(camera, layout, pageIndex, viewport) {
+    const page = layout.pages[pageIndex];
+    if (!page)
+        return camera;
+    const x = (viewport.width - page.widthPt * camera.zoom) / 2;
+    // Small breathing room above the page top, mirroring the gap.
+    const y = -page.yPt * camera.zoom + Math.min(12, layout.gapPt * camera.zoom);
+    return { zoom: camera.zoom, x, y };
+}

package/dist/events.d.ts

@@ -0,0 +1,7 @@
+/** Minimal typed emitter — no wildcard, no once, no bubbling. */
+export declare class Emitter<Events extends Record<string, unknown>> {
+    private listeners;
+    on<K extends keyof Events>(event: K, listener: (payload: Events[K]) => void): () => void;
+    emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+    clear(): void;
+}

package/dist/events.js

@@ -0,0 +1,37 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * This file is part of paged (https://paged.media) and is additionally
+ * available under the Paged Media Enterprise License (PMEL). Full
+ * copyright and license information is available in LICENSE.md which is
+ * distributed with this source code.
+ *
+ *  @copyright  Copyright (c) And The Next GmbH
+ *  @license    MPL-2.0 OR Paged Media Enterprise License (PMEL)
+ */
+/** Minimal typed emitter — no wildcard, no once, no bubbling. */
+export class Emitter {
+    listeners = new Map();
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return () => set?.delete(listener);
+    }
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const listener of [...set]) {
+            listener(payload);
+        }
+    }
+    clear() {
+        this.listeners.clear();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createViewer, ViewerError } from "./viewer.js";
+export { createSessionFromBundledWasm } from "./bootstrap.js";
+export type { CreateViewerOptions, LayoutMode, Viewer, ViewerErrorCode, ViewerEvents, } from "./viewer.js";
+export type { InputOptions } from "./input.js";
+export type { SessionDiagnostic, SessionDiagnostics, SessionPageRect, SessionPagesLayout, SessionRaster, ViewerSessionLike, } from "./session.js";
+export { clampScroll, clampZoom, contentExtent, currentPageAt, fitPage, scrollToPage, zoomAt, } from "./camera.js";
+export type { Camera, Viewport, ZoomLimits } from "./camera.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * This file is part of paged (https://paged.media) and is additionally
+ * available under the Paged Media Enterprise License (PMEL). Full
+ * copyright and license information is available in LICENSE.md which is
+ * distributed with this source code.
+ *
+ *  @copyright  Copyright (c) And The Next GmbH
+ *  @license    MPL-2.0 OR Paged Media Enterprise License (PMEL)
+ */
+export { createViewer, ViewerError } from "./viewer.js";
+export { createSessionFromBundledWasm } from "./bootstrap.js";
+export { clampScroll, clampZoom, contentExtent, currentPageAt, fitPage, scrollToPage, zoomAt, } from "./camera.js";

package/dist/input.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Input lanes for the viewer — each independently disableable:
+ * - wheel: Ctrl/⌘-wheel and pinch (`ctrlKey` wheel) zoom to cursor,
+ *   plain wheel pans.
+ * - drag: pointer-drag pans.
+ * - double-click: zoom step at the cursor.
+ * - keyboard: `+`/`-`/`0`, arrows, PgUp/PgDn, Home/End.
+ */
+export interface InputOptions {
+    wheelZoom?: boolean;
+    dragPan?: boolean;
+    doubleClickZoom?: boolean;
+    keyboard?: boolean;
+}
+export interface InputSink {
+    zoomAt(factor: number, anchor: {
+        x: number;
+        y: number;
+    }): void;
+    panBy(dx: number, dy: number): void;
+    zoomStep(direction: 1 | -1, anchor?: {
+        x: number;
+        y: number;
+    }): void;
+    fit(): void;
+    pageStep(direction: 1 | -1): void;
+    home(): void;
+    end(): void;
+}
+/** Attach listeners; returns the detach function. */
+export declare function attachInput(canvas: HTMLCanvasElement, options: InputOptions, sink: InputSink): () => void;

package/dist/input.js

@@ -0,0 +1,122 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * This file is part of paged (https://paged.media) and is additionally
+ * available under the Paged Media Enterprise License (PMEL). Full
+ * copyright and license information is available in LICENSE.md which is
+ * distributed with this source code.
+ *
+ *  @copyright  Copyright (c) And The Next GmbH
+ *  @license    MPL-2.0 OR Paged Media Enterprise License (PMEL)
+ */
+const ARROW_PAN_PX = 48;
+/** Attach listeners; returns the detach function. */
+export function attachInput(canvas, options, sink) {
+    const teardown = [];
+    const listen = (type, handler, opts) => {
+        canvas.addEventListener(type, handler, opts);
+        teardown.push(() => canvas.removeEventListener(type, handler, opts));
+    };
+    const anchorOf = (e) => {
+        const rect = canvas.getBoundingClientRect();
+        return { x: e.clientX - rect.left, y: e.clientY - rect.top };
+    };
+    if (options.wheelZoom !== false) {
+        listen("wheel", (e) => {
+            e.preventDefault();
+            if (e.ctrlKey || e.metaKey) {
+                // Trackpad pinch arrives as ctrlKey wheel; exponential map
+                // keeps pinch and wheel-notch speeds comparable.
+                sink.zoomAt(Math.exp(-e.deltaY * 0.0024), anchorOf(e));
+            }
+            else {
+                sink.panBy(-e.deltaX, -e.deltaY);
+            }
+        }, { passive: false });
+    }
+    if (options.dragPan !== false) {
+        let dragging = false;
+        let lastX = 0;
+        let lastY = 0;
+        listen("pointerdown", (e) => {
+            if (e.button !== 0)
+                return;
+            dragging = true;
+            lastX = e.clientX;
+            lastY = e.clientY;
+            canvas.setPointerCapture?.(e.pointerId);
+        });
+        listen("pointermove", (e) => {
+            if (!dragging)
+                return;
+            sink.panBy(e.clientX - lastX, e.clientY - lastY);
+            lastX = e.clientX;
+            lastY = e.clientY;
+        });
+        const stop = (e) => {
+            dragging = false;
+            canvas.releasePointerCapture?.(e.pointerId);
+        };
+        listen("pointerup", stop);
+        listen("pointercancel", stop);
+    }
+    if (options.doubleClickZoom !== false) {
+        listen("dblclick", (e) => {
+            e.preventDefault();
+            sink.zoomStep(e.shiftKey ? -1 : 1, anchorOf(e));
+        });
+    }
+    if (options.keyboard !== false) {
+        // The canvas needs focusability for keydown.
+        if (!canvas.hasAttribute("tabindex"))
+            canvas.setAttribute("tabindex", "0");
+        listen("keydown", (e) => {
+            switch (e.key) {
+                case "+":
+                case "=":
+                    sink.zoomStep(1);
+                    break;
+                case "-":
+                case "_":
+                    sink.zoomStep(-1);
+                    break;
+                case "0":
+                    sink.fit();
+                    break;
+                case "ArrowLeft":
+                    sink.panBy(ARROW_PAN_PX, 0);
+                    break;
+                case "ArrowRight":
+                    sink.panBy(-ARROW_PAN_PX, 0);
+                    break;
+                case "ArrowUp":
+                    sink.panBy(0, ARROW_PAN_PX);
+                    break;
+                case "ArrowDown":
+                    sink.panBy(0, -ARROW_PAN_PX);
+                    break;
+                case "PageUp":
+                    sink.pageStep(-1);
+                    break;
+                case "PageDown":
+                    sink.pageStep(1);
+                    break;
+                case "Home":
+                    sink.home();
+                    break;
+                case "End":
+                    sink.end();
+                    break;
+                default:
+                    return;
+            }
+            e.preventDefault();
+        });
+    }
+    return () => {
+        for (const detach of teardown)
+            detach();
+    };
+}

package/dist/session.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The typed contract of the wasm `ViewerSession`
+ * (`core/crates/paged-sdk/src/lib.rs`). The viewer programs against
+ * this interface so tests can inject a fake session and embedders can
+ * wrap their own init flow. Method names mirror the wasm-bindgen
+ * exports (snake_case); the viewer surface re-exposes everything in
+ * idiomatic camelCase.
+ */
+/** One diagnostic from `load` / `render_*`. */
+export interface SessionDiagnostic {
+    /** `"error" | "warning" | "info"`. */
+    severity: string;
+    /** Short machine code, e.g. `"open"`, `"build"`, `"no_gpu"`. */
+    code: string;
+    message: string;
+    part?: string | null;
+    line?: number | null;
+}
+export interface SessionDiagnostics {
+    ok: boolean;
+    messages: SessionDiagnostic[];
+}
+/** Continuous-layout geometry from `page_layout()`. */
+export interface SessionPageRect {
+    index: number;
+    yPt: number;
+    widthPt: number;
+    heightPt: number;
+}
+export interface SessionPagesLayout {
+    gapPt: number;
+    pages: SessionPageRect[];
+}
+export interface SessionRaster {
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+}
+export interface ViewerSessionLike {
+    load(idml: Uint8Array, font?: Uint8Array): SessionDiagnostics;
+    register_font(family: string, style: string | undefined, bytes: Uint8Array): void;
+    page_count(): number;
+    set_page(index: number): void;
+    page_layout(): SessionPagesLayout;
+    /**
+     * Camera-transformed present of the continuous page stack. `zoom`
+     * is CSS px per pt; `scrollX`/`scrollY` place the doc origin in CSS
+     * px; `onlyPage` restricts to one page laid out at y = 0.
+     */
+    present(zoom: number, scrollX: number, scrollY: number, dpr: number, onlyPage?: number | null): SessionDiagnostics;
+    /** Binds the presenter to `canvas` on first call (fit-page paint). */
+    render_to_canvas_main(canvas: HTMLCanvasElement): Promise<SessionDiagnostics>;
+    render_page_to_bytes(index: number, targetWidthPx: number): Promise<SessionRaster>;
+    resize(width: number, height: number, devicePixelRatio: number): void;
+    /** wasm-bindgen finalizer. */
+    free?(): void;
+}

package/dist/session.js

@@ -0,0 +1,14 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * This file is part of paged (https://paged.media) and is additionally
+ * available under the Paged Media Enterprise License (PMEL). Full
+ * copyright and license information is available in LICENSE.md which is
+ * distributed with this source code.
+ *
+ *  @copyright  Copyright (c) And The Next GmbH
+ *  @license    MPL-2.0 OR Paged Media Enterprise License (PMEL)
+ */
+export {};

package/dist/viewer.d.ts

@@ -0,0 +1,80 @@
+import { type ZoomLimits } from "./camera.js";
+import { type InputOptions } from "./input.js";
+import type { SessionDiagnostics, SessionRaster, ViewerSessionLike } from "./session.js";
+/** Structured load/init failure. */
+export type ViewerErrorCode = "PARSE_ERROR" | "UNSUPPORTED" | "GPU_UNAVAILABLE";
+export declare class ViewerError extends Error {
+    readonly code: ViewerErrorCode;
+    readonly diagnostics: SessionDiagnostics | undefined;
+    constructor(code: ViewerErrorCode, message: string, diagnostics?: SessionDiagnostics);
+}
+export type LayoutMode = "single" | "continuous";
+export interface ViewerEvents extends Record<string, unknown> {
+    loaded: {
+        pageCount: number;
+    };
+    pageChanged: {
+        page: number;
+    };
+    zoomChanged: {
+        zoom: number;
+    };
+    scrollChanged: {
+        x: number;
+        y: number;
+    };
+    error: ViewerError;
+}
+export interface CreateViewerOptions {
+    canvas: HTMLCanvasElement;
+    /**
+     * The wasm session (or a factory). Embedders typically pass
+     * `await ViewerSession.new()` from `@paged-media/sdk` after
+     * `init(wasmUrl)`; tests pass a fake.
+     */
+    session: ViewerSessionLike | (() => Promise<ViewerSessionLike>);
+    /** Zoom clamps in CSS px per pt. Default `{ min: 0.1, max: 8 }`. */
+    zoomLimits?: Partial<ZoomLimits>;
+    /** Input lanes; each defaults to enabled. */
+    input?: InputOptions;
+    /** Initial layout mode. Default `"continuous"`. */
+    layoutMode?: LayoutMode;
+    /**
+     * Frame scheduler — injectable for tests. Defaults to
+     * `requestAnimationFrame` (microtask fallback off-DOM).
+     */
+    schedule?: (frame: () => void) => void;
+    /** Device pixel ratio override (defaults to `window.devicePixelRatio`). */
+    devicePixelRatio?: number;
+}
+export interface Viewer {
+    load(source: ArrayBuffer | Uint8Array | Blob | string): Promise<void>;
+    readonly zoom: number;
+    setZoom(zoom: number, opts?: {
+        anchor?: {
+            x: number;
+            y: number;
+        };
+    }): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    fit(mode: "page" | "width"): void;
+    readonly minZoom: number;
+    readonly maxZoom: number;
+    readonly scroll: {
+        x: number;
+        y: number;
+    };
+    scrollTo(x: number, y: number): void;
+    scrollBy(dx: number, dy: number): void;
+    readonly pageCount: number;
+    readonly currentPage: number;
+    goToPage(index: number): void;
+    layoutMode(mode?: LayoutMode): LayoutMode;
+    renderPageThumbnail(index: number, opts?: {
+        width?: number;
+    }): Promise<SessionRaster>;
+    on<K extends keyof ViewerEvents>(event: K, listener: (payload: ViewerEvents[K]) => void): () => void;
+    dispose(): void;
+}
+export declare function createViewer(options: CreateViewerOptions): Promise<Viewer>;