@2018kguo/recto 0.3.0 → 0.5.0

package/dist/document.d.ts

@@ -170,6 +170,23 @@ export type PdfRenderOptions = {
     width: number;
     /** Default 4096. May be Infinity, to fit the width alone. A render is capped at 16,384 px a side and 64 Mpx. */
     maxHeight?: number;
+    /**
+     * Draws only this part of the page: x, y, width, height in points in the viewer frame, as text and
+     * annotation boxes are (top-left origin, `/Rotate` and the crop box applied). The bitmap holds the
+     * pixels of the whole page's bitmap at the scale `width` and `maxHeight` give that this covers,
+     * grown out to whole pixels and cut to the page, and says where they are. With a region the limits
+     * are on the region's bitmap, not the page's, and `width` may be up to 262,144.
+     */
+    region?: PdfBox;
+};
+/** A render of a region: where its pixels are in the whole page's bitmap at that scale. */
+export type PdfRegionBitmap = PdfBitmap & {
+    /** The bitmap's top-left pixel, in the whole page's bitmap. */
+    x: number;
+    y: number;
+    /** The whole page's bitmap's size at this scale: what `render` without a region and its limits would give. */
+    pageWidth: number;
+    pageHeight: number;
 };
 export type PdfRenderAsyncOptions = PdfRenderOptions & {
     /** Stops the render at the next pause: `aborted`, with the document still usable. */
@@ -188,6 +205,67 @@ export type PdfBitmap = {
      */
     truncated: boolean;
 };
+/** Where a link in this file goes: a page, and the place on it in that page's viewer frame. */
+export type PdfDestination = {
+    /** The page's index, or -1 if it goes nowhere in this file. */
+    page: number;
+    /**
+     * How to show the page, as the file names it: "XYZ", "Fit", "FitH", "FitV", "FitR", "FitB", "FitBH",
+     * "FitBV"; null if it names none.
+     */
+    view: string | null;
+    /**
+     * The point to bring to the window's top-left, in points in the target page's viewer frame
+     * (top-left origin, its `/Rotate` and crop box applied). null for a coordinate the destination leaves
+     * as it was; under a quarter turn, the page's `left` is the viewer's `y`.
+     */
+    x: number | null;
+    y: number | null;
+    /** "XYZ"'s zoom, 1 for 100%; null to leave it as it was. */
+    zoom: number | null;
+    /** "FitR"'s rectangle, in the target page's viewer frame; null for any other view. */
+    box: PdfBox | null;
+};
+/** What a link does. Another file or a program is reported, never followed. */
+export type PdfLinkTarget = {
+    kind: "uri";
+    uri: string;
+}
+/** A `GoTo` action or the link's `/Dest`, named destinations resolved. */
+ | {
+    kind: "page";
+    destination: PdfDestination;
+}
+/** `GoToR`: a destination in another file, by name or by page number there. */
+ | {
+    kind: "remote";
+    file: string;
+    name: string | null;
+    page: number | null;
+}
+/** `Launch`: a file or program. */
+ | {
+    kind: "launch";
+    file: string;
+}
+/** Any other action by its `/S` ("JavaScript", "SubmitForm", ...); a `Named` action's `/N` ("NextPage", ...) is `name`. */
+ | {
+    kind: "action";
+    action: string;
+    name: string | null;
+}
+/** No action and no destination. */
+ | {
+    kind: "none";
+};
+/** A `/Link` annotation and where it goes. */
+export type PdfLink = {
+    /** Its index in what `annotations` returns for the page. */
+    annotation: number;
+    /** Its `/Rect` in the viewer frame, as its annotation's `box`. */
+    box: PdfBox;
+    target: PdfLinkTarget;
+};
 export declare const ANNOT_SUBTYPE: {
     readonly text: 1;
     readonly link: 2;
@@ -237,11 +315,22 @@ export interface PdfDocument {
     };
     objects(index: number): PdfPageObjects;
     annotations(index: number): PdfAnnotation[];
+    /**
+     * The page's links, in the order `annotations` lists them, and where each goes. Loads drawing's
+     * part of the wasm, as `objects` does.
+     */
+    links(index: number): PdfLink[];
+    render(index: number, options: PdfRenderOptions & {
+        region: PdfBox;
+    }): PdfRegionBitmap;
     render(index: number, options: PdfRenderOptions): PdfBitmap;
     /**
      * The same pixels as `render`, giving the thread back between slices, and stoppable with a
      * signal. The last step, rasterizing, is one piece: about a third of a heavy page's time.
      */
+    renderAsync(index: number, options: PdfRenderAsyncOptions & {
+        region: PdfBox;
+    }): Promise<PdfRegionBitmap>;
     renderAsync(index: number, options: PdfRenderAsyncOptions): Promise<PdfBitmap>;
     close(): void;
     [Symbol.dispose](): void;
@@ -291,6 +380,7 @@ export declare class RectoDocument implements PdfDocument {
     };
     outline(): PdfOutlineItem[];
     annotations(index: number): PdfAnnotation[];
+    links(index: number): PdfLink[];
     scan(index: number): {
         text: PdfPageText;
         objects: PdfPageObjects;
@@ -300,7 +390,13 @@ export declare class RectoDocument implements PdfDocument {
         text: PdfPageText;
         annotations: PdfAnnotation[];
     };
+    render(index: number, options: PdfRenderOptions & {
+        region: PdfBox;
+    }): PdfRegionBitmap;
     render(index: number, options: PdfRenderOptions): PdfBitmap;
+    renderAsync(index: number, options: PdfRenderAsyncOptions & {
+        region: PdfBox;
+    }): Promise<PdfRegionBitmap>;
     renderAsync(index: number, options: PdfRenderAsyncOptions): Promise<PdfBitmap>;
     close(): void;
     [Symbol.dispose](): void;

package/dist/document.js

@@ -45,6 +45,37 @@ export const ANNOT_SUBTYPE = {
 };
 const DEFAULT_MAX_HEIGHT = 4096;
 const MAX_DIMENSION = 16_384;
+/** With a region, the whole page's bitmap may be up to this wide. */
+const MAX_REGION_DIMENSION = 262_144;
+/** `width`, `maxHeight` and the region as the engine takes them (NaNs for none), or a RangeError. */
+function renderArgs(options) {
+    const maxHeight = options.maxHeight ?? DEFAULT_MAX_HEIGHT;
+    const { region } = options;
+    const most = region ? MAX_REGION_DIMENSION : MAX_DIMENSION;
+    if (!(options.width > 0 && options.width <= most) || !(maxHeight > 0)) {
+        throw new RangeError(region
+            ? `with a region, render width must be in 1..${MAX_REGION_DIMENSION} and maxHeight above 0`
+            : `render width must be in 1..${MAX_DIMENSION} and maxHeight above 0`);
+    }
+    if (!region) {
+        return [options.width, maxHeight, Number.NaN, Number.NaN, Number.NaN, Number.NaN];
+    }
+    const { x, y, width, height } = region;
+    if (![x, y, width, height].every((v) => typeof v === "number" && Number.isFinite(v)) || !(width > 0 && height > 0)) {
+        throw new RangeError("a render's region needs finite x and y, and width and height above 0");
+    }
+    return [options.width, maxHeight, x, y, width, height];
+}
+/** A rendered page as `render` returns it: with a region, where it is on the page. */
+function bitmapOf(page, region) {
+    const bitmap = {
+        width: page.width,
+        height: page.height,
+        truncated: page.truncated,
+        rgba: page.takeRgba(),
+    };
+    return region ? { ...bitmap, x: page.x, y: page.y, pageWidth: page.pageWidth, pageHeight: page.pageHeight } : bitmap;
+}
 /** What a call into the instance threw, as what the caller should see. */
 export function engineFailure(instance, error) {
     if (error instanceof PdfError) {
@@ -167,6 +198,31 @@ function toAnnotations(a) {
         return out;
     });
 }
+function toLink([annotation, x, y, width, height, kind, text, page, view, destX, destY, zoom, rx, ry, rw, rh, name]) {
+    const number = (v) => (Number.isNaN(v) ? null : v);
+    const target = kind === "uri"
+        ? { kind, uri: text }
+        : kind === "page"
+            ? {
+                kind,
+                destination: {
+                    page,
+                    view,
+                    x: number(destX),
+                    y: number(destY),
+                    zoom: number(zoom),
+                    box: Number.isNaN(rx) ? null : { x: rx, y: ry, width: rw, height: rh },
+                },
+            }
+            : kind === "remote"
+                ? { kind, file: text, name, page: page < 0 ? null : page }
+                : kind === "launch"
+                    ? { kind, file: text }
+                    : kind === "action"
+                        ? { kind, action: text, name }
+                        : { kind: "none" };
+    return { annotation, box: { x, y, width, height }, target };
+}
 const DEFAULT_SLICE_MS = 8;
 /** Back to the event loop, without the 4 ms a nested timer waits in a browser. */
 function nextTask() {
@@ -306,6 +362,12 @@ export class RectoDocument {
         this.#check(index);
         return this.#call(() => toAnnotations(this.#doc.annotations(index)));
     }
+    links(index) {
+        this.#check(index);
+        // A viewer's call: its code is in drawing's part, so text alone downloads none of it.
+        this.#needsRender();
+        return this.#call(() => this.#doc.links(index).map(toLink));
+    }
     scan(index) {
         this.#check(index);
         this.#needsRender();
@@ -324,30 +386,17 @@ export class RectoDocument {
     }
     render(index, options) {
         this.#check(index);
-        const maxHeight = options.maxHeight ?? DEFAULT_MAX_HEIGHT;
-        if (!(options.width > 0 && options.width <= MAX_DIMENSION) ||
-            !(maxHeight > 0)) {
-            throw new RangeError(`render width must be in 1..${MAX_DIMENSION} and maxHeight above 0`);
-        }
+        const args = renderArgs(options);
         this.#needsRender();
-        return this.#call(() => consume(this.#doc.render(index, options.width, maxHeight), (page) => ({
-            width: page.width,
-            height: page.height,
-            truncated: page.truncated,
-            rgba: page.takeRgba(),
-        })));
+        return this.#call(() => consume(this.#doc.render(index, ...args), (page) => bitmapOf(page, options.region !== undefined)));
     }
     async renderAsync(index, options) {
         this.#check(index);
-        const maxHeight = options.maxHeight ?? DEFAULT_MAX_HEIGHT;
-        if (!(options.width > 0 && options.width <= MAX_DIMENSION) ||
-            !(maxHeight > 0)) {
-            throw new RangeError(`render width must be in 1..${MAX_DIMENSION} and maxHeight above 0`);
-        }
+        const args = renderArgs(options);
         this.#needsRender();
         const instance = this.#instance;
         const sliceMs = options.sliceMs ?? DEFAULT_SLICE_MS;
-        const task = this.#call(() => this.#doc.renderTask(index, options.width, maxHeight));
+        const task = this.#call(() => this.#doc.renderTask(index, ...args));
         const stopIfAsked = () => {
             if (options.signal?.aborted) {
                 throw new PdfError("aborted", "the signal was aborted", options.signal.reason);
@@ -370,12 +419,7 @@ export class RectoDocument {
             }
             await nextTask();
             stopIfAsked();
-            return this.#call(() => consume(task.finish(), (page) => ({
-                width: page.width,
-                height: page.height,
-                truncated: page.truncated,
-                rgba: page.takeRgba(),
-            })));
+            return this.#call(() => consume(task.finish(), (page) => bitmapOf(page, options.region !== undefined)));
         }
         finally {
             if (!instance.dead && !instance.abandoned) {

package/dist/engine.d.ts

@@ -15,6 +15,13 @@ export type PdfEngineOptions = {
      * with a document still open, the next open gets a new one.
      */
     recycleAboveBytes?: number;
+    /**
+     * The most bytes one stream may decode to, and one image hold at a byte a component. Past it, that
+     * stream or image is left out and the page's results say `truncated`, so a few bytes that inflate to
+     * gigabytes can't take the instance's memory. Default 768 MiB (a 600 dpi gray scan of an A0 page is
+     * 558 MB); `Infinity` for none.
+     */
+    maxDecodedBytes?: number;
     /**
      * Files to fetch and verify while the engine is created, so that a missing one fails here and no later
      * call waits for it. `recto-render.wasm` saves the first `render` that wait; all three parts check the

package/dist/engine.js

@@ -60,7 +60,7 @@ export function hashOn(instance) {
     };
 }
 const hashing = new WeakSet();
-function instantiate(generation, base, module, documents = { open: 0 }) {
+function instantiate(generation, base, module, maxDecodedBytes, documents = { open: 0 }) {
     const parts = new Set();
     // A function of a part that isn't loaded yet: load it, then make the call this was meant to be. A
     // failure unwinds the engine's frames with its state half-done, so no call can follow on this
@@ -137,6 +137,9 @@ function instantiate(generation, base, module, documents = { open: 0 }) {
             return;
         }
     });
+    if (maxDecodedBytes !== undefined) {
+        glue.setMaxDecodedBytes(maxDecodedBytes);
+    }
     return instance;
 }
 function bytesOf(input) {
@@ -160,6 +163,7 @@ class RectoEngine {
     #starting = null;
     #base;
     #recycleAboveBytes;
+    #maxDecodedBytes;
     /** Past this, an instance with a document open takes no other. */
     #idleAboveBytes;
     /** Whether an instance that grew goes once nothing has been open on it for IDLE_MS: the default. */
@@ -167,7 +171,8 @@ class RectoEngine {
     #idle;
     /** Across every instance: a document that moved, or stayed on an old one, still counts. */
     #documents;
-    constructor(instance, base, recycleAboveBytes) {
+    constructor(instance, base, recycleAboveBytes, maxDecodedBytes) {
+        this.#maxDecodedBytes = maxDecodedBytes;
         this.#instance = instance;
         this.#generation = instance.generation;
         this.#base = base;
@@ -218,7 +223,7 @@ class RectoEngine {
             return current;
         }
         this.#starting ??= compile("recto.wasm", this.#base)
-            .then((module) => instantiate(this.#generation + 1, this.#base, module, this.#documents))
+            .then((module) => instantiate(this.#generation + 1, this.#base, module, this.#maxDecodedBytes, this.#documents))
             .finally(() => {
             this.#starting = null;
         });
@@ -238,7 +243,7 @@ class RectoEngine {
             return current;
         }
         // Compiled already: it's what the abandoned instance ran.
-        const instance = instantiate(this.#generation + 1, this.#base, compiled.get(moduleKey("recto.wasm", this.#base)), this.#documents);
+        const instance = instantiate(this.#generation + 1, this.#base, compiled.get(moduleKey("recto.wasm", this.#base)), this.#maxDecodedBytes, this.#documents);
         this.#adopt(instance);
         return instance;
     }
@@ -290,10 +295,10 @@ class RectoEngine {
         }
         const owned = ownedSource(source);
         const instance = await this.#live();
-        const loader = startRangeLoader(owned, options);
-        const read = (offset, length) => {
+        const loader = await startRangeLoader(owned, options);
+        const read = (offset, length, ahead) => {
             const out = new Uint8Array(length);
-            return loader.read(offset, out) ? out : undefined;
+            return loader.read(offset, out, ahead) ? out : undefined;
         };
         const password = options.password ?? null;
         let doc;
@@ -350,7 +355,11 @@ async function createEngine(options) {
         ...(canRead ? names.filter(isPart) : PARTS).map((part) => compile(part, base)),
         preloadAssets(base, files),
     ]);
-    return new RectoEngine(instantiate(0, base, module), base, options.recycleAboveBytes);
+    const maxDecodedBytes = options.maxDecodedBytes;
+    if (maxDecodedBytes !== undefined && !(typeof maxDecodedBytes === "number" && maxDecodedBytes >= 0)) {
+        throw new RangeError("maxDecodedBytes must be a number of bytes, 0 or more");
+    }
+    return new RectoEngine(instantiate(0, base, module, maxDecodedBytes), base, options.recycleAboveBytes, maxDecodedBytes);
 }
 let shared = null;
 let sharedReady = null;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { ANNOT_SUBTYPE, boxAt, CHAR_GENERATED, CHAR_UNMAPPED, charsText, PATH_FILL, PATH_STROKE, type PdfAnnotation, type PdfBitmap, type PdfBox, type PdfDocument, type PdfFont, type PdfOutlineItem, type PdfPageInfo, type PdfPageObjects, type PdfPageText, type PdfPathSegments, type PdfRenderAsyncOptions, type PdfRenderOptions, type PdfTextRuns, type PdfWords, SEGMENT_BEZIER, SEGMENT_CLOSE, SEGMENT_LINE, SEGMENT_MOVE, SEGMENT_RECT, } from "./document.ts";
+export { ANNOT_SUBTYPE, boxAt, CHAR_GENERATED, CHAR_UNMAPPED, charsText, PATH_FILL, PATH_STROKE, type PdfAnnotation, type PdfBitmap, type PdfBox, type PdfDestination, type PdfDocument, type PdfFont, type PdfLink, type PdfLinkTarget, type PdfOutlineItem, type PdfPageInfo, type PdfPageObjects, type PdfPageText, type PdfPathSegments, type PdfRegionBitmap, type PdfRenderAsyncOptions, type PdfRenderOptions, type PdfTextRuns, type PdfWords, SEGMENT_BEZIER, SEGMENT_CLOSE, SEGMENT_LINE, SEGMENT_MOVE, SEGMENT_RECT, } from "./document.ts";
 export { createPdfEngine, openPdf, type PdfEngine, type PdfEngineOptions, type PdfEngineStats, type PdfOpenOptions, } from "./engine.ts";
 export { PdfError, type PdfErrorCode } from "./errors.ts";
 export type { PdfPool, PdfPoolDocument, PdfPoolOpenOptions, PdfPoolOptions } from "./pool.ts";

package/dist/pool-worker.d.ts

@@ -11,4 +11,5 @@ export type PoolRequest = {
 };
 export type PoolStart = {
     assetBase: string | undefined;
+    maxDecodedBytes: number | undefined;
 };

package/dist/pool-worker.js

@@ -32,9 +32,9 @@ function failureOf(error) {
 }
 async function handle(message) {
     if (!("id" in message)) {
-        const { assetBase } = message;
+        const { assetBase, maxDecodedBytes } = message;
         try {
-            engine = await createPdfEngine(assetBase ? { assetBase } : {});
+            engine = await createPdfEngine({ ...(assetBase ? { assetBase } : {}), ...(maxDecodedBytes === undefined ? {} : { maxDecodedBytes }) });
             port.postMessage({ ready: true }, []);
         }
         catch (error) {

package/dist/pool.d.ts

@@ -1,9 +1,11 @@
-import type { PdfAnnotation, PdfBitmap, PdfOutlineItem, PdfPageInfo, PdfPageObjects, PdfPageText, PdfRenderOptions } from "./document.ts";
+import type { PdfAnnotation, PdfBitmap, PdfBox, PdfLink, PdfOutlineItem, PdfPageInfo, PdfPageObjects, PdfPageText, PdfRegionBitmap, PdfRenderOptions } from "./document.ts";
 export type PdfPoolOptions = {
     /** At most this many threads, up to 64. Default: one less than the machine's cores, up to 8. */
     threads?: number;
     /** As for `createPdfEngine`. A string: it crosses to the threads. */
     assetBase?: string;
+    /** As for `createPdfEngine`, on every thread. */
+    maxDecodedBytes?: number;
 };
 export type PdfPoolOpenOptions = {
     password?: string;
@@ -15,8 +17,12 @@ export interface PdfPoolDocument {
     text(index: number): Promise<PdfPageText>;
     objects(index: number): Promise<PdfPageObjects>;
     annotations(index: number): Promise<PdfAnnotation[]>;
+    links(index: number): Promise<PdfLink[]>;
     outline(): Promise<PdfOutlineItem[]>;
     /** Takes no `signal`: a call that's running can't be stopped. */
+    render(index: number, options: PdfRenderOptions & {
+        region: PdfBox;
+    }): Promise<PdfRegionBitmap>;
     render(index: number, options: PdfRenderOptions): Promise<PdfBitmap>;
     /** Frees it on every thread, and fails its calls still waiting with `closed`. */
     close(): Promise<void>;

package/dist/pool.js

@@ -39,6 +39,7 @@ class Pool {
     #limit;
     #ceiling;
     #assetBase;
+    #maxDecodedBytes;
     #threads = [];
     /** Started and not yet ready. */
     #startingThreads = new Set();
@@ -46,10 +47,11 @@ class Pool {
     #nextFile = 0;
     #nextId = 0;
     #closed = false;
-    constructor(limit, assetBase) {
+    constructor(limit, assetBase, maxDecodedBytes) {
         this.#limit = limit;
         this.#ceiling = limit;
         this.#assetBase = assetBase;
+        this.#maxDecodedBytes = maxDecodedBytes;
     }
     #spawn() {
         const thread = { worker: null, running: null };
@@ -147,7 +149,7 @@ class Pool {
                 };
                 thread.worker = worker;
             }
-            const start = { assetBase: this.#assetBase };
+            const start = { assetBase: this.#assetBase, maxDecodedBytes: this.#maxDecodedBytes };
             thread.worker.postMessage(start);
         }
         catch (error) {
@@ -240,13 +242,15 @@ class Pool {
             text: (index) => call("text", index),
             objects: (index) => call("objects", index),
             annotations: (index) => call("annotations", index),
+            links: (index) => call("links", index),
             outline: () => call("outline"),
-            render: (index, renderOptions) => {
+            render: ((index, renderOptions) => {
                 if (renderOptions?.signal) {
                     return Promise.reject(new TypeError("a pool's render takes no signal: a call that's running can't be stopped. pool.close() ends all of them."));
                 }
-                return call("render", index, { width: renderOptions?.width, maxHeight: renderOptions?.maxHeight });
-            },
+                const { width, maxHeight, region } = renderOptions ?? {};
+                return call("render", index, region === undefined ? { width, maxHeight } : { width, maxHeight, region });
+            }),
             close,
             [Symbol.asyncDispose]: close,
         };
@@ -283,5 +287,9 @@ export function startPool(options) {
     const assetBase = options.assetBase !== undefined && typeof location !== "undefined"
         ? new URL(options.assetBase, location.href).href
         : options.assetBase;
-    return new Pool(threads, assetBase);
+    const maxDecodedBytes = options.maxDecodedBytes;
+    if (maxDecodedBytes !== undefined && !(typeof maxDecodedBytes === "number" && maxDecodedBytes >= 0)) {
+        throw new RangeError("maxDecodedBytes must be a number of bytes, 0 or more");
+    }
+    return new Pool(threads, assetBase, maxDecodedBytes);
 }

package/dist/ranged.d.ts

@@ -43,19 +43,36 @@ export type PdfRangedStats = {
 export type PdfRangedDocument = PdfDocument & {
     stats(): PdfRangedStats;
 };
+/**
+ * Bytes `start..end`. With `yieldTail`, read no further than that many bytes before the file's
+ * end, where a suffix asked for beside it starts, so no byte comes twice.
+ */
 type Range = {
     start: number;
     end: number;
+    yieldTail?: number;
 };
+/** The file's last `suffix` bytes (`bytes=-n`), asked for before its size is known. */
+type Suffix = {
+    suffix: number;
+};
+type Request = Range | Suffix;
+/** `received`: the bytes read off the response, `bytes` and any read past it. */
 type Answer = {
     start: number;
     bytes: Uint8Array;
     length: number;
     etag: string | null;
     status: number;
+    received: number;
 };
-/** Fetches `ranges`; `limit` is how many bytes may still arrive. */
-type Fetch = (ranges: Range[], timeoutMs: number, limit: number) => Answer[];
+/**
+ * Fetches `requests` in parallel; `limit` is how many bytes may still arrive. A range that
+ * fails throws. A suffix that isn't answered as one (a server that ignores or refuses it)
+ * gives null, and isn't counted: the caller asks for the tail by its offset instead.
+ */
+type Fetch = (requests: Request[], timeoutMs: number, limit: number) => (Answer | null)[];
+type FetchAsync = (requests: Request[], timeoutMs: number, limit: number) => Promise<(Answer | null)[]>;
 /** Fetched chunks of one file and the policy for fetching more. */
 declare class RangeLoader {
     #private;
@@ -73,23 +90,31 @@ declare class RangeLoader {
     stats(): PdfRangedStats;
     /** Fetches chunks `firstChunk..endChunk`, keeping only those not held yet. */
     fetchChunks(firstChunk: number, endChunk: number): void;
+    /**
+     * The first round: the head and, in parallel, the tail as a suffix, then the last
+     * cross-reference section if the tail didn't hold it. A file the head covers needs no more;
+     * a server that doesn't answer the suffix gets the tail by offset in a round of its own.
+     */
+    begin(fetchAsync: FetchAsync | null): Promise<void>;
     /**
      * The `startxref` offset in the fetched last chunk, if it names one. Null for a linearized
      * file, whose trailer points at the first-page section near the head.
      */
     startxref(): number | null;
     /**
-     * Copies [offset, offset + out.length) into `out`, fetching what is missing first. On a
-     * failed fetch it records the failure and fails the read; the call that made it then
-     * throws the failure.
+     * Copies [offset, offset + out.length) into `out`, fetching what is missing first, and if it
+     * fetches, `ahead` bytes past it too, as far as the budget allows: the engine's guess at what
+     * it reads next, which then costs no round trip of its own. On a failed fetch it records the
+     * failure and fails the read; the call that made it then throws the failure.
      */
-    read(offset: number, out: Uint8Array): boolean;
+    read(offset: number, out: Uint8Array, ahead?: number): boolean;
 }
 /**
- * Starts a ranged read of `source`: the head, then (for a larger file) the tail and its last
- * cross-reference section. Blocks while it fetches.
+ * Starts a ranged read of `source`: the head and tail, then the last cross-reference section
+ * if the tail didn't hold it. Blocks while it fetches, except in a browser, where these
+ * rounds are `fetch` calls.
  */
-export declare function startRangeLoader(source: string | Uint8Array, options?: PdfRangedOpenOptions): RangeLoader;
+export declare function startRangeLoader(source: string | Uint8Array, options?: PdfRangedOpenOptions): Promise<RangeLoader>;
 /**
  * The caller's source in a form that stays valid across an await: bytes copied, a URL as an
  * absolute http(s) string. Runs before anything asynchronous.