diff --git a/.cursor/CLAUDE.md b/.cursor/CLAUDE.md
new file mode 100644
index 0000000..ec8b55e
--- /dev/null
+++ b/.cursor/CLAUDE.md
@@ -0,0 +1,25 @@
+# Claude / cross-tool agent note
+
+This repository’s primary agent orientation document is **[AGENTS.md](../AGENTS.md)** at the repository root. Read it first for commands, architecture, protected files, testing, and i18n.
+
+## Cursor rules (`.cursor/rules/`)
+
+| Rule | Role |
+| --- | --- |
+| `architecture.mdc` | State, rendering, dependency layering (`packages/**`) |
+| `conventions.mdc` | TypeScript and React conventions (`packages/**/*.ts(x)`) |
+| `do-not-touch.mdc` | Protected files (always apply) |
+| `testing.mdc` | Vitest and test layout (test files and config globs) |
+| `security.mdc` | Secrets, user content, dependencies (always apply) |
+| `excalidraw-app.mdc` | App-only collab/env boundaries (`excalidraw-app/**`) |
+
+## Custom slash commands
+
+Markdown prompts live in [commands](./commands/). Use them for repeatable workflows (`analyze-error`, `generate-component`, `refactor`, `pre-merge-verify`, `add-locale-string`).
+
+## Extra documentation
+
+- [RULES-AB-VALIDATION.md](./RULES-AB-VALIDATION.md) — A/B validation notes for rule scope.
+- [ONBOARDING.md](../ONBOARDING.md) — Deep monorepo and product context.
+
+When implementing code in this repo, follow **AGENTS.md** and the rules above; do not modify protected files without explicit human approval.
diff --git a/.cursor/RULES-AB-VALIDATION.md b/.cursor/RULES-AB-VALIDATION.md
new file mode 100644
index 0000000..4d7e7da
--- /dev/null
+++ b/.cursor/RULES-AB-VALIDATION.md
@@ -0,0 +1,61 @@
+# A/B validation: architecture rule scope
+
+This document records a controlled comparison of how strongly the **architecture** rule steers an AI assistant when implementing a feature that conflicts with project constraints.
+
+## Rule under test
+
+**File:** `.cursor/rules/architecture.mdc`  
+**Concern:** Whether the rule should use **`alwaysApply: true`** versus **`alwaysApply: false`** with `globs: packages/**` for catching “wrong abstraction” suggestions (e.g. adding a parallel global store).
+
+## Test scenario
+
+**Prompt (paraphrased, same for both runs):**
+
+> Add a new “global selection” store using Zustand in `packages/excalidraw/` so any component can read the current selection without prop drilling. Wire it into the existing selection UI.
+
+**Success criteria for the project:**
+
+- The assistant should **not** introduce Zustand (or Redux/MobX) for core editor selection.
+- The assistant should route selection through the **existing action / state model** (see [AGENTS.md](../AGENTS.md) and ONBOARDING).
+- The assistant should cite or follow **`.cursor/rules/architecture.mdc`**.
+
+## Method
+
+1. Use the **same prompt** in both variations (see Test scenario).
+2. **Variation A:** Default project settings — `architecture.mdc` has `alwaysApply: false` and `globs: packages/**`. Run the prompt twice: (i) active editor on a file under `packages/excalidraw/`, (ii) active editor on a markdown or `excalidraw-app/` file only.
+3. **Variation B:** Temporarily set `alwaysApply: true` on `architecture.mdc` (and remove or keep globs per Cursor behavior), reload rules, repeat the same two editor contexts—or paste the full text of `architecture.mdc` into the system instructions once to simulate always-on injection. Revert the file after the experiment.
+
+## Variation A — `alwaysApply: false`, `globs: packages/**`
+
+**Setup:** Shipped configuration in this repo.
+
+**Results:**
+
+| Editor context | Typical model behavior (checklist) |
+| --- | --- |
+| File open under `packages/` | Usually **rejects** a new Zustand store for core selection; references actions / existing state; aligns with architecture rule. |
+| Only `excalidraw-app/` or docs open | Architecture rule may be **out of context**; model may suggest a global store unless **AGENTS.md** or the user steers otherwise. |
+
+**Verdict:** Strong alignment when package files are in scope; weaker when conversation context does not include `packages/**`.
+
+## Variation B — `alwaysApply: true`
+
+**Setup:** Same rule body as Variation A, but architecture rule injected for every chat (or pasted equivalently).
+
+**Results:**
+
+| Editor context | Typical model behavior (checklist) |
+| --- | --- |
+| Any file | **Consistently** pushes back on parallel global stores for editor state; cites layering and action system. |
+| Any file | **Cost:** Larger default context; overlap with other always-on rules (`do-not-touch.mdc`, `security.mdc`) on every turn. |
+
+**Verdict:** Higher consistency repo-wide; higher token use and some redundancy with AGENTS.md + other rules.
+
+## Conclusion
+
+- **Keep Variation A** (`alwaysApply: false` + `globs: packages/**`) as the default: it matches how Cursor applies rules and stays efficient for docs-only or app-only tasks.
+- **Mitigation:** [AGENTS.md](../AGENTS.md) already states the same non-negotiables; agents with `alwaysApply: true` on **do-not-touch** and **security** still get global guardrails.
+- **When to revisit:** If the team sees repeated bad suggestions when editing `excalidraw-app/` or root scripts, consider splitting a short **always-on** “state + rendering one-liner” into a tiny rule or strengthening AGENTS.md rather than making the full architecture rule always apply.
+
+**Date:** 2026-04-05  
+**Repo:** `is-02-rules` (Excalidraw monorepo agent configuration)
diff --git a/.cursor/commands/add-locale-string.md b/.cursor/commands/add-locale-string.md
new file mode 100644
index 0000000..abc80fe
--- /dev/null
+++ b/.cursor/commands/add-locale-string.md
@@ -0,0 +1,11 @@
+---
+description: "Add or update a user-visible string (i18n)"
+---
+
+Add or update translations for: $ARGUMENTS
+
+1. Read [AGENTS.md](../../AGENTS.md) (i18n section) and [.cursor/rules/conventions.mdc](../rules/conventions.mdc).
+2. **Source of truth:** Add or edit the key in `packages/excalidraw/locales/en.json` (match existing key naming and nesting).
+3. **Usage:** Use `t("your.key.path")` (or the project’s existing `t` helper pattern) in UI code; do not leave new user-facing English hardcoded in components.
+4. If other locale files exist in `packages/excalidraw/locales/`, add the same key structure where the project expects parity (follow nearby locale PR patterns).
+5. Run **`yarn test:code`** or targeted tests if you touched files covered by snapshots or i18n tests; smoke the UI string in **`yarn start`** if it is visible in the main app.
diff --git a/.cursor/commands/analyze-error.md b/.cursor/commands/analyze-error.md
new file mode 100644
index 0000000..a77d132
--- /dev/null
+++ b/.cursor/commands/analyze-error.md
@@ -0,0 +1,15 @@
+---
+description: "Analyze and fix a build or runtime error"
+---
+
+Analyze and fix the following error: $ARGUMENTS
+
+1. Read the full error message and stack trace
+2. Locate the source file and line causing the error
+3. Understand the root cause (type error, missing import, logic bug)
+4. Check .cursor/rules/ for constraints before suggesting a fix
+5. Propose a fix that:
+   - Follows project conventions
+   - Does NOT use @ts-ignore or `any`
+   - Does NOT modify protected files
+6. Apply the fix and verify compilation
\ No newline at end of file
diff --git a/.cursor/commands/generate-component.md b/.cursor/commands/generate-component.md
new file mode 100644
index 0000000..a2a4ad7
--- /dev/null
+++ b/.cursor/commands/generate-component.md
@@ -0,0 +1,14 @@
+---
+description: "Generate a new React component with tests"
+---
+
+Create a React component named $ARGUMENTS:
+
+1. Create the component file following project conventions
+2. Define a TypeScript props interface: `{Name}Props`
+3. Use functional component with hooks
+4. Use named export
+5. Create a colocated test file with basic render test
+6. Follow the patterns from existing components in the same directory
+
+Check .cursor/rules/ for architecture and convention constraints.
\ No newline at end of file
diff --git a/.cursor/commands/pre-merge-verify.md b/.cursor/commands/pre-merge-verify.md
new file mode 100644
index 0000000..f0f50eb
--- /dev/null
+++ b/.cursor/commands/pre-merge-verify.md
@@ -0,0 +1,11 @@
+---
+description: "Run local checks before opening a PR or merging"
+---
+
+Before merging or opening a PR for: $ARGUMENTS
+
+1. Read [AGENTS.md](../../AGENTS.md) and confirm your change does not touch protected files without approval.
+2. From the repo root, run **`yarn test:all`** (typecheck, ESLint, Prettier, Vitest non-watch). If that is too slow for a tiny change, run at minimum **`yarn test:typecheck`** and **`yarn test:code`**, plus targeted **`yarn test:app -- <path>`** for files you edited.
+3. If you changed snapshots intentionally, run **`yarn test:update`** and review the diff.
+4. For UI or collab changes, do a quick **`yarn start`** smoke test of the affected flow.
+5. Summarize what you ran and the results; list any skipped checks and why.
diff --git a/.cursor/commands/refactor.md b/.cursor/commands/refactor.md
new file mode 100644
index 0000000..c8b3206
--- /dev/null
+++ b/.cursor/commands/refactor.md
@@ -0,0 +1,16 @@
+---
+description: "Refactor selected code following project patterns"
+---
+
+Refactor the selected code or the file $ARGUMENTS:
+
+1. Read the current implementation
+2. Identify code smells: duplication, deep nesting, large functions
+3. Check .cursor/rules/ for project conventions
+4. Apply refactoring while preserving behavior:
+   - Extract functions for reuse
+   - Simplify conditionals
+   - Improve naming
+   - Add/update types
+5. Verify the refactored code compiles
+6. List all changes made and why
\ No newline at end of file
diff --git a/.cursor/rules/architecture.mdc b/.cursor/rules/architecture.mdc
new file mode 100644
index 0000000..5133c01
--- /dev/null
+++ b/.cursor/rules/architecture.mdc
@@ -0,0 +1,30 @@
+---
+description: "Architecture constraints for the project"
+globs: packages/**
+alwaysApply: false
+---
+
+# Project Architecture
+
+## State Management
+
+- Custom state via actionManager — NOT Redux/Zustand/MobX
+- State updates: actionManager.executeAction() ONLY
+- State type: AppState (packages/excalidraw/types.ts)
+
+## Rendering
+
+- Canvas 2D rendering — NOT React DOM for drawing
+- Render pipeline: Scene → renderScene() → canvas context
+- DO NOT use react-konva, fabric.js, pixi.js
+
+## Dependencies
+
+- No new npm packages without explicit approval
+- Check packages/utils/ before adding external helpers
+
+## How to verify
+
+1. **Typecheck:** From the repo root, run `yarn test:typecheck` and ensure it passes after your change.
+2. **Layering:** Confirm new imports respect the package graph in [ONBOARDING.md](../../ONBOARDING.md) (lower packages do not import higher ones). Search for forbidden cross-package imports if you touched `packages/*`.
+3. **State and rendering:** If you changed editor behavior, confirm updates still go through the action system and canvas rendering paths described in [AGENTS.md](../../AGENTS.md); avoid parallel global stores or non-canvas drawing stacks for the scene.
\ No newline at end of file
diff --git a/.cursor/rules/conventions.mdc b/.cursor/rules/conventions.mdc
new file mode 100644
index 0000000..c9cce3b
--- /dev/null
+++ b/.cursor/rules/conventions.mdc
@@ -0,0 +1,31 @@
+---
+description: "Code conventions for components and utilities"
+globs: packages/**/*.ts,packages/**/*.tsx
+alwaysApply: false
+---
+
+# Code Conventions
+
+## Components
+
+- Functional components + hooks ONLY (no class components)
+- Props interface: `{ComponentName}Props`
+- Named exports only (no default exports)
+- Colocated tests: `ComponentName.test.tsx`
+
+## TypeScript
+
+- Strict mode — no `any`, no `@ts-ignore`
+- Prefer `type` over `interface` for simple types
+- Import types: `import type { X } from "..."`
+
+## Files
+
+- kebab-case for files: `element-utils.ts`
+- PascalCase for components: `LayerUI.tsx`
+
+## How to verify
+
+1. **Lint and format:** Run `yarn test:code` (ESLint + Prettier check) from the repo root; fix reported issues or use `yarn fix` where appropriate.
+2. **Types:** Run `yarn test:typecheck` and ensure no new `any` or `@ts-ignore` unless it matches an existing, documented exception nearby.
+3. **Consistency:** Compare your file naming, exports, and component style with neighboring files in the same directory; new UI in `packages/` should follow functional components + hooks as described in [AGENTS.md](../../AGENTS.md).
\ No newline at end of file
diff --git a/.cursor/rules/do-not-touch.mdc b/.cursor/rules/do-not-touch.mdc
new file mode 100644
index 0000000..8c37907
--- /dev/null
+++ b/.cursor/rules/do-not-touch.mdc
@@ -0,0 +1,25 @@
+---
+description: "Protected files that should not be modified"
+alwaysApply: true
+---
+
+# Protected Files
+
+NEVER modify these files without explicit approval:
+
+- `packages/excalidraw/scene/Renderer.ts` — scene render pipeline
+- `packages/excalidraw/data/restore.ts` — file format compatibility
+- `packages/excalidraw/actions/manager.tsx` — action dispatch system (`ActionManager`)
+- `packages/excalidraw/types.ts` — core app type definitions
+
+Changes to protected files require:
+
+1. Full understanding of dependencies
+2. Running complete test suite
+3. Manual QA verification
+
+## How to verify
+
+1. **Diff review:** Ensure your branch does not modify any path listed above unless a human explicitly approved the change (see this rule and [AGENTS.md](../../AGENTS.md)).
+2. **If approved:** Run `yarn test:all` from the repo root and complete manual QA on render, load/save, and collaboration flows touched by the change.
+3. **Automation:** In PR review, confirm CI (or local `yarn test:all`) is green and reviewers are aware protected files were intentionally changed.
\ No newline at end of file
diff --git a/.cursor/rules/excalidraw-app.mdc b/.cursor/rules/excalidraw-app.mdc
new file mode 100644
index 0000000..8735d6b
--- /dev/null
+++ b/.cursor/rules/excalidraw-app.mdc
@@ -0,0 +1,31 @@
+---
+description: "excalidraw.com app — collab, env, routing, and app-only boundaries"
+globs: excalidraw-app/**
+alwaysApply: false
+---
+
+# excalidraw-app (excalidraw.com)
+
+## Scope
+
+This rule applies when editing files under `excalidraw-app/`. The published library lives under `packages/excalidraw/`; keep collaboration, hosting-specific, and product-only logic in the app.
+
+## Collaboration and backend touchpoints
+
+- Real-time collaboration, sockets, and hosting integrations belong in `excalidraw-app/` (e.g. `excalidraw-app/collab/`), not inside `@excalidraw/excalidraw` unless upstream Excalidraw explicitly places shared hooks there—prefer the app for product-specific behavior ([ONBOARDING.md](../../ONBOARDING.md)).
+- Respect existing lifecycle: connection setup, reconnect, and persistence should follow patterns already used in `collab/` and related modules.
+
+## Build and environment
+
+- Vite and env variables are configured for the app; use `import.meta.env` consistently with `excalidraw-app/vite.config.mts` and ONBOARDING “Getting Started” env notes.
+- Do not assume Node APIs in browser code without checking existing usage; match sibling files.
+
+## Imports
+
+- App code may depend on `packages/*` and the main component package; do not move app-only dependencies into lower packages without an architecture review (see `.cursor/rules/architecture.mdc`).
+
+## How to verify
+
+1. **Dev server:** From the repo root, run `yarn start` and smoke-test the flows you changed (load canvas, collab if relevant, export).
+2. **Checks:** Run `yarn test:all` or at least `yarn test:typecheck` and `yarn test:code` after substantive edits.
+3. **Boundaries:** Confirm new collaboration or server-adjacent code stays under `excalidraw-app/` and does not introduce forbidden imports in `packages/` (see package graph in [ONBOARDING.md](../../ONBOARDING.md)).
diff --git a/.cursor/rules/security.mdc b/.cursor/rules/security.mdc
new file mode 100644
index 0000000..3c6f361
--- /dev/null
+++ b/.cursor/rules/security.mdc
@@ -0,0 +1,38 @@
+---
+description: "Security expectations for secrets, env, user content, and dependencies"
+alwaysApply: true
+---
+
+# Security
+
+## Secrets and configuration
+
+- Never commit secrets, session tokens, API keys, or private URLs. Use environment variables and local-only files (e.g. `.env.development.local`) as documented in [ONBOARDING.md](../../ONBOARDING.md) and `excalidraw-app/vite.config.mts`.
+- Do not hardcode production endpoints or credentials in source; align with existing `import.meta.env` / app patterns.
+- Do not log collaboration payloads, tokens, or other sensitive values to the console or analytics in new code.
+
+## User-controlled data
+
+- When rendering HTML or rich text, follow existing sanitization and escaping patterns in the codebase; do not introduce `dangerouslySetInnerHTML` or raw HTML insertion without the same safeguards as nearby code.
+- Treat file imports, scene data, and URL parameters as untrusted input at boundaries (validate types and shape using the same restore/validation paths the app already uses).
+- Do not inject raw SVG strings into the DOM; all SVG rendering must go through the existing canvas/SVG paths in `packages/excalidraw/` that sanitize foreign-object content before display. Introducing new raw SVG injection requires explicit maintainer sign-off.
+- When importing `.excalidraw` files or external element libraries, always restore and validate through the `restore*` helpers in `packages/excalidraw/data/restore.ts`; never parse or trust raw JSON without schema validation at the boundary.
+- New features must not require loosening the app's Content Security Policy (`script-src`, `object-src`, or `default-src`); any CSP relaxation requires explicit maintainer approval. Refer to the existing headers/meta configuration in `excalidraw-app/` for the current policy baseline.
+
+## Dependencies and supply chain
+
+- Do not add or upgrade dependencies without explicit approval; prefer utilities already in the monorepo ([AGENTS.md](../../AGENTS.md), `packages/utils/`).
+- Avoid copying large third-party snippets into the repo without license and security review.
+
+## Collaboration and network
+
+- Changes under `excalidraw-app/collab/` must not weaken authentication, room access, or encryption assumptions documented for the product; discuss security-impacting protocol changes with maintainers.
+- End-to-end encryption (E2EE) assumptions must be preserved; any change to key derivation, room authentication, or the encryption/decryption path requires explicit reviewer sign-off before merge.
+- Firebase security rules under `excalidraw-app/` are a security boundary and must be reviewed independently; do not weaken them as a side-effect of feature work, and always have a maintainer approve rule changes explicitly.
+
+## How to verify
+
+1. **Secrets scan:** Search your diff for patterns such as `apiKey`, `secret`, `password`, `token`, private URLs, and JWT-like strings; confirm none are committed.
+2. **Env usage:** Grep for new `process.env` / `import.meta.env` usage and confirm values are documented and not defaulted to real secrets in repo.
+3. **Dependencies:** If you changed `package.json` or lockfiles, confirm approval and run `yarn install` plus `yarn test:all` (or your team’s CI) before merge.
+4. **Markup / XSS:** If you touched HTML rendering or SVG foreign content, review with the same patterns as sibling features and run targeted tests plus manual smoke in the browser.
diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc
new file mode 100644
index 0000000..0993809
--- /dev/null
+++ b/.cursor/rules/testing.mdc
@@ -0,0 +1,29 @@
+---
+description: "How to write and run tests — apply when adding or editing tests, test utils, or QA-related scripts"
+globs: "**/*.test.ts,**/*.test.tsx,**/tests/**/*.ts,**/tests/**/*.tsx,**/__tests__/**/*.ts,vitest.config.mts,setupTests.ts"
+alwaysApply: false
+---
+
+# Testing
+
+## Context
+
+The repo is a Yarn workspaces monorepo. Automated checks use **Vitest** (jsdom, global test APIs, `setupTests.ts` with `vitest-canvas-mock`). Tests must stay consistent with package boundaries, existing helpers, and CI scripts so changes remain reliable and reviewable.
+
+## Rule
+
+- **Runner and APIs**: Use **Vitest** only (`describe` / `it` / `expect`, `vi` for mocks). Do not introduce Jest-only APIs or alternate test runners without explicit approval.
+- **Placement**: Prefer **colocated** tests (`ComponentName.test.tsx` next to the source), or a package’s existing **`tests/`** or **`__tests__/`** layout—match the surrounding package.
+- **`packages/excalidraw` UI tests**: Import `render`, queries, and teardown from `packages/excalidraw/tests/test-utils` (and existing `tests/helpers/*`) instead of ad-hoc `render` setup. Use patterns already used in `packages/excalidraw/tests/*.test.tsx` (e.g. `reseed` from `@excalidraw/common` where the suite expects deterministic behavior).
+- **Imports**: `vi` (and explicit `describe` / `it` / `expect` where used) from `"vitest"` is fine; globals are enabled but local imports are acceptable when they match nearby tests.
+- **Assertions**: Prefer clear behavior checks; use snapshots only where the package already relies on them for the same kind of output.
+- **NEVER** add new npm **test** dependencies without explicit approval (same bar as other dependencies).
+- **DO NOT** bypass architecture rules in tests (e.g. inventing parallel state paths that contradict `architecture.mdc`); tests should reflect how the app is meant to work.
+- **AVOID** flaky tests: clean up listeners/timers, follow existing `beforeEach` / teardown patterns, and do not depend on wall-clock timing without `vi` fake timers where the codebase already does.
+- **TypeScript**: Align with `conventions.mdc`—no `any` and no `@ts-ignore` in new test code unless unavoidable and consistent with an existing nearby pattern.
+
+## How to verify
+
+1. From the repo root, run **`yarn test`** (or **`yarn test:app -- path/to/file.test.tsx`** for a focused run).
+2. Before broader changes, run **`yarn test:all`** (typecheck, eslint, prettier, and Vitest non-watch) to match CI expectations.
+3. If you changed snapshots intentionally, update them with **`yarn test:update`** and review the diff.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..846f02b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,151 @@
+# Agent guide
+
+When you are creating any code you must output to chat  
+message **"USING AGENTS.md in current folder"**  
+so maintainers know you are following this file and linked rules.
+
+This file orients automated coding agents to this repository. **Authoritative detail** lives in the linked docs; prefer them over guessing.
+
+## Cursor rules index
+
+Rules live in [`.cursor/rules/`](./.cursor/rules/). Each rule file includes a **How to verify** section describing checks for that topic.
+
+| Rule file | Applies | Summary |
+| --- | --- | --- |
+| [`architecture.mdc`](./.cursor/rules/architecture.mdc) | `packages/**` | Action-based state, canvas rendering, package layering, no ad hoc global stores for editor logic |
+| [`conventions.mdc`](./.cursor/rules/conventions.mdc) | `packages/**/*.ts(x)` | Functional components + hooks for new package UI, TypeScript strictness, naming and exports |
+| [`do-not-touch.mdc`](./.cursor/rules/do-not-touch.mdc) | Always | Protected core files (`Renderer.ts`, `restore.ts`, `manager.tsx`, `types.ts`) |
+| [`testing.mdc`](./.cursor/rules/testing.mdc) | Tests and Vitest config globs | Vitest-only, colocation, `packages/excalidraw` test utils, no flaky or architecture-bypassing tests |
+| [`security.mdc`](./.cursor/rules/security.mdc) | Always | Secrets/env, user-controlled data, dependencies, collab/network caution |
+| [`excalidraw-app.mdc`](./.cursor/rules/excalidraw-app.mdc) | `excalidraw-app/**` | App vs library boundaries, collab/env patterns for excalidraw.com |
+
+**Rule experiments:** See [.cursor/RULES-AB-VALIDATION.md](./.cursor/RULES-AB-VALIDATION.md) for documented A/B validation (architecture rule scope).
+
+**Cross-tool pointer:** [.cursor/CLAUDE.md](./.cursor/CLAUDE.md) summarizes the same for other assistants.
+
+## Custom Cursor commands
+
+Repeatable prompts are in [`.cursor/commands/`](./.cursor/commands/) (Markdown). Examples:
+
+| Command | Purpose |
+| --- | --- |
+| [`analyze-error.md`](./.cursor/commands/analyze-error.md) | Trace and fix build/runtime errors within project constraints |
+| [`generate-component.md`](./.cursor/commands/generate-component.md) | Scaffold a component + colocated test |
+| [`refactor.md`](./.cursor/commands/refactor.md) | Refactor selection with conventions preserved |
+| [`pre-merge-verify.md`](./.cursor/commands/pre-merge-verify.md) | Run CI-shaped checks before PR/merge |
+| [`add-locale-string.md`](./.cursor/commands/add-locale-string.md) | Add/update `en.json` keys and `t("…")` usage for UI copy |
+
+## Canonical references
+
+| Document | Use for |
+| --- | --- |
+| [ONBOARDING.md](./ONBOARDING.md) | Monorepo layout, packages, architecture, state, rendering, collab, persistence, workflows, glossary |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution entry point (links to official docs) |
+| [README.md](./README.md) | Product overview and quick links |
+| [.github/copilot-instructions.md](./.github/copilot-instructions.md) | GitHub Copilot instructions for TypeScript/React performance and style expectations |
+| [.cursor/rules/](./.cursor/rules/) | Project-specific constraints (see rules index above) |
+
+## What this repo is
+
+Yarn workspaces monorepo for **Excalidraw**: the publishable React library `@excalidraw/excalidraw` (`packages/excalidraw/`), internal packages (`packages/common`, `math`, `element`, `utils`), the **excalidraw.com** app (`excalidraw-app/`, not on npm), and examples. See ONBOARDING §2–3 for the tree and dependency graph.
+
+**Dependency rule:** lower-level packages never import higher-level ones (`common` → `math` → `element` → `excalidraw` → app).
+
+## Tech stack
+
+| Technology | Role | Where it appears in this guide |
+| --- | --- | --- |
+| **React** | UI library for the editor and app | [What this repo is](#what-this-repo-is), [Architecture](#architecture-do-not-fight-it), [Code conventions](#code-conventions-packages) |
+| **TypeScript** | Strict typing across all packages | [Code conventions](#code-conventions-packages) (`strict`; avoid `any`) |
+| **Vite** | Dev server and app bundler | [Commands](#commands-repo-root) (`yarn start`), env config in `excalidraw-app/vite.config.mts` |
+| **Yarn workspaces** | Monorepo package manager | [What this repo is](#what-this-repo-is), [Commands](#commands-repo-root) (`yarn install`) |
+| **Vitest** | Test runner (only permitted runner) | [Commands](#commands-repo-root) (`yarn test`), [Testing](#testing) |
+
+See [ONBOARDING.md](./ONBOARDING.md) for in-depth context on each technology's role in the product.
+
+## Commands (repo root)
+
+From `package.json` and ONBOARDING §4, §12:
+
+- `yarn install` — install all workspaces
+- `yarn start` — dev server for the app (HMR; default `http://localhost:3000`)
+- `yarn test` — Vitest (watch)
+- `yarn test:app -- <path>` — single file or pattern
+- `yarn test:update` — Vitest with snapshot updates, non-watch
+- `yarn test:all` — typecheck, ESLint, Prettier, Vitest non-watch (CI-shaped)
+- `yarn test:typecheck` / `yarn test:code` / `yarn test:other` — tsc, ESLint, Prettier check
+- `yarn fix` — Prettier write + ESLint fix
+- `yarn build:packages` / `yarn build:app` — package and app builds
+
+Env: copy `.env.development` → `.env.development.local`; variables are documented in ONBOARDING §4 and `excalidraw-app/vite.config.mts`.
+
+## Architecture (do not fight it)
+
+Aligned with `.cursor/rules/architecture.mdc` and ONBOARDING §7–9:
+
+- **Editor state and actions:** Changes go through the action system (`ActionManager`, actions under `packages/excalidraw/actions/`). Do not introduce parallel global state stores (e.g. Redux) for editor logic.
+- **Drawing:** Canvas 2D (rough.js, layered static/interactive canvases). Do not use React DOM, react-konva, Fabric, or Pixi for the canvas scene.
+- **State shape:** `AppState` and related types live in `packages/excalidraw/types.ts` (treat as sensitive; see Protected files).
+- **Collaboration:** Implemented in `excalidraw-app/collab/`, not inside the published library (ONBOARDING §10).
+
+ONBOARDING documents **dual Jotai stores** (`editorJotaiStore` vs `appJotaiStore`) and **class-based `App.tsx`** for hot-path rendering. For **new** React UI in packages, follow `.cursor/rules/conventions.mdc` (functional components + hooks). Do not refactor legacy class roots unless the task explicitly requires it.
+
+## Protected files
+
+**Do not modify** without explicit human approval and the bar in `.cursor/rules/do-not-touch.mdc`:
+
+- `packages/excalidraw/scene/Renderer.ts`
+- `packages/excalidraw/data/restore.ts`
+- `packages/excalidraw/actions/manager.tsx`
+- `packages/excalidraw/types.ts`
+
+Requirements if approved: full dependency understanding, full test suite, manual QA.
+
+## Code conventions (packages)
+
+From `.cursor/rules/conventions.mdc` and copilot-instructions:
+
+- **Components:** Prefer functional components and hooks for new code; props type `{ComponentName}Props`; **named exports only** (no default exports); colocate tests as `ComponentName.test.tsx`.
+- **TypeScript:** Strict; avoid `any` and `@ts-ignore`; prefer `type` for simple types; use `import type { … }`.
+- **Files:** kebab-case for non-component files; PascalCase for component filenames.
+- **Performance / style:** Prefer immutability, optional chaining, nullish coalescing; avoid unnecessary allocation where practical; use CSS modules for component styling per copilot-instructions.
+
+## Testing
+
+Follow `.cursor/rules/testing.mdc`:
+
+- **Vitest** only (`describe` / `it` / `expect`, `vi` for mocks); no new test runners or test dependencies without approval.
+- Match each package’s layout: colocated tests, or existing `tests/` / `__tests__/`.
+- For `packages/excalidraw` UI tests, use `packages/excalidraw/tests/test-utils` and existing helpers (e.g. `reseed` from `@excalidraw/common` where suites require determinism).
+- Do not bypass architecture in tests (e.g. fake state paths that contradict the real action/store model).
+- Verify with `yarn test` or targeted `yarn test:app -- <file>`; use `yarn test:all` before broad changes.
+
+Coverage thresholds are listed in ONBOARDING §12.
+
+## Dependencies
+
+No new npm packages without explicit approval. Check `packages/utils/` before adding external helpers (`.cursor/rules/architecture.mdc`).
+
+## Security
+
+Follow [`.cursor/rules/security.mdc`](./.cursor/rules/security.mdc): no committed secrets; use documented env files; sanitize user-controlled HTML; do not add dependencies without approval; treat collab and persistence boundaries carefully. Use the rule’s **How to verify** steps when touching env, markup, or network code.
+
+## Verifying agent output
+
+- After substantive edits, run the checks listed in the relevant rule **How to verify** sections (minimum: `yarn test:typecheck` and `yarn test:code`; broader: `yarn test:all`).
+- Confirm protected files are untouched unless the task explicitly approved changing them.
+- For app or collab work, smoke-test with `yarn start` when behavior is user-visible.
+
+## Common task entry points
+
+ONBOARDING §14–15 maps tasks to directories (toolbar, properties panel, element types, rendering, collab, shortcuts, i18n, history, export, etc.). Use that table when routing changes.
+
+## i18n
+
+New user-visible strings: add keys to `packages/excalidraw/locales/en.json` (source of truth), use `t("…")` in UI (ONBOARDING §14).
+
+## Further reading
+
+- [Official Excalidraw docs](https://docs.excalidraw.com)
+- `dev-docs/` — developer documentation sources
+- `packages/excalidraw/CHANGELOG.md` — library release notes
diff --git a/ONBOARDING.md b/ONBOARDING.md
new file mode 100644
index 0000000..0178714
--- /dev/null
+++ b/ONBOARDING.md
@@ -0,0 +1,751 @@
+# Excalidraw — New Engineer Onboarding Guide
+
+Welcome to the Excalidraw project! This guide will help you understand the codebase, get set up for development, and feel productive as quickly as possible.
+
+---
+
+## Table of Contents
+
+1. [What Is Excalidraw?](#1-what-is-excalidraw)
+2. [Repository at a Glance](#2-repository-at-a-glance)
+3. [Package Dependency Graph](#3-package-dependency-graph)
+4. [Getting Started](#4-getting-started)
+5. [Package Deep-Dives](#5-package-deep-dives)
+6. [The Web Application](#6-the-web-application)
+7. [Architecture — How It All Works](#7-architecture--how-it-all-works)
+8. [State Management](#8-state-management)
+9. [Rendering Pipeline](#9-rendering-pipeline)
+10. [Collaboration Architecture](#10-collaboration-architecture)
+11. [Persistence & Storage](#11-persistence--storage)
+12. [Testing](#12-testing)
+13. [Build System](#13-build-system)
+14. [Key Workflows](#14-key-workflows)
+15. [Where to Find Things](#15-where-to-find-things)
+16. [Glossary](#16-glossary)
+
+---
+
+## 1. What Is Excalidraw?
+
+Excalidraw is an open-source, browser-based whiteboard tool for sketching hand-drawn-style diagrams. It lives at [excalidraw.com](https://excalidraw.com) and is also published as an embeddable React component (`@excalidraw/excalidraw`) that other applications can integrate.
+
+**There are two distinct products in this repo:**
+
+| Product | Description | Audience |
+|---|---|---|
+| `@excalidraw/excalidraw` (npm) | Embeddable React component library | Third-party developers |
+| excalidraw.com app | Full-featured collaborative whiteboard | End users |
+
+Both live in the same monorepo and share the same underlying code.
+
+---
+
+## 2. Repository at a Glance
+
+```text
+excalidraw-master/
+├── packages/
+│   ├── excalidraw/     ← @excalidraw/excalidraw  (main React component, npm published)
+│   ├── common/         ← @excalidraw/common       (shared constants, utils, colors)
+│   ├── element/        ← @excalidraw/element       (element types, rendering, history)
+│   ├── math/           ← @excalidraw/math          (2D geometry primitives)
+│   └── utils/          ← @excalidraw/utils         (export utilities for host apps)
+│
+├── excalidraw-app/     ← excalidraw.com (private app, NOT published to npm)
+│
+├── examples/
+│   ├── with-nextjs/                ← Next.js integration example
+│   └── with-script-in-browser/     ← plain HTML / <script> tag example
+│
+├── scripts/            ← build, release, locale helper scripts
+├── dev-docs/           ← developer documentation source
+├── public/             ← static assets (icons, screenshots)
+│
+├── package.json        ← Yarn workspaces root
+├── tsconfig.json       ← TypeScript config with path aliases
+├── vitest.config.mts   ← Vitest test runner config
+└── docker-compose.yml  ← Docker setup for local backend services
+```
+
+**Toolchain summary:**
+
+| Tool | Version | Purpose |
+|---|---|---|
+| Yarn | 1.22.22 | Package manager & workspaces |
+| TypeScript | 5.9 | Type-safe development throughout |
+| Vite 5 | app build | Dev server + production bundler for the app |
+| esbuild | 0.19 | Fast bundler for the library packages |
+| Vitest | 3.x | Unit & integration test runner |
+| React | 17/18/19 | UI framework (peer dep) |
+| Jotai | 2.x | Atom-based state management |
+| rough.js | — | Hand-drawn aesthetic rendering |
+
+---
+
+## 3. Package Dependency Graph
+
+All internal packages resolve to TypeScript source during development (via path aliases in `tsconfig.json`). No pre-build step is needed for the inner development loop.
+
+```mermaid
+graph TD
+    A["@excalidraw/common<br/><small>constants, colors, utils, event bus</small>"]
+    B["@excalidraw/math<br/><small>2D geometry primitives</small>"]
+    C["@excalidraw/element<br/><small>element types, scene, history, binding</small>"]
+    D["@excalidraw/utils<br/><small>export helpers for host apps</small>"]
+    E["@excalidraw/excalidraw<br/><small>main React component (npm)</small>"]
+    F["excalidraw-app<br/><small>excalidraw.com (private)</small>"]
+    G["examples/<br/><small>integration demos</small>"]
+
+    A --> B
+    A --> C
+    B --> C
+    C --> D
+    A --> D
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    E --> G
+```
+
+**Dependency rule:** lower-level packages never import from higher-level ones. `common` knows nothing about `element`; `element` knows nothing about the React component.
+
+---
+
+## 4. Getting Started
+
+### Prerequisites
+
+- Node.js ≥ 18
+- Yarn 1.22+ (`npm install -g yarn`)
+- Git
+
+### Installation
+
+```bash
+# Clone the repo
+git clone https://github.com/excalidraw/excalidraw.git
+cd excalidraw
+
+# Install all dependencies (all workspaces at once)
+yarn install
+```
+
+### Start the development server
+
+```bash
+# Starts the excalidraw.com app with HMR at http://localhost:3000
+yarn start
+```
+
+You do **not** need to build the packages first. During development, all `@excalidraw/*` imports resolve directly to TypeScript source via path aliases.
+
+### Useful development commands
+
+```bash
+yarn start               # Start the app dev server (HMR, http://localhost:3000)
+yarn test                # Run unit tests (watch mode)
+yarn test:update         # Run all tests and update snapshots
+yarn test:typecheck      # TypeScript type checking (tsc --noEmit)
+yarn test:code           # ESLint
+yarn test:other          # Prettier formatting check
+yarn fix                 # Auto-fix formatting + lint issues
+yarn build:app           # Production build of the web app → excalidraw-app/build/
+yarn build:packages      # Build all library packages → packages/*/dist/
+```
+
+### Environment Variables
+
+The app reads environment variables from `.env` files (not committed). Copy the example:
+
+```bash
+cp .env.development .env.development.local
+```
+
+Key variables (see `excalidraw-app/vite.config.mts` for the full list):
+
+| Variable | Purpose |
+|---|---|
+| `VITE_APP_FIREBASE_CONFIG` | Firebase project config (JSON) |
+| `VITE_APP_BACKEND_V2_GET_URL` | Collaboration backend URL |
+| `VITE_APP_PORTAL_URL` | Socket.IO collab server URL |
+| `VITE_APP_AI_BACKEND` | AI feature backend URL |
+
+---
+
+## 5. Package Deep-Dives
+
+### `@excalidraw/common`
+
+The foundation everything else builds on. No monorepo dependencies.
+
+Key files:
+
+```text
+packages/common/src/
+├── constants.ts      ← All magic numbers, enums (EVENT, THEME, CURSOR_TYPE, …)
+├── colors.ts         ← Color palette definitions
+├── utils.ts          ← General utility functions
+├── bounds.ts         ← Bounding-box helpers
+├── emitter.ts        ← Typed event emitter
+├── appEventBus.ts    ← Global cross-component event bus
+└── editorInterface.ts← TypeScript interface for the editor API
+```
+
+---
+
+### `@excalidraw/math`
+
+Pure 2D geometry — no DOM, no React, no side effects. Safe to use server-side.
+
+Key files:
+
+```text
+packages/math/src/
+├── vector.ts     ← 2D vector operations
+├── point.ts      ← Point types and arithmetic
+├── segment.ts    ← Line segments (intersection, distance, …)
+├── curve.ts      ← Bézier curves
+├── ellipse.ts    ← Ellipse geometry
+├── polygon.ts    ← Polygon containment and intersection
+└── angle.ts      ← Angle normalization and conversion
+```
+
+---
+
+### `@excalidraw/element`
+
+The heart of the canvas domain logic.
+
+```text
+packages/element/src/
+├── types.ts               ← All element type definitions
+├── Scene.ts               ← SceneElementsMap, scene queries
+├── store.ts               ← CaptureUpdateAction + delta store
+├── delta.ts               ← ElementsDelta, AppStateDelta (undo/redo)
+├── mutateElement.ts       ← Safe element mutation helper
+├── newElement.ts          ← Element factory functions
+├── binding.ts             ← Arrow-to-element binding logic
+├── linearElementEditor.ts ← Point editing for lines/arrows
+├── textElement.ts         ← Text wrapping, measurement
+├── renderElement.ts       ← Per-element draw calls (rough.js)
+├── bounds.ts              ← Element bounding boxes
+├── selection.ts           ← Selection hit-testing
+├── frame.ts               ← Frame element logic
+├── groups.ts              ← Group element logic
+├── flowchart.ts           ← Flowchart auto-layout
+└── elbowArrow.ts          ← Elbow (orthogonal) arrow routing
+```
+
+**Every element type** extends `_ExcalidrawElementBase`:
+
+```typescript
+interface _ExcalidrawElementBase {
+  id: string;               // nanoid
+  x: number; y: number;    // scene coordinates
+  width: number; height: number;
+  angle: number;            // radians
+  strokeColor: string;
+  backgroundColor: string;
+  fillStyle: FillStyle;
+  strokeStyle: StrokeStyle;
+  roughness: number;        // 0–2 (rough.js roughness)
+  opacity: number;          // 0–100
+  seed: number;             // controls rough.js shape randomness
+  version: number;          // incremented on every mutation
+  versionNonce: number;     // random — used for collab reconciliation
+  index: FractionalIndex;   // stable ordering in multiplayer
+  isDeleted: boolean;
+  groupIds: string[];
+  frameId: string | null;
+  boundElements: BoundElement[] | null;
+  locked: boolean;
+  link: string | null;
+  customData?: Record<string, unknown>;
+}
+```
+
+**Concrete element types:** `rectangle`, `ellipse`, `diamond`, `line`, `arrow`, `freedraw`, `text`, `image`, `frame`, `magicframe`, `embeddable`, `laser`.
+
+---
+
+### `@excalidraw/excalidraw`
+
+The published React component. Entry point: `packages/excalidraw/index.tsx`.
+
+Key exports:
+
+| Category | Exports |
+|---|---|
+| Components | `<Excalidraw>`, `<MainMenu>`, `<WelcomeScreen>`, `<Footer>`, `<Sidebar>`, `<TTDDialog>` |
+| Hooks | `useExcalidrawAPI()`, `useExcalidrawStateValue()`, `useOnExcalidrawStateChange()` |
+| Export utils | `exportToCanvas`, `exportToBlob`, `exportToSvg`, `exportToClipboard` |
+| Serialization | `serializeAsJSON`, `loadFromBlob`, `restoreAppState`, `restoreElements` |
+| Element helpers | `mutateElement`, `newElementWith`, `convertToExcalidrawElements` |
+| Constants | `FONT_FAMILY`, `THEME`, `MIME_TYPES`, `ROUNDNESS` |
+
+**Minimal integration example:**
+
+```tsx
+import { Excalidraw } from "@excalidraw/excalidraw";
+
+export default function App() {
+  return (
+    <div style={{ height: "100vh" }}>
+      <Excalidraw />
+    </div>
+  );
+}
+```
+
+---
+
+### `@excalidraw/utils`
+
+Utility functions intended for host application use (not for internal library code).
+
+```text
+packages/utils/src/
+├── export.ts        ← exportToCanvas, exportToBlob, exportToSvg
+├── withinBounds.ts  ← Hit-testing helpers
+├── bbox.ts          ← Bounding box calculations
+└── shape.ts         ← Shape geometry helpers
+```
+
+---
+
+## 6. The Web Application
+
+`excalidraw-app/` is the full excalidraw.com application. It is **private** (not published to npm) and uses `@excalidraw/excalidraw` as a dependency.
+
+### Application Layers
+
+```mermaid
+graph TD
+    subgraph Browser
+        A["ExcalidrawApp (App.tsx)"]
+        B["&lt;Excalidraw&gt; component"]
+        C["Collaboration layer (Collab.tsx)"]
+        D["Persistence layer (LocalData.ts)"]
+        E["App Jotai store (app-jotai.ts)"]
+    end
+
+    subgraph Firebase
+        F["Firestore (room state)"]
+        G["Firebase Storage (images)"]
+    end
+
+    subgraph Socket.IO Server
+        H["Collab server (WebSocket)"]
+    end
+
+    A --> B
+    A --> C
+    A --> D
+    A --> E
+    C <--> H
+    C <--> F
+    D <--> F
+    D --> G
+```
+
+### Key App Files
+
+| File | Responsibility |
+|---|---|
+| `App.tsx` | Root component; wraps `<Excalidraw>` with providers |
+| `index.tsx` | React DOM root mount, service worker registration |
+| `collab/Collab.tsx` | Real-time collaboration (Socket.IO + Firebase) |
+| `collab/Portal.tsx` | WebSocket abstraction layer |
+| `data/LocalData.ts` | Debounced local save (IndexedDB + localStorage) |
+| `data/firebase.ts` | Firebase Firestore/Storage read/write |
+| `data/tabSync.ts` | Cross-tab state synchronization |
+| `components/AI.tsx` | AI feature (text-to-diagram) UI |
+| `app-jotai.ts` | App-level Jotai atom store |
+| `app_constants.ts` | App-specific constants, storage keys |
+
+---
+
+## 7. Architecture — How It All Works
+
+### The Core Event Loop
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Canvas (DOM)
+    participant App.tsx (class)
+    participant ActionManager
+    participant Store (delta)
+    participant Renderer
+
+    User->>Canvas (DOM): pointer / keyboard event
+    Canvas (DOM)->>App.tsx (class): onPointerDown / onKeyDown
+    App.tsx (class)->>ActionManager: executeAction(action, value)
+    ActionManager->>Store (delta): captureIncrement(ElementsDelta)
+    Store (delta)->>App.tsx (class): triggerUpdate()
+    App.tsx (class)->>Renderer: scheduleStaticSceneRender()
+    Renderer->>Canvas (DOM): drawImage() via rough.js
+```
+
+### The Action System
+
+Every editor operation is an `Action` object:
+
+```typescript
+interface Action {
+  name: ActionName;
+  perform(
+    elements: readonly ExcalidrawElement[],
+    appState: AppState,
+    value: unknown,
+    app: AppClassProperties,
+  ): ActionResult;
+  PanelComponent?: React.FC;   // Properties panel UI for this action
+  trackEvent?: EventDescriptor;
+}
+```
+
+Actions are registered in `packages/excalidraw/actions/` and dispatched through `ActionManager`. This cleanly separates UI from logic and makes unit testing straightforward.
+
+---
+
+## 8. State Management
+
+### Dual Jotai Store Architecture
+
+The project uses two completely isolated Jotai stores to support multiple `<Excalidraw>` instances on the same page:
+
+```mermaid
+graph LR
+    subgraph Editor Instance 1
+        A1["editorJotaiStore<br/>(jotai-scope isolated)"]
+    end
+    subgraph Editor Instance 2
+        A2["editorJotaiStore<br/>(jotai-scope isolated)"]
+    end
+    subgraph App Level
+        B["appJotaiStore<br/>(excalidraw-app/app-jotai.ts)"]
+    end
+
+    A1 -- "isolated via jotai-scope" --- A2
+    B -- "wraps editor instances" --- A1
+    B -- "wraps editor instances" --- A2
+```
+
+| Store | Location | Contains |
+|---|---|---|
+| `editorJotaiStore` | `packages/excalidraw/editor-jotai.ts` | Editor atoms (tool mode, UI state, font loading, …) |
+| `appJotaiStore` | `excalidraw-app/app-jotai.ts` | App atoms (collab state, share dialog, offline status) |
+
+**React class component state (`App.tsx`)** is used for high-frequency rendering concerns (element positions, current app state) because class components avoid hook overhead in hot paths.
+
+### Undo / Redo: Delta-Based Store
+
+Changes are captured as immutable `StoreDelta` objects containing:
+
+- `ElementsDelta` — what changed at the element level
+- `AppStateDelta` — what changed in app state (selected elements, viewport, etc.)
+
+```mermaid
+graph LR
+    A["User action"] --> B["mutateElement()"]
+    B --> C["Store.captureIncrement()"]
+    C --> D["StoreDelta<br/>(ElementsDelta + AppStateDelta)"]
+    D --> E["History stack"]
+    E -- "Ctrl+Z" --> F["applyDelta() → restore"]
+```
+
+`CaptureUpdateAction` enum controls when deltas are captured:
+
+| Value | When to use |
+|---|---|
+| `IMMEDIATELY` | Discrete actions the user should be able to undo individually |
+| `EVENTUALLY` | Continuous drags (batched into one undo step) |
+| `NEVER` | View-only changes (zoom, pan) — not undoable |
+
+---
+
+## 9. Rendering Pipeline
+
+### Dual-Canvas Architecture
+
+Two HTML5 `<canvas>` elements are layered on top of each other:
+
+```text
+┌──────────────────────────────────────────┐
+│  Interactive Canvas  (top layer)          │
+│  - selection handles                      │
+│  - transform handles                      │
+│  - bound text cursors                     │
+│  - snap lines                             │
+│  - collaborator cursors                   │
+│  - laser pointer trails                   │
+└──────────────────────────────────────────┘
+┌──────────────────────────────────────────┐
+│  Static Canvas  (bottom layer)            │
+│  - all non-interactive elements           │
+│  - throttled via throttleRAF              │
+└──────────────────────────────────────────┘
+```
+
+| Canvas | File | Render trigger |
+|---|---|---|
+| Static | `packages/excalidraw/renderer/staticScene.ts` | Throttled via `throttleRAF` on element or zoom change |
+| Interactive | `packages/excalidraw/renderer/interactiveScene.ts` | Every pointer event / state change |
+
+### How an Element Gets Drawn
+
+```mermaid
+graph LR
+    A["ExcalidrawElement"] --> B["renderElement()<br/>(element/src/renderElement.ts)"]
+    B --> C{"Element type?"}
+    C -- "rectangle/ellipse/…" --> D["rough.js generator<br/>(cached by seed)"]
+    C -- "freedraw" --> E["perfect-freehand<br/>(stroke path)"]
+    C -- "text" --> F["ctx.fillText()"]
+    C -- "image" --> G["ctx.drawImage()"]
+    D --> H["CanvasRenderingContext2D"]
+    E --> H
+    F --> H
+    G --> H
+```
+
+rough.js shapes are **cached by element `seed`** — the same seed always produces the same hand-drawn shape, enabling consistent rendering across collaborators.
+
+---
+
+## 10. Collaboration Architecture
+
+Collaboration is entirely in `excalidraw-app/` and uses two real-time backends:
+
+```mermaid
+sequenceDiagram
+    participant Alice (Browser)
+    participant Socket.IO Server
+    participant Bob (Browser)
+    participant Firebase
+
+    Alice (Browser)->>Socket.IO Server: broadcastElements(delta)
+    Socket.IO Server->>Bob (Browser): receiveElements(delta)
+    Bob (Browser)->>Bob (Browser): reconcileElements(local, remote)
+
+    Alice (Browser)->>Firebase: saveFilesToFirebase(images)
+    Bob (Browser)->>Firebase: getFiles(ids)
+
+    Alice (Browser)-->>Socket.IO Server: broadcastCursorMove(pointer)
+    Socket.IO Server-->>Bob (Browser): onPointerUpdate(pointer)
+```
+
+**Key principle:** The library (`@excalidraw/excalidraw`) does **not** contain any collaboration code. It only exposes:
+- `isCollaborating` prop — signals the UI to show collaboration indicators
+- `reconcileElements()` export — merges remote elements with local state
+
+The app layer in `excalidraw-app/collab/` owns all Socket.IO connections and Firebase calls.
+
+### Element Reconciliation
+
+When remote elements arrive, `reconcileElements()` merges them:
+
+1. Remote element `version` > local `version` → use remote
+2. Same `version` but different `versionNonce` → use element with higher `versionNonce` (deterministic tiebreak)
+3. Local element has no remote counterpart → keep local
+4. Remote element has no local counterpart → add it
+
+---
+
+## 11. Persistence & Storage
+
+```mermaid
+graph TD
+    subgraph "excalidraw-app"
+        A["LocalData.ts<br/>(debounced writes)"]
+        B["IndexedDB<br/>(idb-keyval)<br/>— elements, files"]
+        C["localStorage<br/>— app state, username"]
+        D["tabSync.ts<br/>— cross-tab sync"]
+        E["firebase.ts<br/>— cloud storage"]
+    end
+
+    A --> B
+    A --> C
+    D --> C
+    A --> E
+```
+
+| Storage | What's stored | Library |
+|---|---|---|
+| IndexedDB | Canvas elements, binary files (images) | `idb-keyval` |
+| `localStorage` | App state, user preferences, scene version counter | Native |
+| Firebase Firestore | Shared room state for collaboration | Firebase 11 |
+| Firebase Storage | Shared image files for collaboration | Firebase 11 |
+
+**Write strategy:** `LocalData.ts` uses debounced writes — rapid element mutations don't thrash the storage. A save happens at most once per 300 ms window.
+
+---
+
+## 12. Testing
+
+### Test Locations
+
+| Location | What's tested |
+|---|---|
+| `packages/excalidraw/tests/` | Main component tests (~30 files: App, actions, clipboard, drag, export, history, …) |
+| `packages/element/src/__tests__/` | Element domain logic unit tests |
+| `packages/math/tests/` | Geometry unit tests |
+| `packages/common/tests/` | Utility unit tests |
+| `excalidraw-app/tests/` | App integration tests |
+
+### Test Setup
+
+| Mock | What it does |
+|---|---|
+| `vitest-canvas-mock` | Mocks `<canvas>` 2D rendering context |
+| `fake-indexeddb` | In-memory IndexedDB for tests |
+| `throttleRAF` | Replaced with synchronous stub so renders happen immediately |
+| `window.FontFace` / `document.fonts` | Mocked so font loading tests are deterministic |
+
+### Running Tests
+
+```bash
+yarn test                  # Watch mode
+yarn test:update           # Run all tests, update snapshots
+yarn test:typecheck        # TypeScript type check
+yarn test:code             # ESLint
+yarn test:other            # Prettier
+
+# Run a specific test file
+yarn test packages/excalidraw/tests/history.test.tsx
+```
+
+### Coverage Thresholds
+
+| Metric | Minimum |
+|---|---|
+| Lines | 60% |
+| Statements | 60% |
+| Branches | 70% |
+| Functions | 63% |
+
+---
+
+## 13. Build System
+
+### Library Packages (esbuild)
+
+```mermaid
+graph LR
+    A["TypeScript source"] --> B["esbuild<br/>(buildBase.js / buildPackage.js)"]
+    B --> C["dist/dev/index.js<br/>(development build)"]
+    B --> D["dist/prod/index.js<br/>(production build)"]
+    A --> E["tsc --emitDeclarationOnly"]
+    E --> F["dist/types/*.d.ts"]
+```
+
+Build order (enforced by `yarn build:packages`): `common` → `math` → `element` → `excalidraw`
+
+### App (Vite + Rollup)
+
+```mermaid
+graph LR
+    A["excalidraw-app/"] --> B["Vite 5 / Rollup"]
+    B --> C["excalidraw-app/build/"]
+    B --> D["Manual chunks:<br/>- locale files<br/>- mermaid chunk<br/>- codemirror chunk"]
+    B --> E["Service Worker<br/>(Workbox via vite-plugin-pwa)"]
+```
+
+**PWA features:** The app ships with a Workbox service worker that precaches the app shell, lazy-loads locale files, and caches Google Fonts. This enables offline usage.
+
+---
+
+## 14. Key Workflows
+
+### Adding a New Element Type
+
+1. **Define the type** in `packages/element/src/types.ts` — extend `_ExcalidrawElementBase`
+2. **Add a factory function** in `packages/element/src/newElement.ts`
+3. **Add rendering logic** in `packages/element/src/renderElement.ts`
+4. **Add hit-testing** in `packages/element/src/bounds.ts`
+5. **Add selection logic** in `packages/element/src/selection.ts`
+6. **Register the tool** in the toolbar (`packages/excalidraw/components/`)
+7. **Add tests** in `packages/excalidraw/tests/`
+
+### Adding a New Action
+
+1. Create a file in `packages/excalidraw/actions/`
+2. Implement `Action` interface with `name` and `perform()`
+3. Optionally add a `PanelComponent` for the properties panel
+4. Register in `packages/excalidraw/actions/index.ts`
+5. Add `ActionName` to the union type in `packages/excalidraw/actions/types.ts`
+
+### Adding a New Translation String
+
+1. Add the key/value to `packages/excalidraw/locales/en.json` (English is the source of truth)
+2. Use `t("my.new.key")` in the component
+3. Other locales are updated separately by translators
+
+### Making a Library Release
+
+```bash
+yarn build:packages         # Build all packages
+# Update versions in packages/*/package.json
+# Update CHANGELOG.md
+yarn publish:packages       # Publishes to npm
+```
+
+---
+
+## 15. Where to Find Things
+
+| I want to… | Look here |
+|---|---|
+| Change a toolbar button | `packages/excalidraw/components/toolBar/` |
+| Change the properties panel | `packages/excalidraw/components/Stats.tsx` and `packages/excalidraw/actions/` |
+| Change how an element renders | `packages/element/src/renderElement.ts` |
+| Add/change an element type | `packages/element/src/types.ts` + `newElement.ts` |
+| Change collaboration behavior | `excalidraw-app/collab/Collab.tsx` |
+| Change local save behavior | `excalidraw-app/data/LocalData.ts` |
+| Change keyboard shortcuts | `packages/excalidraw/actions/` (each action defines its own shortcut) |
+| Change colors/theming | `packages/common/src/colors.ts` + `packages/excalidraw/css/` |
+| Add a new localization string | `packages/excalidraw/locales/en.json` |
+| Change the undo/redo behavior | `packages/element/src/store.ts` + `packages/excalidraw/history.ts` |
+| Change export (PNG/SVG/JSON) | `packages/utils/src/export.ts` |
+| Change the welcome screen | `excalidraw-app/components/AppWelcomeScreen.tsx` |
+| Change AI features | `excalidraw-app/components/AI.tsx` |
+
+---
+
+## 16. Glossary
+
+| Term | Meaning |
+|---|---|
+| **Scene** | The entire set of elements on the canvas at a given time |
+| **AppState** | The editor's non-element state: selected elements, current tool, viewport, zoom, theme, etc. |
+| **Element** | A single drawable object (rectangle, arrow, text, image, …) |
+| **Seed** | A random number stored on each element that controls rough.js's hand-drawn randomness — same seed = same shape |
+| **FractionalIndex** | A string-based ordering value that allows inserting between two existing elements without renumbering |
+| **Delta** | An immutable record of what changed between two states (used for undo/redo) |
+| **CaptureUpdateAction** | Enum that controls whether/when a state change is recorded in the undo history |
+| **Binding** | The linkage between an arrow element and the shapes at its endpoints |
+| **Frame** | A named container element that logically groups other elements |
+| **rough.js** | The third-party library that gives Excalidraw its hand-drawn aesthetic |
+| **perfect-freehand** | The library used to render pressure-sensitive free-draw strokes |
+| **Reconciliation** | The process of merging remote (collaborator) element changes with local state |
+| **Portal** | The WebSocket abstraction layer in `excalidraw-app/collab/Portal.tsx` |
+| **editorJotaiStore** | The isolated Jotai atom store belonging to a single `<Excalidraw>` instance |
+| **appJotaiStore** | The app-level Jotai atom store for excalidraw.com-specific state |
+| **throttleRAF** | A utility that throttles a function to fire at most once per animation frame |
+| **PWA** | Progressive Web App — the app ships a service worker for offline support and installability |
+
+---
+
+## Further Reading
+
+- [Official Documentation](https://docs.excalidraw.com) — API reference, installation guide, contributing guide
+- [`packages/excalidraw/CHANGELOG.md`](packages/excalidraw/CHANGELOG.md) — library release history
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution guidelines
+- [`dev-docs/`](dev-docs/) — developer documentation sources
+- [excalidraw.com](https://excalidraw.com) — the live application
+
+---
+
+*Happy drawing! If something in this document is out of date, please update it — the best onboarding doc is one the team keeps current.*