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

OpenSpec Change: enterprise-gaming-r3f-building

• Change ID: enterprise-gaming-r3f-building
• Package: @suaveplan/r3f-building
• Category: gaming/scene
• Target path: gaming/scene/r3f-building
• Status: PROPOSED
• Date: 2026-04-24
• Reference spec: /mnt/s/web/suaveplan/enterprise/r3f-building.md

---

Summary

Deliver @suaveplan/r3f-building on the genesis branch from scratch at enterprise quality. The package provides R3F building mode UI: ghost preview of the piece being placed, snap socket highlight spheres, invalid placement red tint, confirm/cancel keybind integration, and structural instability shake effect. It wires directly to @suaveplan/building's PlacementEngine and StructureGraph. A BuildingMode component activates the placement mode context; PlacementGhost renders the translucent preview mesh. Genesis adds structured errors, OTel placement counter, and 100% coverage.

---

Available workspace deps

@suaveplan/error, @suaveplan/building, @suaveplan/controller, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

function BuildingMode(props: BuildingModeProps): JSX.Element
// registry, onPlaced, onCancel, controllerManager

function PlacementGhost(props: PlacementGhostProps): JSX.Element
function SnapIndicator(props: SnapIndicatorProps): JSX.Element
function PlacedPieces(props: PlacedPiecesProps): JSX.Element

function useBuildingMode(): BuildingModeCon```text

---

## File layout

```text
gaming/scene/r3f-building/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    context/building-mode-provider.tsx + md + test
    hooks/use-building-mode.ts + md + test
    components/
      BuildingMode/ (tsx + md + test + stories + index)
      PlacementGhost/ (tsx + md + test + stories + index)
      SnapIndicator/ (tsx + md + test + stories + index)
      PlacedPieces/ (tsx + md + test + stories + index)
  tests/integration.test.ts