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

package/src/app-presentation.ts

@@ -36,6 +36,7 @@ import {
   isValidSize,
 } from "./camera-reference";
 import { createPresentationRuntimeTeardown } from "./runtime-lifecycle";
+import { waitForCurrentPageImage } from "./setup-ready";
 import debounce from "lodash/debounce";
 
 export type Logger = (...data: any[]) => void;
@@ -98,8 +99,8 @@ export 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;
   /**
@@ -199,44 +200,6 @@ const isBlurDegradationAllowed = (context: AppContext): boolean => {
 
 const DEFAULT_SETUP_READY_TIMEOUT = 5_000;
 
-/**
- * Resolve once the current page background image has loaded (or after
- * `timeoutMs`). `false` means timeout or the app was disposed mid-wait;
- * callers must treat it as "continue loading in background", not an error.
- */
-const waitForCurrentPageImage = (
-  view: View,
-  timeoutMs: number,
-  isDisposed: () => boolean,
-): Promise<boolean> => {
-  return new Promise<boolean>(resolve => {
-    let settled = false;
-    let pollTimer: number | undefined;
-    const settle = (loaded: boolean) => {
-      if (settled) return;
-      settled = true;
-      window.clearTimeout(timeoutTimer);
-      if (pollTimer !== undefined) 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);
-    }
-  });
-};
-
 /**
  * Compare image URLs by resolved absolute href so relative/absolute
  * representations of the same URL do not look different (and to keep the
@@ -283,7 +246,8 @@ const hasUsableThumbnail = (page: PresentationPage): boolean => {
  * 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.
@@ -305,6 +269,29 @@ export const setupBlurThumbnailDegradation = (config: {
   // fails, so we don't fight the SDK's background onError retry.
   let blurEpisode = false;
   let reDegradeEnabled = false;
+  // Duplicate focus(false) deliveries are unavoidable (multiple sources in
+  // the host). Preview-resource clearing is the only non-idempotent DOM op
+  // in the blur path, so gate it on this flag until focus restores it.
+  let previewSuspended = false;
+  // A freshly-created runtime has active resources even if setup completed
+  // after the box already lost focus. Track applied resource state instead of
+  // reading box.focus, and ignore repeated signals from the host.
+  let appliedFocusState = true;
+  let logicalFocused = true;
+  const activityBlocked = (): boolean => {
+    const wm = context.getWindowManager() as any;
+    if (wm?.lazySetupInMaximizedMode !== true) return false;
+    const host = (context as any).getRuntimeActivity?.();
+    // Use the host's complete activity snapshot when available, rather than
+    // combining it with a local boxState from a different restore revision.
+    if (host) return document.visibilityState === "hidden" || !host.active;
+    return (
+      document.visibilityState === "hidden" ||
+      wm.boxState === "minimized" ||
+      wm.attributes?.minimized === true ||
+      context.getBoxStatus() === "minimized"
+    );
+  };
   let boxBlurred = box.$box.classList.contains(boxBlurClass);
 
   const setBackgroundSuspended = (suspended: boolean): void => {
@@ -320,7 +307,7 @@ export const setupBlurThumbnailDegradation = (config: {
     const thumbnailURL = page.thumbnail;
     const img = findBackgroundImage(view);
     if (!thumbnailURL || !hasUsableThumbnail(page)) {
-      if (boxBlurred) {
+      if (boxBlurred || activityBlocked()) {
         setBackgroundSuspended(true);
         if (
           img &&
@@ -347,8 +334,11 @@ export const setupBlurThumbnailDegradation = (config: {
   };
 
   const suspendCachedResources = (): void => {
-    if (!blurEpisode || !boxBlurred) return;
-    app.suspendPreviewResources();
+    if (!blurEpisode || (!boxBlurred && !activityBlocked())) return;
+    if (!previewSuspended) {
+      previewSuspended = true;
+      app.suspendPreviewResources();
+    }
     const page = pages[pageIndex$.value];
     if (!page || !hasUsableThumbnail(page) || reDegradeEnabled) {
       degrade();
@@ -359,6 +349,7 @@ export const setupBlurThumbnailDegradation = (config: {
     if (!blurEpisode) return;
     blurEpisode = false;
     reDegradeEnabled = false;
+    previewSuspended = false;
     restore();
     app.preload.resume(pageIndex$.value);
   };
@@ -397,25 +388,36 @@ export const setupBlurThumbnailDegradation = (config: {
     reDegradeEnabled = false;
   };
 
-  const offFocus = context.emitter.on("focus", (isFocused: boolean) => {
+  const applyActivity = (): void => {
+    const lazy = (context.getWindowManager() as any)?.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: boolean) => {
+    logicalFocused = isFocused;
+    applyActivity();
   });
   dispose.add(offFocus);
+  dispose.add((context.emitter as any).on("runtimeActivity", applyActivity));
+  document.addEventListener("visibilitychange", applyActivity);
+  dispose.add(() => document.removeEventListener("visibilitychange", applyActivity));
 
   const updateBoxBlurred = (blurred: boolean): void => {
     if (boxBlurred === blurred) return;
     boxBlurred = blurred;
     if (blurred) suspendCachedResources();
-    else restoreFocusedResources();
+    else if (logicalFocused && !activityBlocked()) restoreFocusedResources();
   };
   const onBoxBlur = (): void => updateBoxBlurred(true);
   const onBoxFocus = (): void => updateBoxBlurred(false);
@@ -1522,9 +1524,19 @@ export const NetlessAppPresentation: NetlessApp<
     return prepareScenesPromise.then(async () => {
       // Keep the serial setup queue honest: resolve only once the current
       // page image is actually visible (or the bounded wait gives up).
-      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 as any).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 as any).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;
     }) as unknown as PresentationController;

package/src/preload.ts

@@ -38,6 +38,7 @@ export class Preload implements IDisposable {
   // 暂停后不再创建预加载链接（app 失焦降级时调用）；已插入的 link 会被移除，
   // 挂起的 idle 回调重新进入 touch() 时也会被跳过
   paused: boolean = false;
+  private disposed = false;
   constructor(readonly pages: PresentationPage[]) {
     this.preloadMap = new Map(pages.map((e,index) => [index, {
       src: e.src,
@@ -52,23 +53,23 @@ export class Preload implements IDisposable {
     this.destroySomeLink();
   }
   resume(index?: number) {
-    if (!this.paused) return;
+    if (!this.paused || this.disposed) return;
     this.paused = false;
     this.touch(index ?? this.touchIndex, true);
   }
   touch(index: number, force: boolean = false) {
-    if (this.paused) return;
+    if (this.paused || this.disposed) return;
     if (index >= this.preloadSize) {
       this.touchIndex = 0;
     } else {
       this.touchIndex = index;
     }
     const value = this.preloadMap.get(this.touchIndex);
-    if (value && value.state === ELoadState.unloaded) {
+    if (value && (value.state === ELoadState.unloaded || (force && value.state === ELoadState.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 !== ELoadState.loaded);
+      const willLoad = [...this.preloadMap.entries()].find(([i, e]) => i > this.touchIndex && e.state === ELoadState.unloaded);
       if (willLoad) {
         this.requestAsyncCallBack(()=>{this.touch(willLoad[0], false)}, 100);
       }
@@ -100,21 +101,25 @@ export class Preload implements IDisposable {
       linkDom.as = 'image';
       linkDom.href = value.src;
       linkDom.dataset.order = index + '';
-      document.head.appendChild(linkDom);
       linkDom.onload = () => {
+        if (this.loadingLinks.get(index)?.link !== linkDom) return;
         const value = this.preloadMap.get(index);
         if (value) {
           value.state = ELoadState.loaded;
           this.preloadMap.set(index, value);
-          document.head.contains(linkDom) && document.head.removeChild(linkDom);
-          this.loadingLinks.delete(index);
+          this.removeLink(index, linkDom);
           this.touch(this.touchIndex + 1, false);
         }
       }
       linkDom.onerror = () => {
+        if (this.loadingLinks.get(index)?.link !== linkDom) return;
         const value = this.preloadMap.get(index);
-        if (value?.src) {
-          linkDom.href = value.src;
+        if (value) {
+          // Preloading is best effort. Do not retry in an error loop;
+          // revisiting the page explicitly may retry after network recovery.
+          value.state = ELoadState.error;
+          this.removeLink(index, linkDom);
+          this.touch(this.touchIndex + 1, false);
         }
       }
       this.loadingLinks.set(index, {
@@ -123,18 +128,24 @@ export class Preload implements IDisposable {
       });
       value.state = ELoadState.unloaded;
       this.preloadMap.set(index, value);
+      document.head.appendChild(linkDom);
       return ELoadState.unloaded;
     }
     return ELoadState.error;
   }
 
+  private removeLink(index: number, link: HTMLLinkElement) {
+    link.onload = null;
+    link.onerror = null;
+    document.head.contains(link) && document.head.removeChild(link);
+    this.loadingLinks.delete(index);
+  }
   private destroySomeLink(excludeIndex?: number) {
     for (const [index, { link }] of this.loadingLinks) {
       if (excludeIndex !== undefined && index === excludeIndex) {
         continue;
       }
-      document.head.contains(link) && document.head.removeChild(link);
-      this.loadingLinks.delete(index);
+      this.removeLink(index, link);
     }
   }
   private async requestAsyncCallBack (callBack:()=>void, timeout:number):Promise<void> {
@@ -152,6 +163,7 @@ export class Preload implements IDisposable {
       callBack();
   }
   dispose() {
+    this.disposed = true;
     this.destroySomeLink();
     this.preloadMap.clear();
   }

package/src/runtime-lifecycle.ts

@@ -1,7 +1,7 @@
 export interface PresentationRuntimeBox {
-  unmountContent(): unknown;
-  unmountFooter(): unknown;
-  unmountStyles(): unknown;
+  unmountContent?(): unknown;
+  unmountFooter?(): unknown;
+  unmountStyles?(): unknown;
 }
 
 /** Build an idempotent runtime teardown while preserving the TeleBox shell. */
@@ -16,9 +16,16 @@ export const createPresentationRuntimeTeardown = (
     try {
       dispose();
     } finally {
-      box.unmountContent();
-      box.unmountFooter();
-      box.unmountStyles();
+      // A partial host API or a failing mount must not skip other cleanup.
+      try {
+        box.unmountContent?.();
+      } finally {
+        try {
+          box.unmountFooter?.();
+        } finally {
+          box.unmountStyles?.();
+        }
+      }
     }
   };
 };

package/src/setup-ready.ts

@@ -0,0 +1,46 @@
+export type SetupImageResult = "loaded" | "error" | "timeout" | "disposed";
+
+/** New lazy hosts await actual readiness; legacy hosts retain the bounded wait. */
+export const waitForCurrentPageImage = (
+  getImage: () => HTMLImageElement | null,
+  timeoutMs: number,
+  isDisposed: () => boolean,
+  options?: { waitForReady: () => boolean; onTimeout: () => void },
+): Promise<SetupImageResult> => {
+  return new Promise(resolve => {
+    let settled = false;
+    let timedOut = false;
+    let pollTimer: number | undefined;
+    const settle = (result: SetupImageResult) => {
+      if (settled) return;
+      settled = true;
+      window.clearTimeout(timeoutTimer);
+      if (pollTimer !== undefined) window.clearInterval(pollTimer);
+      resolve(result);
+    };
+    const timeoutTimer = window.setTimeout(() => {
+      timedOut = true;
+      options?.onTimeout();
+      if (!options?.waitForReady()) settle("timeout");
+    }, timeoutMs);
+    const check = () => {
+      if (isDisposed()) {
+        settle("disposed");
+        return;
+      }
+      if (timedOut && !options?.waitForReady()) { settle("timeout"); return; }
+      const img = getImage();
+      if (img?.complete) {
+        if (img.naturalWidth > 0) {
+          settle("loaded");
+        } else if (img.currentSrc || img.getAttribute("src")?.trim() || img.getAttribute("srcset")?.trim()) {
+          // complete is also true before src is assigned. Only an actual
+          // image request with zero decoded width represents a failed load.
+          settle("error");
+        }
+      }
+    };
+    check();
+    if (!settled) pollTimer = window.setInterval(check, 100);
+  });
+};