Without a unified 2D canvas layer, spatial UIs splinter into hand-rolled pan/zoom, fragile position tracking, and incompatible node drag-and-drop — a workflow graph snaps to one grid, a diagram uses another, and an agent trying to read node placement via DOM scraping gets stale bounding boxes. Canvas solves the foundational layer: one coordinate system, one viewport, stable node identity, and pluggable 3D engines that run alongside without interfering with the 2D surface.

Canvas is a controlled compound component that establishes a pan/zoom viewport over a 2D node-and-edge graph surface. It exposes viewport + onViewportChange for viewport control, pannable and zoomable toggles, an optional gridSize + snapToGrid for alignment, and fitOnMount to auto-center nodes. Subcomponents Canvas.Node (positioned via x, y, and id), Canvas.Edge (connecting nodes with curves, markers, labels), Canvas.Minimap, and Canvas.Controls are discoverable via useCanvas(), which yields node registry and viewport state. Each node carries data-node-id={id} and data-react-fancy-canvas-node for agent lookup; dragged positions fire onPositionChange callbacks. An optional engine prop (string "dom" or a CanvasEngine object) mounts a 3D backend alongside the 2D surface — WebGL engines come from sibling packages like @particle-academy/fancy-3d-babylon.

Import Canvas and subcomponents from @particle-academy/fancy-3d, wrap your diagram or graph in <Canvas viewport={vp} onViewportChange={setVp} showGrid snapToGrid>, place <Canvas.Node id="a" x={10} y={20}> elements inside, connect them with <Canvas.Edge from="a" to="b">, and optionally add <Canvas.Minimap /> and <Canvas.Controls /> overlays. For WebGL, import an engine from a companion package and pass engine={babylonEngine}; inside any child, call useCanvas() to access the active engine and viewport—agents read/write node positions via onPositionChange callbacks and stable id attributes, with no Playwright scraping required.