diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b7e0f88 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# AGENTS.md + +## Purpose + +Guidance for AI coding agents working in this repository. Follow these rules unless a human explicitly overrides them. + +## Architecture Constraints + +- Use custom state management via `actionManager`; do not introduce Redux, Zustand, or MobX. +- Perform state updates through `actionManager.dispatch()` only. +- Keep core app state aligned with `AppState` in `src/types.ts`. +- Use Canvas 2D for drawing/rendering flows; do not replace with React DOM drawing. +- Preserve render flow: `Scene -> renderScene() -> canvas context`. +- Do not introduce `react-konva`, `fabric.js`, or `pixi.js`. +- Do not add new npm dependencies without explicit approval. +- Check existing utilities (for example `src/utils/`) before adding external helpers. + +## Code Conventions + +- Use functional components with hooks only; avoid class components. +- Prefer named exports over default exports. +- Keep TypeScript strict; avoid `any` and `@ts-ignore`. +- Prefer `type` over `interface` for simple types. +- Use `import type { X } from "..."` for type-only imports. +- Use `kebab-case` for utility file names and `PascalCase` for component files. +- Keep tests colocated where practical (for example `ComponentName.test.tsx`). + +## Protected Files + +Do not modify the following files without explicit human approval: + +- `src/core/renderer.ts` (render pipeline) +- `src/data/restore.ts` (file format compatibility) +- `src/actions/manager.ts` (action dispatch system) +- `src/types.ts` (core type definitions) + +If protected files must change, require: + +1. Understanding of dependencies and downstream impact. +2. Running the relevant test suite. +3. Manual verification of behavior. + +## Working Style + +- Make focused, minimal changes. +- Do not refactor unrelated code. +- Preserve existing behavior unless asked to change it. +- Flag uncertainty and assumptions in your final update. diff --git a/ONBOARDING.md b/ONBOARDING.md new file mode 100644 index 0000000..6fe816b --- /dev/null +++ b/ONBOARDING.md @@ -0,0 +1,65 @@ +# ONBOARDING + +## Purpose + +This guide helps new contributors (human and AI) work safely in this repository with consistent project rules and Cursor commands. + +## Repository Guidance Files + +- `AGENTS.md`: repo-wide operating guidance for AI agents. +- `.cursor/rules/*.mdc`: focused, persistent rules that apply by scope (`globs`) or globally (`alwaysApply`). +- `.cursor/commands/*.md`: reusable slash commands for common workflows. + +## Quick Start + +1. Read `README.md` for project setup and architecture context. +2. Read `AGENTS.md` before making code changes. +3. Review relevant rule files in `.cursor/rules/`. +4. Use commands in `.cursor/commands/` for consistent execution and review. +5. Keep changes minimal, test behavior changes, and document assumptions. + +## Current Cursor Rules + +- `architecture.mdc`: architecture constraints for project structure and dependencies. +- `conventions.mdc`: code conventions for TypeScript/components. +- `do-not-touch.mdc`: protected files and restrictions. +- `action-manager-state.mdc`: state updates must go through `actionManager.dispatch()`. +- `canvas-rendering.mdc`: rendering must remain on Canvas 2D pipeline. +- `typescript-safety.mdc`: strict typing and type import conventions. +- `module-boundaries.mdc`: package boundaries and utility reuse guidance. +- `testing-requirements.mdc`: tests required for behavior changes. +- `change-scope.mdc`: keep changes focused and minimal. + +## Rule Usage Notes + +- Rule scope is controlled by front-matter: + - `globs`: where a rule applies (for example `packages/**/*.ts`). + - `alwaysApply`: if `true`, rule applies in every session. +- Keep rules concise and actionable. +- Include a `How to verify` section in rule content for consistency. + +## Current Cursor Commands + +- `rules-check.md` -> `/rules-check` + - Reviews changes against `AGENTS.md` and all `.cursor/rules/*.mdc`. + - Returns violations, risk level, and a compliance checklist. +- `implement-safe.md` -> `/implement-safe` + - Implements a request with minimal changes while enforcing repository rules. + - Accepts user prompt via `$ARGUMENTS`. + +## Recommended Workflow + +1. Start with `/implement-safe `. +2. Apply the smallest correct change. +3. Add/update tests for behavior changes. +4. Run `/rules-check` before finalizing. + +## Protected File Reminder + +Certain files are protected by policy in `do-not-touch.mdc` and `AGENTS.md`. Any change to protected/core files requires explicit approval plus stronger verification. + +## Maintenance + +- When adding new `.cursor/rules` files, update this document. +- When adding new `.cursor/commands`, add usage notes here. +- Keep examples and paths aligned with the current monorepo layout. diff --git a/README.md b/README.md index 74fc2c0..7d5b12c 100644 --- a/README.md +++ b/README.md @@ -1,124 +1,42 @@ - - - - Excalidraw - - +# Cursor Rules -

- Excalidraw Editor | - Blog | - Documentation | - Excalidraw+ -

+This folder is for Cursor rule files (e.g. `RULE.md`) that provide persistent AI guidance within this repository. -
-

- An open source virtual hand-drawn style whiteboard.
- Collaborative and end-to-end encrypted.
-
-

-
+## Pull Request Placement Rule -
-

- - Excalidraw is released under the MIT license. - - npm downloads/month - - PRs welcome! - - Chat on Discord - - Ask DeepWiki - - Follow Excalidraw on Twitter -

+- Any Cursor-related files included in a Pull Request must be placed under `.cursor/`. +- Rule files must go in `.cursor/rules/`. +- Command files must go in `.cursor/commands/`. -
-
- - Product showcase - -
-

- Create beautiful hand-drawn like diagrams, wireframes, or whatever you like. -

-
-
-
+## What Goes In `.cursor/rules/` -## Features +- Files with `.mdc` extension only. +- Persistent project guidance and constraints for AI. +- Rules that define architecture, coding conventions, safety limits, testing expectations, and protected files. +- Rules should use front-matter fields such as `description`, `globs`, and `alwaysApply`. +- Examples: + - `architecture.mdc` + - `conventions.mdc` + - `do-not-touch.mdc` + - `module-boundaries.mdc` + - `change-scope.mdc` + - `canvas-rendering.mdc` + - `action-manager-state.mdc` + - `typescript-safety.mdc` + - `testing-requirements.mdc` -The Excalidraw editor (npm package) supports: +## What Goes In `.cursor/commands/` -- 💯 Free & open-source. -- 🎨 Infinite, canvas-based whiteboard. -- ✍️ Hand-drawn like style. -- 🌓 Dark mode. -- 🏗️ Customizable. -- 📷 Image support. -- 😀 Shape libraries support. -- 🌐 Localization (i18n) support. -- 🖼️ Export to PNG, SVG & clipboard. -- 💾 Open format - export drawings as an `.excalidraw` json file. -- ⚒️ Wide range of tools - rectangle, circle, diamond, arrow, line, free-draw, eraser... -- ➡️ Arrow-binding & labeled arrows. -- 🔙 Undo / Redo. -- 🔍 Zoom and panning support. +- Files with `.md` extension only. +- Reusable slash command prompts the team can run in Cursor. +- Commands that describe task workflows (for example: implement safely, run compliance review, prepare PR checks). +- Commands can include `$ARGUMENTS` placeholders for user input. +- Examples: + - `rules-check.md` -> `/rules-check` + - `implement-safe.md` -> `/implement-safe` -## Excalidraw.com +## Do Not Mix These -The app hosted at [excalidraw.com](https://excalidraw.com) is a minimal showcase of what you can build with Excalidraw. Its [source code](https://github.com/excalidraw/excalidraw/tree/master/excalidraw-app) is part of this repository as well, and the app features: +- Do not put command prompts in `.cursor/rules/`. +- Do not put `.mdc` rule definitions in `.cursor/commands/`. -- 📡 PWA support (works offline). -- 🤼 Real-time collaboration. -- 🔒 End-to-end encryption. -- 💾 Local-first support (autosaves to the browser). -- 🔗 Shareable links (export to a readonly link you can share with others). - -We'll be adding these features as drop-in plugins for the npm package in the future. - -## Quick start - -**Note:** following instructions are for installing the Excalidraw [npm package](https://www.npmjs.com/package/@excalidraw/excalidraw) when integrating Excalidraw into your own app. To run the repository locally for development, please refer to our [Development Guide](https://docs.excalidraw.com/docs/introduction/development). - -Use `npm` or `yarn` to install the package. - -```bash -npm install react react-dom @excalidraw/excalidraw -# or -yarn add react react-dom @excalidraw/excalidraw -``` - -Check out our [documentation](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/installation) for more details! - -## Contributing - -- Missing something or found a bug? [Report here](https://github.com/excalidraw/excalidraw/issues). -- Want to contribute? Check out our [contribution guide](https://docs.excalidraw.com/docs/introduction/contributing) or let us know on [Discord](https://discord.gg/UexuTaE). -- Want to help with translations? See the [translation guide](https://docs.excalidraw.com/docs/introduction/contributing#translating). - -## Integrations - -- [VScode extension](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor) -- [npm package](https://www.npmjs.com/package/@excalidraw/excalidraw) - -## Who's integrating Excalidraw - -[Google Cloud](https://googlecloudcheatsheet.withgoogle.com/architecture) • [Meta](https://meta.com/) • [CodeSandbox](https://codesandbox.io/) • [Obsidian Excalidraw](https://github.com/zsviczian/obsidian-excalidraw-plugin) • [Replit](https://replit.com/) • [Slite](https://slite.com/) • [Notion](https://notion.so/) • [HackerRank](https://www.hackerrank.com/) • and many others - -## Sponsors & support - -If you like the project, you can become a sponsor at [Open Collective](https://opencollective.com/excalidraw) or use [Excalidraw+](https://plus.excalidraw.com/). - -## Thank you for supporting Excalidraw - -[](https://opencollective.com/excalidraw/tiers/sponsors/0/website) [](https://opencollective.com/excalidraw/tiers/sponsors/1/website) [](https://opencollective.com/excalidraw/tiers/sponsors/2/website) [](https://opencollective.com/excalidraw/tiers/sponsors/3/website) [](https://opencollective.com/excalidraw/tiers/sponsors/4/website) [](https://opencollective.com/excalidraw/tiers/sponsors/5/website) [](https://opencollective.com/excalidraw/tiers/sponsors/6/website) [](https://opencollective.com/excalidraw/tiers/sponsors/7/website) [](https://opencollective.com/excalidraw/tiers/sponsors/8/website) [](https://opencollective.com/excalidraw/tiers/sponsors/9/website) [](https://opencollective.com/excalidraw/tiers/sponsors/10/website) - - - -Last but not least, we're thankful to these companies for offering their services for free: - -[![Vercel](./.github/assets/vercel.svg)](https://vercel.com) [![Sentry](./.github/assets/sentry.svg)](https://sentry.io) [![Crowdin](./.github/assets/crowdin.svg)](https://crowdin.com) diff --git a/action-manager-state.mdc b/action-manager-state.mdc new file mode 100644 index 0000000..14caff8 --- /dev/null +++ b/action-manager-state.mdc @@ -0,0 +1,18 @@ +--- +description: State updates must go through actionManager +globs: packages/**/*.ts,packages/**/*.tsx +alwaysApply: false +--- + +# State Updates Through actionManager + +- Use project state managed by `actionManager`. +- Do not introduce Redux, Zustand, MobX, or ad-hoc global stores. +- Route state changes via `actionManager.dispatch()` only. +- Keep state shape compatible with `AppState`. + +## How to verify + +- Search changed files for direct state mutation patterns. +- Confirm new state-changing code calls `actionManager.dispatch()`. +- Confirm no new third-party state manager dependency was added. diff --git a/architecture.mdc b/architecture.mdc new file mode 100644 index 0000000..a6492ab --- /dev/null +++ b/architecture.mdc @@ -0,0 +1,24 @@ +--- +description: Architecture constraints for the project +globs: src/** +alwaysApply: false +--- + +# Project Architecture + +## State Management + +- Custom state via actionManager — NOT Redux/Zustand/MobX +- State updates: actionManager.dispatch() ONLY +- State type: AppState (src/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 src/utils/ before adding external helpers diff --git a/canvas-rendering.mdc b/canvas-rendering.mdc new file mode 100644 index 0000000..cd70484 --- /dev/null +++ b/canvas-rendering.mdc @@ -0,0 +1,18 @@ +--- +description: Keep rendering on Canvas 2D pipeline +globs: packages/**/*.ts,packages/**/*.tsx +alwaysApply: false +--- + +# Canvas Rendering Pipeline + +- Use Canvas 2D rendering for drawing operations. +- Preserve render flow: `Scene -> renderScene() -> canvas context`. +- Do not switch drawing to React DOM. +- Do not introduce `react-konva`, `fabric.js`, or `pixi.js`. + +## How to verify + +- Review rendering changes for canvas context usage. +- Confirm no JSX/DOM drawing replacement was added. +- Check `package.json` diff for prohibited rendering dependencies. diff --git a/change-scope.mdc b/change-scope.mdc new file mode 100644 index 0000000..8d7023c --- /dev/null +++ b/change-scope.mdc @@ -0,0 +1,17 @@ +--- +description: Keep changes minimal and task-focused +alwaysApply: true +--- + +# Change Scope Discipline + +- Make the smallest change that solves the requested task. +- Avoid broad refactors unless explicitly requested. +- Do not modify protected/core files without explicit approval. +- Call out assumptions and risks when requirements are ambiguous. + +## How to verify + +- Review diff for unrelated file churn and remove it. +- Confirm changes map directly to the user request. +- Ensure any protected-file edits have explicit approval recorded. diff --git a/conventions.mdc b/conventions.mdc new file mode 100644 index 0000000..3dca909 --- /dev/null +++ b/conventions.mdc @@ -0,0 +1,3 @@ +--- +alwaysApply: true +--- diff --git a/do-not-touch.mdc b/do-not-touch.mdc new file mode 100644 index 0000000..3dca909 --- /dev/null +++ b/do-not-touch.mdc @@ -0,0 +1,3 @@ +--- +alwaysApply: true +--- diff --git a/implement-safe.md b/implement-safe.md new file mode 100644 index 0000000..ec9198b --- /dev/null +++ b/implement-safe.md @@ -0,0 +1,16 @@ +Implement the request below with minimal, task-focused edits while following `AGENTS.md` and `.cursor/rules/*.mdc`. + +Request: +$ARGUMENTS + +Execution requirements: +- make the smallest correct change +- avoid unrelated refactors +- do not add new dependencies without explicit approval +- do not modify protected files without explicit approval +- update or add tests when behavior changes + +Before finishing, provide: +1. files changed +2. what was verified (tests/lint/typecheck/manual) +3. assumptions or follow-ups diff --git a/module-boundaries.mdc b/module-boundaries.mdc new file mode 100644 index 0000000..49563aa --- /dev/null +++ b/module-boundaries.mdc @@ -0,0 +1,18 @@ +--- +description: Respect package boundaries and reuse existing utilities +globs: packages/**/*.ts,packages/**/*.tsx +alwaysApply: false +--- + +# Module Boundaries + +- Reuse existing helpers before creating new utility modules. +- Keep imports scoped to intended package APIs where possible. +- Avoid circular dependencies across packages. +- Keep feature changes localized; do not restructure unrelated modules. + +## How to verify + +- Review import graph in changed files for new cross-package coupling. +- Confirm no duplicate utility logic was added when equivalents exist. +- Check for newly introduced circular import warnings/errors. diff --git a/rules-check.md b/rules-check.md new file mode 100644 index 0000000..63e9732 --- /dev/null +++ b/rules-check.md @@ -0,0 +1,15 @@ +Review my proposed or current changes for compliance with project rules in `AGENTS.md` and `.cursor/rules/*.mdc`. + +Focus on: +- architecture constraints +- TypeScript safety +- dependency restrictions +- protected file restrictions +- testing expectations + +Return: +1. Violations found (with file paths and fixes) +2. Risk level (low/medium/high) +3. A short checklist to make the changes compliant + +If no violations are found, explicitly say "No rule violations found." diff --git a/testing-requirements.mdc b/testing-requirements.mdc new file mode 100644 index 0000000..e95e444 --- /dev/null +++ b/testing-requirements.mdc @@ -0,0 +1,18 @@ +--- +description: Require tests for behavior changes +globs: packages/**/*.ts,packages/**/*.tsx +alwaysApply: false +--- + +# Testing Requirements + +- Add or update tests when behavior changes. +- Prefer colocated tests near modified modules. +- Cover edge cases for state transitions and rendering-sensitive logic. +- Do not merge known-failing test updates. + +## How to verify + +- Check diffs include relevant test updates for behavior changes. +- Run targeted tests for changed packages. +- Confirm CI/local test command passes for touched areas. diff --git a/typescript-safety.mdc b/typescript-safety.mdc new file mode 100644 index 0000000..8fc5fb5 --- /dev/null +++ b/typescript-safety.mdc @@ -0,0 +1,18 @@ +--- +description: TypeScript strictness and typing conventions +globs: packages/**/*.ts,packages/**/*.tsx +alwaysApply: false +--- + +# TypeScript Safety + +- Keep strict typing; avoid `any` unless explicitly justified. +- Do not use `@ts-ignore` when a type-safe fix is possible. +- Prefer `type` aliases for simple object and union types. +- Use `import type` for type-only imports. + +## How to verify + +- Search changed files for `any` and `@ts-ignore`. +- Ensure type-only imports use `import type`. +- Run project type checking and resolve new type errors.