Development

Start the dev server:

pnpm dev

pnpm dev runs three steps in order (from package.json):

package.json

"dev": "pnpm run build:wasm && pnpm run build:vanilla-logger && vite"

1. build:wasm: compiles rust/brain_sim to WebAssembly via wasm-pack.
2. build:vanilla-logger: bundles the diagnostics logger into a standalone IIFE for the legacy reference pages (see Diagnostics Logger and Reference Pages).
3. vite: starts the Vite dev server on port 9001.

Open http://localhost:9001 once Vite reports it is ready.

Keyboard shortcuts

The shortcuts are registered in src/events.ts:

Key	Action
Space	Toggle simulation pause.
A	Toggle the grid helper.
S	Toggle the axis helper.

The diagnostics panel adds one more, handled in src/diag/logger.ts:

Key	Action
Ctrl + Shift + L	Toggle the in-app diagnostics panel.

Hot reload

Vite handles HMR for the TypeScript and CSS. Changes to the Rust code are not hot-reloaded: rerun pnpm run build:wasm (or restart pnpm dev) to pick up simulation changes.

All available commands

Command	Description
pnpm dev	Start dev server (builds WASM + vanilla logger, then Vite HMR)
pnpm build	Full production build (WASM + vanilla logger + Vite)
pnpm preview	Preview production build locally on port 9001
pnpm typecheck	Run TypeScript type checking (no emit)
pnpm test	Run unit tests (Vitest)
pnpm test:watch	Run tests in watch mode
pnpm test:e2e	Run Playwright end-to-end tests
pnpm test:e2e:ui	Run Playwright tests with UI
pnpm search:index	Populate Typesense search indexes
pnpm supabase:start	Start local Supabase stack
pnpm supabase:stop	Stop local Supabase stack
pnpm supabase:reset	Reset local database
pnpm supabase:diff	Generate migration diff
pnpm supabase:push	Push migrations to remote
pnpm supabase:gen-types	Regenerate TypeScript types from schema

Docs site

cd docs-site
pnpm install
pnpm start         # Live-editing dev server at http://localhost:3000
pnpm build         # Production build, including the local search index
pnpm serve         # Serve the production build
pnpm preview:search # Build, serve, and verify local search

When the app runs from a local origin such as http://localhost:9001, the top-nav Docs button and in-app help links default to the Docusaurus dev server at http://localhost:3000. Start both servers when you want the app and docs to work side by side locally.

The docs search box uses @easyops-cn/docusaurus-search-local. pnpm start is useful for editing layout and content, but it does not serve the generated search index. To test search, run pnpm build followed by pnpm serve, or use pnpm preview:search.

Troubleshooting stale content

If changes don't appear after saving:

1. Hard refresh the browser: Ctrl+Shift+R
2. Clear Vite cache: npx vite --force
3. Full clean rebuild: pnpm build
4. Check terminal: if the Vite process crashed, restart with pnpm dev

Security note for shared dev servers

vite.config.ts sets server.fs.allow: ['..'] and binds the dev server on port 9001 with no authentication. That is convenient locally because the build serves sibling reference directories, but it means anyone who can reach the port can read files from the parent directory. Do not expose the dev server on a public or shared network as-is. For sharing a build, use the static output from pnpm build behind your own server instead.

Typesense Search Indexer (Plan 008)

When Typesense is configured, populate or refresh the search indexes:

pnpm search:index

This runs scripts/typesense-index.mjs, which connects to Typesense (using TYPESENSE_ADMIN_KEY + VITE_TYPESENSE_HOST from .env), drops and recreates the traces_spans and docs collections, then bulk-imports data from Supabase and docs-site/docs/**/*.md. The script auto-loads .env so it works without the --env-file flag on Node < 20.6. Requires admin credentials in .env.