@netless/appliance-plugin 1.1.36-beta.0 → 1.1.36-beta.2

package/READMA.zh-CN.md

@@ -47,6 +47,10 @@ appliance-plugin 是一个高性能的白板绘制插件，依赖 [white-web-sdk
 npm install @netless/appliance-plugin
 ```
 
+> **Fastboard full 包说明：** 如果你是通过 `@netless/fastboard-full` 或 `@netless/fastboard-react-full` 配合 `enableAppliancePlugin` 使用，请安装带有 `./bridge` 导出的 `@netless/appliance-plugin` 版本，建议 `>= 1.1.35`（`./bridge` 首次出现在 `>= 1.1.34-beta.2`）。
+>
+> 业务代码继续引用 `@netless/appliance-plugin` 即可，不需要也不建议手动改成 `@netless/appliance-plugin/bridge`。`@netless/appliance-plugin/bridge` 由 fastboard full 在内部加载，用来复用 full 内部已经 bundled 的 `white-web-sdk` runtime。
+
 ### 注册插件
 
 插件可以支持两种场景,它们接入插件命名不同:
@@ -59,34 +63,13 @@ import { ApplianceMultiPlugin } from '@netless/appliance-plugin';
 import { ApplianceSinglePlugin } from '@netless/appliance-plugin';
 ```
 
-> **worker.js 文件与 CDN / 静态资源**
->
-> 我们采用双 worker 并发来提高绘制效率，比主线程效率提高 40% 以上。两个 worker 文件的公共依赖重复，直接打进包体会显著增加体积，因此推荐通过 `options.cdn` 指定 worker 地址，有两种常见方式：
->
-> 1. **CDN 方式**：将 `@netless/appliance-plugin/cdn` 下的 `fullWorker.js`、`subWorker.js` 部署到 CDN，在插件的 `getInstance` 的第二个参数 `options.cdn` 中传入这两个文件的 CDN 地址（`fullWorkerUrl`、`subWorkerUrl`）。
-> ***注意***：CDN 配置的 URL 必须同源，否则 worker 线程会无法加载。
->
-> 2. **静态资源方式**：将 `fullWorker.js`、`subWorker.js` 放到项目的静态目录（如 Vite 的 `public/`），不参与打包。在代码中基于 `import.meta.env.BASE_URL`（或等效的 publicPath）拼出完整 URL，传入 `options.cdn`。同源请求、不占打包体积，也无需 Blob 内联，内存占用更小。
->
-> 若需控制包体积，请使用上述任一方式配置 `options.cdn`。
-
 ### 接入方式参考
 
-#### 引入worker.js
+#### 准备 worker URL
 ```js
-// 引入 worker 方式三选一：
-// 方式一：静态资源（推荐）- 将 fullWorker.js、subWorker.js 放到 public 等静态目录，同源请求、不占打包体积
-const workerBase = (import.meta.env.BASE_URL || '/').replace(/\/?$/, '/');
-const fullWorkerUrl = workerBase + 'fullWorker.js';
-const subWorkerUrl = workerBase + 'subWorker.js';
-
-// 方式二：CDN - 将 @netless/appliance-plugin/cdn 下文件部署到 CDN 后，此处写 CDN 地址、不占打包体积 注意: 域名一定要同源
-const fullWorkerUrl = 'https://your-cdn.com/fullWorker.js';
-const subWorkerUrl = 'https://your-cdn.com/subWorker.js';
-
-// 方式三：从 dist 以 ?raw 内联为 Blob（需打包器支持 ?raw，如 Vite / webpack raw-loader）这种方式会占用一定内存.
 import fullWorkerString from '@netless/appliance-plugin/dist/fullWorker.js?raw';
 import subWorkerString from '@netless/appliance-plugin/dist/subWorker.js?raw';
+
 const fullWorkerUrl = URL.createObjectURL(new Blob([fullWorkerString], { type: 'text/javascript' }));
 const subWorkerUrl = URL.createObjectURL(new Blob([subWorkerString], { type: 'text/javascript' }));
 ```
@@ -99,7 +82,7 @@ const subWorkerUrl = URL.createObjectURL(new Blob([subWorkerString], { type: 'te
 // 分包引用
 import { useFastboard, Fastboard } from "@netless/fastboard-react";
 
-// 引入 worker 方式三选一：
+// 按上文方式准备 worker URL：
 const fullWorkerUrl = ...;
 const subWorkerUrl = ...;
 
@@ -130,7 +113,7 @@ const app = useFastboard(() => ({
 // 分包引用
 import { createFastboard, createUI } from "@netless/fastboard";
 
-// 引入 worker 方式三选一：
+// 按上文方式准备 worker URL：
 const fullWorkerUrl = ...;
 const subWorkerUrl = ...;
 
@@ -156,6 +139,8 @@ const fastboard = await createFastboard({
   });
 ```
 
+> **注意：** 在 fastboard full 模式下，`@netless/fastboard-full` / `@netless/fastboard-react-full` 会在内部加载 `@netless/appliance-plugin/bridge`。业务代码只需要配置 `enableAppliancePlugin` 并提供 worker 地址，同时继续引用 `@netless/appliance-plugin` 即可；不需要也不建议手动引入 `@netless/appliance-plugin/bridge`。
+
 #### 多窗口(直接对接window-manager)
 
 ```js
@@ -167,7 +152,7 @@ import { WhiteWebSdk } from "white-web-sdk";
 import { WindowManager } from "@netless/window-manager";
 import { ApplianceMultiPlugin } from '@netless/appliance-plugin';
 
-// 引入 worker 方式三选一：
+// 按上文方式准备 worker URL：
 const fullWorkerUrl = ...;
 const subWorkerUrl = ...;
 
@@ -205,7 +190,7 @@ import '@netless/appliance-plugin/dist/style.css';
 import { WhiteWebSdk } from "white-web-sdk";
 import { ApplianceSinglePlugin, ApplianceSigleWrapper } from '@netless/appliance-plugin';
 
-// 引入 worker 方式三选一：
+// 按上文方式准备 worker URL：
 const fullWorkerUrl = ...;
 const subWorkerUrl = ...;
 
@@ -330,6 +315,36 @@ injectMethodToObject(windowmanager.mainView,'setMemberState');
 - `updateMarkmap` - 修改白板中的markdow文本 (Version >=1.1.32) **该方法需要开启extras.useBackgroundThread**
 - `insertBackgroundImage` - 插入白板的背景图片 (Version >=1.1.32) **该方法需要开启extras.useBackgroundThread**
 
+6. Selector / Element 扩展接口
+- `getSelectedElements(viewId?)` - 获取当前 selector 选中快照
+- `blurSelector(viewId?)` - 取消当前 selector 选中
+- `updateSelectedElements(viewId?, changes)` - 更新当前 selector 选中集的属性
+- `copySelectedElements(viewId?)` - 复制当前 selector 选中集
+- `deleteSelectedElements(viewId?)` - 删除当前 selector 选中集
+- `updateElement(elementId, scenePath, viewId, updateElementInfo, useUndoRedoStack?)` - 单元素最终态更新接口，返回 `Promise<boolean>`
+
+其中需要注意：
+
+- `updateSelectedElements(...)` 是 selector-only 能力，只处理当前选中的 selector 集合
+- `updateElement(...)` 是 storage-first 的单元素最终态更新通知接口
+- `updateElement(...)` 不表达调用返回时已经渲染完成
+- `updateElement(...)` 不支持 selector
+- `updateElementInfo` 需要显式携带 `toolsType`，并按教具类型声明对应字段
+- `updateElement(...)` 返回 `Promise<boolean>`，仅表示本次调用是否通过基础校验并成功发起
+
+7. Selector 扩展事件
+- `selectedElementsChange`
+  - 只在 `selectedIds` 变化时触发
+  - 只表示最终选中集合变化
+- `selectorGeometryChange`
+  - 只表示最终几何结果变化
+  - 坐标统一为 `viewRect`
+- `selectorTransformChange`
+  - 只表示拖拽、拉伸、旋转、端点编辑等过程态
+  - 只暴露 `viewId + emitEventType + workState`
+- `remoteSelectorChange`
+  - 表示远端 / 被同步端 selector 的同步结果变化
+
 5. 不兼容接口
 - [`exportScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#exportScene) - appliance-plugin 开启后，笔记不能按 room 的方式导出
 - [服务端截图](https://doc.shengwang.cn/doc/whiteboard/restful/fastboard-sdk/restful-wb/operations/post-v5-rooms-uuid-screenshots) - appliance-plugin 开启后，笔记不能通过调用服务端截图方式获取截图，而需要改用 `screenshotToCanvasAsync` 获取
@@ -760,10 +775,10 @@ plugin.insertBackgroundImage(viewId, {
 `getInstance(wm: WindowManager | Room | Player, adaptor: ApplianceAdaptor)`
 - `wm`: `WindowManager | Room | Player`。多窗口模式下传入的是 `WindowManager`，单窗口模式下传入的是 `Room` 或者 `Player`（白板回放模式）。
 - `adaptor`: 配置适配器。
-    - `options: AppliancePluginOptions` - 必须配置，其中 `cdn` 为必填项。
+    - `options: AppliancePluginOptions` - 必须配置，其中 `cdn` 用于传入 worker URL。
         ```js
         export type AppliancePluginOptions = {
-            /** cdn配置项 */
+            /** worker URL 配置项 */
             cdn: CdnOpt;
             /** 额外配置项 */
             extras?: ExtrasOptions;
@@ -838,19 +853,9 @@ appliancePlugin.currentManager.consoleWorkerInfo()  // 可以查看到 worker
 import { ApplianceSinglePlugin } from '@netless/appliance-plugin';
 import '@netless/appliance-plugin/dist/style.css';
 
-// 方式1: 使用 CDN（推荐生产环境）
-const plugin = await ApplianceSinglePlugin.getInstance(room, {
-  options: {
-    cdn: {
-      fullWorkerUrl: 'https://your-cdn.com/fullWorker.js',
-      subWorkerUrl: 'https://your-cdn.com/subWorker.js',
-    },
-  },
-});
-
-// 方式2: 使用本地 worker 文件（适合开发环境）
 import fullWorkerString from '@netless/appliance-plugin/dist/fullWorker.js?raw';
 import subWorkerString from '@netless/appliance-plugin/dist/subWorker.js?raw';
+
 const fullWorkerBlob = new Blob([fullWorkerString], {type: 'text/javascript'});
 const fullWorkerUrl = URL.createObjectURL(fullWorkerBlob);
 const subWorkerBlob = new Blob([subWorkerString], {type: 'text/javascript'});
@@ -956,19 +961,13 @@ const canRedo = plugin.canRedoSteps() > 0;
 - **多窗口场景**：如果需要多窗口功能，使用 `ApplianceMultiPlugin`
 - **单白板场景**：如果只需要单白板功能，使用 `ApplianceSinglePlugin`
 
-### 2. Worker 文件部署方式选择？
-
-- **CDN 部署**（推荐）：适合生产环境，可以减少主包体积（主包约 400kB，两个 worker 各约 800kB）
-- **本地打包**：适合开发环境或对包体积不敏感的场景
-
-### 3. 性能优化建议
+### 2. 性能优化建议
 
-- 使用 CDN 部署 worker 文件，减少主包体积
 - 合理配置 `bufferSize`，根据设备性能调整画布缓存大小
 - 在移动端或低性能设备上，可以考虑使用 `useSimple: true` 简单模式
 - 如有非必要的功能, 可以不用开启 `useBackgroundThread: true`
 
-### 4. 兼容性说明
+### 3. 兼容性说明
 
 - 支持现代浏览器（Chrome、Firefox、Safari、Edge）
 - 移动端浏览器支持情况取决于 OffscreenCanvas 支持情况

package/README.md

@@ -47,6 +47,10 @@ The plugin supports the following drawing tools:
 npm install @netless/appliance-plugin
 ```
 
+> **Fastboard full packages:** If you are using `@netless/fastboard-full` or `@netless/fastboard-react-full` together with `enableAppliancePlugin`, install an `@netless/appliance-plugin` version that exposes `./bridge`. We recommend `>= 1.1.35` (`./bridge` first appeared in `>= 1.1.34-beta.2`).
+>
+> Keep importing `@netless/appliance-plugin` in app code. You do not need, and generally should not, replace it with `@netless/appliance-plugin/bridge`. The `/bridge` entry is loaded internally by fastboard full to reuse the bundled `white-web-sdk` runtime.
+
 ### Register Plugin
 
 Plugins can support two scenarios, they have different plugin names:
@@ -59,35 +63,13 @@ import { ApplianceMultiPlugin } from '@netless/appliance-plugin';
 import { ApplianceSinglePlugin } from '@netless/appliance-plugin';
 ```
 
-> **worker.js files: CDN & static assets**
->
-> We use dual workers for higher drawing efficiency (40%+ over the main thread). The two worker files share duplicated dependencies, so bundling them would significantly increase package size. We recommend providing worker URLs via `options.cdn`. Two common approaches:
->
-> 1. **CDN**: Deploy `fullWorker.js` and `subWorker.js` from `@netless/appliance-plugin/cdn` to your CDN, then pass their URLs as `fullWorkerUrl` and `subWorkerUrl` in the plugin’s `getInstance` second argument `options.cdn`.
-> ***Note***: CDN URLs must be same-origin with your app, or the workers will fail to load.
->
-> 2. **Static assets**: Put `fullWorker.js` and `subWorker.js` in your project’s static directory (e.g. Vite’s `public/`), so they are not bundled. In code, build full URLs from `import.meta.env.BASE_URL` (or your publicPath) and pass them to `options.cdn`. Same-origin, no bundle bloat, no Blob inline, lower memory use.
->
-> To keep bundle size down, configure `options.cdn` using one of the above.
-
 ### Access Mode Reference
 
-#### Introducing worker.js
+#### Preparing worker URLs
 ```js
-// Choose one of three ways to provide worker URLs:
-
-// Option 1: Static assets (recommended) — put fullWorker.js & subWorker.js in public (or similar); same-origin, no bundle cost
-const workerBase = (import.meta.env.BASE_URL || '/').replace(/\/?$/, '/');
-const fullWorkerUrl = workerBase + 'fullWorker.js';
-const subWorkerUrl = workerBase + 'subWorker.js';
-
-// Option 2: CDN — after deploying files from @netless/appliance-plugin/cdn to your CDN, set URLs here. Note: must be same-origin
-const fullWorkerUrl = 'https://your-cdn.com/fullWorker.js';
-const subWorkerUrl = 'https://your-cdn.com/subWorker.js';
-
-// Option 3: Inline via ?raw as Blob (requires ?raw support, e.g. Vite or webpack raw-loader). Uses more memory.
 import fullWorkerString from '@netless/appliance-plugin/dist/fullWorker.js?raw';
 import subWorkerString from '@netless/appliance-plugin/dist/subWorker.js?raw';
+
 const fullWorkerUrl = URL.createObjectURL(new Blob([fullWorkerString], { type: 'text/javascript' }));
 const subWorkerUrl = URL.createObjectURL(new Blob([subWorkerString], { type: 'text/javascript' }));
 ```
@@ -100,7 +82,7 @@ const subWorkerUrl = URL.createObjectURL(new Blob([subWorkerString], { type: 'te
 // Subpackage reference
 import { useFastboard, Fastboard } from "@netless/fastboard-react";
 
-// Use one of the three worker options from "Introducing worker.js" above:
+// Prepare worker URLs as shown above:
 const fullWorkerUrl = ...;
 const subWorkerUrl = ...;
 
@@ -131,7 +113,7 @@ const app = useFastboard(() => ({
 // Subpackage reference
 import { createFastboard, createUI } from "@netless/fastboard";
 
-// Use one of the three worker options from "Introducing worker.js" above:
+// Prepare worker URLs as shown above:
 const fullWorkerUrl = ...;
 const subWorkerUrl = ...;
 
@@ -157,6 +139,8 @@ const fastboard = await createFastboard({
   });
 ```
 
+> **Note:** In fastboard full mode, `@netless/fastboard-full` / `@netless/fastboard-react-full` load `@netless/appliance-plugin/bridge` internally. App code only needs to configure `enableAppliancePlugin`, provide worker URLs, and keep importing `@netless/appliance-plugin`; do not manually switch your import to `@netless/appliance-plugin/bridge`.
+
 #### Multi-window (Direct integration with window-manager)
 
 ```js
@@ -168,7 +152,7 @@ import { WhiteWebSdk } from "white-web-sdk";
 import { WindowManager } from "@netless/window-manager";
 import { ApplianceMultiPlugin } from '@netless/appliance-plugin';
 
-// Use one of the three worker options from "Introducing worker.js" above:
+// Prepare worker URLs as shown above:
 const fullWorkerUrl = ...;
 const subWorkerUrl = ...;
 
@@ -205,7 +189,7 @@ import '@netless/appliance-plugin/dist/style.css';
 
 import { WhiteWebSdk } from "white-web-sdk";
 import { ApplianceSinglePlugin, ApplianceSigleWrapper } from '@netless/appliance-plugin';
-// Use one of the three worker options from "Introducing worker.js" above:
+// Prepare worker URLs as shown above:
 const fullWorkerUrl = ...;
 const subWorkerUrl = ...;
 
@@ -774,10 +758,10 @@ plugin.usePlugin(autoDrawPlugin);
 `getInstance(wm: WindowManager | Room | Player, adaptor: ApplianceAdaptor)`
 - `wm`: `WindowManager | Room | Player`. In multi-window mode, pass `WindowManager`, in single-window mode, pass `Room` or `Player` (whiteboard playback mode).
 - `adaptor`: Configuration adapter.
-    - `options: AppliancePluginOptions` - Must be configured, where `cdn` is required.
+    - `options: AppliancePluginOptions` - Must be configured, where `cdn` contains worker URLs.
         ```js
         export type AppliancePluginOptions = {
-            /** CDN configuration item */
+            /** Worker URL configuration item */
             cdn: CdnOpt;
             /** Additional configuration items */
             extras?: ExtrasOptions;
@@ -850,19 +834,9 @@ appliancePlugin.currentManager.consoleWorkerInfo()  // Can view drawing informat
 import { ApplianceSinglePlugin } from '@netless/appliance-plugin';
 import '@netless/appliance-plugin/dist/style.css';
 
-// Method 1: Using CDN (recommended for production)
-const plugin = await ApplianceSinglePlugin.getInstance(room, {
-  options: {
-    cdn: {
-      fullWorkerUrl: 'https://your-cdn.com/fullWorker.js',
-      subWorkerUrl: 'https://your-cdn.com/subWorker.js',
-    },
-  },
-});
-
-// Method 2: Using local worker files (suitable for development)
 import fullWorkerString from '@netless/appliance-plugin/dist/fullWorker.js?raw';
 import subWorkerString from '@netless/appliance-plugin/dist/subWorker.js?raw';
+
 const fullWorkerBlob = new Blob([fullWorkerString], {type: 'text/javascript'});
 const fullWorkerUrl = URL.createObjectURL(fullWorkerBlob);
 const subWorkerBlob = new Blob([subWorkerString], {type: 'text/javascript'});
@@ -968,19 +942,13 @@ const canRedo = plugin.canRedoSteps() > 0;
 - **Multi-window scenario**: If you need multi-window functionality, use `ApplianceMultiPlugin`
 - **Single whiteboard scenario**: If you only need single whiteboard functionality, use `ApplianceSinglePlugin`
 
-### 2. Worker file deployment method selection?
-
-- **CDN deployment** (recommended): Suitable for production environments, can reduce main package size (main package ~400kB, two workers ~800kB each)
-- **Local packaging**: Suitable for development environments or scenarios where package size is not a concern
-
-### 3. Performance optimization recommendations
+### 2. Performance optimization recommendations
 
-- Use CDN deployment for worker files to reduce main package size
 - Reasonably configure `bufferSize` to adjust canvas cache size according to device performance
 - On mobile or low-performance devices, consider using `useSimple: true` simple mode
 - If there are unnecessary features, you can avoid enabling `useBackgroundThread: true`
 
-### 4. Compatibility notes
+### 3. Compatibility notes
 
 - Supports modern browsers (Chrome, Firefox, Safari, Edge)
 - Mobile browser support depends on OffscreenCanvas support

package/dist/appliance-plugin.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-D50QxS0c.js");exports.ActiveContainerType=e.ActiveContainerType;exports.ApplianceMultiPlugin=e.ApplianceMultiPlugin;exports.ApplianceNames=e.ApplianceNames;exports.ApplianceSigleWrapper=e.ApplianceSigleWrapper;exports.ApplianceSinglePlugin=e.ApplianceSinglePlugin;exports.Cursor_Hover_Id=e.Cursor_Hover_Id;exports.ECanvasShowType=e.ECanvasShowType;exports.EDataType=e.EDataType;exports.EForceStopReason=e.EForceStopReason;exports.EImageType=e.EImageType;exports.EMatrixrRelationType=e.EMatrixrRelationType;exports.EOperationType=e.EOperationType;exports.EPostMessageType=e.EPostMessageType;exports.ERenderFilterType=e.ERenderFilterType;exports.ESVGType=e.ESVGType;exports.EScaleType=e.EScaleType;exports.EStrokeType=e.EStrokeType;exports.EToolsKey=e.EToolsKey;exports.ElayerType=e.ElayerType;exports.EmitEventType=e.EmitEventType;exports.EventMessageType=e.EventMessageType;exports.EventWorkState=e.EventWorkState;exports.EvevtWorkState=e.EventWorkState;exports.InternalMsgEmitterType=e.InternalMsgEmitterType;exports.Main_View_Id=e.Main_View_Id;exports.Plugin=e.Plugin;exports.ShapeType=e.ShapeType;exports.Task_Time_Interval=e.Task_Time_Interval;exports.fullWorkerUrl=e.fullWorker;exports.subWorkerUrl=e.subWorker;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-B7w-GcID.js");exports.ActiveContainerType=e.ActiveContainerType;exports.ApplianceMultiPlugin=e.ApplianceMultiPlugin;exports.ApplianceNames=e.ApplianceNames;exports.ApplianceSigleWrapper=e.ApplianceSigleWrapper;exports.ApplianceSinglePlugin=e.ApplianceSinglePlugin;exports.Cursor_Hover_Id=e.Cursor_Hover_Id;exports.ECanvasShowType=e.ECanvasShowType;exports.EDataType=e.EDataType;exports.EForceStopReason=e.EForceStopReason;exports.EImageType=e.EImageType;exports.EMatrixrRelationType=e.EMatrixrRelationType;exports.EOperationType=e.EOperationType;exports.EPostMessageType=e.EPostMessageType;exports.ERenderFilterType=e.ERenderFilterType;exports.ESVGType=e.ESVGType;exports.EScaleType=e.EScaleType;exports.EStrokeType=e.EStrokeType;exports.EToolsKey=e.EToolsKey;exports.ElayerType=e.ElayerType;exports.EmitEventType=e.EmitEventType;exports.EventMessageType=e.EventMessageType;exports.EventWorkState=e.EventWorkState;exports.EvevtWorkState=e.EventWorkState;exports.InternalMsgEmitterType=e.InternalMsgEmitterType;exports.Main_View_Id=e.Main_View_Id;exports.Plugin=e.Plugin;exports.ShapeType=e.ShapeType;exports.Task_Time_Interval=e.Task_Time_Interval;exports.fullWorkerUrl=e.fullWorker;exports.subWorkerUrl=e.subWorker;

package/dist/appliance-plugin.mjs

@@ -1,4 +1,4 @@
-import { a7 as s, a8 as p, a9 as r, aa as t, ab as i, a4 as l, Z as n, b as E, ac as o, t as T, j as y, ad as v, a as g, ae as S, d as c, u, w as k, c as m, af as M, E as _, ag as d, v as A, v as I, ah as W, Y as P, ai as b, aj as f, a6 as h, ak as w, al as C } from "./index-DTMQbvIh.mjs";
+import { a7 as s, a8 as p, a9 as r, aa as t, ab as i, a4 as l, Z as n, b as E, ac as o, t as T, j as y, ad as v, a as g, ae as S, d as c, u, w as k, c as m, af as M, E as _, ag as d, v as A, v as I, ah as W, Y as P, ai as b, aj as f, a6 as h, ak as w, al as C } from "./index-CfKLCV2y.mjs";
 export {
   s as ActiveContainerType,
   p as ApplianceMultiPlugin,