@vuer-ai/vuer-rtc 0.1.2 → 0.2.1

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/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;AAyBD;;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,CAgDrE;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,CA6BjF;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAsDxF;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAwCxF;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"}