vue-pdfjs-headless 4.3.3 → 4.5.0

package/README.md

@@ -5,25 +5,64 @@
 [![NPM downloads][badge-npm-downloads]][url-npm]
 [![NPM Unpacked Size (with version)][badge-npm-unpacked-size]][url-npm]
 
-Headless Vue composables over pdfjs-dist: a document's loading, a page's drawing and the viewer's state, with no styling and no renderer of its own.
+This package provides headless Vue composables over pdfjs-dist. The composables load a document, draw its pages and track the viewer's state, with no styling and no renderer of their own.
+
+Design notes live in [the specs](https://github.com/Esposter/Esposter/tree/main/openspec/specs/vue-pdfjs-headless).
 
 ## Table of Contents
 
 - 🚀 [Getting Started](#getting-started)
-- 📖 [Documentation](#documentation)
+- 🧩 [Key Exports](#key-exports)
 - ⚖️ [License](#license)
 
 ---
 
 ## <a name="getting-started">🚀 Getting Started</a>
 
+1. Install the package.
+
 ```bash
 pnpm i vue-pdfjs-headless
 ```
 
-## <a name="documentation">📖 Documentation</a>
+2. Add this code to the `<script setup>` of a component.
+
+```ts
+import * as pdfjs from "pdfjs-dist";
+import { shallowRef } from "vue";
+import { usePdfDocument, usePdfPage } from "vue-pdfjs-headless";
+
+const canvas = shallowRef<HTMLCanvasElement>();
+const { pdfDocument } = usePdfDocument({
+  renderer: {
+    api: pdfjs,
+    cMapUrl: "/cmaps/",
+    standardFontDataUrl: "/fonts/",
+    wasmUrl: "/wasm/",
+    workerSrc: "/pdf.worker.mjs",
+  },
+  source: "/document.pdf",
+});
+usePdfPage({ canvas, pageNumber: 1, pdfDocument });
+```
+
+3. Bind `canvas` to a `<canvas ref="canvas" />` in the template. The first page appears in the canvas.
+
+## <a name="key-exports">🧩 Key Exports</a>
 
-We highly recommend you take a look at the [documentation](https://github.com/Esposter/Esposter/tree/main/openspec/specs) to level up.
+| Export              | Kind       | Purpose                                                                                                        |
+| ------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
+| `PdfRenderer`       | interface  | The renderer: its API module, its data folder URLs and its worker. The consumer supplies it.                   |
+| `PdfSource`         | type       | A document, given by its URL, its bytes or a file that the reader picked                                       |
+| `PdfViewerState`    | interface  | The viewer's pages, zoom, rotation, search, download and print, as state and actions                           |
+| `readXfdf`          | function   | Reads the free-text annotations of an XFDF file, or returns an error that names what is wrong with it          |
+| `usePdfAnnotations` | composable | Lists the reader's comments once they are wanted, and imports and exports free texts as XFDF                   |
+| `usePdfDocument`    | composable | Loads a document from a source through the consumer's renderer. Its password prompt and its failure are state. |
+| `usePdfPage`        | composable | Draws one page of a loaded document into a canvas, at the canvas's width and the device's pixel ratio          |
+| `usePdfThumbnails`  | composable | One thumbnail per page. A thumbnail's page is loaded and drawn only while its row is in view of the sidebar.   |
+| `usePdfViewer`      | composable | Builds the renderer's viewer for a loaded document. Its pages, zoom and search are state.                      |
+| `usePdfZoomGesture` | composable | Zooms the viewer about the pointer on a pinch or a Ctrl-wheel. The content under the pointer stays in place.   |
+| `writeXfdf`         | function   | Writes free-text annotations as XFDF                                                                           |
 
 ## <a name="license">⚖️ License</a>
 

package/dist/index.d.ts

@@ -1,8 +1,79 @@
+import { Result } from "neverthrow";
 import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
 import * as PdfJs from "pdfjs-dist";
-import { PDFDocumentLoadingTask, PDFDocumentProxy, PageViewport } from "pdfjs-dist";
+import { PDFDocumentLoadingTask, PDFDocumentProxy, PDFPageProxy, PageViewport } from "pdfjs-dist";
 import * as PdfJsViewer from "pdfjs-dist/web/pdf_viewer.mjs";
 import { PDFViewer } from "pdfjs-dist/web/pdf_viewer.mjs";
+export declare enum PdfEditorMode {
+  None = 0,
+  FreeText = 3,
+  Highlight = 9,
+  Stamp = 13,
+  Ink = 15
+}
+export interface PdfAnnotationChange {
+  kind: PdfEditorMode;
+  pageNumber: number;
+}
+export interface PdfComment {
+  contents: string;
+  pageNumber: number;
+}
+export interface PdfAnnotationsState {
+  comments: ShallowRef<PdfComment[] | undefined>;
+  exportXfdf: () => string;
+  importXfdf: (xfdf: string) => Result<void, string>;
+  setEditorMode: (mode: PdfEditorMode) => void;
+}
+export interface PdfMatchesCount {
+  current: number;
+  total: number;
+}
+export type PdfOutline = NonNullable<Awaited<ReturnType<PDFDocumentProxy["getOutline"]>>>;
+export interface PdfPageOverlay {
+  element: HTMLElement;
+  pageNumber: number;
+  viewport: PageViewport;
+}
+export interface PdfViewerState {
+  actualSize: () => void;
+  currentPageNumber: Ref<number>;
+  download: (filename: string, watermark?: string) => void;
+  drawStoredEditors: () => void;
+  editorMode: Ref<PdfEditorMode>;
+  findNext: () => void;
+  findPrevious: () => void;
+  fitPage: () => void;
+  fitWidth: () => void;
+  followBookmark: (item: PdfOutline[number]) => void;
+  goToPage: (pageNumber: number) => void;
+  isMatchCase: Ref<boolean>;
+  isNotFound: Ref<boolean>;
+  isWholeWord: Ref<boolean>;
+  isZoomInDisabled: ComputedRef<boolean>;
+  isZoomOutDisabled: ComputedRef<boolean>;
+  matchesCount: Ref<PdfMatchesCount>;
+  nextPage: () => void;
+  outline: ShallowRef<PdfOutline | undefined>;
+  overlays: ShallowRef<PdfPageOverlay[]>;
+  pagesCount: Ref<number>;
+  pagesRotation: Ref<number>;
+  previousPage: () => void;
+  print: () => void;
+  resetZoom: () => void;
+  rotate: (degrees: number) => void;
+  scale: Ref<number>;
+  searchQuery: Ref<string>;
+  zoomIn: () => void;
+  zoomOut: () => void;
+}
+interface UsePdfAnnotationsOptions {
+  isCommentsWanted?: MaybeRefOrGetter<boolean>;
+  onChange?: (change: PdfAnnotationChange) => void;
+  pdfDocument: MaybeRefOrGetter<PDFDocumentProxy | undefined>;
+  viewer: PdfViewerState;
+}
+export declare const usePdfAnnotations: ({ isCommentsWanted, onChange, pdfDocument, viewer }: UsePdfAnnotationsOptions) => PdfAnnotationsState;
 export type PdfApi = Pick<typeof PdfJs, "getDocument" | "GlobalWorkerOptions" | "PasswordResponses">;
 export type PdfDocumentParameters = Partial<Parameters<PdfApi["getDocument"]>[0]>;
 export interface PdfLoadingProgress {
@@ -33,11 +104,13 @@ interface UsePdfDocumentOptions {
 export declare const usePdfDocument: ({ parameters, renderer, source }: UsePdfDocumentOptions) => PdfDocumentState;
 interface UsePdfPageOptions {
   canvas: MaybeRefOrGetter<HTMLCanvasElement | undefined>;
+  isActive?: MaybeRefOrGetter<boolean>;
   isVisible?: MaybeRefOrGetter<boolean>;
   pageNumber: MaybeRefOrGetter<number>;
+  pagesRotation?: MaybeRefOrGetter<number>;
   pdfDocument: MaybeRefOrGetter<PDFDocumentProxy | undefined>;
 }
-export declare const usePdfPage: ({ canvas, isVisible, pageNumber, pdfDocument }: UsePdfPageOptions) => void;
+export declare const usePdfPage: ({ canvas, isActive, isVisible, pageNumber, pagesRotation, pdfDocument }: UsePdfPageOptions) => void;
 export interface PdfThumbnail {
   canvas: ShallowRef<HTMLCanvasElement | undefined>;
   isCurrent: ComputedRef<boolean>;
@@ -46,75 +119,70 @@ export interface PdfThumbnail {
 }
 interface UsePdfThumbnailsOptions {
   currentPageNumber: MaybeRefOrGetter<number>;
+  pagesRotation: MaybeRefOrGetter<number>;
   pdfDocument: MaybeRefOrGetter<PDFDocumentProxy | undefined>;
   root: MaybeRefOrGetter<HTMLElement | undefined>;
 }
-export declare const usePdfThumbnails: ({ currentPageNumber, pdfDocument, root }: UsePdfThumbnailsOptions) => ShallowRef<PdfThumbnail[]>;
+export declare const usePdfThumbnails: ({ currentPageNumber, pagesRotation, pdfDocument, root }: UsePdfThumbnailsOptions) => ShallowRef<PdfThumbnail[]>;
 export type PdfViewerApi = Pick<typeof PdfJsViewer, "EventBus" | "FindState" | "LinkTarget" | "PDFFindController" | "PDFLinkService" | "PDFViewer">;
-export interface PdfMatchesCount {
-  current: number;
-  total: number;
-}
-export type PdfOutline = NonNullable<Awaited<ReturnType<PDFDocumentProxy["getOutline"]>>>;
-export interface PdfPageOverlay {
-  element: HTMLElement;
-  pageNumber: number;
-  viewport: PageViewport;
-}
-export interface PdfViewerState {
-  actualSize: () => void;
-  currentPageNumber: Ref<number>;
-  download: (filename: string) => void;
-  findNext: () => void;
-  findPrevious: () => void;
-  fitPage: () => void;
-  fitWidth: () => void;
-  followBookmark: (item: PdfOutline[number]) => void;
-  goToPage: (pageNumber: number) => void;
-  isFullscreen: Ref<boolean>;
-  isMatchCase: Ref<boolean>;
-  isNotFound: Ref<boolean>;
-  isWholeWord: Ref<boolean>;
-  isZoomInDisabled: ComputedRef<boolean>;
-  matchesCount: Ref<PdfMatchesCount>;
-  nextPage: () => void;
-  outline: ShallowRef<PdfOutline>;
-  overlays: ShallowRef<PdfPageOverlay[]>;
-  pagesCount: Ref<number>;
-  pagesRotation: Ref<number>;
-  previousPage: () => void;
-  print: () => void;
-  rotate: () => void;
-  scale: Ref<number>;
-  searchQuery: Ref<string>;
-  toggleFullscreen: () => void;
-  zoomIn: () => void;
-  zoomOut: () => void;
-}
 interface UsePdfViewerOptions {
   container: MaybeRefOrGetter<HTMLDivElement | undefined>;
   highlightTerms?: MaybeRefOrGetter<string[]>;
+  imageResourcesPath: string;
   pdfDocument: MaybeRefOrGetter<PDFDocumentProxy | undefined>;
   viewer: MaybeRefOrGetter<HTMLDivElement | undefined>;
   viewerApi: MaybeRefOrGetter<PdfViewerApi | undefined>;
 }
-export declare const usePdfViewer: ({ container, highlightTerms, pdfDocument, viewer, viewerApi }: UsePdfViewerOptions) => PdfViewerState;
+export declare const usePdfViewer: ({ container, highlightTerms, imageResourcesPath, pdfDocument, viewer, viewerApi }: UsePdfViewerOptions) => PdfViewerState;
 interface UsePdfZoomGestureOptions {
   container: MaybeRefOrGetter<HTMLDivElement | undefined>;
   getViewer: () => PDFViewer | undefined;
 }
 export declare const usePdfZoomGesture: ({ container, getViewer }: UsePdfZoomGestureOptions) => void;
+export interface PdfFreeText {
+  contents: string;
+  id: string;
+  pageNumber: number;
+  rect: [number, number, number, number];
+}
+export interface PdfFreeTextEntry {
+  annotationType: PdfEditorMode.FreeText;
+  color: number[];
+  deleted: false;
+  fontSize: number;
+  id: string;
+  pageIndex: number;
+  rect: [number, number, number, number];
+  rotation: 0;
+  value: string;
+}
 export declare const PDF_MAX_CANVAS_AREA = 16777216;
 export declare const PDF_MIN_SCALE = .1;
 export declare const PDF_MAX_SCALE = 10;
+export declare const PDF_ZOOM_STEP = 1.1;
+export declare const PDF_OPENING_SCALE = "auto";
 export declare const PDF_ROTATION_STEP = 90;
 export declare const PDF_FULL_TURN = 360;
 export declare const PDF_PRINT_SCALE = 2;
 export declare const PDF_PRINT_BATCH_SIZE = 10;
 export declare const PDF_PRINT_CLASS = "pdf-print";
 export declare const PDF_MIME_TYPE = "application/pdf";
+export declare const PDF_EDITOR_KEY_PREFIX = "pdfjs_internal_editor_";
+export declare const PDF_FREE_TEXT_FONT_SIZE = 12;
+export declare const PDF_FREE_TEXT_COLOR: number[];
+export declare const PDF_WATERMARK_FONT_SIZE = 48;
+export declare const PDF_WATERMARK_COLOR: number[];
 export declare const PDF_PRINT_STYLE: string;
 export declare const PDF_WHEEL_ZOOM_DIVISOR = 500;
+interface CreateFreeTextEntryParameters {
+  color: number[];
+  fontSize: number;
+  id: string;
+  pageIndex: number;
+  rect: [number, number, number, number];
+  value: string;
+}
+export declare const createFreeTextEntry: ({ color, fontSize, id, pageIndex, rect, value }: CreateFreeTextEntryParameters) => PdfFreeTextEntry;
 export declare const destroyLoadingTask: (task: PDFDocumentLoadingTask) => void;
 interface Props {
   cssWidth: number;
@@ -123,6 +191,8 @@ interface Props {
   pixelRatio: number;
 }
 export declare const getCanvasScale: ({ cssWidth, pageHeight, pageWidth, pixelRatio }: Props) => number;
+export declare const getDownloadBytes: (pdfDocument: PDFDocumentProxy, watermark: string | undefined) => Promise<Uint8Array<ArrayBuffer>>;
+export declare const getPdfPages: (pdfDocument: PDFDocumentProxy) => Promise<PDFPageProxy[]>;
 export declare const getSourceParameters: (source: PdfSource) => Promise<{
   data: Uint8Array;
 } | {
@@ -136,4 +206,6 @@ export declare const getZoomedScroll: ({ point, ratio, scroll }: {
 export declare const loadPdfDocument: (renderer: PdfRenderer, source: PdfSource, parameters: PdfDocumentParameters) => Promise<PDFDocumentLoadingTask>;
 export declare const renderPrintImage: (pdfDocument: PDFDocumentProxy, pageNumber: number) => Promise<HTMLImageElement>;
 export declare const renderPrintSheets: (pdfDocument: PDFDocumentProxy, checkIsCancelled: () => boolean) => Promise<HTMLDivElement | undefined>;
+export declare const readXfdf: (xfdf: string, takenIds: ReadonlySet<string>) => Result<PdfFreeText[], string>;
+export declare const writeXfdf: (freeTexts: PdfFreeText[]) => string;
 export {};

package/dist/index.js

@@ -1,5 +1,181 @@
-import { downloadFile, getResultAsync, getSynchronizedFunction, noop } from "@esposter/shared";
+import { Result, err, ok } from "neverthrow";
+import { downloadFile, getResultAsync, getSynchronizedFunction, noop, withFinalizerAsync } from "@esposter/shared";
 import { computed, effectScope, onScopeDispose, ref, shallowRef, toValue, watch } from "vue";
+// src/models/PdfEditorMode.ts
+let PdfEditorMode = /* @__PURE__ */ function(PdfEditorMode) {
+	PdfEditorMode[PdfEditorMode["None"] = 0] = "None";
+	PdfEditorMode[PdfEditorMode["FreeText"] = 3] = "FreeText";
+	PdfEditorMode[PdfEditorMode["Highlight"] = 9] = "Highlight";
+	PdfEditorMode[PdfEditorMode["Stamp"] = 13] = "Stamp";
+	PdfEditorMode[PdfEditorMode["Ink"] = 15] = "Ink";
+	return PdfEditorMode;
+}({});
+// src/services/constants.ts
+const PDF_MAX_CANVAS_AREA = 16777216;
+const PDF_MIN_SCALE = .1;
+const PDF_MAX_SCALE = 10;
+const PDF_ZOOM_STEP = 1.1;
+const PDF_OPENING_SCALE = "auto";
+const PDF_ROTATION_STEP = 90;
+const PDF_FULL_TURN = 360;
+const PDF_PRINT_SCALE = 2;
+const PDF_PRINT_BATCH_SIZE = 10;
+const PDF_PRINT_CLASS = "pdf-print";
+const PDF_MIME_TYPE = "application/pdf";
+const PDF_EDITOR_KEY_PREFIX = "pdfjs_internal_editor_";
+const PDF_FREE_TEXT_FONT_SIZE = 12;
+const PDF_FREE_TEXT_COLOR = [
+	0,
+	0,
+	0
+];
+const PDF_WATERMARK_FONT_SIZE = 48;
+const PDF_WATERMARK_COLOR = [
+	128,
+	128,
+	128
+];
+const PDF_PRINT_STYLE = `@page { margin: 3mm } .${PDF_PRINT_CLASS} { display: none } .${PDF_PRINT_CLASS} img { display: block; page-break-after: always; width: 100% } @media print { .${PDF_PRINT_CLASS} { display: block } body > :not(.${PDF_PRINT_CLASS}) { display: none !important } }`;
+const PDF_WHEEL_ZOOM_DIVISOR = 500;
+// src/services/createFreeTextEntry.ts
+const createFreeTextEntry = ({ color, fontSize, id, pageIndex, rect, value }) => ({
+	annotationType: 3,
+	color,
+	deleted: false,
+	fontSize,
+	id,
+	pageIndex,
+	rect,
+	rotation: 0,
+	value
+});
+// src/services/getPdfPages.ts
+const getPdfPages = (pdfDocument) => Promise.all(Array.from({ length: pdfDocument.numPages }, (_value, pageIndex) => pdfDocument.getPage(pageIndex + 1)));
+// src/xfdf/readXfdf.ts
+const parseCoordinate = (text) => text.trim() === "" ? NaN : Number(text);
+const checkRectangle = (coordinates) => coordinates.length === 4 && coordinates.every((coordinate) => Number.isFinite(coordinate));
+const readFreeText = (element, index, usedIds) => {
+	const page = element.getAttribute("page") ?? "";
+	const coordinates = (element.getAttribute("rect") ?? "").split(",").map((text) => parseCoordinate(text));
+	if (!/^\d+$/u.test(page)) return err(`Free text ${index + 1} has no valid page`);
+	if (!checkRectangle(coordinates)) return err(`Free text ${index + 1} has no valid rect`);
+	const contents = element.querySelector("contents")?.textContent ?? "";
+	if (contents.trim() === "") return err(`Free text ${index + 1} has no contents`);
+	const name = element.getAttribute("name") ?? "";
+	const id = name === "" || usedIds.has(name) ? crypto.randomUUID() : name;
+	usedIds.add(id);
+	return ok({
+		contents,
+		id,
+		pageNumber: Number(page) + 1,
+		rect: coordinates
+	});
+};
+const readXfdf = (xfdf, takenIds) => {
+	const xfdfDocument = new DOMParser().parseFromString(xfdf, "application/xml");
+	if (xfdfDocument.querySelector("parsererror")) return err("The XFDF is not well-formed XML");
+	const usedIds = new Set(takenIds);
+	return Result.combine(Array.from(xfdfDocument.querySelectorAll("freetext"), (element, index) => readFreeText(element, index, usedIds)));
+};
+// src/xfdf/writeXfdf.ts
+const escapeXml = (text) => text.replaceAll(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/gu, "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+const writeXfdf = (freeTexts) => {
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve"><annots>${freeTexts.map(({ contents, id, pageNumber, rect }) => `<freetext name="${escapeXml(id)}" page="${pageNumber - 1}" rect="${rect.join(",")}"><contents>${escapeXml(contents)}</contents></freetext>`).join("")}</annots></xfdf>`;
+};
+// src/composables/usePdfAnnotations.ts
+const readComments = async (loaded) => {
+	const pages = await getPdfPages(loaded);
+	return (await Promise.all(pages.map(async (page, pageIndex) => {
+		const annotations = await page.getAnnotations();
+		page.cleanup();
+		return annotations.filter(({ subtype }) => subtype === "Text").map(({ contentsObj }) => ({
+			contents: contentsObj?.str ?? "",
+			pageNumber: pageIndex + 1
+		}));
+	}))).flat();
+};
+const setEditorHook = (loaded, onEditor) => {
+	Object.assign(loaded.annotationStorage, { onAnnotationEditor: onEditor });
+};
+const readFreeTexts = (loaded) => Array.from(loaded.annotationStorage, ([key, value]) => {
+	const data = typeof value.serialize === "function" ? value.serialize() : value;
+	if (data?.annotationType !== 3 || !data.rect) return [];
+	const id = data.id ?? key.slice(22);
+	return [{
+		contents: data.value ?? "",
+		id,
+		pageNumber: (data.pageIndex ?? 0) + 1,
+		rect: data.rect
+	}];
+}).flat();
+const storeFreeTexts = (loaded, freeTexts) => {
+	for (const { contents, id, pageNumber, rect } of freeTexts) loaded.annotationStorage.setValue(`${PDF_EDITOR_KEY_PREFIX}xfdf${id}`, {
+		...createFreeTextEntry({
+			color: PDF_FREE_TEXT_COLOR,
+			fontSize: 12,
+			id,
+			pageIndex: pageNumber - 1,
+			rect,
+			value: contents
+		}),
+		isClone: true,
+		isCopy: true
+	});
+};
+const usePdfAnnotations = ({ isCommentsWanted = false, onChange, pdfDocument, viewer }) => {
+	const comments = shallowRef();
+	const loadComments = getSynchronizedFunction(async (loaded) => {
+		await getResultAsync(async () => {
+			const loadedComments = await readComments(loaded);
+			if (loaded === toValue(pdfDocument)) comments.value = loadedComments;
+		}).match(noop, (error) => {
+			console.error(error);
+			if (loaded === toValue(pdfDocument)) comments.value = [];
+		});
+	});
+	const setEditorMode = (mode) => {
+		viewer.editorMode.value = mode;
+	};
+	const exportXfdf = () => {
+		const loaded = toValue(pdfDocument);
+		return writeXfdf(loaded ? readFreeTexts(loaded) : []);
+	};
+	const importXfdf = (xfdf) => {
+		const loaded = toValue(pdfDocument);
+		if (!loaded) return err("No document is open to import into");
+		return readXfdf(xfdf, new Set(readFreeTexts(loaded).map(({ id }) => id))).andThen((freeTexts) => {
+			const stray = freeTexts.find(({ pageNumber }) => pageNumber > loaded.numPages);
+			if (stray) return err(`The XFDF has a free text on page ${stray.pageNumber}, and the document ends at page ${loaded.numPages}`);
+			storeFreeTexts(loaded, freeTexts);
+			viewer.drawStoredEditors();
+			return ok(void 0);
+		});
+	};
+	watch(() => toValue(pdfDocument), (loaded) => {
+		comments.value = void 0;
+		if (!loaded) return;
+		setEditorHook(loaded, (kind) => {
+			if (kind === null) return;
+			const drawn = [...loaded.annotationStorage].at(-1)?.[1];
+			if (drawn) onChange?.({
+				kind,
+				pageNumber: drawn.pageIndex + 1
+			});
+		});
+	}, { immediate: true });
+	let commentsDocument;
+	watch([() => toValue(pdfDocument), () => toValue(isCommentsWanted)], ([loaded, isWanted]) => {
+		if (!loaded || !isWanted || loaded === commentsDocument) return;
+		commentsDocument = loaded;
+		loadComments(loaded);
+	}, { immediate: true });
+	return {
+		comments,
+		exportXfdf,
+		importXfdf,
+		setEditorMode
+	};
+};
 // src/services/destroyLoadingTask.ts
 const destroyLoadingTask = getSynchronizedFunction(async (task) => {
 	await task.destroy();
@@ -98,18 +274,6 @@ const usePdfDocument = ({ parameters = {}, renderer, source }) => {
 		submitPassword
 	};
 };
-// src/services/constants.ts
-const PDF_MAX_CANVAS_AREA = 16777216;
-const PDF_MIN_SCALE = .1;
-const PDF_MAX_SCALE = 10;
-const PDF_ROTATION_STEP = 90;
-const PDF_FULL_TURN = 360;
-const PDF_PRINT_SCALE = 2;
-const PDF_PRINT_BATCH_SIZE = 10;
-const PDF_PRINT_CLASS = "pdf-print";
-const PDF_MIME_TYPE = "application/pdf";
-const PDF_PRINT_STYLE = `@page { margin: 3mm } .${PDF_PRINT_CLASS} { display: none } .${PDF_PRINT_CLASS} img { display: block; page-break-after: always; width: 100% } @media print { .${PDF_PRINT_CLASS} { display: block } body > :not(.${PDF_PRINT_CLASS}) { display: none !important } }`;
-const PDF_WHEEL_ZOOM_DIVISOR = 500;
 // src/services/getCanvasScale.ts
 const getCanvasScale = ({ cssWidth, pageHeight, pageWidth, pixelRatio }) => {
 	const scale = cssWidth / pageWidth * pixelRatio;
@@ -117,7 +281,7 @@ const getCanvasScale = ({ cssWidth, pageHeight, pageWidth, pixelRatio }) => {
 	return Math.sqrt(PDF_MAX_CANVAS_AREA / (pageWidth * pageHeight));
 };
 // src/composables/usePdfPage.ts
-const usePdfPage = ({ canvas, isVisible = true, pageNumber, pdfDocument }) => {
+const usePdfPage = ({ canvas, isActive = true, isVisible = true, pageNumber, pagesRotation = 0, pdfDocument }) => {
 	let cssWidth = 0;
 	let loadGeneration = 0;
 	let page;
@@ -135,13 +299,20 @@ const usePdfPage = ({ canvas, isVisible = true, pageNumber, pdfDocument }) => {
 		const currentCanvas = toValue(canvas);
 		if (!page || !currentCanvas || cssWidth === 0 || !toValue(isVisible)) return;
 		cancelRender();
-		const { height, width } = page.getViewport({ scale: 1 });
-		const viewport = page.getViewport({ scale: getCanvasScale({
-			cssWidth,
-			pageHeight: height,
-			pageWidth: width,
-			pixelRatio: window.devicePixelRatio
-		}) });
+		const rotation = (page.rotate + toValue(pagesRotation)) % 360;
+		const { height, width } = page.getViewport({
+			rotation,
+			scale: 1
+		});
+		const viewport = page.getViewport({
+			rotation,
+			scale: getCanvasScale({
+				cssWidth,
+				pageHeight: height,
+				pageWidth: width,
+				pixelRatio: window.devicePixelRatio
+			})
+		});
 		currentCanvas.width = viewport.width;
 		currentCanvas.height = viewport.height;
 		const task = page.render({
@@ -151,11 +322,19 @@ const usePdfPage = ({ canvas, isVisible = true, pageNumber, pdfDocument }) => {
 		renderTask = task;
 		awaitRender(task);
 	};
-	watch([() => toValue(pdfDocument), () => toValue(pageNumber)], getSynchronizedFunction(async ([currentDocument, currentPageNumber]) => {
+	const isWanted = ref(false);
+	watch(() => toValue(isActive), (active) => {
+		if (active) isWanted.value = true;
+	}, { immediate: true });
+	watch([
+		() => toValue(pdfDocument),
+		() => toValue(pageNumber),
+		isWanted
+	], getSynchronizedFunction(async ([currentDocument, currentPageNumber, currentIsWanted]) => {
 		const generation = ++loadGeneration;
 		cancelRender();
 		page = void 0;
-		if (!currentDocument) return;
+		if (!currentDocument || !currentIsWanted) return;
 		await getResultAsync(async () => {
 			const loadedPage = await currentDocument.getPage(currentPageNumber);
 			if (generation !== loadGeneration) return;
@@ -185,18 +364,22 @@ const usePdfPage = ({ canvas, isVisible = true, pageNumber, pdfDocument }) => {
 	watch(() => toValue(isVisible), (visible) => {
 		if (visible) drawPage();
 	});
+	watch(() => toValue(pagesRotation), () => {
+		drawPage();
+	});
 	onScopeDispose(() => {
 		loadGeneration++;
 		cancelRender();
+		page?.cleanup();
 	});
 };
 // src/composables/usePdfThumbnails.ts
-const usePdfThumbnails = ({ currentPageNumber, pdfDocument, root }) => {
+const usePdfThumbnails = ({ currentPageNumber, pagesRotation, pdfDocument, root }) => {
 	const thumbnails = shallowRef([]);
 	const rows = /* @__PURE__ */ new Map();
 	let observer;
 	let scope;
-	const createThumbnail = (pageNumber, currentDocument, currentObserver) => {
+	const createThumbnail = (pageNumber, currentDocument) => {
 		const canvas = shallowRef();
 		const isVisible = ref(false);
 		const thumbnail = {
@@ -207,41 +390,45 @@ const usePdfThumbnails = ({ currentPageNumber, pdfDocument, root }) => {
 		};
 		usePdfPage({
 			canvas: () => canvas.value,
+			isActive: () => isVisible.value,
 			isVisible: () => isVisible.value,
 			pageNumber,
+			pagesRotation: () => toValue(pagesRotation),
 			pdfDocument: currentDocument
 		});
 		watch(canvas, (element, _previousElement, onCleanup) => {
 			if (!element) return;
 			rows.set(element, thumbnail);
-			currentObserver.observe(element);
+			observer?.observe(element);
 			onCleanup(() => {
-				currentObserver.unobserve(element);
+				observer?.unobserve(element);
 				rows.delete(element);
 			});
 		});
 		return thumbnail;
 	};
-	const disposeThumbnails = () => {
-		scope?.stop();
+	watch(() => toValue(root), (rootElement) => {
 		observer?.disconnect();
-	};
-	watch(() => toValue(pdfDocument), (loaded) => {
-		disposeThumbnails();
-		rows.clear();
-		thumbnails.value = [];
-		if (!loaded) return;
-		const currentObserver = new IntersectionObserver((entries) => {
+		observer = new IntersectionObserver((entries) => {
 			for (const entry of entries) {
 				const row = rows.get(entry.target);
 				if (row) row.isVisible.value = entry.isIntersecting;
 			}
-		}, { root: toValue(root) ?? null });
-		observer = currentObserver;
+		}, { root: rootElement ?? null });
+		for (const element of rows.keys()) observer.observe(element);
+	}, { immediate: true });
+	watch(() => toValue(pdfDocument), (loaded) => {
+		scope?.stop();
+		rows.clear();
+		thumbnails.value = [];
+		if (!loaded) return;
 		scope = effectScope();
-		thumbnails.value = scope.run(() => Array.from({ length: loaded.numPages }, (_value, index) => createThumbnail(index + 1, loaded, currentObserver))) ?? [];
+		thumbnails.value = scope.run(() => Array.from({ length: loaded.numPages }, (_value, index) => createThumbnail(index + 1, loaded))) ?? [];
 	}, { immediate: true });
-	onScopeDispose(disposeThumbnails);
+	onScopeDispose(() => {
+		scope?.stop();
+		observer?.disconnect();
+	});
 	return thumbnails;
 };
 // src/services/getZoomedScroll.ts
@@ -342,6 +529,39 @@ const usePdfZoomGesture = ({ container, getViewer }) => {
 		abortController.abort();
 	});
 };
+// src/services/getDownloadBytes.ts
+const addWatermark = async (pdfDocument, watermark) => {
+	const { annotationStorage } = pdfDocument;
+	return (await getPdfPages(pdfDocument)).map((page, pageIndex) => {
+		const [left = 0, bottom = 0, right = 0, top = 0] = page.view;
+		page.cleanup();
+		const middle = (bottom + top) / 2;
+		const id = `watermark${pageIndex}`;
+		const key = `${PDF_EDITOR_KEY_PREFIX}${id}`;
+		annotationStorage.setValue(key, createFreeTextEntry({
+			color: PDF_WATERMARK_COLOR,
+			fontSize: 48,
+			id,
+			pageIndex,
+			rect: [
+				left,
+				middle - 24,
+				right,
+				middle + 24
+			],
+			value: watermark
+		}));
+		return key;
+	});
+};
+const getDownloadBytes = async (pdfDocument, watermark) => {
+	const { annotationStorage } = pdfDocument;
+	if (annotationStorage.size === 0 && !watermark) return new Uint8Array(await pdfDocument.getData());
+	const watermarkKeys = watermark ? await addWatermark(pdfDocument, watermark) : [];
+	return withFinalizerAsync(() => pdfDocument.saveDocument(), () => {
+		for (const key of watermarkKeys) annotationStorage.remove(key);
+	});
+};
 // src/services/renderPrintImage.ts
 const renderPrintImage = async (pdfDocument, pageNumber) => {
 	const page = await pdfDocument.getPage(pageNumber);
@@ -382,9 +602,9 @@ const renderPrintSheets = async (pdfDocument, checkIsCancelled) => {
 	return checkIsCancelled() ? void 0 : printRoot;
 };
 // src/composables/usePdfViewer.ts
-const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, viewerApi }) => {
+const usePdfViewer = ({ container, highlightTerms = [], imageResourcesPath, pdfDocument, viewer, viewerApi }) => {
 	const currentPageNumber = ref(0);
-	const isFullscreen = ref(false);
+	const editorMode = ref(0);
 	const isMatchCase = ref(false);
 	const isNotFound = ref(false);
 	const isWholeWord = ref(false);
@@ -392,23 +612,25 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 		current: 0,
 		total: 0
 	});
-	const outline = shallowRef([]);
+	const outline = shallowRef();
 	const overlays = shallowRef([]);
 	const pagesCount = ref(0);
 	const pagesRotation = ref(0);
 	const scale = ref(0);
 	const searchQuery = ref("");
+	const documentGeneration = ref(0);
 	const isZoomInDisabled = computed(() => scale.value >= 10);
+	const isZoomOutDisabled = computed(() => scale.value <= PDF_MIN_SCALE);
 	let abortController;
-	let containerElement;
 	let eventBus;
 	let linkService;
 	let pdfViewer;
 	let resizeObserver;
 	let printRoot;
 	let printGeneration = 0;
-	const onFullscreenChange = () => {
-		isFullscreen.value = window.document.fullscreenElement === containerElement;
+	let editorManager;
+	const applyEditorMode = () => {
+		if (pdfViewer && editorManager) pdfViewer.annotationEditorMode = { mode: editorMode.value };
 	};
 	const createViewer = (currentViewerApi, containerValue, viewerElement) => {
 		const { EventBus, FindState, LinkTarget, PDFFindController, PDFLinkService, PDFViewer } = currentViewerApi;
@@ -428,18 +650,22 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 			container: containerValue,
 			eventBus: bus,
 			findController: controller,
+			imageResourcesPath,
 			linkService: links,
 			maxCanvasPixels: PDF_MAX_CANVAS_AREA,
 			viewer: viewerElement
 		});
 		links.setViewer(instance);
 		abortController = viewerAbortController;
-		containerElement = containerValue;
 		eventBus = bus;
 		linkService = links;
 		pdfViewer = instance;
 		bus.on("pagesinit", () => {
-			instance.currentScaleValue = "auto";
+			instance.currentScaleValue = PDF_OPENING_SCALE;
+		});
+		bus.on("annotationeditoruimanager", (event) => {
+			editorManager = event.uiManager;
+			applyEditorMode();
 		});
 		bus.on("pagechanging", (event) => {
 			currentPageNumber.value = event.pageNumber;
@@ -471,9 +697,6 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 			if (currentScaleValue) pdfViewer.currentScaleValue = currentScaleValue;
 		});
 		resizeObserver.observe(containerValue);
-		window.document.addEventListener("fullscreenchange", () => {
-			onFullscreenChange();
-		}, { signal });
 		window.addEventListener("afterprint", () => {
 			removePrint();
 		}, { signal });
@@ -483,17 +706,22 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 		await getResultAsync(async () => {
 			const items = await loaded.getOutline();
 			if (loaded === toValue(pdfDocument)) outline.value = items ?? [];
-		}).match(noop, console.error);
+		}).match(noop, (error) => {
+			console.error(error);
+			if (loaded === toValue(pdfDocument)) outline.value = [];
+		});
 	});
 	const applyDocument = (loaded) => {
 		if (!pdfViewer || !linkService) return;
 		pagesCount.value = loaded?.numPages ?? 0;
 		overlays.value = [];
-		outline.value = [];
+		outline.value = void 0;
+		editorManager = void 0;
 		pdfViewer.setDocument(loaded ?? null);
 		linkService.setDocument(loaded ?? null);
 		currentPageNumber.value = 1;
 		pagesRotation.value = 0;
+		searchQuery.value = "";
 		matchesCount.value = {
 			current: 0,
 			total: 0
@@ -501,8 +729,8 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 		isNotFound.value = false;
 		if (!loaded) return;
 		loadOutline(loaded);
-		const terms = toValue(highlightTerms);
-		if (terms.length > 0) findText({ query: terms });
+		searchQuery.value = toValue(highlightTerms).join(" ");
+		documentGeneration.value++;
 	};
 	const findText = ({ isPrevious = false, query, type = "" }) => {
 		eventBus?.dispatch("find", {
@@ -515,14 +743,24 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 			type
 		});
 	};
+	watch([
+		searchQuery,
+		isMatchCase,
+		isWholeWord,
+		documentGeneration
+	], () => {
+		if (toValue(pdfDocument)) findText({ query: searchQuery.value });
+	});
 	const removePrint = () => {
 		printGeneration++;
 		printRoot?.remove();
 		printRoot = void 0;
 	};
-	const followBookmark = (item) => {
-		if (item.dest) linkService?.goToDestination(item.dest);
-	};
+	const followBookmark = getSynchronizedFunction(async (item) => {
+		await getResultAsync(async () => {
+			if (item.dest) await linkService?.goToDestination(item.dest);
+		}).match(noop, console.error);
+	});
 	const goToPage = (pageNumber) => {
 		if (pdfViewer && Number.isInteger(pageNumber) && pageNumber >= 1 && pageNumber <= pagesCount.value) pdfViewer.currentPageNumber = pageNumber;
 	};
@@ -532,11 +770,17 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 	const nextPage = () => {
 		pdfViewer?.nextPage();
 	};
+	const zoomTo = (nextScale) => {
+		if (pdfViewer) pdfViewer.currentScale = Math.min(Math.max(nextScale, PDF_MIN_SCALE), 10);
+	};
 	const zoomIn = () => {
-		pdfViewer?.increaseScale();
+		if (pdfViewer && pdfViewer.currentScale > 0) zoomTo(pdfViewer.currentScale * PDF_ZOOM_STEP);
 	};
 	const zoomOut = () => {
-		pdfViewer?.decreaseScale();
+		if (pdfViewer && pdfViewer.currentScale > 0) zoomTo(pdfViewer.currentScale / PDF_ZOOM_STEP);
+	};
+	const resetZoom = () => {
+		if (pdfViewer) pdfViewer.currentScaleValue = PDF_OPENING_SCALE;
 	};
 	const fitWidth = () => {
 		if (pdfViewer) pdfViewer.currentScaleValue = "page-width";
@@ -547,8 +791,8 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 	const actualSize = () => {
 		if (pdfViewer) pdfViewer.currentScaleValue = "page-actual";
 	};
-	const rotate = () => {
-		if (pdfViewer) pdfViewer.pagesRotation = (pdfViewer.pagesRotation + 90) % 360;
+	const rotate = (degrees) => {
+		if (pdfViewer) pdfViewer.pagesRotation = ((pdfViewer.pagesRotation + degrees) % 360 + 360) % 360;
 	};
 	const findNext = () => {
 		findText({
@@ -563,19 +807,11 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 			type: "again"
 		});
 	};
-	const toggleFullscreen = getSynchronizedFunction(async () => {
-		const element = containerElement;
-		if (!element) return;
-		await getResultAsync(async () => {
-			if (window.document.fullscreenElement) await window.document.exitFullscreen();
-			else await element.requestFullscreen();
-		}).match(noop, console.error);
-	});
-	const download = getSynchronizedFunction(async (filename) => {
+	const download = getSynchronizedFunction(async (filename, watermark) => {
 		const downloaded = toValue(pdfDocument);
 		if (!downloaded) return;
 		await getResultAsync(async () => {
-			downloadFile(filename, new Uint8Array(await downloaded.getData()), PDF_MIME_TYPE);
+			downloadFile(filename, await getDownloadBytes(downloaded, watermark), PDF_MIME_TYPE);
 		}).match(noop, console.error);
 	});
 	const print = getSynchronizedFunction(async () => {
@@ -591,6 +827,18 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 			window.print();
 		}).match(noop, console.error);
 	});
+	const drawStoredEditors = getSynchronizedFunction(async () => {
+		const manager = editorManager;
+		if (!manager) return;
+		await getResultAsync(async () => {
+			await Promise.all(Array.from({ length: pagesCount.value }, async (_value, pageIndex) => {
+				const layer = manager.getLayer(pageIndex);
+				if (!layer) return;
+				await manager.findClonesForPage(layer);
+				layer.div.hidden = layer.isEmpty;
+			}));
+		}).match(noop, console.error);
+	});
 	usePdfZoomGesture({
 		container,
 		getViewer: () => pdfViewer
@@ -606,13 +854,7 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 	watch(() => toValue(pdfDocument), (loaded) => {
 		applyDocument(loaded);
 	});
-	watch([
-		searchQuery,
-		isMatchCase,
-		isWholeWord
-	], () => {
-		findText({ query: searchQuery.value });
-	});
+	watch(editorMode, applyEditorMode);
 	onScopeDispose(() => {
 		removePrint();
 		if (!pdfViewer) return;
@@ -624,17 +866,19 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 		actualSize,
 		currentPageNumber,
 		download,
+		drawStoredEditors,
+		editorMode,
 		findNext,
 		findPrevious,
 		fitPage,
 		fitWidth,
 		followBookmark,
 		goToPage,
-		isFullscreen,
 		isMatchCase,
 		isNotFound,
 		isWholeWord,
 		isZoomInDisabled,
+		isZoomOutDisabled,
 		matchesCount,
 		nextPage,
 		outline,
@@ -643,12 +887,12 @@ const usePdfViewer = ({ container, highlightTerms = [], pdfDocument, viewer, vie
 		pagesRotation,
 		previousPage,
 		print,
+		resetZoom,
 		rotate,
 		scale,
 		searchQuery,
-		toggleFullscreen,
 		zoomIn,
 		zoomOut
 	};
 };
-export { PDF_FULL_TURN, PDF_MAX_CANVAS_AREA, PDF_MAX_SCALE, PDF_MIME_TYPE, PDF_MIN_SCALE, PDF_PRINT_BATCH_SIZE, PDF_PRINT_CLASS, PDF_PRINT_SCALE, PDF_PRINT_STYLE, PDF_ROTATION_STEP, PDF_WHEEL_ZOOM_DIVISOR, destroyLoadingTask, getCanvasScale, getSourceParameters, getZoomedScroll, loadPdfDocument, renderPrintImage, renderPrintSheets, usePdfDocument, usePdfPage, usePdfThumbnails, usePdfViewer, usePdfZoomGesture };
+export { PDF_EDITOR_KEY_PREFIX, PDF_FREE_TEXT_COLOR, PDF_FREE_TEXT_FONT_SIZE, PDF_FULL_TURN, PDF_MAX_CANVAS_AREA, PDF_MAX_SCALE, PDF_MIME_TYPE, PDF_MIN_SCALE, PDF_OPENING_SCALE, PDF_PRINT_BATCH_SIZE, PDF_PRINT_CLASS, PDF_PRINT_SCALE, PDF_PRINT_STYLE, PDF_ROTATION_STEP, PDF_WATERMARK_COLOR, PDF_WATERMARK_FONT_SIZE, PDF_WHEEL_ZOOM_DIVISOR, PDF_ZOOM_STEP, PdfEditorMode, createFreeTextEntry, destroyLoadingTask, getCanvasScale, getDownloadBytes, getPdfPages, getSourceParameters, getZoomedScroll, loadPdfDocument, readXfdf, renderPrintImage, renderPrintSheets, usePdfAnnotations, usePdfDocument, usePdfPage, usePdfThumbnails, usePdfViewer, usePdfZoomGesture, writeXfdf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-pdfjs-headless",
-  "version": "4.3.3",
+  "version": "4.5.0",
   "description": "Headless Vue composables over pdfjs-dist: a document's loading, a page's drawing and the viewer's state, with no styling and no renderer of its own.",
   "keywords": [
     "headless",
@@ -43,20 +43,21 @@
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "test": "vitest",
-    "typecheck": "tsc"
+    "typecheck": "tsrs --fast"
   },
   "dependencies": {
-    "@esposter/shared": "4.3.3"
+    "@esposter/shared": "4.5.0",
+    "neverthrow": "^8.2.0"
   },
   "devDependencies": {
-    "@esposter/configuration": "4.3.3",
+    "@esposter/configuration": "4.5.0",
     "@vue/test-utils": "^2.5.1",
     "happy-dom": "^21.0.4",
-    "tsdown": "^0.23.1"
+    "tsdown": "^0.23.5"
   },
   "peerDependencies": {
-    "pdfjs-dist": "^6.4.299",
+    "pdfjs-dist": "^6.5.438",
     "vue": "^3.5.44"
   },
-  "gitHead": "955bbc130ad9b28877fd4ae8efc73a045141ce01"
+  "gitHead": "e30c001f3b4b15693e75fb53092d62a97ade4d2b"
 }