@rightkit/document-core 0.1.1 → 0.2.0

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

@@ -1,59 +0,0 @@
-import { type MutableRefObject } from "react";
-import type { PDFDocumentProxy } from "pdfjs-dist";
-import { type PdfEditorMode } from "./pdfEditor.js";
-type AnyUIManager = any;
-export interface PdfEditorState {
-    /** Current tool. "none" = pure viewer, no AnnotationEditorLayer is interactive. */
-    mode: PdfEditorMode;
-    setMode: (mode: PdfEditorMode) => void;
-    /** Construct the editor manager for an explicit edit request. Returns false when no PDF or
-     *  container is available yet. Construction is synchronous so callers can immediately render
-     *  editor layers against the returned manager. */
-    ensureReady: () => boolean;
-    freeTextSize: number;
-    setFreeTextSize: (size: number) => void;
-    /** True once any annotation-editor edit exists in the document's annotation storage. */
-    dirty: boolean;
-    /** Serialize current edits (editor annotations + form values) to PDF bytes via pdf.js
-     *  `saveDocument()`. Returns null if no document is loaded or serialization fails. */
-    saveBytes: () => Promise<Uint8Array | null>;
-    /** Checkpoint serialized annotation bytes after successful disk commit, retaining newer edits. */
-    checkpointAnnotationSave: () => boolean;
-    /** Stable token for detecting annotation mutations across async save/reload work. */
-    annotationStateToken: () => string;
-    /** Token captured immediately after pdf.js synchronously serializes current annotations. */
-    serializedAnnotationStateToken: () => string | null;
-    /** Add an image stamp editor on the current page from a picked file (drag-drop or file picker).
-     *  No-op if no editor layer is currently registered for the visible page (e.g. before first
-     *  render). Returns false when the add could not be performed. */
-    addImageStamp: (file: File, layerWaitMs?: number) => Promise<boolean>;
-    /** True once the UI manager is constructed for this document. */
-    ready: boolean;
-    uiManagerRef: MutableRefObject<AnyUIManager | null>;
-    /** Forward the viewer's own scale/rotation/page state into the UI manager so newly-placed
-     *  editors and existing ones stay correctly positioned as the user zooms/rotates/scrolls. Cheap
-     *  no-op when no document/editor is loaded. */
-    syncViewState: (state: {
-        scale: number;
-        rotation: number;
-        page: number;
-    }) => void;
-}
-/**
- * Stage 1 PDF editing: owns the pdf.js `AnnotationEditorUIManager` + its `EventBus` for one open
- * document, and exposes a small React-facing surface (mode, dirty, save, add-image) to PdfViewer.
- * Per-page `AnnotationEditorLayer`s are built in PdfViewer's renderPage (they need the same
- * per-page viewport/canvas/text-layer context renderPage already computes) and register themselves
- * with `uiManagerRef.current` via their own constructor (`uiManager.addLayer(this)`).
- *
- * View-first invariant: `mode` defaults to "none" on every new document, so opening a PDF is
- * unchanged — editing is an explicit opt-in via the toolbar.
- */
-export declare function usePdfEditor({ pdfDoc, containerRef, }: {
-    pdfDoc: PDFDocumentProxy | null;
-    /** The scrollable pages container — doubles as both the UI manager's focus-containment root and
-     *  its "viewer" element (only used for `--scale-factor` bookkeeping and `dir`, not for indexing
-     *  page children, so our virtualized/unloaded slots don't confuse it). */
-    containerRef: MutableRefObject<HTMLElement | null>;
-}): PdfEditorState;
-export {};

package/dist/documents/pdf/usePdfEditor.js

@@ -1,317 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-import * as pdfjs from "pdfjs-dist";
-import { logError, logEvent } from "../../state/diagnostics.js";
-import { modeToAnnotationEditorType } from "./pdfEditor.js";
-let viewerModule = null;
-let viewerLoad = null;
-function loadViewerModule() {
-    viewerLoad ??= import("./pdfjsLibGlobal.js")
-        .then(() => import("pdfjs-dist/web/pdf_viewer.mjs"))
-        .then((m) => {
-        viewerModule = m;
-    })
-        .catch(() => {
-        viewerLoad = null;
-        logError("pdf-editor:viewer-load");
-    });
-    return viewerLoad;
-}
-const IMAGE_STAMP_LAYER_WAIT_MS = 2000;
-const IMAGE_STAMP_LAYER_POLL_MS = 16;
-/**
- * Stage 1 PDF editing: owns the pdf.js `AnnotationEditorUIManager` + its `EventBus` for one open
- * document, and exposes a small React-facing surface (mode, dirty, save, add-image) to PdfViewer.
- * Per-page `AnnotationEditorLayer`s are built in PdfViewer's renderPage (they need the same
- * per-page viewport/canvas/text-layer context renderPage already computes) and register themselves
- * with `uiManagerRef.current` via their own constructor (`uiManager.addLayer(this)`).
- *
- * View-first invariant: `mode` defaults to "none" on every new document, so opening a PDF is
- * unchanged — editing is an explicit opt-in via the toolbar.
- */
-export function usePdfEditor({ pdfDoc, containerRef, }) {
-    const [mode, setModeState] = useState("none");
-    const [dirty, setDirty] = useState(false);
-    const [freeTextSize, setFreeTextSizeState] = useState(10);
-    const [ready, setReady] = useState(false);
-    const uiManagerRef = useRef(null);
-    const eventBusRef = useRef(null);
-    const storageRef = useRef(null);
-    const pdfDocRef = useRef(null);
-    pdfDocRef.current = pdfDoc;
-    // True while `saveBytes` is inside pdf.js `saveDocument()` — see `onReset` below.
-    const serializingRef = useRef(false);
-    const annotationEpochRef = useRef(0);
-    const serializedEpochRef = useRef(null);
-    const serializedAnnotationHashRef = useRef(null);
-    const serializedStateTokenRef = useRef(null);
-    const committedAnnotationHashRef = useRef(null);
-    const annotationCheckpointSafeRef = useRef(true);
-    const viewStateRef = useRef(null);
-    const syncViewState = useCallback(({ scale, rotation, page }) => {
-        viewStateRef.current = { scale, rotation, page };
-        const eventBus = eventBusRef.current;
-        if (!eventBus)
-            return;
-        // UIManager multiplies viewer scale by PDF_TO_CSS_UNITS. Our scale already measures CSS
-        // pixels per PDF unit, so normalize it first to keep annotation placement at the pointer.
-        eventBus.dispatch("scalechanging", {
-            source: eventBus,
-            scale: scale / pdfjs.PixelsPerInch.PDF_TO_CSS_UNITS,
-        });
-        eventBus.dispatch("rotationchanging", { source: eventBus, pagesRotation: rotation });
-        eventBus.dispatch("pagechanging", { source: eventBus, pageNumber: page });
-    }, []);
-    const destroyManager = useCallback(() => {
-        const storage = storageRef.current;
-        if (storage) {
-            storage.onSetModified = null;
-            storage.onResetModified = null;
-        }
-        storageRef.current = null;
-        const uiManager = uiManagerRef.current;
-        uiManagerRef.current = null;
-        eventBusRef.current = null;
-        if (uiManager) {
-            // pdf.js owns a window keydown listener for editor history. Detach it before destroying
-            // CommandManager: its destroy() intentionally nulls command storage, so a queued Cmd-Z or
-            // Cmd-Shift-Z must not enter undo/redo after this document's manager has gone away.
-            uiManager.removeEditListeners?.();
-            uiManager.destroy();
-        }
-        setReady(false);
-    }, []);
-    // pdf.js's AnnotationEditorUIManager is a viewer-internal class with no stability contract on
-    // its constructor signature (see docs/ENGINEERING-FINDINGS-2026-08.md §4 — Mozilla declined a
-    // generic embedding API). Guard construction so a pdfjs-dist upgrade that shifts this shape
-    // degrades to "editing controls stay disabled" rather than breaking the pure viewer.
-    const ensureReady = useCallback(() => {
-        if (uiManagerRef.current)
-            return true;
-        const doc = pdfDocRef.current;
-        const container = containerRef.current;
-        if (!doc || !container)
-            return false;
-        // The viewer module loads on the first mount; until it has, editing controls stay disabled.
-        const viewer = viewerModule;
-        if (!viewer) {
-            void loadViewerModule();
-            return false;
-        }
-        let eventBus = null;
-        let uiManager = null;
-        try {
-            eventBus = new viewer.EventBus();
-            const l10n = new viewer.GenericL10n(navigator.language || "en-US");
-            uiManager = new pdfjs.AnnotationEditorUIManager(container, // container: focus/keyboard scoping root
-            container, // viewer: only read for --scale-factor / dir bookkeeping here
-            null, // viewerAlert
-            null, // altTextManager
-            null, // commentManager
-            null, // signatureManager
-            eventBus, doc, null, // pageColors — no forced high-contrast palette
-            undefined, // highlightColors — pdf.js defaults
-            false, // enableHighlightFloatingButton
-            false, // enableUpdatedAddImage
-            false, // enableNewAltTextWhenAddingImage
-            null, // mlManager — no ML alt-text guesses
-            null, // editorUndoBar — toolbar has no undo-bar UI in Stage 1
-            false);
-            uiManager.l10n = l10n;
-        }
-        catch {
-            logError("pdf-editor:init");
-            eventBus = null;
-            uiManager = null;
-        }
-        if (!eventBus || !uiManager)
-            return false;
-        eventBusRef.current = eventBus;
-        uiManagerRef.current = uiManager;
-        // A save reload can replace the manager without ready ever rendering false.
-        // Seed its scale immediately, before any annotation layer can accept input.
-        if (viewStateRef.current)
-            syncViewState(viewStateRef.current);
-        // pdfjs-dist's generated types declare these callback slots as literal `null` (they're meant
-        // to be assigned a function at runtime, same as pdf.js's own viewer does) — cast the boundary.
-        // `annotationStorage` is a lazily-created getter on every real PDFDocumentProxy, but stays
-        // undefined on the minimal PDFDocumentProxy stand-ins other PdfViewer tests construct (they
-        // predate Stage 1 and only implement what the pure viewer touches) — guard rather than crash
-        // the whole component (and, with it, unrelated pure-viewer behavior) from an editor-only hook.
-        const storage = doc.annotationStorage;
-        const onModified = () => {
-            annotationEpochRef.current += 1;
-            annotationCheckpointSafeRef.current = false;
-            setDirty(true);
-        };
-        // pdf.js calls `annotationStorage.resetModified()` inside `saveDocument()` itself, i.e. the
-        // moment bytes are SERIALIZED — long before the app has written anything to disk. Honouring
-        // that reset here flipped the tab to "clean" during every save attempt, and a save that then
-        // failed (prepare/commit rejected) left real unsaved annotations showing as saved. Dirty state
-        // is cleared by the post-commit document reload instead (new `pdfDoc` re-runs this effect), so
-        // resets raised while `saveBytes` is serializing are ignored.
-        const onReset = () => {
-            if (serializingRef.current)
-                return;
-            annotationCheckpointSafeRef.current = true;
-            setDirty(false);
-        };
-        if (storage) {
-            storage.onSetModified = onModified;
-            storage.onResetModified = onReset;
-        }
-        storageRef.current = storage ?? null;
-        setReady(true);
-        return true;
-    }, [containerRef, syncViewState]);
-    // Build/tear down one UIManager per loaded document. The manager stays absent while a PDF is
-    // merely being viewed, then survives mode="none" so pdf.js's unified undo history remains intact.
-    // A document identity change always destroys it and resets mode/dirty state.
-    // biome-ignore lint/correctness/useExhaustiveDependencies: pdfDoc identity defines the manager lifetime.
-    // Start loading the viewer module (EventBus, GenericL10n) as soon as an editor mounts.
-    useEffect(() => {
-        void loadViewerModule();
-    }, []);
-    useEffect(() => {
-        setModeState("none");
-        setDirty(false);
-        annotationEpochRef.current = 0;
-        serializedEpochRef.current = null;
-        serializedAnnotationHashRef.current = null;
-        serializedStateTokenRef.current = null;
-        committedAnnotationHashRef.current = null;
-        annotationCheckpointSafeRef.current = true;
-        setReady(false);
-        return () => {
-            destroyManager();
-        };
-    }, [destroyManager, pdfDoc]);
-    const setMode = useCallback((next) => {
-        const uiManager = next === "none" ? uiManagerRef.current : ensureReady() ? uiManagerRef.current : null;
-        setModeState(next);
-        if (!uiManager)
-            return;
-        // A rejection here previously vanished completely: pdf.js's own viewer also calls
-        // `updateMode()` fire-and-forget, and every registered page's `AnnotationEditorLayer.
-        // updateMode()` — the call that un-hides its div — only runs once THIS promise resolves. A
-        // page whose annotations include a Stamp used to reject this unconditionally (see
-        // `NULL_STRUCT_TREE_LAYER`'s doc comment in PdfViewer.tsx) with zero visible error: the mode
-        // still LOOKED like it switched (this hook's own `mode` state flips regardless), but every
-        // editor layer stayed permanently inert. Logging a rejection here keeps any future regression
-        // in this class diagnosable instead of silently inert again.
-        void uiManager
-            .updateMode(modeToAnnotationEditorType(next))
-            .catch(() => logError("pdf-editor:mode-switch"));
-    }, [ensureReady]);
-    const setFreeTextSize = useCallback((size) => {
-        if (!Number.isFinite(size))
-            return;
-        const normalized = Math.max(6, Math.min(144, Math.round(size)));
-        setFreeTextSizeState(normalized);
-        uiManagerRef.current?.updateParams(pdfjs.AnnotationEditorParamsType.FREETEXT_SIZE, normalized);
-    }, []);
-    const annotationStateToken = useCallback(() => {
-        const hash = pdfDocRef.current?.annotationStorage?.serializable?.hash ?? "";
-        return `${annotationEpochRef.current}:${hash}`;
-    }, []);
-    const saveBytes = useCallback(async () => {
-        const doc = pdfDocRef.current;
-        if (!doc)
-            return null;
-        const serializedEpoch = annotationEpochRef.current;
-        serializedEpochRef.current = serializedEpoch;
-        serializedAnnotationHashRef.current = doc.annotationStorage?.serializable?.hash ?? null;
-        serializedStateTokenRef.current = null;
-        annotationCheckpointSafeRef.current = true;
-        serializingRef.current = true;
-        logEvent("pdf-editor:serialize:start");
-        try {
-            // saveDocument() invokes annotationStorage.serializable synchronously before returning its
-            // worker promise. Capture token immediately after that call: FreeText serialization can
-            // normalize editor state/hash without a real edit, while any later mutation must remain
-            // visible to save-plan stale checks.
-            const savePromise = doc.saveDocument();
-            const serializedStateToken = annotationStateToken();
-            const serializedEpochAfterCall = annotationEpochRef.current;
-            if (serializedEpochAfterCall === serializedEpoch) {
-                // Checkpoint against normalized serialization state. Keep the pre-call hash when an
-                // epoch changed during save so newer edits remain visible to checkpointAnnotationSave.
-                serializedAnnotationHashRef.current =
-                    doc.annotationStorage?.serializable?.hash ?? serializedAnnotationHashRef.current;
-            }
-            const bytes = await savePromise;
-            const settledStateToken = annotationStateToken();
-            if (serializedEpochAfterCall === serializedEpoch &&
-                settledStateToken === serializedStateToken) {
-                serializedStateTokenRef.current = serializedStateToken;
-            }
-            logEvent("pdf-editor:serialize:done");
-            return bytes;
-        }
-        catch {
-            logError("pdf-editor:serialize");
-            return null;
-        }
-        finally {
-            serializingRef.current = false;
-        }
-    }, [annotationStateToken]);
-    const serializedAnnotationStateToken = useCallback(() => serializedStateTokenRef.current, []);
-    const checkpointAnnotationSave = useCallback(() => {
-        const serializedEpoch = serializedEpochRef.current;
-        const serializedHash = serializedAnnotationHashRef.current;
-        const storage = pdfDocRef.current?.annotationStorage;
-        if (!storage || !annotationCheckpointSafeRef.current)
-            return false;
-        const currentHash = storage.serializable.hash;
-        if (serializedEpoch === null || serializedHash === null) {
-            return (committedAnnotationHashRef.current === null ||
-                currentHash === committedAnnotationHashRef.current);
-        }
-        if (serializedEpoch !== annotationEpochRef.current || currentHash !== serializedHash) {
-            return false;
-        }
-        storage.resetModified();
-        setDirty(false);
-        committedAnnotationHashRef.current = serializedHash;
-        serializedEpochRef.current = null;
-        serializedAnnotationHashRef.current = null;
-        annotationCheckpointSafeRef.current = true;
-        return true;
-    }, []);
-    const addImageStamp = useCallback(async (file, layerWaitMs = IMAGE_STAMP_LAYER_WAIT_MS) => {
-        if (!ensureReady())
-            return false;
-        const uiManager = uiManagerRef.current;
-        if (!uiManager)
-            return false;
-        const deadline = Date.now() + Math.min(15000, Math.max(0, layerWaitMs));
-        while (!uiManager.currentLayer && Date.now() < deadline) {
-            await new Promise((resolve) => setTimeout(resolve, IMAGE_STAMP_LAYER_POLL_MS));
-            if (uiManagerRef.current !== uiManager)
-                return false;
-        }
-        const layer = uiManager.currentLayer ?? null;
-        if (!layer)
-            return false;
-        await uiManager.updateMode(modeToAnnotationEditorType("stamp"));
-        await layer.pasteEditor({ mode: modeToAnnotationEditorType("stamp") }, { bitmapFile: file });
-        setModeState("stamp");
-        return true;
-    }, [ensureReady]);
-    return {
-        mode,
-        setMode,
-        ensureReady,
-        freeTextSize,
-        setFreeTextSize,
-        dirty,
-        saveBytes,
-        checkpointAnnotationSave,
-        annotationStateToken,
-        serializedAnnotationStateToken,
-        addImageStamp,
-        ready,
-        uiManagerRef,
-        syncViewState,
-    };
-}

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

@@ -1,19 +0,0 @@
-import { type Dispatch, type MutableRefObject, type SetStateAction } from "react";
-import { type Size } from "./pdfShared.js";
-interface PdfFitDeps {
-    scrollRef: MutableRefObject<HTMLDivElement | null>;
-    /** Base page-1 viewport at scale 1 (null until the document loads). */
-    base: Size | null;
-    /** 0 | 90 | 180 | 270, applied to every page. */
-    rotation: number;
-    fitMode: "width" | "page" | null;
-    setScale: Dispatch<SetStateAction<number>>;
-}
-/**
- * Fit-to-width/page scale math: derive `scale` from the container's client box (rotation-aware),
- * apply it when the base page size or fit mode changes, and re-apply on container resize —
- * rAF-coalesced because ResizeObserver can fire many times per frame during a window drag.
- * Extracted from PdfViewer verbatim — no behavior change.
- */
-export declare function usePdfFit({ scrollRef, base, rotation, fitMode, setScale }: PdfFitDeps): void;
-export {};

package/dist/documents/pdf/usePdfFit.js

@@ -1,55 +0,0 @@
-import { useCallback, useEffect, } from "react";
-import { clampScale } from "./pdfShared.js";
-/**
- * Fit-to-width/page scale math: derive `scale` from the container's client box (rotation-aware),
- * apply it when the base page size or fit mode changes, and re-apply on container resize —
- * rAF-coalesced because ResizeObserver can fire many times per frame during a window drag.
- * Extracted from PdfViewer verbatim — no behavior change.
- */
-export function usePdfFit({ scrollRef, base, rotation, fitMode, setScale }) {
-    // --- Fit-to-width: compute scale from the container width ----------------------
-    // biome-ignore lint/correctness/useExhaustiveDependencies: refs/setters arrive as stable hook params
-    const applyFit = useCallback((mode) => {
-        const el = scrollRef.current;
-        if (!el || !base)
-            return;
-        // On 90°/270° rotation the page's effective footprint has width/height swapped.
-        const swap = rotation % 180 !== 0;
-        const bw = swap ? base.h : base.w;
-        const bh = swap ? base.w : base.h;
-        const availW = el.clientWidth - 48; // page horizontal margin
-        const availH = el.clientHeight - 48;
-        const next = mode === "width" ? availW / bw : Math.min(availW / bw, availH / bh);
-        setScale(clampScale(next));
-    }, [base, rotation]);
-    useEffect(() => {
-        if (base && fitMode)
-            applyFit(fitMode);
-    }, [base, fitMode, applyFit]);
-    // Recompute fit on container resize. rAF-coalesced: ResizeObserver can fire many times per frame
-    // during an interactive window drag, and each call previously re-rasterized every visible page —
-    // collapse to at most one applyFit per animation frame.
-    // biome-ignore lint/correctness/useExhaustiveDependencies: refs arrive as stable hook params
-    useEffect(() => {
-        if (!fitMode)
-            return;
-        const el = scrollRef.current;
-        if (!el)
-            return;
-        let raf = null;
-        const ro = new ResizeObserver(() => {
-            if (raf != null)
-                return;
-            raf = requestAnimationFrame(() => {
-                raf = null;
-                applyFit(fitMode);
-            });
-        });
-        ro.observe(el);
-        return () => {
-            ro.disconnect();
-            if (raf != null)
-                cancelAnimationFrame(raf);
-        };
-    }, [fitMode, applyFit]);
-}

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

@@ -1,38 +0,0 @@
-import type { PDFDocumentProxy } from "pdfjs-dist";
-import { type OcrLine } from "./pdfOcr.js";
-export type PdfOcrStatus = "idle" | "running" | "done" | "error";
-export interface PdfOcrPageState {
-    status: PdfOcrStatus;
-    error?: string;
-}
-export interface PdfOcrDocumentState {
-    status: PdfOcrStatus;
-    completed: number;
-    total: number;
-    scanned: number;
-    skipped: number;
-    failed: number;
-    currentPage?: number;
-}
-export declare function usePdfOcr({ documentId, pdfDoc, pdfRef, current, rotation, setPageText, invalidatePageText, rehighlight, }: {
-    documentId: string;
-    pdfDoc: PDFDocumentProxy | null;
-    pdfRef: React.MutableRefObject<PDFDocumentProxy | null>;
-    current: number;
-    rotation: number;
-    setPageText: (page: number, text: string) => void;
-    invalidatePageText: (page: number) => void;
-    rehighlight: () => void;
-}): {
-    ocrAvailable: boolean;
-    availabilityResolved: boolean;
-    currentPageScanned: boolean;
-    currentPageState: PdfOcrPageState;
-    currentError: string | undefined;
-    currentErrorIsBackendUnavailable: boolean;
-    linesByPage: Map<number, OcrLine[]>;
-    pageStates: Map<number, PdfOcrPageState>;
-    recognizeCurrentPage: (inspectEligibility?: boolean) => Promise<void>;
-    documentOcrState: PdfOcrDocumentState;
-    recognizeDocument: () => Promise<void>;
-};