# HyperTwist Phase 4 gameplay generated-mode selector option launch-request envelope / request-source 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 metadata / origin-notes preview surface by exposing one parameterized option launch-request envelope / request-source preview surface for a chosen selector id.

The open tasks were:

- stop forcing gameplay / Blueprint callers to read raw stored launch-request envelope fields just to explain request reuse, refresh, or first-persist posture for a chosen imported option
- expose request id, request source, requested-at timestamp, and reuse-vs-refresh persistence context for each imported option on the chosen selector
- keep the surface derived from already-cached gameplay consumer run, selector, stored request, and launch-request preview state instead of widening into backend logic

It is not:

- a selector-dispatch behavior change
- a stored launch-request persistence behavior change
- a generated-mode executor behavior change
- a broader gameplay UI composition pass

## Scope

Bounded lane:

- add first-party generated-mode selector option launch-request envelope / request-source preview surfaces in shared training types
- add a coach-library helper that projects stored request id, requested-at timestamp, request source, and persistence posture over the already-landed launch-request preview surface
- expose that parameterized envelope 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, metadata provenance, and refresh posture for imported selector options
- those same consumers already exposed truthful request-alignment and stored-request delta posture

But one thin consumer seam was still open:

- callers could tell whether a chosen option reused the stored request or required refresh
- but they still had to read raw stored launch-request envelope fields to explain which request id, timestamp, and source would stay in play or be replaced

That meant:

- launch payload and persistence posture were thin and reusable
- but stored envelope identity still leaked raw request-envelope access into callers

So the next bounded move was:

- keep the already-landed payload / refresh-preview and metadata / origin-notes preview surfaces unchanged
- and expose one narrow stored launch-request envelope / request-source preview surface above those cached launch-request semantics

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
  - added `FHyperTwistTrainingCoachGeneratedModeSelectorOptionLaunchRequestEnvelopePreviewEntrySurface`
  - added `FHyperTwistTrainingCoachGeneratedModeSelectorOptionLaunchRequestEnvelopePreviewSurface`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingCoachLibrary.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingCoachLibrary.cpp`
  - added `DeriveCoachGeneratedModeSelectorOptionLaunchRequestEnvelopePreviewSurface(...)`
  - envelope preview is derived from cached run state plus the already-landed launch-request preview surface and stored request envelope fields
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingPanelWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPanelWidget.cpp`
  - added `GetDisplayedCoachGeneratedModeSelectorOptionLaunchRequestEnvelopePreviewSurface(const FString& SelectorId)`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSessionActor.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSessionActor.cpp`
  - added `GetDisplayedCoachGeneratedModeSelectorOptionLaunchRequestEnvelopePreviewSurface(const FString& SelectorId)`

Surface behavior:

- reports the current stored request envelope for each imported option on the chosen selector, including request id, requested-at timestamp, and request source when one already exists
- distinguishes reuse, first-persist, refresh-existing, replace-stored, blocked, direct-launch, and unavailable persistence posture without forcing callers to infer it from raw request-envelope state
- projects the execute-time request source used when a fresh stored request would be created or refreshed
- keeps blocked unresolved/payload-unavailable options inspectable instead of collapsing envelope state to an unhelpful 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, and launch-request metadata / origin-notes 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 case-identity / canonical-state preview surface so callers can render the resulting generated case id and canonical-state ref for a chosen option without rebuilding executor naming rules directly.
