@file-viewer/core 3.3.0 → 3.3.1

package/dist/registry/capabilities.js

@@ -1,5 +1,5 @@
-import { ARCHIVE_EXTENSIONS, IMAGE_EXTENSIONS, MODEL_EXTENSIONS, TEXT_EXTENSIONS } from "./formats.js";
-import { normalizeFileExtension } from "../source/index.js";
+import { ARCHIVE_EXTENSIONS, IMAGE_EXTENSIONS, MODEL_EXTENSIONS, TEXT_EXTENSIONS } from './formats.js';
+import { normalizeFileExtension } from '../source/index.js';
 export const DEFAULT_OPERATION_AVAILABILITY = Object.freeze({
     download: false,
     print: false,
@@ -45,9 +45,19 @@ export const createUnsupportedAvailability = (extension) => ({
     ...DEFAULT_OPERATION_AVAILABILITY,
     download: normalizeFileExtension(extension).length > 0,
 });
+/**
+ * 这些格式只有专属适配器准备好后才展示打印。
+ *
+ * 它们的在线预览常依赖分页引擎、虚拟渲染或 Worker 生命周期，直接克隆
+ * DOM 很容易只得到当前页或当前视口。
+ */
 export const ADAPTER_PRINT_REQUIRED_EXTENSIONS = [
     'docx', 'docm', 'dotx', 'dotm', 'doc', 'dot', 'ppt', 'pdf', 'typ', 'typst',
 ];
+/**
+ * 这些格式的预览结果是完整 DOM / SVG / Canvas 截图，解除滚动容器裁切后
+ * 可以稳定进入浏览器打印流程。
+ */
 export const DOM_PRINTABLE_EXTENSIONS = [
     'pptx', 'pptm', 'potx', 'potm', 'ppsx', 'ppsm', 'ofd', 'dxf', 'dwg', 'dwf', 'dwfx', 'xps',
     'excalidraw', 'drawio', 'dio', 'mermaid', 'mmd', 'plantuml', 'puml', 'umd', 'md', 'markdown',
@@ -55,6 +65,9 @@ export const DOM_PRINTABLE_EXTENSIONS = [
     ...TEXT_EXTENSIONS,
     ...IMAGE_EXTENSIONS,
 ];
+/**
+ * 这些格式默认不展示打印按钮，避免导出半截内容。
+ */
 export const NON_PRINTABLE_EXTENSIONS = [
     'xlsx', 'xltx', 'xlsm', 'xlsb', 'xls', 'xlt', 'xltm', 'csv', 'tsv', 'ods', 'fods', 'numbers',
     ...ARCHIVE_EXTENSIONS,

package/dist/registry/formats.d.ts

@@ -1,4 +1,4 @@
-export { DEFAULT_REGISTERED_EXTENSIONS, DEFAULT_RENDERER_DEFINITIONS, DEFAULT_STABLE_SUPPORTED_EXTENSIONS, DEFAULT_SUPPORTED_EXTENSIONS, } from "./formats.generated.js";
+export { DEFAULT_REGISTERED_EXTENSIONS, DEFAULT_RENDERER_DEFINITIONS, DEFAULT_STABLE_SUPPORTED_EXTENSIONS, DEFAULT_SUPPORTED_EXTENSIONS, } from './formats.generated.js';
 export declare const ARCHIVE_EXTENSIONS: readonly ("markdown" | "webp" | "jpeg" | "png" | "pdf" | "xyz" | "wasm" | "chm" | "typst" | "xd" | "fla" | "js" | "html" | "svg" | "rb" | "docx" | "docm" | "dotx" | "dotm" | "doc" | "dot" | "ppt" | "pot" | "pptx" | "pptm" | "potx" | "potm" | "ppsx" | "ppsm" | "rtf" | "odt" | "odp" | "xlsx" | "xltx" | "xlsm" | "xlsb" | "xls" | "xlt" | "xla" | "xlam" | "xltm" | "csv" | "tsv" | "ods" | "fods" | "pages" | "numbers" | "key" | "wpd" | "wp" | "wp5" | "wp6" | "dbf" | "ofd" | "hwp" | "hwpx" | "typ" | "zip" | "zipx" | "7z" | "rar" | "tar" | "gz" | "gzip" | "tgz" | "bz2" | "bzip2" | "tbz" | "tbz2" | "xz" | "txz" | "lzma" | "zst" | "tzst" | "cab" | "ar" | "cpio" | "iso" | "xar" | "lha" | "lzh" | "jar" | "war" | "ear" | "apk" | "cbz" | "cbr" | "eml" | "msg" | "mbox" | "olb" | "dra" | "gds" | "oas" | "oasis" | "dxf" | "dwg" | "dwf" | "dwfx" | "xps" | "glb" | "gltf" | "obj" | "stl" | "ply" | "fbx" | "dae" | "3ds" | "3mf" | "amf" | "usd" | "usda" | "usdc" | "usdz" | "kmz" | "step" | "stp" | "iges" | "igs" | "ifc" | "3dm" | "brep" | "pcd" | "wrl" | "vrml" | "vtk" | "vtp" | "geojson" | "kml" | "gpx" | "shp" | "excalidraw" | "drawio" | "dio" | "mermaid" | "mmd" | "plantuml" | "puml" | "bpmn" | "xmind" | "epub" | "fb2" | "umd" | "gif" | "jpg" | "bmp" | "tiff" | "tif" | "avif" | "ico" | "heic" | "heif" | "jxl" | "dicom" | "dcm" | "p7m" | "p7s" | "p7c" | "p7b" | "pkcs7" | "cms" | "cmsc" | "tsd" | "tst" | "tsq" | "tsr" | "asics" | "scs" | "asice" | "sce" | "ers" | "asc" | "sig" | "pgp" | "gpg" | "jws" | "md" | "txt" | "lrc" | "json" | "mjs" | "cjs" | "css" | "java" | "py" | "htm" | "jsx" | "ts" | "tsx" | "xml" | "log" | "vue" | "yaml" | "yml" | "ini" | "sh" | "bash" | "sql" | "go" | "rs" | "php" | "c" | "cpp" | "cc" | "h" | "hpp" | "cs" | "diff" | "patch" | "bundle" | "bdl" | "jsonc" | "json5" | "ipynb" | "toml" | "proto" | "hcl" | "tex" | "gv" | "http" | "react" | "swift" | "kt" | "mp4" | "webm" | "m3u8" | "mp3" | "mpeg" | "wav" | "ogg" | "oga" | "opus" | "m4a" | "aac" | "flac" | "weba" | "midi" | "mid" | "psb" | "pdd" | "psdt" | "psd" | "ait" | "ai" | "idml" | "icml" | "idms" | "inx" | "xfl" | "indd" | "indt" | "ps" | "eps" | "ase" | "aco" | "abr" | "csh" | "pat" | "grd" | "asl" | "ttf" | "otf" | "woff" | "woff2" | "sqlite" | "parquet" | "avro" | "webarchive" | "bin" | "hex" | "elf" | "exe" | "dll" | "class" | "macho")[];
 export declare const MODEL_EXTENSIONS: readonly ("markdown" | "webp" | "jpeg" | "png" | "pdf" | "xyz" | "wasm" | "chm" | "typst" | "xd" | "fla" | "js" | "html" | "svg" | "rb" | "docx" | "docm" | "dotx" | "dotm" | "doc" | "dot" | "ppt" | "pot" | "pptx" | "pptm" | "potx" | "potm" | "ppsx" | "ppsm" | "rtf" | "odt" | "odp" | "xlsx" | "xltx" | "xlsm" | "xlsb" | "xls" | "xlt" | "xla" | "xlam" | "xltm" | "csv" | "tsv" | "ods" | "fods" | "pages" | "numbers" | "key" | "wpd" | "wp" | "wp5" | "wp6" | "dbf" | "ofd" | "hwp" | "hwpx" | "typ" | "zip" | "zipx" | "7z" | "rar" | "tar" | "gz" | "gzip" | "tgz" | "bz2" | "bzip2" | "tbz" | "tbz2" | "xz" | "txz" | "lzma" | "zst" | "tzst" | "cab" | "ar" | "cpio" | "iso" | "xar" | "lha" | "lzh" | "jar" | "war" | "ear" | "apk" | "cbz" | "cbr" | "eml" | "msg" | "mbox" | "olb" | "dra" | "gds" | "oas" | "oasis" | "dxf" | "dwg" | "dwf" | "dwfx" | "xps" | "glb" | "gltf" | "obj" | "stl" | "ply" | "fbx" | "dae" | "3ds" | "3mf" | "amf" | "usd" | "usda" | "usdc" | "usdz" | "kmz" | "step" | "stp" | "iges" | "igs" | "ifc" | "3dm" | "brep" | "pcd" | "wrl" | "vrml" | "vtk" | "vtp" | "geojson" | "kml" | "gpx" | "shp" | "excalidraw" | "drawio" | "dio" | "mermaid" | "mmd" | "plantuml" | "puml" | "bpmn" | "xmind" | "epub" | "fb2" | "umd" | "gif" | "jpg" | "bmp" | "tiff" | "tif" | "avif" | "ico" | "heic" | "heif" | "jxl" | "dicom" | "dcm" | "p7m" | "p7s" | "p7c" | "p7b" | "pkcs7" | "cms" | "cmsc" | "tsd" | "tst" | "tsq" | "tsr" | "asics" | "scs" | "asice" | "sce" | "ers" | "asc" | "sig" | "pgp" | "gpg" | "jws" | "md" | "txt" | "lrc" | "json" | "mjs" | "cjs" | "css" | "java" | "py" | "htm" | "jsx" | "ts" | "tsx" | "xml" | "log" | "vue" | "yaml" | "yml" | "ini" | "sh" | "bash" | "sql" | "go" | "rs" | "php" | "c" | "cpp" | "cc" | "h" | "hpp" | "cs" | "diff" | "patch" | "bundle" | "bdl" | "jsonc" | "json5" | "ipynb" | "toml" | "proto" | "hcl" | "tex" | "gv" | "http" | "react" | "swift" | "kt" | "mp4" | "webm" | "m3u8" | "mp3" | "mpeg" | "wav" | "ogg" | "oga" | "opus" | "m4a" | "aac" | "flac" | "weba" | "midi" | "mid" | "psb" | "pdd" | "psdt" | "psd" | "ait" | "ai" | "idml" | "icml" | "idms" | "inx" | "xfl" | "indd" | "indt" | "ps" | "eps" | "ase" | "aco" | "abr" | "csh" | "pat" | "grd" | "asl" | "ttf" | "otf" | "woff" | "woff2" | "sqlite" | "parquet" | "avro" | "webarchive" | "bin" | "hex" | "elf" | "exe" | "dll" | "class" | "macho")[];
 export declare const TEXT_EXTENSIONS: readonly ("markdown" | "webp" | "jpeg" | "png" | "pdf" | "xyz" | "wasm" | "chm" | "typst" | "xd" | "fla" | "js" | "html" | "svg" | "rb" | "docx" | "docm" | "dotx" | "dotm" | "doc" | "dot" | "ppt" | "pot" | "pptx" | "pptm" | "potx" | "potm" | "ppsx" | "ppsm" | "rtf" | "odt" | "odp" | "xlsx" | "xltx" | "xlsm" | "xlsb" | "xls" | "xlt" | "xla" | "xlam" | "xltm" | "csv" | "tsv" | "ods" | "fods" | "pages" | "numbers" | "key" | "wpd" | "wp" | "wp5" | "wp6" | "dbf" | "ofd" | "hwp" | "hwpx" | "typ" | "zip" | "zipx" | "7z" | "rar" | "tar" | "gz" | "gzip" | "tgz" | "bz2" | "bzip2" | "tbz" | "tbz2" | "xz" | "txz" | "lzma" | "zst" | "tzst" | "cab" | "ar" | "cpio" | "iso" | "xar" | "lha" | "lzh" | "jar" | "war" | "ear" | "apk" | "cbz" | "cbr" | "eml" | "msg" | "mbox" | "olb" | "dra" | "gds" | "oas" | "oasis" | "dxf" | "dwg" | "dwf" | "dwfx" | "xps" | "glb" | "gltf" | "obj" | "stl" | "ply" | "fbx" | "dae" | "3ds" | "3mf" | "amf" | "usd" | "usda" | "usdc" | "usdz" | "kmz" | "step" | "stp" | "iges" | "igs" | "ifc" | "3dm" | "brep" | "pcd" | "wrl" | "vrml" | "vtk" | "vtp" | "geojson" | "kml" | "gpx" | "shp" | "excalidraw" | "drawio" | "dio" | "mermaid" | "mmd" | "plantuml" | "puml" | "bpmn" | "xmind" | "epub" | "fb2" | "umd" | "gif" | "jpg" | "bmp" | "tiff" | "tif" | "avif" | "ico" | "heic" | "heif" | "jxl" | "dicom" | "dcm" | "p7m" | "p7s" | "p7c" | "p7b" | "pkcs7" | "cms" | "cmsc" | "tsd" | "tst" | "tsq" | "tsr" | "asics" | "scs" | "asice" | "sce" | "ers" | "asc" | "sig" | "pgp" | "gpg" | "jws" | "md" | "txt" | "lrc" | "json" | "mjs" | "cjs" | "css" | "java" | "py" | "htm" | "jsx" | "ts" | "tsx" | "xml" | "log" | "vue" | "yaml" | "yml" | "ini" | "sh" | "bash" | "sql" | "go" | "rs" | "php" | "c" | "cpp" | "cc" | "h" | "hpp" | "cs" | "diff" | "patch" | "bundle" | "bdl" | "jsonc" | "json5" | "ipynb" | "toml" | "proto" | "hcl" | "tex" | "gv" | "http" | "react" | "swift" | "kt" | "mp4" | "webm" | "m3u8" | "mp3" | "mpeg" | "wav" | "ogg" | "oga" | "opus" | "m4a" | "aac" | "flac" | "weba" | "midi" | "mid" | "psb" | "pdd" | "psdt" | "psd" | "ait" | "ai" | "idml" | "icml" | "idms" | "inx" | "xfl" | "indd" | "indt" | "ps" | "eps" | "ase" | "aco" | "abr" | "csh" | "pat" | "grd" | "asl" | "ttf" | "otf" | "woff" | "woff2" | "sqlite" | "parquet" | "avro" | "webarchive" | "bin" | "hex" | "elf" | "exe" | "dll" | "class" | "macho")[];

package/dist/registry/formats.generated.d.ts

@@ -900,4 +900,5 @@ export declare const DEFAULT_RENDERER_DEFINITIONS: readonly [{
 }];
 export declare const DEFAULT_REGISTERED_EXTENSIONS: readonly ("markdown" | "webp" | "jpeg" | "png" | "pdf" | "xyz" | "wasm" | "chm" | "typst" | "xd" | "fla" | "js" | "html" | "svg" | "rb" | "docx" | "docm" | "dotx" | "dotm" | "doc" | "dot" | "ppt" | "pot" | "pptx" | "pptm" | "potx" | "potm" | "ppsx" | "ppsm" | "rtf" | "odt" | "odp" | "xlsx" | "xltx" | "xlsm" | "xlsb" | "xls" | "xlt" | "xla" | "xlam" | "xltm" | "csv" | "tsv" | "ods" | "fods" | "pages" | "numbers" | "key" | "wpd" | "wp" | "wp5" | "wp6" | "dbf" | "ofd" | "hwp" | "hwpx" | "typ" | "zip" | "zipx" | "7z" | "rar" | "tar" | "gz" | "gzip" | "tgz" | "bz2" | "bzip2" | "tbz" | "tbz2" | "xz" | "txz" | "lzma" | "zst" | "tzst" | "cab" | "ar" | "cpio" | "iso" | "xar" | "lha" | "lzh" | "jar" | "war" | "ear" | "apk" | "cbz" | "cbr" | "eml" | "msg" | "mbox" | "olb" | "dra" | "gds" | "oas" | "oasis" | "dxf" | "dwg" | "dwf" | "dwfx" | "xps" | "glb" | "gltf" | "obj" | "stl" | "ply" | "fbx" | "dae" | "3ds" | "3mf" | "amf" | "usd" | "usda" | "usdc" | "usdz" | "kmz" | "step" | "stp" | "iges" | "igs" | "ifc" | "3dm" | "brep" | "pcd" | "wrl" | "vrml" | "vtk" | "vtp" | "geojson" | "kml" | "gpx" | "shp" | "excalidraw" | "drawio" | "dio" | "mermaid" | "mmd" | "plantuml" | "puml" | "bpmn" | "xmind" | "epub" | "fb2" | "umd" | "gif" | "jpg" | "bmp" | "tiff" | "tif" | "avif" | "ico" | "heic" | "heif" | "jxl" | "dicom" | "dcm" | "p7m" | "p7s" | "p7c" | "p7b" | "pkcs7" | "cms" | "cmsc" | "tsd" | "tst" | "tsq" | "tsr" | "asics" | "scs" | "asice" | "sce" | "ers" | "asc" | "sig" | "pgp" | "gpg" | "jws" | "md" | "txt" | "lrc" | "json" | "mjs" | "cjs" | "css" | "java" | "py" | "htm" | "jsx" | "ts" | "tsx" | "xml" | "log" | "vue" | "yaml" | "yml" | "ini" | "sh" | "bash" | "sql" | "go" | "rs" | "php" | "c" | "cpp" | "cc" | "h" | "hpp" | "cs" | "diff" | "patch" | "bundle" | "bdl" | "jsonc" | "json5" | "ipynb" | "toml" | "proto" | "hcl" | "tex" | "gv" | "http" | "react" | "swift" | "kt" | "mp4" | "webm" | "m3u8" | "mp3" | "mpeg" | "wav" | "ogg" | "oga" | "opus" | "m4a" | "aac" | "flac" | "weba" | "midi" | "mid" | "psb" | "pdd" | "psdt" | "psd" | "ait" | "ai" | "idml" | "icml" | "idms" | "inx" | "xfl" | "indd" | "indt" | "ps" | "eps" | "ase" | "aco" | "abr" | "csh" | "pat" | "grd" | "asl" | "ttf" | "otf" | "woff" | "woff2" | "sqlite" | "parquet" | "avro" | "webarchive" | "bin" | "hex" | "elf" | "exe" | "dll" | "class" | "macho")[];
 export declare const DEFAULT_STABLE_SUPPORTED_EXTENSIONS: readonly ("markdown" | "webp" | "jpeg" | "png" | "pdf" | "xyz" | "wasm" | "chm" | "typst" | "js" | "html" | "svg" | "rb" | "docx" | "docm" | "dotx" | "dotm" | "doc" | "dot" | "ppt" | "pot" | "pptx" | "pptm" | "potx" | "potm" | "ppsx" | "ppsm" | "rtf" | "odt" | "odp" | "xlsx" | "xltx" | "xlsm" | "xlsb" | "xls" | "xlt" | "xla" | "xlam" | "xltm" | "csv" | "tsv" | "ods" | "fods" | "pages" | "numbers" | "key" | "wpd" | "wp" | "wp5" | "wp6" | "dbf" | "ofd" | "hwp" | "hwpx" | "typ" | "zip" | "zipx" | "7z" | "rar" | "tar" | "gz" | "gzip" | "tgz" | "bz2" | "bzip2" | "tbz" | "tbz2" | "xz" | "txz" | "lzma" | "zst" | "tzst" | "cab" | "ar" | "cpio" | "iso" | "xar" | "lha" | "lzh" | "jar" | "war" | "ear" | "apk" | "cbz" | "cbr" | "eml" | "msg" | "mbox" | "olb" | "dra" | "gds" | "oas" | "oasis" | "dxf" | "dwg" | "dwf" | "dwfx" | "xps" | "glb" | "gltf" | "obj" | "stl" | "ply" | "fbx" | "dae" | "3ds" | "3mf" | "amf" | "usd" | "usda" | "usdc" | "usdz" | "kmz" | "step" | "stp" | "iges" | "igs" | "ifc" | "3dm" | "brep" | "pcd" | "wrl" | "vrml" | "vtk" | "vtp" | "geojson" | "kml" | "gpx" | "shp" | "excalidraw" | "drawio" | "dio" | "mermaid" | "mmd" | "plantuml" | "puml" | "xmind" | "epub" | "fb2" | "umd" | "gif" | "jpg" | "bmp" | "tiff" | "tif" | "avif" | "ico" | "heic" | "heif" | "jxl" | "md" | "txt" | "lrc" | "json" | "mjs" | "cjs" | "css" | "java" | "py" | "htm" | "jsx" | "ts" | "tsx" | "xml" | "log" | "vue" | "yaml" | "yml" | "ini" | "sh" | "bash" | "sql" | "go" | "rs" | "php" | "c" | "cpp" | "cc" | "h" | "hpp" | "cs" | "diff" | "patch" | "bundle" | "bdl" | "jsonc" | "json5" | "ipynb" | "toml" | "proto" | "hcl" | "tex" | "gv" | "http" | "react" | "swift" | "kt" | "mp4" | "webm" | "m3u8" | "mp3" | "mpeg" | "wav" | "ogg" | "oga" | "opus" | "m4a" | "aac" | "flac" | "weba" | "midi" | "mid" | "psd" | "ai" | "eps" | "ase" | "aco" | "ttf" | "otf" | "woff" | "woff2" | "sqlite" | "parquet" | "avro" | "webarchive")[];
+/** @deprecated Use DEFAULT_REGISTERED_EXTENSIONS when the experimental/stable distinction matters. */
 export declare const DEFAULT_SUPPORTED_EXTENSIONS: readonly ("markdown" | "webp" | "jpeg" | "png" | "pdf" | "xyz" | "wasm" | "chm" | "typst" | "xd" | "fla" | "js" | "html" | "svg" | "rb" | "docx" | "docm" | "dotx" | "dotm" | "doc" | "dot" | "ppt" | "pot" | "pptx" | "pptm" | "potx" | "potm" | "ppsx" | "ppsm" | "rtf" | "odt" | "odp" | "xlsx" | "xltx" | "xlsm" | "xlsb" | "xls" | "xlt" | "xla" | "xlam" | "xltm" | "csv" | "tsv" | "ods" | "fods" | "pages" | "numbers" | "key" | "wpd" | "wp" | "wp5" | "wp6" | "dbf" | "ofd" | "hwp" | "hwpx" | "typ" | "zip" | "zipx" | "7z" | "rar" | "tar" | "gz" | "gzip" | "tgz" | "bz2" | "bzip2" | "tbz" | "tbz2" | "xz" | "txz" | "lzma" | "zst" | "tzst" | "cab" | "ar" | "cpio" | "iso" | "xar" | "lha" | "lzh" | "jar" | "war" | "ear" | "apk" | "cbz" | "cbr" | "eml" | "msg" | "mbox" | "olb" | "dra" | "gds" | "oas" | "oasis" | "dxf" | "dwg" | "dwf" | "dwfx" | "xps" | "glb" | "gltf" | "obj" | "stl" | "ply" | "fbx" | "dae" | "3ds" | "3mf" | "amf" | "usd" | "usda" | "usdc" | "usdz" | "kmz" | "step" | "stp" | "iges" | "igs" | "ifc" | "3dm" | "brep" | "pcd" | "wrl" | "vrml" | "vtk" | "vtp" | "geojson" | "kml" | "gpx" | "shp" | "excalidraw" | "drawio" | "dio" | "mermaid" | "mmd" | "plantuml" | "puml" | "bpmn" | "xmind" | "epub" | "fb2" | "umd" | "gif" | "jpg" | "bmp" | "tiff" | "tif" | "avif" | "ico" | "heic" | "heif" | "jxl" | "dicom" | "dcm" | "p7m" | "p7s" | "p7c" | "p7b" | "pkcs7" | "cms" | "cmsc" | "tsd" | "tst" | "tsq" | "tsr" | "asics" | "scs" | "asice" | "sce" | "ers" | "asc" | "sig" | "pgp" | "gpg" | "jws" | "md" | "txt" | "lrc" | "json" | "mjs" | "cjs" | "css" | "java" | "py" | "htm" | "jsx" | "ts" | "tsx" | "xml" | "log" | "vue" | "yaml" | "yml" | "ini" | "sh" | "bash" | "sql" | "go" | "rs" | "php" | "c" | "cpp" | "cc" | "h" | "hpp" | "cs" | "diff" | "patch" | "bundle" | "bdl" | "jsonc" | "json5" | "ipynb" | "toml" | "proto" | "hcl" | "tex" | "gv" | "http" | "react" | "swift" | "kt" | "mp4" | "webm" | "m3u8" | "mp3" | "mpeg" | "wav" | "ogg" | "oga" | "opus" | "m4a" | "aac" | "flac" | "weba" | "midi" | "mid" | "psb" | "pdd" | "psdt" | "psd" | "ait" | "ai" | "idml" | "icml" | "idms" | "inx" | "xfl" | "indd" | "indt" | "ps" | "eps" | "ase" | "aco" | "abr" | "csh" | "pat" | "grd" | "asl" | "ttf" | "otf" | "woff" | "woff2" | "sqlite" | "parquet" | "avro" | "webarchive" | "bin" | "hex" | "elf" | "exe" | "dll" | "class" | "macho")[];

package/dist/registry/formats.generated.js

@@ -1656,4 +1656,5 @@ export const DEFAULT_REGISTERED_EXTENSIONS = Object.freeze(Array.from(new Set(DE
 export const DEFAULT_STABLE_SUPPORTED_EXTENSIONS = Object.freeze(Array.from(new Set(DEFAULT_RENDERER_DEFINITIONS
     .filter(definition => definition.status === 'stable')
     .flatMap(definition => definition.extensions))).sort());
+/** @deprecated Use DEFAULT_REGISTERED_EXTENSIONS when the experimental/stable distinction matters. */
 export const DEFAULT_SUPPORTED_EXTENSIONS = DEFAULT_REGISTERED_EXTENSIONS;

package/dist/registry/formats.js

@@ -1,5 +1,5 @@
-export { DEFAULT_REGISTERED_EXTENSIONS, DEFAULT_RENDERER_DEFINITIONS, DEFAULT_STABLE_SUPPORTED_EXTENSIONS, DEFAULT_SUPPORTED_EXTENSIONS, } from "./formats.generated.js";
-import { DEFAULT_RENDERER_DEFINITIONS } from "./formats.generated.js";
+export { DEFAULT_REGISTERED_EXTENSIONS, DEFAULT_RENDERER_DEFINITIONS, DEFAULT_STABLE_SUPPORTED_EXTENSIONS, DEFAULT_SUPPORTED_EXTENSIONS, } from './formats.generated.js';
+import { DEFAULT_RENDERER_DEFINITIONS } from './formats.generated.js';
 const extensionsFor = (rendererId) => {
     var _a, _b;
     return Object.freeze([...((_b = (_a = DEFAULT_RENDERER_DEFINITIONS.find(definition => definition.id === rendererId)) === null || _a === void 0 ? void 0 : _a.extensions) !== null && _b !== void 0 ? _b : [])]);

package/dist/registry/registry.d.ts

@@ -1,6 +1,13 @@
-import type { FileViewerRendererHandlerRegistration, FileViewerRendererPluginInput, FileViewerRendererPlugin, FileViewerRendererPresetInput, FileViewerRendererPresetName, RendererDefinition, RendererRegistry } from "../contracts/types.js";
+import type { FileViewerRendererHandlerRegistration, FileViewerRendererPluginInput, FileViewerRendererPlugin, FileViewerRendererPresetInput, FileViewerRendererPresetName, RendererDefinition, RendererRegistry } from '../contracts/types.js';
 export interface RegisterFileViewerAutoRendererPresetOptions {
+    /**
+     * Stable key used to replace an existing auto preset registration.
+     */
     id?: string;
+    /**
+     * Package name is useful for diagnostics and gives generated integrations a
+     * deterministic id even when the preset input is an array.
+     */
     packageName?: string;
 }
 export interface FileViewerAutoRendererPresetEntry<Handler = unknown> {
@@ -32,5 +39,12 @@ export declare const listFileViewerAutoRendererPresetEntries: <Handler = unknown
 export declare const findFileViewerAutoRendererPreset: <Handler = unknown>(id: FileViewerRendererPresetName | string) => FileViewerRendererPluginInput<Handler> | undefined;
 export declare const getFileViewerAutoRendererPresetVersion: () => number;
 export declare const hasFileViewerRendererPresetName: (input?: FileViewerRendererPresetInput | null) => boolean;
+/**
+ * Normalizes `options.preset` / `options.presets` into renderer plugin inputs.
+ *
+ * Passing a preset object is the most portable integration style because it
+ * works in any bundler. String selectors intentionally only resolve presets
+ * that are already registered by a side-effect import or by build tooling.
+ */
 export declare const resolveFileViewerRendererPresetInputs: <Handler = unknown>(input?: FileViewerRendererPresetInput<Handler> | null) => FileViewerRendererPluginInput<Handler>[];
 export declare const installFileViewerRendererPlugins: <Handler = unknown>({ registry, plugins, registerHandler, }: InstallFileViewerRendererPluginsOptions<Handler>) => Promise<RendererRegistry>;

package/dist/registry/registry.js

@@ -1,5 +1,5 @@
-import { DEFAULT_RENDERER_DEFINITIONS } from "./formats.js";
-import { getExtension, normalizeFileExtension, normalizeFilename } from "../source/index.js";
+import { DEFAULT_RENDERER_DEFINITIONS } from './formats.js';
+import { getExtension, normalizeFileExtension, normalizeFilename } from '../source/index.js';
 const autoRendererBucketKey = '__flyfish_file_viewer_auto_renderer_presets__';
 const getAutoRendererBucket = () => {
     const host = globalThis;
@@ -217,6 +217,7 @@ const createRendererDefinitionInstallPlan = (registry, definitions) => {
         ...regularDefinitions,
         ...enhancerDefinitions,
     ];
+    // Validate the complete ownership transition before mutating the caller's registry.
     const validationRegistry = createRendererRegistry(registry.list());
     plannedDefinitions.forEach(definition => validationRegistry.register(definition));
     return { definitions: plannedDefinitions };
@@ -327,6 +328,13 @@ export const hasFileViewerRendererPresetName = (input) => {
     }
     return false;
 };
+/**
+ * Normalizes `options.preset` / `options.presets` into renderer plugin inputs.
+ *
+ * Passing a preset object is the most portable integration style because it
+ * works in any bundler. String selectors intentionally only resolve presets
+ * that are already registered by a side-effect import or by build tooling.
+ */
 export const resolveFileViewerRendererPresetInputs = (input) => {
     if (!input) {
         return [];

package/dist/renderers/image.d.ts

@@ -1,2 +1,2 @@
-import type { FileRenderContext, FileViewerRenderedInstance } from "../contracts/types.js";
+import type { FileRenderContext, FileViewerRenderedInstance } from '../contracts/types.js';
 export default function renderImage(buffer: ArrayBuffer, target: HTMLDivElement, type?: string, context?: FileRenderContext): Promise<FileViewerRenderedInstance>;

package/dist/renderers/image.js

@@ -1,8 +1,8 @@
-import { registerFileViewerZoomProvider, unregisterFileViewerZoomProvider, } from "../features/document/dom/index.js";
-import { installFileViewerImageHandTool } from "../features/document/imageHandTool.js";
-import { resolveFileViewerFitScale, } from "../features/document/fit.js";
-import { createFileViewerTranslator } from "../i18n/messages.js";
-import { createFileViewerZoomChangeEmitter as createZoomChangeEmitter } from "../features/document/zoom.js";
+import { registerFileViewerZoomProvider, unregisterFileViewerZoomProvider, } from '../features/document/dom/index.js';
+import { installFileViewerImageHandTool } from '../features/document/imageHandTool.js';
+import { resolveFileViewerFitScale, } from '../features/document/fit.js';
+import { createFileViewerTranslator } from '../i18n/messages.js';
+import { createFileViewerZoomChangeEmitter as createZoomChangeEmitter } from '../features/document/zoom.js';
 const imageMimeMap = {
     avif: 'image/avif',
     bmp: 'image/bmp',
@@ -201,6 +201,8 @@ export default async function renderImage(buffer, target, type, context) {
         applyImageZoom();
         zoomEmitter.emit();
     };
+    // Zoom subscribers may resize the parent toolbar. Keep geometry writes out
+    // of ResizeObserver delivery so ancestor notifications remain deliverable.
     const scheduleViewportUpdate = () => {
         if (destroyed || viewportResizeFrame !== null)
             return;

package/dist/renderers/index.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerBuiltinRendererPreset, FileRenderHandler, FileViewerRenderedInstance } from "../contracts/types.js";
+import type { FileViewerBuiltinRendererPreset, FileRenderHandler, FileViewerRenderedInstance } from '../contracts/types.js';
 type CoreBrowserRendererHandler = FileRenderHandler<FileViewerRenderedInstance, HTMLDivElement>;
 interface CoreBrowserRendererHandlerEntry {
     rendererId: string;

package/dist/renderers/index.js

@@ -1,17 +1,23 @@
-import { DEFAULT_RENDERER_DEFINITIONS } from "../registry/formats.js";
-import { createFileRenderHandlerRegistry } from "../rendering/handler.js";
-import { createFileViewerRendererDispatcher } from "../rendering/dispatcher.js";
-import { createFileViewerUnsupportedState } from "../viewer/state.js";
+// Browser renderer strategy registry.
+//
+// Each entry lazy-loads a concrete renderer only after its format is selected.
+// Keep renderer-specific dependencies inside the leaf renderer files so the
+// core shell and framework wrappers stay fast on first load.
+import { DEFAULT_RENDERER_DEFINITIONS } from '../registry/formats.js';
+import { createFileRenderHandlerRegistry } from '../rendering/handler.js';
+import { createFileViewerRendererDispatcher } from '../rendering/dispatcher.js';
+import { createFileViewerUnsupportedState } from '../viewer/state.js';
 const createWrapper = (el) => ({
     $el: el,
     unmount() {
+        // DOM renderers clean themselves up through their own returned instance.
     },
 });
 export const coreBrowserRendererHandlers = [
     {
         rendererId: 'image',
         handler: async (buffer, target, type, context) => {
-            const { default: renderImage } = await import("./image.js");
+            const { default: renderImage } = await import('./image.js');
             return renderImage(buffer, target, type, context);
         },
     },

package/dist/rendering/dispatcher.d.ts

@@ -1,8 +1,13 @@
-import type { RendererRegistry } from "../contracts/types.js";
+import type { RendererRegistry } from '../contracts/types.js';
 export interface FileViewerRendererHandlerEntry<Handler> {
     rendererId: string;
     handler: Handler;
 }
+/**
+ * Content-signature aware renderers can throw this shape when the filename
+ * extension points at the wrong container. The orchestration layer follows the
+ * redirect once, using the handler registered for the detected renderer id.
+ */
 export interface FileViewerRendererRedirectError extends Error {
     actualRendererId: string;
 }

package/dist/rendering/dispatcher.js

@@ -1,6 +1,6 @@
-import { DEFAULT_RENDERER_DEFINITIONS } from "../registry/formats.js";
-import { createRendererRegistry } from "../registry/registry.js";
-import { normalizeFileExtension } from "../source/index.js";
+import { DEFAULT_RENDERER_DEFINITIONS } from '../registry/formats.js';
+import { createRendererRegistry } from '../registry/registry.js';
+import { normalizeFileExtension } from '../source/index.js';
 export const resolveFileViewerRendererRedirectId = (error) => {
     if (!error || typeof error !== 'object' || !('actualRendererId' in error)) {
         return undefined;

package/dist/rendering/handler.d.ts

@@ -1,6 +1,6 @@
-import type { FileViewerRendererDispatcher } from "./dispatcher.js";
-import { type FileViewerMutableAccessor, type MutableFileViewerRenderReadinessState } from "../source/loading.js";
-import type { FileRenderExportAdapter, FileRenderThumbnailAdapter, FileRenderContext, FileRenderHandler, FileViewerLifecycleContext, FileViewerOptions, FileViewerStyleIsolation, RenderSurface, RendererDefinition, RendererLoadContext, RendererLoader, RendererRegistry, RendererSession } from "../contracts/types.js";
+import type { FileViewerRendererDispatcher } from './dispatcher.js';
+import { type FileViewerMutableAccessor, type MutableFileViewerRenderReadinessState } from '../source/loading.js';
+import type { FileRenderExportAdapter, FileRenderThumbnailAdapter, FileRenderContext, FileRenderHandler, FileViewerLifecycleContext, FileViewerOptions, FileViewerStyleIsolation, RenderSurface, RendererDefinition, RendererLoadContext, RendererLoader, RendererRegistry, RendererSession } from '../contracts/types.js';
 export declare const FILE_VIEWER_RENDER_SESSION_DISPOSE_ERROR_MESSAGE = "\u9884\u89C8\u5185\u5BB9\u5378\u8F7D\u5931\u8D25";
 export interface ResolveFileViewerRenderSessionDisposeErrorMessageInput {
     message?: string;
@@ -21,6 +21,7 @@ export interface RenderFileViewerHandlerInput<Rendered = unknown, Target extends
 export interface CreateFileRenderHandlerLoaderOptions<Rendered = unknown, Target extends HTMLElement = HTMLElement> {
     handler: FileRenderHandler<Rendered, Target>;
     rendererId?: string;
+    /** Allows stream-preferred handlers to receive an empty buffer plus context.streamUrl. */
     allowUrlSource?: boolean;
     getTarget?: (context: RendererLoadContext) => Target;
     createContext?: (context: RendererLoadContext) => FileRenderContext;
@@ -60,6 +61,10 @@ export interface FileViewerStyleHandle {
     remove(): void;
 }
 export interface AppendFileViewerStyleOptions {
+    /**
+     * Constructable stylesheets are useful for long-lived ShadowRoots. Keep this
+     * opt-in so renderer styles still clean up naturally with their target node.
+     */
     adoptedStyleSheet?: boolean;
 }
 export interface ResetFileViewerRenderSurfaceInput<Session extends RendererSession = RendererSession> {
@@ -164,6 +169,11 @@ export interface CreateFileViewerRenderSurfaceActionHandlersInput<Session extend
 export declare const DEFAULT_FILE_VIEWER_RENDER_TARGET_CLASS = "file-render";
 export declare const FILE_VIEWER_RENDER_SURFACE_BACKGROUND_PROPERTY = "--file-viewer-render-surface-background";
 export declare const normalizeFileViewerRenderSurfaceBackground: (value: unknown) => string | null;
+/**
+ * Keeps the public UI option and the renderer-facing CSS custom property in
+ * sync. Custom properties inherit through Shadow DOM, so setting this on the
+ * render host covers both scoped and shadow-isolated renderer targets.
+ */
 export declare const syncFileViewerRenderSurfaceBackground: (target: HTMLElement | null | undefined, options?: Pick<FileViewerOptions, "ui"> | null) => string | null;
 export declare const isFileViewerShadowRoot: (value: unknown) => value is ShadowRoot;
 export declare const getFileViewerShadowRootForNode: (node: Node | null | undefined) => ShadowRoot | null;

package/dist/rendering/handler.js

@@ -1,12 +1,17 @@
-import { DEFAULT_RENDERER_DEFINITIONS } from "../registry/formats.js";
-import { waitForFileViewerNextPaint } from "../output/export.js";
-import { createFileViewerRendererDispatcher } from "./dispatcher.js";
-import { resolveFileViewerRendererRedirectId } from "./dispatcher.js";
-import { createRendererRegistry } from "../registry/registry.js";
-import { getExtension, normalizeFileExtension } from "../source/index.js";
-import { applyFileViewerRenderReadinessState, } from "../source/loading.js";
-import { findFileViewerViewStateProvider } from "../features/document/dom/index.js";
-import { registerFileViewerGenericViewStateProvider } from "../features/document/viewState.js";
+// Rendering orchestration layer.
+//
+// This module adapts registry entries into disposable renderer sessions. It is
+// the only place that should bridge raw buffers, DOM targets, render contexts,
+// export adapters, and readiness state.
+import { DEFAULT_RENDERER_DEFINITIONS } from '../registry/formats.js';
+import { waitForFileViewerNextPaint } from '../output/export.js';
+import { createFileViewerRendererDispatcher } from './dispatcher.js';
+import { resolveFileViewerRendererRedirectId } from './dispatcher.js';
+import { createRendererRegistry } from '../registry/registry.js';
+import { getExtension, normalizeFileExtension } from '../source/index.js';
+import { applyFileViewerRenderReadinessState, } from '../source/loading.js';
+import { findFileViewerViewStateProvider } from '../features/document/dom/index.js';
+import { registerFileViewerGenericViewStateProvider } from '../features/document/viewState.js';
 export const FILE_VIEWER_RENDER_SESSION_DISPOSE_ERROR_MESSAGE = '预览内容卸载失败';
 export const DEFAULT_FILE_VIEWER_RENDER_TARGET_CLASS = 'file-render';
 export const FILE_VIEWER_RENDER_SURFACE_BACKGROUND_PROPERTY = '--file-viewer-render-surface-background';
@@ -19,6 +24,11 @@ export const normalizeFileViewerRenderSurfaceBackground = (value) => {
     const normalized = value.trim();
     return normalized && normalized.toLowerCase() !== 'auto' ? normalized : null;
 };
+/**
+ * Keeps the public UI option and the renderer-facing CSS custom property in
+ * sync. Custom properties inherit through Shadow DOM, so setting this on the
+ * render host covers both scoped and shadow-isolated renderer targets.
+ */
 export const syncFileViewerRenderSurfaceBackground = (target, options) => {
     var _a;
     if (!target) {
@@ -151,6 +161,8 @@ export const appendFileViewerStyle = (target, css, options = {}) => {
     const shadowRoot = getFileViewerShadowRootForNode(target);
     const StyleSheet = shadowRoot ? getConstructableStyleSheet(shadowRoot) : null;
     if (options.adoptedStyleSheet && shadowRoot && StyleSheet) {
+        // Use the target document's constructor. A stylesheet constructed in the
+        // parent window cannot be adopted by a ShadowRoot owned by an iframe.
         const sheet = new StyleSheet();
         sheet.replaceSync(css);
         shadowRoot.adoptedStyleSheets = [...shadowRoot.adoptedStyleSheets, sheet];

package/dist/security/svgResources.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Keep ordinary SVG styles while preventing imports and resource requests.
+ * Obfuscated URL tokens fail closed instead of depending on parser quirks.
+ */
 export declare const sanitizeFileViewerSvgCss: (value: string) => string;
+/** Remove executable attributes and every SVG resource URL that can load data remotely. */
 export declare const sanitizeFileViewerSvgResources: (root: ParentNode) => void;
+/**
+ * Mermaid 11 resolves image-node URLs with `new Image()` while rendering,
+ * before its SVG can be sanitized. Reject image metadata and explicit remote
+ * URLs before calling Mermaid so an untrusted diagram cannot initiate I/O.
+ */
 export declare const assertFileViewerMermaidSourceHasNoExternalResources: (source: string) => void;

package/dist/security/svgResources.js

@@ -44,6 +44,10 @@ const isSafeSvgCssUrl = (value) => {
         /^blob:/i.test(normalized) ||
         SAFE_EMBEDDED_IMAGE_DATA_URL.test(normalized);
 };
+/**
+ * Keep ordinary SVG styles while preventing imports and resource requests.
+ * Obfuscated URL tokens fail closed instead of depending on parser quirks.
+ */
 export const sanitizeFileViewerSvgCss = (value) => {
     const normalizedCharacters = [];
     for (const character of value) {
@@ -89,6 +93,7 @@ export const sanitizeFileViewerSvgCss = (value) => {
     chunks.push(normalized.slice(segmentStart));
     return chunks.join('');
 };
+/** Remove executable attributes and every SVG resource URL that can load data remotely. */
 export const sanitizeFileViewerSvgResources = (root) => {
     root.querySelectorAll('*').forEach(element => {
         for (const attribute of Array.from(element.attributes)) {
@@ -155,10 +160,17 @@ const canonicalizeMermaidSourceForResourceScan = (source) => {
     }
     return output;
 };
+/**
+ * Mermaid 11 resolves image-node URLs with `new Image()` while rendering,
+ * before its SVG can be sanitized. Reject image metadata and explicit remote
+ * URLs before calling Mermaid so an untrusted diagram cannot initiate I/O.
+ */
 export const assertFileViewerMermaidSourceHasNoExternalResources = (source) => {
     const normalized = canonicalizeMermaidSourceForResourceScan(String(source || ''));
     const compact = normalized.replace(/[\t\r\n ]+/g, '');
     const hasImageMetadata = /(?:^|[,{])\s*(?:img|["']img["'])\s*:/im.test(normalized);
+    // HTML math labels are created by Mermaid before its SVG is returned. Reject
+    // loading elements even when their URL uses entities or a relative path.
     const hasLoadingElement = /<\s*(?:img|image|iframe|object|embed|video|audio|source|link|script|style)\b/i.test(normalized);
     const hasRemoteUrl = /(?:https?|ftp):\/\//i.test(compact) ||
         /(?:^|[\s"'(=:,])(?:\/\/|\\\\)[A-Za-z0-9]/m.test(normalized);

package/dist/source/index.d.ts

@@ -1,6 +1,6 @@
-import type { FileViewerFileRef, FileViewerSource, NormalizedFileViewerSource } from "../contracts/types.js";
-export { DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING, createFileViewerTextDecoder, decodeFileViewerTextBuffer, isSingleByteFileViewerTextEncoding, isValidFileViewerUtf8, resolveFileViewerTextEncoding, } from "./textEncoding.js";
-export type { DecodedFileViewerText, FileViewerSingleByteTextEncoding, FileViewerTextEncoding, ResolvedFileViewerTextEncoding, ResolvedFileViewerTextSource, } from "./textEncoding.js";
+import type { FileViewerFileRef, FileViewerSource, NormalizedFileViewerSource } from '../contracts/types.js';
+export { DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING, createFileViewerTextDecoder, decodeFileViewerTextBuffer, isSingleByteFileViewerTextEncoding, isValidFileViewerUtf8, resolveFileViewerTextEncoding, } from './textEncoding.js';
+export type { DecodedFileViewerText, FileViewerSingleByteTextEncoding, FileViewerTextEncoding, ResolvedFileViewerTextEncoding, ResolvedFileViewerTextSource, } from './textEncoding.js';
 export type FileViewerReadResult = string | ArrayBuffer | undefined | null;
 export declare const DEFAULT_FILE_VIEWER_SOURCE_FILENAME = "preview.bin";
 export declare const normalizeFileExtension: (extension: string) => string;

package/dist/source/index.js

@@ -1,4 +1,4 @@
-export { DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING, createFileViewerTextDecoder, decodeFileViewerTextBuffer, isSingleByteFileViewerTextEncoding, isValidFileViewerUtf8, resolveFileViewerTextEncoding, } from "./textEncoding.js";
+export { DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING, createFileViewerTextDecoder, decodeFileViewerTextBuffer, isSingleByteFileViewerTextEncoding, isValidFileViewerUtf8, resolveFileViewerTextEncoding, } from './textEncoding.js';
 export const DEFAULT_FILE_VIEWER_SOURCE_FILENAME = 'preview.bin';
 export const normalizeFileExtension = (extension) => {
     return extension.trim().replace(/^\./, '').toLowerCase();

package/dist/source/loading.d.ts

@@ -1,7 +1,7 @@
-import type { FileViewerFileRef, FileViewerLifecycleContext, FileViewerPdfOptions } from "../contracts/types.js";
-import { type FileViewerLifecycleStateController } from "../lifecycle/operations.js";
-import { type FileViewerErrorMessageFormatter } from "../viewer/state.js";
-import type { FileViewerI18nInput } from "../i18n/messages.js";
+import type { FileViewerFileRef, FileViewerLifecycleContext, FileViewerPdfOptions } from '../contracts/types.js';
+import { type FileViewerLifecycleStateController } from '../lifecycle/operations.js';
+import { type FileViewerErrorMessageFormatter } from '../viewer/state.js';
+import type { FileViewerI18nInput } from '../i18n/messages.js';
 export declare const DEFAULT_PDF_RANGE_CHUNK_SIZE: number;
 export declare const DEFAULT_FILE_VIEWER_STREAMING_PDF_FILENAME = "preview.pdf";
 export declare const FILE_VIEWER_REMOTE_MISSING_DATA_ERROR_MESSAGE = "\u6587\u4EF6\u4E0B\u8F7D\u5931\u8D25";

package/dist/source/loading.js

@@ -1,7 +1,7 @@
-import { buildFileViewerLifecycleContext, } from "../lifecycle/operations.js";
-import { resolveFileViewerPreviewMessages, } from "../viewer/state.js";
-import { translateFileViewerMessage } from "../i18n/messages.js";
-import { DEFAULT_FILE_VIEWER_SOURCE_FILENAME, getExtension, normalizeFilename, normalizeFileExtension, readFileViewerBuffer, resolveFileViewerSourceFilename, wrapFileViewerFileRef, } from "./index.js";
+import { buildFileViewerLifecycleContext, } from '../lifecycle/operations.js';
+import { resolveFileViewerPreviewMessages, } from '../viewer/state.js';
+import { translateFileViewerMessage } from '../i18n/messages.js';
+import { DEFAULT_FILE_VIEWER_SOURCE_FILENAME, getExtension, normalizeFilename, normalizeFileExtension, readFileViewerBuffer, resolveFileViewerSourceFilename, wrapFileViewerFileRef, } from './index.js';
 export const DEFAULT_PDF_RANGE_CHUNK_SIZE = 64 * 1024;
 export const DEFAULT_FILE_VIEWER_STREAMING_PDF_FILENAME = 'preview.pdf';
 export const FILE_VIEWER_REMOTE_MISSING_DATA_ERROR_MESSAGE = '文件下载失败';
@@ -117,6 +117,7 @@ const encodeFileViewerUrlPathSegment = (segment) => {
         decoded = decodeURIComponent(segment);
     }
     catch {
+        // Invalid percent escapes are treated as literal filename characters.
     }
     return encodeURIComponent(decoded)
         .replace(/%3A/gi, ':')
@@ -606,6 +607,8 @@ export const runFileViewerRemoteFilePreview = async ({ url, filename, type, vers
     });
     const sourceUrl = remoteSource.url;
     const controller = requestController.createAbortController();
+    // The streaming helper finalizes its own load state; probe/download paths
+    // are finalized here, including cancellation before a renderer is mounted.
     let streamFinalized = false;
     try {
         if (!remoteSource.streamPdf && shouldStreamRemoteUrl) {

package/dist/source/precheck.d.ts

@@ -1,10 +1,14 @@
-import type { FileViewerFileRef, FileViewerSource } from "../contracts/types.js";
+import type { FileViewerFileRef, FileViewerSource } from '../contracts/types.js';
 export type FileViewerPrecheckStatus = 'ready' | 'invalid' | 'unsupported';
 export type FileViewerPrecheckReason = 'content-valid' | 'content-not-inspected' | 'content-inconclusive' | 'empty-structured-file' | 'signature-mismatch' | 'invalid-package' | 'missing-package-part' | 'unsupported-extension';
 export interface FileViewerPrecheckOptions {
+    /** Filename used when a Blob or ArrayBuffer has no name. */
     filename?: string;
+    /** Explicit extension, with or without a leading dot. */
     type?: string;
+    /** Restricts the result to the renderers installed by the host application. */
     supportedExtensions?: Iterable<string>;
+    /** Maximum ZIP central-directory bytes read from a Blob. Defaults to 8 MiB. */
     maxPackageMetadataBytes?: number;
 }
 export interface FileViewerPrecheckResult {
@@ -13,6 +17,7 @@ export interface FileViewerPrecheckResult {
     rendererId: string | null;
     supported: boolean;
     inspected: boolean;
+    /** `null` means the extension is supported but no structural validator exists. */
     valid: boolean | null;
     previewable: boolean;
     status: FileViewerPrecheckStatus;
@@ -20,5 +25,12 @@ export interface FileViewerPrecheckResult {
     missingParts: string[];
 }
 type FileViewerPrecheckInput = FileViewerSource | FileViewerFileRef;
+/**
+ * Performs a cheap, renderer-free capability and structure check.
+ *
+ * This intentionally does not promise rendering fidelity. A `ready` result
+ * means the extension is available and any known container/signature checks
+ * passed; the real renderer remains the final authority for malformed content.
+ */
 export declare const precheckFileViewerSource: (input: FileViewerPrecheckInput, options?: FileViewerPrecheckOptions) => Promise<FileViewerPrecheckResult>;
 export {};

package/dist/source/precheck.js

@@ -1,5 +1,5 @@
-import { DEFAULT_RENDERER_DEFINITIONS, DEFAULT_SUPPORTED_EXTENSIONS } from "../registry/formats.js";
-import { getExtension, normalizeFileExtension, normalizeFilename, normalizeSource, } from "./index.js";
+import { DEFAULT_RENDERER_DEFINITIONS, DEFAULT_SUPPORTED_EXTENSIONS } from '../registry/formats.js';
+import { getExtension, normalizeFileExtension, normalizeFilename, normalizeSource, } from './index.js';
 const DEFAULT_MAX_PACKAGE_METADATA_BYTES = 8 * 1024 * 1024;
 const ZIP_LOCAL_SIGNATURE = 0x04034b50;
 const ZIP_CENTRAL_SIGNATURE = 0x02014b50;
@@ -203,6 +203,13 @@ const inspectStructuredContent = async (source, extension, maxPackageMetadataByt
     }
     return { inspected: false, valid: null, reason: 'content-not-inspected' };
 };
+/**
+ * Performs a cheap, renderer-free capability and structure check.
+ *
+ * This intentionally does not promise rendering fidelity. A `ready` result
+ * means the extension is available and any known container/signature checks
+ * passed; the real renderer remains the final authority for malformed content.
+ */
 export const precheckFileViewerSource = async (input, options = {}) => {
     var _a;
     const source = toSource(input, options);

package/dist/source/textEncoding.d.ts

@@ -1,6 +1,15 @@
+/**
+ * Single-byte legacy encodings supported by the browser TextDecoder API.
+ * Each byte decodes to one UTF-16 code unit, so the virtual
+ * large-text renderer can slice them at any byte offset.
+ */
 export type FileViewerSingleByteTextEncoding = 'iso-8859-1' | 'iso-8859-2' | 'iso-8859-15' | 'windows-1250' | 'windows-1251' | 'windows-1252';
 export type FileViewerTextEncoding = 'auto' | 'utf-8' | 'utf-16le' | 'utf-16be' | 'gbk' | 'gb18030' | FileViewerSingleByteTextEncoding;
 export type ResolvedFileViewerTextEncoding = Exclude<FileViewerTextEncoding, 'auto' | 'gbk'>;
+/**
+ * Encoding used by `auto` when the bytes carry no BOM, do not look like
+ * UTF-16, and are not valid UTF-8. GB18030 keeps the historical behavior.
+ */
 export declare const DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING: ResolvedFileViewerTextEncoding;
 export declare const isSingleByteFileViewerTextEncoding: (encoding: string | undefined) => encoding is FileViewerSingleByteTextEncoding;
 export interface DecodedFileViewerText {
@@ -12,6 +21,15 @@ export interface ResolvedFileViewerTextSource {
     bomLength: number;
 }
 export declare const isValidFileViewerUtf8: (bytes: Uint8Array) => boolean;
+/**
+ * Picks the decoder for a text buffer.
+ *
+ * `encoding` other than `auto` is used as-is. In `auto` mode the order is:
+ * BOM, UTF-16 byte structure, strict UTF-8, then `fallbackEncoding`. The
+ * fallback defaults to GB18030; pass `windows-1252`, `windows-1251`, or
+ * another supported label for Latin, Cyrillic, or Central European legacy
+ * files, which are otherwise misread as CJK text.
+ */
 export declare const resolveFileViewerTextEncoding: (bytes: Uint8Array, encoding?: FileViewerTextEncoding | string, fallbackEncoding?: FileViewerTextEncoding | string) => ResolvedFileViewerTextSource;
 export declare const createFileViewerTextDecoder: (encoding: ResolvedFileViewerTextEncoding) => TextDecoder;
 export declare const decodeFileViewerTextBuffer: (data: ArrayBuffer, encoding?: FileViewerTextEncoding | string, fallbackEncoding?: FileViewerTextEncoding | string) => DecodedFileViewerText;