Contributing
Supermouse is a plugin-first cursor runtime. Contributions are welcome — this page covers what belongs in this repo, how to contribute code, and how the toolchain works.
What belongs in this repo
This monorepo is intentionally conservative. It contains the core runtime and reference-quality plugin implementations only.
- ✓Core runtime fixes
- ✓Performance improvements
- ✓Bug fixes
- ✓Documentation
- ✓Reference-quality plugins that demonstrate an essential pattern
- ×Niche visual effects
- ×Framework-specific wrappers
- ×Stylistic variants of existing plugins
- ×Experimental or opinionated behavior
Contributing Code
Use pnpm.
Keep changes scoped to a single concern per PR.
Avoid introducing new abstractions without a clear performance or ergonomics justification.
The render loop is hot-path code — allocations and DOM reads inside
update()are scrutinized. See Core Architecture for the DOM Firewall contract.Logic plugins must declare priority
< 0. Positive or zero priority causes visual tearing.
pnpm install
pnpm devToolchain
The monorepo includes a custom CLI to scaffold and remove plugin packages, keeping the workspace consistent.
Workspace
Managed with pnpm. Internal packages are linked via workspace:* for instant cross-package updates.
Bundler
vite in library mode. Emits dual ESM/UMD builds for browser and Node compatibility.
Versioning
@changesets/cli manages semver bumping and changelog generation from PRs.
Interactive Manager
We provide a unified, interactive CLI manager that acts as the control center for all plugin operations. The vision is for this toolchain to eventually be standalone (e.g., @supermousejs/cli).
pnpm run manageDirect CLI Commands
For users wanting granularity or for CI pipelines, the underlying granular commands are also available.
Scaffold Plugin
Creates the package folder, tsconfig, vite config, and links it to the playground.
pnpm run create:plugin <name>Remove Plugin
Unlinks from workspace and playground, then deletes the package directory.
pnpm run remove:plugin <name>Philosophy
No hidden state. No side effects outside the plugin container. Input → Output.
Input → Logic → Physics → Render. One direction, every frame.
Explicit configuration over auto-guessing.
The core is small. The ecosystem is not.