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

package/src/app-presentation.ts

@@ -35,6 +35,8 @@ import {
   isValidSharedViewport,
   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;
@@ -177,11 +179,17 @@ const findBackgroundImage = (view: View): HTMLImageElement | null => {
 };
 
 /**
- * Degradation only applies when the window cannot be visible: maximized
+ * Degradation is a lazy-mode cache optimization only: inactive unless the
+ * WindowManager runs with lazySetupInMaximizedMode enabled (read dynamically
+ * — lazy can be disabled at runtime, e.g. when forceMaximized is cleared).
+ * It also only applies when the window cannot be visible: maximized
  * (covered by the top app) or minimized. Normal mode may show several
  * windows side by side, so a blurred app there must keep the full image.
  */
 const isBlurDegradationAllowed = (context: AppContext): boolean => {
+  if ((context.getWindowManager() as any)?.lazySetupInMaximizedMode !== true) {
+    return false;
+  }
   const boxStatus = context.getBoxStatus();
   if (boxStatus) {
     return boxStatus !== "normal";
@@ -192,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
@@ -243,21 +213,46 @@ const resolveImageUrl = (url: string): string => {
   }
 };
 
+const TRANSPARENT_BACKGROUND =
+  "data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=";
+const BACKGROUND_SUSPENDED_CLASS =
+  "netless-app-presentation-background-suspended";
+
+const hasUsableThumbnail = (page: PresentationPage): boolean => {
+  const thumbnailURL = page.thumbnail;
+  if (!thumbnailURL) return false;
+  try {
+    const source = new URL(page.src, window.location.href);
+    const thumbnail = new URL(thumbnailURL, window.location.href);
+    const sameResourcePath =
+      source.origin === thumbnail.origin &&
+      source.pathname === thumbnail.pathname;
+    // OSS image resize URLs can return the complete animated GIF unchanged.
+    // Treat query-only GIF variants as the original resource, not a thumbnail.
+    if (/\.gif$/i.test(source.pathname) && sameResourcePath) return false;
+  } catch {
+    if (/\.gif(?:$|[?#])/i.test(page.src)) return false;
+  }
+  return resolveImageUrl(thumbnailURL) !== resolveImageUrl(page.src);
+};
+
 /**
  * Blur thumbnail degradation (see lazy-setup design doc §15): when the app
  * loses focus but stays cached (multi-runtime cache mode), swap the scene
  * background `<img>` src to the low-res `PptDescription.previewURL`
  * (`page.thumbnail`) via a pure DOM change and pause full-image preloading;
- * restore the full image when focus comes back. Skipped when the page has no
- * thumbnail.
+ * restore the full image when focus comes back. A page without a real
+ * thumbnail keeps its measurable view container, but its background layer is
+ * 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.
  */
-const setupBlurThumbnailDegradation = (config: {
+export const setupBlurThumbnailDegradation = (config: {
   context: AppContext;
   view: View;
   pages: PresentationPage[];
@@ -266,19 +261,43 @@ const setupBlurThumbnailDegradation = (config: {
   dispose: ReturnType<typeof disposableStore>;
 }): void => {
   const { context, view, pages, pageIndex$, app, dispose } = config;
+  const box = context.getBox();
+  const boxBlurClass = box.wrapClassName("blur");
   // Two separate flags: `blurEpisode` covers the whole blurred period (pages
   // without a thumbnail don't end it, so a later page degrades again), while
   // `reDegradeEnabled` only turns off when the degraded thumbnail itself
   // fails, so we don't fight the SDK's background onError retry.
   let blurEpisode = false;
   let reDegradeEnabled = false;
+  let boxBlurred = box.$box.classList.contains(boxBlurClass);
+
+  const setBackgroundSuspended = (suspended: boolean): void => {
+    app.whiteboardDOM.classList.toggle(
+      BACKGROUND_SUSPENDED_CLASS,
+      suspended,
+    );
+  };
 
   const degrade = (): void => {
     const page = pages[pageIndex$.value];
-    if (!page?.thumbnail) return; // keep the full image as-is
+    if (!page) return;
+    const thumbnailURL = page.thumbnail;
     const img = findBackgroundImage(view);
-    if (img && resolveImageUrl(img.src) !== resolveImageUrl(page.thumbnail)) {
-      img.src = page.thumbnail;
+    if (!thumbnailURL || !hasUsableThumbnail(page)) {
+      if (boxBlurred) {
+        setBackgroundSuspended(true);
+        if (
+          img &&
+          resolveImageUrl(img.src) !== resolveImageUrl(TRANSPARENT_BACKGROUND)
+        ) {
+          img.src = TRANSPARENT_BACKGROUND;
+        }
+      }
+      return;
+    }
+    setBackgroundSuspended(false);
+    if (img && resolveImageUrl(img.src) !== resolveImageUrl(thumbnailURL)) {
+      img.src = thumbnailURL;
     }
   };
 
@@ -288,6 +307,24 @@ const setupBlurThumbnailDegradation = (config: {
     if (page && img && resolveImageUrl(img.src) !== resolveImageUrl(page.src)) {
       img.src = page.src;
     }
+    setBackgroundSuspended(false);
+  };
+
+  const suspendCachedResources = (): void => {
+    if (!blurEpisode || !boxBlurred) return;
+    app.suspendPreviewResources();
+    const page = pages[pageIndex$.value];
+    if (!page || !hasUsableThumbnail(page) || reDegradeEnabled) {
+      degrade();
+    }
+  };
+
+  const restoreFocusedResources = (): void => {
+    if (!blurEpisode) return;
+    blurEpisode = false;
+    reDegradeEnabled = false;
+    restore();
+    app.preload.resume(pageIndex$.value);
   };
 
   const isBackgroundImg = (target: EventTarget | null): boolean => {
@@ -298,11 +335,20 @@ const setupBlurThumbnailDegradation = (config: {
   };
 
   // Re-degrade any background img that finishes loading a full-size image
-  // while the app is blurred. Scoped to the view container so the app's own
-  // preview-panel thumbnails are untouched.
+  // while the app is blurred. Listeners sit at document level (capture
+  // phase - load/error do not bubble but capture descends from document)
+  // and resolve the view container lazily per event, so a rebinding of
+  // view.divElement (bindContainer etc.) is followed automatically. The
+  // contains() check keeps the app's own preview-panel thumbnails untouched.
+  const ownsTarget = (target: EventTarget | null): target is HTMLImageElement => {
+    if (!isBackgroundImg(target)) return false;
+    const el = (view as any).divElement as HTMLElement | undefined | null;
+    return !!(el && el.contains(target as Node));
+  };
+
   const onImgLoad = (ev: Event): void => {
     if (!blurEpisode || !reDegradeEnabled) return;
-    if (!isBackgroundImg(ev.target)) return;
+    if (!ownsTarget(ev.target)) return;
     degrade();
   };
 
@@ -311,51 +357,56 @@ const setupBlurThumbnailDegradation = (config: {
   // still force-restores afterwards.
   const onImgError = (ev: Event): void => {
     if (!blurEpisode || !reDegradeEnabled) return;
-    if (!isBackgroundImg(ev.target)) return;
+    if (!ownsTarget(ev.target)) return;
     reDegradeEnabled = false;
   };
 
   const offFocus = context.emitter.on("focus", (isFocused: boolean) => {
     if (isFocused) {
-      if (blurEpisode) {
-        blurEpisode = false;
-        reDegradeEnabled = false;
-        restore();
-        app.preload.resume(pageIndex$.value);
-      }
+      restoreFocusedResources();
     } else {
       if (!isBlurDegradationAllowed(context)) return;
       blurEpisode = true;
       reDegradeEnabled = true;
       degrade();
       app.preload.pause();
+      suspendCachedResources();
     }
   });
   dispose.add(offFocus);
 
-  const viewEl = (view as any).divElement as HTMLElement | undefined | null;
-  if (viewEl && typeof viewEl.addEventListener === "function") {
-    viewEl.addEventListener("load", onImgLoad, true);
-    viewEl.addEventListener("error", onImgError, true);
-    dispose.add(() => {
-      viewEl.removeEventListener("load", onImgLoad, true);
-      viewEl.removeEventListener("error", onImgError, true);
-    });
-  } else {
-    // View not mounted yet (should not happen after context.mountView):
-    // keep the degradation on blur only, without re-degrade coverage.
-    warnOnceMissingViewContainer(view);
-  }
-};
+  const updateBoxBlurred = (blurred: boolean): void => {
+    if (boxBlurred === blurred) return;
+    boxBlurred = blurred;
+    if (blurred) suspendCachedResources();
+    else restoreFocusedResources();
+  };
+  const onBoxBlur = (): void => updateBoxBlurred(true);
+  const onBoxFocus = (): void => updateBoxBlurred(false);
+  box.events.on("blur", onBoxBlur);
+  box.events.on("focus", onBoxFocus);
+  dispose.add(() => {
+    box.events.off("blur", onBoxBlur);
+    box.events.off("focus", onBoxFocus);
+  });
 
-// One-shot diagnostic for an unexpected missing view container.
-const degradedWarnedViews = new WeakSet<object>();
-const warnOnceMissingViewContainer = (view: View): void => {
-  if (degradedWarnedViews.has(view)) return;
-  degradedWarnedViews.add(view);
-  console.warn(
-    "[Presentation]: blur thumbnail degradation runs without re-degrade coverage (view container unavailable)",
-  );
+  // WindowManager may update TeleBox focus with skipUpdate=true. In that
+  // path the visual class changes but TeleBox intentionally emits no event.
+  const boxClassObserver = new MutationObserver(() => {
+    updateBoxBlurred(box.$box.classList.contains(boxBlurClass));
+  });
+  boxClassObserver.observe(box.$box, {
+    attributes: true,
+    attributeFilter: ["class"],
+  });
+  dispose.add(() => boxClassObserver.disconnect());
+
+  document.addEventListener("load", onImgLoad, true);
+  document.addEventListener("error", onImgError, true);
+  dispose.add(() => {
+    document.removeEventListener("load", onImgLoad, true);
+    document.removeEventListener("error", onImgError, true);
+  });
 };
 
 const createLogger = (room: Room | undefined): Logger => {
@@ -1155,13 +1206,23 @@ export const NetlessAppPresentation: NetlessApp<
 
     let disposed = false;
     let offDestroy: (() => void) | undefined;
+    // The public readonly box type hides host lifecycle mutators, while the
+    // TeleBox runtime exposes them for app mount cleanup.
+    const teardownRuntime = createPresentationRuntimeTeardown(
+      box as ReadonlyTeleBox & {
+        unmountContent(): unknown;
+        unmountFooter(): unknown;
+        unmountStyles(): unknown;
+      },
+      dispose,
+    );
     const teardown = () => {
       if (disposed) return;
       disposed = true;
       const removeDestroy = offDestroy;
       offDestroy = undefined;
       removeDestroy?.();
-      dispose();
+      teardownRuntime();
     };
     offDestroy = context.emitter.on("destroy", teardown);
     teardownByContext.set(context, teardown);
@@ -1425,9 +1486,13 @@ 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) {
+      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;
     }) 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/presentation.ts

@@ -110,7 +110,7 @@ export class Presentation implements IDisposable<void> {
     if (this.initialized) return
     this.initialized = true
 
-    this.dispose.add(() => this.previewLazyload?.destroy())
+    this.dispose.add(() => this.destroyPreviewLazyload())
 
     this.contentDOM.classList.toggle(this.c('readonly'), this.readonly)
     this.dom.appendChild(this.contentDOM)
@@ -276,6 +276,18 @@ export class Presentation implements IDisposable<void> {
     }
   }
 
+  /** Release preview images while this presentation stays in the runtime cache. */
+  suspendPreviewResources() {
+    this.togglePreview(false)
+    this.destroyPreviewLazyload()
+    this.previewDOM.querySelectorAll<HTMLImageElement>('img').forEach(img => {
+      img.removeAttribute('src')
+      img.removeAttribute('srcset')
+      img.removeAttribute('sizes')
+      LazyLoad.resetStatus(img)
+    })
+  }
+
   // [origin] means the cause:
   // - navigation: user clicked on the left / right button on footer
   // - input: user filled the bottom-right page number input box
@@ -322,6 +334,11 @@ export class Presentation implements IDisposable<void> {
     }
   }
 
+  private destroyPreviewLazyload() {
+    this.previewLazyload?.destroy()
+    this.previewLazyload = null
+  }
+
   private c(className: string): string {
     return `${this.namespace}-${className}`
   }

package/src/runtime-lifecycle.ts

@@ -0,0 +1,31 @@
+export interface PresentationRuntimeBox {
+  unmountContent?(): unknown;
+  unmountFooter?(): unknown;
+  unmountStyles?(): unknown;
+}
+
+/** Build an idempotent runtime teardown while preserving the TeleBox shell. */
+export const createPresentationRuntimeTeardown = (
+  box: PresentationRuntimeBox,
+  dispose: () => void,
+): (() => void) => {
+  let tornDown = false;
+  return () => {
+    if (tornDown) return;
+    tornDown = true;
+    try {
+      dispose();
+    } finally {
+      // 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,39 @@
+export type SetupImageResult = "loaded" | "error" | "timeout" | "disposed";
+
+/** Wait for a terminal image state without blocking setup indefinitely. */
+export const waitForCurrentPageImage = (
+  getImage: () => HTMLImageElement | null,
+  timeoutMs: number,
+  isDisposed: () => boolean,
+): Promise<SetupImageResult> => {
+  return new Promise(resolve => {
+    let settled = 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(() => settle("timeout"), timeoutMs);
+    const check = () => {
+      if (isDisposed()) {
+        settle("disposed");
+        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);
+  });
+};

package/src/style.scss

@@ -12,6 +12,12 @@ $namespace: 'netless-app-presentation';
   overflow: hidden;
 }
 
+// Keep the view container measurable while releasing an unfocused cached
+// page's background from painting and compositing.
+.#{$namespace}-background-suspended .background {
+  display: none !important;
+}
+
 .#{$namespace}-preview-mask {
   display: none;
   position: absolute;
@@ -307,4 +313,4 @@ $namespace: 'netless-app-presentation';
 
 .#{$namespace}-scrollbar-y {
   width: 6px;
-}
+}