# enterprise-controller

**Package**: `@suaveplan/controller`
**Status**: PROPOSED
**Type**: new-package (migration from `../suaveplan/packages/universal/controller/`)

- **Design**: ./design.md
- **Spec delta**: ./specs/controller/spec.md

## Why

Genesis lacks a universal-tier input controller. The upstream `@suaveplan/controller` package
(67 files, ~5000 LoC) provides a unified `ControllerInput` shape across gamepad, keyboard, mouse,
touch, plus pattern recognition and input buffering. Games built on `@suaveplan/ecs` and the
forthcoming `@suaveplan/game-server` need a deterministic, injectable input layer that does not
read wall-clock time directly and can be exercised under a `FakeClock`.

The upstream code uses `Date.now()` throughout, mutates module-level state, and lacks structured
errors, Zod boundary validation, and OTel instrumentation. This migration re-implements the
public surface with genesis primitives (`Clock`/`IdGenerator` injection, `defineCodes`, OTel
counter + histogram, Zod schemas) while preserving the `ControllerInput` shape, the
`BaseController` lifecycle, the `ControllerMerger` semantics, and the device adapters.

## What changes

- ADDED: `BaseController` — abstract base with state, thresholds, deadzone/threshold logic,
  pollRate gating, lifecycle, event emission, `Clock` injection.
- ADDED: `KeyboardController` — DOM keyboard adapter with configurable key→input mapping.
- ADDED: `GamepadController` — `navigator.getGamepads()` polling adapter with axis deadzone.
- ADDED: `ControllerMerger` — merges N child controllers into a single `ControllerInput`
  state via max-value reduction with stable iteration order.
- ADDED: `InputEventEmitter` — typed event dispatcher with `onInput`/`onStateChange`/`onCombo`
  and listener disposal.
- ADDED: `ControllerError` + `CONTROLLER_CODES` — stable error-code registry via `defineCodes`.
- ADDED: OTel `controller_inputs_total` counter (tags: `device`, `input`) and
  `controller_pattern_match_duration_ms` histogram, no-op without exporter.
- ADDED: Zod-validated public input boundaries (options, snapshots, patterns).
- ADDED: Sibling `.md` (≥200 words, 6 sections) for every implementation file.

## Out of scope (Priority 2 — Deferred 2026-05-24)

Per the migration brief's explicit allowance ("ship the input-device adapters + controller
merger as Priority 1 and defer pattern-recognition + input-buffering"), the following upstream
modules are deferred to a follow-up change:

- `TouchController` — touch event adapter (Priority 2; requires DOM `Touch` polyfills in test).
- `MouseController` — 1296-line upstream module requires structural decomposition into
  ≤300-line genesis modules per CLAUDE.md §3; deferred to Priority 2.
- `InputBuffer` — circular buffer for combo sequences (Priority 2; pattern-recognition layer).
- `InputStateMachine` — pattern-recognition state machine (Priority 2).
- `ModalController` — input-mode router (Priority 2).
- Default `defaultPatterns` constant (hadoken / shoryuken / charge-shot / rapid-fire) — moves
  to Priority 2 with the pattern engine.
- `demo/`, `test-utils/`, `e2e/` — non-shipping; demo + integration harnesses are downstream
  concerns and not part of the published surface.

Justification for deferral (≤1 sentence per upstream §0a anti-patterns rule): every deferred
module depends on a co-shipped component that is itself deferred or on a structural
decomposition that requires its own design review — pattern recognition + input buffering
form one cluster (combo grammar + buffer + state machine) that should land atomically, and
the mouse rewrite needs its own 1296→multi-file split design.

## Source mapping

This change derives from `../suaveplan/packages/universal/controller/`. There is no upstream
`enterprise/controller.md` audit document; this section maps to upstream source files instead.

| Requirement | Source | Notes |
|---|---|---|
| ControllerInput shape | `src/types.ts` L1-L66 | verbatim 32-field shape |
| BaseController lifecycle | `src/base/base-controller.ts` L1-L386 | re-authored to inject `Clock` instead of `Date.now()`; threshold logic preserved |
| KeyboardController | `src/keyboard/keyboard-controller.ts` L1-L226 | re-authored; DOM event listeners + key map |
| GamepadController | `src/gamepad/gamepad-controller.ts` L1-L315 | re-authored; `navigator.getGamepads()` polling |
| ControllerMerger | `src/controller-merger.ts` L1-L298 | re-authored; max-value reduction preserved |
| InputEventEmitter | `src/input/input-event-emitter.ts` L1-L115 | re-authored; typed listener registry |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `defineCodes` error registry | Genesis convention — upstream threw plain `Error` |
| OTel instrumentation | Genesis convention — upstream had no observability |
| Zod boundary schemas | Genesis convention — upstream had no runtime boundary validation |
| `Clock` injection | Genesis convention — upstream read `Date.now()` directly |

## Verification approach

- `src/base/base-controller.test.ts` — lifecycle, threshold, deadzone, poll-rate gating.
- `src/keyboard/keyboard-controller.test.ts` — key→input mapping, focus loss cleanup.
- `src/gamepad/gamepad-controller.test.ts` — axis deadzone, multi-pad fanout.
- `src/controller-merger/controller-merger.test.ts` — max-value reduction, add/remove.
- `src/event-emitter/event-emitter.test.ts` — listener add/remove/dispose.
- `src/errors/errors.test.ts` — every code in `CONTROLLER_CODES` reachable.
- `src/observability/observability.test.ts` — counter + histogram emit under in-memory meter.

### Affected dependents

None — additive, new package.