@file-viewer/core 3.3.0 → 3.3.1

package/README.en.md

@@ -2,6 +2,8 @@
 
 [English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/core/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/core/README.zh-CN.md)
 
+Framework-neutral TypeScript APIs for browser-side file preview. Build a viewer in Vanilla JavaScript, or use the Vue, React, Svelte and jQuery components with the same loading, search, zoom, page navigation, print and export controls. Files are processed locally, without server-side conversion.
+
 <!-- FILE_VIEWER_PACKAGE_HEADER -->
 <p>
   <a href="https://www.npmjs.com/package/@file-viewer/core"><img src="https://img.shields.io/npm/v/@file-viewer%2Fcore?logo=npm" alt="npm version"></a>
@@ -20,20 +22,22 @@
 
 > ⭐ If File Viewer helps you, please [star the repo on GitHub](https://github.com/flyfish-dev/file-viewer).
 
-Framework-neutral TypeScript foundation for Flyfish File Viewer.
-
-This package is the migration base for the next architecture: one pure TypeScript core package with internal `headless`, `browser`, and `renderers` layers, plus multiple native standard component packages for Vue, React, pure JavaScript, jQuery, and Svelte. Core owns the shared format matrix, source detection, renderer protocol, capability calculation, lifecycle context, operation guards, operation/event/search/location/zoom/print/export contracts, heavy renderer asset manifests, option normalization, pure state models, and framework-neutral browser rendering engine.
+File Viewer has a catalog of 275 file extensions through optional renderers. **This package is the lightweight foundation, not an all-format viewer.** Add only the engines your application needs; stable and experimental support are listed separately in the [format matrix](https://doc.file-viewer.app/guide/formats).
 
-Browser execution belongs inside core only when it remains framework-neutral TypeScript. DOM mounting, the standard browser shell and toolbar, `HTMLElement` traversal, search highlights, zoom provider discovery, print windows, download triggers, Canvas, Worker, and WASM renderers must not depend on Vue, React, Svelte, or any component package. Framework component packages keep their own component lifecycle, public type surface, compatibility defaults, and ecosystem interaction layer while depending on `@file-viewer/core` as the only shared base.
+## Start here
 
-`@file-viewer/core` is the only shared foundation package. It owns the headless contracts plus browser/renderers layers for the direct `createViewer(container, options)` engine, renderer registry, DOM provider registry, print layout helpers, browser asset resolution, and framework-neutral DOM/Canvas/Worker/WASM rendering contracts. Core source is public; the private Gitea aggregate remains available for the complete workspace, unified release automation, sponsorship, and priority support.
-
-Current framework-neutral browser renderers still inside core are limited to the low-cost image path. Spreadsheet rendering has moved to `@file-viewer/renderer-spreadsheet`; CAD rendering has moved to `@file-viewer/renderer-cad`; Typst rendering has moved to `@file-viewer/renderer-typst`; OFD rendering has moved to `@file-viewer/renderer-ofd`; PDF rendering has moved to `@file-viewer/renderer-pdf`; archive rendering has moved to `@file-viewer/renderer-archive`; email rendering has moved to `@file-viewer/renderer-email`; EPUB and UMD ebook rendering has moved to `@file-viewer/renderer-epub`; 3D model rendering has moved to `@file-viewer/renderer-3d`; Draw.io, Excalidraw, Mermaid, and PlantUML rendering has moved to `@file-viewer/renderer-drawing`; audio, video, HLS, and MIDI rendering has moved to `@file-viewer/renderer-media`; code, text, Markdown, patch, and git bundle rendering has moved to `@file-viewer/renderer-text`; Word DOCX/DOC/RTF/ODT rendering has moved to `@file-viewer/renderer-word`; PowerPoint rendering has moved to `@file-viewer/renderer-presentation`; XMind rendering has moved to `@file-viewer/renderer-mindmap`; geospatial rendering has moved to `@file-viewer/renderer-geo`; data asset rendering has moved to `@file-viewer/renderer-data`; EDA rendering and parsing has moved to `@file-viewer/renderer-eda`. Core-only installs now avoid direct OFD, PDF, Word, Spreadsheet, PPTX, CAD, Typst, XMind, Geo, media, 3D, drawing, archive, email, EPUB, UMD, data asset, EDA, `ofd-xml-parser`, `jszip`, `pdfjs-dist`, `styled-exceljs`, `e-virt-table`, `tinycolor2`, `@flyfish-dev/cad-viewer`, `@myriaddreamin/*`, `highlight.js`, `marked`, `diff2html`, `pako`, `mermaid`, `plantuml-encoder`, `@panzoom/panzoom`, `hls.js`, `@tonejs/midi`, `three`, `@excalidraw/excalidraw`, `roughjs`, `libarchive.js`, `postal-mime`, `@kenjiuno/msgreader`, `epubjs`, `ag-psd`, `sql.js`, `hyparquet`, `avsc`, and `cfb` engine dependencies.
+- [Create a configured application](https://doc.file-viewer.app/guide/cli): `npm create file-viewer@latest my-viewer`.
+- [Use a Web Component](https://doc.file-viewer.app/guide/quickstart-web), or choose a [framework integration](https://github.com/flyfish-dev/file-viewer#readme).
+- For a custom integration, use `core/headless` for metadata and contracts, or `core/browser` for DOM rendering. PDF and Office require an explicit renderer or preset and local runtime assets.
 
 ```bash
 npm install @file-viewer/core
 ```
 
+## Browser source feedback (unreleased)
+
+The browser `mountViewer` shell shows localized download feedback while buffering a URL, then reading feedback until the renderer takes over. File and buffer inputs use reading feedback. The status follows the configured locale/theme, reports acquisition failures, and is cleared when a source is replaced or the viewer is destroyed.
+
 ## 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.
@@ -71,10 +75,7 @@ const pdfAssets = resolveFileViewerRendererAssets('pdf', {
 Use `@file-viewer/core/browser` when a native component package or pure browser integration needs the shared browser shell and toolbar, direct DOM engine, renderer registry, search/zoom providers, print/export adapters, and framework-neutral Canvas/Worker/WASM renderers.
 
 ```ts
-import {
-  createViewer,
-  coreBrowserRendererHandlers
-} from '@file-viewer/core/browser'
+import { createViewer } from '@file-viewer/core/browser'
 
 const viewer = createViewer(document.querySelector('#viewer')!, {
   options: {
@@ -83,7 +84,8 @@ const viewer = createViewer(document.querySelector('#viewer')!, {
   }
 })
 
-await viewer.load({ url: '/files/report.pdf' })
+// Images use the built-in renderer; document formats need an optional preset.
+await viewer.load({ url: '/files/photo.png' })
 ```
 
 Zoom buttons keep their positions and become disabled at their limits. Configure the existing `toolbar.items` map to hide reset controls while retaining the `resetZoom()` API. Set `pdf.zoomToolbar` to `false` to hide the PDF renderer's zoom group while keeping its page navigation and rotation controls:
@@ -149,8 +151,6 @@ Public source repositories:
 - GitHub: https://github.com/flyfish-dev/file-viewer-core
 - Gitee: https://gitee.com/flyfish-dev/file-viewer-core
 
-The GitHub/Gitee repositories are distributed public source packages. The private Gitea aggregate remains useful for the complete workspace, release automation, integration history, sponsorship, and priority support.
-
 License: Apache-2.0. For second development or commercial use, keep clear Flyfish Viewer attribution and contribute shared compatibility improvements where possible.
 
 ## Formats and related packages

package/README.md

@@ -2,6 +2,8 @@
 
 [English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/core/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/core/README.zh-CN.md)
 
+Framework-neutral TypeScript APIs for browser-side file preview. Build a viewer in Vanilla JavaScript, or use the Vue, React, Svelte and jQuery components with the same loading, search, zoom, page navigation, print and export controls. Files are processed locally, without server-side conversion.
+
 <!-- FILE_VIEWER_PACKAGE_HEADER -->
 <p>
   <a href="https://www.npmjs.com/package/@file-viewer/core"><img src="https://img.shields.io/npm/v/@file-viewer%2Fcore?logo=npm" alt="npm version"></a>
@@ -20,20 +22,22 @@
 
 > ⭐ If File Viewer helps you, please [star the repo on GitHub](https://github.com/flyfish-dev/file-viewer).
 
-Framework-neutral TypeScript foundation for Flyfish File Viewer.
-
-This package is the migration base for the next architecture: one pure TypeScript core package with internal `headless`, `browser`, and `renderers` layers, plus multiple native standard component packages for Vue, React, pure JavaScript, jQuery, and Svelte. Core owns the shared format matrix, source detection, renderer protocol, capability calculation, lifecycle context, operation guards, operation/event/search/location/zoom/print/export contracts, heavy renderer asset manifests, option normalization, pure state models, and framework-neutral browser rendering engine.
+File Viewer has a catalog of 275 file extensions through optional renderers. **This package is the lightweight foundation, not an all-format viewer.** Add only the engines your application needs; stable and experimental support are listed separately in the [format matrix](https://doc.file-viewer.app/guide/formats).
 
-Browser execution belongs inside core only when it remains framework-neutral TypeScript. DOM mounting, the standard browser shell and toolbar, `HTMLElement` traversal, search highlights, zoom provider discovery, print windows, download triggers, Canvas, Worker, and WASM renderers must not depend on Vue, React, Svelte, or any component package. Framework component packages keep their own component lifecycle, public type surface, compatibility defaults, and ecosystem interaction layer while depending on `@file-viewer/core` as the only shared base.
+## Start here
 
-`@file-viewer/core` is the only shared foundation package. It owns the headless contracts plus browser/renderers layers for the direct `createViewer(container, options)` engine, renderer registry, DOM provider registry, print layout helpers, browser asset resolution, and framework-neutral DOM/Canvas/Worker/WASM rendering contracts. Core source is public; the private Gitea aggregate remains available for the complete workspace, unified release automation, sponsorship, and priority support.
-
-Current framework-neutral browser renderers still inside core are limited to the low-cost image path. Spreadsheet rendering has moved to `@file-viewer/renderer-spreadsheet`; CAD rendering has moved to `@file-viewer/renderer-cad`; Typst rendering has moved to `@file-viewer/renderer-typst`; OFD rendering has moved to `@file-viewer/renderer-ofd`; PDF rendering has moved to `@file-viewer/renderer-pdf`; archive rendering has moved to `@file-viewer/renderer-archive`; email rendering has moved to `@file-viewer/renderer-email`; EPUB and UMD ebook rendering has moved to `@file-viewer/renderer-epub`; 3D model rendering has moved to `@file-viewer/renderer-3d`; Draw.io, Excalidraw, Mermaid, and PlantUML rendering has moved to `@file-viewer/renderer-drawing`; audio, video, HLS, and MIDI rendering has moved to `@file-viewer/renderer-media`; code, text, Markdown, patch, and git bundle rendering has moved to `@file-viewer/renderer-text`; Word DOCX/DOC/RTF/ODT rendering has moved to `@file-viewer/renderer-word`; PowerPoint rendering has moved to `@file-viewer/renderer-presentation`; XMind rendering has moved to `@file-viewer/renderer-mindmap`; geospatial rendering has moved to `@file-viewer/renderer-geo`; data asset rendering has moved to `@file-viewer/renderer-data`; EDA rendering and parsing has moved to `@file-viewer/renderer-eda`. Core-only installs now avoid direct OFD, PDF, Word, Spreadsheet, PPTX, CAD, Typst, XMind, Geo, media, 3D, drawing, archive, email, EPUB, UMD, data asset, EDA, `ofd-xml-parser`, `jszip`, `pdfjs-dist`, `styled-exceljs`, `e-virt-table`, `tinycolor2`, `@flyfish-dev/cad-viewer`, `@myriaddreamin/*`, `highlight.js`, `marked`, `diff2html`, `pako`, `mermaid`, `plantuml-encoder`, `@panzoom/panzoom`, `hls.js`, `@tonejs/midi`, `three`, `@excalidraw/excalidraw`, `roughjs`, `libarchive.js`, `postal-mime`, `@kenjiuno/msgreader`, `epubjs`, `ag-psd`, `sql.js`, `hyparquet`, `avsc`, and `cfb` engine dependencies.
+- [Create a configured application](https://doc.file-viewer.app/guide/cli): `npm create file-viewer@latest my-viewer`.
+- [Use a Web Component](https://doc.file-viewer.app/guide/quickstart-web), or choose a [framework integration](https://github.com/flyfish-dev/file-viewer#readme).
+- For a custom integration, use `core/headless` for metadata and contracts, or `core/browser` for DOM rendering. PDF and Office require an explicit renderer or preset and local runtime assets.
 
 ```bash
 npm install @file-viewer/core
 ```
 
+## Browser source feedback (unreleased)
+
+The browser `mountViewer` shell shows localized download feedback while buffering a URL, then reading feedback until the renderer takes over. File and buffer inputs use reading feedback. The status follows the configured locale/theme, reports acquisition failures, and is cleared when a source is replaced or the viewer is destroyed.
+
 ## 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.
@@ -71,10 +75,7 @@ const pdfAssets = resolveFileViewerRendererAssets('pdf', {
 Use `@file-viewer/core/browser` when a native component package or pure browser integration needs the shared browser shell and toolbar, direct DOM engine, renderer registry, search/zoom providers, print/export adapters, and framework-neutral Canvas/Worker/WASM renderers.
 
 ```ts
-import {
-  createViewer,
-  coreBrowserRendererHandlers
-} from '@file-viewer/core/browser'
+import { createViewer } from '@file-viewer/core/browser'
 
 const viewer = createViewer(document.querySelector('#viewer')!, {
   options: {
@@ -83,7 +84,8 @@ const viewer = createViewer(document.querySelector('#viewer')!, {
   }
 })
 
-await viewer.load({ url: '/files/report.pdf' })
+// Images use the built-in renderer; document formats need an optional preset.
+await viewer.load({ url: '/files/photo.png' })
 ```
 
 Zoom buttons keep their positions and become disabled at their limits. Configure the existing `toolbar.items` map to hide reset controls while retaining the `resetZoom()` API. Set `pdf.zoomToolbar` to `false` to hide the PDF renderer's zoom group while keeping its page navigation and rotation controls:
@@ -149,8 +151,6 @@ Public source repositories:
 - GitHub: https://github.com/flyfish-dev/file-viewer-core
 - Gitee: https://gitee.com/flyfish-dev/file-viewer-core
 
-The GitHub/Gitee repositories are distributed public source packages. The private Gitea aggregate remains useful for the complete workspace, release automation, integration history, sponsorship, and priority support.
-
 License: Apache-2.0. For second development or commercial use, keep clear Flyfish Viewer attribution and contribute shared compatibility improvements where possible.
 
 ## Formats and related packages

package/README.zh-CN.md

@@ -34,6 +34,10 @@ Current framework-neutral browser renderers still inside core are limited to the
 npm install @file-viewer/core
 ```
 
+## 浏览器源加载反馈（未发布）
+
+浏览器 `mountViewer` 在缓冲 URL 时显示本地化的下载提示，随后显示读取提示，直至渲染器接管。File 和 buffer 输入显示读取提示。状态遵循配置的语言和主题，展示获取失败，并在切源或销毁时清理。
+
 ## 渲染前预检
 
 `precheckFileViewerSource()` 不会创建 viewer，也不会加载重型 renderer。它先检查当前扩展名是否在能力范围内，并对 PDF、OpenXML / OpenDocument、旧版 OLE Office、RTF 等格式执行签名或包结构检查。`valid: null` 明确表示该格式只有能力检查、没有做完整解析；真实 renderer 仍是畸形文件的最终判断者。

package/dist/assets.d.ts

@@ -1,2 +1,2 @@
-export * from "./platform/assets.js";
-export type * from "./platform/assets.js";
+export * from './platform/assets.js';
+export type * from './platform/assets.js';

package/dist/assets.js

@@ -1 +1,5 @@
-export * from "./platform/assets.js";
+// Public subpath facade for `@file-viewer/core/assets`.
+//
+// Asset resolution belongs to the platform layer, but this root-level file is
+// intentionally kept as the stable package export declared in package.json.
+export * from './platform/assets.js';

package/dist/browser/controller.d.ts

@@ -1,4 +1,4 @@
-import { type FileViewerAiOptions, type FileViewerApplyViewStateOptions, type FileViewerArchiveOptions, type FileViewerCadOptions, type FileViewerDocxOptions, type FileViewerDocumentAnchor, type FileViewerDocumentChunk, type FileViewerEvent, type FileViewerEventHandler, type FileViewerEventType, type FileViewerFileRef, type FileViewerFitMode, type FileViewerFitOptions, type FileViewerFitResult, type FileViewerInstance, type FileViewerLifecycleContext, type FileViewerOperationAvailability, type FileViewerOptions, type FileViewerPdfOptions, type FileViewerPresentationOptions, type FileViewerSpreadsheetOptions, type FileViewerPublicApi, type FileViewerSearchOptions, type FileViewerSearchState, type FileViewerThemeMode, type FileViewerToolbarOptions, type FileViewerToolbarPosition, type FileViewerTypstOptions, type FileViewerUiDensity, type FileViewerUiOptions, type FileViewerViewState, type FileViewerWatermarkOptions, type FileViewerPrintOptions, type FileViewerZoomState, type RendererRegistry } from "../index.js";
+import { type FileViewerAiOptions, type FileViewerApplyViewStateOptions, type FileViewerArchiveOptions, type FileViewerCadOptions, type FileViewerDocxOptions, type FileViewerDocumentAnchor, type FileViewerDocumentChunk, type FileViewerEvent, type FileViewerEventHandler, type FileViewerEventType, type FileViewerFileRef, type FileViewerFitMode, type FileViewerFitOptions, type FileViewerFitResult, type FileViewerInstance, type FileViewerLifecycleContext, type FileViewerOperationAvailability, type FileViewerOptions, type FileViewerPdfOptions, type FileViewerPresentationOptions, type FileViewerSpreadsheetOptions, type FileViewerPublicApi, type FileViewerSearchOptions, type FileViewerSearchState, type FileViewerThemeMode, type FileViewerToolbarOptions, type FileViewerToolbarPosition, type FileViewerTypstOptions, type FileViewerUiDensity, type FileViewerUiOptions, type FileViewerViewState, type FileViewerWatermarkOptions, type FileViewerPrintOptions, type FileViewerZoomState, type RendererRegistry } from '../index.js';
 export type FileRef = FileViewerFileRef;
 export type ViewerWatermarkOptions = FileViewerWatermarkOptions;
 export type ViewerToolbarPosition = FileViewerToolbarPosition;
@@ -34,6 +34,7 @@ export interface ViewerState {
     search: FileViewerSearchState | null;
     zoom: FileViewerZoomState | null;
     location: FileViewerDocumentAnchor | null;
+    /** Added in 2.2; optional so existing state fixtures remain source-compatible. */
     viewState?: FileViewerViewState | null;
 }
 export type ViewerStateListener = (state: ViewerState, event?: ViewerEvent) => void;

package/dist/browser/controller.js

@@ -1,7 +1,8 @@
-import { appendFileViewerStyle, cloneFileViewerViewState, applyFileViewerZoomAvailability, createViewer, isFileViewerShadowRoot, normalizeFileViewerUiDensity, normalizeFileViewerTheme, normalizeFileViewerStyleIsolation, syncFileViewerRenderSurfaceBackground, } from "../index.js";
-import { DEFAULT_FILE_VIEWER_SOURCE_FILENAME, createFileViewerTranslator, getExtension, normalizeFileViewerSourceUrl, hasVisibleFileViewerToolbarActions, isFileViewerZoomButtonDisabled, normalizeFileViewerToolbar, normalizeFilename, readFileViewerBuffer, resolveFileViewerSourceFilename, resolveFileViewerRemoteSourcePlan, resolveFileViewerColorScheme, resolveFileViewerToolbarOrder, resolveFileViewerToolbarPosition, resolveVisibleFileViewerToolbar, toggleFileViewerColorScheme, wrapFileViewerFileRef, } from "../index.js";
-import { resolveFileViewerToolbarZoomButtons } from "../lifecycle/operations.js";
-import { createToolbarFocusRestorer } from "./toolbar-focus.js";
+import { appendFileViewerStyle, cloneFileViewerViewState, applyFileViewerZoomAvailability, createViewer, isFileViewerShadowRoot, normalizeFileViewerUiDensity, normalizeFileViewerTheme, normalizeFileViewerStyleIsolation, syncFileViewerRenderSurfaceBackground, } from '../index.js';
+import { DEFAULT_FILE_VIEWER_SOURCE_FILENAME, createFileViewerTranslator, getExtension, normalizeFileViewerSourceUrl, hasVisibleFileViewerToolbarActions, isFileViewerZoomButtonDisabled, normalizeFileViewerToolbar, normalizeFilename, readFileViewerBuffer, resolveFileViewerSourceFilename, resolveFileViewerRemoteSourcePlan, resolveFileViewerColorScheme, resolveFileViewerToolbarOrder, resolveFileViewerToolbarPosition, resolveVisibleFileViewerToolbar, toggleFileViewerColorScheme, wrapFileViewerFileRef, } from '../index.js';
+import { resolveFileViewerToolbarZoomButtons } from '../lifecycle/operations.js';
+import { createToolbarFocusRestorer } from './toolbar-focus.js';
+import { createViewerSourceFeedback } from './source-feedback.js';
 const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'undefined';
 const hasSource = (options = {}) => {
     return !!(options.url || options.file || options.buffer);
@@ -15,6 +16,8 @@ const toViewerSourceInput = (options = {}) => ({
     type: options.type,
     size: options.size,
 });
+// These options feed renderer selection or rendering itself. Viewer chrome,
+// fitting, watermark, and operation callbacks update in place instead.
 const RENDER_AFFECTING_VIEWER_OPTION_KEYS = [
     'theme',
     'rendererMode',
@@ -116,26 +119,28 @@ const resolveViewerSourceFilename = (source) => {
     }), source.type ? `preview.${source.type}` : DEFAULT_FILE_VIEWER_SOURCE_FILENAME);
 };
 const resolveViewerLoadSource = async (source, options = {}) => {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     const filename = resolveViewerSourceFilename(source);
     const type = source.type || getExtension(filename);
     if (source.buffer) {
+        (_a = options.onPhase) === null || _a === void 0 ? void 0 : _a.call(options, 'reading');
         return {
             buffer: source.buffer,
             filename,
             type,
-            size: (_a = source.size) !== null && _a !== void 0 ? _a : source.buffer.byteLength,
+            size: (_b = source.size) !== null && _b !== void 0 ? _b : source.buffer.byteLength,
             url: source.url,
         };
     }
     if (source.file) {
+        (_c = options.onPhase) === null || _c === void 0 ? void 0 : _c.call(options, 'reading');
         const file = wrapFileViewerFileRef(source.file, filename);
         return {
             file,
             buffer: await readFileViewerBuffer(file),
             filename: file.name || filename,
             type: type || getExtension(file.name),
-            size: (_b = source.size) !== null && _b !== void 0 ? _b : file.size,
+            size: (_d = source.size) !== null && _d !== void 0 ? _d : file.size,
             url: source.url,
         };
     }
@@ -144,9 +149,13 @@ const resolveViewerLoadSource = async (source, options = {}) => {
             url: source.url, filename, type,
             pageHref: options.pageHref, streaming: options.streaming,
         });
+        // A supplied transport owns authentication/acquisition and keeps its normal
+        // buffered contract. Only the default PDF URL path defers bytes to PDF.js.
         if (!options.fetchFile && options.acceptsPdfUrl && plan.streamPdf) {
+            (_e = options.onPhase) === null || _e === void 0 ? void 0 : _e.call(options, 'streamingPdf');
             return { url: plan.url, filename: plan.filename, type: plan.extension, size: source.size };
         }
+        (_f = options.onPhase) === null || _f === void 0 ? void 0 : _f.call(options, 'downloading');
         const fileRef = await (options.fetchFile || defaultFetchFile)({
             url: source.url,
             signal: options.signal,
@@ -156,12 +165,13 @@ const resolveViewerLoadSource = async (source, options = {}) => {
             throw new Error('Downloaded file is empty.');
         }
         const file = wrapFileViewerFileRef(fileRef, filename);
+        (_g = options.onPhase) === null || _g === void 0 ? void 0 : _g.call(options, 'reading');
         return {
             file,
             buffer: await readFileViewerBuffer(file),
             filename: file.name || filename,
             type: type || getExtension(file.name),
-            size: (_c = source.size) !== null && _c !== void 0 ? _c : file.size,
+            size: (_h = source.size) !== null && _h !== void 0 ? _h : file.size,
             url: source.url,
         };
     }
@@ -306,6 +316,9 @@ const DEFAULT_TOOLBAR_ZOOM_STATE = {
     canZoomOut: false,
     canReset: false,
 };
+// A ShadowRoot cannot be detached. Track the exact roots created on viewer
+// hosts so a later light-DOM remount can expose its children through a slot,
+// without mistaking and clearing a ShadowRoot owned by the host application.
 const ownedViewerShadowRoots = new WeakMap();
 const WEB_VIEWER_STYLE = `
 :host,.file-viewer-web-shell{display:block;width:100%;height:100%;min-width:0;min-height:0;contain:content;--file-viewer-bg:transparent;--file-viewer-content-bg:transparent;--file-viewer-text:#172033;--file-viewer-muted:#607282;--file-viewer-font:14px/1.45 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;--file-viewer-border:rgba(20,35,53,.08);--file-viewer-toolbar-bg:rgba(255,255,255,.92);--file-viewer-toolbar-border:rgba(20,35,53,.06);--file-viewer-toolbar-shadow:0 18px 44px rgba(15,23,42,.16);--file-viewer-toolbar-radius:999px;--file-viewer-toolbar-gap:6px;--file-viewer-toolbar-min-height:45px;--file-viewer-toolbar-padding:6px 10px;--file-viewer-toolbar-floating-min-height:42px;--file-viewer-toolbar-floating-padding:6px;--file-viewer-toolbar-floating-offset:16px;--file-viewer-group-bg:rgba(20,35,53,.035);--file-viewer-group-border:rgba(20,35,53,.08);--file-viewer-group-gap:2px;--file-viewer-group-padding:2px;--file-viewer-button-color:#40546a;--file-viewer-button-hover-bg:rgba(33,163,102,.1);--file-viewer-button-hover-color:#16774c;--file-viewer-button-disabled-color:#aab5c0;--file-viewer-button-radius:8px;--file-viewer-button-min-width:42px;--file-viewer-button-height:30px;--file-viewer-button-padding:0 10px;--file-viewer-icon-button-size:30px;--file-viewer-zoom-meter-min-width:48px;--file-viewer-zoom-meter-padding:0 8px;--file-viewer-floating-button-min-width:48px;--file-viewer-floating-button-height:32px;--file-viewer-floating-icon-button-size:32px;--file-viewer-floating-zoom-meter-min-width:54px;--file-viewer-search-input-height:30px;--file-viewer-search-input-padding:0 10px;--file-viewer-search-button-min-width:32px;--file-viewer-search-button-padding:0 8px;--file-viewer-search-count-min-width:42px;--file-viewer-floating-search-input-height:32px;--file-viewer-focus-ring:rgba(31,157,103,.22);--file-viewer-z-toolbar:20;--file-viewer-z-floating-toolbar:30}
@@ -314,6 +327,9 @@ const WEB_VIEWER_STYLE = `
 .file-viewer-web-shell{position:relative;width:100%;height:100%;min-height:0;display:flex;flex-direction:column;overflow:hidden;background:var(--file-viewer-render-surface-background,var(--file-viewer-bg));color:var(--file-viewer-text);font:var(--file-viewer-font);letter-spacing:0;box-sizing:border-box;contain:content}
 .file-viewer-web-shell[data-viewer-density="compact"]{--file-viewer-toolbar-gap:3px;--file-viewer-toolbar-min-height:34px;--file-viewer-toolbar-padding:3px 5px;--file-viewer-toolbar-floating-min-height:32px;--file-viewer-toolbar-floating-padding:3px;--file-viewer-toolbar-floating-offset:10px;--file-viewer-group-gap:2px;--file-viewer-group-padding:2px;--file-viewer-button-radius:6px;--file-viewer-button-min-width:34px;--file-viewer-button-height:26px;--file-viewer-button-padding:0 6px;--file-viewer-icon-button-size:26px;--file-viewer-zoom-meter-min-width:42px;--file-viewer-zoom-meter-padding:0 5px;--file-viewer-floating-button-min-width:38px;--file-viewer-floating-button-height:28px;--file-viewer-floating-icon-button-size:28px;--file-viewer-floating-zoom-meter-min-width:46px;--file-viewer-search-input-height:26px;--file-viewer-search-input-padding:0 8px;--file-viewer-search-button-min-width:28px;--file-viewer-search-button-padding:0 6px;--file-viewer-search-count-min-width:36px;--file-viewer-floating-search-input-height:28px}
 .file-viewer-web-content{position:relative;flex:1 1 auto;min-height:0;min-width:0;overflow:auto;overscroll-behavior:contain;background:var(--file-viewer-render-surface-background,var(--file-viewer-content-bg))}
+.file-viewer-web-source-status{position:absolute;inset:0;z-index:10;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:12px;padding:24px;background:var(--file-viewer-toolbar-bg);color:var(--file-viewer-text);text-align:center;overflow:auto}
+.file-viewer-web-source-status p{margin:0;max-width:560px;white-space:pre-wrap;overflow-wrap:anywhere}
+.file-viewer-web-source-status strong{font-size:18px}
 .file-viewer-web-toolbar{flex:0 0 auto;min-height:var(--file-viewer-toolbar-min-height);display:inline-flex;align-items:center;justify-content:flex-end;gap:var(--file-viewer-toolbar-gap);padding:var(--file-viewer-toolbar-padding);border-bottom:1px solid var(--file-viewer-toolbar-border);background:var(--file-viewer-toolbar-bg);box-sizing:border-box;z-index:var(--file-viewer-z-toolbar)}
 .file-viewer-web-toolbar[hidden]{display:none!important}
 .file-viewer-web-toolbar[data-toolbar-position="top-center"]{justify-content:center}
@@ -406,14 +422,26 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
     }
     else if (shouldUseShadowRoot && canAttachShadowRoot) {
         try {
+            // The viewer owns this root even when its host already lives inside a
+            // customer's ShadowRoot. Reusing the ancestor would let that component's
+            // resets override the toolbar and would make our :host rules mutate the
+            // customer's outer custom element.
+            // Delegated focus makes Safari taps on renderer controls focus the first
+            // toolbar input instead, triggering keyboard zoom and viewport scrolling.
             renderRoot = container.attachShadow({ mode: 'open' });
             ownedViewerShadowRoots.set(container, renderRoot);
         }
         catch {
+            // Some HTMLElement subclasses cannot host Shadow DOM, and a closed root
+            // is intentionally invisible through `shadowRoot`. Keep the legacy
+            // scoped path usable instead of surfacing a raw NotSupportedError.
             renderRoot = container;
         }
     }
     else if (existingHostShadowRoot && !hasOwnedHostShadowRoot) {
+        // The application owns this root. Preserve every existing child and mount
+        // the viewer in a dedicated boundary. Shadow mode gets a nested root so
+        // customer resets in the outer component cannot reach the viewer.
         mountBoundary = documentRef.createElement('div');
         mountBoundary.dataset.fileViewerMountBoundary = 'true';
         existingHostShadowRoot.appendChild(mountBoundary);
@@ -430,6 +458,9 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
         }
     }
     else if (!shouldUseShadowRoot && hasOwnedHostShadowRoot && existingHostShadowRoot) {
+        // Light-DOM children of a shadow host are not painted unless the root has
+        // a slot. Keep the immutable owned root, but project the real light-DOM
+        // viewer so host selectors and legacy deep overrides work as documented.
         const slot = documentRef.createElement('slot');
         slot.dataset.fileViewerLightDomSlot = 'true';
         existingHostShadowRoot.replaceChildren(slot);
@@ -437,6 +468,9 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
     }
     renderRoot.replaceChildren();
     const styleHandle = appendFileViewerStyle(renderRoot, WEB_VIEWER_STYLE, {
+        // Adopt only into a root owned by the viewer. Adopting into an ancestor
+        // ShadowRoot would leak toolbar selectors and apply :host rules to the
+        // customer's custom element.
         adoptedStyleSheet: isFileViewerShadowRoot(renderRoot),
     });
     const shell = documentRef.createElement('div');
@@ -462,7 +496,10 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
     let currentSource = hasSource(currentOptions)
         ? toViewerSourceInput(currentOptions)
         : null;
-    let abortController = null;
+    let sourceRequest = null;
+    let renderingRequest = null;
+    let lifecycleVersion = -1;
+    const updateSourceFeedback = createViewerSourceFeedback(shell, contentEl);
     const listeners = new Set();
     const state = {
         loading: false,
@@ -647,6 +684,12 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
                 group.appendChild(createReadonlyMeter(documentRef, zoomState.label, 'file-viewer-web-zoom-meter'));
             }
             if (zoomButtons.zoomReset) {
+                // Placed before the zoom-in button (not after) so that toggling this
+                // button's visibility never shifts the zoom-in button's position: the
+                // toolbar group is right-aligned, and both icon buttons share the same
+                // width, so inserting "1:1" after "+" would make it land exactly on
+                // top of the previous "+" position, turning a repeated zoom-in click
+                // into an accidental reset (see GitHub issue #88).
                 const button = createButton(documentRef, '1:1', 'file-viewer-web-icon-button', () => controller === null || controller === void 0 ? void 0 : controller.resetZoom());
                 button.title = t('toolbar.zoomReset');
                 button.dataset.viewerToolbarKey = 'zoom-reset';
@@ -804,11 +847,20 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
         var _a;
         const snapshot = snapshotState();
         renderToolbar();
+        updateSourceFeedback((sourceRequest === null || sourceRequest === void 0 ? void 0 : sourceRequest.pending) ? sourceRequest.phase : null, state.error, currentSource ? currentSource.type || getExtension(resolveViewerSourceFilename(currentSource)) : '', currentOptions.options, Boolean((sourceRequest === null || sourceRequest === void 0 ? void 0 : sourceRequest.rendering) && contentEl.querySelector('.file-viewer-render-error')));
         (_a = currentOptions.onStateChange) === null || _a === void 0 ? void 0 : _a.call(currentOptions, snapshot, event);
         listeners.forEach(listener => listener(snapshot, event));
     };
     const applyViewerEvent = (event) => {
         var _a;
+        if (disposed || sourceRequest !== renderingRequest)
+            return;
+        if (event.type === 'load-start' || event.type === 'load-complete' ||
+            event.type === 'unload-start' || event.type === 'unload-complete') {
+            if (event.payload.version < lifecycleVersion)
+                return;
+            lifecycleVersion = event.payload.version;
+        }
         state.lastEvent = event;
         if (event.type === 'load-start') {
             state.loading = true;
@@ -819,6 +871,8 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
             searchDraft = '';
         }
         else if (event.type === 'load-complete') {
+            if (sourceRequest)
+                sourceRequest.pending = false;
             state.loading = false;
             state.ready = true;
             state.lifecycle = event.payload;
@@ -829,7 +883,7 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
             state.lifecycle = event.payload;
         }
         else if (event.type === 'unload-complete') {
-            state.loading = false;
+            state.loading = Boolean(sourceRequest === null || sourceRequest === void 0 ? void 0 : sourceRequest.pending);
             state.ready = false;
             state.lifecycle = event.payload;
         }
@@ -860,21 +914,27 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
     (_e = viewerColorSchemeQuery === null || viewerColorSchemeQuery === void 0 ? void 0 : viewerColorSchemeQuery.addEventListener) === null || _e === void 0 ? void 0 : _e.call(viewerColorSchemeQuery, 'change', handleViewerColorSchemeChange);
     renderToolbar();
     const cancel = () => {
-        abortController === null || abortController === void 0 ? void 0 : abortController.abort();
-        abortController = null;
+        var _a;
+        const previous = sourceRequest;
+        sourceRequest = null;
+        (_a = previous === null || previous === void 0 ? void 0 : previous.abort) === null || _a === void 0 ? void 0 : _a.abort();
     };
     const loadSource = async (nextSource) => {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         cancel();
         currentSource = nextSource;
-        abortController = typeof AbortController !== 'undefined' ? new AbortController() : null;
-        const controller = abortController;
+        const request = {
+            abort: typeof AbortController !== 'undefined' ? new AbortController() : null,
+            phase: 'reading', pending: true, rendering: false,
+        };
+        sourceRequest = request;
+        const isCurrent = () => { var _a; return !disposed && sourceRequest === request && !((_a = request.abort) === null || _a === void 0 ? void 0 : _a.signal.aborted); };
         try {
             state.loading = true;
             state.error = null;
             notifyState();
             await ((_a = instance.prepare) === null || _a === void 0 ? void 0 : _a.call(instance));
-            if (disposed || (controller === null || controller === void 0 ? void 0 : controller.signal.aborted) || abortController !== controller) {
+            if (!isCurrent()) {
                 return null;
             }
             const extension = nextSource.type || getExtension(resolveViewerSourceFilename(nextSource));
@@ -882,29 +942,43 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
             const resolvedSource = await resolveViewerLoadSource(nextSource, {
                 acceptsPdfUrl: (renderer === null || renderer === void 0 ? void 0 : renderer.sourceAccess) === 'stream-preferred' && Boolean(renderer.load),
                 fetchFile: coreOptions.fetchFile,
-                signal: controller === null || controller === void 0 ? void 0 : controller.signal,
-                streaming: (_c = (_b = currentOptions.options) === null || _b === void 0 ? void 0 : _b.pdf) === null || _c === void 0 ? void 0 : _c.streaming,
-                pageHref: (_e = (_d = documentRef.defaultView) === null || _d === void 0 ? void 0 : _d.location) === null || _e === void 0 ? void 0 : _e.href,
+                signal: (_b = request.abort) === null || _b === void 0 ? void 0 : _b.signal,
+                streaming: (_d = (_c = currentOptions.options) === null || _c === void 0 ? void 0 : _c.pdf) === null || _d === void 0 ? void 0 : _d.streaming,
+                pageHref: (_f = (_e = documentRef.defaultView) === null || _e === void 0 ? void 0 : _e.location) === null || _f === void 0 ? void 0 : _f.href,
+                onPhase(phase) {
+                    if (!isCurrent())
+                        return;
+                    request.phase = phase;
+                    updateSourceFeedback(phase, null, extension, currentOptions.options);
+                },
             });
-            if (disposed || (controller === null || controller === void 0 ? void 0 : controller.signal.aborted) || abortController !== controller) {
+            if (!isCurrent()) {
                 return null;
             }
-            return await instance.load(resolvedSource);
+            if (resolvedSource.buffer || resolvedSource.file)
+                request.phase = 'reading';
+            request.rendering = true;
+            renderingRequest = request;
+            notifyState();
+            return await instance.load(resolvedSource, { signal: (_g = request.abort) === null || _g === void 0 ? void 0 : _g.signal });
         }
         catch (error) {
-            if (disposed || (controller === null || controller === void 0 ? void 0 : controller.signal.aborted) || abortController !== controller) {
+            if (!isCurrent()) {
                 return null;
             }
             state.loading = false;
             state.ready = false;
-            state.error = error;
+            state.error = error !== null && error !== void 0 ? error : new Error(createFileViewerTranslator(currentOptions.options)('error.unknown'));
+            request.pending = false;
             notifyState();
-            (_f = coreOptions.onError) === null || _f === void 0 ? void 0 : _f.call(coreOptions, error, nextSource);
+            (_h = coreOptions.onError) === null || _h === void 0 ? void 0 : _h.call(coreOptions, error, nextSource);
             throw error;
         }
         finally {
-            if (abortController === controller) {
-                abortController = null;
+            if (isCurrent() && request.pending) {
+                request.pending = false;
+                state.loading = false;
+                notifyState();
             }
         }
     };
@@ -922,6 +996,9 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
         }
     };
     if (currentSource) {
+        // The initial declarative source has no caller awaiting it. State changes
+        // and the visible error surface remain authoritative without a global
+        // unhandled-rejection event for an expected rendering failure.
         void loadSource(currentSource).catch(() => undefined);
     }
     controller = {
@@ -969,7 +1046,13 @@ export const mountViewer = (container, initialOptions = {}, coreOptions = {}) =>
                 }
             }
             else {
+                cancel();
+                renderingRequest = null;
                 currentSource = null;
+                state.loading = false;
+                state.ready = false;
+                state.error = null;
+                notifyState();
                 await instance.load({ filename: DEFAULT_FILE_VIEWER_SOURCE_FILENAME });
             }
         },

package/dist/browser/source-feedback.d.ts

@@ -0,0 +1,4 @@
+import { type FileViewerI18nInput } from '../i18n/messages.js';
+export type ViewerSourcePhase = 'downloading' | 'reading' | 'streamingPdf';
+/** The shell owns acquisition feedback; renderers retain their own error surface. */
+export declare const createViewerSourceFeedback: (shell: HTMLElement, content: HTMLElement) => (phase: ViewerSourcePhase | null, error: unknown, extension: string, options?: FileViewerI18nInput, rendererHasError?: boolean) => void;

package/dist/browser/source-feedback.js

@@ -0,0 +1,40 @@
+import { createFileViewerTranslator } from '../i18n/messages.js';
+import { createFileViewerErrorState } from '../viewer/state.js';
+/** The shell owns acquisition feedback; renderers retain their own error surface. */
+export const createViewerSourceFeedback = (shell, content) => {
+    let surface = null;
+    let title = null;
+    let message = null;
+    return (phase, error, extension, options, rendererHasError = false) => {
+        content.setAttribute('aria-busy', String(Boolean(phase)));
+        content.toggleAttribute('inert', Boolean(phase));
+        if (!phase && (error == null || rendererHasError)) {
+            surface === null || surface === void 0 ? void 0 : surface.remove();
+            surface = title = message = null;
+            return;
+        }
+        if (!surface) {
+            surface = shell.ownerDocument.createElement('div');
+            surface.className = 'file-viewer-web-source-status';
+            surface.setAttribute('part', 'source-status');
+            title = shell.ownerDocument.createElement('strong');
+            message = shell.ownerDocument.createElement('p');
+            surface.append(title, message);
+            shell.append(surface);
+        }
+        surface.dataset.fileViewerSourceState = phase ? 'loading' : 'error';
+        surface.setAttribute('role', phase ? 'status' : 'alert');
+        surface.setAttribute('aria-live', phase ? 'polite' : 'assertive');
+        surface.setAttribute('aria-atomic', 'true');
+        const failure = phase ? null : createFileViewerErrorState(extension, error, undefined, options);
+        const nextTitle = (failure === null || failure === void 0 ? void 0 : failure.title) || '';
+        const nextMessage = phase
+            ? createFileViewerTranslator(options)(`preview.${phase}`)
+            : failure.message;
+        title.hidden = Boolean(phase);
+        if (title.textContent !== nextTitle)
+            title.textContent = nextTitle;
+        if (message.textContent !== nextMessage)
+            message.textContent = nextMessage;
+    };
+};

package/dist/browser/toolbar-focus.d.ts

@@ -1 +1,2 @@
+/** Preserve the active logical action across state-driven toolbar rebuilds. */
 export declare function createToolbarFocusRestorer(toolbar: HTMLElement, content: HTMLElement): () => (temporarilyUnavailable?: boolean) => void;

package/dist/browser/toolbar-focus.js

@@ -1,3 +1,4 @@
+/** Preserve the active logical action across state-driven toolbar rebuilds. */
 export function createToolbarFocusRestorer(toolbar, content) {
     let pendingKey = null;
     const controls = () => Array.from(toolbar.querySelectorAll('[data-viewer-toolbar-key]'));
@@ -34,6 +35,8 @@ export function createToolbarFocusRestorer(toolbar, content) {
                     target.setSelectionRange(selection[0], selection[1], selection[2] || undefined);
             }
             else {
+                // All actions may be temporarily disabled during a load. Restore only
+                // while the user remains here; moving elsewhere clears this pending key.
                 pendingKey = key;
                 toolbar.tabIndex = -1;
                 toolbar.focus({ preventScroll: true });

package/dist/browser.d.ts

@@ -1,2 +1,2 @@
-export * from "./index.js";
-export * from "./browser/controller.js";
+export * from './index.js';
+export * from './browser/controller.js';

package/dist/browser.js

@@ -1,2 +1,2 @@
-export * from "./index.js";
-export * from "./browser/controller.js";
+export * from './index.js';
+export * from './browser/controller.js';

package/dist/config/options.d.ts

@@ -1,4 +1,4 @@
-import type { FileViewerArchiveOptions, FileViewerCadOptions, FileViewerOptions, FileViewerResolvedThemeMode, FileViewerThemeMode, FileViewerToolbarOptions, FileViewerUiDensity } from "../contracts/types.js";
+import type { FileViewerArchiveOptions, FileViewerCadOptions, FileViewerOptions, FileViewerResolvedThemeMode, FileViewerThemeMode, FileViewerToolbarOptions, FileViewerUiDensity } from '../contracts/types.js';
 export type FileViewerSerializableToolbarOptions = Omit<FileViewerToolbarOptions, 'beforeOperation' | 'beforeDownload' | 'beforePrint' | 'beforeExportHtml'>;
 export type FileViewerSerializableCadOptions = Omit<FileViewerCadOptions, 'workerUrl'> & {
     workerUrl?: string;