@zinejs/pdf 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @zinejs/pdf
+
+PDF content source for [zinejs](https://github.com/), powered by [pdf.js](https://mozilla.github.io/pdf.js/). Renders PDF pages to canvases that the zinejs core paints as a flipbook.
+
+## Install
+
+```bash
+npm install @zinejs/core @zinejs/pdf pdfjs-dist
+```
+
+`pdfjs-dist` is a **peer dependency** — you install it, and the plugin loads it lazily so it never lands in the core bundle.
+
+## Usage
+
+```js
+import { Zine } from '@zinejs/core';
+import { PdfSource } from '@zinejs/pdf';
+
+const book = new Zine(document.getElementById('book'), {
+  source: new PdfSource('document.pdf'),
+});
+```
+
+Under a bundler that's all you need — the pdf.js worker is resolved for you.
+
+## The pdf.js worker (`workerSrc`)
+
+pdf.js parses and rasterizes in a Web Worker, a separate file the host must locate. By default `PdfSource` resolves it to:
+
+```js
+new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url).href
+```
+
+Resolution precedence: an explicit `workerSrc` option → an already-set `pdfjsLib.GlobalWorkerOptions.workerSrc` → the auto-default above. You only pass `workerSrc` when the default can't apply.
+
+### Vite / webpack 5 / esbuild
+
+Nothing to do — these bundlers statically rewrite the `new URL(..., import.meta.url)` above and emit the worker asset:
+
+```js
+new PdfSource('document.pdf');
+```
+
+### CDN / `<script>` (UMD)
+
+No bundler to rewrite the URL, so point at a hosted worker matching your pdf.js version:
+
+```js
+new ZineJS.PdfSource('document.pdf', {
+  workerSrc: 'https://cdn.jsdelivr.net/npm/pdfjs-dist/build/pdf.worker.min.mjs',
+});
+```
+
+### Custom path
+
+Serving the worker yourself (copied to your public dir, etc.):
+
+```js
+new PdfSource('document.pdf', { workerSrc: '/assets/pdf.worker.min.mjs' });
+```
+
+### Already configuring pdf.js yourself
+
+If your app sets `GlobalWorkerOptions.workerSrc`, `PdfSource` leaves it alone — no `workerSrc` needed.
+
+## Passing bytes or a pre-created document
+
+```js
+new PdfSource(arrayBuffer);              // raw PDF bytes (ArrayBuffer | Uint8Array)
+new PdfSource(await getDocument(...).promise); // a pdf.js document you created; no workerSrc needed
+```
+
+## Options
+
+```ts
+new PdfSource(src, {
+  workerSrc,          // string — override the auto-resolved worker URL (see above)
+  renderScale: 1,     // pages rasterize at renderScale × devicePixelRatio
+  preload: 1,         // adjacent pages to prefetch around a requested page
+  maxCacheBytes,      // soft cap on cached page bytes (default ~256 MB); LRU-evicts beyond it
+});
+```
+
+`src` is a URL string, `ArrayBuffer`/`Uint8Array` of PDF bytes, or a pre-created pdf.js document.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { PdfSource } from './pdfSource';
+export type { PdfSrc, PdfSourceOptions } from './pdfSource';

package/dist/index.js

@@ -0,0 +1,76 @@
+function e(e) {
+	return typeof e == "object" && !!e && "numPages" in e && typeof e.getPage == "function";
+}
+var t = class {
+	pageCount = 0;
+	#e;
+	#t;
+	#n;
+	#r;
+	#i = null;
+	#a;
+	#o = /* @__PURE__ */ new Map();
+	#s = 0;
+	constructor(e, t = {}) {
+		this.#e = e, this.#t = t.workerSrc, this.#n = t.renderScale ?? 1, this.#r = t.preload ?? 1, this.#a = t.maxCacheBytes ?? 268435456;
+	}
+	async open() {
+		if (e(this.#e)) this.#i = this.#e;
+		else {
+			let e = await import("pdfjs-dist");
+			e.GlobalWorkerOptions.workerSrc = this.#c(e.GlobalWorkerOptions.workerSrc);
+			let t = typeof this.#e == "string" ? { url: this.#e } : { data: this.#e };
+			this.#i = await e.getDocument(t).promise;
+		}
+		this.pageCount = this.#i.numPages;
+	}
+	#c(e) {
+		if (this.#t) return this.#t;
+		if (e) return e;
+		try {
+			return (new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url).href);
+		} catch {
+			throw Error("PdfSource: couldn't auto-resolve pdf.js's worker. Pass a `workerSrc` URL (see the @zinejs/pdf README, \"The pdf.js worker\"), set pdfjs GlobalWorkerOptions.workerSrc yourself, or pass a pre-created pdf.js document.");
+		}
+	}
+	get(e) {
+		let t = this.#l(e);
+		for (let t = 1; t <= this.#r; t++) this.prefetch([e - t, e + t]);
+		return t;
+	}
+	prefetch(e) {
+		for (let t of e) t >= 0 && t < this.pageCount && this.#l(t).catch(() => {});
+	}
+	destroy() {
+		this.#i?.destroy?.(), this.#o.clear(), this.#s = 0, this.#i = null;
+	}
+	#l(e) {
+		let t = this.#o.get(e);
+		if (t) return this.#o.delete(e), this.#o.set(e, t), t.promise;
+		let n = {
+			promise: void 0,
+			bytes: 0
+		};
+		return n.promise = this.#d(e).then((t) => (n.bytes = t.width * t.height * 4, this.#s += n.bytes, this.#u(e), t), (t) => {
+			throw this.#o.delete(e), t;
+		}), this.#o.set(e, n), n.promise;
+	}
+	#u(e) {
+		for (let [t, n] of this.#o) {
+			if (this.#s <= this.#a) break;
+			t === e || n.bytes === 0 || (this.#o.delete(t), this.#s -= n.bytes);
+		}
+	}
+	async #d(e) {
+		if (this.#i === null) throw Error("PdfSource: use after open() — the document is not loaded.");
+		let t = await this.#i.getPage(e + 1), n = typeof devicePixelRatio == "number" ? devicePixelRatio : 1, r = t.getViewport({ scale: this.#n * n }), i = document.createElement("canvas");
+		return i.width = Math.ceil(r.width), i.height = Math.ceil(r.height), await t.render({
+			canvasContext: i.getContext("2d"),
+			viewport: r
+		}).promise, i;
+	}
+};
+//#endregion
+export { t as PdfSource };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#src","#workerSrc","#renderScale","#preload","#maxCacheBytes","#doc","#resolveWorkerSrc","#renderPage","#cache","#cachedBytes","#rasterize","#evictToFit"],"sources":["../src/pdfSource.ts"],"sourcesContent":["import type { PageContent, Source } from '@zinejs/core';\n\n/** Minimal shapes of the pdf.js API we rely on (avoids a hard type dependency). */\ninterface PdfPageLike {\n  getViewport(opts: { scale: number }): { width: number; height: number };\n  render(opts: { canvasContext: unknown; viewport: unknown }): { promise: Promise<void> };\n}\ninterface PdfDocumentLike {\n  numPages: number;\n  getPage(pageNumber: number): Promise<PdfPageLike>;\n  destroy?(): void;\n}\ninterface PdfjsModule {\n  GlobalWorkerOptions: { workerSrc: string };\n  getDocument(src: { url: string } | { data: ArrayBuffer | Uint8Array }): { promise: Promise<PdfDocumentLike> };\n}\n\n/** A URL, raw bytes, or a pre-created pdf.js document. */\nexport type PdfSrc = string | ArrayBuffer | Uint8Array | PdfDocumentLike;\n\nexport interface PdfSourceOptions {\n  /** URL to pdf.js's worker. Optional: auto-resolved under bundlers; pass it for CDN / UMD / custom paths. */\n  workerSrc?: string;\n  /** Base render scale; each page is rasterized at `renderScale × devicePixelRatio`. Default 1. */\n  renderScale?: number;\n  /** How many adjacent pages to prefetch around a requested page. Default 1. */\n  preload?: number;\n  /** Soft cap on cached page bytes; least-recently-used pages evict beyond it. Default ~256 MB. */\n  maxCacheBytes?: number;\n}\n\nconst DEFAULT_MAX_CACHE_BYTES = 256 * 1024 * 1024;\n\ninterface CacheEntry {\n  promise: Promise<PageContent>;\n  bytes: number; // 0 until the render resolves and its size is known\n}\n\nfunction isPdfDocument(src: PdfSrc): src is PdfDocumentLike {\n  return (\n    typeof src === 'object' &&\n    src !== null &&\n    'numPages' in src &&\n    typeof (src as PdfDocumentLike).getPage === 'function'\n  );\n}\n\n/**\n * Renders PDF pages to canvases for zinejs. pdf.js is a peer dependency, loaded\n * lazily so it never lands in the core bundle. Async — pass it to `new Zine`,\n * which calls `open()` (learning the page count) before building spreads.\n */\nexport class PdfSource implements Source {\n  pageCount = 0;\n  #src: PdfSrc;\n  #workerSrc: string | undefined;\n  #renderScale: number;\n  #preload: number;\n  #doc: PdfDocumentLike | null = null;\n  #maxCacheBytes: number;\n  #cache = new Map<number, CacheEntry>();\n  #cachedBytes = 0;\n\n  constructor(src: PdfSrc, options: PdfSourceOptions = {}) {\n    this.#src = src;\n    this.#workerSrc = options.workerSrc;\n    this.#renderScale = options.renderScale ?? 1;\n    this.#preload = options.preload ?? 1;\n    this.#maxCacheBytes = options.maxCacheBytes ?? DEFAULT_MAX_CACHE_BYTES;\n  }\n\n  async open(): Promise<void> {\n    if (isPdfDocument(this.#src)) {\n      this.#doc = this.#src;\n    } else {\n      const pdfjs = (await import('pdfjs-dist')) as unknown as PdfjsModule;\n      pdfjs.GlobalWorkerOptions.workerSrc = this.#resolveWorkerSrc(pdfjs.GlobalWorkerOptions.workerSrc);\n      const params = typeof this.#src === 'string' ? { url: this.#src } : { data: this.#src };\n      this.#doc = await pdfjs.getDocument(params).promise;\n    }\n    this.pageCount = this.#doc.numPages;\n  }\n\n  /** Precedence: an explicit `workerSrc` → an already-configured global → an auto-resolved default. */\n  #resolveWorkerSrc(configured: string): string {\n    if (this.#workerSrc) return this.#workerSrc;\n    if (configured) return configured;\n    try {\n      // Bundlers (Vite / webpack 5 / esbuild) statically rewrite this and emit the worker,\n      // so the common case needs no `workerSrc`. Non-bundler / UMD hosts pass it explicitly.\n      return \"@@ZINE_PDF_WORKER_URL@@\";\n    } catch {\n      throw new Error(\n        \"PdfSource: couldn't auto-resolve pdf.js's worker. Pass a `workerSrc` URL \" +\n          '(see the @zinejs/pdf README, \"The pdf.js worker\"), set pdfjs ' +\n          'GlobalWorkerOptions.workerSrc yourself, or pass a pre-created pdf.js document.',\n      );\n    }\n  }\n\n  get(index: number): Promise<PageContent> {\n    const decoded = this.#renderPage(index);\n    for (let d = 1; d <= this.#preload; d++) {\n      this.prefetch([index - d, index + d]);\n    }\n    return decoded;\n  }\n\n  prefetch(indices: number[]): void {\n    for (const i of indices) {\n      if (i >= 0 && i < this.pageCount) {\n        void this.#renderPage(i).catch(() => {}); // prefetch failures surface on a real get()\n      }\n    }\n  }\n\n  destroy(): void {\n    this.#doc?.destroy?.();\n    this.#cache.clear();\n    this.#cachedBytes = 0;\n    this.#doc = null;\n  }\n\n  #renderPage(index: number): Promise<PageContent> {\n    const existing = this.#cache.get(index);\n    if (existing) {\n      // Mark most-recently-used: re-insert so it sits at the end of the Map's order.\n      this.#cache.delete(index);\n      this.#cache.set(index, existing);\n      return existing.promise;\n    }\n\n    const entry: CacheEntry = { promise: undefined as unknown as Promise<PageContent>, bytes: 0 };\n    entry.promise = this.#rasterize(index).then(\n      (content) => {\n        entry.bytes = content.width * content.height * 4; // RGBA\n        this.#cachedBytes += entry.bytes;\n        this.#evictToFit(index);\n        return content;\n      },\n      (error: unknown) => {\n        this.#cache.delete(index); // let a later get() retry\n        throw error;\n      },\n    );\n    this.#cache.set(index, entry);\n    return entry.promise;\n  }\n\n  /** Drop least-recently-used pages (front of the Map) until under the byte cap. */\n  #evictToFit(keepIndex: number): void {\n    for (const [index, entry] of this.#cache) {\n      if (this.#cachedBytes <= this.#maxCacheBytes) break;\n      if (index === keepIndex || entry.bytes === 0) continue; // keep the newest; skip in-flight renders\n      this.#cache.delete(index);\n      this.#cachedBytes -= entry.bytes;\n    }\n  }\n\n  async #rasterize(index: number): Promise<PageContent> {\n    if (this.#doc === null) throw new Error('PdfSource: use after open() — the document is not loaded.');\n    const page = await this.#doc.getPage(index + 1); // pdf.js pages are 1-indexed\n    const dpr = typeof devicePixelRatio === 'number' ? devicePixelRatio : 1;\n    const viewport = page.getViewport({ scale: this.#renderScale * dpr });\n    const canvas = document.createElement('canvas');\n    canvas.width = Math.ceil(viewport.width);\n    canvas.height = Math.ceil(viewport.height);\n    await page.render({ canvasContext: canvas.getContext('2d'), viewport }).promise;\n    return canvas;\n  }\n}\n"],"mappings":"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"}

package/dist/pdfSource.d.ts

@@ -0,0 +1,48 @@
+import type { PageContent, Source } from '@zinejs/core';
+/** Minimal shapes of the pdf.js API we rely on (avoids a hard type dependency). */
+interface PdfPageLike {
+    getViewport(opts: {
+        scale: number;
+    }): {
+        width: number;
+        height: number;
+    };
+    render(opts: {
+        canvasContext: unknown;
+        viewport: unknown;
+    }): {
+        promise: Promise<void>;
+    };
+}
+interface PdfDocumentLike {
+    numPages: number;
+    getPage(pageNumber: number): Promise<PdfPageLike>;
+    destroy?(): void;
+}
+/** A URL, raw bytes, or a pre-created pdf.js document. */
+export type PdfSrc = string | ArrayBuffer | Uint8Array | PdfDocumentLike;
+export interface PdfSourceOptions {
+    /** URL to pdf.js's worker. Optional: auto-resolved under bundlers; pass it for CDN / UMD / custom paths. */
+    workerSrc?: string;
+    /** Base render scale; each page is rasterized at `renderScale × devicePixelRatio`. Default 1. */
+    renderScale?: number;
+    /** How many adjacent pages to prefetch around a requested page. Default 1. */
+    preload?: number;
+    /** Soft cap on cached page bytes; least-recently-used pages evict beyond it. Default ~256 MB. */
+    maxCacheBytes?: number;
+}
+/**
+ * Renders PDF pages to canvases for zinejs. pdf.js is a peer dependency, loaded
+ * lazily so it never lands in the core bundle. Async — pass it to `new Zine`,
+ * which calls `open()` (learning the page count) before building spreads.
+ */
+export declare class PdfSource implements Source {
+    #private;
+    pageCount: number;
+    constructor(src: PdfSrc, options?: PdfSourceOptions);
+    open(): Promise<void>;
+    get(index: number): Promise<PageContent>;
+    prefetch(indices: number[]): void;
+    destroy(): void;
+}
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zinejs/pdf",
+  "version": "0.1.0",
+  "description": "PDF content source for zinejs, powered by pdf.js.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "keywords": [
+    "flipbook",
+    "pdf",
+    "pdf.js",
+    "page-flip",
+    "viewer",
+    "zinejs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awecode/zinejs.git",
+    "directory": "packages/pdf"
+  },
+  "homepage": "https://github.com/awecode/zinejs/tree/main/packages/pdf#readme",
+  "bugs": "https://github.com/awecode/zinejs/issues",
+  "files": [
+    "dist"
+  ],
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "pdfjs-dist": ">=4",
+    "@zinejs/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@zinejs/core": "^0.1.0"
+  },
+  "size-limit": [
+    {
+      "name": "pdf plugin (ESM, gzip, excl. pdf.js)",
+      "path": "dist/index.js",
+      "limit": "8 kB",
+      "gzip": true
+    }
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "pnpm typecheck && vitest run",
+    "size": "pnpm build && size-limit"
+  }
+}