Contributing
This page is the practical guide for working in the graphboard codebase. It complements the architecture overview and the state and graph-model references.
git clone https://github.com/harryhanYuhao/graphboard.gitcd graphboardpnpm installpnpm dev # http://localhost:3000The project uses pnpm (see pnpm-workspace.yaml); Node 20+ is required.
Commands
Section titled “Commands”| Command | Action |
|---|---|
pnpm dev |
Next.js dev server (Turbopack) |
pnpm build |
Production build into .next/ |
pnpm start |
Serve the production build |
pnpm lint |
ESLint (eslint-config-next, core-web-vitals + TypeScript) |
pnpm test |
Vitest, run once (jsdom env) |
pnpm test:watch |
Vitest in watch mode |
pnpm test:ui |
Vitest UI |
pnpm test:coverage |
Vitest coverage run |
pnpm build:wasm |
Build the Rust crate to WASM (see below) |
pnpm ping:wasm |
Smoke-test the WASM pipeline |
cargo test |
Native Rust tests for the compute crate (workspace default-members = crates/zxw) |
cargo llvm-cov --workspace |
Rust coverage across the workspace |
pnx netlify deploy --prod |
Manual deploy to Netlify (see below) |
There is no dedicated typecheck script — typechecking runs through pnpm build and the VS
Code TypeScript SDK (.vscode/settings.json).
Deployment
Section titled “Deployment”Deployment is manual: pnx netlify deploy --prod (from the app repo root). netlify.toml runs
pnpm run build:wasm; pnpm run build and publishes .next/. The WASM binaries are not
committed to git — the deploy-time build regenerates them.
Testing conventions
Section titled “Testing conventions”- Pure-function helpers (operations, serialisation, edge-geometry, phase parser, registries, shortcuts) and store actions are a primary test surface. Aim to keep new logic pure so it can be tested without standing up a store.
- Components get behavioural tests via React Testing Library (render, interact, assert on DOM and store state). There are no pixel/snapshot tests of styled output — that isn’t worth the maintenance burden.
- Use the shared factories in
src/test-utils/factories.ts(makeVertex,makeEdge) in new tests, so a future change toVertexNode/GraphEdgesurfaces there rather than in every test file.
Documentation map
Section titled “Documentation map”One owner per topic — don’t duplicate across these:
AGENTS.md(main repo root) — the operating manual: commands, layout, architecture invariants, persistence rules. The dev docs mirror it; when they disagree,AGENTS.mdwins.doc/plans.md(main repo) — the compute-layer design contract; its status block at the top says which phases have landed (Phases 0–5 landed, Phase 6 not started). If you change the compute boundary, update it.- This docs site (
doc/zxw-graphboard-doc/submodule) — user-facing: user guides + dev docs. It is a git submodule excluded from the pnpm workspace (!doc/**in the mainpnpm-workspace.yaml) with its own build (see the site’s ownAGENTS.md). README.md(main repo) — a thin pointer doc: quickstart + links to the above.
Coding conventions
Section titled “Coding conventions”- Path alias
@/*→src/*. Prefer it over relative imports for anything outside the same directory. - Any component touching the store,
window, or React Flow must be a"use client"component (this is an App-Router app). - Styling is Tailwind v4 (config-less). Write utility classes inline. Icons from
lucide-react. - IDs via
nanoid(). - No local component state for graph data. Read store slices; dispatch actions. (See State Management.)
Architecture rules that matter for edits
Section titled “Architecture rules that matter for edits”These are the rules most likely to bite a contributor who doesn’t know them:
- All mutation logic lives in
src/lib/graph/operations.ts. Call it from the store, not inline in components. - React Flow is controlled.
nodes/edgescome from the store;onNodesChange/onEdgesChangeroute back via store actions. Don’t read graph data from React Flow’s internals in components — read from the store. - Edges are click-to-connect only.
nodesConnectable={false}is deliberate. The click dispatch (computeVertexClickinoperations.ts) implements six mutually-exclusive cases; re-enabling drag-connect means redesigning that dispatch. HANDLE_IDSis the contract between operations, the serializer, and the renderer. Never inline handle-id string literals — use the constants intypes.ts. On the persisted side, handles are numeric indices (handleIdToIndex/indexToHandleId); don’t break that mapping.VERTEX_TYPES/VERTEX_TYPE_MAP(insrc/lib/graph/vertex-registry.ts) is the single source of truth for vertex shape/colour/size. Adding or changing a generator means editing that one registry (and theisSpiderType/isDirectionalVertex/isBoundaryVertexpredicates if needed) — every consumer picks up the change. There are eleven types today:z,empty,x,w,h,zbox,xbox,and,black_dot(a phaseless Z spider),input,output.- The undo policy has two streams. Structural changes (add/delete) are tracked normally;
visual changes (drag, select, slider) are applied with the temporal store paused. Continuous
gestures must use the
makeGestureController()pattern (snapshot → pause → resume + inject pre-gesture state). See State Management § gesture controller. - The
graph/viewsplit is load-bearing. The compute layer (present and future) reads onlydoc.graph. Selection, rotation, React Flowtype/origin/measured/internals.*are never persisted. If you add a visual field, it goes inview; if you add a graph-theoretic field, it goes ingraph.
Keep these in sync
Section titled “Keep these in sync”These registries must be updated together when their domain changes — there is no compile-time link between them:
- Keyboard shortcuts:
src/lib/keyboard/shortcuts.tsis a display-only registry; the actual dispatch is insrc/components/graph-editor/useKeyboardShortcuts.ts. Adding a shortcut means editing both. (The in-app?dialog and the user-guide shortcuts page are both generated from the registry.) - Vertex types:
VERTEX_TYPES(insrc/lib/graph/vertex-registry.ts) is consumed byVertexNode,VertexSwatch,VertexTypeMenu, andVertexPropertyPanel. Changing the registry updates all four, but if you add a brand-new consumer, make sure it reads fromVERTEX_TYPESrather than re-declaring shape data. - Grid size:
GRID_SIZEinsrc/lib/graph/operations.tsmust match the<Background gap={GRID_SIZE}>prop inGraphEditor.tsx— it drives the dot spacing and position snapping (snapPosition). The paste/import offsets (PASTE_OFFSET_STEP= 24,IMPORT_OFFSET_STEP= 48) are separate constants — don’t change one expecting the other to follow.
Rust / WASM compute layer
Section titled “Rust / WASM compute layer”The crate crates/zxw/ is the compute boundary. It consumes the graph slice of a
GraphDocument and returns a tensor result. Same crate, two build targets:
- Native —
cargo test/cargo buildfrom the repo root. The rootCargo.tomlis a Cargo workspace withmembers = ["crates/zxw", "crates/cartographer"]anddefault-members = ["crates/zxw"], so barecargocommands hit only the compute crate (crates/cartographeris a vendored research CLI, kept for planned later integration). - WASM —
pnpm build:wasmrunswasm-pack build crates/zxw --target web --features wasm --out-dir public/wasm/zxw. The Next.js dev server serves the output as a static asset.
When the frontend calls into the WASM it goes through src/lib/compute/index.ts →
computeTensor(graph, callbacks), which spawns a Web Worker that lazy-loads
public/wasm/zxw/zxw.js and runs the contraction off the main thread. The wrapper reads only
doc.graph, never doc.view. See Compute Layer for the full
architecture, the version handshake, the message protocol, and the result/error model.
The full plan and contract live in doc/plans.md — if you change the compute boundary, update
that plan too.
Reporting and contributing back
Section titled “Reporting and contributing back”- Issues and pull requests: https://github.com/harryhanYuhao/graphboard.
- This documentation site has its own repo: zxw-graphboard-doc — doc fixes and additions are welcome there.