# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

rrweb is a web session recording and replay library. It records user interactions on web pages (DOM mutations, mouse movements, input events, etc.) and can replay them faithfully. The project is a TypeScript monorepo managed by Yarn workspaces and Turborepo.

## Common Commands

```bash
# Install dependencies (use yarn, NOT npm)
yarn install

# Build all packages
yarn build:all

# Watch mode for all packages (auto-rebuild on changes)
yarn dev

# Run all tests across the monorepo
yarn test

# Run tests for a specific package (run from package directory)
cd packages/rrweb && yarn test          # builds then runs tests
cd packages/rrweb && yarn retest        # runs tests without rebuild (faster)
cd packages/rrweb-snapshot && yarn test

# Watch mode tests for a specific package
cd packages/rrweb && yarn test:watch

# Update test snapshots
cd packages/rrweb && yarn test:update   # or retest:update for no rebuild

# Lint
yarn lint

# Format
yarn format

# Type check all packages
yarn check-types

# REPL tool (interactive testing in browser)
yarn repl
```

## Architecture

### Package Dependency Graph

The core data flow is: **snapshot** captures DOM → **record** observes mutations → **replay** reconstructs events.

```
@rrweb/types          (shared type definitions, no deps)
@rrweb/utils          (shared utilities)
rrweb-snapshot        (DOM serialization/deserialization, depends on types/utils)
rrdom / rrdom-nodejs  (virtual DOM for Node.js environments)
rrweb                 (main package: record + replay, depends on all above)
  ├── src/record/     (DOM mutation observers, event capture, canvas recording)
  └── src/replay/     (event replay engine, timer, canvas replay, style injection)
rrweb-player          (Svelte-based player UI)
@rrweb/all            (convenience package combining record + replay)
@rrweb/packer         (pack/unpack utilities for rrweb event data)
```

### Plugin System

Plugins live in `packages/plugins/` and follow a record/replay pair pattern:
- `rrweb-plugin-console-record` / `rrweb-plugin-console-replay` — console logging
- `rrweb-plugin-canvas-webrtc-record` / `rrweb-plugin-canvas-webrtc-replay` — canvas via WebRTC
- `rrweb-plugin-sequential-id-record` / `rrweb-plugin-sequential-id-replay` — sequential IDs

### Build System

- **Turbo** orchestrates builds via `turbo.json` with task dependency graph
- Each package uses **Vite** in library mode (`vite.config.default.ts` shared config)
- Output formats: ES modules (`.js`), CommonJS (`.cjs`), UMD (`.umd.cjs`), plus TypeScript declarations (`.d.ts` / `.d.cts`)
- `DISABLE_WORKER_INLINING=true` env var disables worker inlining for Chrome extension builds
- Test runner is **Vitest** (some older packages still use Jest)
- Tests in `packages/rrweb` use **Puppeteer** for browser-based integration tests; set `PUPPETEER_HEADLESS=true` for headless mode

### Key Source Paths

- `packages/rrweb/src/record/` — recording logic (mutation observer, iframe/shadow-dom managers, canvas observers)
- `packages/rrweb/src/replay/` — replay engine (timer, state machine via @xstate/fsm, canvas replay, style injection)
- `packages/rrweb/src/entries/record.ts` / `replay.ts` — separate entry points for record-only or replay-only bundles
- `packages/rrweb-snapshot/src/snapshot.ts` — DOM → serializable data structure
- `packages/rrweb-snapshot/src/rebuild.ts` — serialized data → DOM reconstruction
- `packages/types/src/` — shared event types (`eventWithTime`, `EventType`, `IncrementalSource`)

### ESLint Configuration

- Uses `@typescript-eslint` with type-checked rules
- `camelCase` rule allows `rr_`, `legacy_`, `UNSAFE_`, `__rrweb_` prefixed identifiers
- TSDoc syntax is enforced via `eslint-plugin-tsdoc`
- Browser compatibility checked via `eslint-plugin-compat`