@file-viewer/renderer-pdf 2.1.25 → 2.1.27

package/README.en.md

@@ -25,21 +25,28 @@ const options = {
 
 ## Offline Assets
 
-PDF preview depends on the PDF.js worker, cMaps, WASM helpers, and standard fonts. Asset paths use the same unified options as `@file-viewer/core`:
+PDF preview depends on the PDF.js worker, cMaps, WASM helpers, standard fonts, and an offline fallback for unembedded CJK fonts. Asset paths use the same unified options as `@file-viewer/core`:
 
 ```ts
 const options = {
   renderers: pdfRenderer,
   pdf: {
+    assetBaseUrl: '/workspace/',
     workerUrl: '/vendor/pdf/pdf.worker.mjs',
     cMapUrl: '/vendor/pdf/cmaps/',
     wasmUrl: '/vendor/pdf/wasm/',
     standardFontDataUrl: '/vendor/pdf/standard_fonts/',
+    cjkFontFallbackPath: '/vendor/pdf/fonts/',
+    identityFontRepair: true,
   },
 }
 ```
 
-When no explicit URL is provided, the renderer resolves `vendor/pdf/pdf.worker.mjs` against the current document `baseURI`. Apps deployed under a subpath such as `/workspace/` therefore request `/workspace/vendor/pdf/pdf.worker.mjs` instead of forcing the site root. If the host app did not run `file-viewer-copy-assets`, does not use `@file-viewer/vite-plugin`, or a local dev server falls back to HTML for that path, the renderer lazy-loads the packaged PDF.js worker handler as a compatibility fallback so preview does not fail with `Setting up fake worker failed`. For best performance, full cMap/standard-font support, or strict offline deployments, still copy viewer assets and point these URLs at real static files; `wasmUrl` remains for PDF.js builds that ship WASM assets.
+When no explicit PDF asset URL is configured, the renderer first uses the public base exposed by build tools such as Vite and can fall back to the page entry script. An app deployed under `/workspace/` therefore still requests `/workspace/vendor/pdf/pdf.worker.mjs` while its current SPA route is `/workspace/c/`. UMI, custom proxies, and builds whose public path cannot be detected can set `pdf.assetBaseUrl: '/workspace/'` to pin the base for every PDF offline asset. If the host app did not run `file-viewer-copy-assets`, does not use `@file-viewer/vite-plugin`, or a local dev server falls back to HTML for that path, the renderer lazy-loads the packaged PDF.js worker handler as a compatibility fallback so preview does not fail with `Setting up fake worker failed`. For best performance, complete cMap/standard-font/WASM decoding, or strict offline deployments, still copy viewer assets and point these URLs at real static files. The pinned PDF.js 5.4 stable line loads local JBIG2, JPEG 2000, color-management, and related helpers through `wasmUrl`; viewer assets and the Vite plugin copy them without relying on the public internet.
+
+`cjkFontFallback` is enabled by default. When a PDF references `MicrosoftYaHei-Bold`, SimSun, SimHei, or another CJK font without embedding the font program, the renderer prefers an installed system font and otherwise aliases the original PDF font name to the bundled Noto Sans SC variable font. Only WOFF2 shards needed by the current page text are loaded. The first page waits for the font before rendering, and later pages are redrawn when they introduce new glyphs. Set the option to `false` to disable this behavior, or point `cjkFontFallbackPath` at a self-hosted directory with the same structure.
+
+`identityFontRepair` is also enabled by default for malformed PDFs that write TrueType glyph IDs through `Identity-H`/`Identity-V` but omit `ToUnicode`. The repair module is loaded only after CJK font substitution and multiple control-character glyphs are detected. If the same PDF embeds a usable same-family TrueType font, its cmap is used to rebuild the Unicode mapping for the in-memory preview. The repair is applied only to a preview copy and never overwrites the original file or download source; an unsafe or unsupported repair falls back to the original preview. Set the option to `false` to disable this compatibility path.
 
 ## Migration Note
 

package/README.md

@@ -25,21 +25,28 @@ const options = {
 
 ## 离线资源
 
-PDF 预览依赖 PDF.js worker、cMaps、WASM 和 standard fonts。资源路径沿用 `@file-viewer/core` 的统一 options：
+PDF 预览依赖 PDF.js worker、cMaps、WASM、standard fonts，以及未嵌入中文字体的离线回退资源。资源路径沿用 `@file-viewer/core` 的统一 options：
 
 ```ts
 const options = {
   renderers: pdfRenderer,
   pdf: {
+    assetBaseUrl: '/workspace/',
     workerUrl: '/vendor/pdf/pdf.worker.mjs',
     cMapUrl: '/vendor/pdf/cmaps/',
     wasmUrl: '/vendor/pdf/wasm/',
     standardFontDataUrl: '/vendor/pdf/standard_fonts/',
+    cjkFontFallbackPath: '/vendor/pdf/fonts/',
+    identityFontRepair: true,
   },
 }
 ```
 
-默认未显式配置时，渲染器会基于当前文档 `baseURI` 探测 `vendor/pdf/pdf.worker.mjs`，因此 Vite/UMI 等项目部署在 `/workspace/` 这类子路径时会请求 `/workspace/vendor/pdf/pdf.worker.mjs`，不会强制落到站点根路径。如果客户项目没有执行 `file-viewer-copy-assets`、没有使用 `@file-viewer/vite-plugin`，或者本地临时服务器把该路径回退成 HTML，PDF renderer 会自动懒加载包内 PDF.js worker handler 作为兼容兜底，避免 `Setting up fake worker failed` 直接中断预览。需要最佳性能、完整 cMap/standard fonts 或严格离线部署时，仍建议复制 viewer assets 并配置真实静态地址；`wasmUrl` 保留给提供 WASM 资产的 PDF.js 构建兼容使用。
+默认未显式配置时，渲染器优先使用 Vite 等构建器提供的公开基址，并可从页面入口脚本回退识别部署子路径。因此应用部署在 `/workspace/`、当前 SPA 路由为 `/workspace/c/` 时，仍会请求 `/workspace/vendor/pdf/pdf.worker.mjs`。UMI、自定义代理或无法自动识别的构建环境可以设置 `pdf.assetBaseUrl: '/workspace/'` 固定全部 PDF 离线资源的基址。如果项目没有执行 `file-viewer-copy-assets`、没有使用 `@file-viewer/vite-plugin`，或者本地临时服务器把该路径回退成 HTML，PDF renderer 会自动懒加载包内 PDF.js worker handler 作为兼容兜底，避免 `Setting up fake worker failed` 直接中断预览。需要最佳性能、完整 cMap/standard fonts/WASM 解码或严格离线部署时，仍建议复制 viewer assets 并配置真实静态地址。当前锁定的 PDF.js 5.4 稳定线会通过 `wasmUrl` 本地加载 JBIG2、JPEG 2000、颜色管理等辅助资源；这些资源由 viewer assets 和 Vite 插件统一复制，不依赖公网。
+
+`cjkFontFallback` 默认开启。PDF 引用了 `MicrosoftYaHei-Bold`、宋体、黑体或其他中文字体但没有嵌入字体数据时，渲染器优先使用本机字体；本机缺失时，会把原 PDF 字体名映射到本地 Noto Sans SC 可变字体，并根据当前页实际文字只加载需要的 WOFF2 分片。首屏会在字体就绪后再渲染，后续页发现新字形时会自动重绘。可设为 `false` 完全关闭，或用 `cjkFontFallbackPath` 指向同结构的自托管字体目录。
+
+`identityFontRepair` 也默认开启，用于少数把 TrueType 字形 ID 写入 `Identity-H`/`Identity-V`、却遗漏 `ToUnicode` 的异常 PDF。只有检测到中文字体替换和多个控制字符乱码时，渲染器才会懒加载修复模块；若文件内同时嵌入了可用的同族 TrueType 字体，就从其 cmap 重建内存预览所需的 Unicode 映射。修复只作用于预览副本，不覆盖原始文件和下载源；无法安全修复时继续使用原预览。可设为 `false` 关闭。
 
 ## 迁移说明
 

package/dist/pdf.js

@@ -3,6 +3,7 @@ import { EventBus, GenericL10n, PDFFindController, PDFLinkService, PDFViewer, }
 import { registerFileViewerSearchProvider, registerFileViewerZoomProvider, unregisterFileViewerSearchProvider, unregisterFileViewerZoomProvider, registerFileViewerViewStateProvider, unregisterFileViewerViewStateProvider, createFileViewerZoomChangeEmitter, createFileViewerViewStateChange, createFileViewerViewStateChangeEmitter, createFileViewerTranslator, buildPrintPageStyle, formatCssPixels, DEFAULT_PDF_RANGE_CHUNK_SIZE, resolveFileViewerLocale, resolveFileViewerFitScale, } from '@file-viewer/core';
 import { DEFAULT_FILE_VIEWER_PDF_WORKER_PATH, resolveFileViewerPdfAssetUrls, } from '@file-viewer/core/assets';
 import { pdfViewerStyle } from './pdfStyles.js';
+import { collectMalformedIdentityFontNames, createPdfCjkFontFallbackManager, detectMalformedIdentityCjkFontFamilies, } from './pdfFontFallback.js';
 export const DEFAULT_FILE_VIEWER_PDF_WORKER_URL = DEFAULT_FILE_VIEWER_PDF_WORKER_PATH;
 const MIN_SCALE = 0.2;
 const MAX_SCALE = 3;
@@ -19,6 +20,7 @@ const normalizedPdfViewerStyle = pdfViewerStyle
     .replace(/--page-border-image:\s*url\(images\/shadow\.png\)\s*9 9 repeat;/g, '--page-border-image:none;')
     .replace(/background:\s*url\("\.\/images\/loading-icon\.gif"\)\s*center no-repeat;/g, 'background:none;');
 const pdfJsConsoleErrorSuppressions = new WeakMap();
+const pdfJsConsoleWarningSuppressions = new WeakMap();
 const createStyle = (documentRef) => {
     const style = documentRef.createElement('style');
     style.textContent = `${normalizedPdfViewerStyle}
@@ -164,6 +166,63 @@ const suppressPdfJsDestroyedTransportPageInitErrors = (view) => {
         }, PDF_JS_DESTROY_CONSOLE_SUPPRESSION_MS);
     };
 };
+const isPdfJsMissingSystemFontWarning = (args) => {
+    const [message] = args;
+    return typeof message === 'string' &&
+        /^(?:Warning:\s*)?Cannot load system font: .+installing it could help to improve PDF rendering\.$/.test(message);
+};
+const suppressPdfJsMissingSystemFontWarnings = (view) => {
+    const consoleRef = (view.console ||
+        globalThis.console);
+    if (!consoleRef || typeof consoleRef.warn !== 'function') {
+        return () => { };
+    }
+    let suppression = pdfJsConsoleWarningSuppressions.get(consoleRef);
+    if (!suppression) {
+        const originalWarn = consoleRef.warn;
+        suppression = {
+            originalWarn,
+            patchedWarn: (...args) => {
+                if (isPdfJsMissingSystemFontWarning(args)) {
+                    return;
+                }
+                return originalWarn.apply(consoleRef, args);
+            },
+            depth: 0,
+            restoreTimer: undefined,
+        };
+        pdfJsConsoleWarningSuppressions.set(consoleRef, suppression);
+        consoleRef.warn = suppression.patchedWarn;
+    }
+    else if (suppression.restoreTimer !== undefined) {
+        view.clearTimeout(suppression.restoreTimer);
+        suppression.restoreTimer = undefined;
+    }
+    suppression.depth += 1;
+    let released = false;
+    return () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        const current = pdfJsConsoleWarningSuppressions.get(consoleRef);
+        if (!current) {
+            return;
+        }
+        current.depth = Math.max(0, current.depth - 1);
+        if (current.depth || current.restoreTimer !== undefined) {
+            return;
+        }
+        current.restoreTimer = view.setTimeout(() => {
+            current.restoreTimer = undefined;
+            if (current.depth || consoleRef.warn !== current.patchedWarn) {
+                return;
+            }
+            consoleRef.warn = current.originalWarn;
+            pdfJsConsoleWarningSuppressions.delete(consoleRef);
+        }, PDF_JS_DESTROY_CONSOLE_SUPPRESSION_MS);
+    };
+};
 const isConfiguredUrl = (value) => {
     return value !== undefined && value !== null && String(value).trim().length > 0;
 };
@@ -195,6 +254,50 @@ const installBundledPdfFakeWorker = async () => {
 const resolvePdfWorkerUrl = (options, documentBaseUrl) => {
     return resolveFileViewerPdfAssetUrls(options, documentBaseUrl).workerUrl;
 };
+const readBundlerPublicBaseUrl = () => {
+    var _a;
+    try {
+        const value = (_a = import.meta.env) === null || _a === void 0 ? void 0 : _a.BASE_URL;
+        return typeof value === 'string' ? value.trim() : '';
+    }
+    catch {
+        return '';
+    }
+};
+const resolvePdfRuntimeAssetBaseUrl = (documentRef) => {
+    const documentBaseUrl = documentRef.baseURI || documentRef.URL || 'file:///';
+    const bundlerBaseUrl = readBundlerPublicBaseUrl();
+    if (bundlerBaseUrl && bundlerBaseUrl !== '.' && bundlerBaseUrl !== './') {
+        try {
+            return new URL(bundlerBaseUrl.endsWith('/') ? bundlerBaseUrl : `${bundlerBaseUrl}/`, documentBaseUrl).href;
+        }
+        catch {
+            // Continue with DOM-based public-path detection.
+        }
+    }
+    // An explicit <base> is authoritative and already reflected by baseURI.
+    if (documentRef.querySelector('base[href]')) {
+        return documentBaseUrl;
+    }
+    // Entry scripts remain under the public deployment base when an SPA route
+    // changes document.baseURI. This covers Vite and common UMI/Webpack layouts.
+    for (const script of Array.from(documentRef.querySelectorAll('script[src]'))) {
+        try {
+            const scriptUrl = new URL(script.src || script.getAttribute('src') || '', documentBaseUrl);
+            const assetDirectory = scriptUrl.pathname.match(/^(.*\/)(?:assets|static)\/[^/]+$/i);
+            if (assetDirectory) {
+                return new URL(assetDirectory[1], scriptUrl.origin).href;
+            }
+            if (/\/(?:umi|main|index)(?:[.-][^/]*)?\.(?:m?js)$/i.test(scriptUrl.pathname)) {
+                return new URL('./', scriptUrl).href;
+            }
+        }
+        catch {
+            // Ignore unrelated or malformed script URLs.
+        }
+    }
+    return documentBaseUrl;
+};
 const buildOutlineItems = (items, prefix = 'outline', getFallbackTitle = index => `Outline ${index + 1}`) => items.map((item, index) => {
     const id = `${prefix}-${index}`;
     const children = Array.isArray(item.items)
@@ -209,7 +312,7 @@ const buildOutlineItems = (items, prefix = 'outline', getFallbackTitle = index =
     };
 });
 export default async function renderPdf(buffer, target, context) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     const documentRef = target.ownerDocument || document;
     const targetWindow = documentRef.defaultView || (typeof window !== 'undefined' ? window : null);
     const t = createFileViewerTranslator(context === null || context === void 0 ? void 0 : context.options);
@@ -218,6 +321,10 @@ export default async function renderPdf(buffer, target, context) {
         throw new Error(t('pdf.error.browserWindow'));
     }
     const options = (_a = context === null || context === void 0 ? void 0 : context.options) === null || _a === void 0 ? void 0 : _a.pdf;
+    const pdfRuntimeAssetBaseUrl = resolvePdfRuntimeAssetBaseUrl(documentRef);
+    const cjkFontFallbackEnabled = (options === null || options === void 0 ? void 0 : options.cjkFontFallback) !== false;
+    const identityFontRepairEnabled = (options === null || options === void 0 ? void 0 : options.identityFontRepair) !== false;
+    const fontInspectionEnabled = cjkFontFallbackEnabled || identityFontRepairEnabled;
     const initialViewState = (options === null || options === void 0 ? void 0 : options.initialViewState) || ((_b = context === null || context === void 0 ? void 0 : context.options) === null || _b === void 0 ? void 0 : _b.initialViewState) || null;
     const navigationEnabled = (options === null || options === void 0 ? void 0 : options.navigation) !== false;
     const toolbarVisible = (options === null || options === void 0 ? void 0 : options.toolbar) !== false;
@@ -260,6 +367,10 @@ export default async function renderPdf(buffer, target, context) {
     let pdfSearchWaiters = [];
     const pdfThumbnails = new Map();
     const pendingPdfThumbnails = new Set();
+    const pdfCjkFontFallbackPageLoads = new Map();
+    const pdfCjkFontFallbackRenderHandledPages = new Set();
+    let pdfCjkFontFallbackManager = null;
+    let restorePdfJsMissingSystemFontWarnings = () => { };
     const pdfContext = {
         viewer: null,
         linkService: null,
@@ -269,6 +380,17 @@ export default async function renderPdf(buffer, target, context) {
         document: null,
         search: '',
     };
+    const ensurePdfPageCjkFontFallback = (pageNumber, page) => {
+        if (!pdfCjkFontFallbackManager) {
+            return Promise.resolve(false);
+        }
+        let pending = pdfCjkFontFallbackPageLoads.get(pageNumber);
+        if (!pending) {
+            pending = pdfCjkFontFallbackManager.ensurePage(page);
+            pdfCjkFontFallbackPageLoads.set(pageNumber, pending);
+        }
+        return pending;
+    };
     const root = createElement(documentRef, 'div', 'pdf-shell');
     root.dataset.viewerSearchProvider = 'pdf';
     root.dataset.viewerZoomProvider = 'pdf';
@@ -426,6 +548,7 @@ export default async function renderPdf(buffer, target, context) {
             if (destroyed || pdfContext.document !== pdfDocument) {
                 return;
             }
+            await ensurePdfPageCjkFontFallback(pageNumber, page);
             const baseViewport = page.getViewport({
                 scale: PixelsPerInch.PDF_TO_CSS_UNITS,
                 rotation: currentRotation,
@@ -444,7 +567,7 @@ export default async function renderPdf(buffer, target, context) {
             }
             canvas.width = Math.max(1, Math.ceil(renderViewport.width));
             canvas.height = Math.max(1, Math.ceil(renderViewport.height));
-            await page.render({ canvasContext, viewport: renderViewport }).promise;
+            await page.render({ canvas, canvasContext, viewport: renderViewport }).promise;
             if (destroyed || pdfContext.document !== pdfDocument) {
                 return;
             }
@@ -463,6 +586,64 @@ export default async function renderPdf(buffer, target, context) {
             pendingPdfThumbnails.delete(pageNumber);
         }
     };
+    const renderFirstPageThumbnail = async (captureOptions) => {
+        var _a, _b, _c, _d, _e, _f;
+        const pdfDocument = pdfContext.document;
+        if (!pdfDocument) {
+            return null;
+        }
+        if ((_a = captureOptions.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+            throw captureOptions.signal.reason;
+        }
+        const page = await pdfDocument.getPage(1);
+        await ensurePdfPageCjkFontFallback(1, page);
+        const baseViewport = page.getViewport({ scale: 1, rotation: currentRotation });
+        const scale = Math.max(0.1, Math.min(captureOptions.width / Math.max(baseViewport.width, 1), captureOptions.height / Math.max(baseViewport.height, 1)));
+        const viewport = page.getViewport({ scale, rotation: currentRotation });
+        const canvas = documentRef.createElement('canvas');
+        const canvasContext = canvas.getContext('2d');
+        if (!canvasContext) {
+            return null;
+        }
+        canvas.width = Math.max(1, Math.ceil(viewport.width));
+        canvas.height = Math.max(1, Math.ceil(viewport.height));
+        const renderTask = page.render({ canvas, canvasContext, viewport });
+        const cancelRender = () => renderTask.cancel();
+        (_b = captureOptions.signal) === null || _b === void 0 ? void 0 : _b.addEventListener('abort', cancelRender, { once: true });
+        try {
+            await renderTask.promise;
+            if ((_c = captureOptions.signal) === null || _c === void 0 ? void 0 : _c.aborted) {
+                throw captureOptions.signal.reason;
+            }
+            return await new Promise(resolve => canvas.toBlob(resolve, 'image/png'));
+        }
+        catch (error) {
+            if ((_d = captureOptions.signal) === null || _d === void 0 ? void 0 : _d.aborted) {
+                throw captureOptions.signal.reason;
+            }
+            throw error;
+        }
+        finally {
+            (_e = captureOptions.signal) === null || _e === void 0 ? void 0 : _e.removeEventListener('abort', cancelRender);
+            canvas.width = 0;
+            canvas.height = 0;
+            (_f = page.cleanup) === null || _f === void 0 ? void 0 : _f.call(page);
+        }
+    };
+    (_d = context === null || context === void 0 ? void 0 : context.registerThumbnailAdapter) === null || _d === void 0 ? void 0 : _d.call(context, {
+        beforeCapture: async ({ signal }) => {
+            while (loadStatus === 'loading' && !destroyed) {
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                    throw signal.reason;
+                }
+                await new Promise(resolve => targetWindow.setTimeout(resolve, 16));
+            }
+            if (loadStatus === 'error') {
+                throw new Error(errorMessage || t('pdf.error.loadFailed'));
+            }
+        },
+        capture: renderFirstPageThumbnail,
+    });
     const ensureThumbnailObserver = () => {
         if (!thumbnailsEnabled || thumbnailObserver || typeof targetWindow.IntersectionObserver !== 'function') {
             return;
@@ -597,7 +778,7 @@ export default async function renderPdf(buffer, target, context) {
         }
     };
     const createPdfWorker = async () => {
-        const workerUrl = resolvePdfWorkerUrl(options, documentRef.baseURI || documentRef.URL || undefined);
+        const workerUrl = resolvePdfWorkerUrl(options, pdfRuntimeAssetBaseUrl);
         const hasExplicitWorkerUrl = isConfiguredUrl(options === null || options === void 0 ? void 0 : options.workerUrl);
         const shouldUseRealWorker = !!(targetWindow === null || targetWindow === void 0 ? void 0 : targetWindow.Worker) &&
             (hasExplicitWorkerUrl || await canUseResolvedPdfWorkerUrl(workerUrl));
@@ -1195,6 +1376,7 @@ export default async function renderPdf(buffer, target, context) {
                 throw new Error(t('pdf.error.unloaded'));
             }
             const page = await pdfDocument.getPage(pageNumber);
+            await ensurePdfPageCjkFontFallback(pageNumber, page);
             const baseViewport = page.getViewport({
                 scale: PixelsPerInch.PDF_TO_CSS_UNITS,
                 rotation: currentRotation,
@@ -1213,7 +1395,7 @@ export default async function renderPdf(buffer, target, context) {
             }
             canvas.width = Math.ceil(renderViewport.width);
             canvas.height = Math.ceil(renderViewport.height);
-            await page.render({ canvasContext, viewport: renderViewport }).promise;
+            await page.render({ canvas, canvasContext, viewport: renderViewport }).promise;
             const pageTitle = t('pdf.export.pageTitle', { title: exportOptions.title, page: pageNumber });
             const pageStyle = [
                 `--viewer-print-page-width:${formatCssPixels(pageWidth)}`,
@@ -1229,8 +1411,13 @@ export default async function renderPdf(buffer, target, context) {
         return `<div class="pdf-export-document">${pagesHtml.join('')}</div>`;
     };
     const loadFile = async () => {
-        var _a, _b;
+        var _a, _b, _c;
         const requestVersion = ++loadVersion;
+        restorePdfJsMissingSystemFontWarnings();
+        restorePdfJsMissingSystemFontWarnings = () => { };
+        pdfCjkFontFallbackManager = null;
+        pdfCjkFontFallbackPageLoads.clear();
+        pdfCjkFontFallbackRenderHandledPages.clear();
         loadStatus = 'loading';
         errorMessage = '';
         pdfContext.document = null;
@@ -1258,6 +1445,7 @@ export default async function renderPdf(buffer, target, context) {
                 linkService: pdfLinkService,
                 findController: pdfFindController,
                 l10n: new GenericL10n(resolvedLocale),
+                enableAutoLinking: false,
             });
             pdfContext.viewer = pdfViewer;
             pdfContext.linkService = pdfLinkService;
@@ -1314,12 +1502,46 @@ export default async function renderPdf(buffer, target, context) {
                     emitViewStateChange('zoom-change', 'viewer');
                 }
             });
-            eventBus.on('pagerendered', scheduleLegacyPageDimensionPatch);
+            eventBus.on('pagerendered', ({ pageNumber }) => {
+                scheduleLegacyPageDimensionPatch();
+                if (!pdfCjkFontFallbackManager ||
+                    pdfCjkFontFallbackRenderHandledPages.has(pageNumber)) {
+                    return;
+                }
+                pdfCjkFontFallbackRenderHandledPages.add(pageNumber);
+                const pdfDocument = pdfContext.document;
+                const alreadyPrepared = pdfCjkFontFallbackPageLoads.has(pageNumber);
+                if (!pdfDocument || alreadyPrepared) {
+                    return;
+                }
+                void pdfDocument.getPage(pageNumber)
+                    .then(page => ensurePdfPageCjkFontFallback(pageNumber, page))
+                    .then(fontLoaded => {
+                    var _a;
+                    if (fontLoaded &&
+                        !destroyed &&
+                        pdfContext.document === pdfDocument) {
+                        (_a = pdfContext.viewer) === null || _a === void 0 ? void 0 : _a.refresh();
+                    }
+                })
+                    .catch(error => {
+                    console.warn('[file-viewer] Unable to inspect a PDF page for CJK font fallback.', error);
+                });
+            });
             if (!(context === null || context === void 0 ? void 0 : context.streamUrl) && !buffer.byteLength) {
                 throw new Error(t('pdf.error.missingSource'));
             }
-            const worker = await createPdfWorker();
-            const pdfAssets = resolveFileViewerPdfAssetUrls(options, documentRef.baseURI || documentRef.URL);
+            const pdfAssets = resolveFileViewerPdfAssetUrls(options, pdfRuntimeAssetBaseUrl);
+            if (cjkFontFallbackEnabled) {
+                pdfCjkFontFallbackManager = createPdfCjkFontFallbackManager({
+                    documentRef,
+                    fontAssetPath: pdfAssets.cjkFontFallbackPath,
+                    onWarning: (message, error) => {
+                        console.warn(`[file-viewer] ${message}`, error || '');
+                    },
+                });
+                restorePdfJsMissingSystemFontWarnings = suppressPdfJsMissingSystemFontWarnings(targetWindow);
+            }
             const source = (context === null || context === void 0 ? void 0 : context.streamUrl)
                 ? {
                     url: context.streamUrl,
@@ -1329,18 +1551,24 @@ export default async function renderPdf(buffer, target, context) {
                 : {
                     data: buffer,
                 };
-            const loadingTask = getDocument({
-                ...source,
-                worker: worker || undefined,
-                cMapUrl: pdfAssets.cMapUrl,
-                standardFontDataUrl: pdfAssets.standardFontDataUrl,
-                useWorkerFetch: true,
-                cMapPacked: true,
-                enableXfa: true,
-            });
-            resource = { loadingTask, worker };
+            const createLoadingResource = async (loadingSource) => {
+                const worker = await createPdfWorker();
+                const loadingTask = getDocument({
+                    ...loadingSource,
+                    worker: worker || undefined,
+                    cMapUrl: pdfAssets.cMapUrl,
+                    wasmUrl: pdfAssets.wasmUrl,
+                    standardFontDataUrl: pdfAssets.standardFontDataUrl,
+                    useWorkerFetch: true,
+                    cMapPacked: true,
+                    enableXfa: true,
+                    fontExtraProperties: fontInspectionEnabled,
+                });
+                return { loadingTask, worker };
+            };
+            resource = await createLoadingResource(source);
             pdfContext.resource = resource;
-            const pdfDocument = await loadingTask.promise;
+            let pdfDocument = await resource.loadingTask.promise;
             if (destroyed || requestVersion !== loadVersion || pdfContext.resource !== resource) {
                 if (pdfContext.resource === resource) {
                     pdfContext.resource = null;
@@ -1348,10 +1576,86 @@ export default async function renderPdf(buffer, target, context) {
                 }
                 return;
             }
+            let firstPageTextContent = null;
+            let firstPageForInspection = null;
+            if (fontInspectionEnabled && pdfDocument.numPages > 0) {
+                const firstPage = await pdfDocument.getPage(1);
+                firstPageForInspection = firstPage;
+                firstPageTextContent = await firstPageForInspection.getTextContent();
+            }
+            if (identityFontRepairEnabled && firstPageTextContent) {
+                const malformedFontNames = collectMalformedIdentityFontNames(firstPageTextContent);
+                if (malformedFontNames.length && firstPageForInspection) {
+                    await firstPageForInspection.getOperatorList();
+                }
+                const malformedFontFamilies = new Map();
+                for (const fontName of malformedFontNames) {
+                    try {
+                        const family = (_b = firstPageForInspection === null || firstPageForInspection === void 0 ? void 0 : firstPageForInspection.commonObjs.get(fontName)) === null || _b === void 0 ? void 0 : _b.name;
+                        if (family) {
+                            malformedFontFamilies.set(fontName, family);
+                        }
+                    }
+                    catch {
+                        // A font object that is still unresolved cannot be repaired safely.
+                    }
+                }
+                const candidateFamilies = detectMalformedIdentityCjkFontFamilies(firstPageTextContent, fontName => malformedFontFamilies.get(fontName) || '');
+                if (candidateFamilies.length) {
+                    let replacementResource = null;
+                    try {
+                        const sourceBytes = await pdfDocument.getData();
+                        const { repairMalformedIdentityCjkFonts } = await import('./pdfIdentityFontRepair.js');
+                        const repaired = await repairMalformedIdentityCjkFonts(sourceBytes, candidateFamilies);
+                        if (repaired.repairedFonts > 0) {
+                            const previousResource = resource;
+                            replacementResource = await createLoadingResource({ data: repaired.bytes });
+                            const replacementDocument = await replacementResource.loadingTask.promise;
+                            const repairedFirstPage = await replacementDocument.getPage(1);
+                            const replacementTextContent = await repairedFirstPage.getTextContent();
+                            if (destroyed ||
+                                requestVersion !== loadVersion ||
+                                pdfContext.resource !== previousResource) {
+                                await destroyPdfResource(replacementResource);
+                                return;
+                            }
+                            resource = replacementResource;
+                            replacementResource = null;
+                            pdfContext.resource = resource;
+                            pdfDocument = replacementDocument;
+                            firstPageTextContent = replacementTextContent;
+                            await destroyPdfResource(previousResource);
+                            console.info(`[file-viewer] Repaired ${repaired.repairedFonts} malformed PDF Identity CJK font mapping(s).`);
+                        }
+                    }
+                    catch (error) {
+                        if (replacementResource) {
+                            await destroyPdfResource(replacementResource);
+                        }
+                        console.warn('[file-viewer] Unable to repair a malformed PDF Identity CJK font; continuing with the original preview.', error);
+                    }
+                }
+            }
+            if (destroyed || requestVersion !== loadVersion || pdfContext.resource !== resource) {
+                return;
+            }
             pageCount = pdfDocument.numPages;
             currentPage = 1;
             pdfContext.document = pdfDocument;
-            (_b = context === null || context === void 0 ? void 0 : context.registerExportAdapter) === null || _b === void 0 ? void 0 : _b.call(context, {
+            if (pdfCjkFontFallbackManager && pageCount > 0) {
+                if (firstPageTextContent) {
+                    pdfCjkFontFallbackPageLoads.set(1, pdfCjkFontFallbackManager.ensureTextContent(firstPageTextContent));
+                    await pdfCjkFontFallbackPageLoads.get(1);
+                }
+                else {
+                    const firstPage = await pdfDocument.getPage(1);
+                    await ensurePdfPageCjkFontFallback(1, firstPage);
+                }
+                if (destroyed || requestVersion !== loadVersion || pdfContext.document !== pdfDocument) {
+                    return;
+                }
+            }
+            (_c = context === null || context === void 0 ? void 0 : context.registerExportAdapter) === null || _c === void 0 ? void 0 : _c.call(context, {
                 includeDocumentStyles: false,
                 printStyle: buildPdfPrintStyle,
                 toHtml: renderPdfPagesForExport,
@@ -1433,9 +1737,14 @@ export default async function renderPdf(buffer, target, context) {
     return {
         $el: root,
         unmount() {
-            var _a;
+            var _a, _b;
             destroyed = true;
             loadVersion += 1;
+            restorePdfJsMissingSystemFontWarnings();
+            restorePdfJsMissingSystemFontWarnings = () => { };
+            pdfCjkFontFallbackManager = null;
+            pdfCjkFontFallbackPageLoads.clear();
+            pdfCjkFontFallbackRenderHandledPages.clear();
             targetWindow.cancelAnimationFrame(fitFrame);
             targetWindow.cancelAnimationFrame(pageDimensionFrame);
             targetWindow.cancelAnimationFrame(scrollStateFrame);
@@ -1449,6 +1758,7 @@ export default async function renderPdf(buffer, target, context) {
             unregisterFileViewerViewStateProvider(root);
             outlineItems = [];
             (_a = context === null || context === void 0 ? void 0 : context.registerExportAdapter) === null || _a === void 0 ? void 0 : _a.call(context, null);
+            (_b = context === null || context === void 0 ? void 0 : context.registerThumbnailAdapter) === null || _b === void 0 ? void 0 : _b.call(context, null);
             const resource = pdfContext.resource;
             pdfContext.viewer = null;
             pdfContext.linkService = null;

package/dist/pdfFontFallback.d.ts

@@ -0,0 +1,33 @@
+type PdfTextContentItem = {
+    str?: string;
+    fontName?: string;
+};
+type PdfTextContentStyle = {
+    fontSubstitution?: string;
+};
+export type PdfTextContent = {
+    items?: PdfTextContentItem[];
+    styles?: Record<string, PdfTextContentStyle>;
+};
+export type PdfTextContentPage = {
+    getTextContent: () => Promise<PdfTextContent>;
+};
+export interface PdfCjkFontFallbackManager {
+    prepare: () => Promise<boolean>;
+    ensureTextContent: (textContent: PdfTextContent) => Promise<boolean>;
+    ensurePage: (page: PdfTextContentPage) => Promise<boolean>;
+}
+export interface CreatePdfCjkFontFallbackManagerOptions {
+    documentRef: Document;
+    fontAssetPath: string;
+    onWarning?: (message: string, error?: unknown) => void;
+}
+/**
+ * Some PDF generators write TrueType glyph IDs through Identity-H but omit
+ * ToUnicode. PDF.js then exposes those glyph IDs as control characters, so a
+ * replacement font alone cannot recover the intended text.
+ */
+export declare const detectMalformedIdentityCjkFontFamilies: (textContent: PdfTextContent, resolveFontFamily?: (fontName: string) => string) => string[];
+export declare const collectMalformedIdentityFontNames: (textContent: PdfTextContent) => string[];
+export declare const createPdfCjkFontFallbackManager: ({ documentRef, fontAssetPath, onWarning, }: CreatePdfCjkFontFallbackManagerOptions) => PdfCjkFontFallbackManager;
+export {};