Viewer API
Page presentation, Reader, and Inspector controllers from @imposia/viewer.
@imposia/viewer presents documents. mountPageViewer presents the canonical iframe of a committed Core page document. It does not run pagination.
mountPageViewer
mountPageViewer(container: HTMLElement, document: PageDocument, options?: PageViewerOptions): PageViewerController;
validatePageViewerOptions(document: PageDocument, options?: PageViewerOptions): void;Validation checks the document, sandbox, theme, and optional reader synchronously; validatePageViewerOptions runs the same checks without mounting.
Mount only after Core commits, in the iframe's own container
mountPageViewer requires a committed PageDocument, and container must be the canonical iframe's current parent — any other element throws. The Viewer presents Core's iframe in place; it never moves, clones, or recreates it.
PageViewerOptions accepts mode?: "continuous" | "single" | "spread", spread?: { cover? }, zoom?, controls?, theme?, inspector?, and reader?. controls defaults to true; set it to false to keep the presentation controller without the built-in brand rail. A theme is a map of CSS properties whose names begin --imposia-viewer-.
PageViewerController
| Member | Returns | Effect or constraint |
|---|---|---|
goToPage(page), nextPage(), previousPage() | void | Clamp/advance within current pages or effective spreads. |
setZoom(zoom) | void | Rounds/clamps finite input. |
setMode(mode), setSpreadCover(cover) | void | Change requested mode/cover layout. |
setTheme(theme?) | void | Replace or clear Viewer variables. |
subscribe(listener) | () => void | Immediately emits state, then emits presentation changes; returns an unsubscribe function. |
refresh(document) | void | Requires the same iframe and a newer generation; throws after destruction/invalid input. |
print() | Promise<void> | Rejects after destruction or when the iframe is unavailable. |
destroy() | void | Removes Viewer bindings/UI and restores the Core iframe container. Idempotent. |
state | PageViewerState | Page, count, zoom, requested/effective mode, status, and generation. |
reader | PublicationReaderController | undefined | Present when reader options were supplied. |
inspector | ViewerInspectorController | undefined | Present when inspector: true. |
Viewer CSS is scoped to .imposia-viewer; the host owns body styles, preview dimensions, background, and surrounding scrolling.
Fit, zoom, and keyboard policy (0.7.0)
| Option | Default | Behavior |
|---|---|---|
fit | "shrink" | Shrinks zoomed pages to available width, without enlarging them. "width" fits in both directions and multiplies that fitted size by zoom. "none" preserves CSS page size before zoom, so narrow hosts must accommodate overflow. |
zoomable | true | false disables zoom buttons, zoom shortcuts, and setZoom; an initial zoom still applies. |
keyboard | true | false disables Viewer keyboard shortcuts, while buttons and controller methods remain available. |
The Core iframe's iframeTitle remains unchanged when Viewer mounts. In React, changing these three policies remounts Viewer presentation and preserves the current page. Existing defaults are unchanged.
Publication Reader and deep links
Reader options require the PublicationController that owns the exact displayed PublicationDocument; they may include initialDeepLink and onDeepLinkChange.
PublicationReaderController member | Returns / effect |
|---|---|
openTableOfContents(), closeTableOfContents(), toggleTableOfContents() | Control the outline panel. |
openThumbnails(), closeThumbnails(), toggleThumbnails() | Control thumbnails. |
selectThumbnail(thumbnail) | Goes to a current-generation thumbnail; foreign thumbnails throw. |
openSearch(), closeSearch(), toggleSearch() | Control search. |
search(query) | readonly PublicationSearchResult[]. |
nextSearchResult(), previousSearchResult() | PublicationSearchResult | undefined. |
selectSearchResult(result) | Selects/navigates to a result. |
navigate(destination) | Validates, navigates, and emits a deep link. |
restoreDeepLink(value) | PublicationDestination | undefined; resolves and navigates. |
state | Panel state, thumbnails, destination/deep link, query, results, and active result index. |
All reader methods throw after destruction. Opening one auxiliary panel closes the others. PublicationThumbnail exposes page, generation, dimensions, and previewLineCount.
serializePublicationDeepLink(destination: PublicationDestination): string;
restorePublicationDeepLink(value: string, controller: PublicationController): PublicationDestination | undefined;Serialization produces a versioned value from the destination ID. The standalone restore helper accepts only canonical encoding and resolves against the current generation; unlike the reader method, it does not navigate.
Viewer Inspector
ViewerInspectorController member | Returns / effect |
|---|---|
open(), close(), toggle() | Control diagnostics; throw after destruction. |
select(warning) | Goes to/highlights a located warning; foreign-generation warnings throw. |
state | { open, warnings, selected }. |
The Inspector panel shares the auxiliary-panel slot with Contents, Search, and Thumbnails: opening any one closes the others. It is hidden for print and absent from EPUB export.