@rightkit/document-core 0.1.1 → 0.2.0

package/dist/documents/pdf/pdfBenchAutopilot.js

@@ -1,154 +0,0 @@
-/**
- * VR-P0-1 benchmark autopilot (dev-only, temporary instrumentation).
- *
- * The PDF loading benchmark has to run in the real WKWebView/WebView2 webview, whose DevTools
- * console is GUI-only — so driving it by hand does not scale to "3 repeats x 3 modes x N fixtures,
- * on two operating systems". This module runs the whole matrix unattended:
- *
- *   1. a plan (modes x repeats) is stored in localStorage;
- *   2. each app load runs whichever mode the plan currently points at;
- *   3. on completion the full result is appended to native PDF benchmark JSONL;
- *      a content-free diagnostics breadcrumb remains for quick status checks;
- *   4. the plan advances and the app reloads, until the matrix is done.
- *
- * Repeats are INTERLEAVED (round-robin across modes) rather than grouped, so a thermal or
- * page-cache drift over the run cannot systematically favour whichever mode ran first.
- *
- * Delete this file together with the rest of the benchmark harness once the study is decided.
- */
-import { logEvent } from "../../state/diagnostics.js";
-const PLAN_KEY = "vr.pdf.bench.autopilot.v1";
-const ENABLED_KEY = "vr.pdf.bench.enabled";
-const MODE_KEY = "vr.pdf.bench.mode";
-const DEFAULT_MODES = ["buffer", "url-native", "custom-range"];
-const DEFAULT_REPEATS = 3;
-function dev() {
-    // Vitest runs with MODE=test; retaining this explicit test-only gate keeps benchmark controls
-    // unavailable in production builds while allowing orchestration behavior to stay covered.
-    return (typeof window !== "undefined" &&
-        (import.meta.env?.DEV ||
-            import.meta.env?.MODE === "test" ||
-            (typeof process !== "undefined" && process.env.NODE_ENV === "test")));
-}
-function loadPlan() {
-    if (!dev())
-        return null;
-    try {
-        const raw = localStorage.getItem(PLAN_KEY);
-        if (!raw)
-            return null;
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed.modes) || parsed.modes.length === 0)
-            return null;
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-function savePlan(plan) {
-    try {
-        localStorage.setItem(PLAN_KEY, JSON.stringify(plan));
-    }
-    catch {
-        // Dev-only; never an application correctness dependency.
-    }
-}
-function totalRuns(plan) {
-    return plan.modes.length * plan.repeats;
-}
-function modeForIndex(plan, index) {
-    return plan.modes[index % plan.modes.length];
-}
-/** Point the benchmark at the mode this run should use, and make sure it is armed. */
-function armMode(mode) {
-    try {
-        localStorage.setItem(ENABLED_KEY, "1");
-        localStorage.setItem(MODE_KEY, mode);
-    }
-    catch {
-        // Dev-only.
-    }
-}
-/** The mode the plan wants for the current load, or null when no plan is active. */
-export function autopilotCurrentMode() {
-    const plan = loadPlan();
-    if (!plan || plan.done)
-        return null;
-    return modeForIndex(plan, plan.index);
-}
-/**
- * Called from benchmark `finalize()`. Records a content-free diagnostics breadcrumb, advances plan,
- * & either reloads for next mode or reports matrix complete. Full result is native JSONL.
- */
-export function autopilotOnComplete() {
-    const plan = loadPlan();
-    if (!plan || plan.done)
-        return;
-    const of = totalRuns(plan);
-    logEvent("pdf-bench-autopilot-result");
-    plan.index += 1;
-    if (plan.index >= of) {
-        plan.done = true;
-        savePlan(plan);
-        logEvent("pdf-bench-autopilot-done");
-        return;
-    }
-    savePlan(plan);
-    armMode(modeForIndex(plan, plan.index));
-    // finalize() has already awaited both settle sampling & durable native write. Reload now: WKWebView
-    // can indefinitely throttle a timer once its benchmark window becomes occluded, stranding a
-    // multi-mode plan after its first valid sample.
-    if (import.meta.env?.MODE !== "test")
-        location.reload();
-}
-/** Begin a matrix. Arms the first mode and reloads so the run starts from a clean document load. */
-export function startAutopilot(label = "unlabelled", modes = DEFAULT_MODES, repeats = DEFAULT_REPEATS, reload = true, runId = String(import.meta.env?.VITE_PDF_BENCH_RUN_ID ?? label)) {
-    if (!dev())
-        return;
-    const plan = { runId, modes, repeats, index: 0, label, done: false };
-    savePlan(plan);
-    armMode(modeForIndex(plan, 0));
-    logEvent("pdf-bench-autopilot-start");
-    if (reload)
-        location.reload();
-}
-export function stopAutopilot() {
-    try {
-        localStorage.removeItem(PLAN_KEY);
-        localStorage.removeItem(ENABLED_KEY);
-    }
-    catch {
-        // Dev-only.
-    }
-}
-export function autopilotStatus() {
-    return loadPlan();
-}
-/**
- * Auto-start from the environment so the matrix needs no console at all:
- *   VITE_PDF_BENCH_AUTOPILOT=1 pnpm dev:tauri <file.pdf>
- *
- * Only fires when no plan exists yet, so the per-run reloads do not restart the matrix.
- */
-export function maybeAutoStartFromEnv() {
-    if (!dev())
-        return;
-    if (import.meta.env?.VITE_PDF_BENCH_AUTOPILOT !== "1")
-        return;
-    const label = String(import.meta.env?.VITE_PDF_BENCH_LABEL ?? "auto");
-    const runId = String(import.meta.env?.VITE_PDF_BENCH_RUN_ID ?? label);
-    const modes = String(import.meta.env?.VITE_PDF_BENCH_MODES ?? "")
-        .split(",")
-        .map((mode) => mode.trim())
-        .filter((mode) => DEFAULT_MODES.includes(mode));
-    const existing = loadPlan();
-    // A plan for THIS label that is still mid-matrix must never be restarted — that's the
-    // per-run reload case. But localStorage survives across app launches (same webview profile),
-    // so a plan left over from an earlier session/label (done, or for a different fixture) must
-    // NOT silently block every future auto-start; start fresh for a new/changed label.
-    if (existing && !existing.done && existing.runId === runId)
-        return;
-    const repeats = Number(import.meta.env?.VITE_PDF_BENCH_REPEATS ?? DEFAULT_REPEATS);
-    startAutopilot(label, modes.length > 0 ? modes : DEFAULT_MODES, Number.isFinite(repeats) && repeats > 0 ? repeats : DEFAULT_REPEATS, false, runId);
-}

package/dist/documents/pdf/pdfBenchTransport.d.ts

@@ -1,21 +0,0 @@
-import * as pdfjs from "pdfjs-dist";
-import type { PDFDocumentProxy } from "pdfjs-dist";
-import { type PdfBenchLoadMode } from "./pdfBench.js";
-/** Above this size the whole-file buffer fallback is skipped in favour of range loading. */
-export declare const MAX_BUFFERED_PDF_BYTES: number;
-export declare function shouldRangeLoadInsteadOfBuffer(contentLength: string | null): boolean;
-export interface PreparedPdfLoading {
-    readonly task: ReturnType<typeof pdfjs.getDocument>;
-    readonly promise: Promise<PDFDocumentProxy>;
-    dispose(): void;
-}
-interface PreparePdfLoadingArgs {
-    readonly url: string;
-    readonly mode: PdfBenchLoadMode;
-    readonly signal: AbortSignal;
-    readonly wasmUrl: string;
-}
-export declare function formatPdfRangeHeader(begin: number, end: number): string;
-export declare function parseContentRangeTotal(value: string | null): number | null;
-export declare function preparePdfLoading({ url, mode, signal, wasmUrl, }: PreparePdfLoadingArgs): Promise<PreparedPdfLoading>;
-export {};

package/dist/documents/pdf/pdfBenchTransport.js

@@ -1,233 +0,0 @@
-import * as pdfjs from "pdfjs-dist";
-import { pdfDocumentInit } from "@rightkit/pdf-ui";
-import { isPdfBenchEnabled } from "./pdfBench.js";
-const RANGE_CHUNK_SIZE = 64 * 1024;
-/** Above this size the whole-file buffer fallback is skipped in favour of range loading. */
-export const MAX_BUFFERED_PDF_BYTES = 150 * 1024 * 1024;
-export function shouldRangeLoadInsteadOfBuffer(contentLength) {
-    const n = Number(contentLength);
-    return Number.isFinite(n) && n > MAX_BUFFERED_PDF_BYTES;
-}
-export function formatPdfRangeHeader(begin, end) {
-    if (!Number.isInteger(begin) || !Number.isInteger(end) || begin < 0 || end <= begin) {
-        throw new Error(`Invalid PDF byte range [${begin}, ${end})`);
-    }
-    return `bytes=${begin}-${end - 1}`;
-}
-export function parseContentRangeTotal(value) {
-    return parseContentRange(value)?.total ?? null;
-}
-function parseContentRange(value) {
-    if (!value)
-        return null;
-    const match = value.match(/^bytes\s+(\d+)-(\d+)\/(\d+)$/i);
-    if (!match)
-        return null;
-    const begin = Number(match[1]);
-    const end = Number(match[2]);
-    const total = Number(match[3]);
-    if (!Number.isSafeInteger(begin) ||
-        !Number.isSafeInteger(end) ||
-        !Number.isSafeInteger(total) ||
-        begin < 0 ||
-        end < begin ||
-        total <= end) {
-        return null;
-    }
-    return { begin, end, total };
-}
-function parseContentLength(value) {
-    if (!value)
-        return null;
-    const length = Number(value);
-    return Number.isSafeInteger(length) && length > 0 ? length : null;
-}
-async function probePdfLength(url, signal) {
-    // HEAD is cheapest when the webview/custom protocol handles it correctly.
-    try {
-        const head = await fetch(url, { method: "HEAD", signal, cache: "no-store" });
-        const length = head.ok ? parseContentLength(head.headers.get("content-length")) : null;
-        if (length !== null)
-            return { length, initialData: null };
-    }
-    catch (error) {
-        if (error?.name === "AbortError")
-            throw error;
-        // Fall through to a 1-byte range probe. Benchmarking exists specifically because custom-scheme
-        // behavior differs across webviews; HEAD support must not be assumed.
-    }
-    const probe = await fetch(url, {
-        signal,
-        cache: "no-store",
-        headers: { Range: "bytes=0-0" },
-    });
-    if (probe.status !== 206) {
-        throw new Error(`PDF range probe failed: expected 206, got ${probe.status}`);
-    }
-    const length = parseContentRangeTotal(probe.headers.get("content-range"));
-    if (length === null)
-        throw new Error("PDF range probe did not expose a valid total length");
-    const initialData = new Uint8Array(await probe.arrayBuffer());
-    const range = parseContentRange(probe.headers.get("content-range"));
-    if (!range || range.begin !== 0 || range.end !== initialData.byteLength - 1) {
-        throw new Error("PDF range probe returned bytes that do not match Content-Range");
-    }
-    return { length, initialData };
-}
-class HostPdfRangeTransport extends pdfjs.PDFDataRangeTransport {
-    #url;
-    #length;
-    #controllers = new Set();
-    #aborted = false;
-    #failure = null;
-    #onFailure = null;
-    constructor(url, length, initialData) {
-        // progressiveDone=true: this transport intentionally supplies explicit ranges only.
-        super(length, initialData, true);
-        this.#url = url;
-        this.#length = length;
-    }
-    get failure() {
-        return this.#failure;
-    }
-    setFailureHandler(handler) {
-        this.#onFailure = handler;
-    }
-    requestDataRange(begin, end) {
-        if (this.#aborted)
-            return;
-        const controller = new AbortController();
-        this.#controllers.add(controller);
-        void fetch(this.#url, {
-            signal: controller.signal,
-            cache: "no-store",
-            headers: { Range: formatPdfRangeHeader(begin, end) },
-        })
-            .then(async (response) => {
-            if (response.status !== 206) {
-                throw new Error(`PDF custom range failed for [${begin}, ${end}): expected 206, got ${response.status}`);
-            }
-            const bytes = new Uint8Array(await response.arrayBuffer());
-            const expected = end - begin;
-            const range = parseContentRange(response.headers.get("content-range"));
-            if (!range ||
-                range.begin !== begin ||
-                range.end !== end - 1 ||
-                range.total !== this.#length) {
-                throw new Error(`PDF custom range returned invalid Content-Range for [${begin}, ${end})`);
-            }
-            if (bytes.byteLength !== expected) {
-                throw new Error(`PDF custom range returned ${bytes.byteLength} bytes for [${begin}, ${end}); expected ${expected}`);
-            }
-            if (!this.#aborted)
-                this.onDataRange(begin, bytes);
-        })
-            .catch((error) => {
-            if (this.#aborted || error?.name === "AbortError")
-                return;
-            const failure = error instanceof Error
-                ? error
-                : new Error(String(error?.message ?? error));
-            this.#failure = failure;
-            this.#onFailure?.(failure);
-        })
-            .finally(() => {
-            this.#controllers.delete(controller);
-        });
-    }
-    abort() {
-        if (this.#aborted)
-            return;
-        this.#aborted = true;
-        for (const controller of this.#controllers)
-            controller.abort();
-        this.#controllers.clear();
-    }
-}
-function commonOptions(wasmUrl) {
-    return {
-        wasmUrl,
-        useWorkerFetch: false,
-        // Only the deterministic benchmark pins OffscreenCanvas off. This transport also serves every
-        // ordinary PDF load, and pdf.js's save path REQUIRES OffscreenCanvas to encode Stamp (image)
-        // annotations: with it forced off, `saveDocument()` hands the stamp writer a null image and
-        // throws ("Cannot destructure property 'imageRef'"), so every image-stamp save failed with
-        // "annotations could not be serialized". Let pdf.js detect support in the real app.
-        isOffscreenCanvasSupported: isPdfBenchEnabled()
-            ? false
-            : typeof OffscreenCanvas !== "undefined",
-        isImageDecoderSupported: false,
-    };
-}
-export async function preparePdfLoading({ url, mode, signal, wasmUrl, }) {
-    let bufferResponse = null;
-    if (mode === "buffer") {
-        const response = await fetch(url, { signal });
-        if (!response.ok) {
-            throw new Error(`PDF fetch failed: ${response.status} ${response.statusText}`.trim());
-        }
-        if (shouldRangeLoadInsteadOfBuffer(response.headers.get("content-length"))) {
-            void response.body?.cancel().catch(() => { });
-        }
-        else {
-            bufferResponse = response;
-        }
-    }
-    if (bufferResponse) {
-        const response = bufferResponse;
-        const data = new Uint8Array(await response.arrayBuffer());
-        const task = pdfjs.getDocument(pdfDocumentInit(data, commonOptions(wasmUrl)));
-        let disposed = false;
-        const dispose = () => {
-            if (disposed)
-                return;
-            disposed = true;
-            void task.destroy();
-        };
-        signal.addEventListener("abort", dispose, { once: true });
-        return { task, promise: task.promise, dispose };
-    }
-    if (mode === "url-native") {
-        // Deliberately use PDF.js's own Fetch/XHR network stream with default stream/range behavior.
-        const task = pdfjs.getDocument(pdfDocumentInit(url, { rangeChunkSize: RANGE_CHUNK_SIZE, ...commonOptions(wasmUrl) }));
-        let disposed = false;
-        const dispose = () => {
-            if (disposed)
-                return;
-            disposed = true;
-            void task.destroy();
-        };
-        signal.addEventListener("abort", dispose, { once: true });
-        return { task, promise: task.promise, dispose };
-    }
-    const probe = await probePdfLength(url, signal);
-    const transport = new HostPdfRangeTransport(url, probe.length, probe.initialData);
-    const task = pdfjs.getDocument({
-        range: transport,
-        rangeChunkSize: RANGE_CHUNK_SIZE,
-        disableRange: false,
-        disableStream: true,
-        ...commonOptions(wasmUrl),
-    });
-    transport.setFailureHandler((error) => {
-        console.error("[pdf-bench] custom range transport failed", error);
-        void task.destroy();
-    });
-    const promise = task.promise.catch((error) => {
-        throw transport.failure ?? error;
-    });
-    let disposed = false;
-    const dispose = () => {
-        if (disposed)
-            return;
-        disposed = true;
-        transport.abort();
-        void task.destroy();
-    };
-    signal.addEventListener("abort", dispose, { once: true });
-    return {
-        task,
-        promise,
-        dispose,
-    };
-}