# Live Cursor Tracker (/docs/experiments/live-cursor-tracker)



Broadcast cursor positions to every client in a shared room using a **Durable Object** and the **WebSocket Hibernation API**. Open multiple tabs to `/` and move your mouse to see colored cursors sync in real time.

## Features [#features]

* **GET /** - Demo page with canvas and WebSocket client
* **GET /ws/:room** - WebSocket upgrade; one DO instance per room name
* **Hibernation API** - `acceptWebSocket`, `webSocketMessage`, `webSocketClose`
* **Colored cursors** - Each client gets a stable color and guest label

## API Reference [#api-reference]

### GET / [#get-]

Returns an HTML demo page with inline JavaScript that connects to `/ws/:room`.

Open `http://localhost:8787/` in two browser tabs to test locally.

### GET /ws/:room [#get-wsroom]

Upgrades to WebSocket and joins the room's Durable Object.

**`room`** `string` (path, required)

Room name: letters, numbers, `_`, or `-` (max 64 characters).

#### Client messages (JSON) [#client-messages-json]

Send cursor position updates:

```json
{ "x": 120, "y": 340 }
```

#### Server messages (JSON) [#server-messages-json]

```json
{ "type": "join", "id": "uuid", "color": "#3b82f6", "name": "Guest-a1b2" }
{ "type": "cursor", "id": "uuid", "x": 120, "y": 340, "color": "#3b82f6", "name": "Guest-a1b2" }
{ "type": "leave", "id": "uuid", "color": "#3b82f6", "name": "Guest-a1b2" }
```

#### Error Codes [#error-codes]

* `400` - Invalid room name (`INVALID_ROOM`)
* `426` - Missing WebSocket upgrade header

## Use Cases [#use-cases]

* Learn Durable Object WebSocket hibernation patterns
* Prototype collaborative UI features (cursors, presence, cursors-on-canvas)
* Demo real-time broadcast without an external pub/sub service

## Limitations [#limitations]

* No authentication; any client can join any room name
* Cursor state is ephemeral (not persisted to storage)
* Demo page only; production apps would use a custom frontend

## Deployment [#deployment]

<Steps>
  <Step>
    ### Click the deploy button [#click-the-deploy-button]

    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/live-cursor-tracker)
  </Step>

  <Step>
    ### Deploy [#deploy]

    Durable Object migration is included in `wrangler.json`. No additional bindings required.
  </Step>
</Steps>

## Local Development [#local-development]

```bash
cd apps/experiments/live-cursor-tracker
npm install
npm run dev
```

Open `http://localhost:8787/` in two tabs.

## Configuration [#configuration]

| Binding | Purpose                                       |
| ------- | --------------------------------------------- |
| `ROOMS` | Durable Object namespace (`CursorRoom` class) |

## Cloudflare Features Used [#cloudflare-features-used]

* **[Workers](https://developers.cloudflare.com/workers/)** - Edge compute runtime
* **[Durable Objects](https://developers.cloudflare.com/durable-objects/)** - Room-scoped WebSocket coordination
* **WebSocket Hibernation API** - Efficient long-lived connections