---
name: bijection-multiplayer-cursors
description: "Evaluate and integrate the Multiplayer Cursors component with Bijection."
---

# Multiplayer Cursors

Shared cursor presence

- Package: @bijectionhq/multiplayer-cursors
- Category: Collaboration
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/multiplayer-cursors/tree/9d5f88da90a174276207115bf153eda2eb4cd346
- Upstream: https://github.com/Iann29/convex-multiplayer-cursors/tree/9b90a448c9a7c8d63b5bbe367dd4559d3e8e926e
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/multiplayer-cursors

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/multiplayer-cursors.git
cd multiplayer-cursors
git checkout 9d5f88da90a174276207115bf153eda2eb4cd346
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-multiplayer-cursors. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Multiplayer Cursors. Follow the installation and configuration steps exactly.

# Multiplayer Cursors

## Instructions

convex-multiplayer-cursors is a Convex component that provides Figma-style real-time cursor presence across rooms. It splits state into three tables (sessions, beats, positions) with distinct invalidation profiles so heartbeats trigger zero query re-runs and cursor movement invalidates only a single hot query. The React overlay drives DOM updates through a requestAnimationFrame loop with interpolated playback, producing zero React re-renders per cursor movement.

### Installation

```bash
npm install convex-multiplayer-cursors
```

Current npm version: `convex-multiplayer-cursors@0.2.1`

## Use cases

- Adding live cursor presence to a collaborative document or whiteboard editor where multiple users work in the same room simultaneously
- Building a design tool or canvas where you need smooth, interpolated remote cursor trails rather than teleporting positions
- Implementing read-only cursor observation (broadcast={false}) so viewers can see collaborator positions without transmitting their own
- Scoping cursor rooms to organizational or document boundaries server-side, keeping presence isolated per tenant or per artifact
- Integrating multiplayer presence into an existing Convex app without coupling cursor logic to your main schema or query invalidation graph

## How it works

The component mounts via `app.use(cursors)` in `convex/convex.config.ts` and exposes isolated tables for sessions, beats, and positions. You write thin authenticated wrappers in your own `convex/cursors.ts` that call `cursors.listSessions`, `cursors.beat`, `cursors.flush`, and related methods, passing `userId` resolved server-side from `ctx.auth`. The `roomKey` helper scopes rooms to an org or document boundary. This keeps the component auth-agnostic while enforcing ownership invariants on every write.

On the server, room capacity is enforced at write time, flush rate is throttled to one batch per 66ms per session, and session ownership is validated so foreign beats and flushes are rejected. Cleanup runs as a scheduled expiry per heartbeat plus opportunistic pruning by live sessions, avoiding a single background sweep that would wake all queries.

The `CursorsOverlay` React component accepts your generated `api.cursors` object and a `path` arg, then subscribes to positions outside the React render cycle using `watchQuery`. Cursor positions are written to the DOM in a rAF loop with `lagMs` (default 260ms) of deliberate playback delay, ensuring there is always a next sample to interpolate toward. For custom rendering, the `useCursors` hook and exported `timeline` and `sampler` utilities are available as primitives.

Defaults are TTL 45s, heartbeat every 20s, flush every 200ms, 32 samples per batch, and up to 128 sessions per room. The package ships plain TypeScript with no build step, consuming directly via Convex's esbuild or Vite. Next.js users add the package to `transpilePackages`. A `cursorsTest` export lets consumers register the component in their own `convex-test` suites.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Multiplayer Cursors is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-multiplayer-cursors)
- [GitHub repository](https://github.com/Iann29/convex-multiplayer-cursors)
- [Live demo](https://github.com/Iann29/convex-multiplayer-cursors/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/convex-multiplayer-cursors)
- [Convex documentation](https://docs.convex.dev)