Initialization

Your license token. A valid license — development or production — is required: Kernstra.init() verifies it before anything else happens; without one it shows a "License required" popup, rejects with LICENSE_REQUIRED, and never downloads the engine.

Pass the token to init, typically from your build's own variable, or set it where the SDK looks when none is passed: a globalThis.KERNSTRA_LICENSE string, a <meta name="kernstra-license" content="…"> tag, or, in Node, process.env.KERNSTRA_LICENSE. The SDK ships prebuilt, so a bundler cannot substitute an environment variable into it; read the variable in your code. An empty or missing value means "no license given"; only Kernstra.setLicense('') signs out and forgets the cached token.

Development tokens watermark every rendered, printed and exported page with the Kernstra mark, so development output can never ship as production; they may name * and run on any host, or be bound to your local and staging origins. Production tokens are bound to your origins and render clean output.

Secure context. The SDK runs only where the browser provides the Web Crypto API — over HTTPS or on localhost. On a plain-HTTP origin it refuses to start (LICENSE_REQUIRED, reason insecure-context). This holds for offline (air-gapped) licenses too: an intranet deployment needs HTTPS, a self-signed certificate is enough. There is deliberately no fallback for plain HTTP. See Licensing for origins, status checks, outages and what a stopped license means.

A self-hosted copy of pdf-engine.bin — self-hosting licenses only. Online licenses download the engine from the asset store the license names, and there is nothing to configure. A license that includes self-hosting may serve the binaries and the bundled fonts from its own infrastructure; today that is an offline license, which names no store and always self-hosts. Fetch the file once from the store — the path is its digest under the engine folder, as Kernstra.assetDigests.engine names it — and pass where you put it.

Without self-hosting in the license, engineUrl, shaperUrl and subsetterUrl are refused by Kernstra.init() with FEATURE_NOT_LICENSED before anything is fetched. Every load is verified: an engine binary that is not this version's fails with ENGINE_LOAD_FAILED and never executes. A self-hosted copy is not kept in Cache Storage: it is fetched from your URL on each load, so serve it with your own HTTP caching headers. See Engine, binaries and fonts.

URL to render.worker.js, the prebuilt, self-contained worker bundle the package ships at dist/render.worker.js and exposes via the ./render-worker export subpath. It is an ES module and must be served as a same-origin URL — Web Workers cannot be loaded from bare package specifiers at runtime. Either copy it to your static assets (works with every bundler) or, in Vite, import it with the ?url suffix. The worker takes the engine's bytes from the page and makes no request of its own. Unlike engineUrl, it is not a self-hosting option: any license may set it, since the file is your own copy of one the package ships.

When a workerUrl is provided, page rendering moves off the main thread with no viewer configuration change; performance.workerEnabled: false disables it. The worker renders from a copy of the document: under a production license that includes export with clean output it holds the document as edited; under any other license it holds only the bytes you handed over and is stopped at the first change to the document, after which every page renders on the main thread (see Web worker rendering). Without a workerUrl the worker is never created. Enabling it keeps the engine (~4.4 MB) in memory twice, once on each thread, though it is downloaded only once; the worker also holds its own copy of the document. See Web worker rendering.

The page's CSP nonce, carried by every stylesheet the SDK injects — the print frame's included. A style-src without 'unsafe-inline' refuses every <style> the SDK adds unless it carries the page's nonce; pass that nonce once. When styleNonce is not given, the SDK reads the nonce a page declares for its tooling as <meta property="csp-nonce" nonce="…">, the convention Vite and others follow. With a nonce in force the Google Fonts link (tools.sign.webFonts) carries it too, so style-src needs no Google origin. The SDK styles its elements through the CSSOM, never with style="…" markup, so style-src-attr needs nothing.

A value that is not base64 or base64url is refused with INVALID_ARGUMENT. A policy that enforces Trusted Types (require-trusted-types-for 'script') is not supported in 1.0. See Installation and support for the full policy.