Define the canvas renderer contract and make React Flow its first implementation

[kube]

Important

Refactor, no user-facing change.

Summary

Before this PR, the canvas view was one React Flow component. Node and arc derivation, selection, drag, connection and placement rules and the viewport lived in React Flow callbacks and hooks. Overlays such as the viewport controls called React Flow's API directly, so a second renderer would have to copy all of it.

Splits the canvas into a renderer-agnostic scene, shared interaction semantics and a renderer contract. React Flow becomes the first renderer behind that contract, moved under its own folder. Behaviour is unchanged.

Links

• Ticket to be filed

Changes

Contract

• CanvasScene describes what a renderer draws

  canvas-scene.ts builds it from the net and the editor state and replaces use-sdcpn-to-react-flow.
  Nodes carry position, size, selection, hover and dimming.
  Arcs carry kind, weight, ports and colour.

• CanvasRenderer props and the CanvasController context

  A renderer receives the scene, the settled container size and host viewport actions.
  It publishes a controller with get and set viewport, zoom in and out, and screen to scene conversion.

• Overlays talk to the controller instead of React Flow

  Viewport controls and the recenter-on-panel-open hook use useCanvasController.

• Fit and recenter math without xyflow

  canvas-viewport.ts replaces ui/lib/viewport.ts with the same formulas.

• Renderer registry keyed by name

  sdcpn-view.tsx measures the container, builds the scene and mounts the registered renderer.
  It remounts when the document or the renderer changes.

Shared interactions

• One hook holds the editing semantics

  use-canvas-interactions.ts covers hover, selection changes, box selection, node drag with grid snapping, connection validation, click to place and toolbar drops.
  A renderer turns its own hit testing and gestures into these calls.

• Toolbar drag payload shared by the bottom bar and renderers

  views/shared/canvas-node-drag.ts writes and reads the dragged node kind.

React Flow renderer

• React Flow code moves under renderers/react-flow/

  Canvas component, node and edge components, scene to element mapping, node change application, controller, Monaco keyboard isolation and port handle ids.
  Declared as arch-docs layer ui.views.canvas.react-flow.

• xyflow stylesheet import moves from petrinaut.tsx into the renderer

Test coverage

• canvas-scene.test.ts:

  Scene building from a net and editor state: nodes, arcs, dimming.

• canvas-viewport.test.ts:

  Fit and recenter math, moved with the module from ui/lib/viewport.test.ts.

• Existing @hashintel/petrinaut unit suite and stories

How to test

• Open Petrinaut preview on Vercel
• Load example > SIR
• Add places and transitions from the bottom toolbar, connect ports by drag, box select, move nodes with snap to grid
• Simulate > Run, play back
• Expect arcs to pulse and transitions to flash as on main
• Zoom with viewport controls, open a side panel, toggle minimap
• Expect same behaviour as on main

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 3, 2026 11:25pm UTC
petrinaut	Ready	Preview	Sep 3, 2026 11:25pm UTC
petrinaut-docs	Ready	Preview	Sep 3, 2026 11:25pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 3, 2026 11:25pm UTC