# HyperTwist - API.md

Canonical companion surfaces:

- `FEATURE_REGISTRY.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md`

## API philosophy

HyperTwist should use APIs to support the native runtime, not to replace it.
The system should remain primarily native-first and local-first where reasonable.

## Main API families

### Recognition API
- frame ingestion
- facelet/state detection
- confidence reporting
- corrective suggestions

### Replay API
- replay storage and export
- solve timeline annotations
- AI-commentary attachment

### Hypercube runtime API
- exact Melinda `2x2x2x2` cell-turn transform construction
- exact order-specific `N^4` state, legal turns, projection, persistence, and
  dedicated-route contracts for 4D orders `2` through `6`
- exact Magic 120-cell permutation state with `7,560` facelets and `7,440`
  legal base moves
- exact order-3 5D state with `243` cubies and `810` facelets
- procedural simulation actors, orbit/zoom camera, pointer interaction, focus,
  and scene-context helpers
- deliberately bounded projected-scene contracts that remain distinct from
  exact simulation-state ownership

### Coaching API
- drill recommendations
- progression updates
- error clustering
- personalized next-step guidance

### Provider/session API
- provider-neutral speech/vision session contracts
- normalized service health
- local-first endpoint policy with remote HTTPS plus explicit cloud consent
- separate AI, STT, and TTS provider/model/endpoint configuration
- current-Windows-user protected provider credentials
- standalone global speech sessions outside active training runs
- microphone enumeration, non-retaining open test, PCM capture, transient WAV
  lifecycle, transcript delivery, and managed audio ducking
- optional TTS response playback with validated PCM16 WAV handling and
  text-first fallback

### Native player-experience API
- `AHyperTwistPlayerControllerBase` for pause/back/exit, fixed-assistant,
  global-dictation, narration, and preference lifecycle
- `UHyperTwistCoachAssistantWidget` for session-only conversation, offline
  guidance, optional provider replies, dictation draft/submit, and narration
  status
- `UHyperTwistDictationCaptureComponent` for bounded capture and cleanup
- `UHyperTwistSettingsPanelWidget` for Controls, Audio, Graphics,
  Accessibility, and Speech & Coach configuration
- `UHyperTwistPlayerSettingsLibrary` for default/load/save/apply,
  conflict-checked key mapping, microphone checks, account handoff, credential
  custody, and provider endpoint validation

### Profile / progression API
- persisted player preferences and schema migration
- classic WCA-style and alternate keyboard profiles with per-action remapping
- pointer/orbit/zoom, audio, graphics, accessibility, AI, STT, and TTS settings
- training history
- unlocked modules
- performance metrics

### Curriculum API
- guided lesson packets
- method ladders
- hyper-specific modules
- school or educational variants if later needed

## Deployment posture

Keep local computation local where sensible.
Do not server-centralize everything just because an HTTP interface can be drawn.
