@file-viewer/vite-plugin 3.2.1 → 3.2.3

package/README.en.md

@@ -1,7 +1,198 @@
 # @file-viewer/vite-plugin
 
-Runtime package version 3.2.1.
+[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.zh-CN.md)
 
-Usage and API documentation: https://doc.file-viewer.app/guide/on-demand-renderers
+<!-- FILE_VIEWER_PACKAGE_HEADER -->
+<p>
+  <a href="https://www.npmjs.com/package/@file-viewer/vite-plugin"><img src="https://img.shields.io/npm/v/@file-viewer%2Fvite-plugin?logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@file-viewer/vite-plugin"><img src="https://img.shields.io/npm/dm/@file-viewer%2Fvite-plugin?logo=npm" alt="npm downloads"></a>
+  <a href="https://github.com/flyfish-dev/file-viewer/stargazers"><img src="https://img.shields.io/github/stars/flyfish-dev/file-viewer?style=flat&logo=github" alt="GitHub stars"></a>
+  <a href="https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
+</p>
 
-The package's own license is Apache-2.0. Included third-party notices apply to their respective components.
+<p>
+  <a href="https://github.com/flyfish-dev/file-viewer">GitHub</a> · <a href="https://doc.file-viewer.app/">Docs</a> · <a href="https://demo.file-viewer.app/">Live demo</a> · <a href="https://doc.file-viewer.app/guide/formats">Format matrix</a> · <a href="https://github.com/flyfish-dev/file-viewer/issues">Issues</a> · <a href="https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.zh-CN.md">简体中文</a>
+</p>
+
+<p>
+  <a href="https://demo.file-viewer.app/"><img src="https://raw.githubusercontent.com/flyfish-dev/file-viewer/main/docs/public/_media/file-viewer-demo-v3-en.webp" width="760" alt="File Viewer live demo: Word, Excel, PowerPoint, 3D model, CAD drawing and binary inspector"></a>
+</p>
+
+> ⭐ If File Viewer helps you, please [star the repo on GitHub](https://github.com/flyfish-dev/file-viewer).
+
+Vite plugin for Flyfish File Viewer on-demand renderer assembly. It can auto-discover installed `@file-viewer/preset-*` and `@file-viewer/*-full` packages, so Vue, React, Svelte, jQuery, and Vanilla JS components receive matching preview capability without application code passing `renderers` manually. It can also generate `virtual:file-viewer-renderers` from declared formats, import only matching renderer packages, and provide renderer-oriented chunk planning plus offline worker/WASM/font asset copying.
+
+## Fastest Start
+
+For complete format support, the fastest path is one full package and one Vite plugin registration. Full packages already include `preset-all`; do not install another preset. `copyAssets:true` matches the installed full package and publishes its Worker, WASM, font, and vendor files under `file-viewer/` at the deployment base (`/file-viewer/` for a root deployment) in both dev and build:
+
+```bash
+pnpm add @file-viewer/vue3-full
+pnpm add -D @file-viewer/vite-plugin
+```
+
+```ts
+import { defineConfig } from 'vite'
+import { fileViewerRenderers } from '@file-viewer/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fileViewerRenderers({
+      copyAssets: true
+    })
+  ]
+})
+```
+
+Installing a full package without publishing these assets leaves PDF Worker, CAD/Typst/Archive WASM, and other formats without runtime files. That is partial support, not a complete setup.
+
+For a smaller install, use a standard component with one preset and keep the same Vite config. The plugin auto-discovers installed presets, so application code does not hand-write renderer imports and the plugin does not need `preset:'office'`:
+
+```bash
+pnpm add @file-viewer/vue3 @file-viewer/preset-office
+pnpm add -D @file-viewer/vite-plugin
+```
+
+Components keep `autoRenderers:true` by default, so `@file-viewer/vue3`, `@file-viewer/react`, `@file-viewer/web`, `@file-viewer/svelte`, `@file-viewer/jquery`, `@file-viewer/vue2.7`, and `@file-viewer/vue2.6` automatically consume the injected preset / renderer registry.
+
+Available presets:
+
+- `@file-viewer/preset-lite`: text, Markdown, code, image, audio, and video.
+- `@file-viewer/preset-office`: PDF, Word, Excel, PowerPoint, OFD, RTF, and OpenDocument.
+- `@file-viewer/preset-engineering`: CAD, 3D, drawing, XMind, Geo, Typst, Archive, Data, and EDA.
+- `@file-viewer/preset-all`: the complete official demo format matrix.
+
+Install individual renderer packages only for strict cuts, such as `@file-viewer/renderer-pdf`, `@file-viewer/renderer-word`, `@file-viewer/renderer-ofd`, `@file-viewer/renderer-presentation`, `@file-viewer/renderer-cad`, `@file-viewer/renderer-drawing`, `@file-viewer/renderer-3d`, `@file-viewer/renderer-data`, `@file-viewer/renderer-eda`, `@file-viewer/renderer-typst`, `@file-viewer/renderer-archive`, or `@file-viewer/renderer-text`, then use `formats` to generate exact imports.
+
+## vite.config.ts
+
+Prefer full/preset auto assembly for normal products. With only `copyAssets:true`, the plugin auto-discovers installed `@file-viewer/*-full` or `@file-viewer/preset-*` packages:
+
+```ts
+fileViewerRenderers({
+  copyAssets: true
+})
+```
+
+Use customization options only when you need source scanning, single-format cuts, or manual registry control:
+
+```ts
+import { defineConfig } from 'vite'
+import { fileViewerRenderers } from '@file-viewer/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fileViewerRenderers({
+      formats: ['pdf', 'dwg', 'typst', 'zip', 'xmind'],
+      scan: true,
+      copyAssets: true,
+      chunkStrategy: 'renderer'
+    })
+  ]
+})
+```
+
+`inject` is enabled by default. The plugin injects `virtual:file-viewer-renderers` into Vite HTML entrypoints, preset imports register themselves in core, and framework components consume them through `autoRenderers`.
+
+```ts
+const options = {
+  // Defaults to true; set false when a product needs total manual control.
+  autoRenderers: true
+}
+```
+
+### Customization Options
+
+| Option | Description |
+| --- | --- |
+| `copyAssets` | `true` or `{ publicDir, outDir, mode, baseDir }`; copies matching Worker, WASM, font, and vendor assets. Installed full packages default to `<deployment-base>/file-viewer/`, which is required for complete full support; standard packages/presets keep the existing root behavior |
+| `preset` | `'auto' | 'lite' | 'office' | 'engineering' | 'all'`; with no explicit formats, installed presets are discovered automatically |
+| `autoPresets` | `true` or a preset list; useful with `scan:true` when installed presets should stay active |
+| `formats` | File extensions or format tokens, for example `['pdf', 'docx', 'dwg']` |
+| `renderers` | Renderer ids, for example `['pdf', 'word', 'cad']` |
+| `scan` | `true` or `{ roots, extensions, maxFileSize }`; scans source hints and merges formats |
+| `inject` | Defaults to `true`; set `false` to import `virtual:file-viewer-renderers` manually |
+| `chunkStrategy` | `'renderer' | 'none'`; controls renderer-level chunk grouping |
+| `stabilizeInteropChunks` | Defaults to `true`; keeps Pako / shared CommonJS helpers and CodeMirror / Lezer / Sandpack in stable groups for default and host-defined chunk splitting |
+| `missingRenderer` | `'error' | 'warn' | 'ignore'`; controls notices for planned renderer mappings |
+
+When host apps split `node_modules` by package name, circular dependencies between `@codemirror/*`, `@lezer/*`, and Sandpack can show up in production as `codemirror-view.* Cannot access ... before initialization`. The plugin stabilizes default chunk splitting and wraps existing `manualChunks` functions. Pako and shared CommonJS helpers use `vendor-commonjs` to prevent compressed-format initialization cycles; CodeMirror / Lezer / Sandpack use `vendor-codemirror`. Other custom groups remain intact, and Vite 8 receives equivalent Rolldown groups. Set `stabilizeInteropChunks:false` only when the host build needs total control.
+
+`copyAssets.baseDir` overrides automatic placement. It must be relative and cannot contain `..`; an empty string explicitly selects the root. The plugin now aligns the shared runtime asset base for standard packages, presets, and full packages; full packages also keep `setDefaultFullAssetBaseUrl()` synchronized. Only integrations that set `inject:false` and do not import the virtual module must call `setDefaultFileViewerAssetBaseUrl()` themselves (plus `setDefaultFullAssetBaseUrl()` for a full package). With Vite `base:'/app/'`, full-package dev URLs start with `/app/file-viewer/...`, while production files remain under `outDir/file-viewer/`.
+
+Asset copying runs at dev-server startup/restart and after a production build, not on ordinary HMR. Files with identical contents are left untouched, and generated manifests omit the volatile `copiedAt` timestamp. Vite's own output cleanup and public-directory copying remain unchanged.
+
+For strict registry control, disable injection and pass the virtual module explicitly:
+
+```ts
+fileViewerRenderers({
+  formats: ['pdf'],
+  inject: false,
+  copyAssets: true
+})
+```
+
+```ts
+import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'
+
+const options = {
+  rendererMode: 'replace',
+  renderers: configuredFileViewerRenderers
+}
+```
+
+You can also use `preset: 'auto'` to discover installed preset packages. When `preset-all` is installed, it wins to avoid importing narrower presets twice. Note: when `scan:true` is enabled, use `preset:'auto'` or `autoPresets:true` explicitly; otherwise the plugin treats source hints as the explicit renderer selection and skips zero-config preset discovery.
+
+```ts
+fileViewerRenderers({
+  preset: 'auto',
+  scan: true,
+  formats: ['pdf'],
+  copyAssets: true,
+  chunkStrategy: 'renderer'
+})
+```
+
+`scan: true` inspects common source folders for lightweight hints and merges them with `formats`:
+
+```ts
+export const fileViewerFormats = ['pdf', 'docx', 'xlsx']
+```
+
+```html
+<input accept=".pdf,.docx" data-file-viewer-formats="dwg,xmind" />
+```
+
+This is useful when upload accept lists, sample matrices, or attachment allow-lists already live in source code: dev and production builds can generate the renderer assembly module without a second hand-written import list.
+
+## Missing Renderer Guidance
+
+When a file extension is in the supported matrix but the current project has not assembled its renderer, core now shows an install-oriented “renderer assembly required” state with the recommended preset / renderer package. For example, `.pdf` points to `@file-viewer/preset-office` or `@file-viewer/renderer-pdf`. Only truly unknown extensions show an unsupported-format state.
+
+## Nested Vite Projects
+
+From 3.0.3, a nested metadata-only project can use a resolvable Full dependency
+declared in an ancestor `package.json`. A nearer light component or preset keeps
+its own root asset layout. Explicit `copyAssets.baseDir` still takes precedence;
+`publicDir` and `build.outDir` stay relative to the Vite root, not the dependency owner.
+
+## Current Boundary
+
+The plugin currently generates imports for extracted renderer packages: Word, Spreadsheet, PDF, OFD, Presentation, CAD, Draw.io/Excalidraw/Mermaid/PlantUML, 3D, Data, EDA, Typst, archives, email, EPUB, code/Markdown/Patch/Git Bundle, image, media, XMind, and Geo. Declare them explicitly with `formats`, or let `scan: true` discover source hints automatically; core-supported extensions such as `.zipx`, `.cbz`, `.tiff`, `.mjs`, `.gv`, `.patch`, `.bundle`, `.mermaid`, `.puml`, and `.mpeg` also resolve to their renderer packages. With `copyAssets:true`, the plugin detects installed capability packages. Full packages copy matching assets into dev `publicDir/file-viewer/` and production `outDir/file-viewer/`; standard packages/presets keep the existing root placement, including the Typst compiler / renderer WASM files and default fonts. `preset: 'auto' | 'lite' | 'office' | 'engineering' | 'all'` imports matching `@file-viewer/preset-*` packages; when `formats` are also present, the plugin adds extra renderers outside the preset.
+
+## Documentation
+
+- On-demand renderer architecture: <https://doc.file-viewer.app/guide/on-demand-renderers>
+- Supported formats: <https://doc.file-viewer.app/guide/formats>
+
+## Formats and related packages
+
+File Viewer previews 275+ file extensions in the browser, covering Office, PDF/OFD, CAD, 3D, archives, email, images, media and code, without server-side conversion. See the [format matrix](https://doc.file-viewer.app/guide/formats) for the full list.
+
+- Components: `@file-viewer/web`, `@file-viewer/vue3`, `@file-viewer/vue2.7`, `@file-viewer/vue2.6`, `@file-viewer/react`, `@file-viewer/react-legacy`, `@file-viewer/svelte`, `@file-viewer/jquery`, plus their `-full` packages
+- Presets: `@file-viewer/preset-lite`, `@file-viewer/preset-office`, `@file-viewer/preset-engineering`, `@file-viewer/preset-all`
+- Build: `@file-viewer/vite-plugin`, `file-viewer-copy-assets`
+
+## License
+
+This package is Apache-2.0. See [LICENSE](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE).

package/README.md

@@ -1,7 +1,198 @@
 # @file-viewer/vite-plugin
 
-Runtime package version 3.2.1.
+[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.zh-CN.md)
 
-Usage and API documentation: https://doc.file-viewer.app/guide/on-demand-renderers
+<!-- FILE_VIEWER_PACKAGE_HEADER -->
+<p>
+  <a href="https://www.npmjs.com/package/@file-viewer/vite-plugin"><img src="https://img.shields.io/npm/v/@file-viewer%2Fvite-plugin?logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@file-viewer/vite-plugin"><img src="https://img.shields.io/npm/dm/@file-viewer%2Fvite-plugin?logo=npm" alt="npm downloads"></a>
+  <a href="https://github.com/flyfish-dev/file-viewer/stargazers"><img src="https://img.shields.io/github/stars/flyfish-dev/file-viewer?style=flat&logo=github" alt="GitHub stars"></a>
+  <a href="https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
+</p>
 
-The package's own license is Apache-2.0. Included third-party notices apply to their respective components.
+<p>
+  <a href="https://github.com/flyfish-dev/file-viewer">GitHub</a> · <a href="https://doc.file-viewer.app/">Docs</a> · <a href="https://demo.file-viewer.app/">Live demo</a> · <a href="https://doc.file-viewer.app/guide/formats">Format matrix</a> · <a href="https://github.com/flyfish-dev/file-viewer/issues">Issues</a> · <a href="https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.zh-CN.md">简体中文</a>
+</p>
+
+<p>
+  <a href="https://demo.file-viewer.app/"><img src="https://raw.githubusercontent.com/flyfish-dev/file-viewer/main/docs/public/_media/file-viewer-demo-v3-en.webp" width="760" alt="File Viewer live demo: Word, Excel, PowerPoint, 3D model, CAD drawing and binary inspector"></a>
+</p>
+
+> ⭐ If File Viewer helps you, please [star the repo on GitHub](https://github.com/flyfish-dev/file-viewer).
+
+Vite plugin for Flyfish File Viewer on-demand renderer assembly. It can auto-discover installed `@file-viewer/preset-*` and `@file-viewer/*-full` packages, so Vue, React, Svelte, jQuery, and Vanilla JS components receive matching preview capability without application code passing `renderers` manually. It can also generate `virtual:file-viewer-renderers` from declared formats, import only matching renderer packages, and provide renderer-oriented chunk planning plus offline worker/WASM/font asset copying.
+
+## Fastest Start
+
+For complete format support, the fastest path is one full package and one Vite plugin registration. Full packages already include `preset-all`; do not install another preset. `copyAssets:true` matches the installed full package and publishes its Worker, WASM, font, and vendor files under `file-viewer/` at the deployment base (`/file-viewer/` for a root deployment) in both dev and build:
+
+```bash
+pnpm add @file-viewer/vue3-full
+pnpm add -D @file-viewer/vite-plugin
+```
+
+```ts
+import { defineConfig } from 'vite'
+import { fileViewerRenderers } from '@file-viewer/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fileViewerRenderers({
+      copyAssets: true
+    })
+  ]
+})
+```
+
+Installing a full package without publishing these assets leaves PDF Worker, CAD/Typst/Archive WASM, and other formats without runtime files. That is partial support, not a complete setup.
+
+For a smaller install, use a standard component with one preset and keep the same Vite config. The plugin auto-discovers installed presets, so application code does not hand-write renderer imports and the plugin does not need `preset:'office'`:
+
+```bash
+pnpm add @file-viewer/vue3 @file-viewer/preset-office
+pnpm add -D @file-viewer/vite-plugin
+```
+
+Components keep `autoRenderers:true` by default, so `@file-viewer/vue3`, `@file-viewer/react`, `@file-viewer/web`, `@file-viewer/svelte`, `@file-viewer/jquery`, `@file-viewer/vue2.7`, and `@file-viewer/vue2.6` automatically consume the injected preset / renderer registry.
+
+Available presets:
+
+- `@file-viewer/preset-lite`: text, Markdown, code, image, audio, and video.
+- `@file-viewer/preset-office`: PDF, Word, Excel, PowerPoint, OFD, RTF, and OpenDocument.
+- `@file-viewer/preset-engineering`: CAD, 3D, drawing, XMind, Geo, Typst, Archive, Data, and EDA.
+- `@file-viewer/preset-all`: the complete official demo format matrix.
+
+Install individual renderer packages only for strict cuts, such as `@file-viewer/renderer-pdf`, `@file-viewer/renderer-word`, `@file-viewer/renderer-ofd`, `@file-viewer/renderer-presentation`, `@file-viewer/renderer-cad`, `@file-viewer/renderer-drawing`, `@file-viewer/renderer-3d`, `@file-viewer/renderer-data`, `@file-viewer/renderer-eda`, `@file-viewer/renderer-typst`, `@file-viewer/renderer-archive`, or `@file-viewer/renderer-text`, then use `formats` to generate exact imports.
+
+## vite.config.ts
+
+Prefer full/preset auto assembly for normal products. With only `copyAssets:true`, the plugin auto-discovers installed `@file-viewer/*-full` or `@file-viewer/preset-*` packages:
+
+```ts
+fileViewerRenderers({
+  copyAssets: true
+})
+```
+
+Use customization options only when you need source scanning, single-format cuts, or manual registry control:
+
+```ts
+import { defineConfig } from 'vite'
+import { fileViewerRenderers } from '@file-viewer/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fileViewerRenderers({
+      formats: ['pdf', 'dwg', 'typst', 'zip', 'xmind'],
+      scan: true,
+      copyAssets: true,
+      chunkStrategy: 'renderer'
+    })
+  ]
+})
+```
+
+`inject` is enabled by default. The plugin injects `virtual:file-viewer-renderers` into Vite HTML entrypoints, preset imports register themselves in core, and framework components consume them through `autoRenderers`.
+
+```ts
+const options = {
+  // Defaults to true; set false when a product needs total manual control.
+  autoRenderers: true
+}
+```
+
+### Customization Options
+
+| Option | Description |
+| --- | --- |
+| `copyAssets` | `true` or `{ publicDir, outDir, mode, baseDir }`; copies matching Worker, WASM, font, and vendor assets. Installed full packages default to `<deployment-base>/file-viewer/`, which is required for complete full support; standard packages/presets keep the existing root behavior |
+| `preset` | `'auto' | 'lite' | 'office' | 'engineering' | 'all'`; with no explicit formats, installed presets are discovered automatically |
+| `autoPresets` | `true` or a preset list; useful with `scan:true` when installed presets should stay active |
+| `formats` | File extensions or format tokens, for example `['pdf', 'docx', 'dwg']` |
+| `renderers` | Renderer ids, for example `['pdf', 'word', 'cad']` |
+| `scan` | `true` or `{ roots, extensions, maxFileSize }`; scans source hints and merges formats |
+| `inject` | Defaults to `true`; set `false` to import `virtual:file-viewer-renderers` manually |
+| `chunkStrategy` | `'renderer' | 'none'`; controls renderer-level chunk grouping |
+| `stabilizeInteropChunks` | Defaults to `true`; keeps Pako / shared CommonJS helpers and CodeMirror / Lezer / Sandpack in stable groups for default and host-defined chunk splitting |
+| `missingRenderer` | `'error' | 'warn' | 'ignore'`; controls notices for planned renderer mappings |
+
+When host apps split `node_modules` by package name, circular dependencies between `@codemirror/*`, `@lezer/*`, and Sandpack can show up in production as `codemirror-view.* Cannot access ... before initialization`. The plugin stabilizes default chunk splitting and wraps existing `manualChunks` functions. Pako and shared CommonJS helpers use `vendor-commonjs` to prevent compressed-format initialization cycles; CodeMirror / Lezer / Sandpack use `vendor-codemirror`. Other custom groups remain intact, and Vite 8 receives equivalent Rolldown groups. Set `stabilizeInteropChunks:false` only when the host build needs total control.
+
+`copyAssets.baseDir` overrides automatic placement. It must be relative and cannot contain `..`; an empty string explicitly selects the root. The plugin now aligns the shared runtime asset base for standard packages, presets, and full packages; full packages also keep `setDefaultFullAssetBaseUrl()` synchronized. Only integrations that set `inject:false` and do not import the virtual module must call `setDefaultFileViewerAssetBaseUrl()` themselves (plus `setDefaultFullAssetBaseUrl()` for a full package). With Vite `base:'/app/'`, full-package dev URLs start with `/app/file-viewer/...`, while production files remain under `outDir/file-viewer/`.
+
+Asset copying runs at dev-server startup/restart and after a production build, not on ordinary HMR. Files with identical contents are left untouched, and generated manifests omit the volatile `copiedAt` timestamp. Vite's own output cleanup and public-directory copying remain unchanged.
+
+For strict registry control, disable injection and pass the virtual module explicitly:
+
+```ts
+fileViewerRenderers({
+  formats: ['pdf'],
+  inject: false,
+  copyAssets: true
+})
+```
+
+```ts
+import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'
+
+const options = {
+  rendererMode: 'replace',
+  renderers: configuredFileViewerRenderers
+}
+```
+
+You can also use `preset: 'auto'` to discover installed preset packages. When `preset-all` is installed, it wins to avoid importing narrower presets twice. Note: when `scan:true` is enabled, use `preset:'auto'` or `autoPresets:true` explicitly; otherwise the plugin treats source hints as the explicit renderer selection and skips zero-config preset discovery.
+
+```ts
+fileViewerRenderers({
+  preset: 'auto',
+  scan: true,
+  formats: ['pdf'],
+  copyAssets: true,
+  chunkStrategy: 'renderer'
+})
+```
+
+`scan: true` inspects common source folders for lightweight hints and merges them with `formats`:
+
+```ts
+export const fileViewerFormats = ['pdf', 'docx', 'xlsx']
+```
+
+```html
+<input accept=".pdf,.docx" data-file-viewer-formats="dwg,xmind" />
+```
+
+This is useful when upload accept lists, sample matrices, or attachment allow-lists already live in source code: dev and production builds can generate the renderer assembly module without a second hand-written import list.
+
+## Missing Renderer Guidance
+
+When a file extension is in the supported matrix but the current project has not assembled its renderer, core now shows an install-oriented “renderer assembly required” state with the recommended preset / renderer package. For example, `.pdf` points to `@file-viewer/preset-office` or `@file-viewer/renderer-pdf`. Only truly unknown extensions show an unsupported-format state.
+
+## Nested Vite Projects
+
+From 3.0.3, a nested metadata-only project can use a resolvable Full dependency
+declared in an ancestor `package.json`. A nearer light component or preset keeps
+its own root asset layout. Explicit `copyAssets.baseDir` still takes precedence;
+`publicDir` and `build.outDir` stay relative to the Vite root, not the dependency owner.
+
+## Current Boundary
+
+The plugin currently generates imports for extracted renderer packages: Word, Spreadsheet, PDF, OFD, Presentation, CAD, Draw.io/Excalidraw/Mermaid/PlantUML, 3D, Data, EDA, Typst, archives, email, EPUB, code/Markdown/Patch/Git Bundle, image, media, XMind, and Geo. Declare them explicitly with `formats`, or let `scan: true` discover source hints automatically; core-supported extensions such as `.zipx`, `.cbz`, `.tiff`, `.mjs`, `.gv`, `.patch`, `.bundle`, `.mermaid`, `.puml`, and `.mpeg` also resolve to their renderer packages. With `copyAssets:true`, the plugin detects installed capability packages. Full packages copy matching assets into dev `publicDir/file-viewer/` and production `outDir/file-viewer/`; standard packages/presets keep the existing root placement, including the Typst compiler / renderer WASM files and default fonts. `preset: 'auto' | 'lite' | 'office' | 'engineering' | 'all'` imports matching `@file-viewer/preset-*` packages; when `formats` are also present, the plugin adds extra renderers outside the preset.
+
+## Documentation
+
+- On-demand renderer architecture: <https://doc.file-viewer.app/guide/on-demand-renderers>
+- Supported formats: <https://doc.file-viewer.app/guide/formats>
+
+## Formats and related packages
+
+File Viewer previews 275+ file extensions in the browser, covering Office, PDF/OFD, CAD, 3D, archives, email, images, media and code, without server-side conversion. See the [format matrix](https://doc.file-viewer.app/guide/formats) for the full list.
+
+- Components: `@file-viewer/web`, `@file-viewer/vue3`, `@file-viewer/vue2.7`, `@file-viewer/vue2.6`, `@file-viewer/react`, `@file-viewer/react-legacy`, `@file-viewer/svelte`, `@file-viewer/jquery`, plus their `-full` packages
+- Presets: `@file-viewer/preset-lite`, `@file-viewer/preset-office`, `@file-viewer/preset-engineering`, `@file-viewer/preset-all`
+- Build: `@file-viewer/vite-plugin`, `file-viewer-copy-assets`
+
+## License
+
+This package is Apache-2.0. See [LICENSE](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,198 @@
+# @file-viewer/vite-plugin
+
+[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.zh-CN.md)
+
+<!-- FILE_VIEWER_PACKAGE_HEADER -->
+<p>
+  <a href="https://www.npmjs.com/package/@file-viewer/vite-plugin"><img src="https://img.shields.io/npm/v/@file-viewer%2Fvite-plugin?logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@file-viewer/vite-plugin"><img src="https://img.shields.io/npm/dm/@file-viewer%2Fvite-plugin?logo=npm" alt="npm downloads"></a>
+  <a href="https://github.com/flyfish-dev/file-viewer/stargazers"><img src="https://img.shields.io/github/stars/flyfish-dev/file-viewer?style=flat&logo=github" alt="GitHub stars"></a>
+  <a href="https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
+</p>
+
+<p>
+  <a href="https://github.com/flyfish-dev/file-viewer">GitHub</a> · <a href="https://doc.file-viewer.app/zh/">文档</a> · <a href="https://demo.file-viewer.app/">在线 Demo</a> · <a href="https://doc.file-viewer.app/guide/formats">格式矩阵</a> · <a href="https://github.com/flyfish-dev/file-viewer/issues">问题反馈</a> · <a href="https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.md">English</a>
+</p>
+
+<p>
+  <a href="https://demo.file-viewer.app/"><img src="https://raw.githubusercontent.com/flyfish-dev/file-viewer/main/docs/public/_media/file-viewer-demo-v3-zh.webp" width="760" alt="File Viewer 在线演示：Word、Excel、PPT、3D 模型、CAD 图纸与二进制检查器"></a>
+</p>
+
+> ⭐ 如果 File Viewer 对你有帮助，欢迎到 [GitHub](https://github.com/flyfish-dev/file-viewer) 点个 Star。
+
+Flyfish File Viewer 的 Vite 按需 renderer 自动装配插件。它可以自动发现已安装的 `@file-viewer/preset-*` 和 `@file-viewer/*-full` 包，让 Vue、React、Svelte、jQuery 和 Vanilla JS 组件无需手动传 `renderers` 就获得对应预览能力；也可以根据业务声明的文件格式生成 `virtual:file-viewer-renderers`，只 import 命中的 renderer 包，并提供 chunk 分组和离线 worker/WASM/字体资源复制能力。
+
+## 最快开始
+
+需要完整格式支持时，最快路径是“full 包 + 注册一次 Vite 插件”。full 已内置 `preset-all`，不要再安装 preset；`copyAssets:true` 会在开发和构建时自动匹配 full 包，并把 Worker、WASM、字体和 vendor 文件发布到部署基址下的 `file-viewer/`（根部署即 `/file-viewer/`）：
+
+```bash
+pnpm add @file-viewer/vue3-full
+pnpm add -D @file-viewer/vite-plugin
+```
+
+```ts
+import { defineConfig } from 'vite'
+import { fileViewerRenderers } from '@file-viewer/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fileViewerRenderers({
+      copyAssets: true
+    })
+  ]
+})
+```
+
+只安装 full 包而不启用资源复制，PDF Worker、CAD/Typst/Archive WASM 等格式会缺少运行文件，只能获得部分格式支持。
+
+需要更小体积时，改用“标准组件包 + 一个 preset”，Vite 配置保持不变。插件会自动发现已安装的 preset，无需手写 renderer import，也无需显式写 `preset:'office'`：
+
+```bash
+pnpm add @file-viewer/vue3 @file-viewer/preset-office
+pnpm add -D @file-viewer/vite-plugin
+```
+
+组件默认 `autoRenderers:true`，会读取 Vite 插件注入的 preset / renderer registry。常规业务代码只要使用 `@file-viewer/vue3`、`@file-viewer/react`、`@file-viewer/web`、`@file-viewer/svelte`、`@file-viewer/jquery`、`@file-viewer/vue2.7` 或 `@file-viewer/vue2.6` 即可获得对应能力。
+
+可选 preset：
+
+- `@file-viewer/preset-lite`: 文本、Markdown、代码、图片、音频、视频。
+- `@file-viewer/preset-office`: PDF、Word、Excel、PowerPoint、OFD、RTF、OpenDocument。
+- `@file-viewer/preset-engineering`: CAD、3D、绘图、XMind、Geo、Typst、Archive、Data、EDA。
+- `@file-viewer/preset-all`: 官方 demo 完整格式矩阵。
+
+如果只需要极少数格式，也可以安装对应 renderer 包，例如 `@file-viewer/renderer-pdf`、`@file-viewer/renderer-word`、`@file-viewer/renderer-ofd`、`@file-viewer/renderer-presentation`、`@file-viewer/renderer-cad`、`@file-viewer/renderer-drawing`、`@file-viewer/renderer-3d`、`@file-viewer/renderer-data`、`@file-viewer/renderer-eda`、`@file-viewer/renderer-typst`、`@file-viewer/renderer-archive`、`@file-viewer/renderer-text`，再通过 `formats` 做精确裁剪。
+
+## vite.config.ts
+
+推荐默认使用 full/preset 自动装配。只传 `copyAssets:true` 时，插件会自动发现已安装的 `@file-viewer/*-full` 或 `@file-viewer/preset-*`，无需写 `preset:'all'`：
+
+```ts
+fileViewerRenderers({
+  copyAssets: true
+})
+```
+
+只有在需要源码扫描、单格式裁剪、或手动 registry 管理时，再使用自定义能力：
+
+```ts
+import { defineConfig } from 'vite'
+import { fileViewerRenderers } from '@file-viewer/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fileViewerRenderers({
+      formats: ['pdf', 'dwg', 'typst', 'zip', 'xmind'],
+      scan: true,
+      copyAssets: true,
+      chunkStrategy: 'renderer'
+    })
+  ]
+})
+```
+
+`inject` 默认开启，插件会把 `virtual:file-viewer-renderers` 注入 Vite HTML 入口，preset 导入后会自动注册到 core。常规业务只需要安装组件包和对应 preset，组件会通过 `autoRenderers` 默认读取这些能力。
+
+```ts
+const options = {
+  // 默认 true；需要完全手动控制时设为 false。
+  autoRenderers: true
+}
+```
+
+### 可定制能力
+
+| 选项 | 说明 |
+| --- | --- |
+| `copyAssets` | `true` 或 `{ publicDir, outDir, mode, baseDir }`；复制匹配的 Worker、WASM、字体和 vendor 资源。检测到 full 时默认发布到 `<部署基址>/file-viewer/`，这是 full 完整格式支持的必需项；标准包/preset 保持原有根目录行为 |
+| `preset` | `'auto' | 'lite' | 'office' | 'engineering' | 'all'`；默认无显式格式时自动发现已安装 preset |
+| `autoPresets` | `true` 或 preset 列表；常用于 `scan:true` 时继续自动激活已安装 preset |
+| `formats` | 文件扩展名或格式 token，例如 `['pdf', 'docx', 'dwg']` |
+| `renderers` | renderer id，例如 `['pdf', 'word', 'cad']` |
+| `scan` | `true` 或 `{ roots, extensions, maxFileSize }`，扫描源码 hint 并合并格式 |
+| `inject` | 默认 `true`；设为 `false` 后手动导入 `virtual:file-viewer-renderers` |
+| `chunkStrategy` | `'renderer' | 'none'`，控制是否注入 renderer 级 chunk 分组 |
+| `stabilizeInteropChunks` | 默认 `true`；为默认分组和宿主 `manualChunks` 稳定 Pako / CommonJS 辅助模块及 CodeMirror / Lezer / Sandpack 的分组 |
+| `missingRenderer` | `'error' | 'warn' | 'ignore'`，控制尚未提取的 renderer 映射提示方式 |
+
+如果宿主项目按包名拆分 `node_modules`，`@codemirror/*`、`@lezer/*` 和 Sandpack 之间的循环依赖可能在生产构建中表现为 `codemirror-view.* Cannot access ... before initialization`。插件同时稳定默认分组和已有的 `manualChunks` 函数：Pako 与共享 CommonJS 辅助模块归入 `vendor-commonjs`，避免压缩格式的初始化循环；CodeMirror / Lezer / Sandpack 归入 `vendor-codemirror`。Vite 8 使用对应的 Rolldown 分组，其它自定义分组保持不变；确实需要完全接管时可设置 `stabilizeInteropChunks:false`。
+
+`copyAssets.baseDir` 可以覆盖自动目录：必须是相对路径，不能包含 `..`；传空字符串表示显式复制到根目录。插件会为标准包、preset 和 full 包同步统一运行时资源根；full 包仍同时同步 `setDefaultFullAssetBaseUrl()`。只有设置 `inject:false` 且不手动导入虚拟模块时，业务才需要调用 `setDefaultFileViewerAssetBaseUrl()`（full 包同时调用 `setDefaultFullAssetBaseUrl()`）。Vite 配置了 `base:'/app/'` 时，full 包开发 URL 为 `/app/file-viewer/...`，构建文件仍位于 `outDir/file-viewer/`。
+
+资源复制在开发服务器启动/重启及生产构建结束时执行，不随普通 HMR 执行。内容相同的文件不会被重复写入，生成的清单不再包含易变的 `copiedAt` 时间戳。Vite 自身清空构建目录、复制 public 目录的行为保持不变。
+
+如果你需要严格控制 registry，可以关闭注入并手动传入：
+
+```ts
+fileViewerRenderers({
+  formats: ['pdf'],
+  inject: false,
+  copyAssets: true
+})
+```
+
+```ts
+import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'
+
+const options = {
+  rendererMode: 'replace',
+  renderers: configuredFileViewerRenderers
+}
+```
+
+也可以使用 `preset: 'auto'` 发现项目中已安装的 preset 包；当 `preset-all` 存在时会优先使用它，避免重复导入其它 preset。注意：如果同时开启 `scan:true`，请显式使用 `preset:'auto'` 或 `autoPresets:true`，否则插件会以源码 hint 为准，不再做“无配置 preset 自动发现”。
+
+```ts
+fileViewerRenderers({
+  preset: 'auto',
+  scan: true,
+  formats: ['pdf'],
+  copyAssets: true,
+  chunkStrategy: 'renderer'
+})
+```
+
+`scan: true` 会扫描常见源码目录里的轻量 hint，并把它们合并到 `formats`：
+
+```ts
+export const fileViewerFormats = ['pdf', 'docx', 'xlsx']
+```
+
+```html
+<input accept=".pdf,.docx" data-file-viewer-formats="dwg,xmind" />
+```
+
+这适合业务把上传入口、示例矩阵或附件白名单维护在源码中时使用：开发和构建阶段插件会自动生成 renderer 装配模块，少写一份手工 import 清单。
+
+## 缺失 renderer 提示
+
+如果用户打开的是支持矩阵内的格式，但项目没有安装或装配对应 renderer，core 会显示“需要装配预览能力”，并提示推荐安装的 preset / renderer 包，例如 `.pdf` 会引导安装 `@file-viewer/preset-office` 或 `@file-viewer/renderer-pdf`。只有真正不在支持矩阵中的扩展名才显示“不支持在线预览”。
+
+## 嵌套 Vite 项目
+
+从 3.0.3 起，子目录只有项目元数据或 Vite 插件声明时，会沿祖先 `package.json`
+查找实际可解析的 Full 依赖。子项目明确声明轻量组件或 preset 时保留其根目录资产布局，
+不会继承父项目的 Full 布局。`copyAssets.baseDir` 仍具有最高优先级；`publicDir`
+和 `build.outDir` 均相对于 Vite root，不相对于依赖所在目录。
+
+## 当前边界
+
+当前插件会为已经拆出的 renderer 包生成导入：Word、Spreadsheet、PDF、OFD、Presentation、CAD、Draw.io/Excalidraw/Mermaid/PlantUML、3D、Data、EDA、Typst、压缩包、邮件、EPUB、代码/Markdown/Patch/Git Bundle、图片、媒体、XMind 和 Geo。可以通过 `formats` 显式声明，也可以通过 `scan: true` 从源码 hint 自动发现；`.zipx`、`.cbz`、`.tiff`、`.mjs`、`.gv`、`.patch`、`.bundle`、`.mermaid`、`.puml`、`.mpeg` 等 core 支持的扩展也会映射到对应 renderer。开启 `copyAssets:true` 时会识别已安装能力；full 包把匹配资源复制到开发 `publicDir/file-viewer/` 与构建 `outDir/file-viewer/`，标准包/preset 维持根目录行为，包括 Typst compiler / renderer WASM 与默认字体目录。`preset: 'auto' | 'lite' | 'office' | 'engineering' | 'all'` 会导入对应 `@file-viewer/preset-*` 包；如果同时声明 `formats`，插件会在 preset 之外补充额外 renderer。
+
+## 文档
+
+- 按需渲染架构: <https://doc.file-viewer.app/guide/on-demand-renderers>
+- 支持格式: <https://doc.file-viewer.app/guide/formats>
+
+## 格式与相关包
+
+File Viewer 在浏览器内预览 275+ 种扩展名，覆盖 Office、PDF/OFD、CAD、3D、压缩包、邮件、图片、音视频和代码，无需服务端转码；完整清单见 [格式矩阵](https://doc.file-viewer.app/guide/formats)。
+
+- 组件：`@file-viewer/web`、`@file-viewer/vue3`、`@file-viewer/vue2.7`、`@file-viewer/vue2.6`、`@file-viewer/react`、`@file-viewer/react-legacy`、`@file-viewer/svelte`、`@file-viewer/jquery`，以及对应的 `-full` 包
+- 能力组合：`@file-viewer/preset-lite`、`@file-viewer/preset-office`、`@file-viewer/preset-engineering`、`@file-viewer/preset-all`
+- 构建：`@file-viewer/vite-plugin`、`file-viewer-copy-assets`
+
+## 许可证
+
+本包采用 Apache-2.0。详见 [LICENSE](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE)。

package/dist/index.d.ts

@@ -4,28 +4,103 @@ export type FileViewerVitePresetMode = FileViewerVitePreset | 'auto';
 export type FileViewerMissingRendererMode = 'error' | 'warn' | 'ignore';
 export type FileViewerChunkStrategy = 'renderer' | 'none';
 export interface FileViewerRendererScanOptions {
+    /**
+     * Disable a shared scan object without branching user config.
+     */
     enabled?: boolean;
+    /**
+     * Source roots, relative to Vite root, that should be inspected for format hints.
+     * Defaults to common application source folders.
+     */
     roots?: readonly string[];
+    /**
+     * Text-like source extensions to inspect. Values may include or omit the dot.
+     */
     extensions?: readonly string[];
+    /**
+     * Large generated files are ignored by default to keep config/startup fast.
+     */
     maxFileSize?: number;
 }
 export interface FileViewerCopyAssetsOptions {
+    /**
+     * Directory used by Vite dev. Defaults to config.publicDir.
+     */
     publicDir?: string;
+    /**
+     * Directory used after production build. Defaults to build.outDir.
+     */
     outDir?: string;
+    /**
+     * Directory below publicDir/outDir where assets are published. When omitted,
+     * projects with an installed @file-viewer/*-full package use `file-viewer`;
+     * other projects keep the existing output-root layout. Use an empty string
+     * to explicitly publish at the output root. The injected runtime module
+     * keeps every renderer's default asset base aligned with this directory.
+     */
     baseDir?: string;
+    /**
+     * Copy during dev server startup, build closeBundle, or both.
+     */
     mode?: 'dev' | 'build' | 'both';
 }
 export interface FileViewerRenderersPluginOptions {
+    /**
+     * File extensions or renderer ids. Examples: pdf, .dwg, typst, zip, xmind.
+     */
     formats?: readonly string[];
+    /**
+     * Explicit renderer ids. Useful when several extensions share one renderer.
+     */
     renderers?: readonly string[];
+    /**
+     * Presets import their dedicated @file-viewer/preset-* package. Use `auto`
+     * to discover installed preset packages, and add `formats` / `renderers`
+     * when you need to extend a preset with extra lines.
+     */
     preset?: FileViewerVitePresetMode;
+    /**
+     * Auto-discovers installed `@file-viewer/preset-*` packages and registers
+     * them globally for framework components. Defaults to true only when no
+     * explicit preset/formats/renderers are configured, or when `preset: 'auto'`.
+     */
     autoPresets?: boolean | readonly FileViewerVitePreset[];
+    /**
+     * Injects the virtual renderer module into Vite HTML entrypoints so
+     * framework components can consume auto-registered renderers without
+     * application code importing `virtual:file-viewer-renderers`.
+     */
     inject?: boolean;
+    /**
+     * Virtual module id consumed by application code.
+     */
     moduleId?: string;
+    /**
+     * Controls how planned-but-not-yet-extracted renderer lines are reported.
+     */
     missingRenderer?: FileViewerMissingRendererMode;
+    /**
+     * Adds renderer-oriented manualChunks when the user did not define one.
+     */
     chunkStrategy?: FileViewerChunkStrategy;
+    /**
+     * Stabilizes default chunk groups and wraps existing manualChunks functions.
+     * This keeps CodeMirror/Lezer/Sandpack in one chunk when host
+     * apps split node_modules by package name, avoiding production TDZ errors.
+     * Pako and the shared CommonJS helpers also stay outside renderer/app chunks
+     * so compressed-format imports cannot form an initialization cycle.
+     */
     stabilizeInteropChunks?: boolean;
+    /**
+     * Copies known worker/WASM/vendor assets for selected renderer lines.
+     */
     copyAssets?: boolean | FileViewerCopyAssetsOptions;
+    /**
+     * Opt-in source scan. The plugin reads lightweight hints such as
+     * `fileViewerFormats = ['pdf', 'docx']`, `data-file-viewer-formats="pdf,docx"`,
+     * and upload `accept=".pdf,.docx"` declarations, then merges them with
+     * `formats` / `renderers` before generating the virtual module.
+     */
     scan?: boolean | FileViewerRendererScanOptions;
 }
 interface MissingRendererNotice {
@@ -36,8 +111,11 @@ interface MissingRendererNotice {
 export declare function extractFileViewerRendererHintTokens(source: string): string[];
 export declare function collectFileViewerRendererScanTokens(projectRoot: string, scan: FileViewerRenderersPluginOptions['scan']): string[];
 export interface FileViewerCopyAssetsTargetConfig {
+    /** Vite project root. Defaults to process.cwd(). */
     projectRoot?: string;
+    /** Resolved Vite publicDir. Defaults to `public`. */
     publicDir?: string;
+    /** Resolved Vite build.outDir. Defaults to `dist`. */
     outDir?: string;
 }
 export interface FileViewerCopyAssetsTarget {
@@ -48,6 +126,10 @@ export interface FileViewerCopyAssetsTarget {
     installedFullPackages: string[];
     installedAssetPackages: string[];
 }
+/**
+ * Resolves the exact directory used by copyAssets without running a Vite build.
+ * This is exported so integrations can validate their deployment contract.
+ */
 export declare function resolveFileViewerCopyAssetsTarget(mode: 'dev' | 'build', value?: true | FileViewerCopyAssetsOptions, config?: FileViewerCopyAssetsTargetConfig): FileViewerCopyAssetsTarget;
 export declare function fileViewerRenderers(options?: FileViewerRenderersPluginOptions): Plugin;
 export declare function createFileViewerManualChunks(options?: FileViewerRenderersPluginOptions): (id: string) => string | undefined;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { copyFile, cp, lstat, mkdir, readFile, readdir, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import { copyFile, lstat, mkdir, readFile, readdir, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 const virtualModuleId = 'virtual:file-viewer-renderers';
@@ -578,6 +578,10 @@ const fileViewerFullPackages = [
     '@file-viewer/jquery-full',
     '@file-viewer/svelte-full'
 ];
+// Vite dep optimization rewrites import.meta.url into node_modules/.vite/deps
+// and can trigger full-preset dev-server re-optimization reloads. Keep File
+// Viewer packages out of dep optimization while still optimizing their
+// CommonJS/UMD helper dependencies below.
 const fileViewerOptimizationExcludedPackages = [
     '@file-viewer/core',
     '@file-viewer/ppt',
@@ -686,15 +690,24 @@ export function extractFileViewerRendererHintTokens(source) {
             }
         });
     };
+    // Explicit JavaScript/TypeScript hints:
+    //   const fileViewerFormats = ['pdf', 'docx']
+    //   fileViewerRenderers: ['pdf', 'cad']
     for (const match of source.matchAll(/\bfileViewer(?:Formats?|Renderers?)\b\s*[:=]\s*\[([\s\S]*?)\]/g)) {
         push(collectQuotedTokens(match[1]));
     }
+    // HTML / template hints:
+    //   <div data-file-viewer-formats="pdf,docx"></div>
+    //   <input accept=".pdf,.docx,application/vnd.ms-excel">
     for (const match of source.matchAll(/\bdata-file-viewer-(?:formats?|renderers?)\s*=\s*["']([^"']+)["']/g)) {
         push(collectDelimitedTokens(match[1]));
     }
     for (const match of source.matchAll(/\baccept\s*=\s*["']([^"']+)["']/g)) {
         push(collectDelimitedTokens(match[1]));
     }
+    // Comment hints are useful in non-framework projects where the upload UI is
+    // assembled dynamically:
+    //   // file-viewer-formats: pdf,docx,dwg
     for (const match of source.matchAll(/file-viewer-(?:formats?|renderers?)\s*:\s*([^\n\r<]+)/g)) {
         push(collectDelimitedTokens(match[1]));
     }
@@ -923,6 +936,7 @@ function resolveProjectViteMajor(projectRoot) {
                 return major;
         }
         catch {
+            // Try the plugin's own Vite installation when the project does not expose one.
         }
     }
     return 7;
@@ -952,6 +966,9 @@ function getNodeModulePackageName(id) {
         : parts[0];
 }
 function getStableInteropChunkName(id) {
+    // Rollup's virtual helper is shared by every converted CommonJS package.
+    // Leaving it in an app/renderer chunk makes Pako depend back on that chunk
+    // before its exported utility object has been initialized (issue #311).
     if (id.startsWith('\0') && /(?:^|\/)commonjsHelpers\.js$/.test(id.slice(1))) {
         return 'vendor-commonjs';
     }
@@ -1137,6 +1154,7 @@ function collectWorkspacePackageJsons(root) {
                 }
             }
             catch {
+                // Ignore malformed package.json files in unrelated workspace folders.
             }
         }
         for (const entry of readdirSync(directory)) {
@@ -1334,6 +1352,7 @@ function resolvePackageEntry(packageName, anchorPackages = []) {
                     return requireFn.resolve(packageName);
                 }
                 catch {
+                    // Continue probing alternate anchors.
                 }
             }
             return null;
@@ -1351,12 +1370,14 @@ function resolvePackageEntry(packageName, anchorPackages = []) {
         }
     }
     catch {
+        // Fall back to Node resolution below.
     }
     for (const requireFn of requireFns) {
         try {
             return requireFn.resolve(packageName);
         }
         catch {
+            // Continue probing alternate anchors.
         }
     }
     return null;
@@ -1440,6 +1461,42 @@ function createFileViewerResolveAliases(anchorPackages) {
         .filter((alias) => Boolean(alias)));
     return aliases;
 }
+async function assetPathInfo(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function ensureAssetCopyDirectory(path, replace) {
+    const info = await assetPathInfo(path);
+    if (info?.isDirectory() && !info.isSymbolicLink())
+        return;
+    if (info) {
+        if (!replace)
+            throw new Error(`[file-viewer:vite-plugin] Unsafe asset directory ${path}.`);
+        await rm(path, { recursive: info.isDirectory(), force: true });
+    }
+    await mkdir(path, { recursive: true });
+}
+async function writeAssetJsonIfChanged(path, value) {
+    const manifest = { ...value };
+    delete manifest.copiedAt;
+    const content = `${JSON.stringify(manifest, null, 2)}\n`;
+    const info = await assetPathInfo(path);
+    if (info) {
+        if (!info.isFile() || info.isSymbolicLink()) {
+            throw new Error(`[file-viewer:vite-plugin] Unsafe asset manifest ${path}.`);
+        }
+        if (await readFile(path, 'utf8') === content)
+            return;
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content);
+}
 async function copyFileIfPresent(from, to) {
     if (!from || !existsSync(from)) {
         return false;
@@ -1448,21 +1505,66 @@ async function copyFileIfPresent(from, to) {
     if (!info.isFile()) {
         return false;
     }
+    const destination = await assetPathInfo(to);
+    if (destination) {
+        if (!destination.isFile() || destination.isSymbolicLink()) {
+            throw new Error(`[file-viewer:vite-plugin] Unsafe asset file ${to}.`);
+        }
+        if (info.size === destination.size) {
+            const [sourceBytes, destinationBytes] = await Promise.all([readFile(from), readFile(to)]);
+            if (sourceBytes.equals(destinationBytes))
+                return true;
+        }
+    }
     await mkdir(dirname(to), { recursive: true });
     await copyFile(from, to);
     return true;
 }
-async function copyDirectoryIfPresent(from, to) {
+async function copyDirectoryIfPresent(from, to, options = {}) {
     if (!from || !existsSync(from)) {
         return false;
     }
-    const info = await stat(from);
+    const info = await lstat(from);
+    if (info.isSymbolicLink()) {
+        throw new Error(`[file-viewer:vite-plugin] Asset source is a symbolic link: ${from}.`);
+    }
     if (!info.isDirectory()) {
         return false;
     }
-    await rm(to, { recursive: true, force: true });
-    await mkdir(dirname(to), { recursive: true });
-    await cp(from, to, { recursive: true, force: true });
+    if (isPathWithin(from, to) || isPathWithin(to, from)) {
+        throw new Error(`[file-viewer:vite-plugin] Asset source and destination overlap: ${from}, ${to}.`);
+    }
+    const entries = await readdir(from, { withFileTypes: true });
+    if (entries.some(entry => entry.isSymbolicLink())) {
+        throw new Error(`[file-viewer:vite-plugin] Asset source contains a symbolic link: ${from}.`);
+    }
+    await ensureAssetCopyDirectory(to, !options.merge);
+    const excluded = new Set(options.exclude || []);
+    if (!options.merge) {
+        const names = new Set([...entries.map(entry => entry.name), ...excluded]);
+        for (const entry of await readdir(to)) {
+            if (!names.has(entry))
+                await rm(join(to, entry), { recursive: true, force: true });
+        }
+    }
+    for (const entry of entries) {
+        if (excluded.has(entry.name))
+            continue;
+        const source = join(from, entry.name), destination = join(to, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirectoryIfPresent(source, destination, { merge: options.merge });
+        }
+        else if (entry.isFile()) {
+            const destinationInfo = await assetPathInfo(destination);
+            if (!options.merge && destinationInfo && (!destinationInfo.isFile() || destinationInfo.isSymbolicLink())) {
+                await rm(destination, { recursive: destinationInfo.isDirectory(), force: true });
+            }
+            await copyFileIfPresent(source, destination);
+        }
+        else {
+            throw new Error(`[file-viewer:vite-plugin] Asset source is not a regular file: ${source}.`);
+        }
+    }
     return true;
 }
 async function copyVersionedCadRuntimeDirectoryIfPresent(from, to, runtimeVersion) {
@@ -1472,12 +1574,13 @@ async function copyVersionedCadRuntimeDirectoryIfPresent(from, to, runtimeVersio
     if (!runtimeVersion || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(runtimeVersion)) {
         throw new Error(`[file-viewer:vite-plugin] Cannot publish CAD runtime assets with invalid version ${JSON.stringify(runtimeVersion)}.`);
     }
-    const copied = await copyDirectoryIfPresent(from, to);
+    const copied = await copyDirectoryIfPresent(from, to, { exclude: [runtimeVersion] });
     if (!copied) {
         return false;
     }
     const versionedTarget = join(to, runtimeVersion);
-    return copyDirectoryIfPresent(from, versionedTarget);
+    // These files are copied from the package root after its runtime directory.
+    return copyDirectoryIfPresent(from, versionedTarget, { exclude: ['LICENSE', 'NOTICE'] });
 }
 async function copyPdfCjkFontAssets(from, to) {
     if (!from) {
@@ -1489,11 +1592,15 @@ async function copyPdfCjkFontAssets(from, to) {
     if (![files, stylesheet, license].every(existsSync) || !statSync(files).isDirectory()) {
         return false;
     }
-    await rm(to, { recursive: true, force: true });
-    await mkdir(to, { recursive: true });
-    await cp(files, join(to, 'files'), { recursive: true, force: true });
-    await copyFile(stylesheet, join(to, 'noto-sans-sc.css'));
-    await copyFile(license, join(to, 'OFL-1.1.txt'));
+    await ensureAssetCopyDirectory(to, true);
+    const retained = new Set(['files', 'noto-sans-sc.css', 'OFL-1.1.txt']);
+    for (const name of await readdir(to)) {
+        if (!retained.has(name))
+            await rm(join(to, name), { recursive: true, force: true });
+    }
+    await copyDirectoryIfPresent(files, join(to, 'files'));
+    await copyFileIfPresent(stylesheet, join(to, 'noto-sans-sc.css'));
+    await copyFileIfPresent(license, join(to, 'OFL-1.1.txt'));
     return true;
 }
 function hasPdfCjkFontAssets(root, stylesheet, license) {
@@ -1579,6 +1686,9 @@ async function copyKnownRendererAssets(targetRoot, rendererIds) {
         '@file-viewer/renderer-pdf'
     ]);
     const pdfCjkFontTarget = join(targetRoot, 'vendor/pdf/fonts');
+    // The PDF renderer owns the runtime font dependency so direct renderer installs retain
+    // CJK fallback support. The standard profile pack is only a pre-staged copy source.
+    // A missing source means an incomplete install and must not silently drop the fallback.
     const hasStandardPdfCjkFont = hasPdfCjkFontAssets(standardPdfCjkFontRoot, 'noto-sans-sc.css', 'OFL-1.1.txt');
     const hasStagedPdfCjkFont = hasPdfCjkFontAssets(stagedPdfCjkFontRoot, 'wght.css', 'LICENSE');
     const hasDependencyPdfCjkFont = hasPdfCjkFontAssets(dependencyPdfCjkFontRoot, 'wght.css', 'LICENSE');
@@ -1730,6 +1840,10 @@ async function copyKnownRendererAssets(targetRoot, rendererIds) {
     const postscriptLicenses = [
         ['postscript-design-license-stet-apache', 'Stet-Apache-2.0.txt', 'LICENSE.stet-Apache-2.0.txt'],
         ['postscript-design-license-stet-mit', 'Stet-MIT.txt', 'LICENSE.stet-MIT.txt'],
+        ['postscript-design-license-urw-ofl', 'Stet-URW-Fonts-OFL-1.1.txt', 'LICENSE.Stet-URW-Fonts-OFL-1.1.txt'],
+        ['postscript-design-license-cmyk-provenance', 'Stet-CMYK-Profile.txt', 'LICENSE.Stet-CMYK-Profile.txt'],
+        ['postscript-design-license-cc0', 'CC0-1.0.txt', 'LICENSE.CC0-1.0.txt'],
+        ['postscript-design-license-native-dependencies', 'Stet_NATIVE_THIRD_PARTY_LICENSES.json', 'Stet_NATIVE_THIRD_PARTY_LICENSES.json'],
         ['postscript-design-license-carlito-ofl', 'Carlito-OFL-1.1.txt', 'LICENSE.Carlito-OFL-1.1.txt'],
         ['postscript-design-license-tinos-ofl', 'Tinos-OFL-1.1.txt', 'LICENSE.Tinos-OFL-1.1.txt'],
         ['postscript-design-license-cousine-ofl', 'Cousine-OFL-1.1.txt', 'LICENSE.Cousine-OFL-1.1.txt'],
@@ -1745,13 +1859,7 @@ async function copyKnownRendererAssets(targetRoot, rendererIds) {
     await push('indesign-idml-design', 'indesign-idml-license', join(targetRoot, 'vendor/design/LICENSE.introspect-wasm-MPL-2.0.txt'), () => copyFileIfPresent(designRendererRoot ? join(designRendererRoot, 'LICENSES/MPL-2.0.txt') : null, join(targetRoot, 'vendor/design/LICENSE.introspect-wasm-MPL-2.0.txt')));
     await push('data-asset', 'data-sql-wasm', join(targetRoot, 'wasm/data/sql-wasm.wasm'), () => copyFileIfPresent(sqlJsRoot ? join(sqlJsRoot, 'dist/sql-wasm.wasm') : null, join(targetRoot, 'wasm/data/sql-wasm.wasm')));
     await mkdir(targetRoot, { recursive: true });
-    await writeFile(join(targetRoot, 'flyfish-viewer-assets.json'), `${JSON.stringify({
-        schemaVersion: 1,
-        generatedBy: '@file-viewer/vite-plugin',
-        rendererIds,
-        copiedAt: new Date().toISOString(),
-        assets: results
-    }, null, 2)}\n`);
+    await writeAssetJsonIfChanged(join(targetRoot, 'flyfish-viewer-assets.json'), { schemaVersion: 1, generatedBy: '@file-viewer/vite-plugin', rendererIds, assets: results });
     return results;
 }
 const independentlyOwnedAssetRendererIds = new Map([
@@ -1895,17 +2003,17 @@ async function copyInstalledCapabilityAssetPacks(targetRoot, rendererIds, instal
     const manifests = [...rendererOwners]
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([, value]) => value.manifest);
-    await writeFile(join(targetRoot, 'flyfish-viewer-assets.json'), `${JSON.stringify({
+    await writeAssetJsonIfChanged(join(targetRoot, 'flyfish-viewer-assets.json'), {
         schemaVersion: 1,
         generatedBy: '@file-viewer/vite-plugin',
         rendererAssetManifests: manifests
-    }, null, 2)}\n`);
-    await writeFile(join(targetRoot, 'flyfish-viewer-manifest.json'), `${JSON.stringify({
+    });
+    await writeAssetJsonIfChanged(join(targetRoot, 'flyfish-viewer-manifest.json'), {
         schemaVersion: 1,
         kind: 'file-viewer-capability-assets',
         owners: sources.map(source => ({ packageName: source.packageName, packageVersion: source.packageVersion }))
             .sort((left, right) => left.packageName.localeCompare(right.packageName))
-    }, null, 2)}\n`);
+    });
     return { results, rendererIds: [...rendererOwners.keys()].sort() };
 }
 function matchesBundledAssetKind(kind, info) {
@@ -1956,6 +2064,8 @@ function resolveBundledFullAssetSource(installedFullPackages) {
             };
         }
     }
+    // Source workspaces may not have staged file-viewer-copy-assets/viewer yet.
+    // @file-viewer/web keeps the same tracked payload for local development.
     const webPackageRoot = resolvePackageRoot('@file-viewer/web', installedFullPackages);
     const webPayloadRoot = webPackageRoot ? join(webPackageRoot, 'viewer') : null;
     const sourceVersion = readPackageVersion(webPackageRoot);
@@ -2003,6 +2113,8 @@ async function copyBundledFullRendererAssets(targetRoot, rendererIds, installedF
         throw new Error(`[file-viewer:vite-plugin] Unsupported full asset manifest in ${sourceManifestPath}.`);
     }
     const packageJson = JSON.parse(readFileSync(join(source.packageRoot, 'package.json'), 'utf8'));
+    // Full may split large asset families into version-paired dependencies.
+    // Resolve only its declared owners, never an unrelated project-level pack.
     const dependencies = packageJson.dependencies || {};
     const splitPackageNames = Object.keys(dependencies)
         .filter(name => name.startsWith('@file-viewer/assets-'));
@@ -2036,7 +2148,12 @@ async function copyBundledFullRendererAssets(targetRoot, rendererIds, installedF
         }
     }
     await mkdir(targetRoot, { recursive: true });
-    await cp(source.payloadRoot, targetRoot, { recursive: true, force: true });
+    // The runtime manifest is generated below; never overwrite it with the bundled
+    // source first, otherwise an unchanged copy still writes it twice.
+    await copyDirectoryIfPresent(source.payloadRoot, targetRoot, {
+        merge: true,
+        exclude: ['flyfish-viewer-assets.json']
+    });
     const results = [];
     for (const asset of manifest.rendererAssetManifests.flatMap((rendererManifest) => rendererManifest.assets)) {
         if (asset.target !== 'public' || !asset.defaultPath) {
@@ -2075,13 +2192,7 @@ async function copyBundledFullRendererAssets(targetRoot, rendererIds, installedF
             sourceVersion: owner?.packageVersion || source.sourceVersion
         });
     }
-    await writeFile(join(targetRoot, 'flyfish-viewer-assets.json'), `${JSON.stringify({
-        ...manifest,
-        generatedBy: '@file-viewer/vite-plugin',
-        copiedAt: new Date().toISOString(),
-        rendererIds,
-        assets: results
-    }, null, 2)}\n`);
+    await writeAssetJsonIfChanged(join(targetRoot, 'flyfish-viewer-assets.json'), { ...manifest, generatedBy: '@file-viewer/vite-plugin', rendererIds, assets: results });
     return results;
 }
 async function copyRendererAssets(target, rendererIds) {
@@ -2102,6 +2213,7 @@ async function copyRendererAssets(target, rendererIds) {
                     id: 'missing-independent-asset-owner',
                     to: target.targetRoot,
                     copied: false,
+                    // Specialist offline payloads stay opt-in; warn instead of failing the build.
                     required: false,
                     reason: `install ${requiredOwner} for this capability`
                 });
@@ -2160,6 +2272,8 @@ function resolveInstalledFullPackages(projectRoot) {
                 return fileViewerFullPackages.filter(packageName => declaredPackages.has(packageName) &&
                     Boolean(tryResolvePackageJson(packageName, projectPackageRequire)));
             }
+            // Vite roots can contain a metadata-only package.json while runtime
+            // dependencies live in an ancestor. A nearer light runtime is a boundary.
             const directory = dirname(packageJsonPath);
             const parent = dirname(directory);
             packageJsonPath = parent === directory ? null : findNearestProjectPackageJson(parent);
@@ -2231,6 +2345,10 @@ function resolveOutputRoot(value, fallback, projectRoot) {
     const output = value || fallback;
     return isAbsolute(output) ? resolve(output) : resolve(projectRoot, output);
 }
+/**
+ * Resolves the exact directory used by copyAssets without running a Vite build.
+ * This is exported so integrations can validate their deployment contract.
+ */
 export function resolveFileViewerCopyAssetsTarget(mode, value = true, config = {}) {
     const projectRoot = resolve(config.projectRoot || process.cwd());
     const options = copyOptions(value);
@@ -2290,6 +2408,10 @@ function resolveViteFullAssetBase(base, baseDir) {
 function resolveDevAssetRequestPath(targetRoot, baseDir, requestPathname, viteBasePath) {
     let requestRelativePath;
     try {
+        // Depending on the Vite major and middleware ordering, configureServer can
+        // observe either the original base-prefixed URL or the pathname after
+        // Vite's base middleware has stripped it. Accept both shapes, then keep the
+        // strict viewer-asset allowlist and target-root boundary checks below.
         const encodedRelativePath = viteBasePath === '/' || requestPathname.startsWith(viteBasePath)
             ? requestPathname.slice(viteBasePath === '/' ? 1 : viteBasePath.length)
             : requestPathname.replace(/^\/+/, '');
@@ -2337,7 +2459,8 @@ const defaultRequiredAssetRendererIds = [
     'office-presentation',
     'archive',
     'cad',
-    'typst'
+    'typst',
+    'postscript-design'
 ];
 function isRequiredAssetResult(result) {
     return result.required ?? defaultRequiredAssetRendererIds.includes(result.rendererId);
@@ -2557,6 +2680,7 @@ export function fileViewerRenderers(options = {}) {
                             }
                         }
                         catch {
+                            // Let Vite return its normal 404/fallback response.
                         }
                     }
                     next();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@file-viewer/vite-plugin",
-  "version": "3.2.1",
+  "version": "3.2.3",
   "private": false,
   "type": "module",
   "description": "Vite plugin for File Viewer on-demand renderer assembly, chunk planning, and offline asset deployment.",
@@ -47,12 +47,13 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "LICENSE",
     "client.d.ts",
-    "dist/index.d.ts",
     "dist/index.js",
-    "LICENSE",
+    "dist/index.d.ts",
+    "README.md",
     "README.en.md",
-    "README.md"
+    "README.zh-CN.md"
   ],
   "peerDependencies": {
     "vite": ">=5 <9"