@netless/app-slide 0.2.105 → 0.2.106-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netless/app-slide",
-  "version": "0.2.105",
+  "version": "0.2.106-beta.1",
   "main": "dist/main.cjs.js",
   "module": "dist/main.es.js",
   "types": "dist/index.d.ts",
@@ -17,11 +17,11 @@
     "README-zh.md"
   ],
   "devDependencies": {
-    "@netless/slide": "1.4.60",
+    "@juggle/resize-observer": "^3.3.1",
+    "@netless/slide": "1.4.61-beta.0",
     "@types/color-string": "^1.5.2",
     "color-string": "^1.9.1",
     "jspdf": "2.5.1",
-    "@juggle/resize-observer": "^3.3.1",
     "side-effect-manager": "^1.2.1",
     "vanilla-lazyload": "^17.8.3"
   },

package/src/DocsViewer/ResizableContainer.ts

@@ -35,6 +35,7 @@ export class ResizableContainer {
     enableResize: boolean,
     _box?: ReadonlyTeleBox
   ) {
+    void _box;
     this.enableResize = enableResize;
     this.parent = parent;
     this.context = context;
@@ -130,9 +131,6 @@ export class ResizableContainer {
       }
     }
 
-    this.translateX = 0.5;
-    this.translateY = 0.5;
-
     this.renderScrollBar(
       parentBounds.width,
       parentBounds.width * this.scale,
@@ -141,7 +139,8 @@ export class ResizableContainer {
     );
     this.handleNormalizeTranslate(this.translateX, this.translateY, {
       triggerScrollBar: true,
-      triggerSync: true,
+      triggerSync: false,
+      force: true,
     });
 
     // enableScale / scaleView 只改变内部 container 的像素尺寸，box 本身不变。
@@ -158,12 +157,14 @@ export class ResizableContainer {
     options: {
       triggerScrollBar: boolean;
       triggerSync: boolean;
+      force?: boolean;
     }
   ) {
     if (
       Math.abs(x - this.translateX) < 0.001 &&
       Math.abs(y - this.translateY) < 0.001 &&
-      !options.triggerSync
+      !options.triggerSync &&
+      !options.force
     ) {
       return;
     }
@@ -230,6 +231,7 @@ export class ResizableContainer {
   }
 
   public destroy(_box?: ReadonlyTeleBox): void {
+    void _box;
     this.cancelScheduledLayoutUpdate();
     this.onLayoutUpdated = null;
     this.scaleChangedListeners.clear();

package/src/SlideController/index.ts

@@ -355,14 +355,16 @@ export class SlideControllerBase {
   }
 
   protected destroyed = false;
+  protected destroyPromise?: Promise<void>;
 
-  public destroy() {
+  public destroy(): Promise<void> {
     this.sideEffect.flushAll();
     if (!this.destroyed) {
       log("[Slide] destroy slide (once)");
-      this.slide.destroy();
       this.destroyed = true;
+      this.destroyPromise = Promise.resolve(this.slide.destroy());
     }
+    return this.destroyPromise ?? Promise.resolve();
   }
 
   public timestamp = () => {
@@ -378,28 +380,30 @@ export class SlideControllerBase {
   public isFrozen = false;
   protected _toFreeze: -1 | 0 | 1 = 0; // -1: unfreeze, 0: no change, 1: freeze
 
-  public freeze = () => {
+  public freeze = (): Promise<void> => {
     this.isFrozen = true;
     if (this.ready) {
       log("[Slide] freeze", this.context.appId);
       if (this.invisibleBehavior === "frozen") {
-        this.slide.frozen();
+        return Promise.resolve(this.slide.frozen());
       } else {
         this.slide.pause();
       }
     } else {
       this._toFreeze = 1;
     }
+    return Promise.resolve();
   };
 
-  public unfreeze = async () => {
+  public unfreeze = async (): Promise<void> => {
     if (!this.visible) return;
+    if (!this.isFrozen && this.ready) return;
     this.isFrozen = false;
     if (this.ready) {
       let isNeedSyncState = false;
       log("[Slide] unfreeze", this.context.appId);
       if (this.invisibleBehavior === "frozen") {
-        this.slide.release(() => {
+        await this.slide.release(() => {
           // release 会重建 player，内部 observer 已关闭，需要按当前 frame 尺寸重绘
           this.slide.notifyFrameResize();
         });

package/src/SlideDocsViewer/index.ts

@@ -163,6 +163,13 @@ export class SlideDocsViewer {
         console.log("[SlideDocsViewer] No initial slideScale found");
       }
 
+      const initialTranslateX = this.context.storage.state.translateX ?? 0.5;
+      const initialTranslateY = this.context.storage.state.translateY ?? 0.5;
+      this.resizableContainer.handleNormalizeTranslate(initialTranslateX, initialTranslateY, {
+        triggerScrollBar: true,
+        triggerSync: false,
+      });
+
       const handler: StorageStateChangedListener<Attributes> = diff => {
         if (diff.slideScale !== undefined) {
           // slideScale 是一个包含 newValue 和 oldValue 的对象
@@ -221,7 +228,7 @@ export class SlideDocsViewer {
         this.viewer.$content,
         this.context,
         this.enableScale,
-        this.box,
+        this.box
       );
       this.resizableContainer.onLayoutUpdated = () => {
         this.scaleDocsToFit();
@@ -384,7 +391,10 @@ export class SlideDocsViewer {
     this.latestBoxSize = { width: payload.width, height: payload.height };
 
     // observer 已经先处理过同一尺寸时，忽略晚到的 event
-    if (sizesEqual(this.lastObserverSize, this.latestBoxSize) || sizesEqual(this.lastAppliedSize, this.latestBoxSize)) {
+    if (
+      sizesEqual(this.lastObserverSize, this.latestBoxSize) ||
+      sizesEqual(this.lastAppliedSize, this.latestBoxSize)
+    ) {
       console.log("[app-slide] boxSizeChange skipped, observer already applied", {
         appId: this.appId,
         eventCount: this.boxSizeEventCount,
@@ -455,14 +465,15 @@ export class SlideDocsViewer {
     return (page > 0 ? page : 1) - 1;
   }
 
-  public unmount() {
+  public async unmount(): Promise<this> {
     this.offBoxSizeChange?.();
     this.offBoxSizeChange = undefined;
     this.contentResizeObserver?.disconnect();
     this.contentResizeObserver = undefined;
     if (this.slideController) {
-      this.slideController.destroy();
+      const controller = this.slideController;
       this.slideController = null;
+      await controller.destroy();
     }
     this.viewer.unmount();
     this.resizableContainer.destroy(this.box);
@@ -473,9 +484,9 @@ export class SlideDocsViewer {
     this.viewer.setReadonly(readonly);
   }
 
-  public destroy() {
+  public async destroy(): Promise<void> {
     this.sideEffect.flushAll();
-    this.unmount();
+    await this.unmount();
     this.viewer.destroy();
   }
 
@@ -489,9 +500,10 @@ export class SlideDocsViewer {
       const { width: slideWidth, height: slideHeight } = this.slideController.slide;
       if (slideWidth && slideHeight) {
         const originSize = this.context.storage.state.originSize;
-        const { width, height } = originSize && originSize.width > 0 && originSize.height > 0
-          ? originSize
-          : { width: slideWidth, height: slideHeight };
+        const { width, height } =
+          originSize && originSize.width > 0 && originSize.height > 0
+            ? originSize
+            : { width: slideWidth, height: slideHeight };
         if (width > 0 && height > 0) {
           this.whiteboardView.moveCameraToContain({
             originX: -width / 2,

package/src/SlidePreviewer/index.ts

@@ -184,12 +184,14 @@ export class SlidePreviewer {
   };
 
   protected destroyed = false;
-  public destroy() {
+  protected destroyPromise?: Promise<void>;
+  public async destroy(): Promise<void> {
     this.sideEffect.flushAll();
     if (this.slide && !this.destroyed) {
-      this.slide.destroy();
       this.destroyed = true;
+      this.destroyPromise = Promise.resolve(this.slide.destroy());
     }
+    await this.destroyPromise;
     this.viewer.destroy();
   }
 

package/src/index.ts

@@ -37,6 +37,8 @@ export const usePlugin: (plugin: any) => any = /* @__PURE__ */ Slide.usePlugin.b
 
 export const version = __APP_VERSION__;
 
+const DEFAULT_SLIDE_SETUP_READY_TIMEOUT = 5_000;
+
 export { DefaultUrl, apps, FreezerLength, addHooks, useFreezer, log, logger };
 
 export { setFreezerLength, getFreezerLength, onCreated, onDestroyed } from "./utils/freezer";
@@ -87,6 +89,11 @@ export interface AppOptions
   enableScale?: boolean;
   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.
+   */
+  setupReadyTimeout?: number;
 }
 
 export interface ILogger {
@@ -115,7 +122,9 @@ export interface AppResult {
   playPptMedia: () => void;
 }
 
-const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> = {
+const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> & {
+  teardown(context: import("@netless/window-manager").AppContext): Promise<void>;
+} = {
   kind: "Slide",
   setup(context) {
     console.log("[Slide] setup @ " + version);
@@ -133,6 +142,8 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> = {
       throw new Error("[Slide] no view, please set scenePath on addApp()");
     }
     view.disableCameraTransform = true;
+    const isLazySetupMode = (): boolean =>
+      (context.getWindowManager() as any)?.lazySetupInMaximizedMode === true;
 
     const box = context.getBox();
     box.mountStyles(styles);
@@ -146,6 +157,10 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> = {
     const baseScenePath = context.getInitScenePath() as string;
 
     let docsViewer: SlideDocsViewer | null = null;
+    // Serial setup queue support: capture the controller so setup() can await
+    // its first render before WindowManager starts the next app's setup.
+    let slideControllerRef: SlideController | null | undefined;
+    let firstRenderFailed = false;
 
     const onPageChanged = (page: number) => {
       const room = context.getRoom();
@@ -174,17 +189,29 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> = {
         ...options,
         onPageChanged,
         onNavigate: options.onNavigate,
-        onRenderError: appOptions.onRenderError,
+        // Wrap the user callback: a render failure before the first
+        // renderEnd also fails the setup wait (serial setup queue).
+        onRenderError: (error, pageIndex) => {
+          firstRenderFailed = true;
+          appOptions.onRenderError?.(error, pageIndex);
+        },
         showRenderError: appOptions.showRenderError,
         invisibleBehavior: appOptions.invisibleBehavior,
       });
-      if (useFreezer) apps.set(context.appId, slideController, box);
+      slideControllerRef = slideController;
+      // The legacy addHooks freezer is not awaitable across App instances.
+      // Lazy WindowManager mode owns freeze/release ordering through the
+      // per-App focus lifecycle instead.
+      if (useFreezer && !isLazySetupMode()) apps.set(context.appId, slideController, box);
       logger.setAppController(context.appId, slideController);
       if (import.meta.env.DEV) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (window as any).slideController = slideController;
       }
       slideController.readyPromise.then(options.onReady).then(() => {
+        // Teardown may have destroyed the box while this deferred callback
+        // was pending; syncing scenes against a destroyed app throws.
+        if (disposed) return;
         const room = context.getRoom();
         let synced = false;
         if (room && context.getIsWritable()) {
@@ -249,19 +276,91 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> = {
       });
     }
 
-    context.emitter.on("destroy", () => {
+    // Blur freeze (same semantics as the Presentation blur thumbnail
+    // degradation): while the app is cached and loses focus in a
+    // maximized/minimized workspace, freeze the slide (destroy the player,
+    // keep a snapshot); on focus, unfreeze. Freezing is skipped in normal
+    // mode where several windows are visible side by side. The whole flow is
+    // 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) => {
+        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();
+        }
+      })
+    );
+
+    let disposed = false;
+    let offDestroy: (() => void) | undefined;
+    const teardown = async (): Promise<void> => {
+      if (disposed) return;
+      disposed = true;
+      const removeDestroy = offDestroy;
+      offDestroy = undefined;
+      removeDestroy?.();
       log("[Slide] destroy", context.appId);
       if (useFreezer) apps.delete(context.appId);
       sideEffect.flushAll();
       if (docsViewer) {
-        docsViewer.destroy();
+        const viewer = docsViewer;
         docsViewer = null;
+        await viewer.destroy();
       }
-    });
+    };
+    offDestroy = context.emitter.on("destroy", teardown);
 
     docsViewer.mount();
 
-    return {
+    (SlideApp as any).__teardownByContext ||= new WeakMap<object, () => Promise<void>>();
+    (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.
+    const waitForFirstRender = (timeoutMs: number): Promise<boolean> =>
+      new Promise<boolean>(resolve => {
+        let settled = false;
+        const settle = (loaded: boolean) => {
+          if (settled) return;
+          settled = true;
+          window.clearTimeout(timeoutTimer);
+          window.clearInterval(pollTimer);
+          resolve(loaded);
+        };
+        const timeoutTimer = window.setTimeout(() => 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(
+          () => settle(!firstRenderFailed),
+          () => settle(false)
+        );
+        const pollTimer = window.setInterval(() => {
+          if (disposed || firstRenderFailed) settle(false);
+        }, 100);
+      });
+
+    const appResult: AppResult = {
       onPptMediaPermissionRequest: callback => {
         const slide = docsViewer?.slideController?.slide;
         return slide?.onPptMediaPermissionRequest(callback) ?? (() => undefined);
@@ -286,6 +385,10 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> = {
           translateX: 0.5,
           translateY: 0.5,
         });
+        container.handleNormalizeTranslate(0.5, 0.5, {
+          triggerScrollBar: true,
+          triggerSync: false,
+        });
         container.scaleContainer(applyScale);
       },
       getViewScale: () => {
@@ -392,6 +495,21 @@ const SlideApp: NetlessApp<Attributes, MagixEvents, AppOptions, AppResult> = {
         return false;
       },
     };
+
+    const setupReadyTimeout = appOptions?.setupReadyTimeout ?? DEFAULT_SLIDE_SETUP_READY_TIMEOUT;
+    return waitForFirstRender(setupReadyTimeout).then(() => {
+      if (firstRenderFailed) {
+        throw new Error("[Slide] first render failed before ready");
+      }
+      if (!disposed && !slideControllerRef?.ready) {
+        log("[Slide] setup ready wait timed out, slide keeps loading in background");
+      }
+      return appResult;
+    }) as unknown as AppResult;
+  },
+  async teardown(context) {
+    await (SlideApp as any).__teardownByContext?.get(context)?.();
+    (SlideApp as any).__teardownByContext?.delete(context);
   },
 };