@vitavision/three-react

React Three Fiber components over @vitavision/three. Per-frame updates go through useFrame and refs, never React state: playback is read from a PlayheadSource ({ get(): number }, e.g. @vitavision/workbench's createPlayhead) once per rendered frame.

bun add @vitavision/three-react @vitavision/three [email protected] @react-three/fiber

Peers: react, react-dom, three (^0.186.0) and @react-three/fiber (^9.8.1). No stylesheet: nothing here is a Tailwind class; the colours are read from the @vitavision/ui tokens at runtime.

<SceneCanvas className="h-full">
  <FrameTree baked={baked} playhead={playhead}>
    <Robot id="ur5e" visuals={manifest.visuals} resolve={meshUrl} />
    <AtFrame name="cam_left">
      <CameraFrustum borderRays={rays} depth={0.12} active onSelect={select} />
    </AtFrame>
    <AtFrame name="board">
      <TargetBoard width={0.25} height={0.175} checker={{ cols: 10, rows: 7 }} />
    </AtFrame>
  </FrameTree>
</SceneCanvas>

• SceneCanvas — Z-up canvas in the theme's scene colours: orbit controls, ground grid, lights. up, fov and clip suit other scenes (up={[0, -1, 0]} for a camera-frame, CV scene). Its camera and raycaster enable GIZMO_LAYER. The view is a labelled group and a tab stop: arrow keys orbit and tilt (Shift for larger steps), + and - zoom, 0 returns to the opening view. keyboard={false} makes it pointer-only.
• FrameTree / AtFrame / useFrameTree — a baked scenario as a frame graph; children of AtFrame live in that frame.
• Robot, CameraFrustum, LaserFan, TargetBoard, LightGizmo, FrameAxes.
• SensorImage — a camera's calibrated image of the enclosing FrameTree (a SensorView on its own canvas, physical layer only) at the playhead. It redraws only when the playhead's sample, the theme or the scene changes, and not while it is out of view.
• invalidateScene(runtime) / useSceneInvalidate() — tell a SensorImage to redraw after changing the scene outside React (Robot and TargetBoard do it themselves).
• TargetBoard is printed paper and ink (color, edgeColor) in every theme; only its viewer-only outline follows the theme and the selection.
• useSceneColors — the theme's scene colours, following the dark class.
• SceneColorsProvider — colours to use instead of the tokens, for an app whose palette does not define them; keys left out still follow the tokens.

Colours are tokens only: signal for selection, fg-muted for robots and idle cameras, defect for laser light and X axes, normal Y, signal Z, warn lights.

Server rendering. Safe to render on the server: SceneCanvas renders its labelled wrapper and R3F's empty canvas element, SensorImage renders its empty canvas, and useSceneColors returns neutral gray (there is no document to read the tokens from) until the client hydrates, except for colours a SceneColorsProvider sets. The stories run through the same axe, SSR and visual harness as every other package, with no opt-outs: the WebGL canvas is screenshotted like any other story.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this package by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.