@build-qube/papyra 0.0.3

package/dist/cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Size-bounded LRU for rendered pages.
+ *
+ * Worth having because a render is never cheap: on a large CAD drawing every page costs
+ * >=93ms no matter how small the output, since the cost is per-draw-call rather than
+ * per-pixel (see docs/spike-results.md). A viewer re-renders the same page constantly —
+ * scrolling back, returning from a zoom, promoting a thumbnail — and each of those is a
+ * fresh 93ms without a cache.
+ *
+ * Bounded by **bytes**, not entries, because page bitmaps span three orders of
+ * magnitude: a 160px thumbnail of an ARCH-E sheet is 0.07 MB and the same page at
+ * 2000px is 11.4 MB. An entry-count limit would either hold almost nothing or hundreds
+ * of megabytes depending on the document.
+ */
+export interface CacheStats {
+    /** Bytes currently held. */
+    bytes: number;
+    entries: number;
+    hits: number;
+    misses: number;
+    /** Entries dropped to stay under budget. */
+    evictions: number;
+}
+export declare class RenderCache<T> {
+    #private;
+    constructor(budgetBytes: number, sizeOf: (value: T) => number);
+    get enabled(): boolean;
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    clear(): void;
+    get stats(): CacheStats;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,WAAW,CAAC,CAAC;;IAUxB,YAAY,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,EAG5D;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAW9B;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAc/B;IAcD,KAAK,IAAI,IAAI,CAGZ;IAED,IAAI,KAAK,IAAI,UAAU,CAQtB;CACF"}

package/dist/cache.js

@@ -0,0 +1,86 @@
+/**
+ * Size-bounded LRU for rendered pages.
+ *
+ * Worth having because a render is never cheap: on a large CAD drawing every page costs
+ * >=93ms no matter how small the output, since the cost is per-draw-call rather than
+ * per-pixel (see docs/spike-results.md). A viewer re-renders the same page constantly —
+ * scrolling back, returning from a zoom, promoting a thumbnail — and each of those is a
+ * fresh 93ms without a cache.
+ *
+ * Bounded by **bytes**, not entries, because page bitmaps span three orders of
+ * magnitude: a 160px thumbnail of an ARCH-E sheet is 0.07 MB and the same page at
+ * 2000px is 11.4 MB. An entry-count limit would either hold almost nothing or hundreds
+ * of megabytes depending on the document.
+ */
+export class RenderCache {
+    #budget;
+    #sizeOf;
+    /** Insertion order is the LRU order: re-inserting on read moves an entry to the end. */
+    #entries = new Map();
+    #bytes = 0;
+    #hits = 0;
+    #misses = 0;
+    #evictions = 0;
+    constructor(budgetBytes, sizeOf) {
+        this.#budget = Math.max(0, budgetBytes);
+        this.#sizeOf = sizeOf;
+    }
+    get enabled() {
+        return this.#budget > 0;
+    }
+    get(key) {
+        const value = this.#entries.get(key);
+        if (value === undefined) {
+            this.#misses++;
+            return undefined;
+        }
+        // Move to the most-recently-used end.
+        this.#entries.delete(key);
+        this.#entries.set(key, value);
+        this.#hits++;
+        return value;
+    }
+    set(key, value) {
+        if (!this.enabled)
+            return;
+        const size = this.#sizeOf(value);
+        // An item larger than the whole budget would evict everything and still not fit.
+        if (size > this.#budget)
+            return;
+        const existing = this.#entries.get(key);
+        if (existing !== undefined) {
+            this.#bytes -= this.#sizeOf(existing);
+            this.#entries.delete(key);
+        }
+        this.#entries.set(key, value);
+        this.#bytes += size;
+        this.#evict();
+    }
+    #evict() {
+        while (this.#bytes > this.#budget) {
+            // Map iteration starts at the least-recently-used entry.
+            const oldest = this.#entries.keys().next();
+            if (oldest.done)
+                return;
+            const value = this.#entries.get(oldest.value);
+            if (value !== undefined)
+                this.#bytes -= this.#sizeOf(value);
+            this.#entries.delete(oldest.value);
+            this.#evictions++;
+        }
+    }
+    clear() {
+        this.#entries.clear();
+        this.#bytes = 0;
+    }
+    get stats() {
+        return {
+            bytes: this.#bytes,
+            entries: this.#entries.size,
+            hits: this.#hits,
+            misses: this.#misses,
+            evictions: this.#evictions,
+        };
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/canvas.d.ts

@@ -0,0 +1,12 @@
+import type { RenderedPage } from './types.js';
+/**
+ * Wrap a rendered page as `ImageData`, ready for `putImageData`.
+ *
+ * This copies. It has to: on the wasm build the pixels live in the module's shared
+ * linear memory, and `ImageData` refuses a `SharedArrayBuffer`-backed view. Copying
+ * unconditionally keeps both runtimes on the same path.
+ */
+export declare function toImageData(page: RenderedPage): ImageData;
+/** Paint a rendered page onto a canvas, resizing the canvas to match. */
+export declare function paintToCanvas(page: RenderedPage, canvas: HTMLCanvasElement | OffscreenCanvas): void;
+//# sourceMappingURL=canvas.d.ts.map

package/dist/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAMzD;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,iBAAiB,GAAG,eAAe,GAC1C,IAAI,CASN"}

package/dist/canvas.js

@@ -0,0 +1,20 @@
+/**
+ * Wrap a rendered page as `ImageData`, ready for `putImageData`.
+ *
+ * This copies. It has to: on the wasm build the pixels live in the module's shared
+ * linear memory, and `ImageData` refuses a `SharedArrayBuffer`-backed view. Copying
+ * unconditionally keeps both runtimes on the same path.
+ */
+export function toImageData(page) {
+    return new ImageData(Uint8ClampedArray.from(page.data), page.width, page.height);
+}
+/** Paint a rendered page onto a canvas, resizing the canvas to match. */
+export function paintToCanvas(page, canvas) {
+    canvas.width = page.width;
+    canvas.height = page.height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        throw new Error('papyra: could not get a 2d canvas context');
+    ctx.putImageData(toImageData(page), 0, 0);
+}
+//# sourceMappingURL=canvas.js.map

package/dist/canvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.js","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,OAAO,IAAI,SAAS,CAClB,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EACjC,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,MAAM,CACZ,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAC3B,IAAkB,EAClB,MAA2C;IAE3C,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAG1B,CAAC;IACT,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACvE,GAAG,CAAC,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/dist/document.d.ts

@@ -0,0 +1,79 @@
+import { PdfDocument as NativeDocument } from '@build-qube/papyra-native';
+import { type CacheStats } from './cache.js';
+import { type JobHandle } from './scheduler.js';
+import type { OpenOptions, PageSize, PdfSource, RenderedPage, RenderOptions, StreamedPage, StreamOptions } from './types.js';
+/** A queued render, plus whether it was served from cache without rendering at all. */
+export interface RenderHandle extends JobHandle<RenderedPage> {
+    readonly cached: boolean;
+}
+/** Open a PDF from bytes, an `ArrayBuffer`, a `Blob`, or a `File`. */
+export declare function open(source: PdfSource, options?: OpenOptions): Promise<Document>;
+export declare class Document {
+    #private;
+    /** @internal — construct via {@link open}. */
+    constructor(inner: NativeDocument, options?: OpenOptions);
+    /** Rendered pages held for reuse, and how often that has paid off. */
+    get cache(): CacheStats;
+    /** Drop every cached page. */
+    clearCache(): void;
+    /** Pages queued but not yet started, pages rendering, and the longest wait so far. */
+    get queued(): {
+        pending: number;
+        running: number;
+        oldestWaitMs: number;
+    };
+    get pageCount(): number;
+    /** Page dimensions in PDF points (1/72 inch). */
+    pageSize(index: number): PageSize;
+    /** Render a single page. Never blocks the event loop. */
+    renderPage(index: number, options?: RenderOptions): Promise<RenderedPage>;
+    /**
+     * Render a page, returning a handle you can reprioritise or drop.
+     *
+     * This is the viewer path: as the user scrolls, promote what came into view and
+     * demote what left, without re-submitting or duplicating work. Requests for the same
+     * page at the same size coalesce into one render, taking the most urgent priority
+     * asked for.
+     *
+     * @example
+     * ```ts
+     * const jobs = visible.map((p) => doc.render(p, { fitWidth: 1600, priority: 0 }));
+     * onScroll(() => {
+     *   for (const [i, job] of jobs.entries()) job.setPriority(distanceFromViewport(i));
+     * });
+     * ```
+     */
+    render(index: number, options?: RenderOptions): RenderHandle;
+    /**
+     * Render `[start, end)`.
+     *
+     * The concurrency strategy differs by runtime, for reasons measured in
+     * `docs/spike-results.md`:
+     *
+     * - **native** — one async task with rayon inside. Fastest, and independent of
+     *   `UV_THREADPOOL_SIZE`, which we cannot set from inside an addon.
+     * - **wasm** — per-page async tasks. rayon's workers there are Web Workers that the
+     *   JS event loop has to create, so a rayon batch cannot be driven from a blocked
+     *   thread; per-page tasks map onto the runtime's own worker pool instead.
+     */
+    renderPages(start: number, end: number, options?: RenderOptions): Promise<RenderedPage[]>;
+    /**
+     * Render pages as an async iterable, yielding each as soon as it finishes.
+     *
+     * At most `concurrency` renders are in flight, so memory stays bounded — 23 letter
+     * pages at 150 DPI is ~193 MB of RGBA if you hold them all. Breaking out of the loop
+     * stops scheduling further work, which makes "thumbnails for the visible rows only"
+     * cheap.
+     *
+     * @example
+     * ```ts
+     * for await (const { page, bitmap } of doc.stream({ dpi: 48, order: visible })) {
+     *   paint(page, bitmap);
+     * }
+     * ```
+     */
+    stream(options?: StreamOptions): AsyncGenerator<StreamedPage>;
+    /** How many pages this document will render at once. */
+    get concurrency(): number;
+}
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,KAAK,UAAU,EAAe,MAAM,YAAY,CAAC;AAO1D,OAAO,EAAoB,KAAK,SAAS,EAAa,MAAM,gBAAgB,CAAC;AAE7E,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,EACd,MAAM,YAAY,CAAC;AAcpB,uFAAuF;AACvF,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,YAAY,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,sEAAsE;AACtE,wBAAsB,IAAI,CACxB,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAQnB;AAED,qBAAa,QAAQ;;IAMnB,8CAA8C;IAC9C,YAAY,KAAK,EAAE,cAAc,EAAE,OAAO,GAAE,WAAgB,EAU3D;IAED,sEAAsE;IACtE,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED,8BAA8B;IAC9B,UAAU,IAAI,IAAI,CAEjB;IAED,sFAAsF;IACtF,IAAI,MAAM,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAMvE;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAEhC;IAED,yDAAyD;IACnD,UAAU,CACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAEvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CAgC/D;IA4BD;;;;;;;;;;;OAWG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC,CAoBzB;IAED;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,cAAc,CAAC,YAAY,CAAC,CA2CvE;IAED,wDAAwD;IACxD,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}

package/dist/document.js

@@ -0,0 +1,255 @@
+import { PdfDocument as NativeDocument } from '@build-qube/papyra-native';
+import { RenderCache } from './cache.js';
+import { currentRuntime, hardwareConcurrency, init, MAX_WASM_CONCURRENCY, } from './runtime.js';
+import { DEFAULT_PRIORITY, Scheduler } from './scheduler.js';
+import { toBytes } from './source.js';
+const DEFAULT_DPI = 72;
+/**
+ * Refuse renders large enough to take down the tab.
+ *
+ * 100 MP is ~400 MB of RGBA — beyond this you almost certainly meant `fitWidth`.
+ */
+const MAX_PIXELS = 100_000_000;
+/** Default bytes of rendered pages to keep. Roughly eleven 2000px ARCH-E sheets. */
+const DEFAULT_CACHE_BYTES = 128 * 1024 * 1024;
+/** Open a PDF from bytes, an `ArrayBuffer`, a `Blob`, or a `File`. */
+export async function open(source, options = {}) {
+    init();
+    const bytes = await toBytes(source);
+    const inner = options.password === undefined
+        ? NativeDocument.load(bytes)
+        : NativeDocument.loadWithPassword(bytes, options.password);
+    return new Document(inner, options);
+}
+export class Document {
+    #inner;
+    #scheduler;
+    #limit;
+    #cache;
+    /** @internal — construct via {@link open}. */
+    constructor(inner, options = {}) {
+        this.#inner = inner;
+        this.#limit = Math.max(1, options.concurrency ?? defaultConcurrency());
+        this.#scheduler = new Scheduler(this.#limit, {
+            yieldToUrgent: options.yieldToUrgent,
+        });
+        this.#cache = new RenderCache(options.cacheBytes ?? DEFAULT_CACHE_BYTES, (page) => page.data.byteLength);
+    }
+    /** Rendered pages held for reuse, and how often that has paid off. */
+    get cache() {
+        return this.#cache.stats;
+    }
+    /** Drop every cached page. */
+    clearCache() {
+        this.#cache.clear();
+    }
+    /** Pages queued but not yet started, pages rendering, and the longest wait so far. */
+    get queued() {
+        return {
+            pending: this.#scheduler.pendingCount,
+            running: this.#scheduler.runningCount,
+            oldestWaitMs: this.#scheduler.oldestWaitMs,
+        };
+    }
+    get pageCount() {
+        return this.#inner.pageCount;
+    }
+    /** Page dimensions in PDF points (1/72 inch). */
+    pageSize(index) {
+        return this.#inner.pageSize(index);
+    }
+    /** Render a single page. Never blocks the event loop. */
+    async renderPage(index, options = {}) {
+        return this.render(index, options).promise;
+    }
+    /**
+     * Render a page, returning a handle you can reprioritise or drop.
+     *
+     * This is the viewer path: as the user scrolls, promote what came into view and
+     * demote what left, without re-submitting or duplicating work. Requests for the same
+     * page at the same size coalesce into one render, taking the most urgent priority
+     * asked for.
+     *
+     * @example
+     * ```ts
+     * const jobs = visible.map((p) => doc.render(p, { fitWidth: 1600, priority: 0 }));
+     * onScroll(() => {
+     *   for (const [i, job] of jobs.entries()) job.setPriority(distanceFromViewport(i));
+     * });
+     * ```
+     */
+    render(index, options = {}) {
+        const dpi = this.#resolveDpi(index, options);
+        const key = `${index}@${dpi.toFixed(4)}`;
+        const hit = this.#cache.get(key);
+        if (hit)
+            return cachedHandle(key, hit);
+        const handle = this.#scheduler.submit({
+            key,
+            priority: options.priority ?? DEFAULT_PRIORITY,
+            run: () => this.#inner.renderPageAsync(index, dpi).then((page) => {
+                this.#cache.set(key, page);
+                return page;
+            }),
+        });
+        const { signal } = options;
+        if (signal) {
+            if (signal.aborted)
+                handle.cancel('signal aborted');
+            else
+                signal.addEventListener('abort', () => handle.cancel('signal aborted'), {
+                    once: true,
+                });
+        }
+        return liveHandle(handle);
+    }
+    /**
+     * Turn `fitWidth`/`dpi` into a concrete DPI, and refuse absurd outputs.
+     *
+     * `fitWidth` exists because page sizes vary by two orders of magnitude in area: a
+     * DPI that is sensible for US Letter produces a 113 MB bitmap for an ARCH-E drawing.
+     */
+    #resolveDpi(index, options) {
+        const { width, height } = this.pageSize(index);
+        const dpi = options.fitWidth !== undefined && width > 0
+            ? (options.fitWidth / width) * 72
+            : (options.dpi ?? DEFAULT_DPI);
+        const pixels = ((width * dpi) / 72) * ((height * dpi) / 72);
+        if (pixels > MAX_PIXELS) {
+            const mb = Math.round((pixels * 4) / 1e6);
+            throw new RangeError(`papyra: page ${index} at ${dpi.toFixed(1)} DPI would be ` +
+                `${Math.round((width * dpi) / 72)}x${Math.round((height * dpi) / 72)} ` +
+                `(${mb} MB). The page is ${(width / 72).toFixed(1)}x${(height / 72).toFixed(1)}in — ` +
+                'use { fitWidth } to size by output pixels instead of DPI.');
+        }
+        return dpi;
+    }
+    /**
+     * Render `[start, end)`.
+     *
+     * The concurrency strategy differs by runtime, for reasons measured in
+     * `docs/spike-results.md`:
+     *
+     * - **native** — one async task with rayon inside. Fastest, and independent of
+     *   `UV_THREADPOOL_SIZE`, which we cannot set from inside an addon.
+     * - **wasm** — per-page async tasks. rayon's workers there are Web Workers that the
+     *   JS event loop has to create, so a rayon batch cannot be driven from a blocked
+     *   thread; per-page tasks map onto the runtime's own worker pool instead.
+     */
+    async renderPages(start, end, options = {}) {
+        if (currentRuntime() === 'native' && options.fitWidth === undefined) {
+            // One DPI for the whole batch, so every page in range has to pass the guard —
+            // a document can mix a letter-size cover sheet with ARCH-E drawings.
+            let dpi = DEFAULT_DPI;
+            for (let i = start; i < end; i++)
+                dpi = this.#resolveDpi(i, options);
+            return (await this.#inner.renderPagesAsync(start, end, dpi));
+        }
+        const out = [];
+        for await (const { page, bitmap } of this.stream({
+            ...options,
+            order: range(start, end),
+        })) {
+            out[page - start] = bitmap;
+        }
+        return out;
+    }
+    /**
+     * Render pages as an async iterable, yielding each as soon as it finishes.
+     *
+     * At most `concurrency` renders are in flight, so memory stays bounded — 23 letter
+     * pages at 150 DPI is ~193 MB of RGBA if you hold them all. Breaking out of the loop
+     * stops scheduling further work, which makes "thumbnails for the visible rows only"
+     * cheap.
+     *
+     * @example
+     * ```ts
+     * for await (const { page, bitmap } of doc.stream({ dpi: 48, order: visible })) {
+     *   paint(page, bitmap);
+     * }
+     * ```
+     */
+    async *stream(options = {}) {
+        const pages = options.order ?? range(0, this.pageCount);
+        const window = Math.max(1, options.concurrency ?? Math.min(this.#limit, pages.length || 1));
+        const inflight = new Map();
+        const handles = new Map();
+        let next = 0;
+        const schedule = (slot) => {
+            const page = pages[slot];
+            if (page === undefined)
+                return;
+            const handle = this.render(page, options);
+            handles.set(slot, handle);
+            inflight.set(slot, handle.promise.then((bitmap) => ({ slot, page, bitmap })));
+        };
+        try {
+            while (next < pages.length && inflight.size < window)
+                schedule(next++);
+            while (inflight.size > 0) {
+                const { slot, page, bitmap } = await Promise.race(inflight.values());
+                inflight.delete(slot);
+                handles.delete(slot);
+                if (next < pages.length)
+                    schedule(next++);
+                yield { page, bitmap };
+            }
+        }
+        finally {
+            // Breaking out of the loop drops everything still queued, so "thumbnails for
+            // the rows I can see" does not keep rendering the rows I cannot.
+            for (const [slot, handle] of handles) {
+                handle.cancel('stream ended');
+                // The derived promise rejects once cancelled; nobody is listening any more.
+                inflight.get(slot)?.catch(() => { });
+            }
+            inflight.clear();
+            handles.clear();
+        }
+    }
+    /** How many pages this document will render at once. */
+    get concurrency() {
+        return this.#limit;
+    }
+}
+function defaultConcurrency() {
+    return currentRuntime() === 'wasm'
+        ? MAX_WASM_CONCURRENCY
+        : hardwareConcurrency();
+}
+/**
+ * Wrap a scheduler handle as a {@link RenderHandle}.
+ *
+ * Delegates rather than spreading: `timing` is a getter that is null until the job
+ * settles, and a spread would freeze it at null forever.
+ */
+function liveHandle(handle) {
+    return {
+        key: handle.key,
+        cached: false,
+        promise: handle.promise,
+        get timing() {
+            return handle.timing;
+        },
+        setPriority: (priority) => handle.setPriority(priority),
+        cancel: (reason) => handle.cancel(reason),
+    };
+}
+/** A handle for work that never had to happen. */
+function cachedHandle(key, page) {
+    return {
+        key,
+        cached: true,
+        promise: Promise.resolve(page),
+        timing: { waitMs: 0, runMs: 0 },
+        setPriority: () => { },
+        cancel: () => { },
+    };
+}
+function range(start, end) {
+    const out = [];
+    for (let i = start; i < end; i++)
+        out.push(i);
+    return out;
+}
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * papyra — fast PDF rendering for Node and the browser.
+ *
+ * ```ts
+ * import { open, paintToCanvas } from '@build-qube/papyra';
+ *
+ * const doc = await open(file);                 // Uint8Array | Blob | File
+ * const page = await doc.renderPage(0, { fitWidth: 1600 });
+ * paintToCanvas(page, canvas);
+ *
+ * // Viewers: attach your own priorities. Lower runs first; the default is urgent.
+ * const job = doc.render(3, { fitWidth: 1600, priority: 2 });
+ * onScroll(() => job.setPriority(0));
+ * ```
+ */
+export type { CacheStats } from './cache.js';
+export { paintToCanvas, toImageData } from './canvas.js';
+export type { RenderHandle } from './document.js';
+export { Document, open } from './document.js';
+export type { Runtime } from './runtime.js';
+export { backend, currentRuntime, hardwareConcurrency, init, } from './runtime.js';
+export type { JobHandle, JobTiming } from './scheduler.js';
+export { AbortError, DEFAULT_PRIORITY } from './scheduler.js';
+export type { OpenOptions, PageSize, PdfSource, RenderedPage, RenderOptions, StreamedPage, StreamOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,IAAI,GACL,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EACV,WAAW,EACX,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * papyra — fast PDF rendering for Node and the browser.
+ *
+ * ```ts
+ * import { open, paintToCanvas } from '@build-qube/papyra';
+ *
+ * const doc = await open(file);                 // Uint8Array | Blob | File
+ * const page = await doc.renderPage(0, { fitWidth: 1600 });
+ * paintToCanvas(page, canvas);
+ *
+ * // Viewers: attach your own priorities. Lower runs first; the default is urgent.
+ * const job = doc.render(3, { fitWidth: 1600, priority: 2 });
+ * onScroll(() => job.setPriority(0));
+ * ```
+ */
+export { paintToCanvas, toImageData } from './canvas.js';
+export { Document, open } from './document.js';
+export { backend, currentRuntime, hardwareConcurrency, init, } from './runtime.js';
+export { AbortError, DEFAULT_PRIORITY } from './scheduler.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EACL,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,IAAI,GACL,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,25 @@
+export type Runtime = 'native' | 'wasm';
+/**
+ * Useful concurrency ceiling on wasm.
+ *
+ * napi-rs hardcodes `asyncWorkPoolSize = 4` in its generated browser glue, and
+ * `AsyncTask` work is dispatched through that pool. Measured throughput is flat from
+ * 4 through 16 in-flight renders, so anything above this only inflates peak memory.
+ */
+export declare const MAX_WASM_CONCURRENCY = 4;
+/** Best guess at how many renders this host can genuinely run at once. */
+export declare function hardwareConcurrency(): number;
+export declare function currentRuntime(): Runtime;
+export declare function backend(): string;
+/**
+ * Prepare the rendering thread pool. Idempotent, and called automatically by
+ * {@link open}.
+ *
+ * Only meaningful on wasm, where `available_parallelism()` is unsupported and rayon
+ * would otherwise pin itself to a single thread. Must run before any other rayon use,
+ * so we do it before the first document is loaded.
+ */
+export declare function init(options?: {
+    threads?: number;
+}): void;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAItC,0EAA0E;AAC1E,wBAAgB,mBAAmB,IAAI,MAAM,CAY5C;AAED,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAS7D"}

package/dist/runtime.js

@@ -0,0 +1,52 @@
+import { backendName, configureThreadPool, runtime, } from '@build-qube/papyra-native';
+/**
+ * Useful concurrency ceiling on wasm.
+ *
+ * napi-rs hardcodes `asyncWorkPoolSize = 4` in its generated browser glue, and
+ * `AsyncTask` work is dispatched through that pool. Measured throughput is flat from
+ * 4 through 16 in-flight renders, so anything above this only inflates peak memory.
+ */
+export const MAX_WASM_CONCURRENCY = 4;
+let initialised = false;
+/** Best guess at how many renders this host can genuinely run at once. */
+export function hardwareConcurrency() {
+    const nav = globalThis
+        .navigator;
+    if (typeof nav?.hardwareConcurrency === 'number') {
+        return Math.max(1, nav.hardwareConcurrency);
+    }
+    // Node/Bun: avoid a static `node:os` import so bundlers do not pull it into
+    // browser builds.
+    const proc = globalThis
+        .process;
+    const fromEnv = Number(proc?.env?.PAPYRA_THREADS);
+    return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : 4;
+}
+export function currentRuntime() {
+    return runtime() === 'wasm' ? 'wasm' : 'native';
+}
+export function backend() {
+    return backendName();
+}
+/**
+ * Prepare the rendering thread pool. Idempotent, and called automatically by
+ * {@link open}.
+ *
+ * Only meaningful on wasm, where `available_parallelism()` is unsupported and rayon
+ * would otherwise pin itself to a single thread. Must run before any other rayon use,
+ * so we do it before the first document is loaded.
+ */
+export function init(options = {}) {
+    if (initialised)
+        return;
+    initialised = true;
+    if (currentRuntime() !== 'wasm')
+        return;
+    try {
+        configureThreadPool(options.threads ?? hardwareConcurrency(), undefined);
+    }
+    catch {
+        // Already built (another copy of the library got there first). Harmless.
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,OAAO,GACR,MAAM,2BAA2B,CAAC;AAInC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB;IACjC,MAAM,GAAG,GAAI,UAA+D;SACzE,SAAS,CAAC;IACb,IAAI,OAAO,GAAG,EAAE,mBAAmB,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC9C,CAAC;IACD,4EAA4E;IAC5E,kBAAkB;IAClB,MAAM,IAAI,GAAI,UAA6D;SACxE,OAAO,CAAC;IACX,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAAC,OAAO,GAAyB,EAAE;IACrD,IAAI,WAAW;QAAE,OAAO;IACxB,WAAW,GAAG,IAAI,CAAC;IACnB,IAAI,cAAc,EAAE,KAAK,MAAM;QAAE,OAAO;IACxC,IAAI,CAAC;QACH,mBAAmB,CAAC,OAAO,CAAC,OAAO,IAAI,mBAAmB,EAAE,EAAE,SAAS,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;AACH,CAAC"}

package/dist/scheduler.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Priority-ordered render scheduler.
+ *
+ * papyra does not decide what is urgent — the caller does. A viewer knows which pages
+ * are on screen, which are one scroll away, and which are thumbnails nobody is looking
+ * at; the library does not. Callers attach a priority and this queue honours it.
+ *
+ * Pending work is reordered freely. Work already running is never interrupted: a page
+ * render is dominated by a fixed, non-preemptible content-stream interpretation cost
+ * (~95ms of a ~150ms render on a large drawing, independent of output size — see
+ * docs/spike-results.md), so cancelling mid-render would reclaim only the rasterisation
+ * tail. Reordering what has not started yet captures nearly all of the benefit.
+ */
+/** Runs first. Lower is more urgent; the default is the most urgent tier. */
+export declare const DEFAULT_PRIORITY = 0;
+export interface SchedulerJob<T> {
+    /** Identity for coalescing. Two live requests with the same key share one render. */
+    key: string;
+    priority: number;
+    run: () => Promise<T>;
+}
+/** Where a job's wall-clock time actually went. */
+export interface JobTiming {
+    /** Submitted until a slot freed and it started. */
+    waitMs: number;
+    /** Started until it finished. */
+    runMs: number;
+}
+export interface JobHandle<T> {
+    readonly key: string;
+    /**
+     * Populated once the job settles, `null` before that.
+     *
+     * The point is to tell a slow render from a long queue: if `waitMs` dominates the
+     * pool is too busy or the priority is wrong, and if `runMs` dominates the render
+     * itself is the cost. Guessing between those two is how you optimise the wrong half.
+     */
+    readonly timing: JobTiming | null;
+    /** Reassign urgency while the job is still pending. A no-op once it is running. */
+    setPriority(priority: number): void;
+    readonly promise: Promise<T>;
+    /**
+     * Detach from this job. If nothing else is waiting on it and it has not started,
+     * it is dropped from the queue; if it is already running it is left to finish.
+     */
+    cancel(reason?: string): void;
+}
+export declare class AbortError extends Error {
+    readonly name = "AbortError";
+    constructor(reason?: string);
+}
+export interface SchedulerOptions {
+    /**
+     * Hold back lower-priority work while something more urgent is still running.
+     *
+     * Ordering the queue is not enough on its own: once a job starts it competes for CPU
+     * for its whole duration, so a page rendered alongside three thumbnails takes ~4x as
+     * long as one rendered alone. With this on, a job only starts if nothing strictly
+     * more urgent is running — already-running work is left to finish, never preempted.
+     *
+     * It is a no-op when every job shares a priority, so batch throughput is unaffected
+     * and it only engages once a caller has expressed intent. On by default.
+     */
+    yieldToUrgent?: boolean;
+}
+export declare class Scheduler<T> {
+    #private;
+    constructor(limit: number, options?: SchedulerOptions);
+    get pendingCount(): number;
+    get runningCount(): number;
+    /** How long the longest-waiting pending job has been queued. */
+    get oldestWaitMs(): number;
+    submit(job: SchedulerJob<T>): JobHandle<T>;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,qFAAqF;IACrF,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;CACvB;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,mFAAmF;IACnF,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAkBD,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAgB;IACtC,YAAY,MAAM,SAAc,EAE/B;CACF;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,SAAS,CAAC,CAAC;;IAOtB,YAAY,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,EAGxD;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IASD,gEAAgE;IAChE,IAAI,YAAY,IAAI,MAAM,CAOzB;IAED,MAAM,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAkCzC;CAgFF"}

package/dist/scheduler.js

@@ -0,0 +1,162 @@
+/**
+ * Priority-ordered render scheduler.
+ *
+ * papyra does not decide what is urgent — the caller does. A viewer knows which pages
+ * are on screen, which are one scroll away, and which are thumbnails nobody is looking
+ * at; the library does not. Callers attach a priority and this queue honours it.
+ *
+ * Pending work is reordered freely. Work already running is never interrupted: a page
+ * render is dominated by a fixed, non-preemptible content-stream interpretation cost
+ * (~95ms of a ~150ms render on a large drawing, independent of output size — see
+ * docs/spike-results.md), so cancelling mid-render would reclaim only the rasterisation
+ * tail. Reordering what has not started yet captures nearly all of the benefit.
+ */
+/** Runs first. Lower is more urgent; the default is the most urgent tier. */
+export const DEFAULT_PRIORITY = 0;
+export class AbortError extends Error {
+    name = 'AbortError';
+    constructor(reason = 'cancelled') {
+        super(reason);
+    }
+}
+export class Scheduler {
+    #limit;
+    #yieldToUrgent;
+    #pending = new Map();
+    #running = new Map();
+    #seq = 0;
+    constructor(limit, options = {}) {
+        this.#limit = Math.max(1, limit);
+        this.#yieldToUrgent = options.yieldToUrgent ?? true;
+    }
+    get pendingCount() {
+        return this.#pending.size;
+    }
+    get runningCount() {
+        return this.#running.size;
+    }
+    #hasMoreUrgentRunning(priority) {
+        for (const entry of this.#running.values()) {
+            if (entry.priority < priority)
+                return true;
+        }
+        return false;
+    }
+    /** How long the longest-waiting pending job has been queued. */
+    get oldestWaitMs() {
+        let oldest = 0;
+        const now = performance.now();
+        for (const entry of this.#pending.values()) {
+            oldest = Math.max(oldest, now - entry.queuedAt);
+        }
+        return oldest;
+    }
+    submit(job) {
+        const existing = this.#pending.get(job.key) ?? this.#running.get(job.key);
+        if (existing) {
+            existing.waiters++;
+            // A more urgent request for work already queued promotes it rather than
+            // duplicating it — the common case when a thumbnail scrolls into view.
+            if (job.priority < existing.priority)
+                existing.priority = job.priority;
+            return this.#handle(existing);
+        }
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        const entry = {
+            key: job.key,
+            priority: job.priority,
+            queuedAt: performance.now(),
+            startedAt: 0,
+            finishedAt: 0,
+            seq: this.#seq++,
+            run: job.run,
+            waiters: 1,
+            started: false,
+            resolve,
+            reject,
+            promise,
+        };
+        this.#pending.set(entry.key, entry);
+        this.#drain();
+        return this.#handle(entry);
+    }
+    #handle(entry) {
+        let detached = false;
+        return {
+            key: entry.key,
+            promise: entry.promise,
+            get timing() {
+                return entry.finishedAt
+                    ? {
+                        waitMs: entry.startedAt - entry.queuedAt,
+                        runMs: entry.finishedAt - entry.startedAt,
+                    }
+                    : null;
+            },
+            setPriority: (priority) => {
+                if (!entry.started)
+                    entry.priority = priority;
+            },
+            cancel: (reason) => {
+                if (detached)
+                    return;
+                detached = true;
+                entry.waiters--;
+                if (entry.waiters > 0 || entry.started)
+                    return;
+                this.#pending.delete(entry.key);
+                entry.reject(new AbortError(reason));
+            },
+        };
+    }
+    /**
+     * Start whatever fits, most urgent first.
+     *
+     * A linear scan rather than a heap: queues are page-sized (hundreds at most) and
+     * each job costs milliseconds, so the scan is free — and mutable priorities in a
+     * binary heap need re-heapification on every change, which is a rich source of bugs.
+     */
+    #drain() {
+        while (this.#running.size < this.#limit && this.#pending.size > 0) {
+            let next;
+            for (const entry of this.#pending.values()) {
+                if (!next ||
+                    entry.priority < next.priority ||
+                    (entry.priority === next.priority && entry.seq < next.seq)) {
+                    next = entry;
+                }
+            }
+            if (!next)
+                return;
+            // Do not pile lower-priority work on top of something more urgent that is
+            // already running; it would only steal CPU from it.
+            if (this.#yieldToUrgent && this.#hasMoreUrgentRunning(next.priority))
+                return;
+            this.#pending.delete(next.key);
+            this.#running.set(next.key, next);
+            next.started = true;
+            next.startedAt = performance.now();
+            // Stamp the finish time before settling, so `timing` is already populated by
+            // the time an awaiting caller resumes — a `.finally()` would run after them.
+            next
+                .run()
+                .then((value) => {
+                next.finishedAt = performance.now();
+                next.resolve(value);
+            }, (error) => {
+                next.finishedAt = performance.now();
+                next.reject(error);
+            })
+                .finally(() => {
+                this.#running.delete(next.key);
+                this.#drain();
+            });
+        }
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/source.d.ts

@@ -0,0 +1,9 @@
+import type { PdfSource } from './types.js';
+/**
+ * Normalise any accepted input to bytes.
+ *
+ * Accepts `File` and `Blob` so an `<input type="file">` value can be passed straight
+ * through, which is the common case in a viewer.
+ */
+export declare function toBytes(source: PdfSource): Promise<Uint8Array>;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAUpE"}

package/dist/source.js

@@ -0,0 +1,22 @@
+function isBlob(value) {
+    return typeof Blob !== 'undefined' && value instanceof Blob;
+}
+/**
+ * Normalise any accepted input to bytes.
+ *
+ * Accepts `File` and `Blob` so an `<input type="file">` value can be passed straight
+ * through, which is the common case in a viewer.
+ */
+export async function toBytes(source) {
+    if (source instanceof Uint8Array)
+        return source;
+    if (isBlob(source))
+        return new Uint8Array(await source.arrayBuffer());
+    if (source instanceof ArrayBuffer)
+        return new Uint8Array(source);
+    if (ArrayBuffer.isView(source)) {
+        return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+    }
+    throw new TypeError('papyra: expected a Uint8Array, ArrayBuffer, TypedArray, Blob, or File');
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAEA,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,IAAI,KAAK,WAAW,IAAI,KAAK,YAAY,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAiB;IAC7C,IAAI,MAAM,YAAY,UAAU;QAAE,OAAO,MAAM,CAAC;IAChD,IAAI,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,UAAU,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IACtE,IAAI,MAAM,YAAY,WAAW;QAAE,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACjE,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,IAAI,SAAS,CACjB,uEAAuE,CACxE,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+/** Anything we can turn into PDF bytes. `File` is a `Blob`, so it is covered. */
+export type PdfSource = Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+export interface RenderOptions {
+    /**
+     * Scheduling order. **Lower runs first**; the default, 0, is the most urgent tier.
+     *
+     * papyra does not infer urgency — a viewer knows what is on screen and the library
+     * does not. Attach whatever scale suits you, e.g. 0 for the visible page, 1 for its
+     * neighbours, 2 for thumbnails in view, 3 for prefetch.
+     *
+     * Pending work reorders freely; work already running is never interrupted.
+     */
+    priority?: number;
+    /** Abort a request that has not started yet. */
+    signal?: AbortSignal;
+    /** Dots per inch. 72 is the PDF's natural size. Defaults to 72. */
+    dpi?: number;
+    /**
+     * Target output width in pixels. Overrides `dpi`.
+     *
+     * Prefer this for thumbnails and for fitting a viewport. A fixed DPI silently
+     * explodes on large-format pages: 36 DPI is a 216x279 thumbnail for US Letter but
+     * a 1512x1080, 6.5 MB image for a 42x30in drawing. Sizing by output width keeps
+     * cost proportional to what is actually displayed.
+     */
+    fitWidth?: number;
+}
+export interface StreamOptions extends RenderOptions {
+    /**
+     * How far ahead of consumption to queue. Defaults to the runtime's concurrency.
+     *
+     * This is backpressure, not a concurrency limit — the document-wide scheduler owns
+     * that, so a high-priority page still preempts a stream that is mid-flight.
+     */
+    concurrency?: number;
+    /**
+     * Page indices to render, in priority order. Defaults to every page in order.
+     * Results are yielded as they complete, not in this order.
+     */
+    order?: readonly number[];
+}
+/** A rendered page. `data` is tightly packed RGBA8, `height * stride` bytes. */
+export interface RenderedPage {
+    readonly width: number;
+    readonly height: number;
+    readonly stride: number;
+    readonly format: 'rgba8';
+    readonly data: Uint8Array;
+}
+export interface StreamedPage {
+    /** Index of the page in the document. */
+    readonly page: number;
+    readonly bitmap: RenderedPage;
+}
+/** Page dimensions in PDF points (1/72 inch). */
+export interface PageSize {
+    readonly width: number;
+    readonly height: number;
+}
+export interface OpenOptions {
+    /** Password for an encrypted document. */
+    password?: string;
+    /**
+     * How many pages may render at once. Defaults to the runtime's concurrency.
+     *
+     * This is a responsiveness/throughput dial. Priority can only reorder work that has
+     * not started, so a wide pool renders a batch faster but makes an urgent page wait
+     * behind more in-flight work. Viewers usually want it narrow (2-4); batch jobs want
+     * it wide.
+     */
+    concurrency?: number;
+    /**
+     * Hold back lower-priority renders while something more urgent is still running.
+     *
+     * Defaults to on, and is a no-op when every request shares a priority. Turn it off
+     * to maximise throughput at the cost of making urgent work wait.
+     */
+    yieldToUrgent?: boolean;
+    /**
+     * Bytes of rendered pages to keep for reuse. Defaults to 128 MB; `0` disables it.
+     *
+     * A render is never cheap — on a large CAD drawing every page costs >=93ms however
+     * small the output — and viewers re-render the same page constantly. Bounded by bytes
+     * rather than entries because page bitmaps span three orders of magnitude.
+     *
+     * Only the single-page path is cached (`render`, `renderPage`, `stream`).
+     * `renderPages` is a throughput API and would evict everything useful in one call.
+     */
+    cacheBytes?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,eAAe,GAAG,IAAI,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,iDAAiD;AACjD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@build-qube/papyra",
+  "version": "0.0.3",
+  "description": "Fast PDF rendering for Node and the browser, powered by Rust",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BuildQube/papyra.git",
+    "directory": "packages/papyra"
+  },
+  "keywords": [
+    "pdf",
+    "render",
+    "thumbnail",
+    "rust",
+    "wasm",
+    "pdfjs"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@build-qube/papyra-native": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}