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

The open tasks were:

- stop forcing gameplay / Blueprint callers to read raw generated-mode launch-config metadata just to render imported provenance over a hypothetical payload
- expose imported origin-path and notes provenance for each imported option on the chosen selector while preserving the already-landed payload / refresh-preview posture
- keep the surface derived from already-cached gameplay consumer run, selector, runtime-surface, and launch-request preview state instead of widening into backend logic

It is not:

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

## Scope

Bounded lane:

- add first-party generated-mode selector option launch-request metadata / origin-notes preview surfaces in shared training types
- add a coach-library helper that projects imported runtime-surface origin paths and notes over the already-landed hypothetical launch-request preview posture
- expose that parameterized metadata 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 generated-mode launch-config composition
- changing stored launch-request creation, refresh, or execute behavior
- 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 identity, selector payload, stored-request reuse posture, and refresh preview
- those same consumers already exposed truthful request-alignment and stored-request delta posture

But one thin consumer seam was still open:

- callers could explain what hypothetical payload would be staged
- but they still had to reach into raw launch-config metadata to render imported origin paths and notes over that payload

That meant:

- payload preview posture was thin and reusable
- but metadata provenance still leaked raw launch-config field access into callers

So the next bounded move was:

- keep the already-landed payload / refresh-preview surface unchanged
- and expose one narrow metadata / origin-notes projection above that cached launch-request preview

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
  - added `FHyperTwistTrainingCoachGeneratedModeSelectorOptionLaunchRequestMetadataPreviewEntrySurface`
  - added `FHyperTwistTrainingCoachGeneratedModeSelectorOptionLaunchRequestMetadataPreviewSurface`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingCoachLibrary.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingCoachLibrary.cpp`
  - added `DeriveCoachGeneratedModeSelectorOptionLaunchRequestMetadataPreviewSurface(...)`
  - metadata preview is derived from cached run state plus the already-landed launch-request preview surface and imported runtime-surface metadata
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingPanelWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPanelWidget.cpp`
  - added `GetDisplayedCoachGeneratedModeSelectorOptionLaunchRequestMetadataPreviewSurface(const FString& SelectorId)`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSessionActor.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSessionActor.cpp`
  - added `GetDisplayedCoachGeneratedModeSelectorOptionLaunchRequestMetadataPreviewSurface(const FString& SelectorId)`

Surface behavior:

- reports imported origin-path and notes provenance for each imported option on the chosen selector over the already-landed hypothetical payload posture
- keeps direct owned-case launch explicitly outside generated-mode launch-request metadata preview instead of pretending that generated-mode provenance still applies
- keeps unavailable options explicitly unavailable instead of forcing callers to infer metadata status from raw launch-request preview kinds
- reports a compact current-selection metadata preview for the chosen selector without requiring callers to read raw launch-config metadata arrays or notes strings
- keeps the surface presentation-only and compatible with the already-landed generated-mode launch / execution, request-alignment, stored-request delta, and payload / refresh-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 stored launch-request envelope / request-source preview surface so callers can render request id, request source, requested-at timestamp, and reuse-vs-refresh persistence context for a chosen option without reading raw launch-request envelope fields directly.
