@netless/app-slide 0.2.106-beta.2 → 0.2.106-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netless/app-slide",
-  "version": "0.2.106-beta.2",
+  "version": "0.2.106-beta.3",
   "main": "dist/main.cjs.js",
   "module": "dist/main.es.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
     "build": "vite build && npm run types",
     "build:dev": "vite build --mode development && npm run types",
     "cleanup": "rimraf ./dist",
-    "test": "rimraf test/.cache && esbuild test/ResizableContainer.test.ts test/NavigationButtonMode.test.ts test/DocsViewerNavigation.integration.test.ts --bundle --platform=node --format=cjs --outdir=test/.cache && node test/.cache/ResizableContainer.test.js && node test/.cache/NavigationButtonMode.test.js && node test/.cache/DocsViewerNavigation.integration.test.js"
+    "test": "rimraf test/.cache && esbuild test/ResizableContainer.test.ts test/NavigationButtonMode.test.ts test/DocsViewerNavigation.integration.test.ts test/FocusTransition.test.ts --bundle --platform=node --format=cjs --outdir=test/.cache && node test/.cache/ResizableContainer.test.js && node test/.cache/NavigationButtonMode.test.js && node test/.cache/DocsViewerNavigation.integration.test.js && node test/.cache/FocusTransition.test.js && node test/run-runtime-activity.mjs"
   },
   "files": [
     "src",

package/src/SlideController/index.ts

@@ -17,8 +17,9 @@ import { SideEffectManager } from "side-effect-manager";
 import { Slide, SLIDE_EVENTS } from "@netless/slide";
 import { clamp } from "../utils/helpers";
 import { cachedGetBgColor } from "../utils/bgcolor";
-import { log, verbose, setRoomLogger } from "../utils/logger";
+import { log, verbose, setRoomLogger, logger } from "../utils/logger";
 import { getRoomTracker } from "../utils/tracker";
+import { createFocusTransitionQueue, shouldSlideRuntimeBeActive } from "../utils/focus-transition";
 export { syncSceneWithSlide, createDocsViewerPages } from "./helpers";
 
 export const DefaultUrl = "https://convertcdn.netless.link/dynamicConvert";
@@ -80,6 +81,7 @@ export class SlideControllerBase {
 
   protected visible: boolean;
   protected savedIsFrozen: boolean;
+  protected focused = true;
 
   protected invisibleBehavior: "frozen" | "pause";
 
@@ -132,7 +134,9 @@ export class SlideControllerBase {
         log("[Slide] render end", slideIndex);
       } else {
         setTimeout(() => {
+          if (this.destroyed) return;
           this.ready = true;
+          if (this.isLazySetupMode()) void this.reconcileActivity(true).catch(() => undefined);
           resolve();
         }, 1000);
       }
@@ -282,6 +286,10 @@ export class SlideControllerBase {
   protected pollCount = 0;
   protected pollReadyState = () => {
     if (this.ready) {
+      if (this.isLazySetupMode()) {
+        void this.reconcileActivity().catch(() => undefined);
+        return;
+      }
       if (this._toFreeze === 1) {
         this.freeze();
       } else if (this._toFreeze === -1) {
@@ -378,49 +386,117 @@ export class SlideControllerBase {
   };
 
   public isFrozen = false;
+  private resourceStateUnknown = false;
+  private managedActivity = false;
   protected _toFreeze: -1 | 0 | 1 = 0; // -1: unfreeze, 0: no change, 1: freeze
 
-  public freeze = (): Promise<void> => {
+  public setFocusedState = (focused: boolean): Promise<void> => {
+    this.focused = focused;
+    return this.reconcileActivity();
+  };
+
+  private resourceTransition = createFocusTransitionQueue(
+    undefined,
+    async active => {
+      if (this.destroyed) return;
+      // A queued release can become stale before the engine starts it.
+      if (active && this.shouldBeActive()) await this.unfreeze();
+      else await this.freeze();
+    },
+    error => logger.warn("[Slide] resource transition failed", this.context.appId, error)
+  );
+
+  private shouldBeActive = (): boolean => {
+    const wm = this.context.getWindowManager() as any;
+    const host = (this.context as any).getRuntimeActivity?.();
+    const lazy = this.isLazySetupMode();
+    // New hosts own one activity snapshot. Mixing it with the delayed UI
+    // boxState can acknowledge "frozen" while the host expects activation.
+    // Old hosts retain the original local/Attribute checks.
+    const minimized =
+      lazy && host
+        ? !host.active
+        : wm?.boxState === "minimized" ||
+          wm?.attributes?.minimized === true ||
+          this.context.getBoxStatus() === "minimized";
+    return (
+      shouldSlideRuntimeBeActive(
+        !lazy || this.focused,
+        document.visibilityState !== "hidden",
+        minimized
+      ) &&
+      (!lazy || host?.active !== false)
+    );
+  };
+
+  public reconcileActivity = (force = false): Promise<void> => {
+    if (this.destroyed) return Promise.resolve();
+    if (this.isLazySetupMode()) this.managedActivity = true;
+    if (!this.managedActivity) return Promise.resolve();
+    this.visible = document.visibilityState !== "hidden";
+    return this.resourceTransition(this.shouldBeActive(), force);
+  };
+
+  public freeze = async (): Promise<void> => {
+    const previousIsFrozen = this.isFrozen;
+    const previousToFreeze = this._toFreeze;
     this.isFrozen = true;
-    if (this.ready) {
-      log("[Slide] freeze", this.context.appId);
-      if (this.invisibleBehavior === "frozen") {
-        return Promise.resolve(this.slide.frozen());
+    try {
+      if (this.ready) {
+        log("[Slide] freeze", this.context.appId);
+        if (this.invisibleBehavior === "frozen") {
+          await this.slide.frozen();
+        } else {
+          this.slide.pause();
+        }
       } else {
-        this.slide.pause();
+        this._toFreeze = 1;
       }
-    } else {
-      this._toFreeze = 1;
+      this.resourceStateUnknown = false;
+    } catch (error) {
+      this.resourceStateUnknown = true;
+      this.isFrozen = previousIsFrozen;
+      this._toFreeze = previousToFreeze;
+      throw error;
     }
-    return Promise.resolve();
   };
 
   public unfreeze = async (): Promise<void> => {
     if (!this.visible) return;
-    if (!this.isFrozen && this.ready) return;
+    if (!this.isFrozen && this.ready && !this.resourceStateUnknown) return;
+    const previousIsFrozen = this.isFrozen;
+    const previousToFreeze = this._toFreeze;
     this.isFrozen = false;
-    if (this.ready) {
-      let isNeedSyncState = false;
-      log("[Slide] unfreeze", this.context.appId);
-      if (this.invisibleBehavior === "frozen") {
-        await this.slide.release(() => {
-          // release 会重建 player，内部 observer 已关闭，需要按当前 frame 尺寸重绘
+    try {
+      if (this.ready) {
+        let isNeedSyncState = false;
+        log("[Slide] unfreeze", this.context.appId);
+        if (this.invisibleBehavior === "frozen") {
+          await this.slide.release(() => {
+            // release 会重建 player，内部 observer 已关闭，需要按当前 frame 尺寸重绘
+            if (!this.isLazySetupMode() || this.shouldBeActive()) this.slide.notifyFrameResize();
+          });
+          isNeedSyncState = true;
+        } else {
+          this.slide.resume();
           this.slide.notifyFrameResize();
-        });
-        isNeedSyncState = true;
-      } else {
-        this.slide.resume();
-        this.slide.notifyFrameResize();
-      }
-      if (isNeedSyncState) {
-        const state = this.context.storage.state.state;
-        if (state) {
-          log("[Slide] sync storage", JSON.stringify(state));
-          this.slide.setSlideState(state);
         }
+        if (isNeedSyncState && (!this.isLazySetupMode() || this.shouldBeActive())) {
+          const state = this.context.storage.state.state;
+          if (state) {
+            log("[Slide] sync storage", JSON.stringify(state));
+            await this.slide.setSlideState(state);
+          }
+        }
+      } else {
+        this._toFreeze = -1;
       }
-    } else {
-      this._toFreeze = -1;
+      this.resourceStateUnknown = false;
+    } catch (error) {
+      this.resourceStateUnknown = true;
+      this.isFrozen = previousIsFrozen;
+      this._toFreeze = previousToFreeze;
+      throw error;
     }
   };
 
@@ -446,6 +522,10 @@ export class SlideControllerBase {
   };
 
   protected onAppStateChangeHandler = (state: "normal" | "minimized" | "maximized") => {
+    if (this.isLazySetupMode() || this.managedActivity) {
+      void this.reconcileActivity().catch(() => undefined);
+      return;
+    }
     if (state === "minimized") {
       log("[Slide] freeze because app state is minimized");
       this.freeze();
@@ -457,6 +537,10 @@ export class SlideControllerBase {
     status: "normal" | "minimized" | "maximized";
   }) => {
     const { appId, status } = payload;
+    if (appId === this.context.appId && (this.isLazySetupMode() || this.managedActivity)) {
+      void this.reconcileActivity().catch(() => undefined);
+      return;
+    }
     if (appId === this.context.appId && status === "minimized") {
       log("[Slide] freeze because app status is minimized");
       this.freeze();
@@ -479,21 +563,35 @@ export class SlideControllerBase {
     }
   };
 
+  protected isLazySetupMode = (): boolean => {
+    try {
+      return (this.context.getWindowManager() as any)?.lazySetupInMaximizedMode === true;
+    } catch {
+      return false;
+    }
+  };
+
   protected onVisibilityChange = async () => {
+    this.visible = document.visibilityState === "visible";
+    if (this.isLazySetupMode() || this.managedActivity) {
+      await this.reconcileActivity().catch(() => undefined);
+      return;
+    }
     const appStatus = this.getAppStatus();
+    if (!this.visible) {
+      this.savedIsFrozen = this.isFrozen;
+      log("[Slide] freeze because tab becomes invisible");
+      if (!this.isFrozen) await this.freeze();
+      return;
+    }
+
     if (appStatus === "minimized") {
       log("[Slide] do nothing because app state is minimized");
       return;
     }
-    if (!(this.visible = document.visibilityState === "visible")) {
-      this.savedIsFrozen = this.isFrozen;
-      log("[Slide] freeze because tab becomes invisible");
-      this.freeze();
-    } else {
-      if (!this.savedIsFrozen) {
-        log("[Slide] unfreeze because tab becomes visible", { savedIsFrozen: this.savedIsFrozen });
-        this.unfreeze();
-      }
+    if (!this.savedIsFrozen) {
+      log("[Slide] unfreeze because tab becomes visible", { savedIsFrozen: this.savedIsFrozen });
+      await this.unfreeze();
     }
   };
 }

package/src/index.ts

@@ -94,8 +94,8 @@ export interface AppOptions
   resourceMaxRetries?: number;
   onResourceMaxRetries: (url: string, error: Error) => void;
   /**
-   * Max time (ms) `setup()` waits for the first `renderEnd` before resolving
-   * anyway (the slide keeps loading in background). Default: 5_000.
+   * First-render warning threshold in ms. Default: 5_000. New lazy hosts
+   * continue awaiting real readiness; legacy/eager hosts resolve on timeout.
    */
   setupReadyTimeout?: number;
 }
@@ -289,30 +289,19 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
     // a lazy-mode-only cache optimization: inactive unless the WindowManager
     // runs with lazySetupInMaximizedMode enabled (read dynamically — lazy can
     // be disabled at runtime, e.g. when forceMaximized is cleared).
-    const isBlurFreezeAllowed = (): boolean => {
-      const boxStatus = context.getBoxStatus();
-      if (boxStatus) return boxStatus !== "normal";
-      const boxState = context.getWindowManager()?.boxState;
-      return boxState != null && boxState !== "normal";
-    };
     sideEffect.add(() =>
-      context.emitter.on("focus", async (isFocused: boolean) => {
+      context.emitter.on("focus", (isFocused: boolean) => {
         if (disposed) return;
-        if (!isLazySetupMode()) return;
         const controller = docsViewer?.slideController;
-        if (!controller) return;
-        if (!isFocused) {
-          if (!isBlurFreezeAllowed()) return;
-          if (!controller.isFrozen) {
-            log("[Slide] blur freeze", context.appId);
-            await controller.freeze();
-          }
-          return;
-        }
-        if (controller.isFrozen) {
-          log("[Slide] focus unfreeze", context.appId);
-          await controller.unfreeze();
-        }
+        // Emittery waits for listener return values. Propagate the transition
+        // promise so WindowManager commits focus only after resources are
+        // frozen/unfrozen and Slide state restoration has completed.
+        return controller?.setFocusedState(isFocused);
+      })
+    );
+    sideEffect.add(() =>
+      (context.emitter as any).on("runtimeActivity", () => {
+        if (!disposed) return docsViewer?.slideController?.reconcileActivity();
       })
     );
 
@@ -346,11 +335,12 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
     (SlideApp as any).__teardownByContext.set(context, teardown);
 
     // Resolve once the SlideController finished its first render (renderEnd).
-    // `false` means timeout or teardown; the slide then keeps loading in the
-    // background without blocking WindowManager's serial setup queue.
+    // New lazy hosts retain the real completion after the warning threshold.
+    // Legacy/eager hosts retain timed readiness; disposal/failure rejects below.
     const waitForFirstRender = (timeoutMs: number): Promise<boolean> =>
       new Promise<boolean>(resolve => {
         let settled = false;
+        let timedOut = false;
         const settle = (loaded: boolean) => {
           if (settled) return;
           settled = true;
@@ -358,7 +348,11 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
           window.clearInterval(pollTimer);
           resolve(loaded);
         };
-        const timeoutTimer = window.setTimeout(() => settle(false), timeoutMs);
+        const timeoutTimer = window.setTimeout(() => {
+          timedOut = true;
+          logger.warn("[Slide] first render still pending", context.appId, timeoutMs);
+          if (!(context as any).waitForActualSetupReady) settle(false);
+        }, timeoutMs);
         // Success path resolves straight from readyPromise (no polling lag);
         // the poll only catches teardown and pre-ready render failures.
         slideControllerRef?.readyPromise.then(
@@ -367,6 +361,7 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
         );
         const pollTimer = window.setInterval(() => {
           if (disposed || firstRenderFailed) settle(false);
+          else if (timedOut && !(context as any).waitForActualSetupReady) settle(false);
         }, 100);
       });
 
@@ -508,6 +503,7 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
 
     const setupReadyTimeout = appOptions?.setupReadyTimeout ?? DEFAULT_SLIDE_SETUP_READY_TIMEOUT;
     return waitForFirstRender(setupReadyTimeout).then(() => {
+      if (disposed) throw new Error("[Slide] disposed before first render");
       if (firstRenderFailed) {
         throw new Error("[Slide] first render failed before ready");
       }

package/src/utils/focus-transition.ts

@@ -0,0 +1,51 @@
+export type FocusTransitionHandler = (isFocused: boolean) => void | Promise<void>;
+
+export function shouldSlideRuntimeBeActive(
+  isFocused: boolean,
+  isVisible: boolean,
+  isMinimized: boolean
+): boolean {
+  return isFocused && isVisible && !isMinimized;
+}
+
+/**
+ * Drops duplicate focus states and serializes opposite resource transitions.
+ * The state tracks accepted events so an in-flight async transition cannot be
+ * started twice by duplicate host signals.
+ */
+export function createFocusTransitionQueue(
+  initialState: boolean | undefined,
+  apply: FocusTransitionHandler,
+  onError?: (error: unknown) => void
+): (isFocused: boolean, force?: boolean) => Promise<void> {
+  let acceptedState = initialState;
+  let revision = 0;
+  let queue = Promise.resolve();
+  let acceptedPromise = Promise.resolve();
+
+  return (isFocused, force = false) => {
+    // A duplicate signal must observe the same completion barrier. Returning
+    // early here would let the host commit focus while freeze/unfreeze is
+    // still running.
+    if (!force && isFocused === acceptedState) return acceptedPromise;
+    acceptedState = isFocused;
+    const transitionRevision = ++revision;
+    const transition = queue
+      .then(() => apply(isFocused))
+      .catch(error => {
+        // Permit a later same-state signal to retry only when no newer focus
+        // transition has superseded the failed request.
+        if (revision === transitionRevision) {
+          acceptedState = undefined;
+          acceptedPromise = Promise.resolve();
+        }
+        onError?.(error);
+        throw error;
+      });
+    // Keep later opposite transitions runnable after a failure, while the
+    // caller still receives the rejection for this exact transition.
+    queue = transition.catch(() => undefined);
+    acceptedPromise = transition;
+    return transition;
+  };
+}