# HyperTwist Phase 4 gameplay generated-mode selector option owned execution case-identity / canonical-state preview 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 selector option launch-request envelope / request-source preview surface by exposing one parameterized owned execution case-identity / canonical-state preview surface for a chosen selector id.

The open tasks were:

- stop forcing gameplay / Blueprint callers to rebuild generated-mode executor naming rules just to explain the resulting owned case target for a chosen imported option
- expose exact direct covered-case targets, exact stored-request-derived generated case ids, and refresh-template case / canonical-state previews on the chosen selector
- keep the surface derived from already-cached gameplay consumer run, selector, stored request, and launch-request envelope state instead of widening into backend logic

It is not:

- a selector-dispatch behavior change
- a generated-mode launch-request persistence behavior change
- a generated-mode execution deck synthesis change
- a broader gameplay UI composition pass

## Scope

Bounded lane:

- extend the launch-request envelope preview entry surface with the hypothetical deck / surface / runtime identity already derived by the underlying launch-request preview layer
- add first-party owned execution case preview surfaces in shared training types
- add a coach-library helper that projects owned case identity and canonical-state preview over the already-landed envelope preview surface
- expose that parameterized owned execution case preview surface on `HyperTwistTrainingPanelWidget` and `HyperTwistTrainingSessionActor`
- keep the derivation presentation-only and rooted in the already-owned selector/runtime/request surfaces

Out of scope:

- changing selector-choice apply behavior
- changing stored launch-request creation, refresh, or execute behavior
- changing generated-mode execution deck synthesis
- widening into dashboard-only or broader gameplay composition work

## Why this was the right next packet

Before this slice:

- gameplay-facing panel/session consumers already exposed truthful hypothetical payload, request reuse, refresh posture, metadata provenance, and stored envelope identity for imported selector options
- callers could tell whether a chosen option launched a covered case directly, reused a stored generated-mode request, or required request refresh

But one thin consumer seam was still open:

- callers still had to reconstruct executor case-id and canonical-state naming from request id, deck id, surface id, and runtime mode if they wanted to describe the resulting owned execution target

That meant:

- request and persistence posture were already thin and reusable
- but resulting owned execution target identity still leaked executor naming rules into callers

So the next bounded move was:

- keep the already-landed launch-request envelope preview surface unchanged in behavior
- reuse that cached identity to expose one narrow owned execution case / canonical-state preview surface above it

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
  - extended `FHyperTwistTrainingCoachGeneratedModeSelectorOptionLaunchRequestEnvelopePreviewEntrySurface` with hypothetical deck / surface / runtime identity
  - added `FHyperTwistTrainingCoachGeneratedModeSelectorOptionOwnedExecutionCasePreviewEntrySurface`
  - added `FHyperTwistTrainingCoachGeneratedModeSelectorOptionOwnedExecutionCasePreviewSurface`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingCoachLibrary.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingCoachLibrary.cpp`
  - added `DeriveCoachGeneratedModeSelectorOptionOwnedExecutionCasePreviewSurface(...)`
  - owned case preview is derived from cached run state plus the already-landed envelope preview surface
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingPanelWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPanelWidget.cpp`
  - added `GetDisplayedCoachGeneratedModeSelectorOptionOwnedExecutionCasePreviewSurface(const FString& SelectorId)`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSessionActor.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSessionActor.cpp`
  - added `GetDisplayedCoachGeneratedModeSelectorOptionOwnedExecutionCasePreviewSurface(const FString& SelectorId)`

Surface behavior:

- reports exact direct covered-case targets for selector options that dispatch straight to owned cases
- reports exact generated owned case ids and canonical-state refs when the chosen option reuses the current stored generated-mode request envelope
- reports deterministic refresh templates when the chosen option would require first-persist, refresh, or replace of the stored generated-mode request envelope
- keeps unresolved or payload-invalid choices inspectable as blocked preview states instead of collapsing them into a generic unavailable branch
- keeps the surface presentation-only and compatible with the already-landed launch / execution, request-alignment, stored-request delta, launch-request payload / refresh-preview, launch-request metadata / origin-notes preview, and launch-request envelope / request-source preview 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 generated-mode selector option owned execution prompt-label / prompt-kind preview surface so callers can render the resulting owned prompt presentation for a chosen option without rebuilding generated deck composition rules directly.
