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.
The wasm session under the Viewer — raw renderer-core, no input handling.
In short ViewerSession (from @paged-media/sdk) is the WebGPU session that
the friendly Viewer API wraps. It loads IDML, reports load diagnostics, lays
out pages, and renders — either to a canvas via present(...) or to raw RGBA
bytes via render_page_to_bytes(...). It has no camera state, no event system,
and no gesture handling; those live in the Viewer wrapper. Reach for the
session directly only when you are building your own viewer shell or rendering
headlessly.
When to use it
- Use the
Viewerwrapper for almost everything — it owns the camera, events, input, and lifecycle. - Use
ViewerSessiondirectly when you need to drive presentation yourself (your own camera/scroll model), render in a worker over anOffscreenCanvas, or produce rasters without any on-screen surface.
Shape
const session = await ViewerSession.new(); // acquires a WebGPU adapter
const diags = session.load(idmlBytes); // Diagnostics { ok, messages }
if (!diags.ok) report(diags.messages);
session.set_page(0);
session.resize(width, height, devicePixelRatio);
session.present(zoom, scrollX, scrollY, dpr); // render the camera to the canvasDiagnostics carry structured messages (a severity, a code, and the
originating IDML part), so a malformed document tells you which part failed
rather than failing opaquely — the same diagnostics the
parser produces.
Members
| Member | Signature | Description |
|---|---|---|
| ViewerSession.new | static new(): Promise<ViewerSession> | Construct a session (acquires a WebGPU adapter). |
| ViewerSession.load | load(idml: Uint8Array, font?: Uint8Array): Diagnostics | Parse and build a document; returns load diagnostics (errors/warnings with the originating IDML part). |
| ViewerSession.register_font | register_font(family: string, style: string | undefined, bytes: Uint8Array): void | Register a font face for text layout before loading. |
| ViewerSession.page_count | page_count(): number | Number of pages in the loaded document. |
| ViewerSession.set_page | set_page(index: number): void | Select the page to render in single-page mode. |
| ViewerSession.page_layout | page_layout(): PagesLayout | The page rectangles in point space — the basis for camera math. |
| ViewerSession.present | present(zoom: number, scrollX: number, scrollY: number, dpr: number, onlyPage?: number): Diagnostics | Render the current camera to the bound canvas. |
| ViewerSession.render_to_canvas | render_to_canvas(canvas: OffscreenCanvas): Promise<Diagnostics> | Render to an OffscreenCanvas (worker path). |
| ViewerSession.render_page_to_bytes | render_page_to_bytes(index: number, targetWidthPx: number): Promise<RenderedRaster> | Render one page to RGBA bytes at a target width. |
| ViewerSession.render_to_bytes | render_to_bytes(dpi: number): Promise<RenderedRaster> | Render the current page to RGBA bytes at a DPI. |
| ViewerSession.resize | resize(width: number, height: number, devicePixelRatio: number): void | Resize the render surface. |
Frequently asked questions
Should I use this or createViewer?
createViewer for nearly all apps. ViewerSession only when you are replacing
the camera/input layer or rendering headlessly.
Can it run in a Web Worker?
Yes — render_to_canvas takes an OffscreenCanvas, which is the worker path.
Does it mutate the document? No. The session is render-only. Mutation and scripting are the editor's job — see the scripting layer.
Rendering to pixels
Produce raster output from the SDK without an on-screen canvas — page thumbnails via the Viewer, or full RGBA/PNG rasters via ViewerSession and Inspector.
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.