@netless/window-manager 0.4.31 → 0.4.34

package/dist/typings.d.ts

@@ -1,5 +1,5 @@
 import type Emittery from "emittery";
-import type { AnimationMode, Displayer, DisplayerState, Player, Room, SceneDefinition, SceneState, View } from "white-web-sdk";
+import type { AnimationMode, ApplianceNames, Displayer, DisplayerState, Player, Room, SceneDefinition, SceneState, View } from "white-web-sdk";
 import type { AppContext } from "./App";
 import type { ReadonlyTeleBox, TeleBoxRect } from "@netless/telebox-insider";
 import type { PageState } from "./Page";
@@ -69,6 +69,7 @@ export declare type RegisterParams<AppOptions = any, SetupResult = any, Attribut
     name?: string;
 };
 export declare type AppListenerKeys = keyof AppEmitterEvent;
+export declare type ApplianceIcons = Partial<Record<ApplianceNames, string>>;
 export type { AppContext } from "./App/AppContext";
 export type { ReadonlyTeleBox, TeleBoxRect };
 export type { SceneState, SceneDefinition, View, AnimationMode, Displayer, Room, Player };

package/docs/api.md

@@ -64,7 +64,7 @@ const manager = await WindowManager.mount(
 | disableCameraTransform | [optional] boolean                      |         | 禁用主白板的相机移动                   |
 | prefersColorScheme     | [optional] string                       | light   | auto, light, dark            |
 | debug                  | [optional] boolean                      | false   | 打印日志信息   
-
+| applianceIcons         | [optional] {ApplianceNames, string}     |         | 配置光标使用的教具图片           ｜
 
 <h3 id="register">WindowManager.register</h3>
 

package/docs/app-context.md

@@ -1,10 +1,11 @@
 ## AppContext
 
--   [api](#api)
+- [api](#api)
     - [view](#view)
     - [page](#page)
     - [storage](#storage)
--   [events](#events)
+- [events](#events)
+- [Advanced](#Advanced)
 
 <h2 id="api">API</h2>
 
@@ -16,6 +17,12 @@
     const appId = context.appId;
     ```
 
+- **context.isReplay**
+    
+    类型: `boolean`
+    
+    当前是否回放模式
+
 - **context.getDisplayer()**
 
     在默认情况下 `Displayer` 为白板的 `room` 实例
@@ -32,10 +39,10 @@
 
 - **context.getIsWritable()**
 
-    获取当前状态是否可写
+    获取当前状态是否可写\
+    可以通过监听 `writableChange` 事件获取可写状态的改变
 
     ```ts
-    // isWritable === (room.isWritable && box.readonly)
     const isWritable = context.getIsWritable();
     ```
 
@@ -50,46 +57,31 @@
     box.$footer;
     ```
 
-<h3 id="view">View</h3>
-
-`view` 可以理解为一块白板，可以从 `context` 中拿到这个实例并挂载到 `Dom` 中
-
-- **context.getView()**
+<h3 id="view">挂载白板</h3>
 
-    获取 `view` 实例
-
-    ```ts
-    const view = context.getView();
-    ```
+当应用想要一个可以涂画的白板，可以使用以下接口
 
 - **context.mountView()**
 
-    挂载 view 到指定 dom
+    挂载白板到指定 dom
 
     ```ts
     context.mountView(element);
     ```
 
-- **context.getScenes()**
-
-    `scenes` 在 `addApp` 时传入 `scenePath` 会由 `WindowManager` 创建
-
-    ```ts
-    const scenes = context.getScenes();
-    ```
-
-- **context.setScenePath()**
-
-    切换当前 `view` 到指定的 `scenePath`
-
-    ```ts
-    context.setScenePath("/page/2");
-    ```
-
+**注意** 在调用 `manager` 的 `addApp` 时必须填写 `scenePath` 才可以使用 `view`
+```ts
+manager.addApp({
+    kind: "xxx",
+    options: { // 可选配置
+        scenePath: "/example-path"
+    }
+})
+```
 
 <h3 id="page">Page</h3>
 
-`Page` 是封装后 `scenes` 的一些概念
+白板有多页的概念, 可以通过以下接口添加，切换，以及删除
 
 - **context.addPage()**
 
@@ -116,10 +108,19 @@
     ```ts
     context.prevPage();
     ```
+- **context.removePage()**
+
+    删除一页
+
+    ```ts
+    context.removePage() // 默认删除当前页
+    context.removePage(1) // 也可以指定 index 删除
+    ```
 
 - **context.pageState**
 
-    获取当前所在的 `index` 和一共有多少页
+    获取当前所在的 `index` 和一共有多少页\
+    当想要监听 `pageState` 的变化时, 可以监听 `pageStateChange` 事件获取最新的 `pageState`
 
     ```ts
     context.pageState;
@@ -141,17 +142,97 @@
     context.storage
     ```
 
-- **createStorage()**
+- **context.createStorage(namespace)**
 
     同时你也可以创建多个 `storage` 实例
+    
+    返回: `Storage<State>`
 
     ```ts
-    const defaultState = { count: 0 } // 可选
-    const storage = context.createStorage("store1", defaultState);
+    type State = { count: number };
+    const defaultState = { count: 0 };
+    const storage = context.createStorage<State>("store1", defaultState);
     ```
 
+- **storage.state**
+
+  类型: `State`\
+  默认值: `defaultState`
+
+  在所有客户端之间同步的状态，调用 `storage.setState()` 来改变它。
+
+- **storage.ensureState(partialState)**
+
+  确保 `storage.state` 包含某些初始值，类似于执行了：
+
+  ```js
+  // 这段代码不能直接运行，因为 app.state 是只读的
+  storage.state = { ...partialState, ...storage.state };
+  ```
 
+  **partialState**
 
+  类型: `Partial<State>`
+
+  ```js
+  storage.state; // { a: 1 }
+  storage.ensureState({ a: 0, b: 0 });
+  storage.state; // { a: 1, b: 0 }
+  ```
+
+- **storage.setState(partialState)**
+
+  和 React 的 `setState` 类似，更新 `storage.state` 并同步到所有客户端。
+
+  当设置某个字段为 `undefined` 时，它会被从 `storage.state` 里删除。
+
+  > - 状态同步所需的时间和网络状态与数据大小有关，建议只在 state 里存储必须的数据。
+
+  **partialState**
+
+  类型: `Partial<State>`
+
+  ```js
+  storage.state; //=> { count: 0, a: 1 }
+  storage.setState({ count: storage.state.count + 1, b: 2 });
+  storage.state; //=> { count: 1, a: 1, b: 2 }
+  ```
+
+- **storage.addStateChangedListener(listener)**
+
+  它在有人调用 `storage.setState()` 后触发 (包含当前 `storage`)
+
+  返回: `() => void`
+
+  ```js
+  const disposer = storage.addStateChangedListener(diff => {
+    console.log("state changed", diff.oldValue, diff.newValue);
+    disposer(); // remove listener by calling disposer
+  });
+  ```
+
+- **context.dispatchMagixEvent(event, payload)**
+
+  向其他客户端广播事件消息
+
+  ```js
+  context.dispatchMagixEvent("click", { data: "data" });
+  ```
+
+- **context.addMagixEventListener(event, listener)**
+
+  当接收来自其他客户端的消息时(当其他客户端调用'context.dispatchMagixEvent()`时), 它会被触发
+
+  返回: `() => void` a disposer function.
+
+  ```js
+  const disposer = context.addMagixEventListener("click", ({ payload }) => {
+    console.log(payload.data);
+    disposer();
+  });
+
+  context.dispatchMagixEvent("click", { data: "data" });
+  ```
 
 <h2 id="events">events</h2>
 
@@ -203,3 +284,13 @@
         // { index: 0, length: 1 }
     });
     ```
+
+<h2 id="Advanced">Advanced</h2>
+
+- **context.getView()**
+
+    获取 `view` 实例
+
+    ```ts
+    const view = context.getView();
+    ```

package/docs/develop-app.md

@@ -49,7 +49,7 @@ const Counter: NetlessApp<{ count: number }> = {
         countDom.innerText = storage.state.count.toString();
         $content.appendChild(countDom);
 
-        // state 变化回调
+        // 监听 state 变化回调
         storage.addStateChangedListener(diff => {
             if (diff.count) {
                 // diff 会给出 newValue 和 oldValue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netless/window-manager",
-  "version": "0.4.31",
+  "version": "0.4.34",
   "description": "",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",

package/src/App/AppProxy.ts

@@ -204,6 +204,10 @@ export class AppProxy implements PageRemoveService {
             });
             if (this.isAddApp && this.box) {
                 this.store.updateAppState(appId, AppAttributes.ZIndex, this.box.zIndex);
+                this.store.updateAppState(appId, AppAttributes.Size, {
+                    width: this.box.intrinsicWidth,
+                    height: this.box.intrinsicHeight
+                });
                 this.boxManager.focusBox({ appId }, false);
             }
         } catch (error: any) {

package/src/AppManager.ts

@@ -785,6 +785,7 @@ export class AppManager {
     }
 
     public async onReconnected() {
+        this.attributesUpdateCallback(this.attributes.apps);
         const appProxies = Array.from(this.appProxies.values());
         const reconnected = appProxies.map(appProxy => {
             return appProxy.onReconnected();

package/src/Cursor/Cursor.ts

@@ -1,5 +1,4 @@
 import App from "./Cursor.svelte";
-import { ApplianceMap } from "./icons";
 import { ApplianceNames } from "white-web-sdk";
 import { findMemberByUid } from "../Helper";
 import { omit } from "lodash";
@@ -159,8 +158,9 @@ export class Cursor {
 
     private getIcon() {
         if (this.member) {
-            const applianceSrc = ApplianceMap[this.memberApplianceName || ApplianceNames.shape];
-            return applianceSrc || ApplianceMap[ApplianceNames.shape];
+            const icons = this.cursorManager.applianceIcons;
+            const applianceSrc = icons[this.memberApplianceName || ApplianceNames.shape];
+            return applianceSrc || icons[ApplianceNames.shape];
         }
     }
 

package/src/Cursor/index.ts

@@ -5,10 +5,11 @@ import { emitter } from "../InternalEmitter";
 import { SideEffectManager } from "side-effect-manager";
 import { throttle } from "lodash";
 import { WindowManager } from "../index";
-import type { CursorMovePayload } from "../index";
+import type { CursorMovePayload , ApplianceIcons} from "../index";
 import type { PositionType } from "../AttributesDelegate";
 import type { Point, RoomMember, View } from "white-web-sdk";
 import type { AppManager } from "../AppManager";
+import { ApplianceMap } from "./icons";
 
 export type EventType = {
     type: PositionType;
@@ -20,6 +21,7 @@ export type MoveCursorParams = {
     x: number;
     y: number;
 };
+
 export class CursorManager {
     public containerRect?: DOMRect;
     public wrapperRect?: DOMRect;
@@ -28,8 +30,9 @@ export class CursorManager {
     private mainViewElement?: HTMLDivElement;
     private sideEffectManager = new SideEffectManager();
     private store = this.manager.store;
+    public applianceIcons: ApplianceIcons = ApplianceMap;
 
-    constructor(private manager: AppManager, private enableCursor: boolean) {
+    constructor(private manager: AppManager, private enableCursor: boolean, applianceIcons?: ApplianceIcons) {
         this.roomMembers = this.manager.room?.state.roomMembers;
         const wrapper = WindowManager.wrapper;
         if (wrapper) {
@@ -42,6 +45,9 @@ export class CursorManager {
         this.sideEffectManager.add(() => {
             return emitter.on("playgroundSizeChange", () => this.updateContainerRect());
         });
+        if (applianceIcons) {
+            this.applianceIcons = { ...ApplianceMap, ...applianceIcons };
+        }
     }
 
     private onCursorMove = (payload: CursorMovePayload) => {

package/src/Helper.ts

@@ -1,4 +1,5 @@
-import { getVersionNumber } from "./Utils/Common";
+import { getVersionNumber, wait } from "./Utils/Common";
+import { log } from "./Utils/log";
 import { REQUIRE_VERSION } from "./constants";
 import { WhiteVersion } from "white-web-sdk";
 import { WhiteWebSDKInvalidError } from "./Utils/error";
@@ -45,3 +46,18 @@ export const findMemberByUid = (room: Room | undefined, uid: string) => {
     const roomMembers = room?.state.roomMembers;
     return roomMembers?.find(member => member.payload?.uid === uid);
 };
+
+export const createInvisiblePlugin = async (room: Room) => {
+    try {
+        const manager = (await room.createInvisiblePlugin(WindowManager, {})) as WindowManager;
+        return manager;
+    } catch (error) {
+        // 如果有两个用户同时调用 WindowManager.mount 有概率出现这个错误
+        if (error.message === `invisible plugin "WindowManager" exits`) {
+            await wait(200);
+            return room.getInvisiblePlugin(WindowManager.kind) as WindowManager;
+        } else {
+            log("createInvisiblePlugin failed", error);
+        }
+    }
+};

package/src/ReconnectRefresher.ts

@@ -4,6 +4,7 @@ import { RoomPhase } from "white-web-sdk";
 import type { Room } from "white-web-sdk";
 import type { EmitterType } from "./InternalEmitter";
 import { EnsureReconnectEvent } from "./constants";
+import { wait } from "./Utils/Common";
 
 export type ReconnectRefresherContext = {
     emitter: EmitterType;
@@ -41,19 +42,24 @@ export class ReconnectRefresher {
         this.ctx = ctx;
     }
 
-    private onPhaseChanged = (phase: RoomPhase) => {
+    private onPhaseChanged = async (phase: RoomPhase) => {
         if (phase === RoomPhase.Reconnecting) {
             this.ctx.emitter.emit("startReconnect");
         }
         if (phase === RoomPhase.Connected && this.phase === RoomPhase.Reconnecting) {
-            this.room?.dispatchMagixEvent(EnsureReconnectEvent, {});
+            if (this.room?.isWritable) {
+                this.room?.dispatchMagixEvent(EnsureReconnectEvent, {});
+            } else {
+                await wait(500);
+                this.onReconnected();
+            }
         }
         this.phase = phase;
     };
 
     private onReconnected = debounce(() => {
         this._onReconnected();
-    }, 3000);
+    }, 1000);
 
     private _onReconnected = () => {
         log("onReconnected refresh reactors");

package/src/index.ts

@@ -2,7 +2,7 @@ import pRetry from "p-retry";
 import { AppManager } from "./AppManager";
 import { appRegister } from "./Register";
 import { callbacks } from "./callback";
-import { checkVersion, setupWrapper } from "./Helper";
+import { checkVersion, createInvisiblePlugin, setupWrapper } from "./Helper";
 import { ContainerResizeObserver } from "./ContainerResizeObserver";
 import { createBoxManager } from "./BoxManager";
 import { CursorManager } from "./Cursor";
@@ -29,13 +29,7 @@ import {
     wait,
 } from "./Utils/Common";
 import type { TELE_BOX_STATE, BoxManager } from "./BoxManager";
-import {
-    AppCreateError,
-    AppManagerNotInitError,
-    BindContainerRoomPhaseInvalidError,
-    InvalidScenePath,
-    ParamsInvalidError,
-} from "./Utils/error";
+import * as Errors from "./Utils/error";
 import type { Apps, Position } from "./AttributesDelegate";
 import type {
     Displayer,
@@ -54,7 +48,7 @@ import type {
     SceneState,
 } from "white-web-sdk";
 import type { AppListeners } from "./AppListener";
-import type { NetlessApp, RegisterParams } from "./typings";
+import type { ApplianceIcons, NetlessApp, RegisterParams } from "./typings";
 import type { TeleBoxColorScheme, TeleBoxState } from "@netless/telebox-insider";
 import type { AppProxy } from "./App";
 import type { PublicEvent } from "./callback";
@@ -143,6 +137,7 @@ export type MountParams = {
     debug?: boolean;
     disableCameraTransform?: boolean;
     prefersColorScheme?: TeleBoxColorScheme;
+    applianceIcons?: ApplianceIcons;
 };
 
 export const reconnectRefresher = new ReconnectRefresher({ emitter });
@@ -238,7 +233,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
 
         manager.appManager = new AppManager(manager);
         manager._pageState = new PageStateImpl(manager.appManager);
-        manager.cursorManager = new CursorManager(manager.appManager, Boolean(cursor));
+        manager.cursorManager = new CursorManager(manager.appManager, Boolean(cursor), params.applianceIcons);
         if (containerSizeRatio) {
             manager.containerSizeRatio = containerSizeRatio;
         }
@@ -259,8 +254,8 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         return manager;
     }
 
-    private static async initManager(room: Room): Promise<WindowManager> {
-        let manager = room.getInvisiblePlugin(WindowManager.kind) as WindowManager;
+    private static async initManager(room: Room): Promise<WindowManager | undefined> {
+        let manager = room.getInvisiblePlugin(WindowManager.kind) as WindowManager | undefined;
         if (!manager) {
             if (isRoom(room)) {
                 if (room.isWritable === false) {
@@ -269,18 +264,12 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
                     } catch (error) {
                         throw new Error("[WindowManger]: room must be switched to be writable");
                     }
-                    manager = (await room.createInvisiblePlugin(
-                        WindowManager,
-                        {}
-                    )) as WindowManager;
-                    manager.ensureAttributes();
+                    manager = await createInvisiblePlugin(room);
+                    manager?.ensureAttributes();
                     await wait(500);
                     await room.setWritable(false);
                 } else {
-                    manager = (await room.createInvisiblePlugin(
-                        WindowManager,
-                        {}
-                    )) as WindowManager;
+                    manager = await createInvisiblePlugin(room);
                 }
             }
         }
@@ -322,7 +311,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
 
     public bindContainer(container: HTMLElement) {
         if (isRoom(this.displayer) && this.room.phase !== RoomPhase.Connected) {
-            throw new BindContainerRoomPhaseInvalidError();
+            throw new Errors.BindContainerRoomPhaseInvalidError();
         }
         if (WindowManager.isCreated && WindowManager.container) {
             if (WindowManager.container.firstChild) {
@@ -408,19 +397,19 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
                 return this._addApp(params);
             }
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
     private async _addApp<T = any>(params: AddAppParams<T>): Promise<string | undefined> {
         if (this.appManager) {
             if (!params.kind || typeof params.kind !== "string") {
-                throw new ParamsInvalidError();
+                throw new Errors.ParamsInvalidError();
             }
             const appImpl = await appRegister.appClasses.get(params.kind)?.();
             if (appImpl && appImpl.config?.singleton) {
                 if (this.appManager.appProxies.has(params.kind)) {
-                    throw new AppCreateError();
+                    throw new Errors.AppCreateError();
                 }
             }
             const isDynamicPPT = this.setupScenePath(params, this.appManager);
@@ -433,7 +422,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
             const appId = await this.appManager.addApp(params, Boolean(isDynamicPPT));
             return appId;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -443,7 +432,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
             const { scenePath, scenes } = params.options;
             if (scenePath) {
                 if (!isValidScenePath(scenePath)) {
-                    throw new InvalidScenePath();
+                    throw new Errors.InvalidScenePath();
                 }
                 const apps = Object.keys(this.apps || {});
                 for (const appId of apps) {
@@ -646,7 +635,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.mainViewProxy.view;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -654,7 +643,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.mainViewProxy.view.camera;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -662,7 +651,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.mainViewProxy.cameraState;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -674,7 +663,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.boxManager?.boxState;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -686,7 +675,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager.boxManager?.prefersColorScheme;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -706,7 +695,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this.appManager) {
             return this.appManager?.getMainViewSceneDir();
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -731,7 +720,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             return this.appManager.sceneState!;
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 
@@ -739,7 +728,7 @@ export class WindowManager extends InvisiblePlugin<WindowMangerAttributes> imple
         if (this._pageState) {
             return this._pageState.toObject();
         } else {
-            throw new AppManagerNotInitError();
+            throw new Errors.AppManagerNotInitError();
         }
     }
 

package/src/typings.ts

@@ -1,6 +1,7 @@
 import type Emittery from "emittery";
 import type {
     AnimationMode,
+    ApplianceNames,
     Displayer,
     DisplayerState,
     Player,
@@ -75,6 +76,8 @@ export type RegisterParams<AppOptions = any, SetupResult = any, Attributes = any
 
 export type AppListenerKeys = keyof AppEmitterEvent;
 
+export type ApplianceIcons = Partial<Record<ApplianceNames, string>>;
+
 export type { AppContext } from "./App/AppContext";
 export type { ReadonlyTeleBox, TeleBoxRect };
 export type { SceneState, SceneDefinition, View, AnimationMode, Displayer, Room, Player };