API Reference

Choose the React, Core, or Viewer contract you need, with shared package and lifecycle guidance.

Use this reference after you have rendered a first document. Choose a package page for exact components, controllers, options, and lifecycle constraints.

Package map

Package	Purpose	Primary APIs
`@imposia/react`	React integration	`ImposiaPageViewer`, `ImposiaDocument`, `ImposiaPublicationViewer`, both lifecycle hooks
`@imposia/core`	Framework-neutral pagination and publications	`mountPageDocument`, `mountPublication`, `prepareDocument`
`@imposia/viewer`	Present committed pages or load a PDF	`mountPageViewer`, `mountViewer`, deep-link helpers
`@imposia/client`	Combined framework-neutral entry point	Re-exports the primary Core and Viewer integration APIs

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

Choose an API

React API

Components, hooks, and imperative handles for React applications.

Core API

Framework-neutral page document and Publication controllers.

Viewer API

Page presentation, Reader, Inspector, and the independent PDF viewer.

Lifecycle and errors

Situation	Result
First generation pending	`current` is `undefined`; React state is `loading`.
Update pending after commit	The previous commit stays visible and in React state.
Newer update starts	Older active generation rejects with `AbortError`.
Caller aborts	Related generation/export rejects with DOM `AbortError`.
Update fails after commit	Promise rejects; previous commit remains current.
Controller destroys	Work aborts, resources/frame are released, and `current` clears.

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.