# HyperTwist Phase 4 gameplay generated-mode selector roster / option-availability surface packet

Created on `2026-05-08`

Status:

- first-party HyperTwist packet
- bounded Phase `4` gameplay-facing consumer slice

## Purpose

This packet closes the next thin gameplay-facing consumer seam above the panel-widget and session-actor generated-mode helpers by exposing one pure selector-roster / option-availability surface over the active imported runtime surface and cached selector-choice state.

The open tasks were:

- stop forcing gameplay / Blueprint callers to read raw imported runtime selector arrays just to list active selectors, bindings, selected values, and unresolved selector coverage
- stop forcing those same callers to inspect raw option payloads just to tell whether unresolved selectors still expose imported options
- keep the surface derived from already-cached gameplay consumer state instead of widening into selector-application behavior or new runtime fetches

It is not:

- a selector option-menu UI packet
- a new selector-application behavior packet
- a generated-mode execution packet
- a broader gameplay HUD composition pass

## Scope

Bounded lane:

- add first-party generated-mode selector-roster surfaces in shared training types
- add a coach-library helper that derives the roster from the active deck imported runtime surface, cached imported selection state, and the already-landed selector / application context surface
- expose that derived roster surface on `HyperTwistTrainingPanelWidget` and `HyperTwistTrainingSessionActor`
- keep the derivation presentation-only and rooted in already-cached gameplay consumer state

Out of scope:

- changing selector-choice persistence
- changing generated-mode launch-config derivation rules
- changing selector-option application behavior
- widening into parameterized selector option-menu/detail surfaces yet

## Why this was the right next packet

Before this slice:

- gameplay-facing panel/session consumers already exposed truthful generated-mode launch / execution context
- those same consumers already exposed truthful selector / application context

But one thin consumer seam was still open:

- callers could tell whether selector application was complete
- but they still had to read raw runtime selectors and option payloads to explain which selectors were active, which bindings they mapped to, what was already selected, and whether unresolved selectors still exposed imported options

That meant:

- selector-application posture was thin and reusable
- but selector roster and option-availability detail still leaked raw imported payloads into callers

So the next bounded move was:

- keep the already-landed launch / execution and selector / application context surfaces unchanged
- and expose one narrow selector-roster / option-availability surface above the cached selector state

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
  - added `FHyperTwistTrainingCoachGeneratedModeSelectorRosterEntrySurface`
  - added `FHyperTwistTrainingCoachGeneratedModeSelectorRosterSurface`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingCoachLibrary.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingCoachLibrary.cpp`
  - added `DeriveCoachGeneratedModeSelectorRosterSurface(...)`
  - roster is derived from the active imported runtime surface, cached imported selection state, and the already-landed selector / application context surface
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingPanelWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPanelWidget.cpp`
  - added `GetDisplayedCoachGeneratedModeSelectorRosterSurface()`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSessionActor.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSessionActor.cpp`
  - added `GetDisplayedCoachGeneratedModeSelectorRosterSurface()`

Surface behavior:

- reports whether a generated-mode selector roster is currently active
- exposes one entry per structurally valid imported selector with selector id, label, binding label, selected value/display value, and imported-option availability
- reports aggregate selector coverage, unresolved selector count, unresolved selectors with imported options, and a short unresolved-selector preview line
- keeps the surface presentation-only and compatible with the already-landed generated-mode context surfaces

## Validation

Validation target:

- full `Development Editor|Win64` build of `C:\HyperTwist\UnrealHyperTwist\UnrealHyperTwist.sln`

Result:

- passed with `0` warnings and `0` errors

## Follow-on

The next bounded packet on this same gameplay-facing consumer lane should stay thin and expose one parameterized generated-mode selector option-menu / detail surface so callers can render normalized option ids, labels, and unresolved-selection detail for a chosen selector without reading raw imported option payloads directly.
