# 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

```ts
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

```text
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
```