API reference
The complete @paged-media/idml-viewer API — every exported function, method, property, event, and type — generated from the package surface, with a live filter.
Every member of the SDK, in one filterable table.
In short this is the full public surface of @paged-media/idml-viewer — the
viewer lifecycle, the camera, page navigation, rendering, events, errors, the
pure camera-math helpers, and every exported type — plus the lower-level
ViewerSession (@paged-media/sdk) and the read-only Inspector
(@paged-media/introspect-wasm). It is generated from the package's API surface,
so it does not drift from the code. Type to filter by name, signature, or
description.
63 members.
Lifecycle
Create and tear down a viewer over a canvas.
| Member | Signature | Description |
|---|---|---|
| createViewer function | createViewer(options: CreateViewerOptions): Promise<Viewer> | Create a viewer bound to a canvas. Initialises the WebGPU device and the renderer-core session; rejects with a ViewerError if WebGPU is unavailable. |
| Viewer.load method | load(source: ArrayBuffer | Uint8Array | Blob | string): Promise<void> | Load an IDML document from bytes, a Blob, or a URL string. Emits `loaded` with the page count when layout is ready. |
| Viewer.dispose method | dispose(): void | Destroy the viewer and release its WebGPU device. Always call on unmount; several viewers on one page each own a device. |
| createSessionFromBundledWasm function | createSessionFromBundledWasm(): Promise<ViewerSessionLike> | Boot a ViewerSession from the wasm bundled with the package — the default session factory createViewer uses. Call directly only to manage the session yourself. |
Camera (zoom & scroll)
Drive the view transform. Zoom is clamped to [minZoom, maxZoom]; scroll is clamped to the content extent.
| Member | Signature | Description |
|---|---|---|
| Viewer.zoom property | readonly zoom: number | The current zoom factor (1 = 100%). |
| Viewer.setZoom method | setZoom(zoom: number, opts?: { anchor?: { x: number; y: number } }): void | Set the zoom factor, optionally anchored about a viewport point so that point stays put. |
| Viewer.zoomIn method | zoomIn(): void | Step zoom up by one notch (toward maxZoom). |
| Viewer.zoomOut method | zoomOut(): void | Step zoom down by one notch (toward minZoom). |
| Viewer.minZoom property | readonly minZoom: number | The smallest allowed zoom factor. |
| Viewer.maxZoom property | readonly maxZoom: number | The largest allowed zoom factor. |
| Viewer.fit method | fit(mode: 'page' | 'width'): void | Fit the current page to the viewport — whole page, or page width. |
| Viewer.scroll property | readonly scroll: { x: number; y: number } | The current scroll offset, in CSS pixels. |
| Viewer.scrollTo method | scrollTo(x: number, y: number): void | Scroll to an absolute offset (clamped to the content extent). |
| Viewer.scrollBy method | scrollBy(dx: number, dy: number): void | Scroll by a relative delta. |
Page navigation & layout
Move between pages and switch how pages are laid out.
| Member | Signature | Description |
|---|---|---|
| Viewer.pageCount property | readonly pageCount: number | Number of pages in the loaded document. |
| Viewer.currentPage property | readonly currentPage: number | The zero-based index of the page currently in view. |
| Viewer.goToPage method | goToPage(index: number): void | Scroll the given page into view and make it current. Emits `pageChanged`. |
| Viewer.layoutMode method | layoutMode(mode?: LayoutMode): LayoutMode | Get or set the layout mode — 'single' (one page) or 'continuous' (a scroll of stacked pages). |
Rendering to pixels
Produce raster output independent of the on-screen canvas.
| Member | Signature | Description |
|---|---|---|
| Viewer.renderPageThumbnail method | renderPageThumbnail(index: number, opts?: { width?: number }): Promise<SessionRaster> | Render one page to an off-screen RGBA raster at a target width — for page rails and thumbnails. |
Events
Subscribe with `viewer.on(event, listener)`; it returns an unsubscribe function.
| Member | Signature | Description |
|---|---|---|
| Viewer.on method | on<K extends keyof ViewerEvents>(event: K, listener: (payload: ViewerEvents[K]) => void): () => void | Subscribe to a viewer event. Returns a disposer that removes the listener. |
| loaded event | loaded: { pageCount: number } | Fired once a document has loaded and laid out. |
| pageChanged event | pageChanged: { page: number } | Fired when the current page changes (via goToPage or scrolling). |
| zoomChanged event | zoomChanged: { zoom: number } | Fired when the zoom factor changes. |
| scrollChanged event | scrollChanged: { x: number; y: number } | Fired when the scroll offset changes. |
| error event | error: ViewerError | Fired on a recoverable viewer error. |
Errors
The viewer reports failures as a typed ViewerError with a stable code.
| Member | Signature | Description |
|---|---|---|
| ViewerError class | class ViewerError extends Error { code: ViewerErrorCode } | Thrown by createViewer/load and emitted on `error`. Inspect `code` rather than the message. |
| ViewerErrorCode type | type ViewerErrorCode = 'GPU_UNAVAILABLE' | 'LOAD_FAILED' | 'RENDER_FAILED' | … | Stable machine-readable error codes — branch on these (e.g. GPU_UNAVAILABLE → show a no-WebGPU fallback). |
Camera helpers (pure functions)
Stateless math exported for building custom navigation UIs — page rails, minimaps, fit buttons.
| Member | Signature | Description |
|---|---|---|
| clampZoom function | clampZoom(zoom: number, limits: ZoomLimits): number | Clamp a zoom factor into [min, max]. |
| clampScroll function | clampScroll(x: number, y: number, viewport: Viewport, extent: ContentExtent): { x: number; y: number } | Clamp a scroll offset to the content extent for a viewport. |
| contentExtent function | contentExtent(layout: SessionPagesLayout, zoom: number): ContentExtent | Total scrollable content size at a given zoom. |
| currentPageAt function | currentPageAt(layout: SessionPagesLayout, scrollY: number): number | Which page is in view at a scroll position (continuous mode). |
| fitPage function | fitPage(page: SessionPageRect, viewport: Viewport, mode: 'page' | 'width'): number | The zoom that fits a page to the viewport. |
| scrollToPage function | scrollToPage(layout: SessionPagesLayout, pageIndex: number, viewport: Viewport): number | The scrollY that brings a page into view. |
| zoomAt function | zoomAt(point, newZoom, currentZoom, scroll): { x: number; y: number } | The scroll offset that keeps a point fixed while zooming about it. |
Types
The exported TypeScript types you compose against.
| Member | Signature | Description |
|---|---|---|
| CreateViewerOptions type | interface CreateViewerOptions { canvas: HTMLCanvasElement | OffscreenCanvas; session?; layoutMode?: LayoutMode; input?: InputOptions } | Options for createViewer — the target canvas, an optional session factory, the initial layout mode, and input behaviour. |
| LayoutMode type | type LayoutMode = 'single' | 'continuous' | Single-page or continuous-scroll page layout. |
| InputOptions type | interface InputOptions { wheelZoom?: boolean; dragPan?: boolean; doubleClickZoom?: boolean; keyboard?: boolean } | Which built-in input gestures the viewer handles. |
| ViewerEvents type | interface ViewerEvents { loaded; pageChanged; zoomChanged; scrollChanged; error } | The event map the `on` method is typed against. |
| Camera type | interface Camera { zoom: number; scroll: { x: number; y: number } } | A view transform — zoom plus scroll offset. |
| Viewport type | interface Viewport { width: number; height: number } | The size of the visible canvas region in CSS pixels. |
| ZoomLimits type | interface ZoomLimits { min: number; max: number } | The clamp range for zoom. |
| SessionRaster type | interface SessionRaster { width: number; height: number; rgba: Uint8Array } | A rendered raster — tightly-packed RGBA8 plus its dimensions. |
| SessionPagesLayout type | interface SessionPagesLayout { gapPt: number; pages: SessionPageRect[] } | Page rectangles in point space, with the inter-page gap. |
| SessionPageRect type | interface SessionPageRect { index: number; yPt: number; widthPt: number; heightPt: number } | One page's position and size in point space. |
| SessionDiagnostics type | interface SessionDiagnostics { ok: boolean; messages: SessionDiagnostic[] } | The result of a load/present call — overall ok plus structured messages. |
| SessionDiagnostic type | interface SessionDiagnostic { severity: 'error' | 'warning' | 'info'; code: string; message: string; part?: string; line?: number } | One diagnostic, with the originating IDML part where known. |
| ViewerSessionLike type | interface ViewerSessionLike { load(...): SessionDiagnostics; present(...): SessionDiagnostics; … } | The structural contract createViewer expects of a session — implement it to supply a custom session. |
ViewerSession (low-level, @paged-media/sdk)
The wasm session `createViewer` wraps. Use it directly only when you need raw control — most apps use the Viewer wrapper above.
| Member | Signature | Description |
|---|---|---|
| ViewerSession.new method | static new(): Promise<ViewerSession> | Construct a session (acquires a WebGPU adapter). |
| ViewerSession.load method | load(idml: Uint8Array, font?: Uint8Array): Diagnostics | Parse and build a document; returns load diagnostics (errors/warnings with the originating IDML part). |
| ViewerSession.register_font method | register_font(family: string, style: string | undefined, bytes: Uint8Array): void | Register a font face for text layout before loading. |
| ViewerSession.page_count method | page_count(): number | Number of pages in the loaded document. |
| ViewerSession.set_page method | set_page(index: number): void | Select the page to render in single-page mode. |
| ViewerSession.page_layout method | page_layout(): PagesLayout | The page rectangles in point space — the basis for camera math. |
| ViewerSession.present method | present(zoom: number, scrollX: number, scrollY: number, dpr: number, onlyPage?: number): Diagnostics | Render the current camera to the bound canvas. |
| ViewerSession.render_to_canvas method | render_to_canvas(canvas: OffscreenCanvas): Promise<Diagnostics> | Render to an OffscreenCanvas (worker path). |
| ViewerSession.render_page_to_bytes method | render_page_to_bytes(index: number, targetWidthPx: number): Promise<RenderedRaster> | Render one page to RGBA bytes at a target width. |
| ViewerSession.render_to_bytes method | render_to_bytes(dpi: number): Promise<RenderedRaster> | Render the current page to RGBA bytes at a DPI. |
| ViewerSession.resize method | resize(width: number, height: number, devicePixelRatio: number): void | Resize the render surface. |
Inspector (read-only, @paged-media/introspect-wasm)
Inspect a document's scene tree and properties, and render single pages, without a canvas — handy for tests and tooling.
| Member | Signature | Description |
|---|---|---|
| Inspector class | new Inspector(idml: Uint8Array) | Construct an inspector over a document's bytes. |
| Inspector.tree method | tree(): string | The scene tree as JSON. |
| Inspector.properties method | properties(nodeJson: string): string | Property descriptors for an addressed node. |
| Inspector.renderPage method | renderPage(pageIndex: number, dpi: number): Uint8Array | Render one page to PNG bytes. |
| describeCatalog function | describeCatalog(): string | The engine capability catalog as JSON — no document required. The source the docs' generated reference tables read. |
Frequently asked questions
Is this list hand-maintained?
No. It is generated into .generated/sdk-catalog.json and rendered here. When the
package gains or changes a member, this page changes on the next build.
Which package do I install?
@paged-media/idml-viewer for the ergonomic Viewer API. It depends on the
@paged-media/sdk wasm session under the hood; you rarely call ViewerSession
directly. The Inspector from @paged-media/introspect-wasm is a separate,
read-only tool for inspection and tests.
Where do I see these in action? The camera & navigation page drives most of this API in a live viewer you can operate.
ViewerSession (low-level)
The wasm session that createViewer wraps — load, set page, present a camera, render to a canvas or to bytes. Use it directly only when you need raw control.
Scripting with paged.*
The Boa-based scripting layer — a sandboxed ECMAScript surface for reading and authoring a paged document through the paged.* host API. The full surface is generated from the engine catalog.