Added rules and commands, A/B rule tesing results

.cursor/commands/add-locale-string.md

@@ -0,0 +1,34 @@
+# Add locale string (i18n)
+
+Use for **user-visible** text in the **library** (`packages/excalidraw`), not hardcoded English.
+
+## 1. Pick a key
+
+- Prefer existing namespaces: **`labels.*`**, **`toolBar.*`**, **`hints.*`**, etc. — follow keys near similar UI in `packages/excalidraw/locales/` (e.g. `en.json`).
+
+## 2. Add English source
+
+- Edit the appropriate locale JSON under **`packages/excalidraw/locales/`** (start from **`en.json`** or the pattern used for your language).
+- Keep placeholders consistent with existing messages (`{variable}` style if the codebase uses interpolation — match siblings).
+
+## 3. Use in UI
+
+- Import **`useI18n`** from `../i18n` (or the established relative path from the component).
+- Call **`const { t } = useI18n()`** and use **`t("your.key")`** for labels, titles, buttons, tooltips.
+
+## 4. Actions
+
+- Action **`label`** (and **`keywords`**) should use **translation keys**, not raw English strings, when exposed in menus/command palette.
+
+## 5. Crowdin
+
+- Project translations are managed via **Crowdin** (per project docs); adding keys in English is the usual first step; translators pick up new keys there.
+
+## Do not
+
+- Hardcode user-facing strings in **`packages/excalidraw/components/`** for production UI.
+- For **`excalidraw-app/`**-only UI, follow existing app patterns (some strings may be app-specific — mirror nearby files).
+
+## See also
+
+`dev-docs/docs/a-docs/08-adding-features.md`, `.cursor/rules/excalidraw-ui.mdc`.

.cursor/commands/app-only-feature.md

@@ -0,0 +1,32 @@
+# App-only feature (excalidraw.com)
+
+Use when the change targets **`excalidraw-app/`** only and must **not** bloat **`@excalidraw/excalidraw`**.
+
+## Boundaries
+
+- **App shell:** routing, welcome, share dialogs, Plus hooks, Firebase, collab wiring — **`excalidraw-app/`**.
+- **Reusable editor:** canvas, actions, element model — **`packages/excalidraw/`** (published npm package).
+
+Prefer **props and callbacks** into `<Excalidraw />` rather than forking core editor logic into the app.
+
+## State
+
+- **App-level Jotai:** **`excalidraw-app/app-jotai.ts`** — not raw `jotai`.
+- **Editor state:** still **`AppState` + elements** inside the package; app listens via **`onChange`** / APIs as today.
+
+## Config & services
+
+- **Env:** `VITE_APP_*` in `.env.development` / `.env.production`.
+- **Firebase / WebSocket URLs:** see app `data/` and `collab/`; reuse **`packages/excalidraw/data`** for encode/decode and reconcile — do not duplicate JSON formats.
+
+## UI placement
+
+- Components in **`excalidraw-app/components/`** with colocated **`.scss`** when needed (match **`AppSidebar.scss`** patterns).
+
+## Finish
+
+`yarn test:typecheck`, tests under **`excalidraw-app/tests/`** if applicable, `yarn fix`.
+
+## See also
+
+`dev-docs/docs/a-docs/03-codebase-navigation.md` (app-level data), `.cursor/rules/excalidraw-app-integration.mdc`, `excalidraw-ui-app.mdc`.

.cursor/commands/debug-collab.md

@@ -0,0 +1,30 @@
+# Debug collaboration
+
+Use when **live collaboration**, **shared rooms**, or **remote cursors** misbehave (drift, lost updates, duplicates, stale scenes).
+
+## Mental model
+
+- **Socket.io** (`excalidraw-app/collab/Portal.tsx`) carries realtime updates.
+- **Firebase** (`excalidraw-app/data/firebase.ts`) persists encrypted scene + files for rooms.
+- **Merge** uses **`reconcileElements`** in **`packages/excalidraw/data/reconcile.ts`** (version-based; ties / tombstones matter).
+- **Encryption key** is in the URL **hash** — not sent to HTTP servers; do not log full share URLs in production debug.
+
+## Investigation order
+
+1. **Repro** — two browsers, same room, minimal steps (draw, delete, reorder, image paste).
+2. **Local vs remote** — does the bug appear offline? If only online, suspect **reconcile**, **socket**, or **Firebase** timing.
+3. **`Collab.tsx`** — `startCollaboration`, `syncElements`, `handleRemoteSceneUpdate`, save queues.
+4. **`reconcile.ts`** — same element id, **version** / **isDeleted** / ordering after merge.
+5. **Element mutations** — direct mutation or missing **version** bumps break reconciliation and undo.
+6. **Images** — `FileManager`, Firebase file prefix, lazy fetch paths for peers’ assets.
+
+## Files to read first
+
+- `excalidraw-app/collab/Collab.tsx`
+- `excalidraw-app/collab/Portal.tsx`
+- `packages/excalidraw/data/reconcile.ts`
+- `packages/excalidraw/data/encryption.ts`
+
+## See also
+
+`dev-docs/docs/a-docs/04-key-business-flows.md` (collaboration section), `.cursor/rules/excalidraw-data-collab.mdc`, `excalidraw-app-integration.mdc`.

.cursor/commands/element-schema-change.md

@@ -0,0 +1,50 @@
+# Element schema change
+
+Use when adding or changing fields on **drawing elements** (shapes, text, arrows, frames, images, etc.).
+
+## 1. Types
+
+- **`packages/element/src/types.ts`** — extend the correct element interface or shared base type.
+
+## 2. Creation defaults
+
+- **`packages/element/src/newElement.ts`** (and any specialized factories) — set defaults for **new** elements.
+
+## 3. Load / paste / migrate
+
+- **`packages/excalidraw/data/restore.ts`** — defaults and migrations for **old** JSON, clipboard, and shared links so older files still open.
+
+## 4. Mutation
+
+- Use **`mutateElement`** (or established helpers). **Never** mutate element objects in place without proper **version** / **versionNonce** behavior.
+
+## 5. Ordering / scene
+
+- If z-order or structure changes: **`packages/element/src/Scene.ts`** and **fractional `index`** rules — prefer Scene APIs over hand-rolled indices.
+
+## 6. Rendering & export
+
+- Canvas: **`packages/excalidraw/renderer/staticScene.ts`**
+- SVG: **`packages/excalidraw/renderer/staticSvgScene.ts`**
+- PNG / export pipeline: **`packages/excalidraw/scene/export.ts`** as needed
+
+## 7. Serialization
+
+- **`packages/excalidraw/data/json.ts`** (and related types) if the field must round-trip in `.excalidraw` JSON.
+
+## 8. Collaboration
+
+- **`packages/excalidraw/data/reconcile.ts`** — merging uses **version**; deleted elements stay as tombstones for a reason.
+- Test **two clients** editing the same scene when the change affects concurrent updates.
+
+## 9. Tests
+
+- Add or extend tests under **`packages/element/tests/`** and **`packages/excalidraw/tests/`** as appropriate.
+
+## Finish
+
+`yarn test:typecheck`, `yarn test:update`, `yarn fix`.
+
+## See also
+
+`restore-migration.md`, `.cursor/rules/excalidraw-element-model.mdc`, `excalidraw-data-collab.mdc`.

.cursor/commands/new-action.md

@@ -0,0 +1,30 @@
+# New editor action
+
+Add a **user-triggered** state change via the action system (`ActionManager`).
+
+## Steps
+
+1. **Create** `packages/excalidraw/actions/actionYourFeature.ts` or `actionYourFeature.tsx`.
+2. **Import** `register` from `./register`, `CaptureUpdateAction` from `@excalidraw/element`, and types with `import type` from `./types` and `../types` as needed.
+3. **Implement** `export const actionYourFeature = register({ name, label, perform, captureUpdate, … })`:
+   - `perform(elements, appState, formData, app)` → `{ elements?, appState?, files?, captureUpdate }` or `false` to no-op.
+   - Choose **`captureUpdate`** to match the closest existing action (`IMMEDIATELY`, `EVENTUALLY`, `NEVER`, etc.).
+4. **Export** from `packages/excalidraw/actions/index.ts` (required for registration).
+5. **Shortcut** (optional): `keyTest` on the action and/or `packages/excalidraw/actions/shortcuts.ts`.
+6. **UI** (optional): toolbar / menu / command palette — follow patterns in `Actions.tsx`, `MainMenu.tsx`, or command palette registrations.
+7. **Label / i18n:** use a translation key for `label` (e.g. `"labels.myFeature"`) and add the string under `packages/excalidraw/locales/` (English + structure for Crowdin).
+8. **Tests:** `packages/excalidraw/actions/actionYourFeature.test.tsx` with `render` / `unmountComponent` from `../tests/test-utils`, `API`, `Keyboard` where relevant.
+
+## Conventions
+
+- Do not import from `packages/excalidraw/index.tsx` inside the package; use concrete module paths.
+- Prefer keeping pure state transforms in **`perform`**; use `App.tsx` only when pointer/tool lifecycle requires it.
+- Mirror **`actionToggleStats.tsx`**, **`actionDeleteSelected`**, or a similar action for structure.
+
+## Finish
+
+Run `yarn test:typecheck`, `yarn test:update` if snapshots change, `yarn fix`.
+
+## See also
+
+`update-state-flow.md`, `dev-docs/docs/a-docs/08-adding-features.md`, `.cursor/rules/excalidraw-actions-state.mdc`.

.cursor/commands/new-vitest-excalidraw.md

@@ -0,0 +1,38 @@
+# New Vitest test (Excalidraw editor)
+
+Add or extend tests using the project’s **Vitest + jsdom + Testing Library** setup.
+
+## Setup (global)
+
+- **`setupTests.ts`** (repo root) — canvas, IndexedDB, fonts, RAF mocks apply automatically.
+- **`vitest.config.mts`** — path aliases **`@excalidraw/*`** must match imports in tests.
+
+## Component / integration tests
+
+1. Import **`render`**, **`unmountComponent`** from **`packages/excalidraw/tests/test-utils`** (adjust relative path from test file).
+2. **`beforeEach`:** `await render(<Excalidraw />)` (or the minimal wrapper used in sibling tests).
+3. **`afterEach`:** `unmountComponent()` when using that helper.
+4. Use **`API`** (`../tests/helpers/api`), **`Keyboard`**, **`Mouse`** from **`../tests/helpers/ui`** when simulating editor actions — prefer existing helpers over brittle DOM queries.
+
+## Pure logic tests
+
+- **`packages/element/tests/`**, **`packages/math/tests/`**, **`packages/common/`** colocated `*.test.ts` — no React unless needed.
+
+## Running
+
+```bash
+yarn test:app -- path/to/file.test.tsx
+yarn test:app -- -t "partial test name"
+```
+
+## Snapshots
+
+- If output is correct, run **`yarn test:update`** and **review diffs** before committing.
+
+## Finish
+
+`yarn test:typecheck`, `yarn fix`.
+
+## See also
+
+`dev-docs/docs/a-docs/06-testing-guide.md`, `.cursor/rules/excalidraw-testing.mdc`.

.cursor/commands/pre-pr-check.md

@@ -0,0 +1,33 @@
+# Pre-PR check
+
+Run this before opening a PR or pushing a feature branch.
+
+## Commands (repo root)
+
+```bash
+yarn test:update
+yarn test:typecheck
+yarn fix
+```
+
+1. **`yarn test:update`** — runs Vitest and updates snapshots where intended. **Review every snapshot diff**; do not commit accidental UI regressions.
+2. **`yarn test:typecheck`** — full TypeScript check for the monorepo configuration.
+3. **`yarn fix`** — Prettier + ESLint auto-fix (`fix:other` + `fix:code`).
+
+## CI parity (optional but thorough)
+
+```bash
+yarn test:all
+```
+
+Equivalent to typecheck + eslint + prettier check + tests (non-watch).
+
+## Manual sanity
+
+- [ ] New user-facing strings go through **`locales/`** (library UI).
+- [ ] Element changes: **`mutateElement`** + version / collab implications considered.
+- [ ] New deps: bundle / **size-limit** CI (`.github/workflows/size-limit.yml`) if the change affects published packages.
+
+## If something fails
+
+Fix in order: **types** → **lint** → **tests** → **snapshots** (only if output is correct).

.cursor/commands/rendering-change.md

@@ -0,0 +1,39 @@
+# Rendering / canvas change
+
+Use when changing **how elements are drawn** or how **canvas layers** behave.
+
+## Architecture
+
+- **Static canvas** — committed elements, **Rough.js**, should **not** redraw every pointer move.
+- **Interactive canvas** — selection, handles, snaps, remote cursors.
+- **New element canvas** — in-progress shape before commit.
+
+Orchestration lives under **`packages/excalidraw/components/canvases/`**; core drawing in **`packages/excalidraw/renderer/`**.
+
+## Files
+
+| Concern | Typical files |
+|--------|----------------|
+| Static bitmap | `renderer/staticScene.ts` |
+| Selection overlay | `renderer/interactiveScene.ts` |
+| SVG export | `renderer/staticSvgScene.ts` |
+| Export to PNG / clipboard | `scene/export.ts` |
+
+## Performance
+
+- Preserve **caching** of Rough drawables (tied to element version — do not recreate all drawables on every frame).
+- Avoid pushing static-layer updates from **`pointerMove`** unless necessary.
+- Stress-test with **many elements** (hundreds+) after changes.
+
+## Consistency
+
+- If canvas appearance changes, check **SVG export** matches for the same scene where applicable.
+
+## Tests / checks
+
+- Relevant renderer tests or visual snapshots; `yarn test:app` for affected areas.
+- `yarn test:typecheck`
+
+## See also
+
+`dev-docs/docs/a-docs/01-architecture-overview.md` (rendering), `.cursor/rules/excalidraw-rendering.mdc`, `excalidraw-canvas-components.mdc`.

.cursor/commands/restore-migration.md

@@ -0,0 +1,30 @@
+# Restore & migration (`restore.ts`)
+
+Use when **saved files**, **clipboard**, or **shared links** must keep working after changing element or app state shape.
+
+## Primary file
+
+- **`packages/excalidraw/data/restore.ts`** — `restoreElements`, `restoreAppState`, `restoreLibraryItems`, version bumps where required.
+
+## Goals
+
+1. **Old JSON** still parses — add defaults for new fields; rename fields with explicit migration steps if needed.
+2. **Invalid / partial data** — normalize defensively; match style of existing restore branches.
+3. **Collaboration** — after restore, **element versions** must remain consistent with reconciliation expectations (see **`bumpElementVersions`** and related helpers in this file / callers).
+
+## Related
+
+- **`packages/element/src/types.ts`** — source of truth for element shape.
+- **`packages/excalidraw/data/json.ts`** — serialization / types for file format.
+- **Tests** — add fixtures or extend tests under **`packages/excalidraw/tests/`** or **`packages/element/tests/`** for old-format samples when possible.
+
+## Checklist
+
+- [ ] New field has a default in **`restore.ts`**
+- [ ] No regression loading a **minimal** and a **real** saved `.excalidraw` file
+- [ ] Clipboard paste from an **old** build still works if users mix versions
+- [ ] `yarn test:typecheck` and targeted tests pass
+
+## See also
+
+`element-schema-change.md`, `dev-docs/docs/a-docs/05-important-components.md` (restore / migration), `.cursor/rules/excalidraw-data-collab.mdc`.

.cursor/commands/size-budget.md

@@ -0,0 +1,30 @@
+# Size budget & bundle impact
+
+Use before adding **heavy dependencies** or **large imports** to **`packages/excalidraw`** or the app entry.
+
+## Why
+
+- The published editor is sensitive to bundle size; CI may enforce limits.
+- **`@size-limit/preset-big-lib`** is a dev dependency of **`packages/excalidraw`**; workflow automation lives under **`.github/workflows/size-limit.yml`**.
+
+## What to do
+
+1. **Prefer** existing utilities in **`@excalidraw/common`**, tree-shakeable imports, and **dynamic import** for rare code paths when the codebase already does so for similar features.
+2. **Avoid** importing whole libraries when only a small API is needed.
+3. After significant dependency adds, run a **production build** locally and compare size if unsure:
+
+   ```bash
+   yarn build:packages
+   yarn build
+   ```
+
+4. Open a PR early if the change is large — CI **size-limit** will report regressions.
+
+## Library vs app
+
+- **`packages/excalidraw`** — stricter; affects all embedders.
+- **`excalidraw-app`** — still matters for first load; be deliberate with new chunks.
+
+## See also
+
+`packages/excalidraw/package.json` (size-limit scripts if present), `.github/workflows/size-limit.yml`.