@file-viewer/core 3.2.2 → 3.3.1

package/dist/contracts/types.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerXmlOptions } from "./xml.js";
+import type { FileViewerXmlOptions } from './xml.js';
 export type FileViewerSourceKind = 'file' | 'url' | 'buffer' | 'empty';
 export type FileViewerThemeMode = 'light' | 'dark' | 'system';
 export type FileViewerResolvedThemeMode = Exclude<FileViewerThemeMode, 'system'>;
@@ -50,9 +50,13 @@ export interface FileViewerToolbarOptions {
     exportHtml?: boolean;
     zoom?: boolean;
     search?: boolean;
+    /** Shows a manual light/dark mode toggle without changing the host page theme. */
     theme?: boolean;
+    /** Built-in toolbar group order. Missing entries keep their default relative order. */
     order?: FileViewerToolbarItem[];
+    /** Controls which built-in toolbar actions are displayed without disabling controller APIs. */
     items?: FileViewerToolbarActionMap;
+    /** Hard operation permission map. False values block both built-in toolbar and public API calls. */
     permissions?: FileViewerToolbarActionMap;
     position?: FileViewerToolbarPosition;
     beforeOperation?: FileViewerBeforeOperation;
@@ -71,6 +75,10 @@ export interface FileViewerArchiveEntryActionContext {
 }
 export type FileViewerArchiveEntryActionPolicy = boolean | ((entry: FileViewerArchiveEntryActionContext) => boolean);
 export interface FileViewerArchiveEntryActionsOptions {
+    /**
+     * Controls the download button for files opened from inside an archive.
+     * The viewer-level original-file download remains controlled by toolbar options.
+     */
     download?: FileViewerArchiveEntryActionPolicy;
 }
 export interface FileViewerArchiveOptions {
@@ -78,23 +86,53 @@ export interface FileViewerArchiveOptions {
     wasmUrl?: string;
     workerTimeoutMs?: number;
     cache?: boolean;
+    /**
+     * Maximum input bytes, and maximum expanded TAR/GZIP bytes in the workerless
+     * fallback (including TAR headers and padding). Defaults to 320 MiB.
+     * Must be a non-negative safe integer; zero permits only empty data.
+     */
     maxArchiveSize?: number;
+    /**
+     * Maximum selected entry preview bytes. Defaults to 64 MiB. Also bounds
+     * single-file GZIP expansion during fallback listing; TAR/TGZ members are
+     * checked when selected. Must be a non-negative safe integer.
+     */
     maxEntryPreviewSize?: number;
     entryActions?: FileViewerArchiveEntryActionsOptions;
+    /**
+     * Optional archive password. It is used for the first encrypted archive
+     * attempt; if it is wrong, the built-in password dialog or requestPassword
+     * callback can still ask the user for a replacement.
+     */
     password?: string;
+    /**
+     * Custom password request hook for encrypted archives. Return a string to
+     * continue, or null/undefined to cancel and surface a friendly error.
+     */
     requestPassword?: (context: FileViewerArchivePasswordRequestContext) => string | null | undefined | Promise<string | null | undefined>;
 }
 export interface FileViewerChmOptions {
+    /** Self-hosted module Worker that owns all untrusted CHM parsing and decompression. */
     workerUrl?: string | URL;
+    /** Self-hosted wasm-bindgen JavaScript module loaded by the CHM Worker. */
     wasmModuleUrl?: string | URL;
+    /** Self-hosted Rust WebAssembly binary loaded by the CHM Worker. */
     wasmUrl?: string | URL;
+    /** Maximum time for an individual Worker request. Defaults to 60 seconds. */
     workerTimeoutMs?: number;
+    /** Maximum accepted CHM input size. Defaults to 320 MiB. */
     maxArchiveBytes?: number;
+    /** Maximum number of virtual files accepted from one CHM. Defaults to 50,000. */
     maxEntries?: number;
+    /** Maximum uncompressed size of one virtual file. Defaults to 32 MiB. */
     maxEntryBytes?: number;
+    /** Maximum total unique decoded content exposed by the parser. Defaults to 512 MiB. */
     maxTotalDecompressedBytes?: number;
+    /** Maximum HTML topic size. Defaults to 16 MiB. */
     maxHtmlBytes?: number;
+    /** Maximum topic count scanned by the built-in search. Defaults to 10,000. */
     maxSearchTopics?: number;
+    /** Maximum built-in search result count. Defaults to 200. */
     maxSearchResults?: number;
 }
 export type FileViewerArchivePasswordRequestReason = 'encrypted' | 'invalid-password' | 'read-failed' | 'extract-failed';
@@ -106,49 +144,99 @@ export interface FileViewerArchivePasswordRequestContext {
     error?: unknown;
 }
 export interface FileViewerPdfOptions {
+    /** Preview-only dark reading palette; follows the viewer theme when omitted. */
+    darkMode?: boolean;
+    /** Opt-in mouse hand-tool panning. Touch/pinch, links and form fields remain native. Default: false. */
     handTool?: boolean;
     toolbar?: boolean;
+    /** Hides only the PDF renderer's zoom controls; navigation and rotation remain available. Default: true. */
+    zoomToolbar?: boolean;
     navigation?: boolean;
     defaultNavigationVisible?: boolean;
     thumbnails?: boolean;
     rotation?: number;
+    /**
+     * Highlights and focuses one or more PDF regions after the document loads.
+     * Use `pixel` with `sourceWidth` / `sourceHeight` for OCR coordinates, or
+     * `pdf-point` for native PDF coordinates. Page numbers are one-based.
+     */
     bbox?: FileViewerPdfBoundingBox | readonly FileViewerPdfBoundingBox[];
+    /**
+     * Initial PDF view position. Prefer the top-level `initialViewState` when the
+     * same state should be passed through framework-neutral viewer APIs.
+     */
     initialViewState?: FileViewerViewState;
     streaming?: boolean | 'same-origin';
+    /** Opt out of PDF.js background streaming while retaining HTTP Range reads. Default: PDF.js defaults. */
+    disableStream?: boolean;
+    /** Stop speculative PDF.js reads; requires disableStream:true to be fully effective. */
+    disableAutoFetch?: boolean;
     rangeChunkSize?: number;
     withCredentials?: boolean;
+    /**
+     * Base URL for the self-hosted PDF worker, cMaps, WASM, standard fonts, and
+     * CJK fallback fonts. Useful for SPA routes whose document URL is deeper
+     * than the deployment public path, for example `/workspace/c/`.
+     */
     assetBaseUrl?: string | URL;
     workerUrl?: string;
     cMapUrl?: string;
     wasmUrl?: string;
     standardFontDataUrl?: string;
+    /**
+     * Enables the self-hosted CJK fallback used when a PDF references a font
+     * such as Microsoft YaHei without embedding the font data. Defaults to true.
+     */
     cjkFontFallback?: boolean;
+    /**
+     * Repairs malformed Identity-H/V CJK fonts that omit ToUnicode when the PDF
+     * also embeds a usable same-family TrueType cmap. Defaults to true. The
+     * repair is applied only to the in-memory preview and never changes the
+     * original file used by download operations.
+     */
     identityFontRepair?: boolean;
+    /**
+     * Directory containing `noto-sans-sc.css`, its `files/` font shards, and
+     * the bundled font license. The path is resolved against the document base.
+     */
     cjkFontFallbackPath?: string;
 }
 export type FileViewerPdfBoundingBoxUnit = 'ratio' | 'percent' | 'pixel' | 'pdf-point';
 export type FileViewerPdfBoundingBoxOrigin = 'top-left' | 'bottom-left';
 export interface FileViewerPdfBoundingBox {
     id?: string;
+    /** One-based PDF page number. Defaults to the current page, then page 1. */
     page?: number;
     x: number;
     y: number;
     width: number;
     height: number;
+    /** Defaults to `pdf-point`. */
     unit?: FileViewerPdfBoundingBoxUnit;
+    /** Defaults to `bottom-left` for PDF points and `top-left` otherwise. */
     origin?: FileViewerPdfBoundingBoxOrigin;
+    /** Required when `unit` is `pixel`; this is the OCR/source image width. */
     sourceWidth?: number;
+    /** Required when `unit` is `pixel`; this is the OCR/source image height. */
     sourceHeight?: number;
+    /** CSS color used for the outline and translucent fill. */
     color?: string;
+    /** Optional accessible description for the highlighted region. */
     label?: string;
 }
 export interface FileViewerDocxOptions {
+    /**
+     * 输出源部件与段落的只读定位标识，供独立展示适配器使用；默认关闭。
+     * 不提供编辑或文件写回能力，重新渲染后的展示状态由适配器维护。
+     */
     exposeDisplayTargets?: boolean;
+    /** DOC/DOCX 默认保留插入和删除修订；final 显示定稿，original 显示修订前原稿。 */
     reviewMode?: 'all' | 'final' | 'original';
     worker?: boolean;
     workerUrl?: string;
     workerJsZipUrl?: string;
     progressive?: boolean;
+    /** 默认 false，使用连续流式阅读；设为 true 时才启用 DOCX 页式预览。 */
     visualPagination?: boolean;
     workerTimeout?: number;
     renderPageBatchSize?: number;
@@ -161,27 +249,49 @@ export interface FileViewerDocxOptions {
     updatePageReferences?: boolean;
     hideWebHiddenContent?: boolean;
     ignoreLastRenderedPageBreak?: boolean;
+    /** Set false to omit embedded HTML altChunks. Omitted/true retains the engine sandbox. */
     renderAltChunks?: boolean;
+    /** External DOC/DOCX/RTF links are blocked by default; internal bookmark links remain active. */
     externalLinkPolicy?: 'allow' | 'block';
+    /** Linked DOC/DOCX/RTF image resources are blocked by default; embedded images remain available. */
     externalResourcePolicy?: 'allow' | 'block';
+    /** Overrides automatic DOCX dark rendering derived from the viewer theme. */
+    darkMode?: boolean;
+}
+export interface FileViewerEpubOptions {
+    /** Follows the viewer theme when omitted; false retains the book's authored colors. */
     darkMode?: boolean;
 }
 export interface FileViewerSpreadsheetOptions {
     worker?: boolean | 'auto';
     workerUrl?: string;
+    /** `worker: 'auto'` 时，大于该字节数的表格自动使用静态 Worker，默认 1MB。 */
     workerAutoThreshold?: number;
+    /**
+     * CSV / TSV 文本编码。默认 `auto`：优先 UTF-8 BOM 和严格 UTF-8，
+     * 否则使用浏览器内置 GB18030 解码器（同时覆盖 GBK）。
+     */
     textEncoding?: 'auto' | 'utf-8' | 'gbk' | 'gb18030';
+    /** 允许用户在 Excel / CSV / ODS 预览中拖拽表头边界调整列宽，默认关闭以保持历史行为。 */
     resizableColumns?: boolean;
+    /** 允许用户在 Excel / CSV / ODS 预览中拖拽行头边界调整行高，默认关闭以保持历史行为。 */
     resizableRows?: boolean;
+    /** Fill spreadsheet previews with display-only blank grid cells by default; false keeps the used range only. */
     fillViewport?: boolean;
 }
 export interface FileViewerPresentationOptions {
+    /** PPTX/OpenXML Worker URL. This is independent from the binary-PPT Worker. */
     workerUrl?: string | URL;
     workerType?: WorkerType;
+    /** Optional self-hosted native WASM URL used only by the PowerPoint 97–2003 renderer. */
     pptWasmUrl?: string | URL;
+    /** Optional self-hosted CJK font-pack URL used only by the PowerPoint 97–2003 renderer. */
     pptFontUrl?: string | URL;
+    /** Optional module Worker URL used only by the PowerPoint 97–2003 renderer. */
     pptWorkerUrl?: string | URL;
+    /** Selects the binary-PPT Worker path. Defaults to `auto`. */
     pptWorker?: boolean | 'auto';
+    /** Controls the binary-PPT bounded IndexedDB frame cache. */
     pptCache?: false | {
         enabled?: boolean;
         dbName?: string;
@@ -189,36 +299,63 @@ export interface FileViewerPresentationOptions {
         maxEntries?: number;
         maxEntryBytes?: number;
     };
+    /** Render and retain only binary-PPT slides near the viewport. Defaults to true. */
     pptVirtualize?: boolean;
+    /** IntersectionObserver overscan for binary-PPT virtualization. Defaults to `150% 0px`. */
     pptVirtualRootMargin?: string;
+    /** Delay before an offscreen binary-PPT canvas is cached and released. Defaults to 1200ms. */
     pptReleaseDelayMs?: number;
+    /**
+     * Optional ESM entry override for `@file-viewer/ppt`.
+     * Full packages and the CDN/IIFE distribution provide a packaged default.
+     */
     pptModuleUrl?: string | URL;
 }
 export type FileViewerIworkEmbeddedPreviewMode = 'never' | 'loading' | 'fallback';
 export interface FileViewerIworkOptions {
+    /** Self-hosted module Worker used for ZIP, Snappy, IWA/Protobuf and iWork '09 XML parsing. */
     workerUrl?: string | URL;
+    /** Defaults to true. Disable only in environments without Worker support. */
     useWorker?: boolean;
+    /** Maximum parse time before the Worker is terminated. Defaults to 60 seconds. */
     workerTimeoutMs?: number;
+    /** Maximum total bytes produced while inflating the outer container and Index.zip. Defaults to 256 MiB. */
     maxUncompressedBytes?: number;
+    /** Maximum accepted ZIP compression ratio for a single entry. Defaults to 200. */
     maxCompressionRatio?: number;
+    /** Maximum decoded IWA archive/object count. Defaults to 250,000. */
     maxObjects?: number;
+    /** Maximum decoded image pixels for one media resource. Defaults to 80 megapixels. */
     maxImagePixels?: number;
+    /** Maximum normalized scene/object nesting depth. Defaults to 128. */
     maxNestingDepth?: number;
+    /** Embedded Quick Look images are loading placeholders or explicit parse-failure fallbacks, never fidelity evidence. */
     embeddedPreview?: FileViewerIworkEmbeddedPreviewMode;
 }
 export interface FileViewerWordPerfectOptions {
+    /** Self-hosted Worker that owns WordPerfect signature detection and parsing. */
     workerUrl?: string | URL;
+    /** Self-hosted libwpd/librevenge WebAssembly module. */
     wasmUrl?: string | URL;
+    /** Defaults to true. */
     useWorker?: boolean;
+    /** Maximum parser time before the Worker is terminated. Defaults to 60 seconds. */
     workerTimeoutMs?: number;
 }
 export interface FileViewerHangulOptions {
+    /** Self-hosted module Worker used for bounded HWP v5 CFB and HWPX ZIP/XML parsing. */
     workerUrl?: string | URL;
+    /** Defaults to true. Disable only in environments without Worker support. */
     useWorker?: boolean;
+    /** Maximum parser time before the Worker is terminated. Defaults to 60 seconds. */
     workerTimeoutMs?: number;
+    /** Maximum total uncompressed HWPX entry bytes or individual HWP stream bytes. Defaults to 256 MiB. */
     maxUncompressedBytes?: number;
+    /** Maximum accepted HWPX ZIP compression ratio for a single entry. Defaults to 200. */
     maxCompressionRatio?: number;
+    /** Maximum HWPX ZIP entry count. Defaults to 25,000. */
     maxEntries?: number;
+    /** Maximum HWP record count decoded across one stream. Defaults to 250,000. */
     maxRecords?: number;
 }
 export type FileRenderExportMode = 'export' | 'print';
@@ -235,9 +372,13 @@ export interface FileViewerThumbnailCaptureOptions {
     signal?: AbortSignal;
 }
 export interface FileRenderThumbnailAdapter {
+    /** Prepare lazy content immediately before capture. */
     beforeCapture?: (options: FileViewerThumbnailCaptureOptions) => void | Promise<void>;
+    /** Identifies a capture result that comes from packaged metadata rather than rendered content. */
     captureSource?: 'embedded' | 'rendered';
+    /** A renderer-native fast path. Returning null delegates to the DOM fallback. */
     capture?: (options: FileViewerThumbnailCaptureOptions) => Blob | null | Promise<Blob | null>;
+    /** The first page/slide/sheet/cover element used by the DOM fallback. */
     getTarget?: (options: FileViewerThumbnailCaptureOptions) => Element | null | Promise<Element | null>;
 }
 export interface FileRenderExportOptions {
@@ -249,6 +390,7 @@ export interface FileRenderExportAdapter {
     exportHtml?: boolean;
     includeDocumentStyles?: boolean;
     beforeSnapshot?: () => Promise<void> | void;
+    /** Live page surfaces used by the interactive print-mask designer. */
     getPrintMaskPages?: () => readonly HTMLElement[];
     printStyle?: string | ((options: FileRenderExportOptions) => Promise<string> | string);
     toHtml?: (options: FileRenderExportOptions) => Promise<string> | string;
@@ -257,6 +399,7 @@ export interface FileRenderContext {
     filename?: string;
     url?: string;
     streamUrl?: string;
+    /** Original browser File or Blob retained for renderers with random access. */
     sourceFile?: File | Blob;
     signal?: AbortSignal;
     options?: FileViewerOptions;
@@ -264,6 +407,7 @@ export interface FileRenderContext {
     registerExportAdapter?: (adapter: FileRenderExportAdapter | null) => void;
     registerThumbnailAdapter?: (adapter: FileRenderThumbnailAdapter | null) => void;
     renderPurpose?: FileViewerRenderPurpose;
+    /** Derived-image download, guarded by the owning viewer's permissions, hooks and request version. */
     requestSnapshotDownload?: (create: (watermark: FileViewerOptions['watermark']) => Promise<{
         blob: Blob;
         filename: string;
@@ -276,6 +420,13 @@ export interface FileRenderHandlerComposite<Rendered = unknown, Target extends H
     accepts: Array<string>;
     handler: FileRenderHandler<Rendered, Target>;
 }
+/**
+ * Framework-neutral instance returned by a renderer after it mounts content.
+ *
+ * Vue, React legacy, Web Components or imperative renderers may expose different
+ * teardown names, but wrappers can share this single contract when bridging old
+ * renderer handlers into the core registry.
+ */
 export type FileViewerRenderedInstance = {
     $el?: Node;
     unmount: () => void | Promise<void>;
@@ -294,10 +445,15 @@ export interface FileViewerTypstOptions {
 }
 export type FileViewerModelLinearUnit = 'millimeter' | 'centimeter' | 'meter' | 'inch' | 'foot';
 export interface FileViewerModelOptions {
+    /** Self-hosted worker that keeps STEP/IGES/BREP tessellation off the UI thread. */
     workerUrl?: string;
+    /** Self-hosted occt-import-js runtime loaded by the classic worker. */
     runtimeUrl?: string;
+    /** Self-hosted OpenCascade WebAssembly module used by the model renderer. */
     wasmUrl?: string;
+    /** Disable only when Worker is unavailable or a host deliberately accepts main-thread parsing. */
     useWorker?: boolean;
+    /** Maximum time allowed for geometry-kernel initialization and tessellation. Defaults to 120 seconds. */
     workerTimeoutMs?: number;
     linearUnit?: FileViewerModelLinearUnit;
     linearDeflectionType?: 'bounding_box_ratio' | 'absolute_value';
@@ -307,14 +463,21 @@ export interface FileViewerModelOptions {
 export interface FileViewerDataOptions {
     sqlWasmUrl?: string;
 }
+/** Limits for the explicit, read-only binary inspector renderer. */
 export interface FileViewerBinaryInspectorOptions {
+    /** Whole-input ceiling before the renderer copies bytes into its Worker. Defaults to 16 MiB. */
     maxFileBytes?: number;
+    /** Maximum time allowed for one structure-template pass. Defaults to 5 seconds. */
     maxParseMilliseconds?: number;
+    /** Maximum structure nodes returned from the Worker. Defaults to 512. */
     maxStructureNodes?: number;
+    /** Maximum structure-tree nesting depth. Defaults to 16. */
     maxStructureDepth?: number;
+    /** Maximum decoded string bytes in one displayed field. Defaults to 4 KiB. */
     maxStringBytes?: number;
 }
 export type FileViewerIllustratorMode = 'auto' | 'pdf' | 'native';
+/** Resource budgets forwarded to the standalone illustrator-pgf Worker. */
 export interface FileViewerIllustratorLimits {
     maxFileBytes: number;
     maxDecodedBytes: number;
@@ -352,45 +515,85 @@ export interface FileViewerIllustratorResourceResolver {
     resolve(reference: FileViewerIllustratorResourceReference, signal: AbortSignal): Promise<ArrayBuffer | null>;
 }
 export interface FileViewerDesignOptions {
+    /** Illustrator routing: PDF-compatible surface, native PGF scene, or safe automatic fallback. */
     illustratorMode?: FileViewerIllustratorMode;
+    /** Self-hosted module Worker that runs the standalone illustrator-pgf parser and renderer. */
     illustratorWorkerUrl?: string | URL;
+    /** Resource budgets forwarded to illustrator-pgf. Defaults to the SDK's bounded limits. */
     illustratorLimits?: Partial<FileViewerIllustratorLimits>;
+    /** Optional host font resolver used only by the native Illustrator session. */
     illustratorFontResolver?: FileViewerIllustratorFontResolver;
+    /** Optional host linked/embedded resource resolver used only by the native Illustrator session. */
     illustratorResourceResolver?: FileViewerIllustratorResourceResolver;
+    /** Self-hosted module Worker used for heavy Adobe document parsing and pixel synthesis. */
     workerUrl?: string | URL;
+    /** Self-hosted module Worker used for bounded FLA/XFL, XD, INDD/INDT, ICML/IDMS/INX, ASE, and ACO parsing. */
     containerWorkerUrl?: string | URL;
+    /** Self-hosted module Worker used for ABR/CSH/PAT/GRD/ASL resource parsing. */
     adobeResourceWorkerUrl?: string | URL;
+    /** Self-hosted module Worker that runs the bounded EPS/PostScript interpreter. */
     postscriptWorkerUrl?: string | URL;
+    /** Self-hosted, license-safe Stet WebAssembly binary used only inside the PostScript Worker. */
     postscriptWasmUrl?: string | URL;
+    /** Defaults to true. Disable only when Worker is unavailable. */
     useWorker?: boolean;
+    /** Maximum parser time before the Worker is terminated. Defaults to 60 seconds. */
     workerTimeoutMs?: number;
+    /** Base EPS/PostScript rasterization density. Defaults to 96 DPI. */
     postscriptRenderDpi?: number;
+    /** Maximum pages produced by one EPS/PostScript program. Defaults to 100. */
     postscriptMaxPages?: number;
+    /** Maximum source width or height reported by a PostScript page. Defaults to 100,000 units. */
     postscriptMaxSourceDimension?: number;
+    /** Maximum PostScript virtual-machine allocation. Defaults to 256 MiB. */
     postscriptMaxVmBytes?: number;
+    /** Maximum PostScript print working set across visible, cached, transient, and print RGBA canvases. Defaults to 128 MiB. */
     postscriptMaxPrintBytes?: number;
+    /** Self-hosted module Worker used by the high-fidelity IDML page renderer. */
     idmlWorkerUrl?: string | URL;
+    /** Self-hosted @paged-media/introspect-wasm binary used only inside the IDML Worker. */
     idmlWasmUrl?: string | URL;
+    /** Base rasterization density for IDML pages. Defaults to 96 DPI. */
     idmlRenderDpi?: number;
+    /** Maximum IDML ZIP entry count. Defaults to 20,000. */
     idmlMaxEntries?: number;
+    /** Maximum total expanded bytes declared by an IDML package. Defaults to 512 MiB. */
     idmlMaxExpandedBytes?: number;
+    /** Maximum IDML page count exposed by the renderer. Defaults to 500. */
     idmlMaxPages?: number;
+    /** Maximum frame count exposed by the IDML page tree. Defaults to 100,000. */
     idmlMaxFrames?: number;
+    /** Maximum IDML print working set across visible, cached, transient, and print RGBA canvases. Defaults to 128 MiB. */
     idmlMaxPrintBytes?: number;
+    /** Maximum structured result returned for ICML/IDMS/INX parsing. Defaults to 24 MiB and is hard-capped at 64 MiB. */
     indesignExchangeMaxResultBytes?: number;
+    /** Maximum geometry points retained for one ICML/IDMS/INX page item. Defaults to 4,096 and is hard-capped at 16,384. */
     indesignExchangeMaxPointsPerItem?: number;
+    /** Maximum DOM/SVG nodes materialized for one active ICML/IDMS/INX panel. Defaults to 8,000 and is hard-capped at 20,000. */
     indesignExchangeMaxDomNodesPerPanel?: number;
+    /** Maximum accepted Photoshop source size. Defaults to 128 MiB. */
     maxFileBytes?: number;
+    /** Maximum document canvas area. Defaults to 16 megapixels. */
     maxCanvasPixels?: number;
+    /** Maximum width or height accepted for a browser canvas. Defaults to 16,384 pixels. */
     maxCanvasDimension?: number;
+    /** Maximum decoded layer count. Defaults to 2,000. */
     maxLayers?: number;
+    /** Maximum group nesting depth. Defaults to 64. */
     maxNestingDepth?: number;
+    /** Maximum area decoded for one interactive layer. Defaults to 16 megapixels. */
     maxLayerPixels?: number;
+    /** Maximum transferred RGBA bytes for one result. Defaults to 128 MiB. */
     maxDecodedBytes?: number;
+    /** Maximum retained interactive layer canvas bytes. Defaults to 64 MiB. */
     maxLayerCacheBytes?: number;
+    /** Maximum colors, brushes, shapes, pages, or other resource records. Defaults to 4,096. */
     maxResourceItems?: number;
+    /** Maximum UTF-16 code units accepted for one resource name. Defaults to 4,096. */
     maxResourceNameCodeUnits?: number;
+    /** Maximum total pixels decoded for one resource preview collection. Defaults to 16 megapixels. */
     maxResourcePreviewPixels?: number;
+    /** Safety and inventory limits for XD UCF/ZIP containers and saved raster previews. */
     xd?: {
         maxFileBytes?: number;
         maxEntries?: number;
@@ -416,6 +619,7 @@ export interface FileViewerDesignOptions {
         maxReportedResources?: number;
         maxReportedArtboards?: number;
     };
+    /** Safety and bounded first-frame reconstruction limits for modern ZIP/XFL-based Animate FLA files. */
     fla?: {
         maxFileBytes?: number;
         maxEntries?: number;
@@ -448,6 +652,7 @@ export interface FileViewerDesignOptions {
         maxPreviewPixels?: number;
         maxSymbolDepth?: number;
     };
+    /** Safety limits for native INDD/INDT master-page, contiguous-object, XMP, and thumbnail reads. */
     inDesign?: {
         maxFileBytes?: number;
         maxDatabasePages?: number;
@@ -463,10 +668,29 @@ export interface FileViewerDesignOptions {
 export type FileViewerGeoBasemapPreset = 'none' | 'offline' | 'openfreemap' | 'openfreemap-liberty' | 'openfreemap-bright' | 'openfreemap-positron' | 'openfreemap-dark' | 'openfreemap-fiord' | 'osm-raster' | 'tianditu-vector' | 'tianditu-imagery' | 'tianditu-terrain';
 export type FileViewerTiandituMapStyle = 'vector' | 'imagery' | 'terrain';
 export interface FileViewerGeoBasemapOptions {
+    /**
+     * `raster` uses XYZ/TMS image tiles. `vector-style` uses a MapLibre style
+     * object or URL, which is the best path for OpenFreeMap/OpenMapTiles stacks.
+     * `tianditu` builds the official base and annotation raster layers from the
+     * caller-provided Tianditu token.
+     */
     type?: 'raster' | 'vector-style' | 'tianditu';
+    /**
+     * Raster XYZ/TMS tile template, for example `/tiles/{z}/{x}/{y}.png`.
+     */
     tileUrl?: string | string[];
+    /**
+     * MapLibre style JSON URL. Can point to a public source, an intranet mirror,
+     * or an offline static file distributed with the viewer.
+     */
     styleUrl?: string;
+    /**
+     * Inline MapLibre style object for fully offline deployments.
+     */
     style?: Record<string, unknown>;
+    /**
+     * Human-readable label shown in the geo preview details panel.
+     */
     label?: string;
     attribution?: string;
     tileSize?: number;
@@ -474,23 +698,86 @@ export interface FileViewerGeoBasemapOptions {
     maxZoom?: number;
     scheme?: 'xyz' | 'tms';
     rasterOpacity?: number;
+    /** Tianditu API token. Required when `type` is `tianditu`. */
     token?: string;
+    /** Tianditu map family. Defaults to `vector`. */
     mapStyle?: FileViewerTiandituMapStyle;
+    /** Include the matching Tianditu annotation layer. Defaults to true. */
     labels?: boolean;
 }
 export interface FileViewerGeoOptions {
+    /**
+     * Source coordinate reference system. GeoJSON normally uses WGS84, but many
+     * business exports carry Web Mercator, GCJ-02, BD-09, or legacy CRS metadata.
+     *
+     * Accepts values such as `EPSG:4326`, `EPSG:3857`, `CRS:84`, `GCJ02`,
+     * `BD09`, or a proj4 definition string.
+     */
     projection?: string;
+    /**
+     * Convenience raster tile URL. The renderer stays offline by default; setting
+     * this property opts into a raster basemap without requiring a full MapLibre
+     * style. Use `basemap` when you need a named preset or vector style URL.
+     */
     tileUrl?: string | string[];
+    /**
+     * Basemap configuration. Defaults to an offline empty MapLibre style.
+     *
+     * Built-in presets are opt-in: `openfreemap-liberty` uses the public
+     * OpenFreeMap MapLibre style, and `osm-raster` uses the public OSM raster
+     * tiles for light usage or demos. Production systems should prefer a
+     * self-hosted or intranet style/tile URL.
+     */
     basemap?: false | FileViewerGeoBasemapPreset | FileViewerGeoBasemapOptions;
+    /**
+     * Tianditu API token used by the `tianditu-*` presets. The viewer never
+     * supplies or persists a token; obtain one for the deployment's own domain.
+     */
     tiandituToken?: string;
+    /**
+     * Defaults to true. When no CRS is declared and coordinates exceed longitude
+     * or latitude ranges, the geo renderer treats Web Mercator-sized values as
+     * EPSG:3857 before rendering.
+     */
     inferProjection?: boolean;
+    /**
+     * Defaults to true. Disable only for environments without reliable WebGL,
+     * where the SVG fallback is preferred.
+     */
     preferMapEngine?: boolean;
+    /**
+     * Padding in CSS pixels when fitting the dataset bounds in the map viewport.
+     */
     fitPadding?: number;
 }
 export interface FileViewerDrawingOptions {
+    /**
+     * Self-hosted diagrams.net viewer script.
+     *
+     * The default points to the optional viewer asset copied under
+     * `vendor/drawio/viewer-static.min.js`. It is only requested when
+     * `preferOfficial` is explicitly enabled and never reaches public
+     * diagrams.net hosts.
+     */
     viewerScriptUrl?: string;
+    /**
+     * Defaults to false so untrusted diagrams use the inert built-in SVG path.
+     * Set to true only to opt into the separately delivered diagrams.net viewer
+     * runtime. It runs in a no-same-origin iframe with a restrictive CSP.
+     */
     preferOfficial?: boolean;
+    /**
+     * PlantUML SVG endpoint. When omitted, the renderer stays fully offline and
+     * shows an SVG source preview. When provided, the renderer appends the
+     * encoded PlantUML payload to this base URL. Self-host this endpoint for
+     * intranet preview.
+     *
+     * Example: `/plantuml/svg/`.
+     */
     plantumlServerUrl?: string;
+    /**
+     * Request timeout for server-rendered PlantUML SVG.
+     */
     plantumlTimeoutMs?: number;
 }
 export type FileViewerCadRenderer = 'auto' | 'webgl' | 'canvas2d';
@@ -505,19 +792,32 @@ export interface FileViewerCadOptions {
     useWorker?: boolean;
     workerTimeoutMs?: number;
     renderer?: FileViewerCadRenderer;
+    /** Initial CAD color policy. `monochrome` applies one plot color without mutating source data. */
     colorMode?: FileViewerCadColorMode;
+    /** CSS color used by monochrome mode. Defaults to black (#000000). */
     monochromeColor?: string;
+    /** Shows the CAD toolbar color-mode toggle. Defaults to true. */
     showColorModeToggle?: boolean;
+    /** Show native PNG/JPEG snapshot downloads. Download/export permissions still apply. */
     showImageExport?: boolean;
     preferDwgWasm?: boolean;
     includePaperSpace?: boolean;
     maxInsertDepth?: number;
     keepRaw?: boolean;
     preloadDwg?: boolean;
+    /**
+     * `best` fits the first view to visible drawing geometry and ignores common
+     * CAD outliers such as paper-space frames or far-away markers. `native`
+     * preserves the raw bounds reported by the underlying CAD renderer.
+     */
     fitMode?: FileViewerCadFitMode;
+    /**
+     * Fraction of the CAD viewport used by fit-to-view. Defaults to 0.92.
+     */
     fitPadding?: number;
     dwfPreferWebgl?: boolean;
     dwfPreferWasm?: boolean;
+    /** Explicit DWF background override; otherwise follows the current color mode. */
     dwfBackground?: string;
     dwfMaxDevicePixelRatio?: number;
     dwfMaxCanvasPixels?: number;
@@ -528,12 +828,19 @@ export interface FileViewerCadOptions {
     dwfMaxOverviewStrokeCssPx?: number;
     dwfMinTextCssPx?: number;
     dwfMinFilledAreaCssPx?: number;
+    /** Default background is dark for source colors and white for monochrome. Explicit colors are retained. */
     canvasOptions?: Record<string, unknown>;
 }
 export type FileViewerRendererMode = 'extend' | 'replace';
 export type FileViewerBuiltinRendererPreset = 'all' | 'lite' | 'none';
 export type FileViewerRendererPresetName = 'all' | 'lite' | 'standard' | 'office' | 'engineering';
 export interface FileViewerAutoRendererOptions {
+    /**
+     * Uses renderer presets registered by build tooling or preset side-effect imports.
+     *
+     * Defaults to true in `extend` mode and false in `replace` mode so applications
+     * can keep a strict hand-picked renderer registry when needed.
+     */
     enabled?: boolean;
 }
 export interface FileViewerSearchOptions {
@@ -553,23 +860,83 @@ export interface FileViewerAiOptions {
     chunkOverlap?: number;
 }
 export interface FileViewerTextOptions {
+    /** Initial HTML/HTM view. Preview is static, sandboxed, and offline; defaults to preview. */
     htmlView?: 'preview' | 'source';
+    /**
+     * Source encoding. Defaults to `auto`: BOM and UTF-16 structure first,
+     * then strict UTF-8, then `fallbackEncoding`. Explicit single-byte labels
+     * decode legacy Latin, Cyrillic, and Central European files. Browsers
+     * decode the `iso-8859-1` label with the windows-1252 table, as the
+     * WHATWG Encoding Standard requires.
+     */
     encoding?: 'auto' | 'utf-8' | 'utf-16le' | 'utf-16be' | 'gbk' | 'gb18030' | 'iso-8859-1' | 'iso-8859-2' | 'iso-8859-15' | 'windows-1250' | 'windows-1251' | 'windows-1252';
+    /**
+     * Encoding used by `auto` for bytes that are not valid UTF-8 and carry no
+     * BOM or UTF-16 structure. Defaults to `gb18030`, which preserves the
+     * historical behavior for GBK files. Set `windows-1252` for Western
+     * European sources or `windows-1251` for Cyrillic sources. Legacy byte
+     * sequences can also be valid UTF-8 or GB18030; use an explicit `encoding`
+     * when the source is known. Ignored when `encoding` is explicit.
+     */
     fallbackEncoding?: 'utf-8' | 'gbk' | 'gb18030' | 'iso-8859-1' | 'iso-8859-2' | 'iso-8859-15' | 'windows-1250' | 'windows-1251' | 'windows-1252';
+    /**
+     * Shows the renderer-local source metadata toolbar (file type, indexing
+     * status, and line count). Defaults to true. This does not control the
+     * viewer-level operation toolbar.
+     */
     toolbar?: boolean;
+    /**
+     * Shows a non-selectable, screen-reader-hidden line-number gutter for code and text.
+     * Defaults to false for regular files. The virtual large-text view keeps its
+     * historical visible gutter when this option is omitted; pass false to hide it.
+     */
     lineNumbers?: boolean;
+    /**
+     * Visually wraps long logical lines without inserting source newlines. Defaults to false.
+     * Wrapped continuation rows remain associated with their original line number.
+     */
     wrapLongLines?: boolean;
+    /**
+     * Formats supported structured text with lazily loaded Prettier plugins for display only.
+     * Defaults to false; malformed, unsupported, or oversized inputs keep their original source.
+     */
     prettyPrint?: boolean;
+    /**
+     * Maximum decoded UTF-8 source bytes eligible for Prettier. Defaults to the effective
+     * `virtualizeAboveBytes` value, or 512 KiB when that option is omitted.
+     */
     prettyPrintMaxBytes?: number;
+    /** Switches text and code to bounded virtual rendering above this byte size. Defaults to 512 KiB. */
     virtualizeAboveBytes?: number;
+    /**
+     * Opts Markdown into source-mode virtual rendering above this byte size.
+     * Markdown stays in its rendered reading view by default; set this only when
+     * an application prefers bounded source inspection for exceptionally large files.
+     */
     markdownVirtualizeAboveBytes?: number;
+    /** Highlights fenced Markdown code with a declared language. Defaults to true; bounded to 512 KiB of code per document. */
     markdownHighlight?: boolean;
+    /** Maximum source bytes mounted for one very long logical line at a time. Defaults to 16 KiB. */
     maxRenderedLineBytes?: number;
+    /** Extra logical lines mounted above and below the visible viewport. Defaults to 12. */
     virtualOverscanLines?: number;
 }
 export type FileViewerUiDensity = 'comfortable' | 'compact';
 export interface FileViewerUiOptions {
+    /**
+     * Controls spacing density for viewer chrome such as toolbars, headers,
+     * archive lists, badges, search inputs, and compact action clusters.
+     */
     density?: FileViewerUiDensity;
+    /**
+     * Overrides the workspace behind rendered pages, slides, and other preview
+     * content. Pass any valid CSS background value (for example `transparent`)
+     * to let the host application provide an immersive surface. Omit this value,
+     * or pass `auto`, to keep each renderer's light/dark default.
+     *
+     * This does not change document pages, slide canvases, spreadsheet cells, or
+     * other file-authored backgrounds.
+     */
     surfaceBackground?: string;
 }
 export interface FileViewerDiagnostic {
@@ -580,18 +947,79 @@ export interface FileViewerDiagnostic {
 }
 export interface FileViewerOptions {
     theme?: FileViewerThemeMode;
+    /** Ctrl/Meta wheel and two-finger document zoom. Enabled when a zoom provider
+     * is available; ordinary scrolling and interactive controls stay native.
+     * Use false or disable individual gestures for a host that owns them.
+     */
     zoomGestures?: boolean | {
         wheel?: boolean;
         pinch?: boolean;
     };
+    /**
+     * Controls how aggressively the viewer protects its DOM and CSS from the
+     * host page. Standard component packages resolve `auto` to Shadow DOM so
+     * host resets cannot break the toolbar or rendered content. Use `none`
+     * explicitly only for legacy integrations that require deep class overrides.
+     */
     styleIsolation?: FileViewerStyleIsolation;
+    /**
+     * Viewer UI language. `auto` follows the browser language and resolves the
+     * built-in Chinese, English, Japanese, and German locales before falling
+     * back to `en-US`.
+     */
     locale?: FileViewerLocale;
+    /**
+     * Optional custom copy for built-in viewer UI. Use `i18n.messages` when you
+     * also want to keep locale and messages grouped together.
+     */
     messages?: FileViewerMessages;
     i18n?: FileViewerI18nOptions;
+    /**
+     * Controls how explicit renderer packages or presets are merged into this
+     * viewer instance.
+     *
+     * `extend` mode keeps the configured built-in baseline and appends explicit
+     * renderers. `replace` mode starts from an empty registry, so `preset` or
+     * `renderers` fully define the active capability set.
+     */
     rendererMode?: FileViewerRendererMode;
+    /**
+     * Advanced baseline switch for built-in browser renderers.
+     *
+     * Most applications can ignore this option and use `preset` / `renderers`
+     * with `rendererMode:'replace'`. Keep it for compatibility or very strict
+     * registry control: `all` preserves the historical full baseline, `lite`
+     * keeps only low-cost web-native previewers, and `none` starts from an empty
+     * built-in baseline while still allowing explicit renderer assembly.
+     */
     builtinRenderers?: FileViewerBuiltinRendererPreset;
+    /**
+     * Enables renderer presets that were auto-registered by `@file-viewer/vite-plugin`
+     * or by explicitly importing a preset package. Set to false when a product wants
+     * total manual control through `renderers`.
+     */
     autoRenderers?: boolean | FileViewerAutoRendererOptions;
+    /**
+     * Product-shaped renderer preset or preset list installed into this viewer
+     * instance.
+     *
+     * This is the bundler-neutral path for Webpack, Rspack, Rollup, Umi,
+     * legacy script builds, and any environment that should not depend on the
+     * Vite virtual module. Import one or more preset packages and pass them here:
+     *
+     * `const officePreset = await import(theInstalledOfficePresetPackage)`
+     * `options: { preset: officePreset.default }`
+     * `options: { preset: [officePreset.default, engineeringPreset.default] }`
+     *
+     * The string form (`'office'`, `'all'`, etc.) selects a preset that has
+     * already been registered by a preset side-effect import or by
+     * `@file-viewer/vite-plugin`.
+     */
     preset?: FileViewerRendererPresetInput;
+    /**
+     * @deprecated Use `preset: [officePreset, engineeringPreset]` instead. This
+     * alias is kept only for compatibility with early 2.x integration drafts.
+     */
     presets?: FileViewerRendererPresetInput;
     renderers?: FileViewerRendererPluginInput;
     watermark?: boolean | FileViewerWatermarkOptions;
@@ -600,25 +1028,47 @@ export interface FileViewerOptions {
     search?: boolean | FileViewerSearchOptions;
     ai?: boolean | FileViewerAiOptions;
     text?: FileViewerTextOptions;
+    /**
+     * Explicit content fitting strategy. When omitted, each renderer keeps its
+     * historical first-screen behavior for backward compatibility.
+     */
     fit?: FileViewerFitMode | FileViewerFitOptions;
+    /**
+     * Initial renderer view position used after the document becomes ready.
+     *
+     * Renderers apply the fields they understand. All standard renderer paths
+     * expose at least renderer / zoom / scroll snapshots through the generic
+     * provider; high-interaction renderers such as PDF, XMind, Geo, 3D, and CAD
+     * add page, navigation, canvas, map, camera, or native view details.
+     */
     initialViewState?: FileViewerViewState;
     archive?: FileViewerArchiveOptions;
     chm?: FileViewerChmOptions;
     pdf?: FileViewerPdfOptions;
+    epub?: FileViewerEpubOptions;
     docx?: FileViewerDocxOptions;
     presentation?: FileViewerPresentationOptions;
     spreadsheet?: FileViewerSpreadsheetOptions;
+    /** Image renderer controls; also applies to multipage TIFF previews. */
     image?: {
+        /** Enable mouse drag panning of overflowing images. Defaults to false; touch scrolling and lightbox clicks are preserved. */
+        handTool?: boolean;
+        /**
+         * Show rotation controls and allow view-state rotation. Defaults to true.
+         * Set false for compact previews. Decoder/EXIF orientation is unchanged.
+         */
         rotation?: boolean;
     };
     iwork?: FileViewerIworkOptions;
     wordPerfect?: FileViewerWordPerfectOptions;
     hangul?: FileViewerHangulOptions;
+    /** Receives non-fatal routing, fallback, and capability diagnostics. */
     onDiagnostic?: (diagnostic: FileViewerDiagnostic) => void;
     typst?: FileViewerTypstOptions;
     geo?: FileViewerGeoOptions;
     data?: FileViewerDataOptions;
     binary?: FileViewerBinaryInspectorOptions;
+    /** Configuration for the explicitly installed XML profile renderer. */
     xml?: FileViewerXmlOptions;
     design?: FileViewerDesignOptions;
     drawing?: FileViewerDrawingOptions;
@@ -727,6 +1177,7 @@ export interface FileViewerNavigationState {
     visible?: boolean;
     mode?: string;
 }
+/** Zero-based workbook sheet id and inclusive cell bounds. */
 export interface FileViewerSpreadsheetRange {
     sheetId: number;
     startRow: number;
@@ -736,7 +1187,9 @@ export interface FileViewerSpreadsheetRange {
 }
 export type FileViewerSpreadsheetNavigationStatus = 'idle' | 'pending' | 'applied' | 'rejected' | 'cancelled' | 'failed' | 'disposed';
 export interface FileViewerViewState {
+    /** Coordinate navigation for spreadsheets; does not edit or select cell contents. */
     spreadsheet?: {
+        /** Active workbook sheet id, retained for restoring views without a range. */
         sheetId?: number;
         range?: FileViewerSpreadsheetRange;
         status?: FileViewerSpreadsheetNavigationStatus;
@@ -893,22 +1346,31 @@ export interface FileViewerExportHtmlOptions {
     title?: string;
     watermarkInlineStyle?: string;
 }
+/** Normalized print-mask rectangle in percent of the rendered content box. */
 export interface FileViewerPrintMaskRegion {
     left: number;
     top: number;
     width: number;
     height: number;
+    /** Zero-based rendered page index. Omitted regions retain legacy whole-document coordinates. */
     pageIndex?: number;
 }
+/** Page-aware image placed above rendered content for printing, such as a seal or signature. */
 export interface FileViewerPrintStamp extends FileViewerPrintMaskRegion {
+    /** Image URL. Uploaded stamps are converted to a local data URL by the designer. */
     src: string;
+    /** Image opacity from 0 to 1. Defaults to 1. */
     opacity?: number;
+    /** Clockwise rotation in degrees. Defaults to 0. */
     rotate?: number;
     alt?: string;
 }
 export interface FileViewerPrintMaskOptions {
+    /** Solid black cover blocks, matching common OFD/business redaction UX. */
     regions?: FileViewerPrintMaskRegion[];
+    /** Image overlays, including locally uploaded seals and signatures. */
     stamps?: FileViewerPrintStamp[];
+    /** Fill color for print masks. Defaults to opaque black. */
     color?: string;
 }
 export interface FileViewerPrintOptions {
@@ -917,6 +1379,7 @@ export interface FileViewerPrintOptions {
     printWindow?: Window | null;
     title?: string;
     watermarkInlineStyle?: string;
+    /** Optional print-time cover masks applied above content and below watermark. */
     mask?: FileViewerPrintMaskOptions | null;
 }
 export interface FileViewerSource {
@@ -966,15 +1429,28 @@ export interface RendererDefinition {
     label: string;
     category: FileViewerRendererCategory;
     extensions: readonly string[];
+    /** Optional compound filename claims such as tileset.json or *.copc.laz. */
     filenamePatterns?: readonly string[];
+    /** Prefer passing the original URL to the renderer instead of eagerly downloading it. */
     sourceAccess?: 'buffer' | 'stream-preferred';
+    /**
+     * Optional bounded content probe. Return the specialist type to route the
+     * source through this renderer, or false when the existing extension owner
+     * must remain unchanged.
+     */
     resolveSourceType?: RendererSourceTypeProbe;
     async?: boolean;
+    /** Product-level fidelity contract generated from ecosystem/format-catalog.json. */
     supportLevel?: FileViewerFormatSupportLevel;
+    /** Experimental formats are routable but are excluded from stable support counts. */
     status?: FileViewerFormatStatus;
+    /** Owning on-demand renderer package. */
     packageName?: string;
+    /** Presets that assemble this renderer. */
     presets?: readonly FileViewerRendererPresetName[];
+    /** Existing renderer whose fallback extensions this specialist replaces when installed. */
     enhancesRendererId?: string;
+    /** Extensions transferred from enhancesRendererId to this specialist when installed. */
     enhancesExtensions?: readonly string[];
     containerVersions?: readonly string[];
     knownLimits?: readonly string[];
@@ -1048,6 +1524,7 @@ export interface FileViewerLoadOptions {
 }
 export interface FileViewerInstance {
     readonly container: HTMLElement;
+    /** Installs configured renderer plugins without loading a document. */
     prepare?(): Promise<void>;
     load(source: FileViewerSource, options?: FileViewerLoadOptions): Promise<RendererSession | null>;
     unload?(reason?: FileViewerLifecycleContext['reason']): Promise<void>;
@@ -1063,6 +1540,7 @@ export interface FileViewerInstance {
     download(options?: FileViewerDownloadOptions): Promise<void>;
     exportHtml(options?: FileViewerExportHtmlOptions): Promise<string>;
     print(options?: FileViewerPrintOptions): Promise<void>;
+    /** Open the async print-mask designer, then print with the chosen covers. */
     printWithMask(options?: FileViewerPrintOptions): Promise<void>;
     zoomIn(): Promise<FileViewerZoomState>;
     zoomOut(): Promise<FileViewerZoomState>;