@file-viewer/core 3.1.2 → 3.2.1

package/dist/contracts/types.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerXmlOptions } from './xml';
+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,13 +50,9 @@ 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;
@@ -75,10 +71,6 @@ 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 {
@@ -89,40 +81,20 @@ export interface FileViewerArchiveOptions {
     maxArchiveSize?: number;
     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';
@@ -134,84 +106,49 @@ export interface FileViewerArchivePasswordRequestContext {
     error?: unknown;
 }
 export interface FileViewerPdfOptions {
+    handTool?: boolean;
     toolbar?: 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';
     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 {
-    /** DOC/DOCX 默认保留插入和删除修订；final 显示定稿，original 显示修订前原稿。 */
+    exposeDisplayTargets?: boolean;
     reviewMode?: 'all' | 'final' | 'original';
     worker?: boolean;
     workerUrl?: string;
     workerJsZipUrl?: string;
     progressive?: boolean;
-    /** 默认 false，使用连续流式阅读；设为 true 时才启用 DOCX 页式预览。 */
     visualPagination?: boolean;
     workerTimeout?: number;
     renderPageBatchSize?: number;
@@ -224,41 +161,27 @@ export interface FileViewerDocxOptions {
     updatePageReferences?: boolean;
     hideWebHiddenContent?: boolean;
     ignoreLastRenderedPageBreak?: boolean;
-    /** External DOC/DOCX/RTF links are blocked by default; internal bookmark links remain active. */
+    renderAltChunks?: boolean;
     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 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;
+    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;
@@ -266,63 +189,36 @@ 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';
@@ -339,13 +235,9 @@ 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 {
@@ -357,7 +249,6 @@ 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;
@@ -366,15 +257,13 @@ export interface FileRenderContext {
     filename?: string;
     url?: string;
     streamUrl?: string;
-    /** Original browser File retained for renderers that support Blob-backed random access. */
-    sourceFile?: File;
+    sourceFile?: File | Blob;
     signal?: AbortSignal;
     options?: FileViewerOptions;
     surface?: RenderSurface;
     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;
@@ -387,13 +276,6 @@ 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>;
@@ -412,15 +294,10 @@ 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';
@@ -430,21 +307,14 @@ 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;
@@ -482,85 +352,45 @@ 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;
@@ -586,7 +416,6 @@ 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;
@@ -619,7 +448,6 @@ 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;
@@ -635,29 +463,10 @@ 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;
@@ -665,86 +474,23 @@ 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';
@@ -759,32 +505,19 @@ 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;
@@ -795,19 +528,12 @@ 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 {
@@ -827,69 +553,23 @@ 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, with GB18030 (including GBK) as the final fallback.
-     */
-    encoding?: 'auto' | 'utf-8' | 'utf-16le' | 'utf-16be' | 'gbk' | 'gb18030';
-    /**
-     * 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.
-     */
+    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';
+    fallbackEncoding?: 'utf-8' | 'gbk' | 'gb18030' | 'iso-8859-1' | 'iso-8859-2' | 'iso-8859-15' | 'windows-1250' | 'windows-1251' | 'windows-1252';
     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;
-    /** Maximum source bytes mounted for one very long logical line at a time. Defaults to 16 KiB. */
+    markdownHighlight?: boolean;
     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 {
@@ -900,71 +580,18 @@ export interface FileViewerDiagnostic {
 }
 export interface FileViewerOptions {
     theme?: FileViewerThemeMode;
-    /**
-     * 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.
-     */
+    zoomGestures?: boolean | {
+        wheel?: boolean;
+        pinch?: boolean;
+    };
     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;
@@ -973,19 +600,7 @@ 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;
@@ -993,24 +608,17 @@ export interface FileViewerOptions {
     docx?: FileViewerDocxOptions;
     presentation?: FileViewerPresentationOptions;
     spreadsheet?: FileViewerSpreadsheetOptions;
-    /** Image renderer controls; also applies to multipage TIFF previews. */
     image?: {
-        /**
-         * 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;
@@ -1272,31 +880,22 @@ 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 {
@@ -1305,7 +904,6 @@ 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 {
@@ -1340,23 +938,30 @@ export interface RendererCapability {
 }
 export type FileViewerFormatSupportLevel = 'high-fidelity' | 'structured' | 'basic' | 'experimental';
 export type FileViewerFormatStatus = 'stable' | 'experimental';
+export interface RendererSourceTypeProbeInput {
+    filename: string;
+    extension: string;
+    url?: string;
+    file?: File | Blob;
+    buffer?: ArrayBuffer;
+    mimeType?: string;
+    signal?: AbortSignal;
+}
+export type RendererSourceTypeProbe = (input: RendererSourceTypeProbeInput) => string | false | null | undefined | Promise<string | false | null | undefined>;
 export interface RendererDefinition {
     id: string;
     label: string;
     category: FileViewerRendererCategory;
     extensions: readonly string[];
+    filenamePatterns?: readonly string[];
+    sourceAccess?: 'buffer' | 'stream-preferred';
+    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[];
@@ -1430,7 +1035,6 @@ 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>;
@@ -1446,7 +1050,6 @@ 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>;