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

package/src/app-presentation.ts

@@ -99,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;
   /**
@@ -263,12 +263,34 @@ export const setupBlurThumbnailDegradation = (config: {
   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.
+  // A failed thumbnail is pinned only for its page during this blur episode.
   let blurEpisode = false;
-  let reDegradeEnabled = false;
+  let failedThumbnailPageIndex: number | null = null;
+  const canReDegrade = (): boolean =>
+    blurEpisode && failedThumbnailPageIndex !== pageIndex$.value;
+  // 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 => {
@@ -284,7 +306,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 &&
@@ -311,10 +333,13 @@ 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) {
+    if (!page || !hasUsableThumbnail(page) || canReDegrade()) {
       degrade();
     }
   };
@@ -322,7 +347,8 @@ export const setupBlurThumbnailDegradation = (config: {
   const restoreFocusedResources = (): void => {
     if (!blurEpisode) return;
     blurEpisode = false;
-    reDegradeEnabled = false;
+    failedThumbnailPageIndex = null;
+    previewSuspended = false;
     restore();
     app.preload.resume(pageIndex$.value);
   };
@@ -347,39 +373,55 @@ export const setupBlurThumbnailDegradation = (config: {
   };
 
   const onImgLoad = (ev: Event): void => {
-    if (!blurEpisode || !reDegradeEnabled) return;
+    if (!canReDegrade()) return;
     if (!ownsTarget(ev.target)) return;
     degrade();
   };
 
-  // The degraded thumbnail failed to load: stop re-degrading for this blur
-  // episode so the SDK's onError retry can settle on the full image. Focus
-  // still force-restores afterwards.
+  // Stop re-degrading this page when its thumbnail fails, so the SDK's
+  // onError retry can settle on the full image. Other pages remain eligible.
   const onImgError = (ev: Event): void => {
-    if (!blurEpisode || !reDegradeEnabled) return;
+    if (!canReDegrade()) return;
     if (!ownsTarget(ev.target)) return;
-    reDegradeEnabled = false;
+    const thumbnailURL = pages[pageIndex$.value]?.thumbnail;
+    if (
+      thumbnailURL &&
+      resolveImageUrl(ev.target.src) === resolveImageUrl(thumbnailURL)
+    ) {
+      failedThumbnailPageIndex = pageIndex$.value;
+    }
   };
 
-  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;
+      failedThumbnailPageIndex = null;
       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);
@@ -409,27 +451,16 @@ export const setupBlurThumbnailDegradation = (config: {
   });
 };
 
-const createLogger = (room: Room | undefined): Logger => {
-  if (room && (room as any).logger) {
-    return (...args) => (room as any).logger.info(...args);
-  } else {
-    return (...args) => console.log(...args);
-  }
+const getLogger = (context: AppContext) =>
+  (context.getWindowManager() as any)?.Logger ?? (context.getRoom() as any)?.logger;
+
+const createLogger = (context: AppContext): Logger => {
+  return (...args) => getLogger(context)?.info?.(...args);
 };
 
-const createDiagnosticLogger = (
+export const createDiagnosticLogger = (
   context: AppContext,
 ): PresentationDiagnosticLogger => {
-  const createAppLogger = (context as any).createLogger;
-  if (typeof createAppLogger === "function") {
-    return createAppLogger.call(context, "camera", {
-      debounceTime: 300,
-      maxWaitTime: 2000,
-    });
-  }
-
-  // Compatibility fallback for WindowManager versions without AppContext.createLogger().
-  const roomLogger = (context.getRoom() as any)?.logger;
   const prefix = `[Presentation][${context.appId}][camera]`;
   const emit = (
     level: "info" | "warn" | "error",
@@ -437,6 +468,7 @@ const createDiagnosticLogger = (
     ...data: unknown[]
   ) => {
     try {
+      const roomLogger = getLogger(context);
       const printer = roomLogger?.[level];
       if (typeof printer === "function")
         printer.call(roomLogger, `${prefix}[${event}]`, ...data);
@@ -516,10 +548,8 @@ export const NetlessAppPresentation: NetlessApp<
 
     const options = context.getAppOptions() || {};
     const room = context.getRoom();
-    const log = options.log || createLogger(room);
-    const roomLogger = (room as any)?.logger;
-    const warn: Logger = (...data) =>
-      roomLogger?.warn ? roomLogger.warn(...data) : log(...data);
+    const log = options.log || createLogger(context);
+    const warn: Logger = (...data) => getLogger(context)?.warn?.(...data);
     const configuredOriginSize = context.storage.state.originSize;
     const originSize = isValidSize(configuredOriginSize)
       ? {
@@ -889,6 +919,7 @@ export const NetlessAppPresentation: NetlessApp<
         view,
         options.thumbnail,
         options.useClipView,
+        error => getLogger(context)?.error?.("[Presentation] thumbnail URL parsing failed", context.appId, error),
       ),
     );
     app.contentDOM.dataset.appPresentationVersion = __VERSION__;
@@ -1484,14 +1515,17 @@ export const NetlessAppPresentation: NetlessApp<
     // `SetupResult | Promise<SetupResult>` declaration is the minimum version.
     const setupReadyTimeout = options.setupReadyTimeout ?? DEFAULT_SETUP_READY_TIMEOUT;
     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).
+      // Wait for the current page image or its first failure. The SDK owns
+      // background-image retries, so a failed request must not fail setup.
       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 (result === "timeout" && !disposed) {
-        warn(`[Presentation] setup ready wait timed out after ${setupReadyTimeout}ms`);
-      } else if (result === "error" && !disposed) {
+      if (disposed) throw new Error("[Presentation] disposed before setup ready");
+      if (result === "error") {
         warn("[Presentation] setup page image failed to load; continuing setup");
       }
       return controller;
@@ -1553,6 +1587,7 @@ function createPresentation(
   view: View,
   thumbnail?: (src: string) => string,
   useClipView?: boolean,
+  onThumbnailError?: (error: unknown) => void,
 ): AppPresentation {
   box.mountStyles(styles);
 
@@ -1561,6 +1596,7 @@ function createPresentation(
     readonly: box.readonly,
     jumpPage,
     thumbnail,
+    onThumbnailError,
   });
   app.box = box;
   box.mountContent(app.contentDOM);

package/src/presentation.ts

@@ -18,6 +18,7 @@ export interface PresentationConfig {
   readonly pages: PresentationPage[]
   readonly readonly?: boolean
   readonly thumbnail?: (src: string) => string
+  readonly onThumbnailError?: (error: unknown) => void
 }
 
 /**
@@ -59,6 +60,7 @@ export class Presentation implements IDisposable<void> {
   readonly dispose = disposableStore()
   readonly pages: PresentationPage[]
   readonly preload: Preload
+  readonly onThumbnailError?: (error: unknown) => void
 
   dom: Element | DocumentFragment
   contentDOM: HTMLDivElement
@@ -81,6 +83,7 @@ export class Presentation implements IDisposable<void> {
   constructor(config: PresentationConfig) {
     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)
     this.readonly = config.readonly ?? false
@@ -329,7 +332,11 @@ export class Presentation implements IDisposable<void> {
       url.searchParams.set('x-oss-process', 'image/resize,l_50')
       return url.toString()
     } catch (err) {
-      console.error(err)
+      try {
+        this.onThumbnailError?.(err)
+      } catch {
+        // A diagnostic failure must not change the thumbnail fallback.
+      }
       return src
     }
   }

package/src/setup-ready.ts

@@ -1,13 +1,15 @@
 export type SetupImageResult = "loaded" | "error" | "timeout" | "disposed";
 
-/** Wait for a terminal image state without blocking setup indefinitely. */
+/** 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;
@@ -16,12 +18,17 @@ export const waitForCurrentPageImage = (
       if (pollTimer !== undefined) window.clearInterval(pollTimer);
       resolve(result);
     };
-    const timeoutTimer = window.setTimeout(() => settle("timeout"), timeoutMs);
+    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) {