@file-viewer/core 3.3.0 → 3.3.1

package/dist/source/textEncoding.js

@@ -1,3 +1,7 @@
+/**
+ * Encoding used by `auto` when the bytes carry no BOM, do not look like
+ * UTF-16, and are not valid UTF-8. GB18030 keeps the historical behavior.
+ */
 export const DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING = 'gb18030';
 const SINGLE_BYTE_ENCODING_ALIASES = new Map([
     ['iso-8859-1', 'iso-8859-1'],
@@ -72,6 +76,8 @@ const normalizeFallbackEncoding = (fallbackEncoding) => {
 const isContinuationByte = (value) => {
     return value !== undefined && value >= 0x80 && value <= 0xbf;
 };
+// Validate bytes directly because older WebViews can accept the fatal option
+// while still replacing malformed input. That would hide the GB18030 fallback.
 export const isValidFileViewerUtf8 = (bytes) => {
     for (let index = 0; index < bytes.length;) {
         const first = bytes[index];
@@ -152,6 +158,15 @@ const inferBomlessUtf16 = (bytes) => {
     }
     return null;
 };
+/**
+ * Picks the decoder for a text buffer.
+ *
+ * `encoding` other than `auto` is used as-is. In `auto` mode the order is:
+ * BOM, UTF-16 byte structure, strict UTF-8, then `fallbackEncoding`. The
+ * fallback defaults to GB18030; pass `windows-1252`, `windows-1251`, or
+ * another supported label for Latin, Cyrillic, or Central European legacy
+ * files, which are otherwise misread as CJK text.
+ */
 export const resolveFileViewerTextEncoding = (bytes, encoding = 'auto', fallbackEncoding = DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING) => {
     const normalized = normalizeEncoding(encoding);
     if (normalized !== 'auto') {

package/dist/viewer/createViewer.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerEventHandler, FileViewerInstance, FileViewerOptions, FileViewerRenderPurpose, RendererRegistry } from "../contracts/types.js";
+import type { FileViewerEventHandler, FileViewerInstance, FileViewerOptions, FileViewerRenderPurpose, RendererRegistry } from '../contracts/types.js';
 export interface CreateViewerOptions {
     registry?: RendererRegistry;
     options?: FileViewerOptions;

package/dist/viewer/createViewer.js

@@ -1,20 +1,26 @@
-import { createEmptyFileViewerSearchState, } from "../features/document/model.js";
-import { createFileViewerDocumentFeatureControllerActionHandlers, } from "../features/document/events.js";
-import { createFileViewerZoomController } from "../features/document/zoom.js";
-import { createFileViewerViewStateController } from "../features/document/viewState.js";
-import { createFileViewerFitController, hasFileViewerExplicitInitialViewState, } from "../features/document/fit.js";
-import { DEFAULT_FILE_VIEWER_DOWNLOAD_FILENAME, DEFAULT_FILE_VIEWER_EXPORT_FILENAME, DEFAULT_FILE_VIEWER_PREVIEW_TITLE, createFileViewerOriginalSourceStateFromNormalizedSource, executeFileViewerDownloadOperation, executeFileViewerExportHtmlOperation, executeFileViewerPrintOperation, resolveFileViewerDisplayFilename, resolveFileViewerOperationFilename, } from "./operations.js";
-import { openFileViewerPrintMaskDesignerAsync } from "../features/printMaskLoader.js";
-import { applyFileViewerZoomAvailability, createUnsupportedAvailability, getRendererAvailability, } from "../registry/capabilities.js";
-import { buildFileViewerLifecycleContextFromNormalizedSource, buildFileViewerOperationContext, runFileViewerBeforeOperation, runFileViewerLifecycleHook, } from "../lifecycle/operations.js";
-import { collectFileViewerRendererPlugins, createRendererRegistry, getFileViewerAutoRendererPresetVersion, hasFileViewerRendererPresetName, installFileViewerRendererPlugins, listFileViewerAutoRendererPresets, resolveFileViewerRendererPresetInputs, resolveFileViewerRendererDefinition, } from "../registry/registry.js";
-import { createFileRenderHandlerLoader, applyFileViewerRenderSurfaceState, createFileViewerRenderSurfaceState, createFileViewerRenderSurface, removeFileViewerRenderTarget, syncFileViewerRenderSurfaceBackground, } from "../rendering/handler.js";
-import { createFileViewerCoreRendererRegistry } from "../renderers/index.js";
-import { createFileViewerRequestScope } from "../source/loading.js";
-import { normalizeSource } from "../source/index.js";
-import { buildFileViewerWatermarkInlineStyle } from "../features/watermark.js";
-import { createFileViewerSnapshotDownload } from "../output/snapshotDownload.js";
-import { createFileViewerErrorState, createFileViewerUnsupportedState } from "./state.js";
+// Imperative viewer composition root.
+//
+// `createViewer` wires source normalization, lifecycle hooks, renderer
+// sessions, document features, watermarking, and public operations into a
+// framework-neutral controller. Framework packages should wrap this API instead
+// of reimplementing the orchestration.
+import { createEmptyFileViewerSearchState, } from '../features/document/model.js';
+import { createFileViewerDocumentFeatureControllerActionHandlers, } from '../features/document/events.js';
+import { createFileViewerZoomController } from '../features/document/zoom.js';
+import { createFileViewerViewStateController } from '../features/document/viewState.js';
+import { createFileViewerFitController, hasFileViewerExplicitInitialViewState, } from '../features/document/fit.js';
+import { DEFAULT_FILE_VIEWER_DOWNLOAD_FILENAME, DEFAULT_FILE_VIEWER_EXPORT_FILENAME, DEFAULT_FILE_VIEWER_PREVIEW_TITLE, createFileViewerOriginalSourceStateFromNormalizedSource, executeFileViewerDownloadOperation, executeFileViewerExportHtmlOperation, executeFileViewerPrintOperation, resolveFileViewerDisplayFilename, resolveFileViewerOperationFilename, } from './operations.js';
+import { openFileViewerPrintMaskDesignerAsync } from '../features/printMaskLoader.js';
+import { applyFileViewerZoomAvailability, createUnsupportedAvailability, getRendererAvailability, } from '../registry/capabilities.js';
+import { buildFileViewerLifecycleContextFromNormalizedSource, buildFileViewerOperationContext, runFileViewerBeforeOperation, runFileViewerLifecycleHook, } from '../lifecycle/operations.js';
+import { collectFileViewerRendererPlugins, createRendererRegistry, getFileViewerAutoRendererPresetVersion, hasFileViewerRendererPresetName, installFileViewerRendererPlugins, listFileViewerAutoRendererPresets, resolveFileViewerRendererPresetInputs, resolveFileViewerRendererDefinition, } from '../registry/registry.js';
+import { createFileRenderHandlerLoader, applyFileViewerRenderSurfaceState, createFileViewerRenderSurfaceState, createFileViewerRenderSurface, removeFileViewerRenderTarget, syncFileViewerRenderSurfaceBackground, } from '../rendering/handler.js';
+import { createFileViewerCoreRendererRegistry } from '../renderers/index.js';
+import { createFileViewerRequestScope } from '../source/loading.js';
+import { normalizeSource } from '../source/index.js';
+import { buildFileViewerWatermarkInlineStyle } from '../features/watermark.js';
+import { createFileViewerSnapshotDownload } from '../output/snapshotDownload.js';
+import { createFileViewerErrorState, createFileViewerUnsupportedState } from './state.js';
 const emitLifecycle = async (options, onEvent, phase, source, version, startedAt, reason) => {
     const now = Date.now();
     const context = buildFileViewerLifecycleContextFromNormalizedSource({
@@ -384,6 +390,9 @@ export const createViewer = (container, createOptions = {}) => {
             registry,
             options: {
                 ...inheritedOptions,
+                // The parent already resolved its renderer assembly into `registry`.
+                // Reuse that exact registry without reinstalling presets or mutating a
+                // shared registry while an attachment is open.
                 autoRenderers: false,
                 rendererMode: 'extend',
                 renderers: undefined,
@@ -677,6 +686,8 @@ export const createViewer = (container, createOptions = {}) => {
             zoomController.refreshProvider();
             viewStateController.refreshProvider();
             const finishStaleLoad = async () => {
+                // unload/replace may already have disposed this session. Clear only
+                // the session still owned by this load, preserving a replacement.
                 if (renderSurfaceState.session === session && currentRenderTarget === targetHost) {
                     await destroyCurrent('replace');
                 }

package/dist/viewer/loading.d.ts

@@ -1,5 +1,5 @@
-import { type FileViewerI18nInput } from "../i18n/messages.js";
-import type { FileViewerStateTheme } from "../contracts/types.js";
+import { type FileViewerI18nInput } from '../i18n/messages.js';
+import type { FileViewerStateTheme } from '../contracts/types.js';
 export type FileViewerLoadingTheme = FileViewerStateTheme;
 export interface FileViewerLoadingState {
     loading: boolean;
@@ -51,4 +51,8 @@ export declare const syncFileViewerLoadingControllerState: <Target extends Mutab
 export declare const runFileViewerLoadingControllerAction: <Target extends MutableFileViewerLoadingState>(target: Target, action: () => FileViewerLoadingState) => Target;
 export declare const runFileViewerLoadingExtensionSync: <Target extends MutableFileViewerLoadingState>({ target, controller, extension, }: RunFileViewerLoadingExtensionSyncInput<Target>) => Target;
 export declare const createFileViewerLoadingControllerActionHandlers: <Target extends MutableFileViewerLoadingState>(target: Target, controller: FileViewerLoadingController) => FileViewerLoadingControllerActionHandlers;
+/**
+ * 统一管理加载、错误、文案和主题色。
+ * wrapper 只负责把这个加载状态映射到各自框架的响应式系统。
+ */
 export declare const createFileViewerLoadingController: (extend?: string, initialI18n?: FileViewerI18nInput) => FileViewerLoadingController;

package/dist/viewer/loading.js

@@ -1,4 +1,4 @@
-import { translateFileViewerMessage, } from "../i18n/messages.js";
+import { translateFileViewerMessage, } from '../i18n/messages.js';
 export const FALLBACK_FILE_VIEWER_LOADING_THEME = {
     accent: '#5f6f82',
     soft: 'rgba(95, 111, 130, 0.12)',
@@ -418,6 +418,10 @@ const FILE_VIEWER_LOADING_COPY_KEYS = {
     flac: { label: 'loading.audio.label', hint: 'loading.audio.hint' },
     weba: { label: 'loading.audio.label', hint: 'loading.audio.hint' },
 };
+/**
+ * 根据扩展名返回统一的加载主题。
+ * 这样不同预览器可以复用同一套视觉语义，避免颜色、图标和文案各写一份。
+ */
 const localizeFileViewerLoadingTheme = (theme, extend = '', i18n) => {
     const normalized = extend.trim().toLowerCase();
     const keys = FILE_VIEWER_LOADING_COPY_KEYS[normalized] || {
@@ -507,6 +511,10 @@ export const createFileViewerLoadingControllerActionHandlers = (target, controll
         },
     };
 };
+/**
+ * 统一管理加载、错误、文案和主题色。
+ * wrapper 只负责把这个加载状态映射到各自框架的响应式系统。
+ */
 export const createFileViewerLoadingController = (extend = '', initialI18n) => {
     let currentExtend = extend;
     let currentI18n = initialI18n;

package/dist/viewer/operations.d.ts

@@ -1,6 +1,6 @@
-import type { FileViewerErrorMessageFormatter } from "./state.js";
-import { type FileViewerI18nInput } from "../i18n/messages.js";
-import type { FileRenderExportAdapter, FileViewerDownloadOptions, FileViewerExportHtmlOptions, FileViewerOperationType, FileViewerPrintOptions, NormalizedFileViewerSource } from "../contracts/types.js";
+import type { FileViewerErrorMessageFormatter } from './state.js';
+import { type FileViewerI18nInput } from '../i18n/messages.js';
+import type { FileRenderExportAdapter, FileViewerDownloadOptions, FileViewerExportHtmlOptions, FileViewerOperationType, FileViewerPrintOptions, NormalizedFileViewerSource } from '../contracts/types.js';
 export interface FileViewerOriginalSourceState {
     buffer?: ArrayBuffer | null;
     file?: File | Blob | null;

package/dist/viewer/operations.js

@@ -1,6 +1,6 @@
-import { triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerPrintWindowReady, } from "../output/export.js";
-import { DEFAULT_FILE_VIEWER_SOURCE_FILENAME } from "../source/index.js";
-import { translateFileViewerMessage, } from "../i18n/messages.js";
+import { triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerPrintWindowReady, } from '../output/export.js';
+import { DEFAULT_FILE_VIEWER_SOURCE_FILENAME } from '../source/index.js';
+import { translateFileViewerMessage, } from '../i18n/messages.js';
 export const DEFAULT_FILE_VIEWER_PREVIEW_TITLE = 'file-viewer-preview';
 export const DEFAULT_FILE_VIEWER_EXPORT_FILENAME = 'preview';
 export const DEFAULT_FILE_VIEWER_DOWNLOAD_FILENAME = DEFAULT_FILE_VIEWER_SOURCE_FILENAME;
@@ -65,7 +65,7 @@ const buildRenderedHtmlDocumentFromOperation = async (mode, { source, title, fil
     if (!source) {
         throw new Error(translateFileViewerMessage(i18n, 'error.noExportContent'));
     }
-    const { buildFileViewerRenderedHtmlDocument } = await import("../export.js");
+    const { buildFileViewerRenderedHtmlDocument } = await import('../export.js');
     return buildFileViewerRenderedHtmlDocument({
         source,
         mode,
@@ -82,7 +82,7 @@ const buildRenderedDomDocumentFromOperation = async ({ source, title, filename,
     if (!source) {
         throw new Error(translateFileViewerMessage(i18n, 'error.noExportContent'));
     }
-    const { buildFileViewerRenderedDomDocument } = await import("../export.js");
+    const { buildFileViewerRenderedDomDocument } = await import('../export.js');
     return buildFileViewerRenderedDomDocument({
         source,
         mode: 'print',
@@ -157,6 +157,11 @@ export const executeFileViewerDownloadOperation = async ({ source, filename, bef
         source,
         fallback: DEFAULT_FILE_VIEWER_DOWNLOAD_FILENAME,
     });
+    // PDF.js transfers ArrayBuffer-backed data to its worker. After a successful
+    // render the original buffer can therefore be detached (byteLength === 0),
+    // while the File or URL retained by the viewer is still the complete source.
+    // Preserve the existing buffer-first contract for non-empty buffers, but do
+    // not turn a detached buffer into a zero-byte download.
     if (source.buffer &&
         (source.buffer.byteLength > 0 || (!source.file && !source.url))) {
         triggerFileViewerBlobDownload(new Blob([source.buffer], { type: source.mimeType || ((_a = source.file) === null || _a === void 0 ? void 0 : _a.type) || 'application/octet-stream' }), resolvedFilename);
@@ -170,6 +175,8 @@ export const executeFileViewerDownloadOperation = async ({ source, filename, bef
         triggerFileViewerUrlDownload(source.url, resolvedFilename);
         return true;
     }
+    // Empty local files are valid sources. These final fallbacks preserve their
+    // intentional zero-byte downloads when no complete File or URL is available.
     if (source.file) {
         triggerFileViewerBlobDownload(source.file, resolvedFilename);
         return true;
@@ -203,6 +210,7 @@ export const executeFileViewerPrintOperation = async ({ autoPrint = true, before
     if (beforeResult === false) {
         return false;
     }
+    // Preserve the browser's transient user activation while the snapshot is built.
     const ownsPrintWindow = !printWindow;
     const targetWindow = printWindow ||
         (openWindow === null || openWindow === void 0 ? void 0 : openWindow()) ||
@@ -340,7 +348,7 @@ export const createFileViewerOperationActionHandlers = ({ getBuffer, getFile, ge
                 if (!source) {
                     throw new Error(translateFileViewerMessage(resolveI18n(), 'error.noExportContent'));
                 }
-                const { openFileViewerPrintMaskDesignerAsync } = await import("../features/printMaskLoader.js");
+                const { openFileViewerPrintMaskDesignerAsync } = await import('../features/printMaskLoader.js');
                 const adapter = (_a = getAdapter === null || getAdapter === void 0 ? void 0 : getAdapter()) !== null && _a !== void 0 ? _a : null;
                 const result = await openFileViewerPrintMaskDesignerAsync({
                     root: source,

package/dist/viewer/state.d.ts

@@ -1,6 +1,10 @@
-import { type FileViewerI18nInput } from "../i18n/messages.js";
-import type { FileViewerRendererCategory, FileViewerStateDescriptor, FileViewerStateTheme } from "../contracts/types.js";
+import { type FileViewerI18nInput } from '../i18n/messages.js';
+import type { FileViewerRendererCategory, FileViewerStateDescriptor, FileViewerStateTheme } from '../contracts/types.js';
 export type FileViewerErrorMessageFormatter = (prefix: string, error: unknown, i18n?: FileViewerI18nInput) => string;
+/**
+ * Renderers can attach a localized, user-safe explanation without replacing
+ * the original error object that hosts use for diagnostics and recovery.
+ */
 export declare const FILE_VIEWER_ERROR_MESSAGE: "fileViewerErrorMessage";
 export interface FileViewerErrorMessageCarrier {
     [FILE_VIEWER_ERROR_MESSAGE]?: string;

package/dist/viewer/state.js

@@ -1,6 +1,10 @@
-import { normalizeFileExtension } from "../source/index.js";
-import { DEFAULT_RENDERER_DEFINITIONS } from "../registry/formats.js";
-import { resolveFileViewerLocale, translateFileViewerMessage, } from "../i18n/messages.js";
+import { normalizeFileExtension } from '../source/index.js';
+import { DEFAULT_RENDERER_DEFINITIONS } from '../registry/formats.js';
+import { resolveFileViewerLocale, translateFileViewerMessage, } from '../i18n/messages.js';
+/**
+ * Renderers can attach a localized, user-safe explanation without replacing
+ * the original error object that hosts use for diagnostics and recovery.
+ */
 export const FILE_VIEWER_ERROR_MESSAGE = 'fileViewerErrorMessage';
 export const attachFileViewerErrorMessage = (error, message) => {
     const normalizedMessage = message.trim();
@@ -16,6 +20,7 @@ export const attachFileViewerErrorMessage = (error, message) => {
             return error;
         }
         catch {
+            // Frozen cross-realm errors retain their original value as the cause below.
         }
     }
     const presented = new Error(normalizedMessage);

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@file-viewer/core",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "private": false,
   "type": "module",
-  "description": "Framework-neutral modular TypeScript core for File Viewer renderer orchestration, lifecycle APIs, search, zoom, print, and export",
+  "description": "Framework-neutral TypeScript APIs for browser-side file preview, renderer presets, search, zoom, page navigation, print and export.",
   "keywords": [
     "file-viewer",
     "document-preview",
@@ -36,7 +36,7 @@
     "type": "individual",
     "url": "https://dev.flyfish.group/donate?source=npm"
   },
-  "homepage": "https://doc.file-viewer.app/",
+  "homepage": "https://github.com/flyfish-dev/file-viewer#readme",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -84,6 +84,8 @@
     "dist/browser.js",
     "dist/browser/controller.d.ts",
     "dist/browser/controller.js",
+    "dist/browser/source-feedback.d.ts",
+    "dist/browser/source-feedback.js",
     "dist/browser/toolbar-focus.d.ts",
     "dist/browser/toolbar-focus.js",
     "dist/config/options.d.ts",