@file-viewer/core 2.1.1 → 2.1.2

package/dist/contracts/types.d.ts

@@ -195,6 +195,15 @@ export interface FileViewerCadOptions {
 }
 export type FileViewerRendererMode = 'extend' | 'replace';
 export type FileViewerBuiltinRendererPreset = 'all' | 'lite' | 'none';
+export interface FileViewerAutoRendererOptions {
+    /**
+     * Uses renderer presets registered by build tooling or preset side-effect imports.
+     *
+     * Defaults to true in `extend` mode and false in `replace` mode so applications
+     * can keep a strict hand-picked renderer registry when needed.
+     */
+    enabled?: boolean;
+}
 export interface FileViewerSearchOptions {
     enabled?: boolean;
     caseSensitive?: boolean;
@@ -230,6 +239,12 @@ export interface FileViewerOptions {
      * allowing renderer plugins or presets to be installed through `renderers`.
      */
     builtinRenderers?: FileViewerBuiltinRendererPreset;
+    /**
+     * Enables renderer presets that were auto-registered by `@file-viewer/vite-plugin`
+     * or by explicitly importing a preset package. Set to false when a product wants
+     * total manual control through `renderers`.
+     */
+    autoRenderers?: boolean | FileViewerAutoRendererOptions;
     renderers?: FileViewerRendererPluginInput;
     watermark?: boolean | FileViewerWatermarkOptions;
     toolbar?: boolean | FileViewerToolbarOptions;

package/dist/index.d.ts

@@ -14,7 +14,8 @@ export { applyPrintPageSize, buildPrintPageStyle, formatCssPixels, getElementPri
 export type { ApplyPrintPageSizeOptions, BuildPrintPageStyleOptions, PrintPageSize, } from './output/printLayout';
 export { DEFAULT_FILE_VIEWER_DOWNLOAD_FILENAME, DEFAULT_FILE_VIEWER_EXPORT_FILENAME, DEFAULT_FILE_VIEWER_PREVIEW_TITLE, FILE_VIEWER_OPERATION_ACTION_ERROR_PREFIXES, createFileViewerOperationActionHandlers, createFileViewerOriginalSourceState, createFileViewerOriginalSourceStateFromNormalizedSource, createFileViewerPublicOperationActionHandlers, executeFileViewerDownloadOperation, executeFileViewerExportHtmlOperation, executeFileViewerPrintOperation, hasFileViewerOriginalSource, resolveFileViewerDisplayFilename, resolveFileViewerOperationActionErrorMessage, resolveFileViewerOperationFilename, resolveFileViewerOriginalFilename, } from './viewer/operations';
 export type { CreateFileViewerOperationActionHandlersInput, FileViewerOperationActionErrorFormatter, FileViewerFileOperationType, FileViewerOperationActionErrorContext, FileViewerOperationActionErrorPrefixes, FileViewerOperationActionHandlers, FileViewerPublicOperationActionHandlers, ResolveFileViewerOperationActionErrorMessageInput, } from './viewer/operations';
-export { collectFileViewerRendererPlugins, createRendererRegistry, installFileViewerRendererPlugins, } from './registry/registry';
+export { clearFileViewerAutoRendererPresets, collectFileViewerRendererPlugins, createRendererRegistry, getFileViewerAutoRendererPresetVersion, installFileViewerRendererPlugins, listFileViewerAutoRendererPresets, registerFileViewerAutoRendererPreset, unregisterFileViewerAutoRendererPreset, } from './registry/registry';
+export type { RegisterFileViewerAutoRendererPresetOptions, } from './registry/registry';
 export { CORE_LITE_RENDERER_IDS, coreBrowserRendererHandlers, coreLiteBrowserRendererHandlers, coreLiteRendererDefinitions, createFileViewerCoreRendererRegistry, fileViewerCoreRendererDispatcher, fileViewerCoreRendererRegistry, fileViewerCoreRendererRegistryBridge, missingFileViewerCoreRendererHandlers, } from './renderers/index';
 export type { CreateFileViewerCoreRendererRegistryOptions, } from './renderers/index';
 export declare const renderFileViewerAudio: (buffer: ArrayBuffer, target: HTMLDivElement, type?: string) => Promise<FileViewerRenderedInstance>;
@@ -56,8 +57,8 @@ export { buildFileRenderContextFromLoadContext, applyFileViewerRenderSurfaceStat
 export type { CreateFileViewerRenderSurfaceActionHandlersInput, CreateFileViewerRenderReadinessTargetInput, CreateFileViewerRenderSurfaceStateTargetInput, FileViewerRenderSurfaceActionHandlers, FileViewerRenderSurfaceClearState, FileViewerRenderSurfaceState, FileViewerRenderSurfaceMountContext, FileViewerRenderSessionDisposeErrorLogger, MutableFileViewerRenderSurfaceState, ReportFileViewerRenderSessionDisposeErrorInput, ResetFileViewerRenderSurfaceInput, ResolveFileViewerRenderSessionDisposeErrorMessageInput, RunFileViewerRenderSurfaceClearInput, RunFileViewerRenderSurfaceMountInput, } from './rendering/handler';
 export { DEFAULT_FILE_VIEWER_SOURCE_FILENAME, decodeFilename, getExtension, normalizeFileExtension, normalizeFilename, resolveFileViewerSourceFilename, normalizeSource, readFileViewerBuffer, readFileViewerDataUrl, readFileViewerText, wrapFileViewerFileRef, } from './source';
 export type { FileViewerReadResult } from './source';
-export { DEFAULT_FILE_VIEWER_STATE_THEME, DEFAULT_FILE_VIEWER_UNSUPPORTED_DESCRIPTION, FILE_VIEWER_PREVIEW_MESSAGES, createFileViewerEmptyState, createFileViewerErrorState, createFileViewerPreviewLoadingState, createFileViewerReadyState, createFileViewerUnsupportedState, formatFileViewerErrorMessage, normalizeFileViewerErrorMessage, } from './viewer/state';
-export type { FileViewerErrorMessageFormatter, } from './viewer/state';
+export { DEFAULT_FILE_VIEWER_STATE_THEME, DEFAULT_FILE_VIEWER_UNSUPPORTED_DESCRIPTION, FILE_VIEWER_PREVIEW_MESSAGES, createFileViewerEmptyState, createFileViewerErrorState, createFileViewerPreviewLoadingState, createFileViewerReadyState, createFileViewerUnsupportedState, formatFileViewerErrorMessage, normalizeFileViewerErrorMessage, resolveFileViewerRendererInstallHint, } from './viewer/state';
+export type { FileViewerErrorMessageFormatter, FileViewerRendererInstallHint, } from './viewer/state';
 export { buildFileViewerWatermarkBackgroundImage, buildFileViewerWatermarkInlineStyle, buildFileViewerWatermarkStyle, buildFileViewerWatermarkSvg, normalizeFileViewerWatermark, resolveFileViewerWatermarkPresentationState, } from './features/watermark';
 export type { FileViewerWatermarkPresentationState, FileViewerWatermarkStyle, } from './features/watermark';
 export { cancelFileViewerPreviewRequest, DEFAULT_FILE_VIEWER_STREAMING_PDF_FILENAME, DEFAULT_FILE_VIEWER_PREVIEW_LOAD_ERROR_LOGGER, DEFAULT_PDF_RANGE_CHUNK_SIZE, FILE_VIEWER_PREVIEW_LOAD_ERROR_PREFIXES, FILE_VIEWER_REMOTE_MISSING_DATA_ERROR_MESSAGE, applyFileViewerEmptyPreviewState, applyFileViewerPreviewFilenameState, applyFileViewerPreviewSourceUrlState, applyFileViewerReadPreviewState, applyFileViewerRenderReadinessState, applyFileViewerPreviewRequestResetState, commitFileViewerEmptyPreviewResetState, commitFileViewerLoadStartState, commitFileViewerPreviewRequestStartState, commitFileViewerRenderCompleteState, commitFileViewerRemoteDownloadState, createFileViewerEmptyPreviewState, createFileViewerLoadStartState, createFileViewerPreviewStateTarget, createFileViewerSourceLoadingActionHandlers, createFileViewerReadPreviewState, createFileViewerPreviewRequestResetState, createFileViewerRenderCompleteState, createFileViewerRequestController, createFileViewerRequestScope, createFileViewerStreamingPdfPlaceholderFile, finalizeFileViewerPreviewLoadState, hasFileViewerPreviewSource, isFileViewerAbortError, isSameOriginUrl, normalizeFileViewerSourceUrl, normalizePdfStreamingMode, resolveFileViewerFileRefSourcePlan, resolveFileViewerLoadStartMessage, resolveFileViewerMissingRemoteDataErrorMessage, resolveFileViewerPreviewLoadErrorMessage, resolveFileViewerPreviewRequestReason, resolveFileViewerRemoteSourcePlan, resolveFileViewerPageHref, reportFileViewerMissingRemoteData, reportFileViewerPreviewLoadError, runFileViewerLocalFilePreview, runFileViewerPreviewComponentUnmount, runFileViewerPreviewRequest, runFileViewerPreviewSourceChange, runFileViewerRemoteFilePreview, runFileViewerReadAndRenderFile, runFileViewerStreamingPdfPreview, shouldStreamPdfUrl, } from './source/loading';

package/dist/index.js

@@ -8,7 +8,7 @@ export { DEFAULT_FILE_VIEWER_ANCHOR_EXCLUDE_SELECTOR, DEFAULT_FILE_VIEWER_ANCHOR
 export { buildFileViewerRenderedHtmlDocument, buildExportHtmlDocument, collectDocumentStyles, prepareFileViewerRenderedContentForSnapshot, replaceFileViewerCanvasWithImages, resolveFileViewerPrintStyle, triggerFileViewerBlobDownload, triggerFileViewerUrlDownload, waitForFileViewerImages, waitForFileViewerNextPaint, waitForFileViewerPrintWindowReady, } from './output/export.js';
 export { applyPrintPageSize, buildPrintPageStyle, formatCssPixels, getElementPrintPageSize, } from './output/printLayout.js';
 export { DEFAULT_FILE_VIEWER_DOWNLOAD_FILENAME, DEFAULT_FILE_VIEWER_EXPORT_FILENAME, DEFAULT_FILE_VIEWER_PREVIEW_TITLE, FILE_VIEWER_OPERATION_ACTION_ERROR_PREFIXES, createFileViewerOperationActionHandlers, createFileViewerOriginalSourceState, createFileViewerOriginalSourceStateFromNormalizedSource, createFileViewerPublicOperationActionHandlers, executeFileViewerDownloadOperation, executeFileViewerExportHtmlOperation, executeFileViewerPrintOperation, hasFileViewerOriginalSource, resolveFileViewerDisplayFilename, resolveFileViewerOperationActionErrorMessage, resolveFileViewerOperationFilename, resolveFileViewerOriginalFilename, } from './viewer/operations.js';
-export { collectFileViewerRendererPlugins, createRendererRegistry, installFileViewerRendererPlugins, } from './registry/registry.js';
+export { clearFileViewerAutoRendererPresets, collectFileViewerRendererPlugins, createRendererRegistry, getFileViewerAutoRendererPresetVersion, installFileViewerRendererPlugins, listFileViewerAutoRendererPresets, registerFileViewerAutoRendererPreset, unregisterFileViewerAutoRendererPreset, } from './registry/registry.js';
 export { CORE_LITE_RENDERER_IDS, coreBrowserRendererHandlers, coreLiteBrowserRendererHandlers, coreLiteRendererDefinitions, createFileViewerCoreRendererRegistry, fileViewerCoreRendererDispatcher, fileViewerCoreRendererRegistry, fileViewerCoreRendererRegistryBridge, missingFileViewerCoreRendererHandlers, } from './renderers/index.js';
 export const renderFileViewerAudio = async (buffer, target, type) => {
     void buffer;
@@ -168,7 +168,7 @@ export { resolveFileViewerPresentationState, } from './presentation/state.js';
 export { createFileViewerRendererDispatcher, } from './rendering/dispatcher.js';
 export { buildFileRenderContextFromLoadContext, applyFileViewerRenderSurfaceState, clearFileViewerRenderSurface, createFileRenderHandlerRendererSession, createFileRenderHandlerRegistry, createFileRenderHandlerLoader, createFileViewerRenderSurfaceActionHandlers, createFileViewerRenderReadinessTarget, createFileViewerRenderSurfaceState, createFileViewerRenderSurfaceStateTarget, createFileViewerRenderTarget, DEFAULT_FILE_VIEWER_RENDER_TARGET_CLASS, DEFAULT_FILE_VIEWER_RENDER_SESSION_DISPOSE_ERROR_LOGGER, FILE_VIEWER_RENDER_SESSION_DISPOSE_ERROR_MESSAGE, disposeActiveFileViewerRendererSession, disposeFileViewerRendered, disposeFileViewerRendererSession, removeFileViewerRenderTarget, reportFileViewerRenderSessionDisposeError, resetFileViewerRenderSurface, resolveFileViewerRenderSessionDisposeErrorMessage, runFileViewerRenderSurfaceClear, runFileViewerRenderSurfaceMount, renderFileViewerHandler, } from './rendering/handler.js';
 export { DEFAULT_FILE_VIEWER_SOURCE_FILENAME, decodeFilename, getExtension, normalizeFileExtension, normalizeFilename, resolveFileViewerSourceFilename, normalizeSource, readFileViewerBuffer, readFileViewerDataUrl, readFileViewerText, wrapFileViewerFileRef, } from './source/index.js';
-export { DEFAULT_FILE_VIEWER_STATE_THEME, DEFAULT_FILE_VIEWER_UNSUPPORTED_DESCRIPTION, FILE_VIEWER_PREVIEW_MESSAGES, createFileViewerEmptyState, createFileViewerErrorState, createFileViewerPreviewLoadingState, createFileViewerReadyState, createFileViewerUnsupportedState, formatFileViewerErrorMessage, normalizeFileViewerErrorMessage, } from './viewer/state.js';
+export { DEFAULT_FILE_VIEWER_STATE_THEME, DEFAULT_FILE_VIEWER_UNSUPPORTED_DESCRIPTION, FILE_VIEWER_PREVIEW_MESSAGES, createFileViewerEmptyState, createFileViewerErrorState, createFileViewerPreviewLoadingState, createFileViewerReadyState, createFileViewerUnsupportedState, formatFileViewerErrorMessage, normalizeFileViewerErrorMessage, resolveFileViewerRendererInstallHint, } from './viewer/state.js';
 export { buildFileViewerWatermarkBackgroundImage, buildFileViewerWatermarkInlineStyle, buildFileViewerWatermarkStyle, buildFileViewerWatermarkSvg, normalizeFileViewerWatermark, resolveFileViewerWatermarkPresentationState, } from './features/watermark.js';
 export { cancelFileViewerPreviewRequest, DEFAULT_FILE_VIEWER_STREAMING_PDF_FILENAME, DEFAULT_FILE_VIEWER_PREVIEW_LOAD_ERROR_LOGGER, DEFAULT_PDF_RANGE_CHUNK_SIZE, FILE_VIEWER_PREVIEW_LOAD_ERROR_PREFIXES, FILE_VIEWER_REMOTE_MISSING_DATA_ERROR_MESSAGE, applyFileViewerEmptyPreviewState, applyFileViewerPreviewFilenameState, applyFileViewerPreviewSourceUrlState, applyFileViewerReadPreviewState, applyFileViewerRenderReadinessState, applyFileViewerPreviewRequestResetState, commitFileViewerEmptyPreviewResetState, commitFileViewerLoadStartState, commitFileViewerPreviewRequestStartState, commitFileViewerRenderCompleteState, commitFileViewerRemoteDownloadState, createFileViewerEmptyPreviewState, createFileViewerLoadStartState, createFileViewerPreviewStateTarget, createFileViewerSourceLoadingActionHandlers, createFileViewerReadPreviewState, createFileViewerPreviewRequestResetState, createFileViewerRenderCompleteState, createFileViewerRequestController, createFileViewerRequestScope, createFileViewerStreamingPdfPlaceholderFile, finalizeFileViewerPreviewLoadState, hasFileViewerPreviewSource, isFileViewerAbortError, isSameOriginUrl, normalizeFileViewerSourceUrl, normalizePdfStreamingMode, resolveFileViewerFileRefSourcePlan, resolveFileViewerLoadStartMessage, resolveFileViewerMissingRemoteDataErrorMessage, resolveFileViewerPreviewLoadErrorMessage, resolveFileViewerPreviewRequestReason, resolveFileViewerRemoteSourcePlan, resolveFileViewerPageHref, reportFileViewerMissingRemoteData, reportFileViewerPreviewLoadError, runFileViewerLocalFilePreview, runFileViewerPreviewComponentUnmount, runFileViewerPreviewRequest, runFileViewerPreviewSourceChange, runFileViewerRemoteFilePreview, runFileViewerReadAndRenderFile, runFileViewerStreamingPdfPreview, shouldStreamPdfUrl, } from './source/loading.js';
 export { createViewer } from './viewer/createViewer.js';

package/dist/registry/registry.d.ts

@@ -1,4 +1,15 @@
 import type { FileViewerRendererHandlerRegistration, FileViewerRendererPluginInput, FileViewerRendererPlugin, RendererDefinition, RendererRegistry } from '../contracts/types';
+export interface RegisterFileViewerAutoRendererPresetOptions {
+    /**
+     * Stable key used to replace an existing auto preset registration.
+     */
+    id?: string;
+    /**
+     * Package name is useful for diagnostics and gives generated integrations a
+     * deterministic id even when the preset input is an array.
+     */
+    packageName?: string;
+}
 export declare const createRendererRegistry: (initialDefinitions?: readonly RendererDefinition[]) => RendererRegistry;
 export interface InstallFileViewerRendererPluginsOptions<Handler = unknown> {
     registry: RendererRegistry;
@@ -6,4 +17,9 @@ export interface InstallFileViewerRendererPluginsOptions<Handler = unknown> {
     registerHandler?: (registration: FileViewerRendererHandlerRegistration<Handler>) => void;
 }
 export declare const collectFileViewerRendererPlugins: <Handler = unknown>(input?: FileViewerRendererPluginInput<Handler> | null) => FileViewerRendererPlugin<Handler>[];
+export declare const registerFileViewerAutoRendererPreset: <Handler = unknown>(input: FileViewerRendererPluginInput<Handler>, options?: RegisterFileViewerAutoRendererPresetOptions) => () => void;
+export declare const unregisterFileViewerAutoRendererPreset: (id: string) => boolean;
+export declare const clearFileViewerAutoRendererPresets: () => void;
+export declare const listFileViewerAutoRendererPresets: <Handler = unknown>() => FileViewerRendererPluginInput<Handler>[];
+export declare const getFileViewerAutoRendererPresetVersion: () => number;
 export declare const installFileViewerRendererPlugins: <Handler = unknown>({ registry, plugins, registerHandler, }: InstallFileViewerRendererPluginsOptions<Handler>) => Promise<RendererRegistry>;

package/dist/registry/registry.js

@@ -1,5 +1,16 @@
 import { DEFAULT_RENDERER_DEFINITIONS } from './formats.js';
 import { normalizeFileExtension } from '../source/index.js';
+const autoRendererBucketKey = '__flyfish_file_viewer_auto_renderer_presets__';
+const getAutoRendererBucket = () => {
+    const host = globalThis;
+    if (!host[autoRendererBucketKey]) {
+        host[autoRendererBucketKey] = {
+            version: 0,
+            presets: new Map(),
+        };
+    }
+    return host[autoRendererBucketKey];
+};
 const normalizeDefinition = (definition) => ({
     ...definition,
     extensions: definition.extensions.map(normalizeFileExtension),
@@ -77,6 +88,55 @@ export const collectFileViewerRendererPlugins = (input) => {
     }
     return [input];
 };
+const resolveAutoRendererPresetId = (input, options = {}) => {
+    if (options.id) {
+        return options.id;
+    }
+    if (options.packageName) {
+        return options.packageName;
+    }
+    if (isRendererPreset(input)) {
+        return input.id;
+    }
+    if (!Array.isArray(input) && input && typeof input === 'object' && 'id' in input) {
+        return String(input.id);
+    }
+    return 'file-viewer-auto-renderers';
+};
+export const registerFileViewerAutoRendererPreset = (input, options = {}) => {
+    const bucket = getAutoRendererBucket();
+    const id = resolveAutoRendererPresetId(input, options);
+    const existing = bucket.presets.get(id);
+    if ((existing === null || existing === void 0 ? void 0 : existing.input) !== input || existing.packageName !== options.packageName) {
+        bucket.presets.set(id, {
+            id,
+            packageName: options.packageName,
+            input: input,
+        });
+        bucket.version += 1;
+    }
+    return () => {
+        unregisterFileViewerAutoRendererPreset(id);
+    };
+};
+export const unregisterFileViewerAutoRendererPreset = (id) => {
+    const bucket = getAutoRendererBucket();
+    const removed = bucket.presets.delete(id);
+    if (removed) {
+        bucket.version += 1;
+    }
+    return removed;
+};
+export const clearFileViewerAutoRendererPresets = () => {
+    const bucket = getAutoRendererBucket();
+    if (!bucket.presets.size) {
+        return;
+    }
+    bucket.presets.clear();
+    bucket.version += 1;
+};
+export const listFileViewerAutoRendererPresets = () => Array.from(getAutoRendererBucket().presets.values()).map(entry => entry.input);
+export const getFileViewerAutoRendererPresetVersion = () => getAutoRendererBucket().version;
 export const installFileViewerRendererPlugins = async ({ registry, plugins, registerHandler, }) => {
     var _a, _b, _c;
     for (const plugin of plugins) {

package/dist/viewer/createViewer.js

@@ -10,7 +10,7 @@ import { createFileViewerZoomController } from '../features/document/zoom.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 { getRendererAvailability, createUnsupportedAvailability } from '../registry/capabilities.js';
 import { buildFileViewerLifecycleContextFromNormalizedSource, buildFileViewerOperationContext, runFileViewerBeforeOperation, runFileViewerLifecycleHook, } from '../lifecycle/operations.js';
-import { collectFileViewerRendererPlugins, createRendererRegistry, installFileViewerRendererPlugins, } from '../registry/registry.js';
+import { collectFileViewerRendererPlugins, createRendererRegistry, getFileViewerAutoRendererPresetVersion, installFileViewerRendererPlugins, listFileViewerAutoRendererPresets, } from '../registry/registry.js';
 import { createFileRenderHandlerLoader, applyFileViewerRenderSurfaceState, createFileViewerRenderSurfaceState, } from '../rendering/handler.js';
 import { createFileViewerCoreRendererRegistry } from '../renderers/index.js';
 import { createFileViewerRequestScope } from '../source/loading.js';
@@ -43,6 +43,16 @@ const createBaseRendererRegistry = (createOptions, options) => {
         builtinRenderers: options.builtinRenderers,
     }).registry;
 };
+const resolveAutoRenderersEnabled = (options) => {
+    const setting = options.autoRenderers;
+    if (typeof setting === 'boolean') {
+        return setting;
+    }
+    if ((setting === null || setting === void 0 ? void 0 : setting.enabled) !== undefined) {
+        return setting.enabled;
+    }
+    return (options.rendererMode || 'extend') !== 'replace';
+};
 const renderMissingRendererState = (container, type) => {
     const documentRef = container.ownerDocument;
     const state = createFileViewerUnsupportedState(type);
@@ -78,6 +88,8 @@ export const createViewer = (container, createOptions = {}) => {
     let installedRendererInput = undefined;
     let installedRendererMode = options.rendererMode || 'extend';
     let installedBuiltinRenderers = options.builtinRenderers || 'all';
+    let installedAutoRenderersEnabled = resolveAutoRenderersEnabled(options);
+    let installedAutoRendererVersion = -1;
     let currentSource = null;
     const renderSurfaceState = createFileViewerRenderSurfaceState();
     const requestScope = createFileViewerRequestScope();
@@ -89,16 +101,31 @@ export const createViewer = (container, createOptions = {}) => {
         const nextMode = options.rendererMode || 'extend';
         const nextRendererInput = options.renderers;
         const nextBuiltinRenderers = options.builtinRenderers || 'all';
+        const nextAutoRenderersEnabled = resolveAutoRenderersEnabled(options);
+        const nextAutoRendererVersion = nextAutoRenderersEnabled
+            ? getFileViewerAutoRendererPresetVersion()
+            : 0;
         if (nextMode === installedRendererMode &&
             nextRendererInput === installedRendererInput &&
-            nextBuiltinRenderers === installedBuiltinRenderers) {
+            nextBuiltinRenderers === installedBuiltinRenderers &&
+            nextAutoRenderersEnabled === installedAutoRenderersEnabled &&
+            nextAutoRendererVersion === installedAutoRendererVersion) {
             return;
         }
         registry = createBaseRendererRegistry(createOptions, options);
         installedRendererMode = nextMode;
         installedRendererInput = nextRendererInput;
         installedBuiltinRenderers = nextBuiltinRenderers;
-        const plugins = collectFileViewerRendererPlugins(nextRendererInput);
+        installedAutoRenderersEnabled = nextAutoRenderersEnabled;
+        installedAutoRendererVersion = nextAutoRendererVersion;
+        const rendererInputs = [];
+        if (nextAutoRenderersEnabled) {
+            rendererInputs.push(...listFileViewerAutoRendererPresets());
+        }
+        if (nextRendererInput) {
+            rendererInputs.push(nextRendererInput);
+        }
+        const plugins = collectFileViewerRendererPlugins(rendererInputs);
         if (!plugins.length) {
             return;
         }

package/dist/viewer/state.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerStateDescriptor, FileViewerStateTheme } from '../contracts/types';
+import type { FileViewerRendererCategory, FileViewerStateDescriptor, FileViewerStateTheme } from '../contracts/types';
 export type FileViewerErrorMessageFormatter = (prefix: string, error: unknown) => string;
 export declare const FILE_VIEWER_PREVIEW_MESSAGES: Readonly<{
     downloading: "正在下载文件资源...";
@@ -7,6 +7,17 @@ export declare const FILE_VIEWER_PREVIEW_MESSAGES: Readonly<{
 }>;
 export declare const DEFAULT_FILE_VIEWER_STATE_THEME: FileViewerStateTheme;
 export declare const DEFAULT_FILE_VIEWER_UNSUPPORTED_DESCRIPTION = "\u652F\u6301 Office\u3001PDF\u3001OFD\u3001Typst\u3001\u538B\u7F29\u5305\u3001\u90AE\u4EF6\u3001OLB/DRA\u3001CAD\u3001\u5730\u7406\u6570\u636E\u30013D \u6A21\u578B\u3001Excalidraw\u3001draw.io\u3001EPUB\u3001UMD\u3001Markdown\u3001\u4EE3\u7801/\u6587\u672C\u3001\u56FE\u7247\u3001\u97F3\u89C6\u9891\u3001\u5B57\u4F53\u548C\u6570\u636E\u8D44\u4EA7\u7684\u5728\u7EBF\u9884\u89C8";
+export interface FileViewerRendererInstallHint {
+    extension: string;
+    rendererId: string;
+    rendererLabel: string;
+    rendererCategory: FileViewerRendererCategory;
+    rendererPackage?: string;
+    presetPackage: string;
+    vitePreset: string;
+    presetLabel: string;
+}
+export declare const resolveFileViewerRendererInstallHint: (extension?: string) => FileViewerRendererInstallHint | null;
 export declare const createFileViewerPreviewLoadingState: (extension?: string, message?: "正在解析文件内容...", theme?: FileViewerStateTheme) => FileViewerStateDescriptor;
 export declare const createFileViewerReadyState: (extension?: string, theme?: FileViewerStateTheme) => FileViewerStateDescriptor;
 export declare const createFileViewerEmptyState: (extension?: string, theme?: FileViewerStateTheme) => FileViewerStateDescriptor;

package/dist/viewer/state.js

@@ -1,4 +1,5 @@
 import { normalizeFileExtension } from '../source/index.js';
+import { DEFAULT_RENDERER_DEFINITIONS } from '../registry/formats.js';
 export const FILE_VIEWER_PREVIEW_MESSAGES = Object.freeze({
     downloading: '正在下载文件资源...',
     streamingPdf: '正在建立 PDF 流式预览...',
@@ -16,6 +17,105 @@ const extensionLabel = (extension) => {
     const normalized = normalizeFileExtension(extension);
     return normalized ? `.${normalized}` : '当前';
 };
+const rendererPackageById = {
+    'office-word-openxml': '@file-viewer/renderer-word',
+    'office-word-binary': '@file-viewer/renderer-word',
+    'office-presentation': '@file-viewer/renderer-presentation',
+    'open-document': '@file-viewer/renderer-word',
+    'spreadsheet-openxml': '@file-viewer/renderer-spreadsheet',
+    pdf: '@file-viewer/renderer-pdf',
+    ofd: '@file-viewer/renderer-ofd',
+    typst: '@file-viewer/renderer-typst',
+    archive: '@file-viewer/renderer-archive',
+    email: '@file-viewer/renderer-email',
+    eda: '@file-viewer/renderer-eda',
+    cad: '@file-viewer/renderer-cad',
+    model: '@file-viewer/renderer-3d',
+    geo: '@file-viewer/renderer-geo',
+    drawing: '@file-viewer/renderer-drawing',
+    mindmap: '@file-viewer/renderer-mindmap',
+    epub: '@file-viewer/renderer-epub',
+    umd: '@file-viewer/renderer-epub',
+    image: '@file-viewer/renderer-image',
+    markdown: '@file-viewer/renderer-text',
+    code: '@file-viewer/renderer-text',
+    video: '@file-viewer/renderer-media',
+    audio: '@file-viewer/renderer-media',
+    'data-asset': '@file-viewer/renderer-data',
+};
+const officeRendererIds = new Set([
+    'office-word-openxml',
+    'office-word-binary',
+    'office-presentation',
+    'open-document',
+    'spreadsheet-openxml',
+    'pdf',
+    'ofd',
+]);
+const liteRendererIds = new Set([
+    'image',
+    'markdown',
+    'code',
+    'video',
+    'audio',
+]);
+const engineeringRendererIds = new Set([
+    'typst',
+    'archive',
+    'eda',
+    'cad',
+    'model',
+    'geo',
+    'drawing',
+    'mindmap',
+    'data-asset',
+]);
+const resolvePresetHint = (definition) => {
+    if (officeRendererIds.has(definition.id)) {
+        return {
+            packageName: '@file-viewer/preset-office',
+            vitePreset: 'office',
+            label: 'Office preset',
+        };
+    }
+    if (engineeringRendererIds.has(definition.id)) {
+        return {
+            packageName: '@file-viewer/preset-engineering',
+            vitePreset: 'engineering',
+            label: 'Engineering preset',
+        };
+    }
+    if (liteRendererIds.has(definition.id)) {
+        return {
+            packageName: '@file-viewer/preset-lite',
+            vitePreset: 'lite',
+            label: 'Lite preset',
+        };
+    }
+    return {
+        packageName: '@file-viewer/preset-all',
+        vitePreset: 'all',
+        label: 'Full preset',
+    };
+};
+export const resolveFileViewerRendererInstallHint = (extension = '') => {
+    const normalized = normalizeFileExtension(extension);
+    const definition = DEFAULT_RENDERER_DEFINITIONS.find(item => item.extensions.map(normalizeFileExtension).includes(normalized));
+    if (!definition) {
+        return null;
+    }
+    const preset = resolvePresetHint(definition);
+    return {
+        extension: normalized,
+        rendererId: definition.id,
+        rendererLabel: definition.label,
+        rendererCategory: definition.category,
+        rendererPackage: rendererPackageById[definition.id],
+        presetPackage: preset.packageName,
+        vitePreset: preset.vitePreset,
+        presetLabel: preset.label,
+    };
+};
 const createFileViewerStateDescriptor = ({ state, extension = '', title, message, description, theme = DEFAULT_FILE_VIEWER_STATE_THEME, recoverable, }) => ({
     state,
     extension: normalizeFileExtension(extension),
@@ -52,6 +152,21 @@ export const createFileViewerEmptyState = (extension = '', theme = DEFAULT_FILE_
 });
 export const createFileViewerUnsupportedState = (extension = '', theme = DEFAULT_FILE_VIEWER_STATE_THEME) => {
     const label = extensionLabel(extension);
+    const installHint = resolveFileViewerRendererInstallHint(extension);
+    if (installHint) {
+        const rendererTip = installHint.rendererPackage
+            ? `；如果需要极致裁剪，也可以只安装 ${installHint.rendererPackage}`
+            : '';
+        return createFileViewerStateDescriptor({
+            state: 'unsupported',
+            extension,
+            title: '需要装配预览能力',
+            message: `${label} 格式已在支持矩阵中，但当前项目尚未装配 ${installHint.rendererLabel} renderer。`,
+            description: `推荐安装 ${installHint.presetPackage} 并启用 @file-viewer/vite-plugin（preset: '${installHint.vitePreset}' 或 preset: 'auto'）${rendererTip}，也可以通过 options.renderers 手动传入对应 renderer。`,
+            theme,
+            recoverable: true,
+        });
+    }
     return createFileViewerStateDescriptor({
         state: 'unsupported',
         extension,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@file-viewer/core",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "private": false,
   "type": "module",
   "description": "Framework-neutral modular TypeScript core for Flyfish File Viewer renderer orchestration, lifecycle APIs, search, zoom, print, and export",