@vuer-ai/vuer-rtc 0.1.3 → 0.2.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "vuer-rtc",
+  "owner": {
+    "name": "Ge Yang"
+  },
+  "description": "CRDT-based real-time collaborative state management for 3D scenes",
+  "plugins": [
+    {
+      "name": "vuer-rtc",
+      "source": "./",
+      "description": "vuer-rtc skills for real-time collaborative 3D scene editing"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "vuer-rtc",
+  "version": "0.1.3",
+  "description": "CRDT-based real-time collaborative state management for 3D scenes",
+  "author": {
+    "name": "Ge Yang"
+  },
+  "repository": "https://github.com/vuer-ai/vuer-rtc-workspace",
+  "license": "MIT",
+  "keywords": ["crdt", "real-time", "collaboration", "3d", "scene-graph"],
+  "skills": "./skills/"
+}

package/.claude-plugin/skills/vuer-rtc.md

@@ -0,0 +1,158 @@
+# vuer-rtc Skill
+
+CRDT-based real-time collaborative state management for 3D scenes and text.
+
+## When to Use This Skill
+
+Use when the user is working with:
+- Real-time collaborative editing (multiplayer)
+- Scene graph state management
+- Collaborative text editing (TextRope CRDT)
+- Undo/redo that syncs across clients
+- React hooks for vuer-rtc
+
+## Package Structure
+
+```
+@vuer-ai/vuer-rtc
+├── client/     → State management, actions, journal
+├── crdt/       → TextRope for collaborative text
+├── operations/ → Scene graph CRDT operations
+├── hooks.ts    → React integration
+└── index.ts    → Main exports
+```
+
+## Quick Patterns
+
+### 1. Basic Setup
+```typescript
+import { createGraph } from '@vuer-ai/vuer-rtc';
+
+const store = createGraph({
+  sessionId: 'user-123',
+  onSend: (msg) => websocket.send(JSON.stringify(msg)),
+});
+
+websocket.onmessage = (e) => store.receive(JSON.parse(e.data));
+```
+
+### 2. Edit → Commit Flow
+```typescript
+// Edits are local-only until committed
+store.edit({ otype: 'vector3.set', key: 'cube', path: 'position', value: [1, 2, 3] });
+store.edit({ otype: 'number.set', key: 'cube', path: 'opacity', value: 0.5 });
+
+// Commit sends all edits as one message
+store.commit('Update cube');
+
+// Or cancel uncommitted edits
+store.cancel();
+```
+
+### 3. Undo/Redo (Synced)
+```typescript
+store.undo();  // Creates meta.undo message, syncs to all clients
+store.redo();  // Creates meta.redo message, syncs to all clients
+```
+
+### 4. React Hooks
+```typescript
+import { useGraph, useNode, useUndo } from '@vuer-ai/vuer-rtc';
+
+function Component() {
+  const store = useGraph();
+  const cube = useNode('cube-1');
+  const { undo, redo, canUndo, canRedo } = useUndo();
+
+  return <mesh position={cube?.position} />;
+}
+```
+
+### 5. TextRope (Collaborative Text)
+```typescript
+import { create, getText, insertWithSplit, remove, replace } from '@vuer-ai/vuer-rtc/crdt';
+
+const rope = create('agent-1');
+insertWithSplit(rope, 0, 'Hello');
+replace(rope, 0, 5, 'Hi');        // Atomic delete+insert
+console.log(getText(rope));       // "Hi"
+```
+
+## Operation Types (Quick Reference)
+
+| Category | Operations |
+|----------|------------|
+| **Numbers** | `number.set`, `number.add`, `number.multiply`, `number.min`, `number.max` |
+| **Vectors** | `vector3.set`, `vector3.add`, `vector3.multiply` |
+| **Rotations** | `quaternion.set`, `euler.set` |
+| **Booleans** | `boolean.set`, `boolean.and`, `boolean.or` |
+| **Collections** | `array.set`, `array.push`, `array.remove`, `object.set`, `object.merge` |
+| **Nodes** | `node.insert`, `node.remove` |
+| **Text** | `text.init`, `text.insert`, `text.delete` |
+| **Meta** | `meta.undo`, `meta.redo` |
+
+## Conflict Resolution
+
+| Pattern | Strategy |
+|---------|----------|
+| `*.set` | Last-Write-Wins (higher lamport timestamp) |
+| `*.add`, `*.multiply` | Commutative merge |
+| `meta.undo/redo` | Marks `deletedAt` on target message |
+
+## Detailed Documentation
+
+For in-depth API references, fetch these docs:
+
+| Topic | URL |
+|-------|-----|
+| **Architecture** | https://rtc.vuer.ai/architecture |
+| **Operations** | https://rtc.vuer.ai/operations |
+| **TextRope CRDT** | https://rtc.vuer.ai/rope |
+| **React Hooks** | https://rtc.vuer.ai/react-hooks |
+| **Server Setup** | https://rtc.vuer.ai/server |
+| **Examples** | https://rtc.vuer.ai/examples |
+
+## Common Tasks
+
+### Add a node to scene
+```typescript
+store.edit({
+  otype: 'node.insert',
+  key: 'parent-key',  // Parent node ('' for root)
+  path: 'children',
+  value: { key: 'new-node', tag: 'Mesh', name: 'Cube' },
+});
+store.commit('Add cube');
+```
+
+### Update node property
+```typescript
+store.edit({
+  otype: 'vector3.set',
+  key: 'cube-1',
+  path: 'position',
+  value: [1, 2, 3],
+});
+```
+
+### Initialize collaborative text
+```typescript
+store.edit({ otype: 'text.init', key: 'doc-1', path: 'content', value: 'Hello' });
+store.edit({ otype: 'text.insert', key: 'doc-1', path: 'content', position: 5, value: ' World' });
+```
+
+### Handle reconnection
+```typescript
+// Get unacked messages to resend
+const pending = store.getUnackedMessages();
+pending.forEach(msg => websocket.send(JSON.stringify(msg)));
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Edits not syncing | Check `store.commit()` was called |
+| Undo not working | Ensure target message is acked by server |
+| Text interleaving | Use `insertWithSplit()` instead of `insert()` |
+| State divergence | Verify all clients receive same messages |

package/.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

package/README.md

@@ -8,6 +8,19 @@ CRDT-based real-time collaborative state management for 3D scenes.
 pnpm add @vuer-ai/vuer-rtc
 ```
 
+## Claude Code Skill
+
+Add vuer-rtc knowledge to Claude Code for CRDT-based real-time collaboration assistance:
+
+```bash
+# Plugin marketplace
+/plugin marketplace add vuer-ai/vuer-rtc-workspace
+/plugin install vuer-rtc@vuer-rtc
+
+# Or add to your CLAUDE.md
+# @import https://raw.githubusercontent.com/vuer-ai/vuer-rtc-workspace/main/skill/vuer-rtc.md
+```
+
 ## Quick Start
 
 ```typescript
@@ -80,18 +93,20 @@ function Node({ nodeKey }: { nodeKey: string }) {
 
 ## Operation Types
 
-| Category | Operations |
-|----------|-----------|
-| Number | `number.set`, `number.add`, `number.multiply`, `number.min`, `number.max` |
-| Vector3 | `vector3.set`, `vector3.add`, `vector3.multiply` |
-| Quaternion | `quaternion.set`, `quaternion.multiply` |
-| Color | `color.set`, `color.blend` |
-| String | `string.set`, `string.concat` |
-| Boolean | `boolean.set`, `boolean.or`, `boolean.and` |
-| Array | `array.set`, `array.push`, `array.union`, `array.remove` |
-| Object | `object.set`, `object.merge` |
-| Node | `node.insert`, `node.remove` |
-| Meta | `meta.undo`, `meta.redo` |
+| Category | Operations | Merge Behavior |
+|----------|-----------|----------------|
+| Node | `node.insert`, `node.remove`, `node.move` | Idempotent / Tombstone |
+| Text | `text.init`, `text.insert`, `text.delete`, `text.replace` | CRDT (YATA) |
+| Number | `number.set`, `number.add`, `number.multiply`, `number.min`, `number.max` | LWW / Commutative |
+| String | `string.set`, `string.concat` | LWW / Append |
+| Boolean | `boolean.set`, `boolean.or`, `boolean.and` | LWW / Commutative |
+| Vector3 | `vector3.set`, `vector3.add`, `vector3.multiply`, `vector3.applyEuler`, `vector3.applyQuaternion` | LWW / Commutative |
+| Euler | `euler.set`, `euler.add` | LWW / Commutative |
+| Quaternion | `quaternion.set`, `quaternion.multiply` | LWW / Commutative |
+| Color | `color.set`, `color.blend` | LWW / Blend |
+| Array | `array.set`, `array.push`, `array.union`, `array.remove` | LWW / Set ops |
+| Object | `object.set`, `object.merge` | LWW / Merge |
+| Meta | `meta.undo`, `meta.redo` | Journal-based |
 
 ## Documentation
 

package/dist/client/EditBuffer.d.ts

@@ -5,6 +5,16 @@
  * Merges additive operations to reduce message size.
  */
 import type { Operation } from '../operations/OperationTypes.js';
+/**
+ * Compute the dedup key for an operation.
+ *
+ * Property operations use `key:path` — e.g. two `vector3.set` on the
+ * same node+path should merge/replace.
+ *
+ * Node structural operations include the target node key so that
+ * multiple inserts/removes under the same parent are NOT deduped.
+ */
+export declare function opDedupKey(op: Operation): string;
 /**
  * Check if an operation type is additive (can be merged)
  */

package/dist/client/EditBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EditBuffer.d.ts","sourceRoot":"","sources":["../../src/client/EditBuffer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAEjE;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKnD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAyB1E;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,OAAO,CAAgB;IAE/B;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAiBxB;;OAEG;IACH,MAAM,IAAI,SAAS,EAAE;IAIrB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,IAAI,IAAI,MAAM;CAGf"}
+{"version":3,"file":"EditBuffer.d.ts","sourceRoot":"","sources":["../../src/client/EditBuffer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAEjE;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAKhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKnD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAyB1E;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,OAAO,CAAgB;IAE/B;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAiBxB;;OAEG;IACH,MAAM,IAAI,SAAS,EAAE;IAIrB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,IAAI,IAAI,MAAM;CAGf"}

package/dist/client/EditBuffer.js

@@ -4,6 +4,24 @@
  * Accumulates uncommitted operations during gestures (e.g., dragging).
  * Merges additive operations to reduce message size.
  */
+/**
+ * Compute the dedup key for an operation.
+ *
+ * Property operations use `key:path` — e.g. two `vector3.set` on the
+ * same node+path should merge/replace.
+ *
+ * Node structural operations include the target node key so that
+ * multiple inserts/removes under the same parent are NOT deduped.
+ */
+export function opDedupKey(op) {
+    if (op.otype === 'node.insert')
+        return `${op.key}:${op.path}:insert:${op.value.key}`;
+    if (op.otype === 'node.remove')
+        return `${op.key}:${op.path}:remove:${op.value}`;
+    if (op.otype === 'node.move')
+        return `${op.key}:${op.path}:move:${op.value.nodeKey}`;
+    return `${op.key}:${op.path}`;
+}
 /**
  * Check if an operation type is additive (can be merged)
  */
@@ -52,7 +70,7 @@ export class EditBufferImpl {
      * Add or merge an operation
      */
     add(op) {
-        const key = `${op.key}:${op.path}`;
+        const key = opDedupKey(op);
         const existing = this.opsMap.get(key);
         if (existing && existing.otype === op.otype && isAdditiveOp(op.otype)) {
             // Merge additive ops

package/dist/client/EditBuffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"EditBuffer.js","sourceRoot":"","sources":["../../src/client/EditBuffer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EditBuffer.js","sourceRoot":"","sources":["../../src/client/EditBuffer.ts"],"names":[],"mappings":"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"}

package/dist/client/actions.d.ts

@@ -3,11 +3,14 @@
  *
  * Pure functions that transform ClientState.
  * Used by createGraph and React hooks.
+ *
+ * No Immer — manual immutable state construction to avoid proxy issues
+ * with mutable CRDT structures (TextRope, B-tree back-pointers, WeakMaps).
  */
 import type { CRDTMessage, Operation, SceneGraph } from '../operations/OperationTypes.js';
 import type { ClientState, JournalEntry, Snapshot } from './types.js';
 /**
- * Generate a UUID
+ * Generate a compact session ID (12-char nanoid, 2^72 entropy)
  */
 export declare function generateUUID(): string;
 /**
@@ -56,31 +59,26 @@ export declare function redo(state: ClientState): {
     msg: CRDTMessage | null;
 };
 /**
- * Action: Compact (create snapshot from acked entries)
+ * Action: Compact (create snapshot from acked entries).
+ *
+ * Folds all acknowledged entries into the snapshot and removes them from
+ * the journal. This reduces journal size (and bloom filter size for sync)
+ * but compacted entries can no longer be undone.
+ *
+ * Call this manually or on a periodic timer. Not called automatically
+ * because undo() requires target entries to be in the journal.
  */
 export declare function compact(state: ClientState): ClientState;
 /**
  * Get unacknowledged messages for retry
- *
- * Returns messages that haven't been acknowledged by the server.
- * Use this for implementing retry logic on network failures.
- *
- * @param state - Current client state
- * @returns Array of messages that need to be (re)sent to server
  */
 export declare function getUnackedMessages(state: ClientState): CRDTMessage[];
 /**
  * Check if there are pending messages to send
- *
- * @param state - Current client state
- * @returns True if there are unacknowledged messages
  */
 export declare function hasPendingMessages(state: ClientState): boolean;
 /**
  * Get count of pending (unacked) messages
- *
- * @param state - Current client state
- * @returns Number of unacknowledged messages
  */
 export declare function getPendingCount(state: ClientState): number;
 /**

package/dist/client/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/client/actions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAOtE;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,QAAQ,GAAG,WAAW,CAkB7F;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,YAAY,EAAE,EACvB,UAAU,EAAE,SAAS,EAAE,GACtB,UAAU,CA4BZ;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,GAAG,WAAW,CAqCrE;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CA6BjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAa3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAO1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,WAAW,CA8BjF;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAqDxF;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAyCxF;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CA2BvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,EAAE,CAIpE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,WAAW,EAAE,GACrB,WAAW,CAqCb"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/client/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAa,MAAM,iCAAiC,CAAC;AACrG,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAQtE;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,QAAQ,GAAG,WAAW,CAkB7F;AAmGD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,YAAY,EAAE,EACvB,UAAU,EAAE,SAAS,EAAE,GACtB,UAAU,CAkCZ;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,GAAG,WAAW,CAiErE;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CA0BjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAU3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAK1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,WAAW,CA8BjF;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAyDxF;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAoDxF;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CA0BvD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,EAAE,CAIpE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAE9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,WAAW,EAAE,GACrB,WAAW,CAqCb"}