OpenSpec Change: enterprise-gaming-react-controller

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

Summary

Deliver @suaveplan/react-controller on the genesis branch from scratch at enterprise quality. The package is the React touch/mouse game-controller kit. It composes a Document root (window-level event manager), a VirtualJoystick component (on-screen analog stick), and ActionButton components for on-screen digital inputs — all wired to @suaveplan/controller's virtual adapter. A useController() hook exposes action states via useSyncExternalStore. Genesis adds Storybook stories for mobile/desktop layouts, Vitest DOM tests, and 100% coverage.

Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/controller` (`workspace:^`)	Virtual adapter, `ControllerManager`
`react` (`catalog:react`)	React 18

Public API surface

function useController(manager: ControllerManager): ControllerState
interface ControllerState {
  isPressed(action: string): boolean
  getAxis(action: string): number
}

// Components
function ControllerDocument(props: ControllerDocumentProps): JSX.Element   // root keyboard/mouse listener
function VirtualJoystick(props: VirtualJoystickProps): JSX.Element         // touch joystick
function ActionButton(props: ActionButtonProps): JSX.Element               // digital button
function DPad(props: DPadProps): JSX.Element                               // 4-way dpad

File layout

gaming/react/react-controller/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    types/common.ts + md
    hooks/use-controller.ts + md + test
    components/
      controller-document/ (tsx + md + test + stories + index)
      virtual-joystick/ (tsx + md + test + stories + index)
      action-button/ (tsx + md + test + stories + index)
      d-pad/ (tsx + md + test + stories + index)

Impact

Downstream: @suaveplan/r3f-controller combines this with R3F camera control. Prerequisites: @suaveplan/controller, react.

2.4 KiB Raw Blame History