@file-viewer/core 3.0.2 → 3.1.0

package/dist/viewer/createViewer.js

@@ -19,7 +19,8 @@ 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 { createFileViewerUnsupportedState } from './state.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({
@@ -77,6 +78,9 @@ const createFileViewerLoadSignal = (controller, signals) => {
     }
     return controller.signal;
 };
+const isAbortError = (error) => {
+    return Boolean(error && typeof error === 'object' && error.name === 'AbortError');
+};
 const renderMissingRendererState = (container, type, options) => {
     const documentRef = container.ownerDocument;
     const state = createFileViewerUnsupportedState(type, undefined, options);
@@ -105,6 +109,43 @@ const renderMissingRendererState = (container, type, options) => {
     wrapper.append(content);
     container.replaceChildren(wrapper);
 };
+const renderFileViewerErrorState = (container, type, error, options) => {
+    const documentRef = container.ownerDocument;
+    const state = createFileViewerErrorState(type, error, undefined, options);
+    const wrapper = documentRef.createElement('div');
+    wrapper.className = 'file-viewer-render-error';
+    wrapper.setAttribute('role', 'alert');
+    wrapper.setAttribute('aria-live', 'assertive');
+    wrapper.style.cssText = [
+        'display:flex',
+        'min-height:260px',
+        'height:100%',
+        'align-items:center',
+        'justify-content:center',
+        'padding:32px',
+        'box-sizing:border-box',
+        'color:var(--file-viewer-text,#172033)',
+        'font:14px/1.6 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif',
+    ].join(';');
+    const content = documentRef.createElement('div');
+    content.style.cssText = [
+        'width:min(680px,100%)',
+        'padding:24px',
+        'border:1px solid var(--file-viewer-border,rgba(20,35,53,.12))',
+        'border-radius:14px',
+        'background:var(--file-viewer-render-surface-background,#fff)',
+        'box-shadow:0 16px 42px rgba(25,42,54,.08)',
+    ].join(';');
+    const title = documentRef.createElement('strong');
+    title.textContent = state.title;
+    title.style.cssText = 'display:block;margin-bottom:10px;font-size:18px;';
+    const message = documentRef.createElement('p');
+    message.textContent = state.message;
+    message.style.cssText = 'margin:0;white-space:pre-wrap;overflow-wrap:anywhere;';
+    content.append(title, message);
+    wrapper.append(content);
+    container.replaceChildren(wrapper);
+};
 export const createViewer = (container, createOptions = {}) => {
     let options = createOptions.options || {};
     let registry = createBaseRendererRegistry(createOptions, options);
@@ -556,15 +597,27 @@ export const createViewer = (container, createOptions = {}) => {
                     renderContext: {
                         renderPurpose: createOptions.renderPurpose || 'preview',
                         renderNestedBuffer,
+                        requestSnapshotDownload: createFileViewerSnapshotDownload({
+                            getOptions: () => options,
+                            isCurrent: () => requestScope.isCurrentRequest(version),
+                            beforeDownload: () => runBeforeViewerOperation('download'),
+                        }),
                     },
                 });
             }
             catch (error) {
-                if (!requestScope.isCurrentRequest(version)) {
+                if (!requestScope.isCurrentRequest(version) || (loadSignal === null || loadSignal === void 0 ? void 0 : loadSignal.aborted) || isAbortError(error)) {
                     removeRenderTarget(targetHost);
                     return null;
                 }
-                removeRenderTarget(targetHost);
+                applyFileViewerRenderSurfaceState(renderSurfaceState, {
+                    session: null,
+                    exportAdapter: null,
+                    thumbnailAdapter: null,
+                });
+                removeWatermarkOverlay();
+                renderFileViewerErrorState(target, normalized.extension, error, options);
+                emitZoomAndOperationAvailabilityChange();
                 throw error;
             }
             if (!requestScope.isCurrentRequest(version)) {

package/dist/viewer/state.d.ts

@@ -1,6 +1,15 @@
 import { type FileViewerI18nInput } from '../i18n/messages';
 import type { FileViewerRendererCategory, FileViewerStateDescriptor, FileViewerStateTheme } from '../contracts/types';
 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;
+}
+export declare const attachFileViewerErrorMessage: (error: unknown, message: string) => unknown;
 export declare const FILE_VIEWER_PREVIEW_MESSAGES: Readonly<{
     downloading: "正在下载文件资源...";
     streamingPdf: "正在建立 PDF 流式预览...";

package/dist/viewer/state.js

@@ -1,6 +1,39 @@
 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();
+    if (!normalizedMessage) {
+        return error;
+    }
+    if (error && typeof error === 'object') {
+        try {
+            Object.defineProperty(error, FILE_VIEWER_ERROR_MESSAGE, {
+                configurable: true,
+                value: normalizedMessage,
+            });
+            return error;
+        }
+        catch {
+            // Frozen cross-realm errors retain their original value as the cause below.
+        }
+    }
+    const presented = new Error(normalizedMessage);
+    Object.defineProperty(presented, FILE_VIEWER_ERROR_MESSAGE, {
+        configurable: true,
+        value: normalizedMessage,
+    });
+    Object.defineProperty(presented, 'cause', {
+        configurable: true,
+        value: error,
+    });
+    return presented;
+};
 export const FILE_VIEWER_PREVIEW_MESSAGES = Object.freeze({
     downloading: '正在下载文件资源...',
     streamingPdf: '正在建立 PDF 流式预览...',
@@ -247,6 +280,12 @@ const readFileViewerErrorProperty = (error, key) => {
     }
 };
 export const normalizeFileViewerErrorMessage = (error, i18n) => {
+    if (error && typeof error === 'object') {
+        const presentedMessage = readFileViewerErrorProperty(error, FILE_VIEWER_ERROR_MESSAGE);
+        if (typeof presentedMessage === 'string' && presentedMessage.trim()) {
+            return resolveKnownFileViewerErrorMessage(presentedMessage, i18n);
+        }
+    }
     if (error instanceof Error) {
         return resolveKnownFileViewerErrorMessage(error.message, i18n);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@file-viewer/core",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "private": false,
   "type": "module",
   "description": "Framework-neutral modular TypeScript core for File Viewer renderer orchestration, lifecycle APIs, search, zoom, print, and export",
@@ -90,7 +90,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "dompurify": "3.4.14"
+    "dompurify": "3.4.15"
   },
   "devDependencies": {
     "typescript": "^6.0.3"