suaveplan/openspec/changes/enterprise-gaming-r3f-ui/proposal.md

OpenSpec Change: enterprise-gaming-r3f-ui

• Change ID: enterprise-gaming-r3f-ui
• Package: @suaveplan/r3f-ui
• Category: gaming/gameplay
• Target path: gaming/gameplay/r3f-ui
• Status: PROPOSED
• Date: 2026-04-24

---

Summary

Deliver @suaveplan/r3f-ui on the genesis branch from scratch at enterprise quality. The package provides HTML/React UI components embedded into 3D space via React Three Fiber: Billboard3D always-facing panel with configurable lock-axis, WorldLabel text label anchored to a 3D point with screen-edge clamping, HealthBar3D segmented progress bar above an entity, InteractionPrompt contextual action tooltip with keyboard hint, Tooltip3D hover-triggered tooltip, and RadialMenu circular context menu. All components use @react-three/drei's <Html> for crisp GPU-independent rendering. Genesis adds 100% coverage and Storybook stories.

---

Available workspace deps

@suaveplan/error, @suaveplan/types, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

function Billboard3D(props: Billboard3DProps): JSX.Element
// position, lockX, lockY, lockZ, children

function WorldLabel(props: WorldLabelProps): JSX.Element
// position, text, clampToEdge, style

function HealthBar3D(props: HealthBar3DProps): JSX.Element
// value, max, segments, width, height, colors

function InteractionPrompt(props: InteractionPromptProps): JSX.Element
// label, keyHint, visible, position

function Tooltip3D(props: Tooltip3DProps): JSX.Element
// content, triggerRef, offset

function RadialMenu(props: RadialMenuProps): JSX.Element
// items: RadialMenuItem[], onSelect, open, position

---

File layout

gaming/gameplay/r3f-ui/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    components/
      Billboard3D/ (tsx + md + test + stories + index)
      WorldLabel/ (tsx + md + test + stories + index)
      HealthBar3D/ (tsx + md + test + stories + index)
      InteractionPrompt/ (tsx + md + test + stories + index)
      Tooltip3D/ (tsx + md + test + stories + index)
      RadialMenu/ (tsx + md + test + stories + index)
  tests/integration.test.ts