@build-qube/papyra 0.0.4 → 0.2.0

package/README.md

@@ -0,0 +1,129 @@
+# papyra
+
+Fast PDF rendering for Node **and** the browser, from one Rust core. The engine
+([hayro](https://github.com/LaurenzV/hayro)) is compiled in — there are no pdfium
+binaries to ship and nothing to install alongside it.
+
+## Install
+
+```bash
+npm install @build-qube/papyra
+```
+
+The native addon and the browser wasm build ship as optional dependencies; your
+package manager picks the right one.
+
+## Render a page
+
+```ts
+import { open, paintToCanvas } from '@build-qube/papyra';
+
+const doc = await open(file); // Uint8Array | ArrayBuffer | Blob | File
+const page = await doc.renderPage(0, { fitWidth: 1600 });
+
+paintToCanvas(page, canvas);
+```
+
+`renderPage` never blocks the event loop. `page` is tightly packed RGBA8, so
+`paintToCanvas` is a convenience rather than the only route — `toImageData`, the
+encoders, or your own buffer handling all work from the same bytes.
+
+## Thumbnails
+
+`stream` yields pages as they finish, with concurrency bounded for you:
+
+```ts
+for await (const { page, bitmap } of doc.stream({ fitWidth: 160 })) {
+  paint(page, bitmap);
+}
+```
+
+## Say what is urgent
+
+papyra does not guess which page matters — a viewer knows what is on screen and the
+library does not. Attach a priority and the queue honours it. **Lower runs first**,
+and the default is the most urgent tier, so callers who do not care can ignore this
+entirely.
+
+```ts
+const doc = await open(file, { concurrency: 4 }); // viewers want a narrow pool
+
+// Thumbnails yield to whatever is on screen.
+for await (const t of doc.stream({ fitWidth: 160, priority: 2 })) { /* … */ }
+
+// Reprioritise on scroll instead of cancelling and resubmitting.
+const job = doc.render(12, { fitWidth: 1600, priority: 2 });
+onScroll(() => job.setPriority(isVisible(12) ? 0 : 3));
+```
+
+Requests for the same page at the same size coalesce into one render. Pending work
+reorders freely; work already running is never interrupted.
+
+## Export, text, and outlines
+
+```ts
+const image = await doc.renderImage(0, { fitWidth: 2000 });
+await writeFile('page-0.webp', (await image.toWebp()).bytes);
+
+for await (const hit of doc.search('site plan')) {
+  highlight(hit.page, hit.rects);
+}
+
+for (const node of await doc.outline()) {
+  if (node.page !== null) goTo(node.page);
+}
+```
+
+`renderImage` keeps the pixels in Rust and encodes on demand, so nothing but the
+finished file crosses into JS. For output that has to survive being scaled there is
+`doc.renderSvg(0)`, which returns vector markup instead of pixels and so takes no
+size and no quality.
+
+## Links, labels, and what the file says about itself
+
+```ts
+const scale = rendered.width / doc.pageSize(index).width;
+for (const link of await doc.links(index)) {
+  const box = scaleRect(link.rect, scale);
+  if (link.target.kind === 'uri') openExternally(link.target.uri);
+  else goTo(link.target.dest.page);
+}
+
+const labels = await doc.pageLabels();
+const shown = labels[index] || String(index + 1);   // "iv", not "4"
+
+doc.metadata.title;   // null when the document never said
+doc.fingerprint;      // stable key for per-document state
+```
+
+Link rectangles are in the same space as extracted text — 72 DPI from the top-left,
+rotation applied — so one multiply places them over any render. `pageLabels()` is empty
+when the document defines no labels, which is your signal to number by index.
+
+Encrypted files throw `PasswordRequiredError` or `IncorrectPasswordError`, both
+extending `PasswordError` with a `retry` flag, so one dialog handles the cold ask and
+the wrong answer.
+
+## Two things that will bite you
+
+**Size with `fitWidth`, not `dpi`.** Page areas vary by two orders of magnitude. At a
+fixed 36 DPI, US Letter is a 216x279 thumbnail while a 42x30in drawing is a 1512x1080,
+6.5 MB image. Sizing by output width keeps cost proportional to what you actually
+display; renders above 100 MP are refused outright.
+
+**The browser build needs cross-origin isolation.** It uses shared wasm memory, so
+`SharedArrayBuffer` must be available. Serve your page with:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+## More
+
+The [full API reference](https://buildqube.github.io/Papyra/docs) is generated from
+these sources, so it never drifts from them. The
+[project README](https://github.com/BuildQube/Papyra) covers architecture, benchmarks
+against pdf.js, and the measurements behind these defaults.
+
+MIT.

package/dist/cache.d.ts

@@ -15,8 +15,11 @@
 export interface CacheStats {
     /** Bytes currently held. */
     bytes: number;
+    /** Pages currently held. */
     entries: number;
+    /** Lookups served without rendering. */
     hits: number;
+    /** Lookups that had to render. */
     misses: number;
     /** Entries dropped to stay under budget. */
     evictions: number;

package/dist/cache.d.ts.map

@@ -1 +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"}
+{"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,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,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.map

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

package/dist/document.d.ts

@@ -1,32 +1,226 @@
 import { PdfDocument as NativeDocument } from '@build-qube/papyra-native';
 import { type CacheStats } from './cache.js';
+import { PageImage, type SvgPage } from './encode.js';
+import { type PageLink } from './links.js';
+import { type OutlineNode } from './outline.js';
 import { type JobHandle } from './scheduler.js';
-import type { OpenOptions, PageSize, PdfSource, RenderedPage, RenderOptions, StreamedPage, StreamOptions } from './types.js';
+import { type SearchMatch } from './search.js';
+import { type PageText } from './text.js';
+import type { DocumentMetadata, OpenOptions, PageSize, PdfSource, RenderedPage, RenderOptions, SearchOptions, StreamedPage, StreamOptions, SvgOptions } from './types.js';
 /** A queued render, plus whether it was served from cache without rendering at all. */
 export interface RenderHandle extends JobHandle<RenderedPage> {
+    /**
+     * The page was already in the cache and nothing was queued.
+     *
+     * `promise` still resolves normally, so this only matters for instrumentation —
+     * a cache hit costs none of the ~93ms floor a real render does.
+     */
     readonly cached: boolean;
 }
-/** Open a PDF from bytes, an `ArrayBuffer`, a `Blob`, or a `File`. */
+/**
+ * A queued export render. No `cached` flag: unlike {@link RenderHandle} the image path
+ * never comes from the cache, which is keyed by page and size with no format dimension.
+ */
+export type ImageHandle = JobHandle<PageImage>;
+/**
+ * A queued SVG conversion. Uncached for the same reason as {@link ImageHandle}, and
+ * unsized: an SVG has no DPI to key on.
+ */
+export type SvgHandle = JobHandle<SvgPage>;
+/**
+ * Open a PDF from bytes, an `ArrayBuffer`, a `Blob`, or a `File`.
+ *
+ * Throws {@link PasswordRequiredError} when the document is encrypted and no
+ * {@link OpenOptions.password} was given, and {@link IncorrectPasswordError} when one
+ * was given and rejected. Both extend {@link PasswordError}, so a viewer that shows
+ * one dialog for both can catch the base.
+ */
 export declare function open(source: PdfSource, options?: OpenOptions): Promise<Document>;
+/**
+ * An open PDF, and the queue and caches that serve it.
+ *
+ * Every page-level call goes through one shared scheduler, so a thumbnail sweep can
+ * never starve the page on screen — attach a {@link RenderOptions.priority} and the
+ * queue reorders around it. Construct via {@link open}, not `new`.
+ */
 export declare class Document {
     #private;
+    /**
+     * A stable identifier for this document's bytes.
+     *
+     * Sixteen hex characters, for keying whatever you remember per document — the page
+     * it was left on, a zoom level, a set of highlights. Two `open` calls on the same
+     * file always agree.
+     *
+     * It is a hash of the file, **not** the PDF's own `/ID`: the engine exposes no
+     * trailer accessor, so that identifier is out of reach. The practical difference is
+     * that saving an incremental update changes this while `/ID` would have survived.
+     */
+    readonly fingerprint: string;
     /** @internal — construct via {@link open}. */
-    constructor(inner: NativeDocument, options?: OpenOptions);
+    constructor(inner: NativeDocument, fingerprintOfBytes: string, 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(): {
+        /** Submitted but not started. These are the ones priority can still reorder. */
         pending: number;
+        /** Rendering now. Never preempted, so this is work you are committed to. */
         running: number;
+        /**
+         * How long the longest-waiting pending job has sat there.
+         *
+         * The number to watch in a viewer: if it climbs, the pool is too wide for the
+         * work or a priority is wrong.
+         */
         oldestWaitMs: number;
     };
+    /** How many pages the document has. Page indices are 0-based throughout. */
     get pageCount(): number;
+    /**
+     * The PDF specification version the file declares, e.g. `'1.7'`.
+     *
+     * Deliberately not part of {@link Document.metadata}: that is what the producer
+     * chose to say about the document, while this is a structural property read from
+     * the file's header — and from the catalog, which overrides it for 1.4 and later,
+     * so an incrementally saved file reports the version it was last written as.
+     *
+     * `'1.0'` is worth treating with suspicion. Genuine PDF 1.0 files are close to
+     * extinct, and it is also what a file with an unreadable header reports.
+     */
+    get pdfVersion(): string | null;
+    /**
+     * The document outline — bookmarks, the table of contents — as a tree.
+     *
+     * Resolves to an empty array when the document has no outline, which is the common
+     * case. The walk runs off the event loop and the result is memoised, so calling
+     * this on every render of a sidebar costs nothing after the first.
+     *
+     * Entries that point outside the document (a URL, another file) and containers that
+     * group children without a destination of their own both have a `dest` of `null`;
+     * they are kept because a viewer still lists them.
+     *
+     * @example
+     * ```ts
+     * for (const node of await doc.outline()) {
+     *   if (node.page !== null) void doc.render(node.page, { fitWidth: 1600 });
+     * }
+     * ```
+     */
+    outline(): Promise<OutlineNode[]>;
+    /**
+     * What the document says about itself: title, author, dates, the tool that wrote it.
+     *
+     * Synchronous — the engine reads the information dictionary while loading, so this
+     * only decodes strings. Every field is independently `null`, and none of it is
+     * verified; `title` in particular is often a filename or missing entirely.
+     */
+    get metadata(): DocumentMetadata;
+    /**
+     * The label printed on each page, one entry per page.
+     *
+     * Resolves to an **empty array** when the document defines no page labels, which is
+     * the common case — that is the signal to number pages by index yourself. A
+     * document that defines labels but says nothing about a particular page gives that
+     * page an empty string, which is a different answer.
+     *
+     * Worth honouring wherever a page number is shown: a document with front matter
+     * numbers its first pages i, ii, iii, and a viewer that says "page 4 of 300" when
+     * the sheet reads "A101" is describing a document nobody else can see.
+     *
+     * The walk runs off the event loop and the result is memoised.
+     *
+     * @example
+     * ```ts
+     * const labels = await doc.pageLabels();
+     * const shown = labels[index] || String(index + 1);
+     * ```
+     */
+    pageLabels(): Promise<readonly string[]>;
+    /**
+     * The links on one page — where they are, and where they go.
+     *
+     * Rectangles are in the same 72-DPI top-left space as {@link Document.pageText} and
+     * {@link Document.pageSize}, so placing them over a render is one multiply; see
+     * {@link scaleRect}. Only links that resolve to something actionable are reported.
+     *
+     * Unlike text extraction this never interprets a content stream — it is an
+     * object-graph read, roughly a thousandth the cost of rendering the page — so it
+     * does **not** go through the priority queue. Making a link layer wait behind
+     * renders would add latency a viewer can feel, for work that costs nothing.
+     * Results are cached, and two calls for the same page share one read.
+     *
+     * @example
+     * ```ts
+     * const scale = rendered.width / doc.pageSize(index).width;
+     * for (const link of await doc.links(index)) {
+     *   const { x, y, width, height } = scaleRect(link.rect, scale);
+     *   // ...position an anchor over the canvas
+     * }
+     * ```
+     */
+    links(index: number): Promise<readonly PageLink[]>;
     /** 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 for export, keeping the pixels in Rust.
+     *
+     * The returned {@link PageImage} encodes on demand — `toWebp()`, `toPng()`,
+     * `toJpeg()`, `toDataUrl()` — and never hands the raw bitmap to JS. A 42x30in
+     * drawing at 150 DPI is 6.5 MB raw and a fraction of that encoded, so for anything
+     * leaving the process that buffer is pure overhead.
+     *
+     * Use `renderPage` when you want to paint to a canvas, and `encode()` when you want
+     * both the pixels and a file.
+     *
+     * Shares the scheduler with every other render, so priority and concurrency behave
+     * exactly as they do for `render`. **Not cached** — the cache is keyed by page and
+     * size with no format dimension, and it measures raw bytes.
+     *
+     * @example
+     * ```ts
+     * const img = await doc.renderImage(0, { fitWidth: 2000 });
+     * await writeFile('page-0.webp', (await img.toWebp()).bytes);
+     * ```
+     */
+    renderImage(index: number, options?: RenderOptions): Promise<PageImage>;
+    /**
+     * As {@link renderImage}, but returns the handle so the job can be reprioritised,
+     * cancelled, or timed — the same relationship `render` has to `renderPage`.
+     *
+     * `timing` is where the export path becomes measurable: it separates queue wait from
+     * render time, which end-to-end timing around the promise cannot.
+     */
+    imageHandle(index: number, options?: RenderOptions): ImageHandle;
+    /**
+     * Convert a page to SVG — vector output, not pixels.
+     *
+     * Paths stay paths and text stays glyph outlines, so the result scales to any size
+     * and can be edited downstream. That is the trade: an SVG of a dense drawing is
+     * larger than a WebP of the same page at screen size and slower for a browser to
+     * paint, but it is the only output that survives being scaled up.
+     *
+     * Conversion is content-stream interpretation without rasterisation — roughly the
+     * non-preemptible portion of a render — so it shares the scheduler with everything
+     * else and honours {@link SvgOptions.priority}. **Not cached**, for the same reason
+     * {@link renderImage} is not.
+     *
+     * @example
+     * ```ts
+     * const page = await doc.renderSvg(0, { background: 'transparent' });
+     * await writeFile('page-0.svg', page.markup);
+     * ```
+     */
+    renderSvg(index: number, options?: SvgOptions): Promise<SvgPage>;
+    /**
+     * As {@link renderSvg}, but returns the handle so the job can be reprioritised,
+     * cancelled, or timed — the same relationship `imageHandle` has to `renderImage`.
+     */
+    svgHandle(index: number, options?: SvgOptions): SvgHandle;
     /**
      * Render a page, returning a handle you can reprioritise or drop.
      *
@@ -73,6 +267,60 @@ export declare class Document {
      * ```
      */
     stream(options?: StreamOptions): AsyncGenerator<StreamedPage>;
+    /**
+     * Extract the text of one page.
+     *
+     * Scheduled like a render, but behind one by default: a search should not stall the
+     * page the user is looking at. Results are cached, so searching the same document
+     * repeatedly extracts each page once.
+     *
+     * Extraction is interpretation without rasterisation, which makes it roughly a
+     * hundredth the cost of rendering the same page — about 1ms for a dense page of a
+     * paper. It is cheap enough to do speculatively.
+     */
+    pageText(index: number, options?: {
+        priority?: number;
+        signal?: AbortSignal;
+    }): Promise<PageText>;
+    /**
+     * Extract every page's text up front, so a later search is immediate.
+     *
+     * Worth calling on a long document: on native this fans out across rayon rather
+     * than the JS thread pool, which an addon cannot resize past four threads —
+     * measured 15ms for a 14-page paper against ~1ms per page one at a time.
+     *
+     * On wasm it walks the pages through the scheduler instead. The rayon batch is a
+     * native-only path for the same reason `renderPages` is: rayon's wasm workers are
+     * Web Workers the JS event loop has to create, and driving a batch from a blocked
+     * thread traps (`docs/spike-results.md`, "wasm parallel rendering is UNSTABLE").
+     *
+     * Idempotent, and never necessary — {@link search} extracts what it needs as it
+     * goes. This only trades a pause now for instant results later.
+     */
+    indexText(options?: {
+        priority?: number;
+    }): Promise<void>;
+    /**
+     * Find `query` in the document, yielding matches as each page is searched.
+     *
+     * Streaming rather than collected, because the first hit is usually the one the user
+     * wants and a long document should not make them wait for the last. Breaking out of
+     * the loop stops the search.
+     *
+     * `order` is the lever a viewer wants: searching outward from the current page finds
+     * the nearest hit first, which is almost never page 1.
+     *
+     * @example
+     * ```ts
+     * for await (const hit of doc.search('site plan', { order: outward(current) })) {
+     *   show(hit.page, hit.rects);
+     *   break;
+     * }
+     * ```
+     */
+    search(query: string, options?: SearchOptions): AsyncGenerator<SearchMatch>;
+    /** Extracted page text held for reuse, and how often that has paid off. */
+    get textCache(): CacheStats;
     /** How many pages this document will render at once. */
     get concurrency(): number;
 }

package/dist/document.d.ts.map

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