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

package/README-zh.md

@@ -93,6 +93,24 @@ scenePpt.height = ppt.height * ratio
 
 ### 应用选项
 
+#### Lazy 缓存生命周期与图片就绪
+
+Lazy setup/cache 需要带有 `teardown` 和 focus 事件生命周期的 WindowManager
+`1.0.23-beta.1` 或更高版本；当前集成验证版本为 `1.0.23-beta.3`。
+未启用 lazy 的旧宿主仍可使用普通查看功能。
+
+`setupReadyTimeout` 限制当前背景图的等待时间，默认 5000ms。图片加载成功或请求失败
+均结束等待；尚未设置图片地址的元素仍等待 SDK 赋值。失败/超时会记录警告并允许 setup
+完成，不会取消 SDK 自己的图片加载或重试。
+
+在 lazy 最大化/最小化模式下，失焦 App 优先使用可用的 `ppt.previewURL` 缩略图；
+没有可用缩略图时隐藏背景并替换为静态像素，重新聚焦恢复原图。`thumbnail(src)` 自定义
+侧边预览图，不参与此背景降级策略。设置 `disableBlurThumbnailDegradation: true` 可关闭降级。
+该优化减少常驻图片资源，不保证节省下载流量：宿主可能在首次 setup 等待完成后才补发焦点状态。
+
+预加载为尽力而为：失败时移除对应 link，不自动循环重试；显式重新访问失败页时可再次尝试
+预加载。SDK 的可见图片加载不受此策略影响。
+
 #### `disableDeviceCameraTransform`
 
 禁止鼠标滚轮、触摸手势等本地设备输入改变相机，但不改变程序化相机操作使用的

package/README.md

@@ -99,6 +99,28 @@ handles app whose kind is `DocsViewer` or `Slide`.
 
 ### App Options
 
+#### Lazy cache lifecycle and image readiness
+
+Lazy setup/cache requires WindowManager `1.0.23-beta.1` or later with the
+`teardown` and focus-event lifecycle; integration is currently verified with
+`1.0.23-beta.3`. Older hosts without lazy mode can still use the normal viewer.
+
+`setupReadyTimeout` bounds the current background-image wait (default 5000 ms).
+A loaded image or a failed image request releases the wait; an image element
+without a source still waits for the SDK to assign it. Failure/timeout logs a
+warning and lets setup finish; it does not cancel SDK image loading or retrying.
+
+In lazy maximized/minimized mode, blurred apps use `ppt.previewURL` when it is a
+usable thumbnail. Otherwise their background is hidden behind a static pixel;
+focus restores the original image. `thumbnail(src)` customizes sidebar previews,
+not this background policy. Set `disableBlurThumbnailDegradation: true` to opt out.
+This reduces retained image resources; it does not guarantee reduced downloads,
+since the host can synchronize focus only after the initial setup wait.
+
+Image preloading is best effort: failed preload links are removed without an
+automatic retry loop. Explicitly revisiting the failed page can retry preloading;
+the SDK's visible image loading remains independent.
+
 #### `disableDeviceCameraTransform`
 
 Disable camera transforms initiated by local device input, such as mouse-wheel and touch gestures,

package/dist/index.d.ts

@@ -253,11 +253,13 @@ declare class Preload implements IDisposable {
     touchIndex: number;
     preloadSize: number;
     paused: boolean;
+    private disposed;
     constructor(pages: PresentationPage[]);
     pause(): void;
     resume(index?: number): void;
     touch(index: number, force?: boolean): void;
     private createLink;
+    private removeLink;
     private destroySomeLink;
     private requestAsyncCallBack;
     dispose(): void;
@@ -470,8 +472,8 @@ interface PresentationAppOptions {
     /** useClipView is used to set the presentation use clip view, it will be used in the presentation, and the presentation will be use clip view when the app is initialized */
     useClipView?: boolean;
     /**
-     * Max time (ms) `setup()` waits for the first visible page image to load
-     * before resolving anyway. Default: 5_000.
+     * First-image warning threshold in ms. Default: 5_000. New lazy hosts
+     * await real readiness; legacy/eager hosts resolve on timeout.
      */
     setupReadyTimeout?: number;
     /**
@@ -539,7 +541,8 @@ interface PresentationController {
  * hidden and replaced with a static pixel after TeleBox commits the blur.
  *
  * While degraded, every load of a background `<img>` is re-degraded
- * immediately via a capture-phase `load` listener on the view container
+ * immediately via a capture-phase `load` listener on the document, filtered
+ * to the current view container
  * (`load` does not bubble but capture works). This covers remote page turns,
  * SDK React re-renders and the SDK's own background-image onError retries —
  * any path that (re)renders the full-size image while the app stays blurred.

package/dist/index.global.js

@@ -1153,6 +1153,7 @@ var NetlessAppPresentation = (function (exports) {
       // 暂停后不再创建预加载链接（app 失焦降级时调用）；已插入的 link 会被移除，
       // 挂起的 idle 回调重新进入 touch() 时也会被跳过
       this.paused = false;
+      this.disposed = false;
       this.preloadMap = new Map(pages.map((e, index) => [index, {
         src: e.src,
         state: 0 /* unloaded */
@@ -1167,13 +1168,13 @@ var NetlessAppPresentation = (function (exports) {
       this.destroySomeLink();
     }
     resume(index) {
-      if (!this.paused)
+      if (!this.paused || this.disposed)
         return;
       this.paused = false;
       this.touch(index != null ? index : this.touchIndex, true);
     }
     touch(index, force = false) {
-      if (this.paused)
+      if (this.paused || this.disposed)
         return;
       if (index >= this.preloadSize) {
         this.touchIndex = 0;
@@ -1181,11 +1182,11 @@ var NetlessAppPresentation = (function (exports) {
         this.touchIndex = index;
       }
       const value = this.preloadMap.get(this.touchIndex);
-      if (value && value.state === 0 /* unloaded */) {
+      if (value && (value.state === 0 /* unloaded */ || force && value.state === 2 /* error */)) {
         this.createLink(this.touchIndex, force);
       }
       if (this.loadingLinks.size < _Preload.maxLinks) {
-        const willLoad = [...this.preloadMap.entries()].find(([i, e]) => i > this.touchIndex && e.state !== 1 /* loaded */);
+        const willLoad = [...this.preloadMap.entries()].find(([i, e]) => i > this.touchIndex && e.state === 0 /* unloaded */);
         if (willLoad) {
           this.requestAsyncCallBack(() => {
             this.touch(willLoad[0], false);
@@ -1218,21 +1219,27 @@ var NetlessAppPresentation = (function (exports) {
         linkDom.as = "image";
         linkDom.href = value.src;
         linkDom.dataset.order = index + "";
-        document.head.appendChild(linkDom);
         linkDom.onload = () => {
+          var _a;
+          if (((_a = this.loadingLinks.get(index)) == null ? void 0 : _a.link) !== linkDom)
+            return;
           const value2 = this.preloadMap.get(index);
           if (value2) {
             value2.state = 1 /* loaded */;
             this.preloadMap.set(index, value2);
-            document.head.contains(linkDom) && document.head.removeChild(linkDom);
-            this.loadingLinks.delete(index);
+            this.removeLink(index, linkDom);
             this.touch(this.touchIndex + 1, false);
           }
         };
         linkDom.onerror = () => {
+          var _a;
+          if (((_a = this.loadingLinks.get(index)) == null ? void 0 : _a.link) !== linkDom)
+            return;
           const value2 = this.preloadMap.get(index);
-          if (value2 == null ? void 0 : value2.src) {
-            linkDom.href = value2.src;
+          if (value2) {
+            value2.state = 2 /* error */;
+            this.removeLink(index, linkDom);
+            this.touch(this.touchIndex + 1, false);
           }
         };
         this.loadingLinks.set(index, {
@@ -1241,17 +1248,23 @@ var NetlessAppPresentation = (function (exports) {
         });
         value.state = 0 /* unloaded */;
         this.preloadMap.set(index, value);
+        document.head.appendChild(linkDom);
         return 0 /* unloaded */;
       }
       return 2 /* error */;
     }
+    removeLink(index, link) {
+      link.onload = null;
+      link.onerror = null;
+      document.head.contains(link) && document.head.removeChild(link);
+      this.loadingLinks.delete(index);
+    }
     destroySomeLink(excludeIndex) {
       for (const [index, { link }] of this.loadingLinks) {
         if (excludeIndex !== void 0 && index === excludeIndex) {
           continue;
         }
-        document.head.contains(link) && document.head.removeChild(link);
-        this.loadingLinks.delete(index);
+        this.removeLink(index, link);
       }
     }
     async requestAsyncCallBack(callBack, timeout) {
@@ -1269,6 +1282,7 @@ var NetlessAppPresentation = (function (exports) {
       callBack();
     }
     dispose() {
+      this.disposed = true;
       this.destroySomeLink();
       this.preloadMap.clear();
     }
@@ -1981,19 +1995,72 @@ var NetlessAppPresentation = (function (exports) {
   var createPresentationRuntimeTeardown = (box, dispose2) => {
     let tornDown = false;
     return () => {
+      var _a, _b, _c;
       if (tornDown)
         return;
       tornDown = true;
       try {
         dispose2();
       } finally {
-        box.unmountContent();
-        box.unmountFooter();
-        box.unmountStyles();
+        try {
+          (_a = box.unmountContent) == null ? void 0 : _a.call(box);
+        } finally {
+          try {
+            (_b = box.unmountFooter) == null ? void 0 : _b.call(box);
+          } finally {
+            (_c = box.unmountStyles) == null ? void 0 : _c.call(box);
+          }
+        }
       }
     };
   };
 
+  // src/setup-ready.ts
+  var waitForCurrentPageImage = (getImage, timeoutMs, isDisposed, options) => {
+    return new Promise((resolve) => {
+      let settled = false;
+      let timedOut = false;
+      let pollTimer;
+      const settle = (result) => {
+        if (settled)
+          return;
+        settled = true;
+        window.clearTimeout(timeoutTimer);
+        if (pollTimer !== void 0)
+          window.clearInterval(pollTimer);
+        resolve(result);
+      };
+      const timeoutTimer = window.setTimeout(() => {
+        timedOut = true;
+        options == null ? void 0 : options.onTimeout();
+        if (!(options == null ? void 0 : options.waitForReady()))
+          settle("timeout");
+      }, timeoutMs);
+      const check = () => {
+        var _a, _b;
+        if (isDisposed()) {
+          settle("disposed");
+          return;
+        }
+        if (timedOut && !(options == null ? void 0 : options.waitForReady())) {
+          settle("timeout");
+          return;
+        }
+        const img = getImage();
+        if (img == null ? void 0 : img.complete) {
+          if (img.naturalWidth > 0) {
+            settle("loaded");
+          } else if (img.currentSrc || ((_a = img.getAttribute("src")) == null ? void 0 : _a.trim()) || ((_b = img.getAttribute("srcset")) == null ? void 0 : _b.trim())) {
+            settle("error");
+          }
+        }
+      };
+      check();
+      if (!settled)
+        pollTimer = window.setInterval(check, 100);
+    });
+  };
+
   // src/app-presentation.ts
   var import_debounce2 = __toESM(require_debounce());
   var emptySceneName = "$$empty$$";
@@ -2022,36 +2089,6 @@ var NetlessAppPresentation = (function (exports) {
     return boxState !== void 0 && boxState !== "normal";
   };
   var DEFAULT_SETUP_READY_TIMEOUT = 5e3;
-  var waitForCurrentPageImage = (view, timeoutMs, isDisposed) => {
-    return new Promise((resolve) => {
-      let settled = false;
-      let pollTimer;
-      const settle = (loaded) => {
-        if (settled)
-          return;
-        settled = true;
-        window.clearTimeout(timeoutTimer);
-        if (pollTimer !== void 0)
-          window.clearInterval(pollTimer);
-        resolve(loaded);
-      };
-      const timeoutTimer = window.setTimeout(() => settle(false), timeoutMs);
-      const check = () => {
-        if (isDisposed()) {
-          settle(false);
-          return;
-        }
-        const img = findBackgroundImage(view);
-        if (img && img.complete && img.naturalWidth > 0) {
-          settle(true);
-        }
-      };
-      check();
-      if (!settled) {
-        pollTimer = window.setInterval(check, 100);
-      }
-    });
-  };
   var resolveImageUrl = (url) => {
     try {
       return new URL(url, window.location.href).href;
@@ -2083,6 +2120,19 @@ var NetlessAppPresentation = (function (exports) {
     const boxBlurClass = box.wrapClassName("blur");
     let blurEpisode = false;
     let reDegradeEnabled = false;
+    let previewSuspended = false;
+    let appliedFocusState = true;
+    let logicalFocused = true;
+    const activityBlocked = () => {
+      var _a, _b;
+      const wm = context.getWindowManager();
+      if ((wm == null ? void 0 : wm.lazySetupInMaximizedMode) !== true)
+        return false;
+      const host = (_a = context.getRuntimeActivity) == null ? void 0 : _a.call(context);
+      if (host)
+        return document.visibilityState === "hidden" || !host.active;
+      return document.visibilityState === "hidden" || wm.boxState === "minimized" || ((_b = wm.attributes) == null ? void 0 : _b.minimized) === true || context.getBoxStatus() === "minimized";
+    };
     let boxBlurred = box.$box.classList.contains(boxBlurClass);
     const setBackgroundSuspended = (suspended) => {
       app.whiteboardDOM.classList.toggle(
@@ -2097,7 +2147,7 @@ var NetlessAppPresentation = (function (exports) {
       const thumbnailURL = page.thumbnail;
       const img = findBackgroundImage(view);
       if (!thumbnailURL || !hasUsableThumbnail(page)) {
-        if (boxBlurred) {
+        if (boxBlurred || activityBlocked()) {
           setBackgroundSuspended(true);
           if (img && resolveImageUrl(img.src) !== resolveImageUrl(TRANSPARENT_BACKGROUND)) {
             img.src = TRANSPARENT_BACKGROUND;
@@ -2119,9 +2169,12 @@ var NetlessAppPresentation = (function (exports) {
       setBackgroundSuspended(false);
     };
     const suspendCachedResources = () => {
-      if (!blurEpisode || !boxBlurred)
+      if (!blurEpisode || !boxBlurred && !activityBlocked())
         return;
-      app.suspendPreviewResources();
+      if (!previewSuspended) {
+        previewSuspended = true;
+        app.suspendPreviewResources();
+      }
       const page = pages[pageIndex$.value];
       if (!page || !hasUsableThumbnail(page) || reDegradeEnabled) {
         degrade();
@@ -2132,6 +2185,7 @@ var NetlessAppPresentation = (function (exports) {
         return;
       blurEpisode = false;
       reDegradeEnabled = false;
+      previewSuspended = false;
       restore2();
       app.preload.resume(pageIndex$.value);
     };
@@ -2162,27 +2216,40 @@ var NetlessAppPresentation = (function (exports) {
         return;
       reDegradeEnabled = false;
     };
-    const offFocus = context.emitter.on("focus", (isFocused) => {
+    const applyActivity = () => {
+      var _a;
+      const lazy = ((_a = context.getWindowManager()) == null ? void 0 : _a.lazySetupInMaximizedMode) === true;
+      const isFocused = (!lazy || logicalFocused) && !activityBlocked();
+      if (appliedFocusState === isFocused)
+        return;
+      if (!isFocused && !isBlurDegradationAllowed(context) && !activityBlocked())
+        return;
       if (isFocused) {
         restoreFocusedResources();
       } else {
-        if (!isBlurDegradationAllowed(context))
-          return;
         blurEpisode = true;
         reDegradeEnabled = true;
         degrade();
         app.preload.pause();
         suspendCachedResources();
       }
+      appliedFocusState = isFocused;
+    };
+    const offFocus = context.emitter.on("focus", (isFocused) => {
+      logicalFocused = isFocused;
+      applyActivity();
     });
     dispose2.add(offFocus);
+    dispose2.add(context.emitter.on("runtimeActivity", applyActivity));
+    document.addEventListener("visibilitychange", applyActivity);
+    dispose2.add(() => document.removeEventListener("visibilitychange", applyActivity));
     const updateBoxBlurred = (blurred) => {
       if (boxBlurred === blurred)
         return;
       boxBlurred = blurred;
       if (blurred)
         suspendCachedResources();
-      else
+      else if (logicalFocused && !activityBlocked())
         restoreFocusedResources();
     };
     const onBoxBlur = () => updateBoxBlurred(true);
@@ -2629,7 +2696,7 @@ var NetlessAppPresentation = (function (exports) {
           options.useClipView
         )
       );
-      app.contentDOM.dataset.appPresentationVersion = "0.1.13-beta.2";
+      app.contentDOM.dataset.appPresentationVersion = "0.1.13-beta.4";
       app.scaleDocsToFit = scaleDocsToFit;
       app.log = log;
       app.warn = warn;
@@ -3098,9 +3165,22 @@ var NetlessAppPresentation = (function (exports) {
       );
       const setupReadyTimeout = (_d = options.setupReadyTimeout) != null ? _d : DEFAULT_SETUP_READY_TIMEOUT;
       return prepareScenesPromise.then(async () => {
-        const loaded = await waitForCurrentPageImage(view, setupReadyTimeout, () => disposed);
-        if (!loaded && !disposed) {
-          warn(`[Presentation] setup ready wait timed out after ${setupReadyTimeout}ms`);
+        const result = await waitForCurrentPageImage(
+          () => findBackgroundImage(view),
+          setupReadyTimeout,
+          () => disposed,
+          {
+            waitForReady: () => Boolean(context.waitForActualSetupReady),
+            onTimeout: () => warn(`[Presentation] setup page image still pending after ${setupReadyTimeout}ms`)
+          }
+        );
+        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) {
+          warn("[Presentation] setup page image failed to load; continuing setup");
         }
         return controller;
       });
@@ -3189,7 +3269,7 @@ var NetlessAppPresentation = (function (exports) {
   };
 
   // src/index.ts
-  var version = "0.1.13-beta.2";
+  var version = "0.1.13-beta.4";
 
   exports.NetlessAppPresentation = NetlessAppPresentation;
   exports.Presentation = Presentation;