@netless/app-presentation 0.1.13-beta.4 → 0.1.14

package/README-zh.md

@@ -32,6 +32,17 @@ install(register, {
 })
 ```
 
+### 依赖边界与本地开发
+
+库代码通过 `import type` 引用 WindowManager 和 White SDK 类型；运行时由宿主通过
+`AppContext` 和 `install(register)` 提供。`install()` 也可以直接接收
+`WindowManager.register`。Fastboard 仅用于集成示例中的房间创建和 UI。
+
+使用 `pnpm install` 安装库构建依赖。运行 Fastboard 示例时，再执行
+`pnpm --dir e2e install`，然后运行 `pnpm dev:e2e`；房间的 `VITE_*` 配置放在
+仓库根目录的 `.env.local`。Fastboard 和教具插件依赖由独立的 `e2e` 私有包管理，
+不会随库发布。库构建会拒绝对宿主包的运行时导入。
+
 ### 将应用插入房间
 
 如果你以 `{ as: 'DocsViewer' }` 的方式安装了这个应用，请调用 [`fastboard.insertDocs()`](https://github.com/netless-io/fastboard#insert-pdf-ppt-and-pptx)。

package/README.md

@@ -34,6 +34,19 @@ install(register, {
 })
 ```
 
+### Dependency boundary and local development
+
+The library imports WindowManager and White SDK types with `import type`; their
+runtime is supplied by the host through `AppContext` and `install(register)`.
+`install()` also accepts `WindowManager.register` directly. Fastboard is only
+needed by the integration demo, where it creates the room and UI.
+
+Install the library build dependencies with `pnpm install`. To run the Fastboard
+demo, also run `pnpm --dir e2e install`, then `pnpm dev:e2e`. Configure its
+`VITE_*` room settings in the repository's `.env.local`. The private `e2e`
+package owns the Fastboard and appliance plugin dependencies and is not published.
+The library build rejects runtime imports of host packages.
+
 ### Insert This App Into Room
 
 Call [`fastboard.insertDocs()`](https://github.com/netless-io/fastboard#insert-pdf-ppt-and-pptx)

package/build.ts

@@ -46,6 +46,20 @@ const lazyload = (): esbuild.Plugin => ({
   }
 })
 
+// Host APIs are provided by AppContext or install(register), never imported at runtime.
+const hostTypesOnly = (): esbuild.Plugin => ({
+  name: 'host-types-only',
+  setup({ onResolve }) {
+    onResolve({
+      filter: /^(?:@netless\/(?:window-manager|fastboard(?:-[^/]+)?|appliance-plugin)|white-web-sdk)(?:\/|$)/,
+    }, args => ({
+      errors: [{
+        text: `Presentation cannot import ${args.path} at runtime. Use import type for host types; keep host runtime imports in e2e.`,
+      }],
+    }))
+  },
+})
+
 fs.rmSync('dist', { recursive: true, force: true })
 
 let bundle = await rollup.rollup({
@@ -62,17 +76,11 @@ let bundle = await rollup.rollup({
         sourcemap: true,
         write: false,
         target: ['es2017'],
-        plugins: [sass(), lazyload()],
+        plugins: [hostTypesOnly(), sass(), lazyload()],
         define: {
           __VERSION__: JSON.stringify(version)
         },
-        external: Object.keys({
-          '@netless/window-manager': '*',
-          '@netless/appliance-plugin': '*',
-          '@netless/fastboard': '*',
-          'white-web-sdk': '*',
-          ...peerDependencies,
-        })
+        external: Object.keys(peerDependencies)
       })
       let code: any, map: any
       for (const { path, text } of outputFiles) {
@@ -98,4 +106,6 @@ code = code.replace(`await import('jspdf')`, `jspdf`)
 fs.writeFileSync('dist/index.global.js', code)
 
 if (process.env.DTS != '0')
-  await dts.build('src/index.ts', 'dist/index.d.ts', { exclude: ['@netless/window-manager'] })
+  await dts.build('src/index.ts', 'dist/index.d.ts', {
+    exclude: ['@netless/window-manager', 'white-web-sdk'],
+  })

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { View, NetlessApp, Size, AppContext, WindowManager } from '@netless/window-manager';
+import { View, NetlessApp, AppContext, WindowManager } from '@netless/window-manager';
+import { Size } from 'white-web-sdk';
 
 /**
  * A combination of {@link Disposer} and {@link IDisposable}.
@@ -276,6 +277,7 @@ interface PresentationConfig {
     readonly pages: PresentationPage[];
     readonly readonly?: boolean;
     readonly thumbnail?: (src: string) => string;
+    readonly onThumbnailError?: (error: unknown) => void;
 }
 /**
  * Standalone presentation slide viewer.
@@ -316,6 +318,7 @@ declare class Presentation implements IDisposable<void> {
     readonly dispose: DisposableStore;
     readonly pages: PresentationPage[];
     readonly preload: Preload;
+    readonly onThumbnailError?: (error: unknown) => void;
     dom: Element | DocumentFragment;
     contentDOM: HTMLDivElement;
     previewDOM: HTMLDivElement;
@@ -429,6 +432,13 @@ declare class Scrollbar {
 }
 
 type Logger = (...data: any[]) => void;
+interface PresentationDiagnosticLogger {
+    info(event: string, payload?: unknown): void;
+    warn(event: string, payload?: unknown): void;
+    error(event: string, error: unknown, payload?: unknown): void;
+    debouncedInfo(event: string, payload?: unknown): void;
+    flush(): void;
+}
 interface PresentationAttributes {
     /** Shared logical camera reference size. New pages are proportionally contained within it. */
     originSize?: Size | null;
@@ -555,6 +565,7 @@ declare const setupBlurThumbnailDegradation: (config: {
     app: Presentation;
     dispose: ReturnType<typeof disposableStore>;
 }) => void;
+declare const createDiagnosticLogger: (context: AppContext) => PresentationDiagnosticLogger;
 declare const NetlessAppPresentation: NetlessApp<PresentationAttributes, {}, PresentationAppOptions, PresentationController> & {
     teardown(context: AppContext): void;
 };
@@ -582,5 +593,5 @@ declare const install: (register: RegisterFn, options?: InstallOptions) => Promi
 
 declare const version: string;
 
-export { NetlessAppPresentation, Presentation, Scrollbar, NetlessAppPresentation as default, install, setupBlurThumbnailDegradation, version };
+export { NetlessAppPresentation, Presentation, Scrollbar, createDiagnosticLogger, NetlessAppPresentation as default, install, setupBlurThumbnailDegradation, version };
 export type { InstallOptions, Logger, PresentationAppOptions, PresentationAttributes, PresentationConfig, PresentationController, PresentationPage, RegisterFn, ScrollbarEventCallback, ScrollbarOption };

package/dist/index.global.js

@@ -1304,6 +1304,7 @@ var NetlessAppPresentation = (function (exports) {
       var _a;
       this.pages = config.pages;
       this.preload = new Preload(this.pages);
+      this.onThumbnailError = config.onThumbnailError;
       if (config.thumbnail)
         this.thumbnail = config.thumbnail;
       this.dispose.add(this.preload);
@@ -1519,12 +1520,16 @@ var NetlessAppPresentation = (function (exports) {
     }
     /** Returns a modified URL that points to the thumbnail image. */
     thumbnail(src) {
+      var _a;
       try {
         const url = new URL(src);
         url.searchParams.set("x-oss-process", "image/resize,l_50");
         return url.toString();
       } catch (err) {
-        console.error(err);
+        try {
+          (_a = this.onThumbnailError) == null ? void 0 : _a.call(this, err);
+        } catch (e) {
+        }
         return src;
       }
     }
@@ -2119,7 +2124,8 @@ var NetlessAppPresentation = (function (exports) {
     const box = context.getBox();
     const boxBlurClass = box.wrapClassName("blur");
     let blurEpisode = false;
-    let reDegradeEnabled = false;
+    let failedThumbnailPageIndex = null;
+    const canReDegrade = () => blurEpisode && failedThumbnailPageIndex !== pageIndex$.value;
     let previewSuspended = false;
     let appliedFocusState = true;
     let logicalFocused = true;
@@ -2176,15 +2182,16 @@ var NetlessAppPresentation = (function (exports) {
         app.suspendPreviewResources();
       }
       const page = pages[pageIndex$.value];
-      if (!page || !hasUsableThumbnail(page) || reDegradeEnabled) {
+      if (!page || !hasUsableThumbnail(page) || canReDegrade()) {
         degrade();
       }
     };
     const restoreFocusedResources = () => {
+      appliedFocusState = true;
       if (!blurEpisode)
         return;
       blurEpisode = false;
-      reDegradeEnabled = false;
+      failedThumbnailPageIndex = null;
       previewSuspended = false;
       restore2();
       app.preload.resume(pageIndex$.value);
@@ -2203,18 +2210,22 @@ var NetlessAppPresentation = (function (exports) {
       return !!(el && el.contains(target));
     };
     const onImgLoad = (ev) => {
-      if (!blurEpisode || !reDegradeEnabled)
+      if (!canReDegrade())
         return;
       if (!ownsTarget(ev.target))
         return;
       degrade();
     };
     const onImgError = (ev) => {
-      if (!blurEpisode || !reDegradeEnabled)
+      var _a;
+      if (!canReDegrade())
         return;
       if (!ownsTarget(ev.target))
         return;
-      reDegradeEnabled = false;
+      const thumbnailURL = (_a = pages[pageIndex$.value]) == null ? void 0 : _a.thumbnail;
+      if (thumbnailURL && resolveImageUrl(ev.target.src) === resolveImageUrl(thumbnailURL)) {
+        failedThumbnailPageIndex = pageIndex$.value;
+      }
     };
     const applyActivity = () => {
       var _a;
@@ -2228,7 +2239,7 @@ var NetlessAppPresentation = (function (exports) {
         restoreFocusedResources();
       } else {
         blurEpisode = true;
-        reDegradeEnabled = true;
+        failedThumbnailPageIndex = null;
         degrade();
         app.preload.pause();
         suspendCachedResources();
@@ -2275,26 +2286,21 @@ var NetlessAppPresentation = (function (exports) {
       document.removeEventListener("error", onImgError, true);
     });
   };
-  var createLogger = (room) => {
-    if (room && room.logger) {
-      return (...args) => room.logger.info(...args);
-    } else {
-      return (...args) => console.log(...args);
-    }
+  var getLogger = (context) => {
+    var _a, _b, _c;
+    return (_c = (_a = context.getWindowManager()) == null ? void 0 : _a.Logger) != null ? _c : (_b = context.getRoom()) == null ? void 0 : _b.logger;
+  };
+  var createLogger = (context) => {
+    return (...args) => {
+      var _a, _b;
+      return (_b = (_a = getLogger(context)) == null ? void 0 : _a.info) == null ? void 0 : _b.call(_a, ...args);
+    };
   };
   var createDiagnosticLogger = (context) => {
-    var _a;
-    const createAppLogger = context.createLogger;
-    if (typeof createAppLogger === "function") {
-      return createAppLogger.call(context, "camera", {
-        debounceTime: 300,
-        maxWaitTime: 2e3
-      });
-    }
-    const roomLogger = (_a = context.getRoom()) == null ? void 0 : _a.logger;
     const prefix = `[Presentation][${context.appId}][camera]`;
     const emit = (level, event, ...data) => {
       try {
+        const roomLogger = getLogger(context);
         const printer = roomLogger == null ? void 0 : roomLogger[level];
         if (typeof printer === "function")
           printer.call(roomLogger, `${prefix}[${event}]`, ...data);
@@ -2359,9 +2365,11 @@ var NetlessAppPresentation = (function (exports) {
         );
       const options = context.getAppOptions() || {};
       const room = context.getRoom();
-      const log = options.log || createLogger(room);
-      const roomLogger = room == null ? void 0 : room.logger;
-      const warn = (...data) => (roomLogger == null ? void 0 : roomLogger.warn) ? roomLogger.warn(...data) : log(...data);
+      const log = options.log || createLogger(context);
+      const warn = (...data) => {
+        var _a2, _b2;
+        return (_b2 = (_a2 = getLogger(context)) == null ? void 0 : _a2.warn) == null ? void 0 : _b2.call(_a2, ...data);
+      };
       const configuredOriginSize = context.storage.state.originSize;
       const originSize = isValidSize(configuredOriginSize) ? {
         width: configuredOriginSize.width,
@@ -2693,10 +2701,14 @@ var NetlessAppPresentation = (function (exports) {
           pageIndex$,
           view,
           options.thumbnail,
-          options.useClipView
+          options.useClipView,
+          (error) => {
+            var _a2, _b2;
+            return (_b2 = (_a2 = getLogger(context)) == null ? void 0 : _a2.error) == null ? void 0 : _b2.call(_a2, "[Presentation] thumbnail URL parsing failed", context.appId, error);
+          }
         )
       );
-      app.contentDOM.dataset.appPresentationVersion = "0.1.13-beta.4";
+      app.contentDOM.dataset.appPresentationVersion = "0.1.14";
       app.scaleDocsToFit = scaleDocsToFit;
       app.log = log;
       app.warn = warn;
@@ -3176,10 +3188,7 @@ var NetlessAppPresentation = (function (exports) {
         );
         if (disposed)
           throw new Error("[Presentation] disposed before setup ready");
-        if (result === "error" && context.waitForActualSetupReady) {
-          throw new Error("[Presentation] setup page image failed to load");
-        }
-        if (result === "error" && !disposed) {
+        if (result === "error") {
           warn("[Presentation] setup page image failed to load; continuing setup");
         }
         return controller;
@@ -3215,13 +3224,14 @@ var NetlessAppPresentation = (function (exports) {
       }
     }
   };
-  function createPresentation(box, pages, jumpPage, pageIndex$, view, thumbnail, useClipView) {
+  function createPresentation(box, pages, jumpPage, pageIndex$, view, thumbnail, useClipView, onThumbnailError) {
     box.mountStyles(style_default);
     const app = new AppPresentation({
       pages,
       readonly: box.readonly,
       jumpPage,
-      thumbnail
+      thumbnail,
+      onThumbnailError
     });
     app.box = box;
     box.mountContent(app.contentDOM);
@@ -3269,11 +3279,12 @@ var NetlessAppPresentation = (function (exports) {
   };
 
   // src/index.ts
-  var version = "0.1.13-beta.4";
+  var version = "0.1.14";
 
   exports.NetlessAppPresentation = NetlessAppPresentation;
   exports.Presentation = Presentation;
   exports.Scrollbar = Scrollbar;
+  exports.createDiagnosticLogger = createDiagnosticLogger;
   exports.default = NetlessAppPresentation;
   exports.install = install;
   exports.setupBlurThumbnailDegradation = setupBlurThumbnailDegradation;

package/dist/index.js

@@ -1305,6 +1305,7 @@ var Presentation = class {
     var _a;
     this.pages = config.pages;
     this.preload = new Preload(this.pages);
+    this.onThumbnailError = config.onThumbnailError;
     if (config.thumbnail)
       this.thumbnail = config.thumbnail;
     this.dispose.add(this.preload);
@@ -1520,12 +1521,16 @@ var Presentation = class {
   }
   /** Returns a modified URL that points to the thumbnail image. */
   thumbnail(src) {
+    var _a;
     try {
       const url = new URL(src);
       url.searchParams.set("x-oss-process", "image/resize,l_50");
       return url.toString();
     } catch (err) {
-      console.error(err);
+      try {
+        (_a = this.onThumbnailError) == null ? void 0 : _a.call(this, err);
+      } catch (e) {
+      }
       return src;
     }
   }
@@ -2120,7 +2125,8 @@ var setupBlurThumbnailDegradation = (config) => {
   const box = context.getBox();
   const boxBlurClass = box.wrapClassName("blur");
   let blurEpisode = false;
-  let reDegradeEnabled = false;
+  let failedThumbnailPageIndex = null;
+  const canReDegrade = () => blurEpisode && failedThumbnailPageIndex !== pageIndex$.value;
   let previewSuspended = false;
   let appliedFocusState = true;
   let logicalFocused = true;
@@ -2177,15 +2183,16 @@ var setupBlurThumbnailDegradation = (config) => {
       app.suspendPreviewResources();
     }
     const page = pages[pageIndex$.value];
-    if (!page || !hasUsableThumbnail(page) || reDegradeEnabled) {
+    if (!page || !hasUsableThumbnail(page) || canReDegrade()) {
       degrade();
     }
   };
   const restoreFocusedResources = () => {
+    appliedFocusState = true;
     if (!blurEpisode)
       return;
     blurEpisode = false;
-    reDegradeEnabled = false;
+    failedThumbnailPageIndex = null;
     previewSuspended = false;
     restore2();
     app.preload.resume(pageIndex$.value);
@@ -2204,18 +2211,22 @@ var setupBlurThumbnailDegradation = (config) => {
     return !!(el && el.contains(target));
   };
   const onImgLoad = (ev) => {
-    if (!blurEpisode || !reDegradeEnabled)
+    if (!canReDegrade())
       return;
     if (!ownsTarget(ev.target))
       return;
     degrade();
   };
   const onImgError = (ev) => {
-    if (!blurEpisode || !reDegradeEnabled)
+    var _a;
+    if (!canReDegrade())
       return;
     if (!ownsTarget(ev.target))
       return;
-    reDegradeEnabled = false;
+    const thumbnailURL = (_a = pages[pageIndex$.value]) == null ? void 0 : _a.thumbnail;
+    if (thumbnailURL && resolveImageUrl(ev.target.src) === resolveImageUrl(thumbnailURL)) {
+      failedThumbnailPageIndex = pageIndex$.value;
+    }
   };
   const applyActivity = () => {
     var _a;
@@ -2229,7 +2240,7 @@ var setupBlurThumbnailDegradation = (config) => {
       restoreFocusedResources();
     } else {
       blurEpisode = true;
-      reDegradeEnabled = true;
+      failedThumbnailPageIndex = null;
       degrade();
       app.preload.pause();
       suspendCachedResources();
@@ -2276,26 +2287,21 @@ var setupBlurThumbnailDegradation = (config) => {
     document.removeEventListener("error", onImgError, true);
   });
 };
-var createLogger = (room) => {
-  if (room && room.logger) {
-    return (...args) => room.logger.info(...args);
-  } else {
-    return (...args) => console.log(...args);
-  }
+var getLogger = (context) => {
+  var _a, _b, _c;
+  return (_c = (_a = context.getWindowManager()) == null ? void 0 : _a.Logger) != null ? _c : (_b = context.getRoom()) == null ? void 0 : _b.logger;
+};
+var createLogger = (context) => {
+  return (...args) => {
+    var _a, _b;
+    return (_b = (_a = getLogger(context)) == null ? void 0 : _a.info) == null ? void 0 : _b.call(_a, ...args);
+  };
 };
 var createDiagnosticLogger = (context) => {
-  var _a;
-  const createAppLogger = context.createLogger;
-  if (typeof createAppLogger === "function") {
-    return createAppLogger.call(context, "camera", {
-      debounceTime: 300,
-      maxWaitTime: 2e3
-    });
-  }
-  const roomLogger = (_a = context.getRoom()) == null ? void 0 : _a.logger;
   const prefix = `[Presentation][${context.appId}][camera]`;
   const emit = (level, event, ...data) => {
     try {
+      const roomLogger = getLogger(context);
       const printer = roomLogger == null ? void 0 : roomLogger[level];
       if (typeof printer === "function")
         printer.call(roomLogger, `${prefix}[${event}]`, ...data);
@@ -2360,9 +2366,11 @@ var NetlessAppPresentation = {
       );
     const options = context.getAppOptions() || {};
     const room = context.getRoom();
-    const log = options.log || createLogger(room);
-    const roomLogger = room == null ? void 0 : room.logger;
-    const warn = (...data) => (roomLogger == null ? void 0 : roomLogger.warn) ? roomLogger.warn(...data) : log(...data);
+    const log = options.log || createLogger(context);
+    const warn = (...data) => {
+      var _a2, _b2;
+      return (_b2 = (_a2 = getLogger(context)) == null ? void 0 : _a2.warn) == null ? void 0 : _b2.call(_a2, ...data);
+    };
     const configuredOriginSize = context.storage.state.originSize;
     const originSize = isValidSize(configuredOriginSize) ? {
       width: configuredOriginSize.width,
@@ -2694,10 +2702,14 @@ var NetlessAppPresentation = {
         pageIndex$,
         view,
         options.thumbnail,
-        options.useClipView
+        options.useClipView,
+        (error) => {
+          var _a2, _b2;
+          return (_b2 = (_a2 = getLogger(context)) == null ? void 0 : _a2.error) == null ? void 0 : _b2.call(_a2, "[Presentation] thumbnail URL parsing failed", context.appId, error);
+        }
       )
     );
-    app.contentDOM.dataset.appPresentationVersion = "0.1.13-beta.4";
+    app.contentDOM.dataset.appPresentationVersion = "0.1.14";
     app.scaleDocsToFit = scaleDocsToFit;
     app.log = log;
     app.warn = warn;
@@ -3177,10 +3189,7 @@ var NetlessAppPresentation = {
       );
       if (disposed)
         throw new Error("[Presentation] disposed before setup ready");
-      if (result === "error" && context.waitForActualSetupReady) {
-        throw new Error("[Presentation] setup page image failed to load");
-      }
-      if (result === "error" && !disposed) {
+      if (result === "error") {
         warn("[Presentation] setup page image failed to load; continuing setup");
       }
       return controller;
@@ -3216,13 +3225,14 @@ var AppPresentation = class extends Presentation {
     }
   }
 };
-function createPresentation(box, pages, jumpPage, pageIndex$, view, thumbnail, useClipView) {
+function createPresentation(box, pages, jumpPage, pageIndex$, view, thumbnail, useClipView, onThumbnailError) {
   box.mountStyles(style_default);
   const app = new AppPresentation({
     pages,
     readonly: box.readonly,
     jumpPage,
-    thumbnail
+    thumbnail,
+    onThumbnailError
   });
   app.box = box;
   box.mountContent(app.contentDOM);
@@ -3270,11 +3280,12 @@ var install = (register, options = {}) => {
 };
 
 // src/index.ts
-var version = "0.1.13-beta.4";
+var version = "0.1.14";
 
 exports.NetlessAppPresentation = NetlessAppPresentation;
 exports.Presentation = Presentation;
 exports.Scrollbar = Scrollbar;
+exports.createDiagnosticLogger = createDiagnosticLogger;
 exports.default = NetlessAppPresentation;
 exports.install = install;
 exports.setupBlurThumbnailDegradation = setupBlurThumbnailDegradation;