API reference

Use this reference after you have rendered a first document. It covers the browser APIs application code calls directly, including every controller and React handle method. Core and Viewer require DOM APIs and do not run during server-side rendering.

Package map

Import @imposia/react/styles.css once when you use the React package.

React components and hooks

ImposiaPageViewer and ImposiaDocument

ImposiaPageViewer mounts a Core page document, then binds the page Viewer after the first commit. ImposiaDocument is a compatibility wrapper with the same public props and handle types: ImposiaDocumentProps = ImposiaPageViewerProps and ImposiaDocumentHandle = ImposiaPageViewerHandle.

const viewer = useRef<ImposiaPageViewerHandle>(null);

<ImposiaPageViewer
  ref={viewer}
  source={{ html: "<main><h1>Report</h1></main>" }}
  documentOptions={{ page: { size: "A4", margin: "18mm" } }}
  viewerOptions={{ mode: "single", inspector: true }}
  onError={console.error}
/>;

ImposiaPageViewerHandle

ImposiaPublicationViewer

const publication = useRef<ImposiaPublicationViewerHandle>(null);

<ImposiaPublicationViewer
  ref={publication}
  snapshot={{
    metadata: { title: "Guide", language: "en" },
    entries: [{ id: "intro", title: "Introduction", html: "<h1>Introduction</h1>" }],
  }}
/>;

Its required snapshot prop accepts PublicationSnapshot. Optional props are snapshotRevision, publicationOptions, publicationOptionsRevision, viewerOptions (without reader), readerOptions (without controller), className, style, onReady, onError, and onStateChange. Revision props force updates/remounts as their names indicate. The component supplies the reader/controller binding.

ImposiaPublicationViewerHandle

All actions except current and resolveDestination throw after unmount. Reader actions also throw before the Publication reader is ready.

useImposiaDocument and useImposiaPublication

useImposiaDocument(props: UseImposiaDocumentProps): UseImposiaDocumentResult;
useImposiaPublication(props: UseImposiaPublicationProps): UseImposiaPublicationResult;

Both hooks return a hostRef, lifecycle state, and a controller that is undefined until the mount effect creates it. Attach hostRef to one div. A loading or error state can retain the last committed document/publication.

useImposiaDocument accepts the page component's source, revision, options, and callbacks. HTML sources update when HTML/base URL changes; light-DOM sources update when node identity changes. sourceRevision forces an update, and documentOptionsRevision remounts the controller.

useImposiaPublication accepts the publication component's snapshot, revision, options, and callbacks. It updates when the snapshot reference or snapshotRevision changes; publicationOptionsRevision remounts the controller. Both hooks destroy their controller on cleanup and treat AbortError as lifecycle cancellation.

function Article({ html }: { html: string }) {
  const { hostRef, state } = useImposiaDocument({ source: { html } });
  return <div ref={hostRef} aria-busy={state.status === "loading"} />;
}

Core page document

mountPageDocument

mountPageDocument(
  container: HTMLElement,
  source: PageSource,
  options?: PageDocumentOptions,
): PageDocumentController;

The function appends one canonical iframe immediately, starts a staged generation, and returns synchronously. Await ready before reading the first document.

const controller = mountPageDocument(host, { html: "<article><h1>Hello</h1></article>" });
const pageDocument = await controller.ready;

PageSource is { html: string; baseUrl?: string } or { lightDom: Element | DocumentFragment; baseUrl?: string }.

An AssetResolver receives { url, kind, baseUrl, signal } and resolves to { status: "resolved", bytes, mimeType, resolvedUrl? } or { status: "blocked", reason? }.

PageDocumentController

PageDocument

EPUB options require metadata: { title, language, identifier, modified? } and optionally accept signal and { maxEntries?, maxBytes? } limits.

Core utilities

prepareDocument(html: string, options?: PrepareDocumentOptions): PreparedDocument;
pageWarningTargetBounds(document: PageDocument, warning: PageWarning): PageWarningTargetBounds | undefined;
hasPageDocumentFrameSandbox(iframe: HTMLIFrameElement): boolean;
selectBlankMarkers(markers: PageSideConstraint[], pages: Map<number, number>): number[];

• prepareDocument synchronously normalizes/sanitizes HTML and returns { html, headerTemplate?, footerTemplate?, warnings }. Its options are headerTemplate, footerTemplate, and allowRemoteResources. API decoration options override embedded templates.
• pageWarningTargetBounds returns live { left, top, width, height } in iframe viewport coordinates. It returns undefined for a foreign/unlocated warning.
• hasPageDocumentFrameSandbox is true only for the exact public sandbox token set (allow-same-origin and allow-modals).
• selectBlankMarkers returns marker IDs needing a blank to satisfy left/right parity, accounting for prior selections. It throws when a marker has no page mapping.

Core publication

mountPublication

mountPublication(
  container: HTMLElement,
  snapshot: PublicationSnapshot,
  options?: PublicationOptions,
): PublicationController;

It composes ordered entries into one page sequence and returns synchronously. Invalid snapshots or Publication extensions can throw during mounting.

const controller = mountPublication(host, {
  metadata: { title: "Handbook", language: "en" },
  entries: [
    { id: "cover", title: "Cover", html: "<h1>Handbook</h1>" },
    { id: "start", title: "Start", html: "<h1>Start</h1><p>First step.</p>" },
  ],
});
const publication = await controller.ready;

PublicationSnapshot contains metadata: { title, language?, identifier? } and ordered entries. Each entry requires id, title, optional baseUrl, and exactly one of html or lightDom. PublicationOptions contains PageDocumentOptions except that extensions accepts only PublicationExtension[].

PublicationController

PublicationDocument extends PageDocument with committed metadata, entries, and nested outline. Each entry has an inclusive global pageRange. A PublicationDestination is { id, entryId, page, generation }; it is generation-bound. A search result is { entry, page, excerpt, destination }.

Viewer page documents, PDF, reader, and inspector

mountPageViewer

mountPageViewer(container: HTMLElement, document: PageDocument, options?: PageViewerOptions): PageViewerController;
validatePageViewerOptions(document: PageDocument, options?: PageViewerOptions): void;

Mount only after Core commits. container must be the canonical iframe's current parent. Validation checks the document, sandbox, theme, and optional reader synchronously.

PageViewerOptions accepts mode?: "continuous" | "single" | "spread", spread?: { cover? }, zoom?, theme?, inspector?, and reader?. A theme is a map of CSS properties whose names begin --imposia-viewer-.

PageViewerController

Narrow containers can report mode: "spread" with effectiveMode: "single".

Publication reader and deep links

Reader options require the PublicationController that owns the exact displayed PublicationDocument; they may include initialDeepLink and onDeepLinkChange.

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

mountViewer for PDF

mountViewer(container: HTMLElement, source: ViewerSource, options?: ViewerOptions): ViewerController;
type ViewerSource = Uint8Array | ArrayBuffer | string | { pdf: Uint8Array };

This separate Viewer loads/rasterizes PDF pages with PDF.js. Options are mode?: "continuous" | "single", zoom?, workerSrc?, and theme?. It returns immediately in loading; failures set state.status to error and populate state.error.

Lifecycle and errors

ImposiaError extends Error with readonly code: string. Handle cancellation separately from reportable failures:

try {
  await controller.update(nextSource, { signal });
} catch (error) {
  if (error instanceof DOMException && error.name === "AbortError") return;
  if (error instanceof ImposiaError) console.error(error.code, error.message);
  throw error;
}

Viewer methods generally ignore calls that cannot operate in their current state. Ownership-sensitive calls throw: page Viewer mount/refresh validate the canonical iframe, Publication navigation rejects stale destinations, reader selection rejects foreign thumbnails, and inspector selection rejects foreign warnings.