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

OpenSpec Change: enterprise-gaming-r3f-emulator

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

---

Summary

Deliver @suaveplan/r3f-emulator on the genesis branch from scratch at enterprise quality. The package renders 3D device emulation interfaces in React Three Fiber: handheld console shell (GameBoy-style and modern pad presets), on-screen virtual display texture (useRenderTarget), button press animations, thumbstick deflection, d-pad tilt, screen glare/smudge material, and a useEmulator hook that pipes @suaveplan/controller input events into the 3D mesh state. Enables in-game retro-game-within-a-game and tutorial device overlays. Genesis adds 100% coverage and Storybook stories.

---

Available workspace deps

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

---

Public API surface

type DevicePreset = 'handheld-retro' | 'handheld-modern' | 'custom'

interface EmulatorProps {
  preset?: DevicePreset
  screenTexture?: THREE.Texture
  inputRef?: ControllerRef
  scale?: number
}

function Emulator(props: EmulatorProps): JSX.Element

function useEmulator(): EmulatorContext
// pressButton, releaseButton, setStick, screenTexture

---

File layout

gaming/devices/r3f-emulator/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    presets/ (handheld-retro.ts, handheld-modern.ts + md)
    hooks/use-emulator.ts + md + test
    components/
      Emulator/ (tsx + md + test + stories + index)
  tests/integration.test.ts