# HyperTwist - PRD.md

## Product definition

HyperTwist is a native cube and hypercube training environment that combines:

- physical recognition and reconstruction
- replay and explanation
- training/coaching orchestration
- hyper puzzle simulation
- publication/social training surfaces
- bounded voice/speech sidecars

## Canonical discovery surfaces

Use these before expanding or describing product truth:

- `FEATURE_REGISTRY.md` for normalized feature extraction and confidence tiers
- `ROADMAP.md` for current sequencing truth
- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` for
  current landed runtime anchors
- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md`
  for memory lane taxonomy and sequencing
- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md`
  for provider-neutral/BYOK rules
- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md`
  for skill-layer rollout

## Current product-state truth

The current product must be described carefully.

HyperTwist already has real first-party owned implementation, but later
manual/marketing work must distinguish:

- implemented now
- deep-source grounded retained capability
- shallow placeholder capability

The canonical normalized surface for that distinction is:

- `FEATURE_REGISTRY.md`

Do not infer product truth from donor presence, queue position, or prompt-pack
presence.

## Website and simulator boundary

HyperTwist keeps both of these because they solve different product problems:

- the website owns public pages, account/auth, pricing, release posture,
  notices, and desktop pairing
- the desktop Unreal runtime owns the real simulator, packaged training flow,
  device/runtime integration, and higher-dimensional interaction

The website is therefore not superfluous, but it is intentionally inferior for
the core simulator job. Public and manual wording must keep that distinction
explicit.

Concrete interpretation rule:

- the browser version is for public docs, pricing, release posture, notices,
  support-safe onboarding, protected account state, and browser-to-desktop
  handoff
- the browser version is not the place to overclaim package-validated
  training behavior, higher-dimensional packaged execution, low-latency native
  input authority, or finished XR/controller runtime ownership
- the downloadable remains the materially more powerful product surface because
  it owns the simulator itself, the higher-dimensional family maps, packaged
  proof, and the current serious training workflows

The current first-party website also doubles as a bounded public-facing
operator manual:

- homepage and about explain the browser-versus-desktop split
- docs and resources explain rollout-safe product truth and simulator-use
  guidance
- pricing, download, and notices surfaces explain entitlement, package proof,
  and public distribution posture

## Users

- beginners learning 3D solving
- intermediate and advanced cubers
- hypercubers
- educators
- content creators
- self-directed AI-assisted learners

## Core problems solved

- weak solve analysis in existing tools
- separation between physical practice and virtual analysis
- insufficient support for higher-dimensional practice
- fragmented training, timing, recognition, replay, and coaching flows

## Core feature families

- physical cube recognition and reconstruction
- replay and state explanation
- algorithm/drill training and session control
- coaching/progression
- hyper puzzle catalog/topology/runtime
- public website/account/distribution surfaces
- deferred immersive training environments and focus-presence shells
- publication/challenge/social training surfaces
- analytics/reporting and provenance
- browser account, pricing, download, and legal distribution surfaces
- bounded speech/voice sidecars

## Deferred first-party experiential lane

HyperTwist now has one explicit deferred experiential milestone:

- scenic virtual training environments and focus-presence shells

Important interpretation rule:

- this is planned HyperTwist-native product direction
- it is not current shipped capability
- it is not a generic virtual desktop/workspace shell
- it is separate from any future `VectorShell` immersive workspace lane

Canonical scoping note:

- `C:\HyperTwist\docs\HYPERTWIST_VIRTUAL_TRAINING_ENVIRONMENT_AND_SCENIC_IMMERSION_SCOPING_NOTE_2026-05-31.md`

## Current Unreal input and XR truth

The current desktop runtime has first-party player-facing input and preference
ownership for classic and higher-dimensional keyboard/mouse play. Controls are
persisted and remappable; pointer, orbit, zoom, inversion, touch, audio,
graphics, accessibility, AI, STT, and TTS settings are exposed through the
native Settings surface. HyperTwist should still not claim fully proven
shipping VR/controller behavior until live headset-session and controller-input
observation is complete.

The latest native/operator truth follow-up on `2026-06-28` also tightened the
higher-dimensional side of that statement: native control-input readiness now
proves shipped `Magic120Cell` and `MagicCube5D` host, view-context, session,
and interactive-scene ownership explicitly by activation profile id instead of
only implying readiness from broad runtime-catalog validity.

The adjacent native control-settings ownership seam was tightened the same day
too: operator-facing settings truth now proves dedicated-family session,
interactive-scene, persistence-boundary, and state-semantics ownership
explicitly for both `Magic120Cell` and `MagicCube5D` instead of leaving that
family-owned runtime state hidden behind generic view-settings wording.

The next adjacent non-`XR` preferences-continuity follow-up first tightened the
same native/operator truth without reopening the controller lane. The later
Release 19 player-experience repair then closed the desktop-facing gap with a
real persisted preference schema, selectable keyboard profiles,
conflict-checked per-action rebinding, runtime application, and dedicated
Controls, Audio, Graphics, Accessibility, and Speech & Coach pages.

The same-family truth pass also carried that bounded continuity and active
scene ownership into the native control-profile roster seam, so the selectable
roster truth now stays aligned with the sibling control-settings and active
runtime surfaces instead of leaving those facts implied.

The next same-family `2026-07-01` follow-up then moved the XR side of that
statement forward too without overclaiming launch-tier completion:

- the desktop-hosted branch now enables `OpenXR` plus `XRBase`
- first-party bounded runtime-owner/profile ownership now exists through:
  - `xr/openxr-desktop-training-runtime-owner`
  - `xr-openxr-training-preferences/v1`
  - `xr-openxr-motion-controllers/v1`
- a dedicated `AHyperTwistXrTrainingPawn` now owns bounded camera/controller
  anchors, posture switching, recentering, bounded manual vertical-adjust
  ownership, sanitized preference application, and desktop fallback pitch
  handling that now clears stale fallback rotation when a headset becomes
  active
- the maintained Windows validation lane then re-proved the exact-source state
  with:
  - editor build `Result: Succeeded`, UnrealBuildTool `Total execution time:
    3672.35 seconds`
  - focused XR automation
    `XR-BoundedRuntimeOwner-Hardening-20260701`: `4/4` green
  - full browser automation `Browser-XrHardening-20260701`: `26/26`
    `HyperTwist.Browser.*` green

That is real bounded runtime ownership, and the current same-family
controller-settings continuation now also owns first-party user-facing
controller settings, layout presets, and rebinding truth for the exact shipped
XR input ids. But it is still not the same thing as packaged
headset/controller proof or generic marketed VR completion.

The current launch-UX truth on `2026-07-02` should be stated the same way on
public pages, manuals, and operator closeouts:

- keyboard and mouse development is viable now because the desktop runtime owns
  shipped classic keyboard, pointer, orbit, zoom, and higher-dimensional
  interaction surfaces
- the native boot path now has a first-party code-owned first-run launch menu
  through `AHyperTwistFirstRunLaunchGameMode`,
  `AHyperTwistFirstRunLaunchPlayerController`,
  `UHyperTwistFirstRunLaunchWidget`, and
  `UHyperTwistFirstRunLaunchLibrary`; that menu routes explicitly to Coach
  Settings, Learning Studio, Classic Cube, dedicated 4D orders `2` through `6`,
  `Magic120Cell`, `MagicCube5D`, and the bounded OpenXR validation path instead
  of dropping new users into an unexplained operator-only surface
- the common native player controller owns reliable pause, back, main-menu, and
  desktop-exit behavior plus a fixed `F3` in-game coach; the coach remains
  useful offline and can optionally use separately configured AI, global STT,
  and asynchronous TTS without making an API key a play prerequisite
- bounded XR runtime, controller-settings, layout, and rebinding ownership are
  real first-party seams, but live headset-connected and controller-input
  observation remain the proof gates before marketing finished VR completion
- the new first-run menu is a code-owned launch and truth surface, not a claim
  of completed visual art direction, production entitlement configuration, or
  physical headset/controller proof; rollout copy must still keep
  first-launch verification, pairing, and settings truth visible
- the same first-run source state was then revalidated through the maintained
  reverse-SSH Windows lane at `C:\HyperTwist_worktrees\phase10validate` with
  `UnrealHyperTwistEditor` build `Result: Succeeded`, UnrealBuildTool total
  execution `52.97` seconds, and focused automation report
  `FirstRunLaunchSurface-20260702` showing `3` succeeded, `0` failed, `0`
  not-run, and `0` in-process tests for `HyperTwist.FirstRun`
- Release 19 then closed the combined package gate: the post-repair UE 5.7
  editor build passed, `HyperTwist.PlayerExperience` passed `5/5`, all `9`
  native route smokes passed, staged browser and solver assets hash-matched,
  the `167`-entry ZIP reopened cleanly, and both the validation-archive and
  exact Downloads executables produced fresh semantic
  `launch-menu-renderable` frames
- the `2026-07-26` installer continuation then closed per-machine Windows
  installation, readiness, in-place upgrade, and uninstall ownership above
  that exact Release 19 payload: the final installer carries a complete
  `143`-file SHA-256 manifest, bundles a valid Microsoft-signed Visual C++
  runtime, refuses unsafe or unowned non-empty targets, preserves user data,
  and passed install-to-uninstall lifecycle validation from a path containing
  spaces; this remains isolated-current-host evidence rather than a fabricated
  fresh-machine or trusted-code-signing claim
- Paddle checkout URLs, public Windows release URLs, production auth/runtime
  configuration, and corresponding-source/notices URLs remain deployment
  configuration gates, not hardcoded product facts
- the website remains useful because it owns public docs, account, pricing,
  notices, release posture, support, and protected download handoff; it should
  not be described as simulator parity with the downloadable

Canonical audit note:

- `C:\HyperTwist\docs\ops\HYPERTWIST_UNREAL_INPUT_AND_XR_COMPLETENESS_AUDIT_2026-06-22.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_NATIVE_XR_HOST_AND_PLUGIN_DECISION_PACKET_2026-06-24.md`

## Product guardrails

- packet docs and live code beat summaries when conflicts exist
- provider-specific donor patterns must not define the top-level provider
  contract
- compacted or assistive-transformed outputs must remain derived, not
  authoritative
- skills must remain optional assistive layers, not mandatory product truth

## Success criteria

- users measurably improve faster
- higher-dimensional users take the platform seriously
- physical and virtual practice reinforce each other
- the product feels native, rigorous, and coherent
