hishamk/spatialboard: A React + TypeScript spatial canvas and node-board library for whiteboards, visual editors, and graph interfaces.

A React + TypeScript spatial canvas and node-board library for whiteboards, visual editors, and graph interfaces. - hishamk/spatialboard

Summary

SpatialBoard is a TypeScript library that combines an infinite canvas, a node-graph editor, a presentation surface, and an LLM-readable board format. It centers on a headless SpatialEngine that holds all board state, with a React shell that ships hand-drawn whiteboarding, typed data flow between nodes, frame-based slide decks, and a markdown-compatible serialization format called SBD.

What it is useful for

Engineers building products that need more than a static diagram tool. The README describes four concrete use cases: whiteboarding (pressure-aware freehand ink, rough shapes via roughjs, sticky notes, BlockNote rich text, frames, snapping, alignment guides, grouping, minimap, undo history); visual programming (custom node types with typed input/output ports and a pure compute function that the reactive DataFlowEngine propagates, with cycle detection); presentations (frames double as slides with pan, fade, dissolve, zoom, fold, and 3D cube transitions driven by engine.enterPresentation()); and AI-driven boards (getAgentState() for budgeted snapshots, a programmatic drawing API, and SBD for round-tripping boards through LLM context).

The library also covers interop gaps that often slow canvas projects: it imports Excalidraw .excalidrawlib shape libraries, includes a Mermaid importer that turns flowcharts and sequence diagrams into editable nodes, and exposes remote-op methods (addRemoteNode, applyRemoteNodeUpdate, deleteRemoteNode) with gesture awareness for plugging into any CRDT or sync layer. Storage is left to the caller via toSBD() / toJSON().

How engineers can use it

Installation is npm install spatialboard, with react and react-dom (^18 || ^19) as the only required peers. The minimal app is a SpatialEngine instance passed to <SpatialBoard /> inside a sized container, plus an import of spatialboard/style.css. The package exposes three entries: spatialboard (full board, engine, and built-in nodes), spatialboard/blocknote (opt-in rich text, adding BlockNote and Mantine peers), and spatialboard/engine (headless, no React, no CSS — usable in tests and agent scripts).

Custom behavior is registered by passing a NodeTypeDefinition (React component plus type name) to <SpatialBoard nodeTypes={...} />; the README's counter example shows the full surface, and docs/custom-nodes.md covers ports, hit-testing, properties panels, and lifecycle hooks. For AI workflows, engine.toSBD() and engine.fromSBD(text) round-trip boards through markdown with HTML-comment directives, and getAgentStateMarkdown() produces prompts.

Four runnable examples (examples/basic, examples/rich-text, examples/custom-nodes, examples/dev-app) ship in the repo, all PWA-installable and persisting to localStorage. Documented limitations: the interaction layer, data-flow edge cases, and React rendering are described in the README's roadmap as still mostly verified manually, and the planned MCP server and end-to-end CRDT collaboration example are not yet shipped, so real-time collab needs a bring-your-own-transport layer for now.