@file-viewer/core 2.1.17 → 2.1.18

package/README.en.md

@@ -41,13 +41,16 @@ import {
 
 const viewer = createViewer(document.querySelector('#viewer')!, {
   options: {
-    toolbar: true
+    toolbar: true,
+    styleIsolation: 'shadow'
   }
 })
 
 await viewer.load({ url: '/files/report.pdf' })
 ```
 
+`options.styleIsolation` accepts `auto`, `shadow`, `scoped`, or `none`. Use `shadow` when a custom host or framework wrapper needs a ShadowRoot-backed render surface. Core passes the resolved `surface` to renderer `load(context)`, so custom renderers should inject styles into `context.surface.shadowRoot` or the renderer container instead of `document.head`, and should mount overlays inside the same isolated surface when possible.
+
 The root `@file-viewer/core` entry remains the complete compatibility entry for existing integrations. New component packages should prefer the narrowest explicit entry point they need: `headless` for contracts and build-time helpers, `browser` for real browser preview.
 
 ```ts

package/README.md

@@ -41,13 +41,16 @@ import {
 
 const viewer = createViewer(document.querySelector('#viewer')!, {
   options: {
-    toolbar: true
+    toolbar: true,
+    styleIsolation: 'shadow'
   }
 })
 
 await viewer.load({ url: '/files/report.pdf' })
 ```
 
+`options.styleIsolation` accepts `auto`, `shadow`, `scoped`, or `none`. Use `shadow` when a custom host or framework wrapper needs a ShadowRoot-backed render surface. Core passes the resolved `surface` to renderer `load(context)`, so custom renderers should inject styles into `context.surface.shadowRoot` or the renderer container instead of `document.head`, and should mount overlays inside the same isolated surface when possible.
+
 The root `@file-viewer/core` entry remains the complete compatibility entry for existing integrations. New component packages should prefer the narrowest explicit entry point they need: `headless` for contracts and build-time helpers, `browser` for real browser preview.
 
 ```ts

package/dist/contracts/types.d.ts

@@ -1,7 +1,8 @@
 export type FileViewerSourceKind = 'file' | 'url' | 'buffer' | 'empty';
 export type FileViewerThemeMode = 'light' | 'dark' | 'system';
 export type FileViewerLocale = 'auto' | 'zh-CN' | 'en-US' | (string & {});
-export type FileViewerMessageKey = 'toolbar.zoomGroup' | 'toolbar.zoomOut' | 'toolbar.zoomIn' | 'toolbar.zoomReset' | 'toolbar.download' | 'toolbar.downloadTitle' | 'toolbar.print' | 'toolbar.printTitle' | 'toolbar.exportHtml' | 'toolbar.exportHtmlTitle' | 'toolbar.search' | 'toolbar.searchPlaceholder' | 'toolbar.searchPrevious' | 'toolbar.searchNext' | 'toolbar.searchClear' | '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' | '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' | '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.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' | '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.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 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.exportHtml' | 'toolbar.exportHtmlTitle' | 'toolbar.search' | 'toolbar.searchPlaceholder' | 'toolbar.searchPrevious' | 'toolbar.searchNext' | 'toolbar.searchClear' | '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' | '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' | '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.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 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;
@@ -10,9 +11,20 @@ export interface FileViewerI18nOptions {
     messages?: FileViewerMessages;
 }
 export type FileViewerFileRef = File | Blob | ArrayBuffer;
-export type FileViewerToolbarPosition = 'auto' | 'top' | 'bottom-right';
+export type FileViewerToolbarPosition = 'auto' | 'top' | 'top-center' | 'bottom-right';
+export type FileViewerFitMode = 'auto' | 'contain' | 'cover' | 'width' | 'height' | 'actual' | 'scale-down';
+export type FileViewerFitResize = 'until-interaction' | 'always' | 'initial';
+export interface FileViewerFitOptions {
+    mode?: FileViewerFitMode;
+    resize?: FileViewerFitResize;
+    padding?: number;
+    minScale?: number;
+    maxScale?: number;
+}
 export type FileViewerLifecyclePhase = 'load-start' | 'load-complete' | 'unload-start' | 'unload-complete';
 export type FileViewerOperationType = 'download' | 'print' | 'export-html' | 'zoom-in' | 'zoom-out' | 'zoom-reset';
+export type FileViewerToolbarItem = 'search' | 'zoom' | 'download' | 'print' | 'exportHtml' | 'export-html';
+export type FileViewerResolvedToolbarItem = 'search' | 'zoom' | 'download' | 'print' | 'exportHtml';
 export type FileViewerToolbarActionMap = Partial<Record<FileViewerOperationType, boolean>>;
 export type FileViewerRenderStateKind = 'idle' | 'loading' | 'ready' | 'empty' | 'unsupported' | 'error';
 export type FileViewerRendererCategory = 'office' | 'document' | 'archive' | 'email' | 'eda' | 'cad' | 'model' | 'geo' | 'drawing' | 'mindmap' | 'ebook' | 'image' | 'markdown' | 'code' | 'media' | 'asset' | 'fallback';
@@ -36,6 +48,8 @@ export interface FileViewerToolbarOptions {
     exportHtml?: boolean;
     zoom?: boolean;
     search?: boolean;
+    /** Built-in toolbar group order. Missing entries keep their default relative order. */
+    order?: FileViewerToolbarItem[];
     /** Controls which built-in toolbar actions are displayed without disabling controller APIs. */
     items?: FileViewerToolbarActionMap;
     /** Hard operation permission map. False values block both built-in toolbar and public API calls. */
@@ -143,6 +157,7 @@ export interface FileRenderContext {
     url?: string;
     streamUrl?: string;
     options?: FileViewerOptions;
+    surface?: RenderSurface;
     registerExportAdapter?: (adapter: FileRenderExportAdapter | null) => void;
     onProgressiveRender?: () => void;
     renderNestedBuffer?: (buffer: ArrayBuffer, type: string, target: HTMLDivElement, context?: FileRenderContext) => Promise<FileViewerRenderedInstance | undefined>;
@@ -279,6 +294,7 @@ export interface FileViewerDrawingOptions {
 }
 export type FileViewerCadRenderer = 'auto' | 'webgl' | 'canvas2d';
 export type FileViewerCadDwfLineWeightMode = 'adaptive' | 'physical' | 'hairline';
+export type FileViewerCadFitMode = 'best' | 'native';
 export interface FileViewerCadOptions {
     wasmPath?: string;
     workerUrl?: string | URL;
@@ -292,6 +308,16 @@ export interface FileViewerCadOptions {
     maxInsertDepth?: number;
     keepRaw?: boolean;
     preloadDwg?: boolean;
+    /**
+     * `best` fits the first view to visible drawing geometry and ignores common
+     * CAD outliers such as paper-space frames or far-away markers. `native`
+     * preserves the raw bounds reported by the underlying CAD renderer.
+     */
+    fitMode?: FileViewerCadFitMode;
+    /**
+     * Fraction of the CAD viewport used by fit-to-view. Defaults to 0.92.
+     */
+    fitPadding?: number;
     dwfPreferWebgl?: boolean;
     dwfPreferWasm?: boolean;
     dwfBackground?: string;
@@ -336,6 +362,12 @@ export interface FileViewerAiOptions {
 }
 export interface FileViewerOptions {
     theme?: FileViewerThemeMode;
+    /**
+     * Controls how aggressively the viewer protects its DOM and CSS from the
+     * host page. `auto` keeps framework integrations compatible while allowing
+     * Web Component integrations to opt into Shadow DOM by default.
+     */
+    styleIsolation?: FileViewerStyleIsolation;
     /**
      * Viewer UI language. `auto` follows the browser language, Chinese browsers
      * resolve to `zh-CN`, and all other languages currently resolve to `en-US`.
@@ -399,6 +431,11 @@ export interface FileViewerOptions {
     toolbar?: boolean | FileViewerToolbarOptions;
     search?: boolean | FileViewerSearchOptions;
     ai?: boolean | FileViewerAiOptions;
+    /**
+     * Explicit content fitting strategy. When omitted, each renderer keeps its
+     * historical first-screen behavior for backward compatibility.
+     */
+    fit?: FileViewerFitMode | FileViewerFitOptions;
     /**
      * Initial renderer view position used after the document becomes ready.
      *
@@ -479,11 +516,31 @@ export interface FileViewerZoomState {
     minScale?: number;
     maxScale?: number;
 }
+export interface FileViewerFitRequest extends Required<Pick<FileViewerFitOptions, 'mode' | 'resize' | 'padding'>> {
+    minScale?: number;
+    maxScale?: number;
+    source: FileViewerViewStateChangeSource;
+    reason: 'initial' | 'resize' | 'api' | 'retry';
+    viewportWidth: number;
+    viewportHeight: number;
+    container?: HTMLElement | null;
+}
+export interface FileViewerFitResult {
+    applied: boolean;
+    mode: FileViewerFitMode;
+    resize: FileViewerFitResize;
+    scale?: number;
+    source?: FileViewerViewStateChangeSource;
+    reason?: string;
+    provider?: 'view-state' | 'zoom' | 'none' | (string & {});
+    state?: FileViewerViewState;
+}
 export interface FileViewerZoomProvider {
     zoomIn: () => FileViewerZoomState | Promise<FileViewerZoomState>;
     zoomOut: () => FileViewerZoomState | Promise<FileViewerZoomState>;
     resetZoom: () => FileViewerZoomState | Promise<FileViewerZoomState>;
     setZoom?: (scale: number) => FileViewerZoomState | Promise<FileViewerZoomState>;
+    fit?: (request: FileViewerFitRequest) => FileViewerFitResult | Promise<FileViewerFitResult>;
     getState: () => FileViewerZoomState;
     subscribe?: (listener: () => void) => () => void;
 }
@@ -513,7 +570,7 @@ export interface FileViewerViewState {
     extra?: Record<string, unknown>;
 }
 export type FileViewerViewStateChangeSource = 'initial' | 'api' | 'user' | 'viewer' | (string & {});
-export type FileViewerViewStateChangeAction = 'init' | 'restore' | 'page-change' | 'page-click' | 'page-step' | 'outline-click' | 'zoom-change' | 'zoom-in' | 'zoom-out' | 'zoom-reset' | 'rotation-change' | 'rotate-left' | 'rotate-right' | 'scroll' | 'navigation-toggle' | 'navigation-mode-change' | (string & {});
+export type FileViewerViewStateChangeAction = 'init' | 'restore' | 'page-change' | 'page-click' | 'page-step' | 'outline-click' | 'zoom-change' | 'zoom-in' | 'zoom-out' | 'zoom-reset' | 'fit' | 'rotation-change' | 'rotate-left' | 'rotate-right' | 'scroll' | 'navigation-toggle' | 'navigation-mode-change' | (string & {});
 export interface FileViewerViewStateChange {
     state: FileViewerViewState;
     action: FileViewerViewStateChangeAction;
@@ -528,6 +585,7 @@ export interface FileViewerApplyViewStateOptions {
 export interface FileViewerViewStateProvider {
     getState: () => FileViewerViewState;
     applyState?: (state: FileViewerViewState, options?: FileViewerApplyViewStateOptions) => FileViewerViewState | Promise<FileViewerViewState>;
+    fit?: (request: FileViewerFitRequest) => FileViewerFitResult | Promise<FileViewerFitResult>;
     subscribe?: (listener: (change: FileViewerViewStateChange) => void) => () => void;
 }
 export interface FileViewerSearchMatch {
@@ -593,6 +651,7 @@ export interface FileViewerComponentEventMap {
     'location-change': FileViewerDocumentAnchor | null;
     'zoom-change': FileViewerZoomState;
     'view-state-change': FileViewerViewStateChange;
+    'fit-change': FileViewerFitResult;
 }
 export type FileViewerEventType = keyof FileViewerComponentEventMap;
 export type FileViewerEvent = {
@@ -614,14 +673,17 @@ export interface FileViewerComponentEmits {
     (event: 'location-change', anchor: FileViewerComponentEventMap['location-change']): void;
     (event: 'zoom-change', state: FileViewerComponentEventMap['zoom-change']): void;
     (event: 'view-state-change', change: FileViewerComponentEventMap['view-state-change']): void;
+    (event: 'fit-change', result: FileViewerComponentEventMap['fit-change']): void;
 }
 export interface FileViewerPublicApi {
+    destroy(): void;
     downloadOriginalFile(): Promise<void>;
     printRenderedHtml(): Promise<void>;
     exportRenderedHtml(): Promise<void>;
     zoomIn(): Promise<FileViewerZoomState>;
     zoomOut(): Promise<FileViewerZoomState>;
     resetZoom(): Promise<FileViewerZoomState>;
+    fitToView(fit?: FileViewerFitMode | FileViewerFitOptions): Promise<FileViewerFitResult>;
     getZoomState(): FileViewerZoomState;
     getViewState(): FileViewerViewState | null;
     applyViewState(state: FileViewerViewState, options?: FileViewerApplyViewStateOptions): Promise<FileViewerViewState | null>;
@@ -671,8 +733,10 @@ export interface NormalizedFileViewerSource {
     size?: number;
 }
 export interface RenderSurface {
+    host?: HTMLElement;
     container: HTMLElement;
     shadowRoot?: ShadowRoot;
+    styleIsolation?: Exclude<FileViewerStyleIsolation, 'auto'>;
 }
 export interface RendererCapability {
     download?: boolean;
@@ -767,6 +831,7 @@ export interface FileViewerInstance {
     zoomIn(): Promise<FileViewerZoomState>;
     zoomOut(): Promise<FileViewerZoomState>;
     resetZoom(): Promise<FileViewerZoomState>;
+    fitToView(fit?: FileViewerFitMode | FileViewerFitOptions): Promise<FileViewerFitResult>;
     getZoomState(): FileViewerZoomState;
     getViewState(): FileViewerViewState | null;
     applyViewState(state: FileViewerViewState, options?: FileViewerApplyViewStateOptions): Promise<FileViewerViewState | null>;

package/dist/features/document/dom/providers.js

@@ -13,6 +13,7 @@ export const unregisterFileViewerSearchProvider = (host) => {
     delete host.__flyfishViewerSearchProvider;
 };
 export const findFileViewerSearchProvider = (root) => {
+    var _a;
     if (!root) {
         return null;
     }
@@ -20,7 +21,7 @@ export const findFileViewerSearchProvider = (root) => {
     if (direct) {
         return direct;
     }
-    const host = root.querySelector('[data-viewer-search-provider]');
+    const host = (_a = root.querySelector) === null || _a === void 0 ? void 0 : _a.call(root, '[data-viewer-search-provider]');
     return host
         ? searchProviderRegistry.get(host) || host.__flyfishViewerSearchProvider || null
         : null;
@@ -39,6 +40,7 @@ export const unregisterFileViewerZoomProvider = (host) => {
     delete host.__flyfishViewerZoomProvider;
 };
 export const findFileViewerZoomProvider = (root) => {
+    var _a;
     if (!root) {
         return null;
     }
@@ -46,7 +48,7 @@ export const findFileViewerZoomProvider = (root) => {
     if (direct) {
         return direct;
     }
-    const host = root.querySelector('[data-viewer-zoom-provider]');
+    const host = (_a = root.querySelector) === null || _a === void 0 ? void 0 : _a.call(root, '[data-viewer-zoom-provider]');
     return host
         ? zoomProviderRegistry.get(host) || host.__flyfishViewerZoomProvider || null
         : null;
@@ -65,6 +67,7 @@ export const unregisterFileViewerViewStateProvider = (host) => {
     delete host.__flyfishViewerViewStateProvider;
 };
 export const findFileViewerViewStateProvider = (root) => {
+    var _a;
     if (!root) {
         return null;
     }
@@ -73,7 +76,7 @@ export const findFileViewerViewStateProvider = (root) => {
     if (direct && root.dataset.viewerViewStateProvider !== 'generic') {
         return direct;
     }
-    const hosts = Array.from(root.querySelectorAll('[data-viewer-view-state-provider]'));
+    const hosts = Array.from(((_a = root.querySelectorAll) === null || _a === void 0 ? void 0 : _a.call(root, '[data-viewer-view-state-provider]')) || []);
     const customHost = hosts.find(host => host.dataset.viewerViewStateProvider !== 'generic');
     const genericHost = hosts.find(host => host.dataset.viewerViewStateProvider === 'generic');
     const host = customHost || genericHost;

package/dist/features/document/fit.d.ts

@@ -0,0 +1,46 @@
+import type { FileViewerFitMode, FileViewerFitOptions, FileViewerFitRequest, FileViewerFitResize, FileViewerFitResult, FileViewerViewState, FileViewerViewStateChangeSource } from '../../contracts/types';
+export declare const FILE_VIEWER_FIT_MODES: readonly ["auto", "contain", "cover", "width", "height", "actual", "scale-down"];
+export declare const FILE_VIEWER_FIT_RESIZE_MODES: readonly ["until-interaction", "always", "initial"];
+export interface NormalizedFileViewerFitOptions extends Required<Pick<FileViewerFitOptions, 'mode' | 'resize' | 'padding'>> {
+    minScale?: number;
+    maxScale?: number;
+}
+export interface ResolveFileViewerFitScaleInput {
+    mode: FileViewerFitMode;
+    viewportWidth: number;
+    viewportHeight: number;
+    contentWidth: number;
+    contentHeight: number;
+    currentScale?: number;
+    minScale?: number;
+    maxScale?: number;
+}
+export interface CreateFileViewerFitControllerOptions {
+    root: () => HTMLElement | null | undefined;
+    enabled?: () => boolean;
+    getFit?: () => FileViewerFitMode | FileViewerFitOptions | null | undefined;
+    onFit?: (result: FileViewerFitResult) => void;
+}
+export interface ApplyInitialFileViewerFitOptions {
+    skip?: boolean;
+}
+export interface RunFileViewerFitOptions {
+    source?: FileViewerViewStateChangeSource;
+    reason?: FileViewerFitRequest['reason'];
+}
+export interface FileViewerFitController {
+    normalize(fit?: FileViewerFitMode | FileViewerFitOptions | null): NormalizedFileViewerFitOptions | null;
+    fit(fit?: FileViewerFitMode | FileViewerFitOptions | null, options?: RunFileViewerFitOptions): Promise<FileViewerFitResult>;
+    applyInitialFit(options?: ApplyInitialFileViewerFitOptions): Promise<FileViewerFitResult>;
+    scheduleFit(reason?: FileViewerFitRequest['reason']): void;
+    observe(): void;
+    markUserInteraction(): void;
+    resetAutoFit(): void;
+    destroy(): void;
+}
+export declare const isFileViewerFitMode: (value: unknown) => value is FileViewerFitMode;
+export declare const isFileViewerFitResize: (value: unknown) => value is FileViewerFitResize;
+export declare const normalizeFileViewerFitOptions: (fit?: FileViewerFitMode | FileViewerFitOptions | null) => NormalizedFileViewerFitOptions | null;
+export declare const resolveFileViewerFitScale: ({ mode, viewportWidth, viewportHeight, contentWidth, contentHeight, currentScale, minScale, maxScale, }: ResolveFileViewerFitScaleInput) => number | undefined;
+export declare const hasFileViewerExplicitInitialViewState: (state?: FileViewerViewState | null) => boolean;
+export declare const createFileViewerFitController: ({ root, enabled, getFit, onFit, }: CreateFileViewerFitControllerOptions) => FileViewerFitController;