@file-viewer/core 3.3.0 → 3.3.1

package/dist/contracts/xml.d.ts

@@ -1,3 +1,4 @@
+/** Optional, self-hosted XML Schema 1.0 / XSLT 1.0 profiles. */
 export interface FileViewerXmlProfile {
     id: string;
     match: {
@@ -10,6 +11,7 @@ export interface FileViewerXmlProfile {
             enabled: boolean;
         };
     };
+    /** Relative to the manifest URL (or baseUrl for inline profiles). */
     xsd?: string;
     xslt: string;
 }
@@ -23,14 +25,21 @@ export interface FileViewerXmlDiagnostic {
     profileId?: string;
 }
 export interface FileViewerXmlOptions {
+    /** Opt in with a same-origin HTTP(S) manifest. Redirects are rejected. */
     profilesUrl?: string;
+    /** Alternative to profilesUrl. Supplying both is a configuration error. */
     profiles?: FileViewerXmlProfile[];
+    /** Base for inline profiles' resource paths; defaults to the document URL. */
     baseUrl?: string;
     runtime?: {
+        /** xmllint-wasm@5.3.0 browser worker; xmllint.wasm must be beside it. */
         xsdWorkerUrl?: string;
+        /** xslt-polyfill@1.0.29 dist/xslt-wasm.js, containing embedded WASM. */
         xsltModuleUrl?: string;
     };
+    /** Whole profile operation, including downloads; default 15s, ceiling 60s. */
     timeoutMs?: number;
+    /** Limits may lower the hard ceilings but cannot disable them. */
     limits?: {
         maxXmlBytes?: number;
         maxResourceBytes?: number;
@@ -39,10 +48,12 @@ export interface FileViewerXmlOptions {
         maxTotalResourceBytes?: number;
     };
     initialView?: 'source' | 'rendered';
+    /** Labels can be localized without replacing the source renderer. */
     labels?: {
         viewSource?: string;
         viewRendered?: string;
         diagnostics?: string;
     };
+    /** Also available on the rendered instance; never contains generated HTML. */
     onDiagnostic?: (diagnostic: FileViewerXmlDiagnostic) => void;
 }

package/dist/export.d.ts

@@ -1,3 +1,10 @@
-export { buildFileViewerRenderedDomDocument, buildFileViewerRenderedHtmlDocument, buildExportDomDocument, buildExportHtmlDocument, collectDocumentStyles, sanitizeFileViewerExportDocumentDom, sanitizeFileViewerExportDocumentHtml, } from "./exportDocument.js";
-export type { BuildExportHtmlDocumentOptions, BuildFileViewerRenderedHtmlDocumentOptions, } from "./exportDocument.js";
-export { inlineFileViewerBlobUrlsInHtml, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerImages, waitForFileViewerNextPaint, waitForFileViewerPrintWindowReady, } from "./output/export.js";
+/**
+ * Explicit HTML export and print-document entrypoint.
+ *
+ * This subpath owns the DOM sanitizer and is intentionally excluded from the
+ * normal viewer/headless graph. Viewer operations load it only when the user
+ * starts an HTML export or print operation.
+ */
+export { buildFileViewerRenderedDomDocument, buildFileViewerRenderedHtmlDocument, buildExportDomDocument, buildExportHtmlDocument, collectDocumentStyles, sanitizeFileViewerExportDocumentDom, sanitizeFileViewerExportDocumentHtml, } from './exportDocument.js';
+export type { BuildExportHtmlDocumentOptions, BuildFileViewerRenderedHtmlDocumentOptions, } from './exportDocument.js';
+export { inlineFileViewerBlobUrlsInHtml, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerImages, waitForFileViewerNextPaint, waitForFileViewerPrintWindowReady, } from './output/export.js';

package/dist/export.js

@@ -1,2 +1,9 @@
-export { buildFileViewerRenderedDomDocument, buildFileViewerRenderedHtmlDocument, buildExportDomDocument, buildExportHtmlDocument, collectDocumentStyles, sanitizeFileViewerExportDocumentDom, sanitizeFileViewerExportDocumentHtml, } from "./exportDocument.js";
-export { inlineFileViewerBlobUrlsInHtml, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerImages, waitForFileViewerNextPaint, waitForFileViewerPrintWindowReady, } from "./output/export.js";
+/**
+ * Explicit HTML export and print-document entrypoint.
+ *
+ * This subpath owns the DOM sanitizer and is intentionally excluded from the
+ * normal viewer/headless graph. Viewer operations load it only when the user
+ * starts an HTML export or print operation.
+ */
+export { buildFileViewerRenderedDomDocument, buildFileViewerRenderedHtmlDocument, buildExportDomDocument, buildExportHtmlDocument, collectDocumentStyles, sanitizeFileViewerExportDocumentDom, sanitizeFileViewerExportDocumentHtml, } from './exportDocument.js';
+export { inlineFileViewerBlobUrlsInHtml, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerImages, waitForFileViewerNextPaint, waitForFileViewerPrintWindowReady, } from './output/export.js';

package/dist/exportDocument.d.ts

@@ -1,5 +1,15 @@
-import type { FileRenderExportAdapter, FileRenderExportMode, FileViewerPrintMaskOptions } from "./contracts/types.js";
+import type { FileRenderExportAdapter, FileRenderExportMode, FileViewerPrintMaskOptions } from './contracts/types.js';
+/**
+ * Sanitize the complete standalone export document before it is downloaded or
+ * mounted into a print window. This is deliberately enforced in core because
+ * third-party render adapters and watermark overrides are library inputs.
+ */
 export declare const sanitizeFileViewerExportDocumentHtml: (html: string, documentRef?: Document) => string;
+/**
+ * Produce a sanitized, inert document tree for the print-window mount path.
+ * Returning DOM here avoids reinterpreting the sanitized string through a
+ * second HTML sink such as document.write or innerHTML.
+ */
 export declare const sanitizeFileViewerExportDocumentDom: (html: string, documentRef?: Document) => HTMLHtmlElement;
 export interface BuildExportHtmlDocumentOptions {
     contentHtml: string;
@@ -8,6 +18,7 @@ export interface BuildExportHtmlDocumentOptions {
     title: string;
     watermarkInlineStyle?: string;
     mask?: FileViewerPrintMaskOptions | null;
+    /** Document whose Window owns the sanitizer. Defaults to the active document. */
     documentRef?: Document;
 }
 export declare const collectDocumentStyles: (documentRef?: Document) => string;

package/dist/exportDocument.js

@@ -1,6 +1,6 @@
 import createDOMPurify from 'dompurify';
-import { applyFileViewerPagePrintMasksToHtml, buildFileViewerPrintMaskOverlayHtml, FILE_VIEWER_PRINT_MASK_STYLE, normalizeFileViewerPrintMaskOptions, } from "./features/printMask.js";
-import { inlineFileViewerBlobUrlsInHtml, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, } from "./output/export.js";
+import { applyFileViewerPagePrintMasksToHtml, buildFileViewerPrintMaskOverlayHtml, FILE_VIEWER_PRINT_MASK_STYLE, normalizeFileViewerPrintMaskOptions, } from './features/printMask.js';
+import { inlineFileViewerBlobUrlsInHtml, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, } from './output/export.js';
 const escapeHtmlAttribute = (value) => value
     .replace(/&/g, '&')
     .replace(/"/g, '"')
@@ -47,6 +47,11 @@ const decodeCssEscape = (value, slashIndex) => {
     }
     return { value: first, nextIndex: cursor + 1 };
 };
+/**
+ * Remove CSS comments and decode identifier escapes before looking for URL
+ * functions. CSS comments and escapes may otherwise split security-sensitive
+ * tokens such as `url` or `@import` while the browser still accepts them.
+ */
 const canonicalizeCssForSecurity = (css) => {
     let output = '';
     let quote = '';
@@ -241,6 +246,12 @@ const inspectCssNetworkTokens = (css) => {
     }
     return { hasImport, hasUrl };
 };
+/**
+ * Keep ordinary CSS and local embedded resources, but remove every construct
+ * that can make an exported document initiate a new network request. Imported
+ * stylesheets fail closed; unsafe url() values become `none` so the rest of a
+ * declaration can still render.
+ */
 const sanitizeExportCss = (css) => {
     const canonical = canonicalizeCssForSecurity(css);
     const canonicalTokens = inspectCssNetworkTokens(canonical);
@@ -342,9 +353,13 @@ const getExportPurifier = (documentRef) => {
             element.setAttribute('rel', 'noopener noreferrer');
         }
         if (localName === 'a' || localName === 'area') {
+            // Keep ordinary links, but never preserve document-controlled beacons.
             element.removeAttribute('ping');
         }
         if (element.hasAttribute('srcset')) {
+            // Candidate lists have their own comma/descriptor grammar. The export
+            // keeps the materialized src and drops candidates that could select a
+            // remote resource after the standalone document is opened.
             element.removeAttribute('srcset');
         }
         if (['img', 'audio', 'video', 'source', 'track', 'input'].includes(localName || '')) {
@@ -377,12 +392,19 @@ const EXPORT_STATIC_META = [
     '<meta charset="utf-8" />',
     '<meta name="viewport" content="width=device-width,initial-scale=1" />',
 ].join('\n  ');
+/**
+ * Sanitize the complete standalone export document before it is downloaded or
+ * mounted into a print window. This is deliberately enforced in core because
+ * third-party render adapters and watermark overrides are library inputs.
+ */
 export const sanitizeFileViewerExportDocumentHtml = (html, documentRef) => {
     const currentDocument = resolveExportDocument(documentRef);
     const purifier = currentDocument
         ? getExportPurifier(currentDocument)
         : null;
     if (!purifier) {
+        // Export is a browser feature. Fail closed rather than return executable
+        // markup when called without a usable DOM implementation.
         return '<!doctype html>\n<html lang="en"><head><meta charset="utf-8" /></head><body></body></html>';
     }
     const sanitized = String(purifier.sanitize(html, EXPORT_SANITIZER_OPTIONS));
@@ -417,6 +439,11 @@ const ensureFileViewerExportDocumentMeta = (root) => {
     }
     return root;
 };
+/**
+ * Produce a sanitized, inert document tree for the print-window mount path.
+ * Returning DOM here avoids reinterpreting the sanitized string through a
+ * second HTML sink such as document.write or innerHTML.
+ */
 export const sanitizeFileViewerExportDocumentDom = (html, documentRef) => {
     const currentDocument = resolveExportDocument(documentRef);
     if (!currentDocument) {
@@ -779,6 +806,8 @@ export const collectDocumentStyles = (documentRef) => {
                 : '';
         }
         catch {
+            // Cross-origin and unreadable stylesheets fail closed. Keeping their
+            // link would make a standalone export initiate a second request.
             return '';
         }
     })

package/dist/features/document/dom/anchors.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerDocumentAnchor } from "../../../contracts/types.js";
+import type { FileViewerDocumentAnchor } from '../../../contracts/types.js';
 export declare const DEFAULT_FILE_VIEWER_ANCHOR_SELECTOR: string;
 export declare const DEFAULT_FILE_VIEWER_ANCHOR_EXCLUDE_SELECTOR: string;
 export declare const collectFileViewerDocumentAnchors: (root: HTMLElement | null) => FileViewerDocumentAnchor[];

package/dist/features/document/dom/index.d.ts

@@ -1,5 +1,5 @@
-export { DEFAULT_FILE_VIEWER_ANCHOR_EXCLUDE_SELECTOR, DEFAULT_FILE_VIEWER_ANCHOR_SELECTOR, collectFileViewerDocumentAnchors, findFileViewerAnchorForElement, getCurrentFileViewerDocumentAnchor, scrollToFileViewerDocumentAnchor, } from "./anchors.js";
-export { findFileViewerSearchProvider, findFileViewerViewStateProvider, findFileViewerZoomProvider, registerFileViewerSearchProvider, registerFileViewerViewStateProvider, registerFileViewerZoomProvider, unregisterFileViewerSearchProvider, unregisterFileViewerViewStateProvider, unregisterFileViewerZoomProvider, } from "./providers.js";
-export type { FileViewerSearchProviderHost, FileViewerViewStateProviderHost, FileViewerZoomProviderHost, } from "./providers.js";
-export { DEFAULT_FILE_VIEWER_SCROLL_CONTAINER_CANDIDATE_SELECTOR, DEFAULT_FILE_VIEWER_SCROLL_CONTAINER_SELECTOR, DEFAULT_FILE_VIEWER_SCROLLABLE_OVERFLOW_VALUES, getFileViewerScrollableRange, isFileViewerScrollableElement, resolveFileViewerScrollContainer, } from "./scroll.js";
-export type { ResolveFileViewerScrollContainerOptions, } from "./scroll.js";
+export { DEFAULT_FILE_VIEWER_ANCHOR_EXCLUDE_SELECTOR, DEFAULT_FILE_VIEWER_ANCHOR_SELECTOR, collectFileViewerDocumentAnchors, findFileViewerAnchorForElement, getCurrentFileViewerDocumentAnchor, scrollToFileViewerDocumentAnchor, } from './anchors.js';
+export { findFileViewerSearchProvider, findFileViewerViewStateProvider, findFileViewerZoomProvider, registerFileViewerSearchProvider, registerFileViewerViewStateProvider, registerFileViewerZoomProvider, unregisterFileViewerSearchProvider, unregisterFileViewerViewStateProvider, unregisterFileViewerZoomProvider, } from './providers.js';
+export type { FileViewerSearchProviderHost, FileViewerViewStateProviderHost, FileViewerZoomProviderHost, } from './providers.js';
+export { DEFAULT_FILE_VIEWER_SCROLL_CONTAINER_CANDIDATE_SELECTOR, DEFAULT_FILE_VIEWER_SCROLL_CONTAINER_SELECTOR, DEFAULT_FILE_VIEWER_SCROLLABLE_OVERFLOW_VALUES, getFileViewerScrollableRange, isFileViewerScrollableElement, resolveFileViewerScrollContainer, } from './scroll.js';
+export type { ResolveFileViewerScrollContainerOptions, } from './scroll.js';

package/dist/features/document/dom/index.js

@@ -1,3 +1,3 @@
-export { DEFAULT_FILE_VIEWER_ANCHOR_EXCLUDE_SELECTOR, DEFAULT_FILE_VIEWER_ANCHOR_SELECTOR, collectFileViewerDocumentAnchors, findFileViewerAnchorForElement, getCurrentFileViewerDocumentAnchor, scrollToFileViewerDocumentAnchor, } from "./anchors.js";
-export { findFileViewerSearchProvider, findFileViewerViewStateProvider, findFileViewerZoomProvider, registerFileViewerSearchProvider, registerFileViewerViewStateProvider, registerFileViewerZoomProvider, unregisterFileViewerSearchProvider, unregisterFileViewerViewStateProvider, unregisterFileViewerZoomProvider, } from "./providers.js";
-export { DEFAULT_FILE_VIEWER_SCROLL_CONTAINER_CANDIDATE_SELECTOR, DEFAULT_FILE_VIEWER_SCROLL_CONTAINER_SELECTOR, DEFAULT_FILE_VIEWER_SCROLLABLE_OVERFLOW_VALUES, getFileViewerScrollableRange, isFileViewerScrollableElement, resolveFileViewerScrollContainer, } from "./scroll.js";
+export { DEFAULT_FILE_VIEWER_ANCHOR_EXCLUDE_SELECTOR, DEFAULT_FILE_VIEWER_ANCHOR_SELECTOR, collectFileViewerDocumentAnchors, findFileViewerAnchorForElement, getCurrentFileViewerDocumentAnchor, scrollToFileViewerDocumentAnchor, } from './anchors.js';
+export { findFileViewerSearchProvider, findFileViewerViewStateProvider, findFileViewerZoomProvider, registerFileViewerSearchProvider, registerFileViewerViewStateProvider, registerFileViewerZoomProvider, unregisterFileViewerSearchProvider, unregisterFileViewerViewStateProvider, unregisterFileViewerZoomProvider, } from './providers.js';
+export { DEFAULT_FILE_VIEWER_SCROLL_CONTAINER_CANDIDATE_SELECTOR, DEFAULT_FILE_VIEWER_SCROLL_CONTAINER_SELECTOR, DEFAULT_FILE_VIEWER_SCROLLABLE_OVERFLOW_VALUES, getFileViewerScrollableRange, isFileViewerScrollableElement, resolveFileViewerScrollContainer, } from './scroll.js';

package/dist/features/document/dom/providers.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerSearchProvider, FileViewerViewStateProvider, FileViewerZoomProvider } from "../../../contracts/types.js";
+import type { FileViewerSearchProvider, FileViewerViewStateProvider, FileViewerZoomProvider } from '../../../contracts/types.js';
 export interface FileViewerSearchProviderHost extends HTMLElement {
     __flyfishViewerSearchProvider?: FileViewerSearchProvider;
 }

package/dist/features/document/events.d.ts

@@ -1,5 +1,5 @@
-import { type FileViewerDomSearchControllerStateTarget } from "./search.js";
-import type { FileViewerAiOptions, FileViewerDocumentAnchor, FileViewerDocumentChunk, FileViewerSearchOptions, FileViewerSearchState } from "../../contracts/types.js";
+import { type FileViewerDomSearchControllerStateTarget } from './search.js';
+import type { FileViewerAiOptions, FileViewerDocumentAnchor, FileViewerDocumentChunk, FileViewerSearchOptions, FileViewerSearchState } from '../../contracts/types.js';
 export interface ResolveFileViewerLocationChangeAnchorInput {
     root: HTMLElement | null | undefined;
     anchors: FileViewerDocumentAnchor[];

package/dist/features/document/events.js

@@ -1,6 +1,6 @@
-import { buildFileViewerDocumentTextChunks } from "./model.js";
-import { getCurrentFileViewerDocumentAnchor, resolveFileViewerScrollContainer, scrollToFileViewerDocumentAnchor, } from "./dom/index.js";
-import { cloneFileViewerSearchState, createFileViewerDomSearchController, createFileViewerDomSearchControllerActionHandlers, } from "./search.js";
+import { buildFileViewerDocumentTextChunks } from './model.js';
+import { getCurrentFileViewerDocumentAnchor, resolveFileViewerScrollContainer, scrollToFileViewerDocumentAnchor, } from './dom/index.js';
+import { cloneFileViewerSearchState, createFileViewerDomSearchController, createFileViewerDomSearchControllerActionHandlers, } from './search.js';
 export const createFileViewerSearchChangeState = (state) => {
     return cloneFileViewerSearchState(state);
 };

package/dist/features/document/fit.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerFitMode, FileViewerFitOptions, FileViewerFitRequest, FileViewerFitResize, FileViewerFitResult, FileViewerViewState, FileViewerViewStateChangeSource } from "../../contracts/types.js";
+import type { FileViewerFitMode, FileViewerFitOptions, FileViewerFitRequest, FileViewerFitResize, FileViewerFitResult, FileViewerViewState, FileViewerViewStateChangeSource } from '../../contracts/types.js';
 export declare const FILE_VIEWER_FIT_MODES: readonly ["auto", "contain", "cover", "width", "height", "actual", "scale-down"];
 export declare const FILE_VIEWER_FIT_RESIZE_MODES: readonly ["until-interaction", "always", "initial"];
 export interface NormalizedFileViewerFitOptions extends Required<Pick<FileViewerFitOptions, 'mode' | 'resize' | 'padding'>> {

package/dist/features/document/fit.js

@@ -1,4 +1,4 @@
-import { findFileViewerViewStateProvider, findFileViewerZoomProvider, } from "./dom/index.js";
+import { findFileViewerViewStateProvider, findFileViewerZoomProvider, } from './dom/index.js';
 export const FILE_VIEWER_FIT_MODES = [
     'auto',
     'contain',

package/dist/features/document/imageHandTool.d.ts

@@ -1 +1,3 @@
+/** Optional mouse panning for image previews. Touch/pinch, keyboard activation,
+ * controls and native scrollbars retain their normal browser behavior. */
 export declare function installFileViewerImageHandTool(container: HTMLElement, signal?: AbortSignal): () => void;

package/dist/features/document/imageHandTool.js

@@ -1,3 +1,5 @@
+/** Optional mouse panning for image previews. Touch/pinch, keyboard activation,
+ * controls and native scrollbars retain their normal browser behavior. */
 export function installFileViewerImageHandTool(container, signal) {
     const view = container.ownerDocument.defaultView;
     if (!view || (signal === null || signal === void 0 ? void 0 : signal.aborted))
@@ -60,10 +62,12 @@ export function installFileViewerImageHandTool(container, signal) {
             container.setAttribute('data-viewer-image-panning', 'true');
             container.style.cursor = 'grabbing';
             container.style.setProperty('user-select', 'none');
+            // Delay capture until a drag starts so an ordinary click still reaches
+            // the image's lightbox handler instead of being retargeted to its parent.
             try {
                 (_a = container.setPointerCapture) === null || _a === void 0 ? void 0 : _a.call(container, event.pointerId);
             }
-            catch { }
+            catch { /* window listeners remain active */ }
         }
         container.scrollLeft = drag.left - dx;
         container.scrollTop = drag.top - dy;

package/dist/features/document/model.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerAiOptions, FileViewerDocumentAnchor, FileViewerDocumentChunk, FileViewerSearchOptions, FileViewerSearchState, FileViewerZoomState } from "../../contracts/types.js";
+import type { FileViewerAiOptions, FileViewerDocumentAnchor, FileViewerDocumentChunk, FileViewerSearchOptions, FileViewerSearchState, FileViewerZoomState } from '../../contracts/types.js';
 export declare const DEFAULT_FILE_VIEWER_ZOOM_SCALE = 1;
 export declare const DEFAULT_FILE_VIEWER_TEXT_CHUNK_SIZE = 1200;
 export declare const DEFAULT_FILE_VIEWER_TEXT_CHUNK_OVERLAP = 160;

package/dist/features/document/search.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerDocumentAnchor, FileViewerSearchMatch, FileViewerSearchOptions, FileViewerSearchState } from "../../contracts/types.js";
+import type { FileViewerDocumentAnchor, FileViewerSearchMatch, FileViewerSearchOptions, FileViewerSearchState } from '../../contracts/types.js';
 export interface CreateFileViewerDomSearchControllerOptions {
     root: () => HTMLElement | null | undefined;
     options?: () => boolean | FileViewerSearchOptions | undefined;

package/dist/features/document/search.js

@@ -1,5 +1,5 @@
-import { collectFileViewerDocumentAnchors, findFileViewerAnchorForElement, findFileViewerSearchProvider, } from "./dom/index.js";
-import { createEmptyFileViewerSearchState, normalizeFileViewerSearchOptions, } from "./model.js";
+import { collectFileViewerDocumentAnchors, findFileViewerAnchorForElement, findFileViewerSearchProvider, } from './dom/index.js';
+import { createEmptyFileViewerSearchState, normalizeFileViewerSearchOptions, } from './model.js';
 export const DEFAULT_FILE_VIEWER_SEARCH_MATCH_CLASS = 'flyfish-search-match';
 export const DEFAULT_FILE_VIEWER_SEARCH_ACTIVE_CLASS = 'flyfish-search-match--active';
 export const DEFAULT_FILE_VIEWER_SEARCH_MAX_MATCHES = 1000;

package/dist/features/document/viewState.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerApplyViewStateOptions, FileViewerViewState, FileViewerViewStateChange, FileViewerViewStateProvider } from "../../contracts/types.js";
+import type { FileViewerApplyViewStateOptions, FileViewerViewState, FileViewerViewStateChange, FileViewerViewStateProvider } from '../../contracts/types.js';
 export interface RegisterFileViewerGenericViewStateProviderOptions {
     host: HTMLElement;
     renderer?: string;

package/dist/features/document/viewState.js

@@ -1,5 +1,5 @@
-import { findFileViewerViewStateProvider, findFileViewerZoomProvider, registerFileViewerViewStateProvider, resolveFileViewerScrollContainer, unregisterFileViewerViewStateProvider, } from "./dom/index.js";
-import { resolveFileViewerFitScale } from "./fit.js";
+import { findFileViewerViewStateProvider, findFileViewerZoomProvider, registerFileViewerViewStateProvider, resolveFileViewerScrollContainer, unregisterFileViewerViewStateProvider, } from './dom/index.js';
+import { resolveFileViewerFitScale } from './fit.js';
 export const cloneFileViewerViewState = (state) => {
     if (!state) {
         return null;

package/dist/features/document/zoom.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerOptions, FileViewerOperationType, FileViewerZoomProvider, FileViewerZoomState } from "../../contracts/types.js";
+import type { FileViewerOptions, FileViewerOperationType, FileViewerZoomProvider, FileViewerZoomState } from '../../contracts/types.js';
 export type FileViewerZoomOperation = Extract<FileViewerOperationType, 'zoom-in' | 'zoom-out' | 'zoom-reset'>;
 export interface CreateFileViewerZoomControllerOptions {
     root: () => HTMLElement | null | undefined;

package/dist/features/document/zoom.js

@@ -1,6 +1,6 @@
-import { createFileViewerZoomState } from "./model.js";
-import { findFileViewerZoomProvider } from "./dom/index.js";
-import { installFileViewerZoomGestures } from "./zoomGestures.js";
+import { createFileViewerZoomState } from './model.js';
+import { findFileViewerZoomProvider } from './dom/index.js';
+import { installFileViewerZoomGestures } from './zoomGestures.js';
 export const cloneFileViewerZoomState = (state) => ({
     scale: state.scale,
     label: state.label,

package/dist/features/document/zoomGestures.d.ts

@@ -1,5 +1,5 @@
-import type { FileViewerOptions, FileViewerZoomProvider } from "../../contracts/types.js";
-import type { FileViewerZoomOperation } from "./zoom.js";
+import type { FileViewerOptions, FileViewerZoomProvider } from '../../contracts/types.js';
+import type { FileViewerZoomOperation } from './zoom.js';
 interface ZoomGestureOptions {
     provider: () => FileViewerZoomProvider | null;
     enabled: () => boolean;

package/dist/features/document/zoomGestures.js

@@ -43,6 +43,8 @@ export function installFileViewerZoomGestures(container, options) {
                 options.onZoom();
         }
         catch {
+            // Operation hooks report their errors. Native events have no caller to
+            // receive a rejected promise, so do not leak an unhandled rejection.
         }
         finally {
             busy = false;

package/dist/features/printMask.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerPrintMaskOptions, FileViewerPrintMaskRegion, FileViewerPrintStamp } from "../contracts/types.js";
+import type { FileViewerPrintMaskOptions, FileViewerPrintMaskRegion, FileViewerPrintStamp } from '../contracts/types.js';
 export declare const normalizeFileViewerPrintMaskRegion: (region: Partial<FileViewerPrintMaskRegion> | null | undefined) => FileViewerPrintMaskRegion | null;
 export declare const normalizeFileViewerPrintStamp: (stamp: Partial<FileViewerPrintStamp> | null | undefined) => FileViewerPrintStamp | null;
 export declare const normalizeFileViewerPrintMaskOptions: (mask?: FileViewerPrintMaskOptions | null) => FileViewerPrintMaskOptions | null;

package/dist/features/printMaskDesigner.d.ts

@@ -1,5 +1,5 @@
-import type { FileViewerPrintMaskOptions, FileViewerPrintMaskRegion, FileViewerPrintStamp } from "../contracts/types.js";
-import { type FileViewerI18nInput } from "../i18n/messages.js";
+import type { FileViewerPrintMaskOptions, FileViewerPrintMaskRegion, FileViewerPrintStamp } from '../contracts/types.js';
+import { type FileViewerI18nInput } from '../i18n/messages.js';
 export interface OpenFileViewerPrintMaskDesignerOptions {
     root: HTMLElement;
     pages?: readonly HTMLElement[];
@@ -11,4 +11,8 @@ export interface OpenFileViewerPrintMaskDesignerOptions {
 export interface FileViewerPrintMaskDesignerResult {
     mask: FileViewerPrintMaskOptions;
 }
+/**
+ * Opens a page-aware print-mask designer. Browsing remains the default mode;
+ * drawing is armed for the currently visible page only and disarms after one block.
+ */
 export declare const openFileViewerPrintMaskDesigner: (options: OpenFileViewerPrintMaskDesignerOptions) => Promise<FileViewerPrintMaskDesignerResult | null>;

package/dist/features/printMaskDesigner.js

@@ -1,5 +1,5 @@
-import { createFileViewerTranslator } from "../i18n/messages.js";
-import { normalizeFileViewerPrintMaskRegion, normalizeFileViewerPrintStamp, } from "./printMask.js";
+import { createFileViewerTranslator } from '../i18n/messages.js';
+import { normalizeFileViewerPrintMaskRegion, normalizeFileViewerPrintStamp, } from './printMask.js';
 const DESIGNER_STYLE = `
 .fv-print-mask-layer{position:absolute;inset:0;z-index:2147483000;pointer-events:none;}
 .fv-print-mask-canvas{position:absolute;inset:0;z-index:2147483000;pointer-events:none;cursor:default;}
@@ -74,6 +74,10 @@ const readStampFileAsDataUrl = (file, windowRef) => new Promise((resolve, reject
     reader.addEventListener('error', () => reject(reader.error || new Error('Failed to read print stamp image')));
     reader.readAsDataURL(file);
 });
+/**
+ * Opens a page-aware print-mask designer. Browsing remains the default mode;
+ * drawing is armed for the currently visible page only and disarms after one block.
+ */
 export const openFileViewerPrintMaskDesigner = (options) => {
     const root = options.root;
     const documentRef = root.ownerDocument;
@@ -101,6 +105,8 @@ export const openFileViewerPrintMaskDesigner = (options) => {
         }
         return previousPosition;
     };
+    // The toolbar layer is positioned against the viewer root even when page
+    // canvases live on child page elements.
     const previousRootPosition = ensureOverlayContainingBlock(root);
     return new Promise(resolve => {
         let settled = false;
@@ -310,6 +316,7 @@ export const openFileViewerPrintMaskDesigner = (options) => {
                         (_a = stampElement.releasePointerCapture) === null || _a === void 0 ? void 0 : _a.call(stampElement, interaction.pointerId);
                     }
                     catch {
+                        // Pointer capture may already be released by the browser.
                     }
                     interaction = null;
                 };
@@ -364,6 +371,7 @@ export const openFileViewerPrintMaskDesigner = (options) => {
                     surface.canvas.releasePointerCapture(drawing.pointerId);
                 }
                 catch {
+                    // Pointer capture may already be released by the browser.
                 }
                 drawing = null;
                 disarm();
@@ -427,6 +435,7 @@ export const openFileViewerPrintMaskDesigner = (options) => {
                 }
             }
             catch {
+                // Unsupported or unreadable images are ignored; the document stays untouched.
             }
         });
         clearButton.addEventListener('click', () => {

package/dist/features/printMaskLoader.d.ts

@@ -1,2 +1,8 @@
-import type { FileViewerPrintMaskDesignerResult, OpenFileViewerPrintMaskDesignerOptions } from "./printMaskDesigner.js";
+import type { FileViewerPrintMaskDesignerResult, OpenFileViewerPrintMaskDesignerOptions } from './printMaskDesigner.js';
+/**
+ * Lazily opens the print-mask designer.
+ * Kept as a dynamic import so the designer stays out of the main core graph,
+ * while remaining reachable through the primary `@file-viewer/core` entry
+ * (no consumer alias / subpath setup required).
+ */
 export declare const openFileViewerPrintMaskDesignerAsync: (options: OpenFileViewerPrintMaskDesignerOptions) => Promise<FileViewerPrintMaskDesignerResult | null>;

package/dist/features/printMaskLoader.js

@@ -1,4 +1,10 @@
+/**
+ * Lazily opens the print-mask designer.
+ * Kept as a dynamic import so the designer stays out of the main core graph,
+ * while remaining reachable through the primary `@file-viewer/core` entry
+ * (no consumer alias / subpath setup required).
+ */
 export const openFileViewerPrintMaskDesignerAsync = async (options) => {
-    const { openFileViewerPrintMaskDesigner } = await import("../print-mask.js");
+    const { openFileViewerPrintMaskDesigner } = await import('../print-mask.js');
     return openFileViewerPrintMaskDesigner(options);
 };

package/dist/features/watermark.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerWatermarkOptions } from "../contracts/types.js";
+import type { FileViewerWatermarkOptions } from '../contracts/types.js';
 export type FileViewerWatermarkStyle = Record<string, string> & {
     backgroundImage: string;
 };