filens-preview 0.2.0 → 0.3.1

package/README.md

@@ -1,14 +1,27 @@
 # Standalone browser previews / 独立前端预览
 
-Build the same preview engines as a single JavaScript file or split modules. Both
+Build the same preview engines as one main JavaScript file or split modules,
+with an optional external archive engine in either build. Both
 include Vue, styles, PDF/iWork workers and the document, image/RAW and STEP WASM
 engines. No conversion server or host Vue installation is needed.
 
+For iOS and Android application embedding, the [source SDKs](../../sdk/README.zh-CN.md)
+wrap this same runtime in native views, with local file loading and lifecycle callbacks.
+
+Version **0.3.0** adds the mobile source SDK integration, encrypted / solid / multipart
+RAR and 7z previews, Office attachment previews, smaller embedded WASM, shared ZIP
+loading and the default `FiLens © IceWhale` watermark. The optional archive engine
+and its worker stay external in both runtime builds.
+
 Version 0.2.0 adds 28 toolbar languages, application-icon previews and the
 runtime fixes used by CLI 0.5.0's offline HTML preview. It uses native HEIC/HEIF decoding first, with a small dedicated WASM
 decoder as fallback. MOV plays through browser codecs.
 Applications can supply an optional `mediaConverter` for unsupported MOV codecs.
 Both builds preserve the same image and video support boundaries.
+For optional local MP4/MOV recovery, pass `browserMedia: true` to `createPreview`.
+It tries native playback first, then bounded remuxing or necessary WebCodecs AVC
+processing, and never calls `mediaConverter` for video in this mode.
+[Browser-only media scope and validation](../../docs/browser-media-engine.md).
 
 ```sh
 npm install filens-preview
@@ -30,14 +43,30 @@ npm run build:wasm
 npm run build:preview
 ```
 
-| Build | Deploy | Approximate runtime size |
-| --- | --- | --- |
-| Split | Entire `packages/preview/dist/split/` directory | 11.05 MB raw / 3.20 MB gzip / 2.52 MB Brotli, across all runtime files |
-| All in one | `packages/preview/dist/all-in-one/filens.js` | 12.68 MB raw / 3.77 MB gzip / 2.83 MB Brotli |
+Deploy the entire `packages/preview/dist/split/` directory, or
+`dist/all-in-one/filens.js` with the archive sidecars when needed. The following
+table is generated by `npm run report:preview-sizes` from exact byte measurements.
+
+<!-- preview-runtime-sizes:start -->
+| Runtime | Raw MB | gzip MB | Brotli MB |
+| --- | ---: | ---: | ---: |
+| Split main runtime | 10.55 | 3.34 | 2.67 |
+| All-in-one main JS | 8.05 | 3.34 | 3.02 |
+| Optional archive WASM + worker (either build) | 0.88 | 0.35 | 0.28 |
+| Split with archive assets | 11.44 | 3.69 | 2.94 |
+| All-in-one with archive assets | 8.93 | 3.69 | 3.30 |
+<!-- preview-runtime-sizes:end -->
 
 These are current source build measurements (MB = 1,000,000 bytes), including
 application icons, optional Office decryption and 28 locale dictionaries. The
-npm package contains both directories, including notices, types and
+archive engine always stays external, including all-in-one builds, and is loaded
+only for RAR, 7z or multi-volume ZIP. Ordinary ZIP and ZIP-based document formats
+share the existing JSZip/fflate dependencies. The extraction-only engine uses
+-O3 and LTO, retains encryption and all supported decoders, and shares its compiled
+WASM module between fresh per-operation workers. iWork uses the ordinary ZIP
+reader without duplicating the ZIP encryption library. The totals in the table
+include the optional archive assets and exclude notices.
+The npm package contains both directories, including notices, types and
 documentation. Packed and installed bytes are recorded for each release.
 [Package measurements](https://github.com/IceWhaleTech/filens/blob/main/docs/preview-package-sizes.json).
 
@@ -67,10 +96,15 @@ directory over HTTP(S). To integrate into another page:
 uses the bundled frontend WASM engines. Use [`@filens/vue`](https://github.com/IceWhaleTech/filens/tree/main/packages/vue) for
 direct Vue component integration.
 
+Previews display a translucent `FiLens © IceWhale` watermark at the bottom right,
+including when the toolbar is hidden and in preview fullscreen mode.
+
 Split chunks can range from a few KB to hundreds of KB after compression. Those
 figures exclude shared dependencies and engines; a chunk is not a complete
-per-format download. The all-in-one file embeds CSS, base64 WASM and workers; it
-needs no additional runtime files.
+per-format download. The all-in-one file embeds CSS and document/image engines.
+The RAR/7z engine and its worker are always separate files, never base64-embedded;
+deploy both sidecars alongside the main JS to enable RAR, 7z and multi-volume ZIP.
+They can be omitted when those formats are not required.
 A separate notices file accompanies
 both builds and should be distributed with them. [Exact measurements](https://github.com/IceWhaleTech/filens/blob/main/docs/preview-build-sizes.json).
 
@@ -79,6 +113,8 @@ Pages with a Content Security Policy must permit the generated inline styles,
 `blob:` workers and `data:` WASM. Use an HTTP(S) server for module imports, rather
 than opening the module-importing `index.html` as a `file:` URL. The CLI's
 self-contained HTML embeds the module instead and supports `file:` URLs.
+RAR, 7z and multi-volume ZIP require the separate archive assets over HTTP(S);
+CLI HTML shows a `--mode serve` fallback for them instead of embedding the engine.
 The supported formats and fidelity
 limits are shared with the [demo](https://github.com/IceWhaleTech/filens/blob/main/docs/support-matrix.md).
 
@@ -91,20 +127,36 @@ detection. Switch language with `viewer.update({ locale: 'de_DE' })`. Optional
 Both split and all-in-one builds contain these dictionaries for offline use.
 See the [locale list and API notes](../vue/README.md#languages-source-build).
 
-APK/IPA packages and Windows EXE/DLL/MUI/MUN resource files can be previewed as
-application icons using the included WASM converter. Icon extraction supports
-compiled Android icon resources, XML/binary iOS plist metadata, iOS CgBI PNGs,
+APK/IPA packages open as ZIP-compatible archives with directory browsing and
+entry previews. Windows EXE/DLL/MUI/MUN resource files can be previewed as
+application icons using the included WASM converter. The converter also exposes
+APK/IPA icon extraction for explicit requests. Icon extraction supports compiled
+Android icon resources, XML/binary iOS plist metadata, iOS CgBI PNGs,
 and Windows PNG/DIB icon frames. These additions are included in 0.2.0.
 See the [supported icon representations
 and limits](../vue/README.md#application-icons-source-build).
 
+The browser file picker accepts multi-volume RAR (`.part01.rar` or `.rar`/`.r00`),
+7z (`.7z.001`) and ZIP (`.zip.001` or `.z01`/`.zip`) archives. Select every part
+together; picker order does not matter. Password prompts and nested previews
+work across the parts. Missing first/intermediate volumes identify the filename;
+the engine validates completeness. Limits are 256 parts and 512 MiB compressed
+input per set, with 128 MiB per expanded entry. Both HTTP(S)-served builds support
+this workflow with local archive sidecars; no remote service or CDN is used.
+Programmatic callers supply the other
+parts as `src.archiveVolumes: [{ name, source }]`; see the
+[core API example](../core/README.md).
+
 The split build loads `converter-office.wasm` only when an encrypted Office
 document has a supplied password; a password prompt alone does not download it.
 The core is about 413 KB gzip, and the optional decryptor about 164 KB gzip.
 Splitting saves about 64 KB gzip on ordinary converted previews, while downloading
 both costs about 100 KB gzip more than the combined core due to shared code.
 The all-in-one file uses the combined core (477 KB gzip / 387 KB Brotli) to avoid
-that duplication; its download includes decryption. See the
+that duplication; its download includes decryption. Embedded WASM is gzipped
+before base64 encoding and decompressed on first use, with a JavaScript fallback
+for browsers without DecompressionStream. HTTP split assets remain ordinary WASM
+and use streaming compilation when the server supplies the correct MIME. See the
 [same-source measurements](../../docs/converter-size-impact.md) and the
 [format package audit](../../docs/format-package-sizes.md).
 
@@ -199,17 +251,18 @@ macOS; Windows/Linux browser launching still needs native validation.
 ## 中文说明
 
 两种产物使用相同 API：分包版部署整个 `split/` 目录，WASM 与重型引擎按需加载；
-单文件版仅需部署 `all-in-one/filens.js`，其中包含 Vue、样式、Worker 和 WASM，
-另附第三方许可文件。单文件部署更简单，初次下载也更大。
+单文件版的 `all-in-one/filens.js` 包含 Vue、样式和文档/图片引擎，另附第三方许可文件。
+RAR/7z 和分卷 ZIP 始终使用独立的 `archive/7zz.wasm` 与 `assets/archive-worker-*.js`，
+按需加载，任何构建都不合并进主 JS。无需这些格式时可以省略这两个资源。
 
 `filens preview 文件路径` 会启动本地浏览器预览，由前端完成格式解析与渲染。
 CLI 0.5.0 首次预览时自动安装 filens-preview 0.2.0，也可先运行 `filens setup-preview`；
 源码版先运行 `npm run build:agent:preview`。
-当前源码构建中，分包运行时合计 2.52 MB Brotli，单文件为 2.83 MB Brotli / 3.77 MB gzip / 12.68 MB 原始体积，已包含安装包图标、可选 Office 解密模块和 28 个语言包。分包版仅在加密 Office 文档提交密码后加载解密模块；单文件版使用含解密功能的合并核心，避免重复代码。合并核心为 477 KB gzip / 387 KB Brotli，尚未达到约 300 KB 的目标。
+当前 0.3.0 构建的精确体积见上方自动生成表格，主运行时、可选压缩引擎和包含压缩引擎的总量分别计量。主运行时已包含安装包图标、可选 Office 解密模块和 28 个语言包。压缩引擎采用 O3 加 LTO，保留密码、固实压缩、分卷和所有原有解码器，移除写入功能及未使用的格式；复用编译模块，各操作仍使用独立 Worker 和内存。iWork 不再重复内嵌 ZIP 解密库。JSZip 使用源模块，让 ZIP 文档和 TIFF 共享同一份 pako，Three.js 与文档解析器共享 fflate。分包版仅在加密 Office 文档提交密码后加载解密模块；单文件版使用含解密功能的合并核心。自包含 HTML 不嵌入压缩引擎，RAR/7z 和分卷 ZIP 使用 `--mode serve`。
 独立 npm 包同时包含两种产物，[各版本包体积记录](../../docs/preview-package-sizes.json)。
 CLI 的安装体积另计：Lite 7.7–8.1 MiB，Full 31.1–36.8 MiB（含 OCR 运行时与模型）；
 其中原生可执行文件为 1.8–2.2 MiB，不含 Node.js、缓存及预览包。
-源码仅附带分包目录时约 11.6 MB（含许可文件与 HTML）。图片先尝试原生显示，分包版仅在失败时加载 HEIF 解码器；视频使用浏览器编解码器，不支持的编码可通过可选 mediaConverter 接入转换器。`--no-open --json` 返回本地地址，`--assets` 可切换单文件或分包版，
+图片先尝试原生显示，分包版仅在失败时加载 HEIF 解码器；视频使用浏览器编解码器，不支持的编码可通过可选 mediaConverter 接入转换器。`--no-open --json` 返回本地地址，`--assets` 可切换单文件或分包版，
 HTTP 模式下 Ctrl-C 退出。**CLI 0.5.0 默认生成携带原文件、预览引擎和许可说明的独立 HTML**，
 通过 `file://` 打开，生成后 CLI 退出，无需本地服务器，可完全离线使用。
 `--output preview.html` 保存到指定路径且不覆盖已有文件；默认临时 HTML 不会随 CLI