# Contributing

## Setup and checks

Use Node.js 20 or 22. Install from the repository root:

```bash
npm ci --include=dev
npm run demo       # Vite writing demo
npm run dev        # Library build in watch mode
```

Before submitting a change, run the checks relevant to it:

```bash
npm run typecheck
npm run typecheck:demo
npm run lint
npm test
npm run build
npm run build:demo
npx playwright install chromium
npm run test:e2e
```

`CHROME_PATH=/path/to/chrome` selects an installed Chrome. CI installs Playwright Chromium and retains browser failures as artifacts. With Vite running, `node scripts/capture.mjs` records the demo and a long-document sample; `CAPTURE_OUT` and `DEMO_URL` override its output directory and URL. The capture uses `?test=1` to load a deterministic note in an isolated browser context.

## Implementation boundaries

- Markdown in `EditorState` is authoritative. Editor changes use transactions and normal history.
- Keep parser extensions in `src/syntax`, shared mode/update behavior in `src/core`, decorations in plugins, and DOM behavior in widgets.
- Inline styling and highlighting can use visible ranges in ViewPlugins. Block replacement and other geometry-changing decorations belong in StateFields.
- A widget may survive edits before it. Resolve live document positions from its DOM, or explicitly map state; never write using a stale constructor offset.
- Async work must tolerate cancellation and destroyed/reused DOM. Request measurement when an async preview changes height.
- Keep note lookup, file saving, navigation and third-party rendering behind host callbacks. Avoid adding a parallel vault or extension system.
- Add a focused regression for changes that can affect document integrity, undo, async ordering or editing behavior. Use browser tests for real layout, focus, clipboard events and selection; jsdom cannot prove those behaviors.

The table cell editor intentionally commits drafts on blur/navigation. Treat external document replacement and collaboration as coordinated host operations, and document changes to this behavior.

## Manual acceptance

Use actual system IMEs and physical touch devices before making platform-support claims. Check candidate confirmation versus Enter, cancellation, selection across block boundaries, virtual keyboard resizing, keyboard-only toolbar navigation and screen-reader labels. Automated composition events and narrow desktop viewports only cover part of that behavior.

## License

Contributions are licensed under the project's MIT license.