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

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;
@@ -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,62 @@ 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) => {
+    return new Promise((resolve) => {
+      let settled = 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(() => settle("timeout"), timeoutMs);
+      const check = () => {
+        var _a, _b;
+        if (isDisposed()) {
+          settle("disposed");
+          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 +2079,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;
@@ -2629,7 +2656,7 @@ var NetlessAppPresentation = (function (exports) {
           options.useClipView
         )
       );
-      app.contentDOM.dataset.appPresentationVersion = "0.1.13-beta.2";
+      app.contentDOM.dataset.appPresentationVersion = "0.1.13-beta.3";
       app.scaleDocsToFit = scaleDocsToFit;
       app.log = log;
       app.warn = warn;
@@ -3098,9 +3125,15 @@ 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) {
+        const result = await waitForCurrentPageImage(
+          () => findBackgroundImage(view),
+          setupReadyTimeout,
+          () => disposed
+        );
+        if (result === "timeout" && !disposed) {
           warn(`[Presentation] setup ready wait timed out after ${setupReadyTimeout}ms`);
+        } else if (result === "error" && !disposed) {
+          warn("[Presentation] setup page image failed to load; continuing setup");
         }
         return controller;
       });
@@ -3189,7 +3222,7 @@ var NetlessAppPresentation = (function (exports) {
   };
 
   // src/index.ts
-  var version = "0.1.13-beta.2";
+  var version = "0.1.13-beta.3";
 
   exports.NetlessAppPresentation = NetlessAppPresentation;
   exports.Presentation = Presentation;

package/dist/index.js

@@ -1154,6 +1154,7 @@ var _Preload = class _Preload {
     // 暂停后不再创建预加载链接（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 */
@@ -1168,13 +1169,13 @@ var _Preload = class _Preload {
     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;
@@ -1182,11 +1183,11 @@ var _Preload = class _Preload {
       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);
@@ -1219,21 +1220,27 @@ var _Preload = class _Preload {
       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, {
@@ -1242,17 +1249,23 @@ var _Preload = class _Preload {
       });
       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) {
@@ -1270,6 +1283,7 @@ var _Preload = class _Preload {
     callBack();
   }
   dispose() {
+    this.disposed = true;
     this.destroySomeLink();
     this.preloadMap.clear();
   }
@@ -1982,19 +1996,62 @@ function cameraToSharedViewport(camera, viewSize, referenceSize) {
 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) => {
+  return new Promise((resolve) => {
+    let settled = 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(() => settle("timeout"), timeoutMs);
+    const check = () => {
+      var _a, _b;
+      if (isDisposed()) {
+        settle("disposed");
+        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$$";
@@ -2023,36 +2080,6 @@ var isBlurDegradationAllowed = (context) => {
   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;
@@ -2630,7 +2657,7 @@ var NetlessAppPresentation = {
         options.useClipView
       )
     );
-    app.contentDOM.dataset.appPresentationVersion = "0.1.13-beta.2";
+    app.contentDOM.dataset.appPresentationVersion = "0.1.13-beta.3";
     app.scaleDocsToFit = scaleDocsToFit;
     app.log = log;
     app.warn = warn;
@@ -3099,9 +3126,15 @@ var NetlessAppPresentation = {
     );
     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) {
+      const result = await waitForCurrentPageImage(
+        () => findBackgroundImage(view),
+        setupReadyTimeout,
+        () => disposed
+      );
+      if (result === "timeout" && !disposed) {
         warn(`[Presentation] setup ready wait timed out after ${setupReadyTimeout}ms`);
+      } else if (result === "error" && !disposed) {
+        warn("[Presentation] setup page image failed to load; continuing setup");
       }
       return controller;
     });
@@ -3190,7 +3223,7 @@ var install = (register, options = {}) => {
 };
 
 // src/index.ts
-var version = "0.1.13-beta.2";
+var version = "0.1.13-beta.3";
 
 exports.NetlessAppPresentation = NetlessAppPresentation;
 exports.Presentation = Presentation;