mce 0.24.4 → 0.25.0

package/README.md

@@ -18,7 +18,7 @@
   </a>
 </p>
 
-<p align="center">A headless infinite canvas editor framework built on WebGL rendering, supports exporting to image, video, and PPT. Only the ESM.</p>
+<p align="center">An infinite canvas editor framework (Vue 3 + TypeScript) with real-time collaboration, a timeline, components and design tokens — built on WebGL rendering. Bring your own UI. ESM only.</p>
 
 <p align="center">
   <a href="https://qq15725.github.io/mce/">📚 Documentation</a>
@@ -26,6 +26,76 @@
   <a href="https://codesandbox.io/p/github/qq15725/mce/main">🎮 Try in CodeSandbox</a>
 </p>
 
+## ✨ Features
+
+**Canvas & editing**
+- Infinite canvas with pan / zoom, rulers, scrollbars, pixel grid and checkerboard
+- Smart guides & snapping, alignment / distribution, z-order arrange, tidy-up
+- Multi-select & marquee, transform (move / resize / rotate / flip), foreground crop
+- Frames (artboards) with auto-nesting, and Flex auto-layout (drag-to-reorder)
+
+**Content**
+- Shapes, pen / freehand paths, lines & arrows
+- Rich text (fragment styling, custom fonts, format painter, auto-fit strategies)
+- Images (insert / upload / crop), video, tables (`@mce/table`) and charts (`@mce/chart`)
+
+**Motion**
+- Timeline with frame-based playback
+- Keyframe animation with reusable easing (presets + custom cubic-bezier)
+- Export to GIF, MP4 and Lottie
+
+**Collaboration & history**
+- CRDT document model ([Yjs](https://github.com/yjs/yjs)) in the core — undo / redo and offline persistence (IndexedDB) build on it
+- Real-time multi-user editing + awareness (remote cursors / selection / avatars) via `@mce/collaboration` (WebSocket / pluggable transport)
+- Comments anchored to elements (pins follow on move / scale / rotate, threads with replies & resolve) via `@mce/comments`
+
+**Design systems**
+- Components / symbols / instances with per-instance overrides and master propagation
+- Design tokens / variables (collections + modes) for theming and responsive values
+
+**AI** (`@mce/ai`)
+- A typed AI canvas action schema — drive edits from an LLM over the existing command & undo stack (model wiring left to the consumer)
+
+**Workflow** (`@mce/workflow`)
+- A node-graph editing mode: connectable nodes with input / output ports and curved connections
+
+**Extensible**
+- ~40 built-in plugins; a plugin can contribute commands, tools, hotkeys, exporters, loaders, components and events
+- Element types & modes are decoupled via extension points (selection redirect, resize override, enter handler, editing state, toolbelt item, icon, mode, statusbar item) — see `mixins/extensions.ts`
+- Unified command system, hotkeys, and i18n
+
+## 📤 Import & export
+
+- **Export**: `PNG` · `JPEG` · `WebP` · `SVG` · `PDF` · `GIF` · `MP4` · `Lottie` · `PPTX` / `XLSX` / `DOCX` · `JSON`
+- **Import**: `PPTX` / `XLSX` / `DOCX` · `PSD` · `HTML` · images · `JSON`
+
+These ship as optional plugins; their heavy encoders / parsers are lazy-loaded on first use:
+
+| Package | Adds |
+| --- | --- |
+| `@mce/gif` | GIF export |
+| `@mce/mp4` | MP4 export |
+| `@mce/pdf` | PDF export |
+| `@mce/svg` | SVG export |
+| `@mce/openxml` | PPTX / XLSX / DOCX import & export |
+| `@mce/psd` | PSD import (Photoshop layers → elements) |
+| `@mce/html` | HTML import |
+
+(`PNG` / `JPEG` / `WebP` / `JSON` / `Lottie` export are built in.)
+
+## 🔌 Feature plugins
+
+Specialized features also ship as optional packages, registered the same way (`plugins: [...]`):
+
+| Package | Adds |
+| --- | --- |
+| `@mce/table` | Table element + in-canvas table editor |
+| `@mce/chart` | Chart elements (bar / line / pie / …) |
+| `@mce/ai` | Typed AI canvas action schema (`applyAiActions`) |
+| `@mce/workflow` | Node-graph editing mode |
+| `@mce/collaboration` | Real-time collaboration: transport providers + presence (cursors / selection / avatars) |
+| `@mce/comments` | Comments: comment tool + pins anchored to elements + threads (stored on `element.comments`) |
+
 ## 📦 Install
 
 ```shell
@@ -38,22 +108,38 @@ npm i mce
 <script setup lang="ts">
   import { Editor, EditorLayout, EditorLayoutItem } from 'mce'
   import 'mce/styles'
+  import ai from '@mce/ai'
+  import chart from '@mce/chart'
+  import collaboration from '@mce/collaboration'
+  import comments from '@mce/comments'
   import gif from '@mce/gif'
   import mp4 from '@mce/mp4'
   import openxml from '@mce/openxml'
   import pdf from '@mce/pdf'
   import svg from '@mce/svg'
-  import gifWorkerUrl from 'modern-gif/worker?url'
+  import table from '@mce/table'
+  import workflow from '@mce/workflow'
 
   const editor = new Editor({
     plugins: [
+      // export / import formats
       gif(),
       mp4(),
       svg(),
       pdf(),
       openxml(),
+      // feature plugins (all optional)
+      table(),
+      chart(),
+      ai(),
+      workflow(),
+      collaboration(), // registers the collaboration + presence plugins
+      comments(),
     ],
-    gifWorkerUrl,
+    // @mce/gif bundles its encoding worker by default. To self-host it
+    // (e.g. under a strict CSP), pass `gifWorkerUrl` explicitly:
+    //   import gifWorkerUrl from 'modern-gif/worker?url'
+    //   ...new Editor({ gifWorkerUrl })
     locale: { locale: 'en' },
     viewport: {
       camera: { enabled: true },
@@ -132,7 +218,7 @@ npm i mce
 </template>
 ```
 
-slot sub component
+Slot sub component — read editor state via `useEditor()`:
 
 ```vue
 <script setup lang="ts">
@@ -147,3 +233,150 @@ slot sub component
 </template>
 ```
 
+## 🧩 Commands
+
+Everything the editor does is a command — call `editor.exec(name, ...args)`. A few examples:
+
+```ts
+// Arrange & layout
+editor.exec('alignHorizontalCenter')
+editor.exec('distributeHorizontalSpacing')
+editor.exec('tidyUp')
+
+// Design tokens / variables
+const collection = editor.exec('createVariableCollection', 'Theme', 'Light')
+const dark = editor.exec('addVariableMode', collection, 'Dark')
+const brand = editor.exec('addVariable', collection, { name: 'brand', type: 'color', value: '#ff0000' })
+editor.exec('setVariableValue', brand, dark, '#0000ff')
+editor.exec('bindVariable', 'fill.color', brand) // bind selected element's fill
+editor.exec('setActiveVariableMode', collection, dark) // theme switch → canvas recolors
+
+// Components / instances
+const component = editor.exec('createComponent') // from selection
+editor.exec('createInstance', component, { position: { x: 200, y: 200 } })
+
+// Keyframe animation → Lottie
+editor.exec('addAnimationKeyframe', 0, { left: 0, opacity: 0 })
+editor.exec('addAnimationKeyframe', 1, { left: 300, opacity: 1 })
+const lottie = editor.exec('exportLottie')
+
+// AI canvas actions (validated, applied in one undo step) — needs @mce/ai
+editor.exec('applyAiActions', [
+  { type: 'createText', text: 'Hello', x: 40, y: 40 },
+  { type: 'align', direction: 'left' },
+])
+```
+
+## 🤝 Collaboration
+
+The CRDT document model (Yjs) lives in the **core** — undo / redo and offline
+persistence (IndexedDB) build on it. The **network transport and presence**
+(awareness) layer is the optional `@mce/collaboration` package.
+
+**1. Register the plugin**
+
+```ts
+import collaboration from '@mce/collaboration'
+
+const editor = new Editor({
+  plugins: [
+    collaboration(), // registers the collaboration + presence plugins
+  ],
+})
+```
+
+**2. Identify the local user (presence)**
+
+```ts
+editor.presence.setUser({
+  id: 'u-1', // optional, for dedupe / avatars
+  name: 'Alice',
+  color: '#E64980',
+  avatar: 'https://…', // optional
+})
+```
+
+**3. Connect to a room**
+
+```ts
+// Built-in WebSocket transport (y-websocket compatible server)
+editor.collaboration.connect({
+  url: 'wss://your-server',
+  room: 'doc-1', // defaults to the current document id
+})
+
+// …or a custom / pluggable transport (WebRTC, BroadcastChannel, …)
+import { AbstractProvider } from '@mce/collaboration'
+editor.collaboration.connect({
+  provider: doc => new MyProvider(doc), // doc is the document's YDoc
+})
+
+editor.collaboration.disconnect() // end the session
+```
+
+You can also auto-connect on startup via the editor option:
+
+```ts
+new Editor({ collaboration: { url: 'wss://your-server', room: 'doc-1' } })
+```
+
+**4. Reactive status & remote peers**
+
+```ts
+editor.collaboration.connected // Ref<boolean> — transport connected
+editor.collaboration.synced    // Ref<boolean> — first full sync done
+editor.collaboration.active    // Ref<boolean> — a session is active
+editor.presence.peers          // Ref<Peer[]> — remote users (cursor / selection / user)
+editor.presence.localUser      // Ref<PresenceUser>
+```
+
+Remote cursors, selection boxes and a connection/avatars status-bar item render
+automatically once a session is active. Document switching rebuilds the provider
+on the new document's `YDoc`; the transport is bound per-document.
+
+> Comments (`@mce/comments`) live on `element.comments` and are part of the
+> document model, so they sync over the same session automatically.
+
+## 🏗️ Architecture
+
+```
+packages/
+  mce/           # core editor library (npm: mce)
+  gif/           # GIF export  (@mce/gif)
+  mp4/           # MP4 export  (@mce/mp4)
+  pdf/           # PDF export  (@mce/pdf)
+  svg/           # SVG export  (@mce/svg)
+  openxml/       # PPTX/XLSX/DOCX import & export  (@mce/openxml)
+  psd/           # PSD import  (@mce/psd)
+  html/          # HTML import  (@mce/html)
+  table/         # table element + editor  (@mce/table)
+  chart/         # chart elements  (@mce/chart)
+  ai/            # AI canvas actions  (@mce/ai)
+  workflow/      # node-graph mode  (@mce/workflow)
+  collaboration/ # real-time collaboration  (@mce/collaboration)
+  comments/      # comments  (@mce/comments)
+playground/      # demo & test app
+```
+
+The `Editor` is composed from layered mixins and a plugin system. Rendering is powered by
+[`modern-canvas`](https://www.npmjs.com/package/modern-canvas) (WebGL), with text / fonts /
+document model from `modern-text`, `modern-font` and `modern-idoc`.
+
+The core stays lean: element types and editing modes are decoupled through extension points
+(`mixins/extensions.ts`), so feature packages register their behavior instead of the core
+hard-coding it. The CRDT document model (`yjs` + `y-protocols`) lives in the core; the
+real-time transport and presence layer is the optional `@mce/collaboration` package.
+
+## 🛠️ Development
+
+```shell
+pnpm dev            # start the playground
+pnpm build          # build core + all plugins
+pnpm test           # run tests
+pnpm -F mce typecheck
+pnpm lint
+```
+
+## 📄 License
+
+[MIT](./LICENSE)

package/dist/components/EditorPanels.vue.d.ts

@@ -0,0 +1,6 @@
+type __VLS_Props = {
+    slots: Record<string, any>;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/Interactions.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/shared/Cropper.vue.d.ts

@@ -1,6 +1,10 @@
 import type { ImageFillCropRect } from 'modern-idoc';
 /**
- * TODO 撤回无法重渲
+ * 撤回 / 重做修复说明：
+ * 下方 `viewEffect` watch 在 `view` 变化时反向补偿 `cropRect` 以保持 source 视觉不变。
+ * 但撤回/重做会由 UndoManager 同时回退 `view` 与 `cropRect`，此时不应再据旧 `view` 重算
+ * `cropRect`（会把已回退的 `cropRect` 覆盖掉）。因此 viewEffect 在 `editor.isUndoRedoing`
+ * 期间跳过补偿，仅对用户拖拽 / 改宽高比产生的 view 变化补偿。
  */
 type View = Record<'left' | 'top' | 'width' | 'height' | 'scaleX' | 'scaleY', number>;
 type __VLS_Props = {

package/dist/components/shared/Dialog.vue.d.ts

@@ -1,65 +1,60 @@
-declare function updateLocation(): void;
-declare var __VLS_10: {
+declare var __VLS_1: {
     props: {
-        ref: (el: any) => any;
+        onClick: () => boolean;
     };
     isActive: boolean;
-}, __VLS_12: {};
+}, __VLS_15: {};
 type __VLS_Slots = {} & {
-    activator?: (props: typeof __VLS_10) => any;
+    activator?: (props: typeof __VLS_1) => any;
 } & {
-    default?: (props: typeof __VLS_12) => any;
+    default?: (props: typeof __VLS_15) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
-    location: import("vue").PropType<import("@floating-ui/vue").Side | import("@floating-ui/vue").AlignedPlacement>;
-    offset: NumberConstructor;
-    middlewares: {
-        type: import("vue").PropType<("offset" | "flip" | "shift")[]>;
-        default: () => string[];
+    /** 持久化：点击遮罩 / 按 Esc 不关闭。 */
+    persistent: {
+        type: BooleanConstructor;
+        default: boolean;
     };
-    target: import("vue").PropType<{
-        x: number;
-        y: number;
-    } | import("@floating-ui/vue").ReferenceElement>;
+    /** 对话框宽度（CSS 值），默认自适应内容。 */
+    width: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** Teleport 目标。默认挂到编辑器 overlay 容器（继承风格变量），否则 body。 */
     attach: {
-        type: import("vue").PropType<string | boolean | Element | null | undefined>;
+        type: () => string | HTMLElement | false;
         default: undefined;
     };
-    contentClass: import("vue").PropType<any>;
-    contentStyle: import("vue").PropType<import("vue").CSSProperties>;
     modelValue: {
         type: import("vue").PropType<boolean>;
     };
-}>, {
-    isActive: import("vue").ModelRef<boolean | undefined, string, boolean | undefined, boolean | undefined>;
-    updateLocation: typeof updateLocation;
-}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    "update:modelValue": (value: boolean | undefined) => any;
+}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: boolean) => any;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
-    location: import("vue").PropType<import("@floating-ui/vue").Side | import("@floating-ui/vue").AlignedPlacement>;
-    offset: NumberConstructor;
-    middlewares: {
-        type: import("vue").PropType<("offset" | "flip" | "shift")[]>;
-        default: () => string[];
+    /** 持久化：点击遮罩 / 按 Esc 不关闭。 */
+    persistent: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 对话框宽度（CSS 值），默认自适应内容。 */
+    width: {
+        type: StringConstructor;
+        default: undefined;
     };
-    target: import("vue").PropType<{
-        x: number;
-        y: number;
-    } | import("@floating-ui/vue").ReferenceElement>;
+    /** Teleport 目标。默认挂到编辑器 overlay 容器（继承风格变量），否则 body。 */
     attach: {
-        type: import("vue").PropType<string | boolean | Element | null | undefined>;
+        type: () => string | HTMLElement | false;
         default: undefined;
     };
-    contentClass: import("vue").PropType<any>;
-    contentStyle: import("vue").PropType<import("vue").CSSProperties>;
     modelValue: {
         type: import("vue").PropType<boolean>;
     };
 }>> & Readonly<{
-    "onUpdate:modelValue"?: ((value: boolean | undefined) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
 }>, {
-    attach: string | boolean | Element | null | undefined;
-    middlewares: ("flip" | "shift" | "offset")[];
+    width: string;
+    attach: string | false | HTMLElement;
+    persistent: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/components/shared/FloatPanel.vue.d.ts

@@ -1,5 +1,7 @@
 import type { OrientedBoundingBox } from '../../types';
 type __VLS_Props = {
+    /** 面板唯一标识，接入面板状态源（层叠 / 位置记忆）。 */
+    name: string;
     title?: string;
     defaultTransform?: Partial<OrientedBoundingBox>;
 };
@@ -7,11 +9,11 @@ type __VLS_ModelProps = {
     modelValue?: boolean;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
-declare var __VLS_23: {
+declare var __VLS_10: {
     isActive: import("vue").ModelRef<boolean | undefined, string, boolean | undefined, boolean | undefined>;
 };
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_23) => any;
+    default?: (props: typeof __VLS_10) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (value: boolean | undefined) => any;

package/dist/components/shared/LayoutItem.vue.d.ts

@@ -28,6 +28,19 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
         type: BooleanConstructor;
         default: boolean;
     };
+    /** 是否允许拖拽分隔条调整尺寸（细条类面板如 statusbar 关闭）。 */
+    resizable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    minSize: {
+        type: NumberConstructor;
+        default: number;
+    };
+    maxSize: {
+        type: NumberConstructor;
+        default: undefined;
+    };
 }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     name: {
         type: StringConstructor;
@@ -53,9 +66,25 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
         type: BooleanConstructor;
         default: boolean;
     };
+    /** 是否允许拖拽分隔条调整尺寸（细条类面板如 statusbar 关闭）。 */
+    resizable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    minSize: {
+        type: NumberConstructor;
+        default: number;
+    };
+    maxSize: {
+        type: NumberConstructor;
+        default: undefined;
+    };
 }>> & Readonly<{}>, {
     size: string | number;
     style: string | Record<string, any> | unknown[];
+    resizable: boolean;
+    minSize: number;
+    maxSize: number;
     order: string | number;
     modelValue: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/components/shared/PanelContent.vue.d.ts

@@ -0,0 +1,29 @@
+type __VLS_Props = {
+    title?: string;
+    /** 是否显示关闭按钮（点击触发 close）。 */
+    closable?: boolean;
+    /** 内容区是否加统一内边距（默认不加，由各面板自管）。 */
+    padded?: boolean;
+};
+declare var __VLS_15: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_15) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    close: () => any;
+    headerPointerdown: (event: PointerEvent) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClose?: (() => any) | undefined;
+    onHeaderPointerdown?: ((event: PointerEvent) => any) | undefined;
+}>, {
+    closable: boolean;
+    padded: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/timeline/EasingCurve.vue.d.ts

@@ -0,0 +1,11 @@
+import type { EasingCoords } from '../../utils';
+type __VLS_Props = {
+    modelValue: EasingCoords;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (coords: EasingCoords) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((coords: EasingCoords) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/timeline/KeyframePopover.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/crdt/YDoc.d.ts

@@ -1,12 +1,22 @@
 import type { CoreObject } from 'modern-canvas';
 import type { ObservableEvents } from 'modern-idoc';
 import type { Transaction } from 'yjs';
+import type { Reactivity } from './reactivity';
 import { Node } from 'modern-canvas';
 import { Observable } from 'modern-idoc';
 import * as Y from 'yjs';
 import { IndexeddbProvider } from './providers';
+/**
+ * 本地编辑产生的事务来源：进入 UndoManager，并向远端广播。
+ */
+export declare const LOCAL_ORIGIN: unique symbol;
+/**
+ * 内部回放（把远端 / 撤销变更应用到视图）产生的事务来源：不进入 UndoManager，
+ * observe 回调据此跳过回写，避免本地↔yjs 回环。
+ */
+export declare const INTERNAL_ORIGIN: unique symbol;
 export type YNode = Y.Map<unknown> & {
-    get: ((prop: 'id') => string) & ((prop: 'name') => string) & ((prop: 'parentId') => string) & ((prop: 'style') => Y.Map<unknown>) & ((prop: 'background') => Y.Map<unknown>) & ((prop: 'shape') => Y.Map<unknown>) & ((prop: 'fill') => Y.Map<unknown>) & ((prop: 'outline') => Y.Map<unknown>) & ((prop: 'text') => Y.Map<unknown>) & ((prop: 'foreground') => Y.Map<unknown>) & ((prop: 'shadow') => Y.Map<unknown>) & ((prop: 'meta') => Y.Map<unknown>) & ((prop: 'childrenIds') => Y.Array<string>) & (<T = unknown>(prop: string) => T);
+    get: ((prop: 'id') => string) & ((prop: 'name') => string) & ((prop: 'parentId') => string) & ((prop: 'style') => Y.Map<unknown>) & ((prop: 'background') => Y.Map<unknown>) & ((prop: 'shape') => Y.Map<unknown>) & ((prop: 'fill') => Y.Map<unknown>) & ((prop: 'outline') => Y.Map<unknown>) & ((prop: 'text') => Y.Map<unknown>) & ((prop: 'foreground') => Y.Map<unknown>) & ((prop: 'shadow') => Y.Map<unknown>) & ((prop: 'comments') => Y.Map<unknown>) & ((prop: 'meta') => Y.Map<unknown>) & ((prop: 'childrenIds') => Y.Array<string>) & (<T = unknown>(prop: string) => T);
 };
 export interface YDocEvents extends ObservableEvents {
     history: [arg0: Y.UndoManager];
@@ -26,9 +36,13 @@ export declare class YDoc extends Observable {
     _yChildren: Y.Map<YNode>;
     _yChildrenIds: Y.Array<string>;
     _nodeMap: Map<string, Node>;
+    /** 远端子节点顺序变更先于节点创建到达时，挂起的 move 操作，按 childId 暂存。 */
+    _pendingInserts: Map<string, Set<() => void>>;
     indexeddb?: IndexeddbProvider;
     undoManager: Y.UndoManager;
-    constructor(id?: string);
+    /** 响应式适配器：解耦 Vue。运行时由上层注入 Vue 实现，测试 / headless 用 rawReactivity。 */
+    protected _rx: Reactivity;
+    constructor(id?: string, reactivity?: Reactivity);
     protected _isSelfTransaction(transaction?: Y.Transaction): boolean;
     protected _initUndoManager(typeScope?: any[]): void;
     loadIndexeddb(): Promise<void>;
@@ -43,4 +57,15 @@ export declare class YDoc extends Observable {
     protected _proxyChildren(node: Node, childrenIds: Y.Array<string>): void;
     _proxyNode(node: Node, yNode?: YNode, yChildrenIds?: Y.Array<string>): Node;
     protected _initYNode(yNode: YNode): Node;
+    /** 节点就绪后消费此前因节点缺失而挂起的 move 操作。 */
+    protected _flushPendingInserts(id: string): void;
+    /**
+     * 应用远端增量。origin 必须区别于 LOCAL/INTERNAL，使变更刷新到视图且不进入本端 undo 栈；
+     * 默认用 provider/调用方实例做 origin（这里用 this 兜底）。
+     */
+    applyUpdate(update: Uint8Array, origin?: unknown): void;
+    /** 导出相对 targetStateVector 的差量（不传则全量），用于新端初始同步握手。 */
+    encodeStateAsUpdate(targetStateVector?: Uint8Array): Uint8Array;
+    /** 导出本端状态向量，与对端交换以计算差量。 */
+    encodeStateVector(): Uint8Array;
 }

package/dist/crdt/YDoc.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/crdt/index.d.ts

@@ -1 +1,4 @@
+export * from './providers';
+export * from './reactivity';
+export * from './vueReactivity';
 export * from './YDoc';

package/dist/crdt/providers/indexeddb/IndexeddbProvider.d.ts

@@ -21,7 +21,9 @@ export declare class IndexeddbProvider extends Observable<IndexeddbProviderEvent
     _storeTimeout: number;
     _storeTimeoutId: any;
     _storeUpdate: (update: Uint8Array, origin: any) => void;
-    constructor(name: string, doc: Y.Doc);
+    /** 累积多少条增量后做一次全量快照压缩（compaction）。越小库越小但全量重写越频繁。 */
+    trimSize: number;
+    constructor(name: string, doc: Y.Doc, trimSize?: number);
     destroy(): Promise<void>;
     clearData(): Promise<void>;
     get<T = any>(key: IDBValidKey): Promise<T>;

package/dist/crdt/reactivity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 响应式适配器：把 CRDT 核心层（YDoc）与具体的响应式框架（Vue）解耦。
+ *
+ * 动机：原 `YDoc` 直接 `import { reactive, markRaw, isReactive } from 'vue'`，使数据层硬绑 Vue，
+ * 既无法在非 Vue / 纯 Node 环境下测试，也让「Yjs 数据」与「视图响应式」两个关注点纠缠在一起。
+ * 抽成接口后：
+ * - CRDT 层只依赖 {@link Reactivity} 接口，不 import vue；
+ * - 运行时由上层（scene/Doc）注入真实的 Vue 适配器 —— 行为与原来完全一致；
+ * - 测试 / headless 场景注入 {@link rawReactivity} —— 走纯数据路径，零响应式开销。
+ */
+export interface Reactivity {
+    /** 包装为响应式代理（Vue: reactive）。raw 模式下原样返回。 */
+    reactive: <T extends object>(target: T) => T;
+    /** 判断是否已是响应式代理。raw 模式下恒为 true，使「按需包装」逻辑跳过包装。 */
+    isReactive: (value: unknown) => boolean;
+    /** 标记对象不被响应式系统代理（Vue: markRaw）。raw 模式下原样返回。 */
+    markRaw: <T extends object>(value: T) => T;
+    /** 取回响应式代理背后的原始对象（Vue: toRaw）。raw 模式下原样返回。 */
+    toRaw: <T>(value: T) => T;
+}
+/**
+ * 无响应式实现：纯数据层，不做任何包装。
+ * - `isReactive` 恒 true，让 `if (!isReactive(node)) wrap(node)` 这类逻辑直接跳过；
+ * - 其余均为恒等函数。
+ * 用于单元测试与非 Vue 宿主环境。
+ */
+export declare const rawReactivity: Reactivity;

package/dist/crdt/reactivity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/crdt/vueReactivity.d.ts

@@ -0,0 +1,8 @@
+import type { Reactivity } from './reactivity';
+/**
+ * Vue 响应式适配器：把 Vue 的 reactive/markRaw/isReactive/toRaw 适配为 {@link Reactivity} 接口。
+ *
+ * 这是「Vue 绑定」模块——唯一 import vue 的 CRDT 文件。核心 {@link YDoc} 不依赖它，
+ * 由上层（scene/Doc）显式注入，从而保持数据层框架无关、可在 headless 下测试。
+ */
+export declare const vueReactivity: Reactivity;