# Getting Started

## Installation

```bash
pnpm add @vuer-ai/vuer-rtc
```

### Claude Code Skill

Add vuer-rtc knowledge to Claude Code for intelligent assistance with the library:

**Option 1: Plugin Marketplace** (Recommended)

```bash
# Add the marketplace (one-time setup)
/plugin marketplace add vuer-ai/vuer-rtc-workspace

# Install the skill
/plugin install vuer-rtc@vuer-rtc
```

**Option 2: CLAUDE.md Import**

Add to your project's `CLAUDE.md`:

```markdown
@import https://raw.githubusercontent.com/vuer-ai/vuer-rtc-workspace/main/skill/vuer-rtc.md
```

After installation, Claude Code will have access to:
- **vuer-rtc skill** — CRDT operations, client state, React hooks, and text collaboration
- Context-aware assistance for scene graph operations

To verify installation:
```bash
/plugin list
```

> **Note:** The skill uses hierarchical documentation — Claude loads a structured overview first, then fetches detailed docs as needed for specific operations.

## Quick Start

```typescript

// Create a graph store
const store = createGraph({
  sessionId: 'my-session',
  onSend: (msg) => websocket.send(msg),
});

// Edit (uncommitted, updates UI immediately)
store.edit({
  ot: 'node.insert',   // Learn about all [Operations](/operations.md)
  key: 'scene',           // Parent node's key
  path: 'children',
  value: { key: 'cube', tag: 'Mesh', name: 'Cube' },
});

// Commit (sends to server as one message)
store.commit('Create cube');

// Receive from server
websocket.onmessage = (msg) => store.receive(msg);

// Undo/redo (synced across all clients)
store.undo();
store.redo();
```

## Core Concepts

### State Model

The client maintains four key data structures:

```typescript
interface ClientState {
  graph: SceneGraph;       // Current computed state
  journal: JournalEntry[]; // Committed messages
  edits: EditBuffer;       // Uncommitted operations
  snapshot: Snapshot;      // Checkpoint for fast replay
}
```

| Component | Purpose |
|-----------|---------|
| `graph` | Current state shown in UI. Derived from snapshot + journal + edits. |
| `journal` | Committed messages. Tracks ack status and deletion (undo) state. |
| `edits` | Uncommitted ops. Merged during gestures, committed as one message. |
| `snapshot` | Periodic checkpoint. Bakes in acked entries for fast replay. |

### Edit Buffer

Operations are accumulated in the edit buffer during gestures (like dragging),
then committed as a single message:

```typescript
// During drag (60fps)
store.edit({ ot: 'vector3.add', key: 'cube', path: 'position', value: [0.1, 0, 0] });
store.edit({ ot: 'vector3.add', key: 'cube', path: 'position', value: [0.1, 0, 0] });
// ... many more

// On drag end - all edits become ONE message
store.commit('Move cube');
// Sends: { ops: [{ ot: 'vector3.add', value: [5.0, 0, 0] }] }
```

> **Note:** The edit buffer **merges additive operations**, so 60 small deltas become 1 message.

### Messages & Operations

Changes are expressed as messages containing one or more operations:

```typescript
interface CRDTMessage {
  id: string;           // Unique message ID
  sessionId: string;    // Who sent this
  clock: VectorClock;   // For causal ordering
  lamportTime: number;  // For LWW ordering
  timestamp: number;    // Wall clock
  ops: Operation[];     // Batch of operations
}
```

### Undo / Redo

Undo and redo are **synced messages** that mark entries with `deletedAt`:

```typescript
// Undo the last committed message from this session
const { msg } = store.undo();
// Creates: { ops: [{ ot: 'meta.undo', targetMsgId: 'msg-123' }] }
// Syncs to all clients - everyone sees the undo

// Redo the last undone message
store.redo();
// Creates: { ops: [{ ot: 'meta.redo', targetMsgId: 'msg-123' }] }
```

> **Note:** All clients see the same undo state. Undo is not local-only.

## Conflict Resolution

| Operation | Merge Strategy | Example |
|-----------|---------------|---------|
| `*.set` | Last-Write-Wins (higher lamport) | `color.set '#ff0000'` |
| `*.add` | Sum values | `vector3.add [1, 0, 0]` |
| `meta.undo` | Sets `deletedAt` on target | Synced undo |
| `meta.redo` | Clears `deletedAt` on target | Synced redo |

## Next Steps

<div className="flex flex-wrap gap-4 not-prose">
  <a
    href="/architecture"
    className="inline-flex items-center px-5 py-2 bg-blue-600 dark:bg-blue-500 text-white rounded-full hover:bg-blue-700 dark:hover:bg-blue-600"
  >
    Architecture
  </a>
  <a
    href="/react-hooks"
    className="inline-flex items-center px-5 py-2 border border-gray-300 dark:border-gray-600 rounded-full hover:bg-gray-50 dark:hover:bg-gray-800 text-gray-900 dark:text-gray-100"
  >
    React Hooks
  </a>
  <a
    href="/operations"
    className="inline-flex items-center px-5 py-2 border border-gray-300 dark:border-gray-600 rounded-full hover:bg-gray-50 dark:hover:bg-gray-800 text-gray-900 dark:text-gray-100"
  >
    Operations
  </a>
  <a
    href="/examples"
    className="inline-flex items-center px-5 py-2 border border-gray-300 dark:border-gray-600 rounded-full hover:bg-gray-50 dark:hover:bg-gray-800 text-gray-900 dark:text-gray-100"
  >
    Examples
  </a>
</div>

---

**Next:** See the [Complete Integration Guide](/integration-guide) and [Examples](/examples.md) to build your first collaborative application.