Skip to content

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.

Terminal window
git clone https://github.com/harryhanYuhao/graphboard.git
cd graphboard
pnpm install
pnpm dev # http://localhost:3000

The project uses pnpm (see pnpm-workspace.yaml); Node 20+ is required.

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 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.

  • 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 to VertexNode / GraphEdge surfaces there rather than in every test file.

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.md wins.
  • 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 main pnpm-workspace.yaml) with its own build (see the site’s own AGENTS.md).
  • README.md (main repo) — a thin pointer doc: quickstart + links to the above.
  • 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.)

These are the rules most likely to bite a contributor who doesn’t know them:

  1. All mutation logic lives in src/lib/graph/operations.ts. Call it from the store, not inline in components.
  2. React Flow is controlled. nodes/edges come from the store; onNodesChange / onEdgesChange route back via store actions. Don’t read graph data from React Flow’s internals in components — read from the store.
  3. Edges are click-to-connect only. nodesConnectable={false} is deliberate. The click dispatch (computeVertexClick in operations.ts) implements six mutually-exclusive cases; re-enabling drag-connect means redesigning that dispatch.
  4. HANDLE_IDS is the contract between operations, the serializer, and the renderer. Never inline handle-id string literals — use the constants in types.ts. On the persisted side, handles are numeric indices (handleIdToIndex / indexToHandleId); don’t break that mapping.
  5. VERTEX_TYPES / VERTEX_TYPE_MAP (in src/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 the isSpiderType / isDirectionalVertex / isBoundaryVertex predicates 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.
  6. 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.
  7. The graph / view split is load-bearing. The compute layer (present and future) reads only doc.graph. Selection, rotation, React Flow type/origin/measured/internals.* are never persisted. If you add a visual field, it goes in view; if you add a graph-theoretic field, it goes in graph.

These registries must be updated together when their domain changes — there is no compile-time link between them:

  • Keyboard shortcuts: src/lib/keyboard/shortcuts.ts is a display-only registry; the actual dispatch is in src/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 (in src/lib/graph/vertex-registry.ts) is consumed by VertexNode, VertexSwatch, VertexTypeMenu, and VertexPropertyPanel. Changing the registry updates all four, but if you add a brand-new consumer, make sure it reads from VERTEX_TYPES rather than re-declaring shape data.
  • Grid size: GRID_SIZE in src/lib/graph/operations.ts must match the <Background gap={GRID_SIZE}> prop in GraphEditor.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.

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 build from the repo root. The root Cargo.toml is a Cargo workspace with members = ["crates/zxw", "crates/cartographer"] and default-members = ["crates/zxw"], so bare cargo commands hit only the compute crate (crates/cartographer is a vendored research CLI, kept for planned later integration).
  • WASM — pnpm build:wasm runs wasm-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.