@file-viewer/core 3.2.2 → 3.3.1

package/dist/renderers/image.js

@@ -1,7 +1,8 @@
-import { registerFileViewerZoomProvider, unregisterFileViewerZoomProvider, } from "../features/document/dom/index.js";
-import { resolveFileViewerFitScale, } from "../features/document/fit.js";
-import { createFileViewerTranslator } from "../i18n/messages.js";
-import { createFileViewerZoomChangeEmitter as createZoomChangeEmitter } from "../features/document/zoom.js";
+import { registerFileViewerZoomProvider, unregisterFileViewerZoomProvider, } from '../features/document/dom/index.js';
+import { installFileViewerImageHandTool } from '../features/document/imageHandTool.js';
+import { resolveFileViewerFitScale, } from '../features/document/fit.js';
+import { createFileViewerTranslator } from '../i18n/messages.js';
+import { createFileViewerZoomChangeEmitter as createZoomChangeEmitter } from '../features/document/zoom.js';
 const imageMimeMap = {
     avif: 'image/avif',
     bmp: 'image/bmp',
@@ -20,7 +21,7 @@ const imageMimeMap = {
 };
 const imageStyle = `
 .image-viewer{position:relative;width:100%;height:100%;overflow:auto;background:var(--file-viewer-render-surface-background,#eef1f4);box-sizing:border-box}
-.image-stage{min-width:100%;min-height:100%;display:flex;align-items:center;justify-content:center;padding:24px;box-sizing:border-box}
+.image-stage{width:max-content;min-width:100%;min-height:100%;display:flex;align-items:center;justify-content:center;padding:24px;box-sizing:border-box}
 .image-stage img{display:block;width:auto;max-width:none;margin:0 auto;border:0;box-shadow:0 18px 48px rgba(15,23,42,.16);background:#fff;cursor:zoom-in}
 .image-stage img:focus-visible{outline:3px solid #2563eb;outline-offset:4px}
 .image-lightbox{position:absolute;inset:0;z-index:40;display:flex;align-items:center;justify-content:center;padding:40px;background:rgba(15,23,42,.9);box-sizing:border-box;opacity:0;visibility:hidden;pointer-events:none;transition:opacity .18s ease,visibility 0s linear .18s}
@@ -127,7 +128,7 @@ const createLightbox = (documentRef, src, t) => {
     };
 };
 export default async function renderImage(buffer, target, type, context) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const t = createFileViewerTranslator(context === null || context === void 0 ? void 0 : context.options);
     const documentRef = target.ownerDocument || document;
     const targetWindow = documentRef.defaultView;
@@ -155,6 +156,8 @@ export default async function renderImage(buffer, target, type, context) {
     image.setAttribute('aria-haspopup', 'dialog');
     stage.append(image);
     root.append(stage);
+    const disposeHandTool = ((_c = (_b = context === null || context === void 0 ? void 0 : context.options) === null || _b === void 0 ? void 0 : _b.image) === null || _c === void 0 ? void 0 : _c.handTool) === true
+        ? installFileViewerImageHandTool(root, context.signal) : () => { };
     const lightbox = createLightbox(documentRef, src, t);
     const openLightbox = () => lightbox.open(image);
     const openLightboxFromKeyboard = (event) => {
@@ -198,6 +201,8 @@ export default async function renderImage(buffer, target, type, context) {
         applyImageZoom();
         zoomEmitter.emit();
     };
+    // Zoom subscribers may resize the parent toolbar. Keep geometry writes out
+    // of ResizeObserver delivery so ancestor notifications remain deliverable.
     const scheduleViewportUpdate = () => {
         if (destroyed || viewportResizeFrame !== null)
             return;
@@ -290,7 +295,7 @@ export default async function renderImage(buffer, target, type, context) {
         subscribe: zoomEmitter.subscribe,
     });
     target.replaceChildren(createStyle(documentRef), root);
-    (((_b = context === null || context === void 0 ? void 0 : context.surface) === null || _b === void 0 ? void 0 : _b.shadowRoot) || target).append(lightbox.element);
+    (((_d = context === null || context === void 0 ? void 0 : context.surface) === null || _d === void 0 ? void 0 : _d.shadowRoot) || target).append(lightbox.element);
     updateViewportSize();
     return {
         $el: target,
@@ -303,6 +308,7 @@ export default async function renderImage(buffer, target, type, context) {
             }
             (_a = context === null || context === void 0 ? void 0 : context.registerThumbnailAdapter) === null || _a === void 0 ? void 0 : _a.call(context, null);
             unregisterFileViewerZoomProvider(root);
+            disposeHandTool();
             resizeObserver.disconnect();
             image.removeEventListener('load', updateViewportSize);
             image.removeEventListener('click', openLightbox);

package/dist/renderers/index.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerBuiltinRendererPreset, FileRenderHandler, FileViewerRenderedInstance } from "../contracts/types.js";
+import type { FileViewerBuiltinRendererPreset, FileRenderHandler, FileViewerRenderedInstance } from '../contracts/types.js';
 type CoreBrowserRendererHandler = FileRenderHandler<FileViewerRenderedInstance, HTMLDivElement>;
 interface CoreBrowserRendererHandlerEntry {
     rendererId: string;

package/dist/renderers/index.js

@@ -1,17 +1,23 @@
-import { DEFAULT_RENDERER_DEFINITIONS } from "../registry/formats.js";
-import { createFileRenderHandlerRegistry } from "../rendering/handler.js";
-import { createFileViewerRendererDispatcher } from "../rendering/dispatcher.js";
-import { createFileViewerUnsupportedState } from "../viewer/state.js";
+// Browser renderer strategy registry.
+//
+// Each entry lazy-loads a concrete renderer only after its format is selected.
+// Keep renderer-specific dependencies inside the leaf renderer files so the
+// core shell and framework wrappers stay fast on first load.
+import { DEFAULT_RENDERER_DEFINITIONS } from '../registry/formats.js';
+import { createFileRenderHandlerRegistry } from '../rendering/handler.js';
+import { createFileViewerRendererDispatcher } from '../rendering/dispatcher.js';
+import { createFileViewerUnsupportedState } from '../viewer/state.js';
 const createWrapper = (el) => ({
     $el: el,
     unmount() {
+        // DOM renderers clean themselves up through their own returned instance.
     },
 });
 export const coreBrowserRendererHandlers = [
     {
         rendererId: 'image',
         handler: async (buffer, target, type, context) => {
-            const { default: renderImage } = await import("./image.js");
+            const { default: renderImage } = await import('./image.js');
             return renderImage(buffer, target, type, context);
         },
     },

package/dist/rendering/dispatcher.d.ts

@@ -1,8 +1,13 @@
-import type { RendererRegistry } from "../contracts/types.js";
+import type { RendererRegistry } from '../contracts/types.js';
 export interface FileViewerRendererHandlerEntry<Handler> {
     rendererId: string;
     handler: Handler;
 }
+/**
+ * Content-signature aware renderers can throw this shape when the filename
+ * extension points at the wrong container. The orchestration layer follows the
+ * redirect once, using the handler registered for the detected renderer id.
+ */
 export interface FileViewerRendererRedirectError extends Error {
     actualRendererId: string;
 }

package/dist/rendering/dispatcher.js

@@ -1,6 +1,6 @@
-import { DEFAULT_RENDERER_DEFINITIONS } from "../registry/formats.js";
-import { createRendererRegistry } from "../registry/registry.js";
-import { normalizeFileExtension } from "../source/index.js";
+import { DEFAULT_RENDERER_DEFINITIONS } from '../registry/formats.js';
+import { createRendererRegistry } from '../registry/registry.js';
+import { normalizeFileExtension } from '../source/index.js';
 export const resolveFileViewerRendererRedirectId = (error) => {
     if (!error || typeof error !== 'object' || !('actualRendererId' in error)) {
         return undefined;

package/dist/rendering/handler.d.ts

@@ -1,6 +1,6 @@
-import type { FileViewerRendererDispatcher } from "./dispatcher.js";
-import { type FileViewerMutableAccessor, type MutableFileViewerRenderReadinessState } from "../source/loading.js";
-import type { FileRenderExportAdapter, FileRenderThumbnailAdapter, FileRenderContext, FileRenderHandler, FileViewerLifecycleContext, FileViewerOptions, FileViewerStyleIsolation, RenderSurface, RendererDefinition, RendererLoadContext, RendererLoader, RendererRegistry, RendererSession } from "../contracts/types.js";
+import type { FileViewerRendererDispatcher } from './dispatcher.js';
+import { type FileViewerMutableAccessor, type MutableFileViewerRenderReadinessState } from '../source/loading.js';
+import type { FileRenderExportAdapter, FileRenderThumbnailAdapter, FileRenderContext, FileRenderHandler, FileViewerLifecycleContext, FileViewerOptions, FileViewerStyleIsolation, RenderSurface, RendererDefinition, RendererLoadContext, RendererLoader, RendererRegistry, RendererSession } from '../contracts/types.js';
 export declare const FILE_VIEWER_RENDER_SESSION_DISPOSE_ERROR_MESSAGE = "\u9884\u89C8\u5185\u5BB9\u5378\u8F7D\u5931\u8D25";
 export interface ResolveFileViewerRenderSessionDisposeErrorMessageInput {
     message?: string;
@@ -21,6 +21,7 @@ export interface RenderFileViewerHandlerInput<Rendered = unknown, Target extends
 export interface CreateFileRenderHandlerLoaderOptions<Rendered = unknown, Target extends HTMLElement = HTMLElement> {
     handler: FileRenderHandler<Rendered, Target>;
     rendererId?: string;
+    /** Allows stream-preferred handlers to receive an empty buffer plus context.streamUrl. */
     allowUrlSource?: boolean;
     getTarget?: (context: RendererLoadContext) => Target;
     createContext?: (context: RendererLoadContext) => FileRenderContext;
@@ -60,6 +61,10 @@ export interface FileViewerStyleHandle {
     remove(): void;
 }
 export interface AppendFileViewerStyleOptions {
+    /**
+     * Constructable stylesheets are useful for long-lived ShadowRoots. Keep this
+     * opt-in so renderer styles still clean up naturally with their target node.
+     */
     adoptedStyleSheet?: boolean;
 }
 export interface ResetFileViewerRenderSurfaceInput<Session extends RendererSession = RendererSession> {
@@ -164,6 +169,11 @@ export interface CreateFileViewerRenderSurfaceActionHandlersInput<Session extend
 export declare const DEFAULT_FILE_VIEWER_RENDER_TARGET_CLASS = "file-render";
 export declare const FILE_VIEWER_RENDER_SURFACE_BACKGROUND_PROPERTY = "--file-viewer-render-surface-background";
 export declare const normalizeFileViewerRenderSurfaceBackground: (value: unknown) => string | null;
+/**
+ * Keeps the public UI option and the renderer-facing CSS custom property in
+ * sync. Custom properties inherit through Shadow DOM, so setting this on the
+ * render host covers both scoped and shadow-isolated renderer targets.
+ */
 export declare const syncFileViewerRenderSurfaceBackground: (target: HTMLElement | null | undefined, options?: Pick<FileViewerOptions, "ui"> | null) => string | null;
 export declare const isFileViewerShadowRoot: (value: unknown) => value is ShadowRoot;
 export declare const getFileViewerShadowRootForNode: (node: Node | null | undefined) => ShadowRoot | null;

package/dist/rendering/handler.js

@@ -1,12 +1,17 @@
-import { DEFAULT_RENDERER_DEFINITIONS } from "../registry/formats.js";
-import { waitForFileViewerNextPaint } from "../output/export.js";
-import { createFileViewerRendererDispatcher } from "./dispatcher.js";
-import { resolveFileViewerRendererRedirectId } from "./dispatcher.js";
-import { createRendererRegistry } from "../registry/registry.js";
-import { getExtension, normalizeFileExtension } from "../source/index.js";
-import { applyFileViewerRenderReadinessState, } from "../source/loading.js";
-import { findFileViewerViewStateProvider } from "../features/document/dom/index.js";
-import { registerFileViewerGenericViewStateProvider } from "../features/document/viewState.js";
+// Rendering orchestration layer.
+//
+// This module adapts registry entries into disposable renderer sessions. It is
+// the only place that should bridge raw buffers, DOM targets, render contexts,
+// export adapters, and readiness state.
+import { DEFAULT_RENDERER_DEFINITIONS } from '../registry/formats.js';
+import { waitForFileViewerNextPaint } from '../output/export.js';
+import { createFileViewerRendererDispatcher } from './dispatcher.js';
+import { resolveFileViewerRendererRedirectId } from './dispatcher.js';
+import { createRendererRegistry } from '../registry/registry.js';
+import { getExtension, normalizeFileExtension } from '../source/index.js';
+import { applyFileViewerRenderReadinessState, } from '../source/loading.js';
+import { findFileViewerViewStateProvider } from '../features/document/dom/index.js';
+import { registerFileViewerGenericViewStateProvider } from '../features/document/viewState.js';
 export const FILE_VIEWER_RENDER_SESSION_DISPOSE_ERROR_MESSAGE = '预览内容卸载失败';
 export const DEFAULT_FILE_VIEWER_RENDER_TARGET_CLASS = 'file-render';
 export const FILE_VIEWER_RENDER_SURFACE_BACKGROUND_PROPERTY = '--file-viewer-render-surface-background';
@@ -19,6 +24,11 @@ export const normalizeFileViewerRenderSurfaceBackground = (value) => {
     const normalized = value.trim();
     return normalized && normalized.toLowerCase() !== 'auto' ? normalized : null;
 };
+/**
+ * Keeps the public UI option and the renderer-facing CSS custom property in
+ * sync. Custom properties inherit through Shadow DOM, so setting this on the
+ * render host covers both scoped and shadow-isolated renderer targets.
+ */
 export const syncFileViewerRenderSurfaceBackground = (target, options) => {
     var _a;
     if (!target) {
@@ -151,6 +161,8 @@ export const appendFileViewerStyle = (target, css, options = {}) => {
     const shadowRoot = getFileViewerShadowRootForNode(target);
     const StyleSheet = shadowRoot ? getConstructableStyleSheet(shadowRoot) : null;
     if (options.adoptedStyleSheet && shadowRoot && StyleSheet) {
+        // Use the target document's constructor. A stylesheet constructed in the
+        // parent window cannot be adopted by a ShadowRoot owned by an iframe.
         const sheet = new StyleSheet();
         sheet.replaceSync(css);
         shadowRoot.adoptedStyleSheets = [...shadowRoot.adoptedStyleSheets, sheet];

package/dist/security/svgResources.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Keep ordinary SVG styles while preventing imports and resource requests.
+ * Obfuscated URL tokens fail closed instead of depending on parser quirks.
+ */
 export declare const sanitizeFileViewerSvgCss: (value: string) => string;
+/** Remove executable attributes and every SVG resource URL that can load data remotely. */
 export declare const sanitizeFileViewerSvgResources: (root: ParentNode) => void;
+/**
+ * Mermaid 11 resolves image-node URLs with `new Image()` while rendering,
+ * before its SVG can be sanitized. Reject image metadata and explicit remote
+ * URLs before calling Mermaid so an untrusted diagram cannot initiate I/O.
+ */
 export declare const assertFileViewerMermaidSourceHasNoExternalResources: (source: string) => void;

package/dist/security/svgResources.js

@@ -44,6 +44,10 @@ const isSafeSvgCssUrl = (value) => {
         /^blob:/i.test(normalized) ||
         SAFE_EMBEDDED_IMAGE_DATA_URL.test(normalized);
 };
+/**
+ * Keep ordinary SVG styles while preventing imports and resource requests.
+ * Obfuscated URL tokens fail closed instead of depending on parser quirks.
+ */
 export const sanitizeFileViewerSvgCss = (value) => {
     const normalizedCharacters = [];
     for (const character of value) {
@@ -89,6 +93,7 @@ export const sanitizeFileViewerSvgCss = (value) => {
     chunks.push(normalized.slice(segmentStart));
     return chunks.join('');
 };
+/** Remove executable attributes and every SVG resource URL that can load data remotely. */
 export const sanitizeFileViewerSvgResources = (root) => {
     root.querySelectorAll('*').forEach(element => {
         for (const attribute of Array.from(element.attributes)) {
@@ -155,10 +160,17 @@ const canonicalizeMermaidSourceForResourceScan = (source) => {
     }
     return output;
 };
+/**
+ * Mermaid 11 resolves image-node URLs with `new Image()` while rendering,
+ * before its SVG can be sanitized. Reject image metadata and explicit remote
+ * URLs before calling Mermaid so an untrusted diagram cannot initiate I/O.
+ */
 export const assertFileViewerMermaidSourceHasNoExternalResources = (source) => {
     const normalized = canonicalizeMermaidSourceForResourceScan(String(source || ''));
     const compact = normalized.replace(/[\t\r\n ]+/g, '');
     const hasImageMetadata = /(?:^|[,{])\s*(?:img|["']img["'])\s*:/im.test(normalized);
+    // HTML math labels are created by Mermaid before its SVG is returned. Reject
+    // loading elements even when their URL uses entities or a relative path.
     const hasLoadingElement = /<\s*(?:img|image|iframe|object|embed|video|audio|source|link|script|style)\b/i.test(normalized);
     const hasRemoteUrl = /(?:https?|ftp):\/\//i.test(compact) ||
         /(?:^|[\s"'(=:,])(?:\/\/|\\\\)[A-Za-z0-9]/m.test(normalized);

package/dist/source/index.d.ts

@@ -1,6 +1,6 @@
-import type { FileViewerFileRef, FileViewerSource, NormalizedFileViewerSource } from "../contracts/types.js";
-export { DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING, createFileViewerTextDecoder, decodeFileViewerTextBuffer, isSingleByteFileViewerTextEncoding, isValidFileViewerUtf8, resolveFileViewerTextEncoding, } from "./textEncoding.js";
-export type { DecodedFileViewerText, FileViewerSingleByteTextEncoding, FileViewerTextEncoding, ResolvedFileViewerTextEncoding, ResolvedFileViewerTextSource, } from "./textEncoding.js";
+import type { FileViewerFileRef, FileViewerSource, NormalizedFileViewerSource } from '../contracts/types.js';
+export { DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING, createFileViewerTextDecoder, decodeFileViewerTextBuffer, isSingleByteFileViewerTextEncoding, isValidFileViewerUtf8, resolveFileViewerTextEncoding, } from './textEncoding.js';
+export type { DecodedFileViewerText, FileViewerSingleByteTextEncoding, FileViewerTextEncoding, ResolvedFileViewerTextEncoding, ResolvedFileViewerTextSource, } from './textEncoding.js';
 export type FileViewerReadResult = string | ArrayBuffer | undefined | null;
 export declare const DEFAULT_FILE_VIEWER_SOURCE_FILENAME = "preview.bin";
 export declare const normalizeFileExtension: (extension: string) => string;

package/dist/source/index.js

@@ -1,4 +1,4 @@
-export { DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING, createFileViewerTextDecoder, decodeFileViewerTextBuffer, isSingleByteFileViewerTextEncoding, isValidFileViewerUtf8, resolveFileViewerTextEncoding, } from "./textEncoding.js";
+export { DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING, createFileViewerTextDecoder, decodeFileViewerTextBuffer, isSingleByteFileViewerTextEncoding, isValidFileViewerUtf8, resolveFileViewerTextEncoding, } from './textEncoding.js';
 export const DEFAULT_FILE_VIEWER_SOURCE_FILENAME = 'preview.bin';
 export const normalizeFileExtension = (extension) => {
     return extension.trim().replace(/^\./, '').toLowerCase();

package/dist/source/loading.d.ts

@@ -1,7 +1,7 @@
-import type { FileViewerFileRef, FileViewerLifecycleContext, FileViewerPdfOptions } from "../contracts/types.js";
-import { type FileViewerLifecycleStateController } from "../lifecycle/operations.js";
-import { type FileViewerErrorMessageFormatter } from "../viewer/state.js";
-import type { FileViewerI18nInput } from "../i18n/messages.js";
+import type { FileViewerFileRef, FileViewerLifecycleContext, FileViewerPdfOptions } from '../contracts/types.js';
+import { type FileViewerLifecycleStateController } from '../lifecycle/operations.js';
+import { type FileViewerErrorMessageFormatter } from '../viewer/state.js';
+import type { FileViewerI18nInput } from '../i18n/messages.js';
 export declare const DEFAULT_PDF_RANGE_CHUNK_SIZE: number;
 export declare const DEFAULT_FILE_VIEWER_STREAMING_PDF_FILENAME = "preview.pdf";
 export declare const FILE_VIEWER_REMOTE_MISSING_DATA_ERROR_MESSAGE = "\u6587\u4EF6\u4E0B\u8F7D\u5931\u8D25";
@@ -314,6 +314,8 @@ export declare const reportFileViewerPreviewLoadError: ({ onLogError, onErrorMes
 export declare const reportFileViewerMissingRemoteData: ({ onErrorMessage, ...messageInput }?: ReportFileViewerMissingRemoteDataInput) => string;
 export interface RunFileViewerRemoteFilePreviewInput<Session = unknown> {
     url: string;
+    filename?: string;
+    type?: string;
     version: number;
     pageHref?: string;
     streaming?: FileViewerPdfOptions['streaming'];
@@ -471,6 +473,8 @@ export interface CreateFileViewerSourceLoadingActionHandlersInput<Session = unkn
     getFile: () => FileViewerFileRef | null | undefined;
     getUrl: () => string | null | undefined;
     getCurrentFilename?: () => string | undefined;
+    getSourceFilename?: () => string | undefined;
+    getSourceType?: () => string | undefined;
     shouldStreamLocalFile?: (input: {
         file: File;
         filename: string;
@@ -550,8 +554,8 @@ export declare const commitFileViewerRenderCompleteState: <Session = unknown>({
 export declare const runFileViewerReadAndRenderFile: <Session = unknown>({ file, version, signal, sourceUrl, source, fallbackFilename, previewTarget, isCurrent, mountRenderedContent, destroyRenderSession, buildRenderCompleteState, onSession, onActiveDocumentContext, onLifecycle, onClearLoadStarted, }: RunFileViewerReadAndRenderFileInput<Session>) => Promise<FileViewerReadAndRenderFileState<Session>>;
 export declare const runFileViewerStreamingPdfPreview: <Session = unknown>({ url, version, filename, previewTarget, isCurrent, mountRenderedContent, destroyRenderSession, buildRenderCompleteState, loadingMessage, signal, typeOverride, i18n, onStartLoading, onSession, onActiveDocumentContext, onLifecycle, onClearLoadStarted, onStopLoading, onError, }: RunFileViewerStreamingPdfPreviewInput<Session>) => Promise<FileViewerStreamingPdfPreviewState<Session>>;
 export declare const runFileViewerLocalFilePreview: <Session = unknown>({ source, version, currentFilename, fallbackFilename, shouldStreamLocalFile, requestController, previewTarget, isCurrent, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, onMarkLoadStarted, onStartLoading, onSession, onActiveDocumentContext, onLifecycle, onClearLoadStarted, onStopLoading, onError, }: RunFileViewerLocalFilePreviewInput<Session>) => Promise<FileViewerLocalFilePreviewState<Session>>;
-export declare const runFileViewerRemoteFilePreview: <Session = unknown>({ url, version, pageHref, streaming, shouldStreamRemoteUrl, previewTarget, requestController, isCurrent, downloadFile, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, i18n, onMarkLoadStarted, onStartLoading, onSetLoadingMessage, onSession, onActiveDocumentContext, onLifecycle, onClearLoadStarted, onStopLoading, onMissingData, onError, }: RunFileViewerRemoteFilePreviewInput<Session>) => Promise<FileViewerRemoteFilePreviewState<Session>>;
-export declare const createFileViewerSourceLoadingActionHandlers: <Session = unknown>({ getFile, getUrl, getCurrentFilename, shouldStreamLocalFile, getPdfStreaming, shouldStreamRemoteUrl, getI18n, getPageHref, previewTarget, requestController, downloadFile, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, formatErrorMessage, onMarkLoadStarted, onClearLoadStarted, onStartLoading, onSetLoadingMessage, onStopLoading, onShowError, onClearError, onResetLoading, onClearRenderedContent, onSession, onActiveDocumentContext, onLifecycle, }: CreateFileViewerSourceLoadingActionHandlersInput<Session>) => FileViewerSourceLoadingActionHandlers<Session>;
+export declare const runFileViewerRemoteFilePreview: <Session = unknown>({ url, filename, type, version, pageHref, streaming, shouldStreamRemoteUrl, previewTarget, requestController, isCurrent, downloadFile, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, i18n, onMarkLoadStarted, onStartLoading, onSetLoadingMessage, onSession, onActiveDocumentContext, onLifecycle, onClearLoadStarted, onStopLoading, onMissingData, onError, }: RunFileViewerRemoteFilePreviewInput<Session>) => Promise<FileViewerRemoteFilePreviewState<Session>>;
+export declare const createFileViewerSourceLoadingActionHandlers: <Session = unknown>({ getFile, getUrl, getCurrentFilename, getSourceFilename, getSourceType, shouldStreamLocalFile, getPdfStreaming, shouldStreamRemoteUrl, getI18n, getPageHref, previewTarget, requestController, downloadFile, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, formatErrorMessage, onMarkLoadStarted, onClearLoadStarted, onStartLoading, onSetLoadingMessage, onStopLoading, onShowError, onClearError, onResetLoading, onClearRenderedContent, onSession, onActiveDocumentContext, onLifecycle, }: CreateFileViewerSourceLoadingActionHandlersInput<Session>) => FileViewerSourceLoadingActionHandlers<Session>;
 export declare const finalizeFileViewerPreviewLoadState: ({ version, isCurrent, onClearLoadStarted, onStopLoading, }: FinalizeFileViewerPreviewLoadStateInput) => void;
 export declare const resolveFileViewerLoadStartMessage: (source: FileViewerLifecycleContext["source"], i18n?: FileViewerI18nInput) => string;
 export declare const commitFileViewerLoadStartState: ({ version, filename, fallbackFilename, filenameTarget, buildState, onMarkLoadStarted, onLifecycle, onStartLoading, }: CommitFileViewerLoadStartStateInput) => FileViewerLoadStartState;
@@ -601,8 +605,9 @@ export interface FileViewerLocationLike {
     href?: string | null;
 }
 export declare const resolveFileViewerPageHref: (locationLike?: FileViewerLocationLike) => string | undefined;
-export declare const resolveFileViewerRemoteSourcePlan: ({ filename, fallbackFilename, pageHref, streaming, shouldStreamRemoteUrl, url, }: {
+export declare const resolveFileViewerRemoteSourcePlan: ({ filename, type, fallbackFilename, pageHref, streaming, shouldStreamRemoteUrl, url, }: {
     filename?: string;
+    type?: string;
     fallbackFilename?: string;
     pageHref?: string;
     streaming?: FileViewerPdfOptions["streaming"];

package/dist/source/loading.js

@@ -1,7 +1,7 @@
-import { buildFileViewerLifecycleContext, } from "../lifecycle/operations.js";
-import { resolveFileViewerPreviewMessages, } from "../viewer/state.js";
-import { translateFileViewerMessage } from "../i18n/messages.js";
-import { DEFAULT_FILE_VIEWER_SOURCE_FILENAME, getExtension, normalizeFilename, readFileViewerBuffer, resolveFileViewerSourceFilename, wrapFileViewerFileRef, } from "./index.js";
+import { buildFileViewerLifecycleContext, } from '../lifecycle/operations.js';
+import { resolveFileViewerPreviewMessages, } from '../viewer/state.js';
+import { translateFileViewerMessage } from '../i18n/messages.js';
+import { DEFAULT_FILE_VIEWER_SOURCE_FILENAME, getExtension, normalizeFilename, normalizeFileExtension, readFileViewerBuffer, resolveFileViewerSourceFilename, wrapFileViewerFileRef, } from './index.js';
 export const DEFAULT_PDF_RANGE_CHUNK_SIZE = 64 * 1024;
 export const DEFAULT_FILE_VIEWER_STREAMING_PDF_FILENAME = 'preview.pdf';
 export const FILE_VIEWER_REMOTE_MISSING_DATA_ERROR_MESSAGE = '文件下载失败';
@@ -117,6 +117,7 @@ const encodeFileViewerUrlPathSegment = (segment) => {
         decoded = decodeURIComponent(segment);
     }
     catch {
+        // Invalid percent escapes are treated as literal filename characters.
     }
     return encodeURIComponent(decoded)
         .replace(/%3A/gi, ':')
@@ -596,14 +597,18 @@ export const runFileViewerLocalFilePreview = async ({ source, version, currentFi
         });
     }
 };
-export const runFileViewerRemoteFilePreview = async ({ url, version, pageHref, streaming, shouldStreamRemoteUrl, previewTarget, requestController, isCurrent, downloadFile, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, i18n, onMarkLoadStarted, onStartLoading, onSetLoadingMessage, onSession, onActiveDocumentContext, onLifecycle, onClearLoadStarted, onStopLoading, onMissingData, onError, }) => {
+export const runFileViewerRemoteFilePreview = async ({ url, filename, type, version, pageHref, streaming, shouldStreamRemoteUrl, previewTarget, requestController, isCurrent, downloadFile, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, i18n, onMarkLoadStarted, onStartLoading, onSetLoadingMessage, onSession, onActiveDocumentContext, onLifecycle, onClearLoadStarted, onStopLoading, onMissingData, onError, }) => {
     let remoteSource = resolveFileViewerRemoteSourcePlan({
+        filename,
+        type,
         pageHref,
         streaming,
         url,
     });
     const sourceUrl = remoteSource.url;
     const controller = requestController.createAbortController();
+    // The streaming helper finalizes its own load state; probe/download paths
+    // are finalized here, including cancellation before a renderer is mounted.
     let streamFinalized = false;
     try {
         if (!remoteSource.streamPdf && shouldStreamRemoteUrl) {
@@ -664,7 +669,7 @@ export const runFileViewerRemoteFilePreview = async ({ url, version, pageHref, s
                     ? undefined
                     : resolveFileViewerPreviewMessages(i18n).downloading,
                 signal: controller === null || controller === void 0 ? void 0 : controller.signal,
-                typeOverride: remoteSource.streamType,
+                typeOverride: remoteSource.streamPdf ? 'pdf' : remoteSource.streamType,
                 onStartLoading,
                 onSession,
                 onActiveDocumentContext,
@@ -808,7 +813,7 @@ export const runFileViewerRemoteFilePreview = async ({ url, version, pageHref, s
         }
     }
 };
-export const createFileViewerSourceLoadingActionHandlers = ({ getFile, getUrl, getCurrentFilename, shouldStreamLocalFile, getPdfStreaming, shouldStreamRemoteUrl, getI18n, getPageHref, previewTarget, requestController, downloadFile, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, formatErrorMessage, onMarkLoadStarted, onClearLoadStarted, onStartLoading, onSetLoadingMessage, onStopLoading, onShowError, onClearError, onResetLoading, onClearRenderedContent, onSession, onActiveDocumentContext, onLifecycle, }) => {
+export const createFileViewerSourceLoadingActionHandlers = ({ getFile, getUrl, getCurrentFilename, getSourceFilename, getSourceType, shouldStreamLocalFile, getPdfStreaming, shouldStreamRemoteUrl, getI18n, getPageHref, previewTarget, requestController, downloadFile, mountRenderedContent, destroyRenderSession, buildLoadStartState, buildRenderCompleteState, formatErrorMessage, onMarkLoadStarted, onClearLoadStarted, onStartLoading, onSetLoadingMessage, onStopLoading, onShowError, onClearError, onResetLoading, onClearRenderedContent, onSession, onActiveDocumentContext, onLifecycle, }) => {
     const isCurrentRequest = (version) => requestController.isCurrent(version);
     const previewLocalFile = async (source, version) => {
         var _a;
@@ -853,6 +858,8 @@ export const createFileViewerSourceLoadingActionHandlers = ({ getFile, getUrl, g
     const previewRemoteFile = async (url, version) => {
         return await runFileViewerRemoteFilePreview({
             url,
+            filename: getSourceFilename === null || getSourceFilename === void 0 ? void 0 : getSourceFilename(),
+            type: getSourceType === null || getSourceType === void 0 ? void 0 : getSourceType(),
             version,
             pageHref: getPageHref === null || getPageHref === void 0 ? void 0 : getPageHref(),
             streaming: getPdfStreaming === null || getPdfStreaming === void 0 ? void 0 : getPdfStreaming(),
@@ -1034,18 +1041,16 @@ export const shouldStreamPdfUrl = ({ extension, pageHref, streaming, url, }) =>
 export const resolveFileViewerPageHref = (locationLike) => {
     return (locationLike === null || locationLike === void 0 ? void 0 : locationLike.href) || undefined;
 };
-export const resolveFileViewerRemoteSourcePlan = ({ filename, fallbackFilename = DEFAULT_FILE_VIEWER_SOURCE_FILENAME, pageHref, streaming, shouldStreamRemoteUrl, url, }) => {
+export const resolveFileViewerRemoteSourcePlan = ({ filename, type, fallbackFilename = DEFAULT_FILE_VIEWER_SOURCE_FILENAME, pageHref, streaming, shouldStreamRemoteUrl, url, }) => {
     const sourceUrl = normalizeFileViewerSourceUrl(url) || url;
     const nextFilename = normalizeFilename(filename || url, fallbackFilename);
-    const extension = getExtension(nextFilename);
-    const streamPdf = pageHref
-        ? shouldStreamPdfUrl({
-            extension,
-            pageHref,
-            streaming,
-            url: sourceUrl,
-        })
-        : false;
+    const extension = normalizeFileExtension(type || getExtension(nextFilename));
+    const streamPdf = shouldStreamPdfUrl({
+        extension,
+        pageHref: pageHref || '',
+        streaming,
+        url: sourceUrl,
+    });
     const streamDecision = !streamPdf
         ? shouldStreamRemoteUrl === null || shouldStreamRemoteUrl === void 0 ? void 0 : shouldStreamRemoteUrl({
             url: sourceUrl,

package/dist/source/precheck.d.ts

@@ -1,10 +1,14 @@
-import type { FileViewerFileRef, FileViewerSource } from "../contracts/types.js";
+import type { FileViewerFileRef, FileViewerSource } from '../contracts/types.js';
 export type FileViewerPrecheckStatus = 'ready' | 'invalid' | 'unsupported';
 export type FileViewerPrecheckReason = 'content-valid' | 'content-not-inspected' | 'content-inconclusive' | 'empty-structured-file' | 'signature-mismatch' | 'invalid-package' | 'missing-package-part' | 'unsupported-extension';
 export interface FileViewerPrecheckOptions {
+    /** Filename used when a Blob or ArrayBuffer has no name. */
     filename?: string;
+    /** Explicit extension, with or without a leading dot. */
     type?: string;
+    /** Restricts the result to the renderers installed by the host application. */
     supportedExtensions?: Iterable<string>;
+    /** Maximum ZIP central-directory bytes read from a Blob. Defaults to 8 MiB. */
     maxPackageMetadataBytes?: number;
 }
 export interface FileViewerPrecheckResult {
@@ -13,6 +17,7 @@ export interface FileViewerPrecheckResult {
     rendererId: string | null;
     supported: boolean;
     inspected: boolean;
+    /** `null` means the extension is supported but no structural validator exists. */
     valid: boolean | null;
     previewable: boolean;
     status: FileViewerPrecheckStatus;
@@ -20,5 +25,12 @@ export interface FileViewerPrecheckResult {
     missingParts: string[];
 }
 type FileViewerPrecheckInput = FileViewerSource | FileViewerFileRef;
+/**
+ * Performs a cheap, renderer-free capability and structure check.
+ *
+ * This intentionally does not promise rendering fidelity. A `ready` result
+ * means the extension is available and any known container/signature checks
+ * passed; the real renderer remains the final authority for malformed content.
+ */
 export declare const precheckFileViewerSource: (input: FileViewerPrecheckInput, options?: FileViewerPrecheckOptions) => Promise<FileViewerPrecheckResult>;
 export {};

package/dist/source/precheck.js

@@ -1,5 +1,5 @@
-import { DEFAULT_RENDERER_DEFINITIONS, DEFAULT_SUPPORTED_EXTENSIONS } from "../registry/formats.js";
-import { getExtension, normalizeFileExtension, normalizeFilename, normalizeSource, } from "./index.js";
+import { DEFAULT_RENDERER_DEFINITIONS, DEFAULT_SUPPORTED_EXTENSIONS } from '../registry/formats.js';
+import { getExtension, normalizeFileExtension, normalizeFilename, normalizeSource, } from './index.js';
 const DEFAULT_MAX_PACKAGE_METADATA_BYTES = 8 * 1024 * 1024;
 const ZIP_LOCAL_SIGNATURE = 0x04034b50;
 const ZIP_CENTRAL_SIGNATURE = 0x02014b50;
@@ -203,6 +203,13 @@ const inspectStructuredContent = async (source, extension, maxPackageMetadataByt
     }
     return { inspected: false, valid: null, reason: 'content-not-inspected' };
 };
+/**
+ * Performs a cheap, renderer-free capability and structure check.
+ *
+ * This intentionally does not promise rendering fidelity. A `ready` result
+ * means the extension is available and any known container/signature checks
+ * passed; the real renderer remains the final authority for malformed content.
+ */
 export const precheckFileViewerSource = async (input, options = {}) => {
     var _a;
     const source = toSource(input, options);

package/dist/source/textEncoding.d.ts

@@ -1,6 +1,15 @@
+/**
+ * Single-byte legacy encodings supported by the browser TextDecoder API.
+ * Each byte decodes to one UTF-16 code unit, so the virtual
+ * large-text renderer can slice them at any byte offset.
+ */
 export type FileViewerSingleByteTextEncoding = 'iso-8859-1' | 'iso-8859-2' | 'iso-8859-15' | 'windows-1250' | 'windows-1251' | 'windows-1252';
 export type FileViewerTextEncoding = 'auto' | 'utf-8' | 'utf-16le' | 'utf-16be' | 'gbk' | 'gb18030' | FileViewerSingleByteTextEncoding;
 export type ResolvedFileViewerTextEncoding = Exclude<FileViewerTextEncoding, 'auto' | 'gbk'>;
+/**
+ * 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 declare const DEFAULT_FILE_VIEWER_TEXT_FALLBACK_ENCODING: ResolvedFileViewerTextEncoding;
 export declare const isSingleByteFileViewerTextEncoding: (encoding: string | undefined) => encoding is FileViewerSingleByteTextEncoding;
 export interface DecodedFileViewerText {
@@ -12,6 +21,15 @@ export interface ResolvedFileViewerTextSource {
     bomLength: number;
 }
 export declare const isValidFileViewerUtf8: (bytes: Uint8Array) => boolean;
+/**
+ * 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 declare const resolveFileViewerTextEncoding: (bytes: Uint8Array, encoding?: FileViewerTextEncoding | string, fallbackEncoding?: FileViewerTextEncoding | string) => ResolvedFileViewerTextSource;
 export declare const createFileViewerTextDecoder: (encoding: ResolvedFileViewerTextEncoding) => TextDecoder;
 export declare const decodeFileViewerTextBuffer: (data: ArrayBuffer, encoding?: FileViewerTextEncoding | string, fallbackEncoding?: FileViewerTextEncoding | string) => DecodedFileViewerText;

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;