@0k/pdf-viewer 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentin Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,255 @@
-# Temporary Holding Version
+# @0k/pdf-viewer
+
+## Purpose
+
+`@0k/pdf-viewer` is a plain-TypeScript in-page PDF viewer. It owns the
+toolbar, the page canvas, paging, zoom, pinch and pan gestures, the fit
+policy, error and retry, accessible controls, scoped styles and
+single-owner teardown. Hosts own the PDF URL and its access policy,
+where the viewer mounts, the affordance around it, and translated
+labels.
+
+It renders on `@0k/pdfjs-legacy-runtime`, which owns the PDF.js
+compatibility policy (exact `pdfjs-dist` 3.11.174 pin, legacy build,
+worker wiring, single-owner teardown type). This package never imports
+`pdfjs-dist`.
+
+MIT licensed.
+
+## Install
+
+``` bash
+npm install @0k/pdf-viewer
+```
+
+npm ≥7 installs the exact peer `@0k/pdfjs-legacy-runtime` automatically.
+The host's bundler sees one copy of the runtime and emits one PDF.js
+worker asset.
+
+## Usage
+
+``` typescript
+import { mountPdfViewer } from '@0k/pdf-viewer';
+import '@0k/pdf-viewer/style.css';
+
+const owner = mountPdfViewer(host, {
+  url: 'https://example.com/manual.pdf', // PDF.js range-loads it
+  fit: 'width',                      // or 'page'
+  interaction: 'scroll',            // in-flow; 'gestures' (default) for full screen
+  labels: { previous: 'Page précédente' },
+});
+owner.next();
+await owner.destroy();               // releases the worker; idempotent
+```
+
+The host decides when to mount (lazily, on an "open" click, so a
+collapsed widget costs nothing) and where; the viewer fills its host
+element and is in-flow. A host wanting a full-screen reader wraps it in
+its own overlay.
+
+## Options
+
+`mountPdfViewer(host, options)` mounts into an `HTMLElement` and starts
+loading. The required `url` is passed verbatim to PDF.js; hosts own
+access policy, including any cross-origin permissions. Optional fields:
+
+- `fit`: `"width"` (default) fills the surface width; `"page"` fits the
+  whole page within the surface box using the smaller width/height
+  ratio. Both policies follow surface size changes automatically; resize
+  bursts are debounced before the page is re-rendered.
+- `zoom`: an object with `min` (0.5), `max` (2), `step` (0.25) and
+  `initial` (1). Values are fractions of the fitted size; the initial
+  value and subsequent zoom changes are clamped to the bounds.
+- `maxDpr`: backing-canvas device pixel ratio cap, default 2.
+- `interaction`: `"gestures"` (default) owns drag-to-pan, pinch and any
+  wheel zoom, and supports double-click reset. `"scroll"` leaves
+  one-finger swipes and bare wheel scrolling to the browser while pinch
+  and Ctrl/⌘+wheel zoom. `"none"` leaves only the toolbar controls
+  active.
+- `labels`: partial overrides of the English defaults below.
+- `onStateChange`: callback receiving a `PdfViewerState` snapshot when
+  loading starts, a raster commits, or an error occurs. The snapshot has
+  `status` (`"loading"`, `"ready"` or `"error"`), `page`, `pageCount`,
+  `zoom` and `error` (a string or `null`). A ready document can still be
+  awaiting its first raster; the canvas stays hidden until that commit.
+
+The zoom live region changes when a gesture settles (last pointer lifted
+or 250 ms of wheel quiet), not during movement. Toolbar zoom changes the
+readout immediately.
+
+### Labels
+
+`labels` accepts any subset of `PdfViewerLabels`:
+
+| Key         | English default               |
+|-------------|-------------------------------|
+| `controls`  | PDF controls                  |
+| `previous`  | Previous page                 |
+| `next`      | Next page                     |
+| `zoomOut`   | Zoom out                      |
+| `zoomIn`    | Zoom in                       |
+| `zoomReset` | Reset zoom                    |
+| `reset`     | Reset zoom and pan            |
+| `retry`     | Retry                         |
+| `loading`   | Loading…                      |
+| `failed`    | Failed to load PDF: %{reason} |
+
+The `%{reason}` placeholder in `failed` is replaced by the literal error
+message. Labels are rendered as text, not HTML; dollar sequences in an
+error reason are preserved.
+
+### Owner handle
+
+`mountPdfViewer` returns a `PdfViewerOwner` with a readonly `host` and:
+
+- `state()`: return the current state snapshot, including live gesture
+  zoom.
+- `goTo(page)`: floor and clamp the page number to the document range.
+- `next()` and `previous()`: move one page within that range.
+- `setZoom(zoom)`: clamp zoom, update the readout and re-render.
+- `resetView()`: restore zoom 1 (clamped to the bounds), not `initial`,
+  and clear pan.
+- `reload()`: return a promise for releasing the current document and
+  loading the same URL again. Superseded loads cannot overwrite a newer
+  load; startup waits for preceding task teardowns to settle.
+- `destroy()`: remove the DOM and return a promise for worker teardown.
+  Idempotent, including before loading completes.
+
+Paging and zoom methods do nothing unless the document is ready.
+Mounting again on the same host replaces its viewer and waits for the
+previous owner's teardown before creating a new worker. An old owner
+cannot destroy the replacement.
+
+### Exported constants
+
+- `PDF_VIEWER_CLASS`: `"pdf-viewer"`, the viewer root class.
+- `PDF_VIEWER_MIN_ZOOM`: 0.5.
+- `PDF_VIEWER_MAX_ZOOM`: 2.
+- `PDF_VIEWER_ZOOM_STEP`: 0.25.
+- `PDF_VIEWER_DEFAULT_ZOOM`: 1.
+- `PDF_VIEWER_MAX_DPR`: 2.
+- `PDF_VIEWER_WHEEL_FACTOR`: 0.9 per 100 CSS pixels of wheel-down
+  movement; wheel-up reverses the factor. Line deltas use 16 CSS pixels
+  per line, and page deltas use the surface's client height.
+- `PDF_VIEWER_WHEEL_SETTLE_MS`: 250.
+- `DEFAULT_PDF_VIEWER_LABELS`: the English label object above.
+
+## Theming
+
+Import `@0k/pdf-viewer/style.css` separately; importing the JavaScript
+does not inject styles. Override these properties on the `.pdf-viewer`
+root with a selector loaded after the package stylesheet:
+
+| Property                               | Default                   |
+|----------------------------------------|---------------------------|
+| `--pdf-viewer-surface`                 | transparent               |
+| `--pdf-viewer-page-background`         | \#fff                     |
+| `--pdf-viewer-page-border`             | rgba(128, 128, 128, 0.2)  |
+| `--pdf-viewer-page-radius`             | 4px                       |
+| `--pdf-viewer-surface-max-height`      | none                      |
+| `--pdf-viewer-button-size`             | 2.25rem                   |
+| `--pdf-viewer-button-radius`           | 6px                       |
+| `--pdf-viewer-button-background`       | rgba(128, 128, 128, 0.12) |
+| `--pdf-viewer-button-background-hover` | rgba(128, 128, 128, 0.24) |
+| `--pdf-viewer-button-border`           | rgba(128, 128, 128, 0.25) |
+| `--pdf-viewer-button-color`            | inherit                   |
+| `--pdf-viewer-focus`                   | rgba(118, 227, 234, 0.6)  |
+| `--pdf-viewer-info`                    | inherit                   |
+| `--pdf-viewer-error`                   | rgb(220, 90, 90)          |
+| `--pdf-viewer-error-background`        | rgba(239, 68, 68, 0.15)   |
+| `--pdf-viewer-error-border`            | rgba(239, 68, 68, 0.35)   |
+| `--pdf-viewer-reset-background`        | rgba(0, 0, 0, 0.55)       |
+| `--pdf-viewer-reset-background-hover`  | rgba(0, 0, 0, 0.75)       |
+| `--pdf-viewer-reset-color`             | \#fff                     |
+| `--pdf-viewer-gap`                     | 6px                       |
+
+Toolbar button hit areas retain a 44px minimum regardless of button
+size. The viewer fills its host's width and grows with the page unless
+bounded. Set `--pdf-viewer-surface-max-height` (for example `60vh`) to
+cap the surface, or make the root a flex child with a bounded height.
+The surface can shrink (`min-height: 0`); toolbar and status do not
+flex. Scroll and toolbar-only modes use native overflow scrolling;
+gesture mode hides overflow and pans with a transform. Fit-to-page uses
+the resulting surface box, so a full-screen host must provide its own
+height constraint.
+
+## Security
+
+The pinned `pdfjs-dist` 3.11.174 is affected by CVE-2024-4367: a crafted
+font can execute JavaScript when evaluation is enabled. The [runtime's
+security note](https://github.com/0k/pdfjs-legacy-runtime#security)
+explains its mitigation: every document is loaded with
+`isEvalSupported: false`, applied after caller options so it cannot be
+re-enabled. A Content-Security-Policy without `'unsafe-eval'` provides a
+second layer. The version remains pinned for Chrome 91 compatibility;
+the mitigation does not remove the version-based `npm audit` advisory.
+
+PDF.js also has an optional `canvas` dependency for Node.js rendering.
+Its install tooling pulls in `tar` advisories; it does not enter the
+browser bundle. Browser-only hosts can skip optional dependencies with
+`npm install --omit=optional`, or use an npm `overrides` entry to select
+a patched transitive `tar` version compatible with their install
+tooling. The latter changes installation tooling, not the browser PDF
+runtime.
+
+## Development
+
+``` bash
+npm install
+npm run check   # unit tests, strict typecheck, build, Chrome 91 audit
+```
+
+With Python Playwright and system Chrome available,
+`npm run test:browser` bundles the built package in a temporary host and
+verifies real PDF.js worker loading, raster pixels, rapid
+zoom/reload/replacement, CSS, teardown, scroll reachability, fitted
+borders and gesture-settle positions.
+
+To try an unreleased change in a host, link the checkout there:
+`npm link <path-to-pdf-viewer>`.
+
+
+## Changelog
+
+
+### 0.2.0 (2026-10-28)
+
+#### New
+
+* Add the PDF page viewer with paging, zoom, gestures, fit, retry and teardown. [Valentin Lab]
+
+  ``mountPdfViewer(host, options)`` mounts a toolbar and a page canvas in the
+  host element and returns an owner handle: the ``host`` it mounted in, and
+  ``state``, ``goTo``, ``next``, ``previous``, ``setZoom``, ``resetView``,
+  ``reload`` and ``destroy``.  The host passes a URL; the PDF reader
+  range-loads it through ``@0k/pdfjs-legacy-runtime``.  An ``interaction``
+  option chooses full gestures (pinch, pan, wheel zoom), in-flow scrolling with
+  pinch zoom only, or the toolbar only (``none``).  Load and render errors show
+  a retry control.  Labels default to English and are configurable.  Styles
+  are scoped under the viewer root, themed only through ``--pdf-viewer-*``
+  custom properties, and imported by the host from
+  ``@0k/pdf-viewer/style.css``.
+
+  Contract:
+  - The loading task is the only owner of worker teardown.  A reload, or a
+    second mount on the same host, starts its worker only after every
+    previous teardown settled; a superseded load never overwrites a newer
+    one; destroy releases the canvas storage.
+  - The owner handle is a frozen facade, safe to keep in a host's reactive
+    state.
+  - The page on screen is never cleaned up, and pages render off-screen and
+    are committed in one step, so Android WebView 91 never shows a blank
+    canvas.
+  - Fitting accounts for the surface padding and borders and follows surface
+    resizes and the appearance of scrollbars, and settles when a scrollbar
+    toggles; a zoomed page stays reachable by scrolling in scroll and
+    toolbar-only modes.
+  - Wheel zoom scales with the scrolled distance and re-renders once, even
+    when a pointer press interrupts it.  A settling gesture keeps the page in
+    place, and the zoom readout changes once the gesture settles (at once for
+    toolbar zoom).
+  - Error reasons are shown verbatim, an undefined label keeps its English
+    default, and a throwing ``onStateChange`` callback is logged without
+    affecting the viewer.
+
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/** Class of the viewer root; every style is scoped under it. */
+export declare const PDF_VIEWER_CLASS = "pdf-viewer";
+/** Default zoom bounds and toolbar step (a fraction of the fitted size). */
+export declare const PDF_VIEWER_MIN_ZOOM = 0.5;
+export declare const PDF_VIEWER_MAX_ZOOM = 2;
+export declare const PDF_VIEWER_ZOOM_STEP = 0.25;
+export declare const PDF_VIEWER_DEFAULT_ZOOM = 1;
+/**
+ * Cap on the effective device pixel ratio used to size the backing
+ * canvas. 2 is sharp enough while bounding memory on a 3× phone.
+ */
+export declare const PDF_VIEWER_MAX_DPR = 2;
+/** Zoom factor for 100 CSS pixels of wheel-down movement. */
+export declare const PDF_VIEWER_WHEEL_FACTOR = 0.9;
+/** Milliseconds of quiet that end a wheel burst — a wheel has no "up". */
+export declare const PDF_VIEWER_WHEEL_SETTLE_MS = 250;
+export interface PdfViewerLabels {
+    /** `aria-label` of the toolbar. */
+    readonly controls: string;
+    readonly previous: string;
+    readonly next: string;
+    readonly zoomOut: string;
+    readonly zoomIn: string;
+    /** Back to the fitted size (toolbar). */
+    readonly zoomReset: string;
+    /** Back to the resting view after a gesture (floating control). */
+    readonly reset: string;
+    readonly retry: string;
+    readonly loading: string;
+    /** Failure sentence; `%{reason}` is replaced by the error message. */
+    readonly failed: string;
+}
+export declare const DEFAULT_PDF_VIEWER_LABELS: PdfViewerLabels;
+/**
+ * How the resting (100 %) zoom relates to the surface:
+ * - `width`: the page fills the surface width; taller pages scroll.
+ *   Right for an in-flow reader in a prose column.
+ * - `page`: the whole page fits the surface box (smaller ratio wins).
+ *   Right for a full-screen reader, where cropping a scanned page would
+ *   hide the margin a stamp or signature sits in.
+ */
+export type PdfViewerFit = "width" | "page";
+export type PdfViewerInteraction = "gestures" | "scroll" | "none";
+export type PdfViewerStatus = "loading" | "ready" | "error";
+export interface PdfViewerState {
+    readonly status: PdfViewerStatus;
+    readonly page: number;
+    readonly pageCount: number;
+    readonly zoom: number;
+    readonly error: string | null;
+}
+export interface PdfViewerOptions {
+    /** The document URL, handed verbatim to PDF.js (range-loaded). */
+    readonly url: string;
+    readonly fit?: PdfViewerFit;
+    readonly labels?: {
+        readonly [K in keyof PdfViewerLabels]?: string | undefined;
+    };
+    readonly zoom?: {
+        readonly min?: number;
+        readonly max?: number;
+        readonly step?: number;
+        readonly initial?: number;
+    };
+    readonly maxDpr?: number;
+    /**
+     * How the page surface reacts to pointers and the wheel:
+     * - `gestures` (default): the surface owns every gesture — drag pans,
+     *   pinch and any wheel zoom. Right for a full-screen reader, where
+     *   there is nothing else to scroll.
+     * - `scroll`: the BROWSER keeps scrolling (one-finger swipe, bare
+     *   wheel), so a reader embedded in a scrolling page never traps the
+     *   reader's finger; pinch and Ctrl/⌘+wheel (what a touchpad pinch
+     *   emits) still zoom the page.
+     * - `none`: toolbar only.
+     */
+    readonly interaction?: PdfViewerInteraction;
+    readonly onStateChange?: (state: PdfViewerState) => void;
+}
+/** The handle a host keeps for the viewer it mounted. */
+export interface PdfViewerOwner {
+    readonly host: HTMLElement;
+    state(): PdfViewerState;
+    goTo(page: number): void;
+    next(): void;
+    previous(): void;
+    setZoom(zoom: number): void;
+    /** Restore the resting view: zoom 1, no pan. */
+    resetView(): void;
+    /** Release the current document (if any) and load the URL again. */
+    reload(): Promise<void>;
+    /**
+     * Release the loading task (the worker), remove the viewer DOM and
+     * stop listening. Idempotent; safe on a viewer that never loaded.
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * Mount a viewer into `host` and start loading `options.url`.
+ *
+ * Mounting twice on one host replaces the previous viewer, releasing its
+ * loading task before the replacement starts its worker. The returned
+ * owner acts only on the viewer it mounted.
+ */
+export declare function mountPdfViewer(host: HTMLElement, options: PdfViewerOptions): PdfViewerOwner;