@file-viewer/core 2.2.4 → 2.2.6

package/README.en.md

@@ -14,6 +14,23 @@ Current framework-neutral browser renderers still inside core are limited to the
 npm install @file-viewer/core
 ```
 
+## Preflight Before Rendering
+
+`precheckFileViewerSource()` does not create a viewer or load a heavy renderer. It checks whether the extension is available and validates known PDF, OpenXML / OpenDocument, legacy OLE Office, and RTF signatures or package parts. `valid: null` explicitly means capability-only detection, not a full parse; the real renderer remains the final authority for malformed content.
+
+```ts
+import { precheckFileViewerSource } from '@file-viewer/core/headless'
+
+const result = await precheckFileViewerSource(file, {
+  // Restrict this to the extensions actually installed by this product.
+  supportedExtensions: ['pdf', 'docx', 'xlsx', 'pptx']
+})
+
+if (!result.previewable) {
+  console.warn(result.reason, result.missingParts)
+}
+```
+
 ## Entry points
 
 Use `@file-viewer/core/headless` when a component package, server-side helper, or build script only needs framework-neutral contracts: format support, source normalization, renderer capability metadata, lifecycle/operation context, option normalization, state helpers, and static asset resolution. This entry intentionally does not expose the DOM viewer engine or browser renderers.

package/README.md

@@ -14,6 +14,23 @@ Current framework-neutral browser renderers still inside core are limited to the
 npm install @file-viewer/core
 ```
 
+## 渲染前预检
+
+`precheckFileViewerSource()` 不会创建 viewer，也不会加载重型 renderer。它先检查当前扩展名是否在能力范围内，并对 PDF、OpenXML / OpenDocument、旧版 OLE Office、RTF 等格式执行签名或包结构检查。`valid: null` 明确表示该格式只有能力检查、没有做完整解析；真实 renderer 仍是畸形文件的最终判断者。
+
+```ts
+import { precheckFileViewerSource } from '@file-viewer/core/headless'
+
+const result = await precheckFileViewerSource(file, {
+  // 可传当前产品实际安装的扩展名列表，避免把未装 preset 的格式报成可预览
+  supportedExtensions: ['pdf', 'docx', 'xlsx', 'pptx']
+})
+
+if (!result.previewable) {
+  console.warn(result.reason, result.missingParts)
+}
+```
+
 ## Entry points
 
 Use `@file-viewer/core/headless` when a component package, server-side helper or build script only needs framework-neutral contracts: format support, source normalization, renderer capability metadata, lifecycle/operation context, option normalization, state helpers and static asset resolution. This entry intentionally does not expose the DOM viewer engine or browser renderers.

package/dist/contracts/types.d.ts

@@ -3,7 +3,7 @@ export type FileViewerThemeMode = 'light' | 'dark' | 'system';
 export type FileViewerResolvedThemeMode = Exclude<FileViewerThemeMode, 'system'>;
 export type FileViewerLocale = 'auto' | 'zh-CN' | 'en-US' | 'ja-JP' | (string & {});
 export type FileViewerStyleIsolation = 'auto' | 'shadow' | 'scoped' | 'none';
-export type FileViewerMessageKey = 'toolbar.zoomGroup' | 'toolbar.zoomOut' | 'toolbar.zoomIn' | 'toolbar.zoomReset' | 'toolbar.download' | 'toolbar.downloadTitle' | 'toolbar.print' | 'toolbar.printTitle' | 'toolbar.printDirect' | 'toolbar.printMask' | 'toolbar.printMaskTitle' | 'toolbar.printMaskAdd' | 'toolbar.printMaskClear' | 'toolbar.printMaskCancel' | 'toolbar.printMaskConfirm' | 'toolbar.printMaskHint' | 'toolbar.exportHtml' | 'toolbar.exportHtmlTitle' | 'toolbar.search' | 'toolbar.searchPlaceholder' | 'toolbar.searchPrevious' | 'toolbar.searchNext' | 'toolbar.searchClear' | 'toolbar.theme' | 'toolbar.themeToLight' | 'toolbar.themeToDark' | 'state.ready.title' | 'state.ready.message' | 'state.empty.title' | 'state.empty.message' | 'state.unsupported.install.title' | 'state.unsupported.install.message' | 'state.unsupported.install.description' | 'state.unsupported.title' | 'state.unsupported.message' | 'state.unsupported.description' | 'state.error.title' | 'preview.downloading' | 'preview.streamingPdf' | 'preview.reading' | 'error.download' | 'error.print' | 'error.exportHtml' | 'error.noDownloadSource' | 'error.noExportContent' | 'error.printUnavailable' | 'error.printWindowBlocked' | 'error.remoteDownload' | 'error.localRead' | 'error.load' | 'error.stream' | 'error.beforeOperation' | 'error.unknown' | 'error.blobUnavailable' | 'error.sourceUnsupported' | 'error.fileReadArrayBuffer' | 'error.fileReadDataUrl' | 'error.fileReadText' | 'error.imageDataUrlRead' | 'operation.download' | 'operation.print' | 'operation.exportHtml' | 'operation.zoomIn' | 'operation.zoomOut' | 'operation.zoomReset' | 'pdf.toolbar.toggleNavigation' | 'pdf.toolbar.previousPage' | 'pdf.toolbar.nextPage' | 'pdf.toolbar.fitWidth' | 'pdf.toolbar.zoomOut' | 'pdf.toolbar.zoomIn' | 'pdf.toolbar.rotateLeft' | 'pdf.toolbar.rotateRight' | 'pdf.nav.typeLabel' | 'pdf.nav.pagesTab' | 'pdf.nav.outlineTab' | 'pdf.nav.pagesTitle' | 'pdf.nav.outlineTitle' | 'pdf.nav.pageCount' | 'pdf.nav.itemCount' | 'pdf.nav.pageLabel' | 'pdf.nav.outlineEmpty' | 'pdf.nav.outlineFallbackTitle' | 'pdf.thumbnail.alt' | 'pdf.state.loading' | 'pdf.error.browserWindow' | 'pdf.error.missingSource' | 'pdf.error.loadFailed' | 'pdf.error.notLoaded' | 'pdf.error.unloaded' | 'pdf.error.canvasUnavailable' | 'pdf.export.pageTitle' | 'spreadsheet.loading.kicker' | 'spreadsheet.loading.title' | 'spreadsheet.loading.hint' | 'spreadsheet.loading.streaming' | 'spreadsheet.tabs.ariaLabel' | 'spreadsheet.state.parsingWorkbook' | 'spreadsheet.state.preparingSheet' | 'spreadsheet.state.preparingSheetNamed' | 'spreadsheet.state.cachedRows' | 'spreadsheet.state.rows' | 'spreadsheet.state.rowsAndColumns' | 'spreadsheet.error.parseFailed' | 'spreadsheet.error.workerFailed' | 'word.error.invalidDocx' | 'word.error.missingOdfContent' | 'word.error.odfXmlParseFailed' | 'word.title.rtf' | 'word.title.openDocumentPresentation' | 'word.title.openDocumentText' | 'word.page.fallback' | 'word.page.empty' | 'word.body' | 'word.body.empty' | 'ofd.state.loading' | 'ofd.error.empty' | 'ofd.error.parseFailed' | 'presentation.state.loading' | 'presentation.error.title' | 'presentation.error.parseFailed' | 'presentation.ppt.state.loading' | 'presentation.ppt.error.title' | 'presentation.ppt.error.parseFailed' | 'presentation.ppt.error.assetHint' | 'archive.error.nestedUnsupported' | 'archive.loading.readingDirectory' | 'archive.loading.readingDirectoryHint' | 'archive.search.placeholder' | 'archive.sidebar.hide' | 'archive.sidebar.show' | 'archive.preview.title' | 'archive.preview.chooseFile' | 'archive.preview.downloadFile' | 'archive.error.title' | 'archive.stats.summary' | 'archive.warning.encrypted' | 'archive.password.title' | 'archive.password.description' | 'archive.password.placeholder' | 'archive.password.invalid' | 'archive.password.required' | 'archive.password.cancel' | 'archive.password.confirm' | 'archive.error.passwordRequired' | 'archive.error.encryptedRequiresWorker' | 'archive.empty.title' | 'archive.empty.message' | 'archive.loading.initializingCandidate' | 'archive.loading.initializingCandidateHint' | 'archive.error.candidateInitTimeout' | 'archive.error.encryptedCheckTimeout' | 'archive.loading.directoryReadyHint' | 'archive.error.candidateReadTimeout' | 'archive.loading.workerFallback' | 'archive.loading.workerFallbackHint' | 'archive.notice.workerFallback' | 'archive.error.tooLarge' | 'archive.loading.initializingWorker' | 'archive.loading.initializingWorkerHint' | 'archive.error.workerInitFailed' | 'archive.error.workerUnsupported' | 'archive.error.indexedDbUnavailable' | 'archive.error.entryTooLarge' | 'archive.loading.extracting' | 'archive.loading.rendering' | 'archive.loading.exporting' | 'media.audio.title' | 'media.audio.description' | 'media.audio.unsupported' | 'media.video.title' | 'media.video.unsupported' | 'media.video.hlsHint' | 'media.midi.title' | 'media.midi.loading' | 'media.midi.trackHeader' | 'media.midi.instrumentHeader' | 'media.midi.channelHeader' | 'media.midi.noteCountHeader' | 'media.midi.durationHeader' | 'media.midi.durationStat' | 'media.midi.trackStat' | 'media.midi.noteStat' | 'media.midi.parseFailed' | 'email.mbox.subject' | 'email.mbox.summary' | 'email.error.title' | 'email.meta.from' | 'email.meta.to' | 'email.meta.cc' | 'email.meta.date' | 'email.tabs.text' | 'email.tabs.headers' | 'email.attachments.title' | 'email.attachments.empty' | 'email.attachments.download' | 'email.attachments.opening' | 'email.attachments.nestedUnavailable' | 'email.loading.parsing' | 'data.font.sample' | 'data.error.fontFaceUnsupported' | 'data.title.font' | 'data.title.sqlite' | 'data.title.parquet' | 'data.title.avro' | 'data.title.wasm' | 'data.title.eps' | 'data.title.ai' | 'data.title.webarchive' | 'data.title.summary' | 'data.label.format' | 'data.label.size' | 'data.label.rendering' | 'data.label.objects' | 'data.label.sampleTable' | 'data.label.rows' | 'data.label.columns' | 'data.label.sampleRows' | 'data.label.imports' | 'data.label.exports' | 'data.label.magic' | 'data.label.note' | 'data.label.container' | 'data.value.schemaRead' | 'data.value.schemaUnread' | 'data.note.aiSummary' | 'data.note.postscriptSummary' | 'data.note.webarchive' | 'data.image.alt' | 'psd.title' | 'psd.action.fit' | 'psd.action.showAll' | 'psd.action.hideAll' | 'psd.layers.title' | 'psd.layers.redrawable' | 'psd.layers.empty' | 'psd.layers.hidden' | 'drawing.error.viewerLoadFailed' | 'drawing.error.excalidrawEmpty' | 'drawing.error.excalidrawTimeout' | 'drawing.error.drawioParseFailed' | 'drawing.error.drawioNoModel' | 'drawing.error.drawioNoElements' | 'drawing.error.viewerInitFailed' | 'drawing.error.drawioTimeout' | 'drawing.error.svgParseFailed' | 'drawing.error.plantumlRenderFailed' | 'drawing.title.excalidraw' | 'drawing.title.mermaid' | 'drawing.title.plantuml' | 'drawing.title.drawio' | 'drawing.toolbar.zoomOut' | 'drawing.toolbar.zoomIn' | 'drawing.toolbar.fit' | 'drawing.toolbar.fitWidth' | 'drawing.state.loading' | 'text.code.loadingHighlight' | 'text.code.indexingLargeFile' | 'text.code.virtualized' | 'text.code.firstSegment' | 'text.code.previousSegment' | 'text.code.nextSegment' | 'text.code.lastSegment' | 'ebook.toc' | 'ebook.reading' | 'ebook.itemCount' | 'epub.title' | 'epub.previousPage' | 'epub.nextPage' | 'epub.loading' | 'epub.chapterFallback' | 'epub.renderIncomplete' | 'umd.title' | 'umd.previousChapter' | 'umd.nextChapter' | 'umd.loading' | 'umd.emptyContent' | 'umd.chapterFallback' | 'umd.galleryFallback' | 'umd.warningBodyTooShort' | 'umd.error.unexpectedEnd' | 'umd.error.invalidFile' | 'typst.summaryRenderer' | 'typst.pageSummary.empty' | 'typst.pageSummary.ready' | 'typst.status.compiling' | 'typst.status.failed' | 'typst.status.rendered' | 'typst.loading.title' | 'typst.loading.hint' | 'typst.error.title' | 'typst.error.timeout' | 'typst.error.timeoutHint' | 'typst.error.assetHint' | 'typst.error.svgParseFailed' | 'typst.error.wasmLoadFailed' | 'xmind.toolbar.zoomOut' | 'xmind.toolbar.zoomIn' | 'xmind.toolbar.fit' | 'xmind.toolbar.fitTitle' | 'xmind.state.loading' | 'xmind.stats.nodes' | 'xmind.stats.depth' | 'xmind.stats.theme' | 'xmind.stats.template' | 'xmind.badge.paused' | 'xmind.badge.collapsed' | 'xmind.badge.floating' | 'xmind.badge.summary' | 'xmind.badge.callout' | 'xmind.imageResource' | 'xmind.error.unrecognized' | 'xmind.error.noCanvas' | 'cad.toolbar.fit' | 'cad.toolbar.zoomOut' | 'cad.toolbar.zoomIn' | 'cad.layers.title' | 'cad.layers.count' | 'cad.layers.merged' | 'cad.inspector.title' | 'cad.inspector.entities' | 'cad.inspector.blocks' | 'cad.inspector.pages' | 'cad.inspector.drawn' | 'cad.state.loadingViewer' | 'cad.state.parsing' | 'cad.error.parseFailed' | 'image.alt' | 'image.lightbox.alt' | 'image.lightbox.close' | 'gitBundle.error.invalid' | 'gitBundle.error.missingPack' | 'gitBundle.notice.delta' | 'gitBundle.title.history' | 'gitBundle.title.fileTree' | 'gitBundle.file.choose' | 'gitBundle.file.noTree' | 'gitBundle.file.none' | 'gitBundle.history.empty' | 'gitBundle.toolbar.summary' | 'gitBundle.meta.bundle' | 'gitBundle.meta.refs' | 'gitBundle.meta.commits' | 'gitBundle.meta.objects' | 'gitBundle.meta.deltas' | 'gitBundle.meta.objectFormat' | 'gitBundle.meta.objectTypes' | 'geo.error.unrecognized' | 'geo.error.xmlParseFailed' | 'geo.error.unsupported' | 'geo.title' | 'geo.featureCount' | 'geo.bounds' | 'geo.geometryTypes' | 'geo.aria' | 'geo.loading' | 'geo.projection' | 'geo.engine' | 'geo.basemap' | 'geo.basemap.offline' | 'geo.basemap.custom' | 'geo.engine.maplibre' | 'geo.engine.svg' | 'geo.error.projection' | 'geo.action.fit' | 'model.toolbar.fit' | 'model.toolbar.rotate' | 'model.toolbar.wireframe' | 'model.toolbar.grid' | 'model.toolbar.axes' | 'model.state.loadingSummary' | 'model.state.loading' | 'model.state.loaded' | 'model.state.parseFailed' | 'model.summary.meshes' | 'model.summary.points' | 'model.error.daeEmpty' | 'model.error.unsupported' | 'model.error.parseFailed' | 'model.notice.signature' | 'loading.generic.label' | 'loading.generic.hint' | 'loading.word.label' | 'loading.word.hint' | 'loading.wordWorker.hint' | 'loading.sheet.label' | 'loading.sheet.hint' | 'loading.csv.label' | 'loading.csv.hint' | 'loading.presentation.label' | 'loading.presentation.hint' | 'loading.pdf.label' | 'loading.pdf.hint' | 'loading.ofd.label' | 'loading.ofd.hint' | 'loading.archive.label' | 'loading.archive.hint' | 'loading.email.label' | 'loading.email.hint' | 'loading.msg.hint' | 'loading.eda.label' | 'loading.eda.hint' | 'loading.cad.label' | 'loading.cad.hint' | 'loading.dwg.hint' | 'loading.dwf.hint' | 'loading.dwfx.hint' | 'loading.xps.hint' | 'loading.drawio.label' | 'loading.drawio.hint' | 'loading.excalidraw.label' | 'loading.excalidraw.hint' | 'loading.epub.label' | 'loading.epub.hint' | 'loading.umd.label' | 'loading.umd.hint' | 'loading.image.label' | 'loading.image.hint' | 'loading.video.label' | 'loading.video.hint' | 'loading.audio.label' | 'loading.audio.hint';
+export type FileViewerMessageKey = 'toolbar.zoomGroup' | 'toolbar.zoomOut' | 'toolbar.zoomIn' | 'toolbar.zoomReset' | 'toolbar.download' | 'toolbar.downloadTitle' | 'toolbar.print' | 'toolbar.printTitle' | 'toolbar.printDirect' | 'toolbar.printMask' | 'toolbar.printMaskTitle' | 'toolbar.printMaskAdd' | 'toolbar.printMaskClear' | 'toolbar.printMaskCancel' | 'toolbar.printMaskConfirm' | 'toolbar.printMaskHint' | 'toolbar.printStampUpload' | 'toolbar.printStampRemove' | 'toolbar.printStampResize' | 'toolbar.exportHtml' | 'toolbar.exportHtmlTitle' | 'toolbar.search' | 'toolbar.searchPlaceholder' | 'toolbar.searchPrevious' | 'toolbar.searchNext' | 'toolbar.searchClear' | 'toolbar.theme' | 'toolbar.themeToLight' | 'toolbar.themeToDark' | 'state.ready.title' | 'state.ready.message' | 'state.empty.title' | 'state.empty.message' | 'state.unsupported.install.title' | 'state.unsupported.install.message' | 'state.unsupported.install.description' | 'state.unsupported.title' | 'state.unsupported.message' | 'state.unsupported.description' | 'state.error.title' | 'preview.downloading' | 'preview.streamingPdf' | 'preview.reading' | 'error.download' | 'error.print' | 'error.exportHtml' | 'error.noDownloadSource' | 'error.noExportContent' | 'error.printUnavailable' | 'error.printWindowBlocked' | 'error.remoteDownload' | 'error.localRead' | 'error.load' | 'error.stream' | 'error.beforeOperation' | 'error.unknown' | 'error.blobUnavailable' | 'error.sourceUnsupported' | 'error.fileReadArrayBuffer' | 'error.fileReadDataUrl' | 'error.fileReadText' | 'error.imageDataUrlRead' | 'operation.download' | 'operation.print' | 'operation.exportHtml' | 'operation.zoomIn' | 'operation.zoomOut' | 'operation.zoomReset' | 'pdf.toolbar.toggleNavigation' | 'pdf.toolbar.previousPage' | 'pdf.toolbar.nextPage' | 'pdf.toolbar.fitWidth' | 'pdf.toolbar.zoomOut' | 'pdf.toolbar.zoomIn' | 'pdf.toolbar.rotateLeft' | 'pdf.toolbar.rotateRight' | 'pdf.nav.typeLabel' | 'pdf.nav.pagesTab' | 'pdf.nav.outlineTab' | 'pdf.nav.pagesTitle' | 'pdf.nav.outlineTitle' | 'pdf.nav.pageCount' | 'pdf.nav.itemCount' | 'pdf.nav.pageLabel' | 'pdf.nav.outlineEmpty' | 'pdf.nav.outlineFallbackTitle' | 'pdf.thumbnail.alt' | 'pdf.state.loading' | 'pdf.error.browserWindow' | 'pdf.error.missingSource' | 'pdf.error.loadFailed' | 'pdf.error.notLoaded' | 'pdf.error.unloaded' | 'pdf.error.canvasUnavailable' | 'pdf.export.pageTitle' | 'spreadsheet.loading.kicker' | 'spreadsheet.loading.title' | 'spreadsheet.loading.hint' | 'spreadsheet.loading.streaming' | 'spreadsheet.tabs.ariaLabel' | 'spreadsheet.state.parsingWorkbook' | 'spreadsheet.state.preparingSheet' | 'spreadsheet.state.preparingSheetNamed' | 'spreadsheet.state.cachedRows' | 'spreadsheet.state.rows' | 'spreadsheet.state.rowsAndColumns' | 'spreadsheet.error.parseFailed' | 'spreadsheet.error.workerFailed' | 'word.error.invalidDocx' | 'word.error.missingOdfContent' | 'word.error.odfXmlParseFailed' | 'word.title.rtf' | 'word.title.openDocumentPresentation' | 'word.title.openDocumentText' | 'word.page.fallback' | 'word.page.empty' | 'word.body' | 'word.body.empty' | 'ofd.toolbar.pageNavigation' | 'ofd.toolbar.documentPages' | 'ofd.toolbar.previousPage' | 'ofd.toolbar.nextPage' | 'ofd.toolbar.pageStatus' | 'ofd.toolbar.noPages' | 'ofd.state.loading' | 'ofd.error.empty' | 'ofd.error.parseFailed' | 'presentation.state.loading' | 'presentation.error.title' | 'presentation.error.parseFailed' | 'presentation.ppt.state.loading' | 'presentation.ppt.error.title' | 'presentation.ppt.error.parseFailed' | 'presentation.ppt.error.assetHint' | 'archive.error.nestedUnsupported' | 'archive.loading.readingDirectory' | 'archive.loading.readingDirectoryHint' | 'archive.search.placeholder' | 'archive.sidebar.hide' | 'archive.sidebar.show' | 'archive.preview.title' | 'archive.preview.chooseFile' | 'archive.preview.downloadFile' | 'archive.error.title' | 'archive.stats.summary' | 'archive.warning.encrypted' | 'archive.password.title' | 'archive.password.description' | 'archive.password.placeholder' | 'archive.password.invalid' | 'archive.password.required' | 'archive.password.cancel' | 'archive.password.confirm' | 'archive.error.passwordRequired' | 'archive.error.encryptedRequiresWorker' | 'archive.empty.title' | 'archive.empty.message' | 'archive.loading.initializingCandidate' | 'archive.loading.initializingCandidateHint' | 'archive.error.candidateInitTimeout' | 'archive.error.encryptedCheckTimeout' | 'archive.loading.directoryReadyHint' | 'archive.error.candidateReadTimeout' | 'archive.loading.workerFallback' | 'archive.loading.workerFallbackHint' | 'archive.notice.workerFallback' | 'archive.error.tooLarge' | 'archive.loading.initializingWorker' | 'archive.loading.initializingWorkerHint' | 'archive.error.workerInitFailed' | 'archive.error.workerUnsupported' | 'archive.error.indexedDbUnavailable' | 'archive.error.entryTooLarge' | 'archive.loading.extracting' | 'archive.loading.rendering' | 'archive.loading.exporting' | 'media.audio.title' | 'media.audio.description' | 'media.audio.unsupported' | 'media.video.title' | 'media.video.unsupported' | 'media.video.hlsHint' | 'media.midi.title' | 'media.midi.loading' | 'media.midi.trackHeader' | 'media.midi.instrumentHeader' | 'media.midi.channelHeader' | 'media.midi.noteCountHeader' | 'media.midi.durationHeader' | 'media.midi.durationStat' | 'media.midi.trackStat' | 'media.midi.noteStat' | 'media.midi.parseFailed' | 'email.mbox.subject' | 'email.mbox.summary' | 'email.error.title' | 'email.meta.from' | 'email.meta.to' | 'email.meta.cc' | 'email.meta.date' | 'email.tabs.text' | 'email.tabs.headers' | 'email.attachments.title' | 'email.attachments.empty' | 'email.attachments.download' | 'email.attachments.opening' | 'email.attachments.nestedUnavailable' | 'email.loading.parsing' | 'data.font.sample' | 'data.error.fontFaceUnsupported' | 'data.title.font' | 'data.title.sqlite' | 'data.title.parquet' | 'data.title.avro' | 'data.title.wasm' | 'data.title.eps' | 'data.title.ai' | 'data.title.webarchive' | 'data.title.summary' | 'data.label.format' | 'data.label.size' | 'data.label.rendering' | 'data.label.objects' | 'data.label.sampleTable' | 'data.label.rows' | 'data.label.columns' | 'data.label.sampleRows' | 'data.label.imports' | 'data.label.exports' | 'data.label.magic' | 'data.label.note' | 'data.label.container' | 'data.value.schemaRead' | 'data.value.schemaUnread' | 'data.note.aiSummary' | 'data.note.postscriptSummary' | 'data.note.webarchive' | 'data.image.alt' | 'psd.title' | 'psd.action.fit' | 'psd.action.showAll' | 'psd.action.hideAll' | 'psd.layers.title' | 'psd.layers.redrawable' | 'psd.layers.empty' | 'psd.layers.hidden' | 'drawing.error.viewerLoadFailed' | 'drawing.error.excalidrawEmpty' | 'drawing.error.excalidrawTimeout' | 'drawing.error.drawioParseFailed' | 'drawing.error.drawioNoModel' | 'drawing.error.drawioNoElements' | 'drawing.error.viewerInitFailed' | 'drawing.error.drawioTimeout' | 'drawing.error.svgParseFailed' | 'drawing.error.plantumlRenderFailed' | 'drawing.title.excalidraw' | 'drawing.title.mermaid' | 'drawing.title.plantuml' | 'drawing.title.drawio' | 'drawing.toolbar.zoomOut' | 'drawing.toolbar.zoomIn' | 'drawing.toolbar.fit' | 'drawing.toolbar.fitWidth' | 'drawing.state.loading' | 'text.code.loadingHighlight' | 'text.code.indexingLargeFile' | 'text.code.virtualized' | 'text.code.firstSegment' | 'text.code.previousSegment' | 'text.code.nextSegment' | 'text.code.lastSegment' | 'ebook.toc' | 'ebook.reading' | 'ebook.itemCount' | 'epub.title' | 'epub.previousPage' | 'epub.nextPage' | 'epub.loading' | 'epub.chapterFallback' | 'epub.renderIncomplete' | 'umd.title' | 'umd.previousChapter' | 'umd.nextChapter' | 'umd.loading' | 'umd.emptyContent' | 'umd.chapterFallback' | 'umd.galleryFallback' | 'umd.warningBodyTooShort' | 'umd.error.unexpectedEnd' | 'umd.error.invalidFile' | 'typst.summaryRenderer' | 'typst.pageSummary.empty' | 'typst.pageSummary.ready' | 'typst.status.compiling' | 'typst.status.failed' | 'typst.status.rendered' | 'typst.loading.title' | 'typst.loading.hint' | 'typst.error.title' | 'typst.error.timeout' | 'typst.error.timeoutHint' | 'typst.error.assetHint' | 'typst.error.svgParseFailed' | 'typst.error.wasmLoadFailed' | 'xmind.toolbar.zoomOut' | 'xmind.toolbar.zoomIn' | 'xmind.toolbar.fit' | 'xmind.toolbar.fitTitle' | 'xmind.state.loading' | 'xmind.stats.nodes' | 'xmind.stats.depth' | 'xmind.stats.theme' | 'xmind.stats.template' | 'xmind.badge.paused' | 'xmind.badge.collapsed' | 'xmind.badge.floating' | 'xmind.badge.summary' | 'xmind.badge.callout' | 'xmind.imageResource' | 'xmind.error.unrecognized' | 'xmind.error.noCanvas' | 'cad.toolbar.fit' | 'cad.toolbar.zoomOut' | 'cad.toolbar.zoomIn' | 'cad.layers.title' | 'cad.layers.count' | 'cad.layers.merged' | 'cad.inspector.title' | 'cad.inspector.entities' | 'cad.inspector.blocks' | 'cad.inspector.pages' | 'cad.inspector.drawn' | 'cad.state.loadingViewer' | 'cad.state.parsing' | 'cad.error.parseFailed' | 'image.alt' | 'image.toolbar.rotation' | 'image.toolbar.rotateLeft' | 'image.toolbar.rotateRight' | 'image.lightbox.alt' | 'image.lightbox.close' | 'gitBundle.error.invalid' | 'gitBundle.error.missingPack' | 'gitBundle.notice.delta' | 'gitBundle.title.history' | 'gitBundle.title.fileTree' | 'gitBundle.file.choose' | 'gitBundle.file.noTree' | 'gitBundle.file.none' | 'gitBundle.history.empty' | 'gitBundle.toolbar.summary' | 'gitBundle.meta.bundle' | 'gitBundle.meta.refs' | 'gitBundle.meta.commits' | 'gitBundle.meta.objects' | 'gitBundle.meta.deltas' | 'gitBundle.meta.objectFormat' | 'gitBundle.meta.objectTypes' | 'geo.error.unrecognized' | 'geo.error.xmlParseFailed' | 'geo.error.unsupported' | 'geo.title' | 'geo.featureCount' | 'geo.bounds' | 'geo.geometryTypes' | 'geo.aria' | 'geo.loading' | 'geo.projection' | 'geo.engine' | 'geo.basemap' | 'geo.basemap.offline' | 'geo.basemap.custom' | 'geo.engine.maplibre' | 'geo.engine.svg' | 'geo.error.projection' | 'geo.action.fit' | 'model.toolbar.fit' | 'model.toolbar.rotate' | 'model.toolbar.wireframe' | 'model.toolbar.grid' | 'model.toolbar.axes' | 'model.state.loadingSummary' | 'model.state.loading' | 'model.state.loaded' | 'model.state.parseFailed' | 'model.summary.meshes' | 'model.summary.points' | 'model.error.daeEmpty' | 'model.error.unsupported' | 'model.error.parseFailed' | 'model.notice.signature' | 'loading.generic.label' | 'loading.generic.hint' | 'loading.word.label' | 'loading.word.hint' | 'loading.wordWorker.hint' | 'loading.sheet.label' | 'loading.sheet.hint' | 'loading.csv.label' | 'loading.csv.hint' | 'loading.presentation.label' | 'loading.presentation.hint' | 'loading.pdf.label' | 'loading.pdf.hint' | 'loading.ofd.label' | 'loading.ofd.hint' | 'loading.archive.label' | 'loading.archive.hint' | 'loading.email.label' | 'loading.email.hint' | 'loading.msg.hint' | 'loading.eda.label' | 'loading.eda.hint' | 'loading.cad.label' | 'loading.cad.hint' | 'loading.dwg.hint' | 'loading.dwf.hint' | 'loading.dwfx.hint' | 'loading.xps.hint' | 'loading.drawio.label' | 'loading.drawio.hint' | 'loading.excalidraw.label' | 'loading.excalidraw.hint' | 'loading.epub.label' | 'loading.epub.hint' | 'loading.umd.label' | 'loading.umd.hint' | 'loading.image.label' | 'loading.image.hint' | 'loading.video.label' | 'loading.video.hint' | 'loading.audio.label' | 'loading.audio.hint';
 export type FileViewerMessageParams = Record<string, string | number | boolean | null | undefined>;
 export type FileViewerMessageResolver = (key: FileViewerMessageKey, params: FileViewerMessageParams, locale: FileViewerLocale) => string | undefined;
 export type FileViewerMessages = Partial<Record<FileViewerMessageKey, string>> | FileViewerMessageResolver;
@@ -114,6 +114,12 @@ export interface FileViewerPdfOptions {
     defaultNavigationVisible?: boolean;
     thumbnails?: boolean;
     rotation?: number;
+    /**
+     * Highlights and focuses one or more PDF regions after the document loads.
+     * Use `pixel` with `sourceWidth` / `sourceHeight` for OCR coordinates, or
+     * `pdf-point` for native PDF coordinates. Page numbers are one-based.
+     */
+    bbox?: FileViewerPdfBoundingBox | readonly FileViewerPdfBoundingBox[];
     /**
      * Initial PDF view position. Prefer the top-level `initialViewState` when the
      * same state should be passed through framework-neutral viewer APIs.
@@ -150,6 +156,29 @@ export interface FileViewerPdfOptions {
      */
     cjkFontFallbackPath?: string;
 }
+export type FileViewerPdfBoundingBoxUnit = 'ratio' | 'percent' | 'pixel' | 'pdf-point';
+export type FileViewerPdfBoundingBoxOrigin = 'top-left' | 'bottom-left';
+export interface FileViewerPdfBoundingBox {
+    id?: string;
+    /** One-based PDF page number. Defaults to the current page, then page 1. */
+    page?: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Defaults to `pdf-point`. */
+    unit?: FileViewerPdfBoundingBoxUnit;
+    /** Defaults to `bottom-left` for PDF points and `top-left` otherwise. */
+    origin?: FileViewerPdfBoundingBoxOrigin;
+    /** Required when `unit` is `pixel`; this is the OCR/source image width. */
+    sourceWidth?: number;
+    /** Required when `unit` is `pixel`; this is the OCR/source image height. */
+    sourceHeight?: number;
+    /** CSS color used for the outline and translucent fill. */
+    color?: string;
+    /** Optional accessible description for the highlighted region. */
+    label?: string;
+}
 export interface FileViewerDocxOptions {
     worker?: boolean;
     workerUrl?: string;
@@ -168,6 +197,8 @@ export interface FileViewerDocxOptions {
     updatePageReferences?: boolean;
     hideWebHiddenContent?: boolean;
     ignoreLastRenderedPageBreak?: boolean;
+    /** External DOCX links are blocked by default; internal bookmark links remain active. */
+    externalLinkPolicy?: 'allow' | 'block';
     /** Overrides automatic DOCX dark rendering derived from the viewer theme. */
     darkMode?: boolean;
 }
@@ -316,13 +347,16 @@ export interface FileViewerModelOptions {
 export interface FileViewerDataOptions {
     sqlWasmUrl?: string;
 }
-export type FileViewerGeoBasemapPreset = 'none' | 'offline' | 'openfreemap' | 'openfreemap-liberty' | 'openfreemap-bright' | 'openfreemap-positron' | 'openfreemap-dark' | 'openfreemap-fiord' | 'osm-raster';
+export type FileViewerGeoBasemapPreset = 'none' | 'offline' | 'openfreemap' | 'openfreemap-liberty' | 'openfreemap-bright' | 'openfreemap-positron' | 'openfreemap-dark' | 'openfreemap-fiord' | 'osm-raster' | 'tianditu-vector' | 'tianditu-imagery' | 'tianditu-terrain';
+export type FileViewerTiandituMapStyle = 'vector' | 'imagery' | 'terrain';
 export interface FileViewerGeoBasemapOptions {
     /**
      * `raster` uses XYZ/TMS image tiles. `vector-style` uses a MapLibre style
      * object or URL, which is the best path for OpenFreeMap/OpenMapTiles stacks.
+     * `tianditu` builds the official base and annotation raster layers from the
+     * caller-provided Tianditu token.
      */
-    type?: 'raster' | 'vector-style';
+    type?: 'raster' | 'vector-style' | 'tianditu';
     /**
      * Raster XYZ/TMS tile template, for example `/tiles/{z}/{x}/{y}.png`.
      */
@@ -346,6 +380,12 @@ export interface FileViewerGeoBasemapOptions {
     maxZoom?: number;
     scheme?: 'xyz' | 'tms';
     rasterOpacity?: number;
+    /** Tianditu API token. Required when `type` is `tianditu`. */
+    token?: string;
+    /** Tianditu map family. Defaults to `vector`. */
+    mapStyle?: FileViewerTiandituMapStyle;
+    /** Include the matching Tianditu annotation layer. Defaults to true. */
+    labels?: boolean;
 }
 export interface FileViewerGeoOptions {
     /**
@@ -371,6 +411,11 @@ export interface FileViewerGeoOptions {
      * self-hosted or intranet style/tile URL.
      */
     basemap?: false | FileViewerGeoBasemapPreset | FileViewerGeoBasemapOptions;
+    /**
+     * Tianditu API token used by the `tianditu-*` presets. The viewer never
+     * supplies or persists a token; obtain one for the deployment's own domain.
+     */
+    tiandituToken?: string;
     /**
      * Defaults to true. When no CRS is declared and coordinates exceed longitude
      * or latitude ranges, the geo renderer treats Web Mercator-sized values as
@@ -891,9 +936,21 @@ export interface FileViewerPrintMaskRegion {
     /** Zero-based rendered page index. Omitted regions retain legacy whole-document coordinates. */
     pageIndex?: number;
 }
+/** Page-aware image placed above rendered content for printing, such as a seal or signature. */
+export interface FileViewerPrintStamp extends FileViewerPrintMaskRegion {
+    /** Image URL. Uploaded stamps are converted to a local data URL by the designer. */
+    src: string;
+    /** Image opacity from 0 to 1. Defaults to 1. */
+    opacity?: number;
+    /** Clockwise rotation in degrees. Defaults to 0. */
+    rotate?: number;
+    alt?: string;
+}
 export interface FileViewerPrintMaskOptions {
     /** Solid black cover blocks, matching common OFD/business redaction UX. */
     regions?: FileViewerPrintMaskRegion[];
+    /** Image overlays, including locally uploaded seals and signatures. */
+    stamps?: FileViewerPrintStamp[];
     /** Fill color for print masks. Defaults to opaque black. */
     color?: string;
 }

package/dist/features/printMask.d.ts

@@ -1,6 +1,7 @@
-import type { FileViewerPrintMaskOptions, FileViewerPrintMaskRegion } from '../contracts/types';
+import type { FileViewerPrintMaskOptions, FileViewerPrintMaskRegion, FileViewerPrintStamp } from '../contracts/types';
 export declare const normalizeFileViewerPrintMaskRegion: (region: Partial<FileViewerPrintMaskRegion> | null | undefined) => FileViewerPrintMaskRegion | null;
+export declare const normalizeFileViewerPrintStamp: (stamp: Partial<FileViewerPrintStamp> | null | undefined) => FileViewerPrintStamp | null;
 export declare const normalizeFileViewerPrintMaskOptions: (mask?: FileViewerPrintMaskOptions | null) => FileViewerPrintMaskOptions | null;
 export declare const buildFileViewerPrintMaskOverlayHtml: (mask?: FileViewerPrintMaskOptions | null, pageScoped?: boolean) => string;
-export declare const FILE_VIEWER_PRINT_MASK_STYLE = "\n  .viewer-export-print-mask{position:absolute;inset:0;z-index:15;pointer-events:none;print-color-adjust:exact;-webkit-print-color-adjust:exact;}\n  .viewer-export-print-mask--page{z-index:2147483647;}\n  .viewer-export-print-mask-block{position:absolute;box-sizing:border-box;print-color-adjust:exact;-webkit-print-color-adjust:exact;}\n  [data-viewer-print-page-index]{position:relative!important;isolation:isolate;}\n";
+export declare const FILE_VIEWER_PRINT_MASK_STYLE = "\n  .viewer-export-print-mask{position:absolute;inset:0;z-index:15;pointer-events:none;print-color-adjust:exact;-webkit-print-color-adjust:exact;}\n  .viewer-export-print-mask--page{z-index:2147483647;}\n  .viewer-export-print-mask-block{position:absolute;box-sizing:border-box;print-color-adjust:exact;-webkit-print-color-adjust:exact;}\n  .viewer-export-print-stamp{position:absolute;display:block;object-fit:contain;transform-origin:center center;print-color-adjust:exact;-webkit-print-color-adjust:exact;}\n  [data-viewer-print-page-index]{position:relative!important;isolation:isolate;}\n";
 export declare const applyFileViewerPagePrintMasksToHtml: (contentHtml: string, mask?: FileViewerPrintMaskOptions | null) => string;

package/dist/features/printMask.js

@@ -23,47 +23,99 @@ export const normalizeFileViewerPrintMaskRegion = (region) => {
         ...(pageIndex === undefined ? {} : { pageIndex }),
     };
 };
+const normalizeStampSource = (value) => {
+    if (typeof value !== 'string') {
+        return '';
+    }
+    const source = value.trim();
+    if (/^data:image\/(?:png|jpe?g|webp|gif|svg\+xml);/i.test(source) ||
+        /^(?:blob:|https?:\/\/|\/|\.\.?\/)/i.test(source)) {
+        return source;
+    }
+    return '';
+};
+const clampOpacity = (value) => {
+    const opacity = Number(value);
+    return Number.isFinite(opacity) ? Math.max(0, Math.min(1, opacity)) : 1;
+};
+const normalizeRotation = (value) => {
+    const rotation = Number(value);
+    if (!Number.isFinite(rotation)) {
+        return 0;
+    }
+    return ((rotation % 360) + 360) % 360;
+};
+export const normalizeFileViewerPrintStamp = (stamp) => {
+    const region = normalizeFileViewerPrintMaskRegion(stamp);
+    const src = normalizeStampSource(stamp === null || stamp === void 0 ? void 0 : stamp.src);
+    if (!region || !src) {
+        return null;
+    }
+    return {
+        ...region,
+        src,
+        opacity: clampOpacity(stamp === null || stamp === void 0 ? void 0 : stamp.opacity),
+        rotate: normalizeRotation(stamp === null || stamp === void 0 ? void 0 : stamp.rotate),
+        ...(typeof (stamp === null || stamp === void 0 ? void 0 : stamp.alt) === 'string' && stamp.alt.trim()
+            ? { alt: stamp.alt.trim() }
+            : {}),
+    };
+};
 export const normalizeFileViewerPrintMaskOptions = (mask) => {
-    if (!mask || !Array.isArray(mask.regions) || !mask.regions.length) {
+    if (!mask) {
         return null;
     }
-    const regions = mask.regions
+    const regions = (mask.regions || [])
         .map(region => normalizeFileViewerPrintMaskRegion(region))
         .filter((region) => !!region);
-    if (!regions.length) {
+    const stamps = (mask.stamps || [])
+        .map(stamp => normalizeFileViewerPrintStamp(stamp))
+        .filter((stamp) => !!stamp);
+    if (!regions.length && !stamps.length) {
         return null;
     }
     return {
-        regions,
+        ...(regions.length ? { regions } : {}),
+        ...(stamps.length ? { stamps } : {}),
         color: mask.color || '#000000',
     };
 };
+const escapeHtmlAttribute = (value) => value
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
 export const buildFileViewerPrintMaskOverlayHtml = (mask, pageScoped = false) => {
-    var _a;
     const normalized = normalizeFileViewerPrintMaskOptions(mask);
-    if (!((_a = normalized === null || normalized === void 0 ? void 0 : normalized.regions) === null || _a === void 0 ? void 0 : _a.length)) {
+    if (!normalized) {
         return '';
     }
     const color = normalized.color || '#000000';
-    const blocks = normalized.regions.map(region => (`<div class="viewer-export-print-mask-block" style="left:${region.left}%;top:${region.top}%;width:${region.width}%;height:${region.height}%;background:${color};"></div>`)).join('');
+    const blocks = (normalized.regions || []).map(region => (`<div class="viewer-export-print-mask-block" style="left:${region.left}%;top:${region.top}%;width:${region.width}%;height:${region.height}%;background:${color};"></div>`)).join('');
+    const stamps = (normalized.stamps || []).map(stamp => {
+        var _a, _b;
+        return (`<img class="viewer-export-print-stamp" src="${escapeHtmlAttribute(stamp.src)}" alt="${escapeHtmlAttribute(stamp.alt || '')}" draggable="false" style="left:${stamp.left}%;top:${stamp.top}%;width:${stamp.width}%;height:${stamp.height}%;opacity:${(_a = stamp.opacity) !== null && _a !== void 0 ? _a : 1};transform:rotate(${(_b = stamp.rotate) !== null && _b !== void 0 ? _b : 0}deg);" />`);
+    }).join('');
     const className = pageScoped
         ? 'viewer-export-print-mask viewer-export-print-mask--page'
         : 'viewer-export-print-mask';
-    return `<div class="${className}" aria-hidden="true">${blocks}</div>`;
+    return `<div class="${className}" aria-hidden="true">${blocks}${stamps}</div>`;
 };
 export const FILE_VIEWER_PRINT_MASK_STYLE = `
   .viewer-export-print-mask{position:absolute;inset:0;z-index:15;pointer-events:none;print-color-adjust:exact;-webkit-print-color-adjust:exact;}
   .viewer-export-print-mask--page{z-index:2147483647;}
   .viewer-export-print-mask-block{position:absolute;box-sizing:border-box;print-color-adjust:exact;-webkit-print-color-adjust:exact;}
+  .viewer-export-print-stamp{position:absolute;display:block;object-fit:contain;transform-origin:center center;print-color-adjust:exact;-webkit-print-color-adjust:exact;}
   [data-viewer-print-page-index]{position:relative!important;isolation:isolate;}
 `;
 export const applyFileViewerPagePrintMasksToHtml = (contentHtml, mask) => {
-    var _a;
+    var _a, _b;
     const normalized = normalizeFileViewerPrintMaskOptions(mask);
     if (!normalized) {
         return contentHtml;
     }
     const regionsByPage = new Map();
+    const stampsByPage = new Map();
     (_a = normalized.regions) === null || _a === void 0 ? void 0 : _a.forEach(region => {
         if (region.pageIndex === undefined) {
             return;
@@ -72,16 +124,26 @@ export const applyFileViewerPagePrintMasksToHtml = (contentHtml, mask) => {
         pageRegions.push(region);
         regionsByPage.set(region.pageIndex, pageRegions);
     });
-    if (!regionsByPage.size) {
+    (_b = normalized.stamps) === null || _b === void 0 ? void 0 : _b.forEach(stamp => {
+        if (stamp.pageIndex === undefined) {
+            return;
+        }
+        const pageStamps = stampsByPage.get(stamp.pageIndex) || [];
+        pageStamps.push(stamp);
+        stampsByPage.set(stamp.pageIndex, pageStamps);
+    });
+    if (!regionsByPage.size && !stampsByPage.size) {
         return contentHtml;
     }
     return contentHtml.replace(/(<[A-Za-z][^>]*\sdata-viewer-print-page-index=(['"])(\d+)\2[^>]*>)/g, (match, openingTag, _quote, rawPageIndex) => {
         const pageRegions = regionsByPage.get(Number(rawPageIndex));
-        if (!(pageRegions === null || pageRegions === void 0 ? void 0 : pageRegions.length)) {
+        const pageStamps = stampsByPage.get(Number(rawPageIndex));
+        if (!(pageRegions === null || pageRegions === void 0 ? void 0 : pageRegions.length) && !(pageStamps === null || pageStamps === void 0 ? void 0 : pageStamps.length)) {
             return match;
         }
         return `${openingTag}${buildFileViewerPrintMaskOverlayHtml({
-            regions: pageRegions,
+            regions: pageRegions || [],
+            stamps: pageStamps || [],
             color: normalized.color,
         }, true)}`;
     });

package/dist/features/printMaskDesigner.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerPrintMaskOptions, FileViewerPrintMaskRegion } from '../contracts/types';
+import type { FileViewerPrintMaskOptions, FileViewerPrintMaskRegion, FileViewerPrintStamp } from '../contracts/types';
 import { type FileViewerI18nInput } from '../i18n/messages';
 export interface OpenFileViewerPrintMaskDesignerOptions {
     root: HTMLElement;
@@ -6,6 +6,7 @@ export interface OpenFileViewerPrintMaskDesignerOptions {
     i18n?: FileViewerI18nInput;
     color?: string;
     initialRegions?: FileViewerPrintMaskRegion[];
+    initialStamps?: FileViewerPrintStamp[];
 }
 export interface FileViewerPrintMaskDesignerResult {
     mask: FileViewerPrintMaskOptions;