# HyperTwist Virtual Training Environment And Scenic Immersion Scoping Note - 2026-05-31

## Status

This note now anchors five landed first-party HyperTwist milestones:
`Phase I-A`, `Phase I-B`, `Phase I-C`, `Phase I-D`, and `Phase I-E`.

This closes the first bounded immersive product scaffold in current code.

It is still not an unlimited immersive-expansion lane.

It is also intentionally separate from any `VectorShell` virtual-workspace or
virtual-desktop lane.

Current decision:

- HyperTwist should develop its virtual training environments on a clean slate
  as a HyperTwist-native training/runtime feature
- VectorShell should be treated as a separate product even if some low-level
  Unreal environment patterns later prove reusable
- no shared-feature assumption is required at the start

## Question answered

Should HyperTwist treat mountain, arena, ridge, observatory, or other scenic
immersive environments as:

- a generic virtual desktop background
- a VectorShell-derived workspace shell
- or a HyperTwist-native training/runtime layer

Answer:

- a HyperTwist-native training/runtime layer

## Why this has value for HyperTwist

The value is not "VR wallpaper."

The value is that a well-built environment can strengthen the actual training
loop.

Exact value to preserve:

1. Embodied focus
   HyperTwist can move long practice, replay, and review sessions out of a
   sterile abstract shell and into a place that supports concentration and
   rhythm.

2. Better orientation for difficult material
   Higher-dimensional puzzles, replay review, and guided drills benefit from a
   stronger sense of place, scale, and direction than a flat or void-only
   presentation.

3. Training-state legibility
   The environment can help communicate state changes such as warm-up,
   deliberate drill, solve review, mastery, error correction, or cooldown
   without relying only on UI chrome.

4. Coaching and tutorial staging
   Spatial coaching anchors, ghosted targets, highlighted puzzle volumes, and
   replay-positioned teaching cues become more natural when the user is in a
   coherent world rather than a detached menu shell.

5. Fatigue reduction and session endurance
   Carefully tuned scenic environments, ambient audio, and immersion controls
   can make long training blocks feel less claustrophobic and less cognitively
   stale.

6. Premium product identity
   HyperTwist should feel like a serious native training environment, not a
   web admin dashboard with puzzle art attached and not a generic VR gimmick.

## Non-goals

This future lane should not default into:

- a generic coding or productivity workspace
- a virtual-monitor or floating-desktop shell
- a direct clone of `visionOS`, `Immersed`, or `Virtual Desktop`
- a dependency on the broader ScriptoriumAI memory/coding-harness posture
- early shared-engine assumptions with `VectorShell`

If later engine-level sharing happens, it should be extracted after both
products prove their own needs independently.

## Planned HyperTwist posture

The right posture is:

- puzzle/training runtime first
- scenic environment second
- controls, coaching, and comfort integrated into the same runtime
- no confusion with a productivity workspace shell

That means the puzzle, replay, and coaching surfaces remain primary.

The environment exists to strengthen those surfaces, not replace them.

## Deferred implementation scaffold

### Phase `I-A` - scenic training environment foundations

Status:

- landed in current code as the first bounded immersive foundations slice

Build the first HyperTwist-native environment shell:

- one high-quality environment family such as alpine ridge, summit chamber,
  observatory, or focus arena
- day/night or mood-linked lighting presets
- ambient audio foundation
- stable world anchors for puzzle, replay, and coach surfaces

Landed contract/value surface:

- scenic environment profile with named environment families
- day, dusk, night, and focus-biased lighting preset boundary
- calm ambient-audio boundary for warm-up, drill, review, mastery, and cooldown
- stable puzzle, replay, coach, and orientation anchors

Success condition:

- HyperTwist no longer feels like a puzzle object in a void-only shell during
  immersive training sessions

### Phase `I-B` - immersion and focus-presence controls

Status:

- landed in current code as the second bounded immersive slice

Add user control over how present the environment feels:

- immersion intensity
- reduced-distraction presets
- comfort and vignette options
- seated/standing posture variants
- session-local environment recall

Landed contract/value surface:

- immersion intensity ladder
- reduced-distraction scenic presets
- comfort and vignette boundary
- seated/standing posture variants
- session-local environment recall boundary

Success condition:

- users can tune the environment for either calm focus or stronger spatial
  presence without destabilizing the training flow

### Phase `I-C` - spatial coaching and tutorial staging

Status:

- landed in current code as the third bounded immersive slice

Add training-native environmental interaction:

- coach cue anchors
- ghosted target positions
- replay path emphasis
- drill-target spotlighting
- lesson-specific environmental states

Landed contract/value surface:

- coach cue anchor contract
- ghost-target boundary
- replay-emphasis boundary
- lesson-state spotlighting contract

Success condition:

- environment and coaching become one integrated teaching surface instead of
  two unrelated layers

### Phase `I-D` - reactive session-state environment cues

Status:

- landed in current code as the fourth bounded immersive slice

Make the environment respond carefully to session state:

- subtle transitions for review, mastery, correction, or failure states
- pacing-aware audio or lighting shifts
- challenge-mode versus study-mode differentiation

Landed contract/value surface:

- session-state cue contract
- lighting-reaction boundary
- audio-pacing boundary
- mode-differentiation contract

Success condition:

- environmental feedback deepens comprehension without becoming theatrical or
  distracting

### Phase `I-E` - comfort, accessibility, and performance hardening

Status:

- landed in current code as the fifth bounded immersive slice

Finalize the lane as a real product surface:

- comfort-safe transitions
- legibility and contrast review
- performance budgets
- fallback modes
- accessibility-safe reduced-effects path

Landed contract/value surface:

- transition-safety boundary
- accessibility-legibility contract
- performance-budget boundary
- fallback-mode contract

Success condition:

- the environment system is robust enough for regular training use, not only
  showcase demos

## Architecture guardrails

- keep this Unreal-native
- keep the puzzle/training runtime authoritative
- treat environment state as session-aware but bounded
- prefer world-anchored puzzle/coaching surfaces over generic floating
  dashboard clutter
- do not reopen donor-driven retained rows solely to justify this lane
- do not describe this as current product truth until first-party runtime
  evidence exists

## Relation to VectorShell

VectorShell may eventually build its own immersive workspace and scenic shell.

That does not make VectorShell the correct incubation home for this HyperTwist
feature.

HyperTwist should first solve:

- training atmosphere
- embodied puzzle focus
- spatial coaching
- hypercube and puzzle-scene legibility

VectorShell, separately, would solve:

- spatial coding workspace
- hybrid 2D plus graph/code panes
- productivity and analysis shell behavior

The products may later share some low-level Unreal environment utilities, but
they should not begin from a forced shared feature assumption.
