@file-viewer/core 2.4.0 → 3.0.0

package/README.en.md

@@ -66,9 +66,26 @@ const viewer = createViewer(document.querySelector('#viewer')!, {
 await viewer.load({ url: '/files/report.pdf' })
 ```
 
+HTML document builders live in the opt-in export entry so ordinary previews do
+not download the sanitizer. The viewer's `exportHtml()` and `print()` methods
+load this entry only when invoked. For v3, migrate direct builder imports from
+the package root to the explicit subpath:
+
+```ts
+import {
+  buildExportHtmlDocument,
+  buildFileViewerRenderedHtmlDocument
+} from '@file-viewer/core/export'
+```
+
+The deprecated Vue 3 template re-exports are asynchronous in v3 to preserve
+this lazy boundary, so legacy calls must use `await buildExportHtmlDocument(...)`
+or `await collectDocumentStyles()`. Direct imports from the `export` subpath
+keep their documented return types.
+
 `options.styleIsolation` accepts `auto`, `shadow`, `scoped`, or `none`. Use `shadow` when a custom host or framework wrapper needs a ShadowRoot-backed render surface. Core passes the resolved `surface` to renderer `load(context)`, so custom renderers should inject styles into `context.surface.shadowRoot` or the renderer container instead of `document.head`, and should mount overlays inside the same isolated surface when possible.
 
-The root `@file-viewer/core` entry remains the complete compatibility entry for existing integrations. New component packages should prefer the narrowest explicit entry point they need: `headless` for contracts and build-time helpers, `browser` for real browser preview.
+The root `@file-viewer/core` entry remains the normal browser-compatible entry. New component packages should prefer the narrowest explicit entry point they need: `headless` for contracts and build-time helpers, `browser` for real browser preview, and `export` for sanitized standalone HTML documents.
 
 ```ts
 import {

package/README.md

@@ -66,9 +66,26 @@ const viewer = createViewer(document.querySelector('#viewer')!, {
 await viewer.load({ url: '/files/report.pdf' })
 ```
 
+HTML document builders live in the opt-in export entry so ordinary previews do
+not download the sanitizer. The viewer's `exportHtml()` and `print()` methods
+load this entry only when invoked. For v3, migrate direct builder imports from
+the package root to the explicit subpath:
+
+```ts
+import {
+  buildExportHtmlDocument,
+  buildFileViewerRenderedHtmlDocument
+} from '@file-viewer/core/export'
+```
+
+Vue 3 模板中已弃用的兼容导出在 v3 中改为异步，以保持这条懒加载边界；
+旧调用需要使用 `await buildExportHtmlDocument(...)` 或
+`await collectDocumentStyles()`。直接从 `export` 子路径导入时，返回类型仍
+按该子路径的 API 文档保持不变。
+
 `options.styleIsolation` accepts `auto`, `shadow`, `scoped`, or `none`. Use `shadow` when a custom host or framework wrapper needs a ShadowRoot-backed render surface. Core passes the resolved `surface` to renderer `load(context)`, so custom renderers should inject styles into `context.surface.shadowRoot` or the renderer container instead of `document.head`, and should mount overlays inside the same isolated surface when possible.
 
-The root `@file-viewer/core` entry remains the complete compatibility entry for existing integrations. New component packages should prefer the narrowest explicit entry point they need: `headless` for contracts and build-time helpers, `browser` for real browser preview.
+The root `@file-viewer/core` entry remains the normal browser-compatible entry. New component packages should prefer the narrowest explicit entry point they need: `headless` for contracts and build-time helpers, `browser` for real browser preview, and `export` for sanitized standalone HTML documents.
 
 ```ts
 import {

package/dist/config/options.js

@@ -1,3 +1,4 @@
+const UNSAFE_JSON_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 const isRecord = (value) => {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 };
@@ -31,14 +32,19 @@ const sanitizeJsonValue = (value) => {
     if (!isRecord(value)) {
         return undefined;
     }
-    const output = {};
+    const outputEntries = [];
     Object.entries(value).forEach(([key, nextValue]) => {
+        if (UNSAFE_JSON_KEYS.has(key)) {
+            return;
+        }
         const sanitized = sanitizeJsonValue(nextValue);
         if (sanitized !== undefined) {
-            output[key] = sanitized;
+            outputEntries.push([key, sanitized]);
         }
     });
-    return Object.keys(output).length ? output : undefined;
+    return outputEntries.length
+        ? Object.fromEntries(outputEntries)
+        : undefined;
 };
 const stripExecutionOnlyOptions = (value) => {
     const { beforeOperation: _beforeOperation, hooks: _hooks, preset: _preset, presets: _presets, renderers: _renderers, rendererMode: _rendererMode, ...rest } = value;

package/dist/contracts/types.d.ts

@@ -28,7 +28,7 @@ export type FileViewerToolbarItem = 'search' | 'zoom' | 'download' | 'print' | '
 export type FileViewerResolvedToolbarItem = 'search' | 'zoom' | 'download' | 'print' | 'exportHtml' | 'theme';
 export type FileViewerToolbarActionMap = Partial<Record<FileViewerOperationType, boolean>>;
 export type FileViewerRenderStateKind = 'idle' | 'loading' | 'ready' | 'empty' | 'unsupported' | 'error';
-export type FileViewerRendererCategory = 'office' | 'document' | 'archive' | 'email' | 'eda' | 'cad' | 'model' | 'geo' | 'drawing' | 'mindmap' | 'ebook' | 'image' | 'markdown' | 'code' | 'media' | 'asset' | 'fallback';
+export type FileViewerRendererCategory = 'office' | 'document' | 'archive' | 'email' | 'eda' | 'cad' | 'model' | 'geo' | 'drawing' | 'mindmap' | 'ebook' | 'image' | 'medical-image' | 'cryptographic-container' | 'markdown' | 'code' | 'media' | 'asset' | 'fallback';
 export interface FileViewerWatermarkOptions {
     enabled?: boolean;
     text?: string;
@@ -197,8 +197,10 @@ export interface FileViewerDocxOptions {
     updatePageReferences?: boolean;
     hideWebHiddenContent?: boolean;
     ignoreLastRenderedPageBreak?: boolean;
-    /** External DOCX links are blocked by default; internal bookmark links remain active. */
+    /** External DOC/DOCX/RTF links are blocked by default; internal bookmark links remain active. */
     externalLinkPolicy?: 'allow' | 'block';
+    /** Linked DOC/DOCX/RTF image resources are blocked by default; embedded images remain available. */
+    externalResourcePolicy?: 'allow' | 'block';
     /** Overrides automatic DOCX dark rendering derived from the viewer theme. */
     darkMode?: boolean;
 }
@@ -483,14 +485,16 @@ export interface FileViewerDrawingOptions {
     /**
      * Self-hosted diagrams.net viewer script.
      *
-     * The default points to the viewer asset copied under
-     * `vendor/drawio/viewer-static.min.js`, so Draw.io uses the official viewer
-     * offline without reaching public diagrams.net hosts.
+     * The default points to the optional viewer asset copied under
+     * `vendor/drawio/viewer-static.min.js`. It is only requested when
+     * `preferOfficial` is explicitly enabled and never reaches public
+     * diagrams.net hosts.
      */
     viewerScriptUrl?: string;
     /**
-     * Defaults to true. Set to false only when a deployment prefers the small
-     * built-in SVG fallback over the official diagrams.net viewer runtime.
+     * Defaults to false so untrusted diagrams use the inert built-in SVG path.
+     * Set to true only to opt into the separately delivered diagrams.net viewer
+     * runtime. It runs in a no-same-origin iframe with a restrictive CSP.
      */
     preferOfficial?: boolean;
     /**
@@ -549,7 +553,7 @@ export interface FileViewerCadOptions {
 }
 export type FileViewerRendererMode = 'extend' | 'replace';
 export type FileViewerBuiltinRendererPreset = 'all' | 'lite' | 'none';
-export type FileViewerRendererPresetName = 'all' | 'lite' | 'office' | 'engineering';
+export type FileViewerRendererPresetName = 'all' | 'lite' | 'standard' | 'office' | 'engineering';
 export interface FileViewerAutoRendererOptions {
     /**
      * Uses renderer presets registered by build tooling or preset side-effect imports.

package/dist/export.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Explicit HTML export and print-document entrypoint.
+ *
+ * This subpath owns the DOM sanitizer and is intentionally excluded from the
+ * normal viewer/headless graph. Viewer operations load it only when the user
+ * starts an HTML export or print operation.
+ */
+export { buildFileViewerRenderedDomDocument, buildFileViewerRenderedHtmlDocument, buildExportDomDocument, buildExportHtmlDocument, collectDocumentStyles, sanitizeFileViewerExportDocumentDom, sanitizeFileViewerExportDocumentHtml, } from './exportDocument';
+export type { BuildExportHtmlDocumentOptions, BuildFileViewerRenderedHtmlDocumentOptions, } from './exportDocument';
+export { inlineFileViewerBlobUrlsInHtml, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerImages, waitForFileViewerNextPaint, waitForFileViewerPrintWindowReady, } from './output/export';

package/dist/export.js

@@ -0,0 +1,9 @@
+/**
+ * Explicit HTML export and print-document entrypoint.
+ *
+ * This subpath owns the DOM sanitizer and is intentionally excluded from the
+ * normal viewer/headless graph. Viewer operations load it only when the user
+ * starts an HTML export or print operation.
+ */
+export { buildFileViewerRenderedDomDocument, buildFileViewerRenderedHtmlDocument, buildExportDomDocument, buildExportHtmlDocument, collectDocumentStyles, sanitizeFileViewerExportDocumentDom, sanitizeFileViewerExportDocumentHtml, } from './exportDocument.js';
+export { inlineFileViewerBlobUrlsInHtml, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerImages, waitForFileViewerNextPaint, waitForFileViewerPrintWindowReady, } from './output/export.js';

package/dist/exportDocument.d.ts

@@ -0,0 +1,36 @@
+import type { FileRenderExportAdapter, FileRenderExportMode, FileViewerPrintMaskOptions } from './contracts/types';
+/**
+ * Sanitize the complete standalone export document before it is downloaded or
+ * mounted into a print window. This is deliberately enforced in core because
+ * third-party render adapters and watermark overrides are library inputs.
+ */
+export declare const sanitizeFileViewerExportDocumentHtml: (html: string, documentRef?: Document) => string;
+/**
+ * Produce a sanitized, inert document tree for the print-window mount path.
+ * Returning DOM here avoids reinterpreting the sanitized string through a
+ * second HTML sink such as document.write or innerHTML.
+ */
+export declare const sanitizeFileViewerExportDocumentDom: (html: string, documentRef?: Document) => HTMLHtmlElement;
+export interface BuildExportHtmlDocumentOptions {
+    contentHtml: string;
+    includeDocumentStyles?: boolean;
+    printStyle?: string;
+    title: string;
+    watermarkInlineStyle?: string;
+    mask?: FileViewerPrintMaskOptions | null;
+    /** Document whose Window owns the sanitizer. Defaults to the active document. */
+    documentRef?: Document;
+}
+export declare const collectDocumentStyles: (documentRef?: Document) => string;
+export declare const buildExportHtmlDocument: (options: BuildExportHtmlDocumentOptions) => string;
+export declare const buildExportDomDocument: (options: BuildExportHtmlDocumentOptions) => HTMLHtmlElement;
+export interface BuildFileViewerRenderedHtmlDocumentOptions {
+    source: HTMLElement;
+    mode?: FileRenderExportMode;
+    title: string;
+    adapter?: FileRenderExportAdapter | null;
+    watermarkInlineStyle?: string;
+    mask?: FileViewerPrintMaskOptions | null;
+}
+export declare const buildFileViewerRenderedHtmlDocument: (options: BuildFileViewerRenderedHtmlDocumentOptions) => Promise<string>;
+export declare const buildFileViewerRenderedDomDocument: (options: BuildFileViewerRenderedHtmlDocumentOptions) => Promise<HTMLHtmlElement>;