file-viewer3 1.0.8 → 1.0.26

package/LICENSE

@@ -0,0 +1,160 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work by
+the copyright owner or by an individual or Legal Entity authorized to submit on
+behalf of the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent to the
+Licensor or its representatives, including but not limited to communication on
+electronic mailing lists, source code control systems, and issue tracking systems
+that are managed by, or on behalf of, the Licensor for the purpose of discussing
+and improving the Work, but excluding communication that is conspicuously marked
+or otherwise designated in writing by the copyright owner as "Not a
+Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work to
+which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the Derivative
+Works; within the Source form or documentation, if provided along with the
+Derivative Works; or, within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents of the NOTICE
+file are for informational purposes only and do not modify the License. You may
+add Your own attribution notices within Derivative Works that You distribute,
+alongside or as an addendum to the NOTICE text from the Work, provided that such
+additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations and/or
+rights consistent with this License. However, in accepting such obligations, You
+may act only on Your own behalf and on Your sole responsibility, not on behalf of
+any other Contributor, and only if You agree to indemnify, defend, and hold each
+Contributor harmless for any liability incurred by, or claims asserted against,
+such Contributor by reason of your accepting any such warranty or additional
+liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Flyfish Viewer

package/README.en.md

@@ -0,0 +1,390 @@
+# Flyfish Viewer
+
+[Simplified Chinese](README.md) | [English](README.en.md)
+
+Bring Word, Excel, PowerPoint, PDF, Typst, archives, email, audio, ebooks, drawings, CAD, 3D models, Markdown, images, and source code preview into the browser with a clean, deployable viewer.
+
+`@flyfish-group/file-viewer3` is a pure frontend file preview component built with Vue 3, TypeScript, and Vite. Vue 2.7 projects should use the matching `@flyfish-group/file-viewer` package. The Vue 3 build is also the baseline runtime for the React, vanilla JavaScript, and iframe integration packages.
+
+The viewer does not require a backend conversion service. It is designed for OA systems, knowledge bases, attachment centers, workflow platforms, customer support portals, document approval flows, intranet systems, and offline-capable deployments where file preview should feel like a maintained product module rather than a temporary feature.
+
+- npm for Vue 3: [@flyfish-group/file-viewer3](https://www.npmjs.com/package/@flyfish-group/file-viewer3)
+- npm for Vue 2.7: [@flyfish-group/file-viewer](https://www.npmjs.com/package/@flyfish-group/file-viewer)
+- npm for React: [@flyfish-group/file-viewer-react](https://www.npmjs.com/package/@flyfish-group/file-viewer-react)
+- npm for vanilla JavaScript: [@flyfish-group/file-viewer-web](https://www.npmjs.com/package/@flyfish-group/file-viewer-web)
+- Official documentation: [doc.flyfish.dev](https://doc.flyfish.dev)
+- Online demo: [viewer.flyfish.dev](https://viewer.flyfish.dev)
+- Document comparison demo: [viewer.flyfish.dev/compare.html](https://viewer.flyfish.dev/compare.html)
+- Release downloads: [github.com/flyfish-dev/file-viewer/releases](https://github.com/flyfish-dev/file-viewer/releases)
+- GitHub artifact repository: [github.com/flyfish-dev/file-viewer](https://github.com/flyfish-dev/file-viewer)
+- Gitee artifact mirror: [gitee.com/flyfish-dev/file-viewer](https://gitee.com/flyfish-dev/file-viewer)
+- Source access and commercial customization: [https://dev.flyfish.group/shop](https://dev.flyfish.group/shop)
+
+## Current Packages
+
+| Stack | Package | Version | Recommended branch | Notes |
+| --- | --- | --- | --- | --- |
+| Vue 3 | `@flyfish-group/file-viewer3` | `1.0.25` | `v3` | Recommended version and the runtime baseline for React / vanilla JS iframe integrations |
+| Vue 2.7 | `@flyfish-group/file-viewer` | `1.0.25` | `main` | Vue 2 compatible package with the same format coverage and API semantics |
+| React 17 / 18 / 19 | `@flyfish-group/file-viewer-react` | `1.0.25` | adapter package | iframe component that loads `/file-viewer/index.html` by default |
+| Vanilla JavaScript | `@flyfish-group/file-viewer-web` | `1.0.25` | adapter package | iframe helpers and static viewer asset copier |
+
+For intranet or offline environments, this artifact repository also ships npm tarballs under `artifacts/`:
+
+```bash
+npm install ./artifacts/flyfish-group-file-viewer3-1.0.25.tgz
+npm install ./artifacts/flyfish-group-file-viewer-1.0.25.tgz
+npm install ./artifacts/flyfish-group-file-viewer-web-1.0.25.tgz
+npm install ./artifacts/flyfish-group-file-viewer-react-1.0.25.tgz
+```
+
+When installing the React tarball offline, install the same-version web tarball first because the React package depends on `@flyfish-group/file-viewer-web`.
+
+If you use pnpm 10 and see `Ignored build scripts: @flyfish-group/file-viewer-web`, run:
+
+```bash
+pnpm approve-builds
+```
+
+Then allow `@flyfish-group/file-viewer-web`, or manually copy the bundled viewer assets:
+
+```bash
+pnpm exec file-viewer-copy-assets ./public/file-viewer
+```
+
+GitHub Releases provide all distribution downloads:
+
+| File | Purpose |
+| --- | --- |
+| `file-viewer-v3-*-demo.tar.gz` | Main demo / iframe private deployment static site; extract it and use `/index.html?url=...` |
+| `file-viewer-v3-*-adapter-demo.tar.gz` | React / vanilla JavaScript adapter demo site |
+| `file-viewer-v3-*-lib-dist.tar.gz` | Vue 3 library dist for offline inspection or self-hosted packaging |
+| `file-viewer-v3-*-docs.tar.gz` | Documentation site static output |
+| `flyfish-group-file-viewer3-*.tgz` | Vue 3 local npm package |
+| `flyfish-group-file-viewer-*.tgz` | Vue 2.7 local npm package |
+| `flyfish-group-file-viewer-web-*.tgz` | Vanilla JavaScript iframe helper with viewer asset copy tooling |
+| `flyfish-group-file-viewer-react-*.tgz` | React iframe component; install the same-version web package together with it |
+
+![Flyfish Viewer demo](docs/_images/demo-main.png)
+
+## Why Use It
+
+- **Pure frontend and serverless.** File parsing and rendering happen in the browser. You do not need Office Server, a LibreOffice daemon, or a document conversion backend.
+- **Broad format coverage.** The current release maps 152 extensions across 20 preview pipelines, including Office, PDF, OFD, Typst, archives, email, EDA files, CAD, 3D models, Excalidraw, draw.io, EPUB, UMD, Markdown, images, audio, video, and source code.
+- **Lazy loaded renderers.** Heavy PDF, Office, OFD, Typst, archive, email, CAD, 3D, ebook, Markdown, and code highlighting dependencies are loaded only when the file type needs them.
+- **Production-ready operations.** The viewer includes original file download, full rendered printing, rendered HTML export, watermark options, theme options, lifecycle hooks, iframe events, and before-operation guards for permission checks.
+- **Better document reading.** Word and PDF keep a grey workspace, white paper surface, centered reading, width fitting, navigation, zoom, rotation, and complete print / HTML export paths.
+- **Renderer-native zoom controls.** The common toolbar can zoom in, zoom out, and reset through per-format providers for PDF, Word, PPTX, virtual Excel tables, images, CAD, OFD, Typst, Markdown, code, and drawing files, avoiding fragile host-level CSS transforms.
+- **Controlled theming.** `options.theme` supports `light`, `dark`, and `system`. Light business UIs can lock the viewer to `light` even when the operating system is in dark mode.
+- **PDF toolbar ergonomics.** `toolbar.position` supports `auto`, `top`, and `bottom-right`. In `auto` mode, PDF uses a bottom-right floating operation bar to avoid duplicating the PDF navigation toolbar.
+- **Demo and comparison views.** The repository includes the main demo and a standalone `/compare.html` page for side-by-side document comparison.
+- **Component and standalone modes.** Use it as a Vue component, or deploy the static viewer and embed it through iframe in any system.
+- **Artifact-first delivery.** This public repository contains minified build artifacts, static demos, documentation output, sample files, Docker deployment assets, and npm tarballs. It does not contain the private source tree.
+
+## Supported Formats
+
+The viewer is organized around preview pipelines rather than one-off file extensions.
+
+| Category | Extensions | Rendering pipeline | Typical use |
+| --- | --- | --- | --- |
+| Word | `docx`, `docm`, `dotx`, `dotm` | `docx-preview`, read-only page preview, print and HTML export | Modern Word documents and templates |
+| Legacy Word | `doc`, `dot` | `msdoc-viewer` with Word-like paper surface and CFB tolerance fixes | Old Word 97-2003 files |
+| Excel | `xlsx`, `xltx` | `styled-exceljs` plus virtual table rendering, merged cells, styles, auto text color, workbook images | Business spreadsheets and templates |
+| Excel-compatible | `xlsm`, `xlsb`, `xls`, `xlt`, `xltm`, `csv`, `ods`, `fods`, `numbers` | Progressive spreadsheet parsing and virtual rendering | Legacy spreadsheets and lightweight data preview |
+| PowerPoint | `pptx`, `pptm`, `potx`, `potm`, `ppsx`, `ppsm` | Slide preview with images, shapes, theme backgrounds, clipping, and EMF fallback | Presentations, training decks, proposals |
+| PDF | `pdf` | `pdfjs-dist`, streaming same-origin loading, Range support, zoom, rotation, page thumbnails, outline tree, width fitting, print, HTML export | Contracts, invoices, official layout documents |
+| OFD | `ofd` | Browser-side OFD preview based on `DLTech21/ofd.js` source | Chinese e-invoices, government documents, archives |
+| Typst | `typ`, `typst` | Direct Typst source rendering with browser WASM compiler and SVG pages | Technical reports, papers, engineering documents |
+| Archives | `zip`, `zipx`, `7z`, `rar`, `tar`, `gz`, `tgz`, `bz2`, `xz`, `zst`, `cab`, `iso`, `jar`, `apk`, `cbz`, `cbr`, and more | `libarchive.js` Worker, directory listing, lazy extraction, IndexedDB cache | Attachment packages and internal document bundles |
+| Email | `eml`, `msg` | `postal-mime` for EML, `@kenjiuno/msgreader` for MSG, headers, HTML/text body, attachment preview | Email archives and support tickets |
+| EDA | `olb`, `dra` | CFB-based OrCAD / Allegro structure inspection, trees, symbols, footprints, padstack candidates, properties, strings, diagnostics | Component libraries and EDA attachments |
+| CAD | `dwg`, `dxf`, `dwf`, `dwfx`, `xps` | `@flyfish-dev/cad-viewer` preview. DWG uses Worker + LibreDWG WASM, DXF uses a JS parser, and DWF/DWFx/XPS use the native `dwf-viewer` path for W2D/W3D/XPS graphics | Engineering drawings and AutoCAD archives |
+| 3D models | `glb`, `gltf`, `obj`, `stl`, `ply`, `fbx`, `dae`, `3ds`, `3mf`, `amf`, `usd`, `usda`, `usdc`, `usdz`, `kmz`, `pcd`, `wrl`, `vrml`, `xyz`, `vtk`, `vtp`, `step`, `stp`, `iges`, `igs`, `ifc`, `3dm` | Three.js interactive preview, with conversion guidance for heavy CAD/BIM kernels | 3D assets, point clouds, design models |
+| Excalidraw | `excalidraw` | Official `@excalidraw/excalidraw` restore and `exportToSvg` read-only rendering | Whiteboard sketches and product diagrams |
+| draw.io | `drawio`, `dio` | Official diagrams.net `GraphViewer` | Flowcharts and architecture diagrams |
+| EPUB | `epub` | `epubjs` table of contents and scrolling reader | Ebooks and long training materials |
+| UMD ebook | `umd` | UMD metadata, chapters, offsets, zlib text blocks | Legacy mobile ebooks |
+| Markdown | `md`, `markdown` | Markdown reading surface with theme-aware styles | README files and knowledge base articles |
+| Images | `gif`, `jpg`, `jpeg`, `bmp`, `tiff`, `tif`, `png`, `svg`, `webp` | Native image preview | Image attachments and design assets |
+| Source and text | `txt`, `json`, `js`, `mjs`, `cjs`, `css`, `java`, `py`, `html`, `htm`, `jsx`, `ts`, `tsx`, `xml`, `log`, `vue`, `yaml`, `yml`, `ini`, `sh`, `bash`, `sql`, `go`, `rs`, `php`, `c`, `cpp`, `cc`, `h`, `hpp`, `cs`, `diff` | Lightweight `highlight.js` language-specific highlighting, HTML shown as source | Logs, configs, code snippets, API responses |
+| Audio | `mp3`, `mpeg`, `wav`, `ogg`, `oga`, `opus`, `m4a`, `aac`, `flac`, `weba` | Native browser audio player | Recordings and audio attachments |
+| Video | `mp4` | Native browser video player | Screen recordings and demo videos |
+
+## Vue 3 Integration
+
+```bash
+npm install @flyfish-group/file-viewer3
+```
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import FileViewer from '@flyfish-group/file-viewer3'
+
+createApp(App).use(FileViewer).mount('#app')
+```
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const url = ref('/files/demo.pdf')
+
+const options = {
+  theme: 'light',
+  toolbar: { position: 'bottom-right', download: true, print: true, exportHtml: true },
+  watermark: { text: 'Internal Preview', opacity: 0.14 },
+  pdf: { streaming: 'same-origin', rangeChunkSize: 64 * 1024 }
+}
+</script>
+
+<template>
+  <div style="height: 100vh">
+    <file-viewer :url="url" :options="options" />
+  </div>
+</template>
+```
+
+For local files or authenticated downloads, pass a `File` object:
+
+```ts
+const response = await fetch('/api/files/contract', { credentials: 'include' })
+const blob = await response.blob()
+
+file.value = new File([blob], 'contract.pdf', { type: blob.type })
+```
+
+The filename matters. The viewer uses the extension to choose the correct rendering pipeline.
+
+## Vue 2.7 Integration
+
+```bash
+npm install @flyfish-group/file-viewer
+```
+
+```ts
+import Vue from 'vue'
+import FileViewer from '@flyfish-group/file-viewer'
+
+Vue.use(FileViewer)
+```
+
+```vue
+<template>
+  <div style="height: 100vh">
+    <file-viewer :url="url" :options="options" />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      url: '/files/demo.pdf',
+      options: {
+        theme: 'light',
+        toolbar: { position: 'bottom-right' }
+      }
+    }
+  }
+}
+</script>
+```
+
+The Vue 2 and Vue 3 package lines share the same user-facing capabilities and option semantics.
+
+## React Integration
+
+The React package is an iframe adapter. It reuses the Vue 3 baseline viewer that is bundled by `@flyfish-group/file-viewer-web`.
+
+```bash
+npm install @flyfish-group/file-viewer-react
+```
+
+```tsx
+import FileViewer from '@flyfish-group/file-viewer-react'
+
+export function Preview() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <FileViewer
+        url="/files/demo.pdf"
+        options={{
+          theme: 'light',
+          toolbar: { position: 'bottom-right' },
+          watermark: { text: 'Internal Preview', opacity: 0.14 }
+        }}
+        onViewerEvent={(event) => {
+          console.log(event.type, event.event, event.payload)
+        }}
+      />
+    </div>
+  )
+}
+```
+
+By default, the iframe loads `/file-viewer/index.html`. If your static assets are deployed elsewhere, pass `viewerUrl`.
+
+## Vanilla JavaScript Integration
+
+```bash
+npm install @flyfish-group/file-viewer-web
+```
+
+```html
+<div id="viewer" style="height: 100vh"></div>
+
+<script type="module">
+  import { mountViewerFrame } from '@flyfish-group/file-viewer-web'
+
+  mountViewerFrame(document.getElementById('viewer'), {
+    url: '/files/demo.pdf',
+    options: {
+      theme: 'light',
+      toolbar: { position: 'bottom-right' },
+      archive: { cache: true, workerTimeoutMs: 30000 }
+    },
+    onEvent(event) {
+      console.log(event.type, event.event, event.payload)
+    }
+  })
+</script>
+```
+
+The web package copies the static viewer into `public/file-viewer` during installation. If your package manager blocks install scripts, run:
+
+```bash
+npx file-viewer-copy-assets ./public/file-viewer
+```
+
+## iframe Protocol
+
+If you cannot use npm helpers, deploy the static viewer and pass a file URL through query parameters:
+
+```html
+<iframe
+  src="/file-viewer/index.html?url=%2Ffiles%2Fdemo.pdf&options=%7B%22theme%22%3A%22light%22%2C%22toolbar%22%3A%7B%22position%22%3A%22bottom-right%22%7D%7D"
+  style="width: 100%; height: 100vh; border: 0"
+></iframe>
+```
+
+For authenticated files, download the file in the host system and push a `Blob` to the iframe:
+
+```ts
+const viewerUrl = '/file-viewer/index.html'
+const viewerOrigin = location.origin
+const filename = 'contract.pdf'
+const options = { theme: 'light', toolbar: { position: 'bottom-right' } }
+const frame = document.getElementById('viewer') as HTMLIFrameElement
+
+frame.src =
+  `${viewerUrl}?name=${encodeURIComponent(filename)}` +
+  `&from=${encodeURIComponent(location.origin)}` +
+  `&options=${encodeURIComponent(JSON.stringify(options))}`
+
+frame.onload = async () => {
+  const response = await fetch('/api/files/contract', { credentials: 'include' })
+  const blob = await response.blob()
+  frame.contentWindow?.postMessage(blob, viewerOrigin)
+}
+```
+
+The viewer validates `event.origin === from` and only accepts `Blob` messages from the declared origin.
+
+## Core Options
+
+| Option | Description |
+| --- | --- |
+| `theme` | `light`, `dark`, or `system`. Default is `system`. Use `light` when embedding in a fixed light UI. |
+| `toolbar` | `true`, `false`, or an object that controls download, print, HTML export, unified zoom controls, and toolbar position. |
+| `toolbar.zoom` | Shows or hides the built-in zoom group. The actual capability is provided by each renderer, so unsupported or interaction-sensitive formats are not force-scaled. |
+| `toolbar.position` | `auto`, `top`, or `bottom-right`. Default `auto` floats the operation bar at bottom right for PDF and keeps other formats at top. |
+| `watermark` | Text or image watermark configuration. Watermark participates in preview, print, and exported HTML. |
+| `archive.workerUrl` | Custom `libarchive.js` Worker URL for special private deployments. By default the viewer tries `vendor/libarchive/worker-bundle.js` under the current base and falls back to the bundled Worker automatically. |
+| `archive.wasmUrl` | Custom libarchive WASM URL used by the bundled Worker fallback. |
+| `archive.workerTimeoutMs` | Worker initialization, encryption check, and directory-read timeout. Defaults to 30000ms and then falls back to ZIP/TAR/GZIP compatibility mode when possible. |
+| `archive.cache` | Enables IndexedDB cache for extracted archive entries. |
+| `archive.maxArchiveSize` | Maximum archive size allowed for directory parsing. |
+| `archive.maxEntryPreviewSize` | Maximum extracted entry size allowed for online preview. |
+| `pdf.streaming` | PDF URL loading strategy. Same-origin streaming is enabled by default. |
+| `pdf.rangeChunkSize` | PDF.js Range request chunk size. |
+| `typst.compilerWasmUrl` | Custom Typst compiler WASM URL. |
+| `hooks` | Vue component lifecycle hooks for load and unload events. |
+| `beforeOperation` | Vue component guard before download, print, HTML export, or zoom actions. Return `false` to cancel. |
+
+React, vanilla JavaScript, and iframe integrations cannot serialize function hooks into query parameters. Use `onViewerEvent` or `onEvent` to receive lifecycle and operation events from the iframe.
+
+## Printing, Exporting, and Watermarks
+
+- Download keeps the original file bytes. It does not write rendered output back into the source file.
+- Print opens a print-only document containing the rendered body and watermark, without the demo shell or host UI.
+- PDF print and HTML export use a dedicated adapter that renders complete pages rather than only the visible canvas.
+- Word print and HTML export preserve the white paper surface and page sizing while removing preview-only layout wrappers.
+- Spreadsheet, archive, email, EPUB, audio, video, and 3D pipelines hide unreliable print buttons when the full document cannot be printed consistently.
+- HTML export clones the current rendered output and converts canvas content where possible.
+
+## Document Comparison
+
+The production demo includes a standalone comparison page:
+
+[https://viewer.flyfish.dev/compare.html](https://viewer.flyfish.dev/compare.html)
+
+It supports two-pane document preview, built-in samples, URL input, local upload, swapping panes, reset, and synchronized scrolling. The comparison page is intentionally separate from the main viewer entry so that the primary component API stays small and predictable.
+
+## Private Deployment
+
+For npm-based iframe integrations, make sure your final static output contains:
+
+```txt
+file-viewer/index.html
+file-viewer/assets/*
+file-viewer/vendor/libarchive/worker-bundle.js  # optional unless you want a static Worker path
+file-viewer/vendor/libarchive/libarchive.wasm   # keep next to worker-bundle.js when using archive.workerUrl
+```
+
+The artifact repository also contains:
+
+| Path | Purpose |
+| --- | --- |
+| `dist/` | Minified library build artifacts |
+| `demo/` | Static production demo, including `index.html` and `compare.html` |
+| `adapter-demo/` | React and vanilla JavaScript integration demo |
+| `docs/` | Static documentation site output |
+| `example/` | Sample files used by the demo |
+| `artifacts/` | npm tarballs and packaged static build archives |
+| `README.md` | Default Chinese documentation |
+| `README.en.md` | English documentation |
+| `LICENSE` | Apache-2.0 license |
+
+## Docker
+
+The project provides a static nginx runtime image and build scripts for `linux/amd64` and `linux/arm64`. A typical deployment can serve the demo and comparison page directly:
+
+```bash
+docker run --rm -p 8080:80 flyfishdev/file-viewer:1.0.25
+```
+
+Then open:
+
+```txt
+http://localhost:8080/
+http://localhost:8080/compare.html
+```
+
+If you build the image yourself, use the provided `Dockerfile` and keep the static viewer assets, examples, and vendor WASM files together.
+
+## Public Artifacts vs Source Code
+
+This public repository is for artifact delivery. It contains minified build output, static demo sites, sample files, documentation output, and npm tarballs. It intentionally does not include the private source tree. The Gitee mirror is synchronized from a clean latest-artifact snapshot when needed, so domestic users can clone the full expanded artifact repository without inheriting oversized binary release history.
+
+If you need source code access, second development resources, or commercial customization, use the self-service source access portal:
+
+[https://dev.flyfish.group/shop](https://dev.flyfish.group/shop)
+
+The self-service source access price is 4.99. It is designed to make legitimate second development and commercial evaluation straightforward without mixing source delivery into the public artifact repository.
+
+## License and Attribution
+
+Flyfish Viewer is distributed under the Apache-2.0 license. You may use the public artifacts according to that license.
+
+For second development or commercial use, please keep clear attribution to Flyfish Viewer and contribute useful fixes or compatibility improvements back whenever possible. This keeps the preview ecosystem healthier for everyone using the component in real business systems.