@netless/window-manager 1.0.18 → 1.0.19

package/docs/cn/box-size-change.md

@@ -0,0 +1,144 @@
+# `boxSizeChange` 接入指南
+
+本文面向 Netless App（特别是 `@netless/app-slide`）维护者，说明如何使用
+WindowManager 提供的 `boxSizeChange` 事件同步 App 内部渲染器尺寸。
+
+## 适用场景
+
+部分旧 Android WebView 虽然提供 `ResizeObserver` API，但在 CSS transition 或连续布局变化时，
+回调可能只包含中间尺寸。此时 Box DOM 已经达到最终尺寸，App 内部渲染器仍可能保留错误的宽高。
+
+WindowManager 会在 Box 布局稳定后读取 App 内容 DOM 的实际尺寸，并通过
+`context.emitter` 发送 `boxSizeChange`。App 应使用该事件更新自己的 viewer、canvas 或 viewport，
+不再以 App 内部的 `ResizeObserver` 作为最终尺寸的唯一来源。
+
+## API
+
+```ts
+type BoxSizeChangePayload = {
+    appId: string;
+    width: number;
+    height: number;
+};
+
+context.emitter.on(
+    "boxSizeChange",
+    (payload: BoxSizeChangePayload) => void | Promise<void>
+): () => void;
+```
+
+字段说明：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `appId` | `string` | 当前 App 实例 ID，与 `context.appId` 相同 |
+| `width` | `number` | App 实际内容 DOM 的宽度，单位为 CSS pixel |
+| `height` | `number` | App 实际内容 DOM 的高度，单位为 CSS pixel |
+
+`width` 和 `height` 均为大于 0 的有限数值。它们不是 TeleBox 的相对模型尺寸，
+也不是包含标题栏和边框的整个窗口尺寸。
+
+## 触发时机
+
+以下变化完成后可能触发事件：
+
+- App setup 或 View mount；
+- Box resize 或最小尺寸约束改变；
+- 最大化、最小化、恢复和 Box 状态切换；
+- WindowManager 容器尺寸变化；
+- TeleBox 的实际视觉尺寸变化。
+
+事件采用 trailing debounce，不是逐帧 resize 事件。当前实现会在最后一次触发后等待 650ms，
+再通过两次间隔 100ms 的 DOM 采样确认尺寸。相同尺寸在 0.5px 容差内不会重复通知。
+
+因此，App 不应依赖该事件实现拖拽过程中的逐帧动画，只应把它作为最终布局尺寸的同步信号。
+
+## app-slide 接入示例
+
+建议在 `setup(context)` 开始阶段立即注册监听。Slide viewer 可能异步创建，事件到达时如果 viewer
+尚未就绪，应缓存最后一次尺寸，并在 viewer 创建完成后应用。
+
+```ts
+type BoxSize = { width: number; height: number };
+
+export async function setup(context: AppContext): Promise<void> {
+    let viewer: SlideViewer | undefined;
+    let latestBoxSize: BoxSize | undefined;
+
+    const applyBoxSize = (size: BoxSize): void => {
+        latestBoxSize = size;
+        if (!viewer) return;
+
+        // 替换为 app-slide 当前 viewer 的实际尺寸更新 API。
+        viewer.resize(size.width, size.height);
+    };
+
+    const offBoxSizeChange = context.emitter.on(
+        "boxSizeChange",
+        ({ appId, width, height }) => {
+            if (appId !== context.appId) return;
+            applyBoxSize({ width, height });
+        }
+    );
+
+    const offDestroy = context.emitter.on("destroy", () => {
+        offBoxSizeChange();
+        offDestroy();
+    });
+
+    viewer = await createSlideViewer(context);
+
+    if (latestBoxSize) {
+        applyBoxSize(latestBoxSize);
+    }
+}
+```
+
+如果 viewer 的尺寸 API 接收容器而不是数值，应在事件回调中调用对应的 layout/resize 方法，
+但尺寸来源仍应以事件的 `width`、`height` 为准。
+
+## 与 white-web-sdk View 的关系
+
+WindowManager 在发送事件前会同步 App 对应的 white-web-sdk `View.size`：
+
+```text
+App 内容 DOM 最终尺寸
+        |
+        +--> white-web-sdk View.refreshSize(width, height)
+        |
+        +--> context.emitter: boxSizeChange
+                    |
+                    +--> app-slide viewer.resize(width, height)
+```
+
+App 不需要调用 white-web-sdk 的 `View.refreshSize()`。该步骤由 WindowManager 负责；App 只需要
+更新自身的 Slide viewer。两者解决的是不同层级的内部尺寸状态。
+
+## 接入注意事项
+
+1. 不要使用 `intrinsicWidth`、`intrinsicHeight` 替代事件尺寸。它们是相对 BoxManager 容器的模型值。
+2. 不要在事件回调中再次修改 Box 宽高，否则可能形成“通知 -> 改 Box -> 再通知”的循环。
+3. viewer 初始化期间只保留最新尺寸，不需要排队执行所有历史尺寸。
+4. resize 操作应保持幂等；同一尺寸重复应用不应改变页面状态或课件同步状态。
+5. 不要把本地像素尺寸写入协作 attributes。不同客户端的容器尺寸可能不同，该尺寸仅用于本地布局。
+6. 监听器如果执行异步操作，应自行捕获业务异常。WindowManager 会记录监听器 rejection，
+   但无法替 App 恢复失败的 viewer 状态。
+
+## 验收建议
+
+至少覆盖以下场景：
+
+- App 首次打开后，viewer 尺寸与内容 DOM 一致；
+- 普通 Box resize 后，viewer 最终使用事件中的尺寸；
+- 最大化、恢复、最小化后恢复均能得到正确尺寸；
+- WindowManager 容器横竖屏切换或宿主尺寸变化后能重新同步；
+- viewer 晚于首次事件创建时，缓存的最后尺寸会被应用；
+- 连续收到相同尺寸时不会重复重建 viewer 或重置课件状态；
+- Android 8.1 / WebView 71 中 PPT 最终铺满 App 内容区域；
+- Room 与 Player、可写与只读模式下均不会因尺寸事件产生协作状态写入。
+
+## 版本要求
+
+接入方需要使用包含 `boxSizeChange` 的 WindowManager 版本或构建产物。仅升级 app-slide 而仍使用
+旧 WindowManager 时不会收到该事件。white-web-sdk 的强制 View 尺寸同步由 WindowManager 兼容层处理，
+不影响 app-slide 的事件监听代码。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netless/window-manager",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Multi-window mode for Netless Whiteboard",
   "author": "l1shen <lishen1635@gmail.com> (https://github.com/l1shen)",
   "license": "MIT",
@@ -23,7 +23,7 @@
   },
   "peerDependencies": {
     "jspdf": "2.5.1",
-    "white-web-sdk": "^2.16.56"
+    "white-web-sdk": "^2.16.57"
   },
   "peerDependenciesMeta": {
     "jspdf": {
@@ -73,6 +73,6 @@
     "typescript": "^4.5.5",
     "vite": "^2.9.9",
     "vitest": "^0.14.1",
-    "white-web-sdk": "^2.16.56"
+    "white-web-sdk": "^2.16.57"
   }
 }

package/src/App/AppBoxSizeSynchronizer.ts

@@ -0,0 +1,124 @@
+import type { View } from "white-web-sdk";
+
+export type AppBoxSize = { width: number; height: number };
+export type AppBoxSizeChange = AppBoxSize & { appId: string };
+
+type ViewWithRefreshSize = View & {
+    refreshSize?: (width: number, height: number) => void;
+    screen?: {
+        refreshSize?: (width: number, height: number) => void;
+        resizeObserver?: {
+            disconnect?: () => void;
+            observe?: (target: Element) => void;
+        };
+    };
+};
+
+const BOX_SIZE_EPSILON = 0.5;
+const BOX_SIZE_SETTLE_DELAY = 650;
+const BOX_SIZE_CONFIRM_DELAY = 100;
+
+const sizesEqual = (left: AppBoxSize | undefined, right: AppBoxSize): boolean =>
+    Boolean(
+        left &&
+            Math.abs(left.width - right.width) <= BOX_SIZE_EPSILON &&
+            Math.abs(left.height - right.height) <= BOX_SIZE_EPSILON
+    );
+
+export class AppBoxSizeSynchronizer {
+    private frame?: number;
+    private timer?: ReturnType<typeof setTimeout>;
+    private pendingSize?: AppBoxSize;
+    private lastNotifiedSize?: AppBoxSize;
+    private destroyed = false;
+
+    public constructor(
+        private readonly appId: string,
+        private readonly getView: () => View | undefined,
+        private readonly getElement: () => Element | undefined,
+        private readonly notify: (payload: AppBoxSizeChange) => void,
+        private readonly onError?: (error: unknown) => void
+    ) {}
+
+    public schedule = (): void => {
+        if (this.destroyed) return;
+        if (this.timer != null) clearTimeout(this.timer);
+        if (this.frame != null) {
+            cancelAnimationFrame(this.frame);
+            this.frame = undefined;
+        }
+        this.pendingSize = undefined;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.frame = requestAnimationFrame(this.confirmDOMSize);
+        }, BOX_SIZE_SETTLE_DELAY);
+    };
+
+    public destroy(): void {
+        this.destroyed = true;
+        if (this.timer != null) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        if (this.frame != null) {
+            cancelAnimationFrame(this.frame);
+            this.frame = undefined;
+        }
+        this.pendingSize = undefined;
+        this.lastNotifiedSize = undefined;
+    }
+
+    private confirmDOMSize = (): void => {
+        this.frame = undefined;
+        if (this.destroyed) return;
+
+        const element = this.getElement();
+        if (!element) return;
+
+        const rect = element.getBoundingClientRect();
+        const size = { width: rect.width, height: rect.height };
+        if (
+            !Number.isFinite(size.width) ||
+            !Number.isFinite(size.height) ||
+            size.width <= 0 ||
+            size.height <= 0
+        ) {
+            this.pendingSize = undefined;
+            return;
+        }
+
+        if (!sizesEqual(this.pendingSize, size)) {
+            this.pendingSize = size;
+            this.timer = setTimeout(() => {
+                this.timer = undefined;
+                this.frame = requestAnimationFrame(this.confirmDOMSize);
+            }, BOX_SIZE_CONFIRM_DELAY);
+            return;
+        }
+
+        this.pendingSize = undefined;
+        const view = this.getView() as ViewWithRefreshSize | undefined;
+        if (view && !sizesEqual(view.size, size)) {
+            try {
+                if (typeof view.refreshSize === "function") {
+                    view.refreshSize(size.width, size.height);
+                } else if (typeof view.screen?.refreshSize === "function") {
+                    const resizeObserver = view.screen.resizeObserver;
+                    resizeObserver?.disconnect?.();
+                    try {
+                        view.screen.refreshSize(size.width, size.height);
+                    } finally {
+                        if (view.divElement) resizeObserver?.observe?.(view.divElement);
+                    }
+                }
+            } catch (error) {
+                this.onError?.(error);
+            }
+        }
+
+        if (!sizesEqual(this.lastNotifiedSize, size)) {
+            this.lastNotifiedSize = size;
+            this.notify({ appId: this.appId, ...size });
+        }
+    };
+}

package/src/App/AppContext.ts

@@ -113,9 +113,11 @@ export class AppContext<TAttributes extends {} = any, TMagixEventPayloads = any,
         const view = this.getView();
         if (view) {
             view.divElement = dom as HTMLDivElement;
+            this.appProxy.scheduleBoxSizeSync();
             setTimeout(() => {
                 // 渲染需要时间，延迟 refresh
                 this.getRoom()?.refreshViewSize();
+                this.appProxy.scheduleBoxSizeSync();
                 callbacks.emit("onAppViewMounted", { appId: this.appId, view });
             }, 1000);
         }

package/src/App/AppProxy.ts

@@ -34,6 +34,7 @@ import { calculateNextIndex } from "../Page";
 import { boxEmitter } from "../BoxEmitter";
 import { callbacks } from "../callback";
 import { getExtendClass } from "../Utils/extendClass";
+import { AppBoxSizeSynchronizer } from "./AppBoxSizeSynchronizer";
 
 export type AppEmitter = Emittery<AppEmitterEvent>;
 
@@ -56,6 +57,7 @@ export class AppProxy implements PageRemoveService {
     private stateKey: string;
     private _pageState: AppPageStateImpl;
     private _prevFullPath: string | undefined;
+    private boxSizeSynchronizer: AppBoxSizeSynchronizer;
 
     public appResult?: NetlessApp<any>;
     public appContext?: AppContext<any, any>;
@@ -71,6 +73,21 @@ export class AppProxy implements PageRemoveService {
         this.stateKey = `${this.id}_state`;
         this.appProxies.set(this.id, this);
         this.appEmitter = new Emittery();
+        this.boxSizeSynchronizer = new AppBoxSizeSynchronizer(
+            this.id,
+            () => this.view,
+            () => this.view?.divElement || this.box?.$content,
+            payload => {
+                this.appEmitter.emit("boxSizeChange", payload).catch(error => {
+                    this.Logger?.error(
+                        `[WindowManager]: failed to notify app box size change: ${error}`
+                    );
+                });
+            },
+            error => {
+                this.Logger?.error(`[WindowManager]: failed to refresh app view size: ${error}`);
+            }
+        );
         this.appListener = this.makeAppEventListener(this.id);
         this.isAddApp = isAddApp;
 
@@ -104,6 +121,10 @@ export class AppProxy implements PageRemoveService {
         return this.manager.viewManager.getView(this.id);
     }
 
+    public scheduleBoxSizeSync = (): void => {
+        if (this.status !== "destroyed") this.boxSizeSynchronizer.schedule();
+    };
+
     public get viewIndex(): number | undefined {
         return this.view?.focusSceneIndex;
     }
@@ -227,6 +248,7 @@ export class AppProxy implements PageRemoveService {
                         );
                     const result = await app.setup(context);
                     this.appResult = result;
+                    this.scheduleBoxSizeSync();
                     appRegister.notifyApp(this.kind, "created", { appId, result });
                     this.afterSetupApp(boxInitState);
                     this.fixMobileSize();
@@ -542,6 +564,7 @@ export class AppProxy implements PageRemoveService {
     ) {
         if (this.status === "destroyed") return;
         this.status = "destroyed";
+        this.boxSizeSynchronizer.destroy();
         try {
             await appRegister.notifyApp(this.kind, "destroy", { appId: this.id });
             await this.appEmitter.emit("destroy", { error });

package/src/AppManager.ts

@@ -441,6 +441,15 @@ export class AppManager {
             });
             callbacks.emit("onBoxResize", payload);
         }
+        this.scheduleAppBoxSizeSync(payload.appId);
+    };
+
+    public scheduleAppBoxSizeSync = (appId?: string): void => {
+        if (appId) {
+            this.appProxies.get(appId)?.scheduleBoxSizeSync();
+        } else {
+            this.appProxies.forEach(appProxy => appProxy.scheduleBoxSizeSync());
+        }
     };
 
     private onBoxFocus = (payload: BoxFocusPayload) => {

package/src/BoxManager.ts

@@ -66,6 +66,7 @@ export type BoxManagerContext = {
     callbacks: CallbacksType;
     canOperate: () => boolean;
     notifyContainerRectUpdate: (rect: TeleBoxRect) => void;
+    scheduleAppBoxSizeSync: (appId?: string) => void;
     cleanFocus: () => void;
     setAppFocus: (appId: string) => void;
 };
@@ -96,6 +97,8 @@ export const createBoxManager = (
             canOperate: () => manager.canOperate,
             notifyContainerRectUpdate: (rect: TeleBoxRect) =>
                 manager.appManager?.notifyContainerRectUpdate(rect),
+            scheduleAppBoxSizeSync: (appId?: string) =>
+                manager.appManager?.scheduleAppBoxSizeSync(appId),
             cleanFocus: () => manager.appManager?.store.cleanFocus(),
             setAppFocus: (appId: string) => manager.appManager?.store.setAppFocus(appId, true),
             callbacks,
@@ -180,6 +183,9 @@ export class BoxManager {
                 });
             }, 200)
         );
+        this.teleBoxManager.events.on("visual_resize", (box: ReadonlyTeleBox): void => {
+            this.context.scheduleAppBoxSizeSync(box.id);
+        });
         this.teleBoxManager.events.on("focused", box => {
             if (box) {
                 if (this.canOperate) {
@@ -202,6 +208,7 @@ export class BoxManager {
         this.teleBoxManager.events.on(
             "box_status",
             (box: { id: string; boxStatus?: TeleBoxState }) => {
+                this.context.scheduleAppBoxSizeSync(box.id);
                 if (this.canOperate) {
                     this.context.setBoxStatus(box.id, box.boxStatus);
                 }
@@ -299,6 +306,7 @@ export class BoxManager {
     public setBoxesStatus(status?: Record<string, TeleBoxState>): void {
         const map = new Map(Object.entries(status ?? {}));
         this.teleBoxManager.setBoxesStatus(map, true);
+        this.context.scheduleAppBoxSizeSync();
         this.context.callbacks.emit("onBoxesStatusChange", map);
         this.context.emitter.emit("boxesStatusChange", map);
     }
@@ -409,6 +417,7 @@ export class BoxManager {
                 if (state.minimized != null) {
                     this.teleBoxManager.setMinimized(Boolean(state.minimized), true);
                 }
+                this.context.scheduleAppBoxSizeSync(box.id);
             }, 50);
             if (!state.boxStatus) {
                 this.context.callbacks.emit("boxStateChange", this.teleBoxManager.state);
@@ -422,6 +431,7 @@ export class BoxManager {
             const containerRect = { x: 0, y: 0, width: rect.width, height: rect.height };
             this.teleBoxManager.setContainerRect(containerRect);
             this.context.notifyContainerRectUpdate(this.teleBoxManager.containerRect);
+            this.context.scheduleAppBoxSizeSync();
         }
     }
 
@@ -435,6 +445,7 @@ export class BoxManager {
 
     public resizeBox({ appId, width, height, skipUpdate }: ResizeBoxParams): void {
         this.teleBoxManager.update(appId, { width, height }, skipUpdate);
+        this.context.scheduleAppBoxSizeSync(appId);
     }
 
     public setBoxMinSize(params: SetBoxMinSizeParams): void {
@@ -446,6 +457,7 @@ export class BoxManager {
             },
             true
         );
+        this.context.scheduleAppBoxSizeSync(params.appId);
     }
 
     public setBoxTitle(params: SetBoxTitleParams): void {
@@ -463,11 +475,13 @@ export class BoxManager {
     public setMaximized(maximized: boolean, skipUpdate = true): void {
         if (maximized !== this.maximized) {
             this.teleBoxManager.setMaximized(maximized, skipUpdate);
+            this.context.scheduleAppBoxSizeSync();
         }
     }
 
     public setMinimized(minimized: boolean, skipUpdate = true) {
         this.teleBoxManager.setMinimized(minimized, skipUpdate);
+        this.context.scheduleAppBoxSizeSync();
     }
 
     public focusTopBox(): void {
@@ -482,6 +496,7 @@ export class BoxManager {
 
     public updateBox(id: string, payload: TeleBoxConfig, skipUpdate = true): void {
         this.teleBoxManager.update(id, payload, skipUpdate);
+        this.context.scheduleAppBoxSizeSync(id);
     }
 
     public setReadonly(readonly: boolean) {

package/src/typings.ts

@@ -59,6 +59,8 @@ export type AppEmitterEvent<T = any> = {
     seek: number;
     pageStateChange: PageState;
     boxStatusChange: { appId: string; status: TeleBoxState };
+    /** Actual app content size in CSS pixels after the box layout is applied. */
+    boxSizeChange: { appId: string; width: number; height: number };
 };
 
 export type RegisterEventData = {