Phase 0: Infrastructure + all 23 donor repo submodules

- Add .external/ and ThirdParty/ directories - Update UnrealHyperTwist.Build.cs with external include paths + Voice module - Add WebBrowser plugin to .uproject - Add .gitmodules with 23 donor repos: - C++ solvers: rob-twophase, glTF-Sample-Renderer, glTF-Sample-Viewer - Speech: piper - Browser spatial: three.js stack (drei, postprocessing, react-postprocessing, react-spring, three-stdlib, maath, zustand, leva, use-gesture, uikit) - Analytics: zrender, echarts-gl - Model viewer: model-viewer - ClayGL: claygl, clay-viewer - Code VR: code-vr - Solvers (IPC): rubiks-cube-solver, rubix-solver, Rubiks-Cube-Solver - Comprehensive reconstruction roadmap - Unwired repo inventory and wiring schedule Next: actual code implementation (solver wrappers, speech pipeline, renderer)
2026-06-10 04:10:20 +00:00 · 2026-06-10 04:10:20 +00:00 · c4e4606d14
commit c4e4606d14
parent 9380ef82a5
27 changed files with 690 additions and 1 deletions
--- a/.external/clay-viewer
+++ b/.external/clay-viewer
@ -0,0 +1 @@
+Subproject commit 86456edc4b28494e5facbe75fc4f009fe8cf3f3e
--- a/.external/claygl
+++ b/.external/claygl
@ -0,0 +1 @@
+Subproject commit 5e3066734fcc6fdb333978c76baefc0b69c258c5
--- a/.external/code-vr
+++ b/.external/code-vr
@ -0,0 +1 @@
+Subproject commit 23204c26cc42cfda1de9705ab34649bd394cc168
--- a/.external/drei
+++ b/.external/drei
@ -0,0 +1 @@
+Subproject commit c9d3d0dc9473f026c83965a7eb8c7f7a1a1bf0ae
--- a/.external/echarts-gl
+++ b/.external/echarts-gl
@ -0,0 +1 @@
+Subproject commit 2bd401e7ca5e10cdfd96643c9b646fd7ee6ca04b
--- a/.external/glTF-Sample-Renderer
+++ b/.external/glTF-Sample-Renderer
@ -0,0 +1 @@
+Subproject commit bec106e53da4a6a398aa3205f0f96563519a657e
--- a/.external/glTF-Sample-Viewer
+++ b/.external/glTF-Sample-Viewer
@ -0,0 +1 @@
+Subproject commit 6b4012c8cd58f933565401fbe4404a40380ee0fb
--- a/.external/leva
+++ b/.external/leva
@ -0,0 +1 @@
+Subproject commit 402a1e9d0899e6d384993aaffe8dc0d2c39110e1
--- a/.external/maath
+++ b/.external/maath
@ -0,0 +1 @@
+Subproject commit 626d198fbae28ba82f2f1b184db7fcafd4d23846
--- a/.external/model-viewer
+++ b/.external/model-viewer
@ -0,0 +1 @@
+Subproject commit 35f94667db54d997264930f5cff1661eb969505d
--- a/.external/piper
+++ b/.external/piper
@ -0,0 +1 @@
+Subproject commit 73c04d81d5590ecc46e522de3601ce7fb29fc2be
--- a/.external/postprocessing
+++ b/.external/postprocessing
@ -0,0 +1 @@
+Subproject commit a0dce6d96e5c839b0e7ff420b3124bc0742027fe
--- a/.external/react-postprocessing
+++ b/.external/react-postprocessing
@ -0,0 +1 @@
+Subproject commit 90d10d59fe5a1a86e027c1bedd36dcf3b87ddd1c
--- a/.external/react-spring
+++ b/.external/react-spring
@ -0,0 +1 @@
+Subproject commit 4eed7260ae526411eaf68b81074ac69081a7f475
--- a/.external/rob-twophase
+++ b/.external/rob-twophase
@ -0,0 +1 @@
+Subproject commit d245031257d52b2663c5790c5410ef30aefd775f
--- a/.external/rubiks-cube-solver
+++ b/.external/rubiks-cube-solver
@ -0,0 +1 @@
+Subproject commit 6f53f57d836a1604f8e5b7829d9e220466574b80
--- a/.external/rubix-solver
+++ b/.external/rubix-solver
@ -0,0 +1 @@
+Subproject commit d5b9c6d87771f83a48a4c73fd6f79bfe2f4289a4
--- a/.external/three-stdlib
+++ b/.external/three-stdlib
@ -0,0 +1 @@
+Subproject commit 13ecb8c219a83e6975c9e6a0ebaa97e651116b4f
--- a/.external/uikit
+++ b/.external/uikit
@ -0,0 +1 @@
+Subproject commit 3f7c958613a007f20d36b0c5bdafb6ce3e2a593a
--- a/.external/use-gesture
+++ b/.external/use-gesture
@ -0,0 +1 @@
+Subproject commit c779631aa05959638dee81b9a25fb1299a7467f6
--- a/.external/zrender
+++ b/.external/zrender
@ -0,0 +1 @@
+Subproject commit 349111033fba0fa08cee745b72dd2ea66dc6fcaa
--- a/.external/zustand
+++ b/.external/zustand
@ -0,0 +1 @@
+Subproject commit 566b5bf448f4354eb8e35c6243ea3772bdb3be96
--- a/.gitmodules
+++ b/.gitmodules
@ -0,0 +1,69 @@
+[submodule ".external/rob-twophase"]
+	path = .external/rob-twophase
+	url = https://github.com/efrantar/rob-twophase.git
+[submodule ".external/piper"]
+	path = .external/piper
+	url = https://github.com/rhasspy/piper.git
+[submodule ".external/glTF-Sample-Renderer"]
+	path = .external/glTF-Sample-Renderer
+	url = https://github.com/KhronosGroup/glTF-Sample-Renderer.git
+[submodule ".external/rubiks-cube-solver"]
+	path = .external/rubiks-cube-solver
+	url = https://github.com/cahidenes/rubiks-cube-solver.git
+[submodule ".external/rubix-solver"]
+	path = .external/rubix-solver
+	url = https://github.com/tentone/rubix-solver.git
+[submodule ".external/code-vr"]
+	path = .external/code-vr
+	url = https://github.com/NuiLab/code-vr.git
+[submodule ".external/claygl"]
+	path = .external/claygl
+	url = https://github.com/pissang/claygl.git
+[submodule ".external/clay-viewer"]
+	path = .external/clay-viewer
+	url = https://github.com/pissang/clay-viewer.git
+[submodule ".external/postprocessing"]
+	path = .external/postprocessing
+	url = https://github.com/pmndrs/postprocessing.git
+[submodule ".external/react-postprocessing"]
+	path = .external/react-postprocessing
+	url = https://github.com/pmndrs/react-postprocessing.git
+[submodule ".external/drei"]
+	path = .external/drei
+	url = https://github.com/pmndrs/drei.git
+[submodule ".external/uikit"]
+	path = .external/uikit
+	url = https://github.com/pmndrs/uikit.git
+[submodule ".external/three-stdlib"]
+	path = .external/three-stdlib
+	url = https://github.com/pmndrs/three-stdlib.git
+[submodule ".external/maath"]
+	path = .external/maath
+	url = https://github.com/pmndrs/maath.git
+[submodule ".external/zustand"]
+	path = .external/zustand
+	url = https://github.com/pmndrs/zustand.git
+[submodule ".external/leva"]
+	path = .external/leva
+	url = https://github.com/pmndrs/leva.git
+[submodule ".external/use-gesture"]
+	path = .external/use-gesture
+	url = https://github.com/pmndrs/use-gesture.git
+[submodule ".external/react-spring"]
+	path = .external/react-spring
+	url = https://github.com/pmndrs/react-spring.git
+[submodule ".external/zrender"]
+	path = .external/zrender
+	url = https://github.com/ecomfe/zrender.git
+[submodule ".external/echarts-gl"]
+	path = .external/echarts-gl
+	url = https://github.com/ecomfe/echarts-gl.git
+[submodule ".external/glTF-Sample-Viewer"]
+	path = .external/glTF-Sample-Viewer
+	url = https://github.com/KhronosGroup/glTF-Sample-Viewer.git
+[submodule ".external/model-viewer"]
+	path = .external/model-viewer
+	url = https://github.com/google/model-viewer.git
+[submodule ".external/Rubiks-Cube-Solver"]
+	path = .external/Rubiks-Cube-Solver
+	url = https://github.com/brownan/Rubiks-Cube-Solver.git
--- a/UnrealHyperTwist/Source/UnrealHyperTwist/UnrealHyperTwist.Build.cs
+++ b/UnrealHyperTwist/Source/UnrealHyperTwist/UnrealHyperTwist.Build.cs
@ -8,10 +8,24 @@ public class UnrealHyperTwist : ModuleRules
 	{
 		PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
 	
-		PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput", "Json", "JsonUtilities", "UMG" });
+		PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput", "Json", "JsonUtilities", "UMG", "Voice" });

 		PrivateDependencyModuleNames.AddRange(new string[] { "Slate", "SlateCore", "HTTP" });

+		// External donor repo include paths
+		string ExternalPath = Path.Combine(ModuleDirectory, "../../../.external/");
+		string ThirdPartyPath = Path.Combine(ModuleDirectory, "../../../ThirdParty/");
+
+		if (Directory.Exists(ExternalPath))
+		{
+			PublicIncludePaths.Add(ExternalPath);
+		}
+
+		if (Directory.Exists(ThirdPartyPath))
+		{
+			PublicIncludePaths.Add(ThirdPartyPath);
+		}
+
 		// Uncomment if you are using Slate UI
 		// PrivateDependencyModuleNames.AddRange(new string[] { "Slate", "SlateCore" });
 		
--- a/UnrealHyperTwist/UnrealHyperTwist.uproject
+++ b/UnrealHyperTwist/UnrealHyperTwist.uproject
@ -21,6 +21,10 @@
 		{
 			"Name": "RemoteControl",
 			"Enabled": true
+		},
+		{
+			"Name": "WebBrowser",
+			"Enabled": true
 		}
 	]
 }
--- a/docs/ops/HYPERTWIST_COMPREHENSIVE_RECONSTRUCTION_ROADMAP_2026-06-10.md
+++ b/docs/ops/HYPERTWIST_COMPREHENSIVE_RECONSTRUCTION_ROADMAP_2026-06-10.md
@ -0,0 +1,417 @@
+# HyperTwist — Comprehensive Reconstruction Roadmap
+## Status: Draft — Post-Audit Reality Alignment
+## Date: 2026-06-10
+
+## Remaining Repo Inventory (Authoritative Reconstruction)
+
+Source: `HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md` and `HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md`
+
+**Within the original 71-row shallow-eval set:**
+
+| Category | Count |
+|----------|-------|
+| Implemented/live (all licenses) | 29 |
+| **Selected, not live (permissive candidates)** | **29** |
+| Reference / benchmark / discard | 13 |
+| **Total non-live** | **42** |
+
+**Outside the 71-row set:**
+
+| Category | Count | Repos |
+|----------|-------|-------|
+| Speech rows (landed as attribution only) | 4 | `ggml-org/whisper.cpp`, `rhasspy/piper`, `SYSTRAN/faster-whisper`, `coqui-ai/TTS` |
+
+**The 29 selected-not-live permissive candidates include:**
+- `cahidenes/rubiks-cube-solver`
+- `tentone/rubix-solver`
+- `NuiLab/code-vr`
+- `pissang/claygl`
+- `pissang/clay-viewer`
+- `pmndrs/postprocessing`, `pmndrs/react-postprocessing`, `pmndrs/drei`, `pmndrs/react-spring`, `@react-spring/*`, `pmndrs/three-stdlib`, `pmndrs/maath`, `pmndrs/uikit`, `pmndrs/zustand`, `pmndrs/leva`, `pmndrs/use-gesture`
+- `ecomfe/zrender`, `ecomfe/echarts-gl`
+- `KhronosGroup/glTF-Sample-Viewer`, `KhronosGroup/glTF-Sample-Renderer`
+- `google/model-viewer/packages/*` (sub-packages)
+- And others in the 0R-B backlog
+
+**None of these 29 are currently wired into the Unreal build.** They exist only as attribution bundles and JSONL reference pages.
+
+---
+
+---
+
+## Executive Summary
+
+This roadmap replaces the self-referential validation-ladder sequence with a
+functional, repo-first reconstruction plan. The audit confirms that HyperTwist
+is ~80% documentation scaffolding, ~15% data-structure code, and ~5% actual
+game logic. No 3D puzzle renderer exists. No playable level exists. No donor
+repos are wired into the build.
+
+**The new rule:** Repos are wired before features are claimed. Features are
+playable before they are documented. Validation tests verify behavior, not
+structural metadata.
+
+---
+
+## Phase 0: Foundation — Build Infrastructure for Repo Wiring
+
+**Goal:** Enable actual donor code to be compiled, linked, and shipped.
+
+**Deliverables:**
+- [ ] Create `.external/` directory with `CMakeLists.txt` wrapper for UE5 plugin-style builds
+- [ ] Create `ThirdParty/` directory for header-only and prebuilt libraries
+- [ ] Add `.gitmodules` for the first wave of C++ donor repos
+- [ ] Add `Build.cs` rules in `UnrealHyperTwist.Build.cs` for `PublicIncludePaths` and `PublicAdditionalLibraries`
+- [ ] Windows build validation after each sub-step (prove the linker sees donor symbols)
+
+**Estimated actions:** ~15 build actions per sub-step
+**Estimated time:** 2–3 hours per sub-step (infrastructure compiles fast)
+
+---
+
+## Phase 1: Wire All Donor Repos (Repo-First Constraint)
+
+**Principle:** Repos are wired into the build BEFORE any feature claims them.
+See `HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md`
+for the full 29-repo queue and per-repo wiring posture.
+
+### 1A — Solver Backend: `efrantar/rob-twophase`
+- [ ] Add submodule `mirrors/rob-twophase`
+- [ ] Write UE `Build.cs` rules linking `libtwophase` or object files
+- [ ] Expose `UHyperTwistSolverLibrary::SolveClassicState(FString KociembaState)` → `TArray<FString> MoveSequence`
+- [ ] Automation test: feed a known scrambled state, assert solution length < 25
+
+### 1B — Speech-to-Text: `freestyle-voice/freestyle` (MIT)
+- [ ] Decision gate: `freestyle` is a hotkey-driven dictation client, not an embeddable C++ library. It calls cloud APIs (OpenAI, Groq, Anthropic, Google, Deepgram, ElevenLabs) via HTTP.
+- [ ] Integration path A (recommended): Run `freestyle` as external sidecar process. UE communicates via local HTTP loopback or IPC.
+- [ ] Integration path B (fallback): Embed `freestyle` source (Tauri/Rust or Electron) as a UE plugin — evaluate complexity vs. value.
+- [ ] Expose `UHyperTwistSpeechLibrary::StartDictationSession()` / `EndDictationSession()`
+- [ ] On hotkey hold: capture microphone via UE `VoiceModule`, stream PCM to `freestyle` loopback endpoint
+- [ ] On release: receive transcript JSON, parse cleaned text, execute move notation or coach command
+- [ ] **Audio Ducking**: when `bDictationActive = true`, duck all non-speech `UAudioComponent` volumes to 15% via `FAudioDevice` mixer gain or per-component `VolumeMultiplier`
+- [ ] Restore full volume 200ms after `EndDictationSession()`
+- [ ] Automation test: simulate hotkey hold, assert `VolumeMultiplier < 0.2f` on background music component; assert restoration after release
+
+### 1C — Text-to-Speech: `rhasspy/piper`
+- [ ] Add submodule `mirrors/piper`
+- [ ] Compile `piper` as static library (espeak-ng dependency)
+- [ ] Download one small voice model (~50MB) into `Content/Voices/`
+- [ ] Expose `UHyperTwistSpeechLibrary::Synthesize(FString Text, FString VoiceId)` → `TArray<uint8> PCM16`
+- [ ] Automation test: synthesize "hello", assert PCM output is non-empty and has correct sample rate
+
+### 1D — Compact Solver Oracle: `brownan/Rubiks-Cube-Solver` (GPL-2.0)
+- [ ] Host as external IPC process (never link GPL into Unreal binary)
+- [ ] Expose `UHyperTwistSolverLibrary::VerifySolution(FString State, TArray<FString> Moves)` → `bool`
+
+### 1E — glTF Reference Renderer: `KhronosGroup/glTF-Sample-Renderer` (Apache-2.0)
+- [ ] Add submodule `mirrors/glTF-Sample-Renderer`
+- [ ] Evaluate: header-only portions vs. full renderer
+- [ ] If linkable: add to `Build.cs`, expose asset import validation helpers
+- [ ] If too heavy: retain as reference-only for QA pipeline
+
+### 1F — Solver Adjunct: `cahidenes/rubiks-cube-solver` (MIT)
+- [ ] Host as external IPC process (Python)
+- [ ] Expose comparison endpoint: same state to both solvers, assert identical solution length
+
+### 1G — Browser Solver: `tentone/rubix-solver` (MIT)
+- [ ] Bundle into browser runtime (`Content/Browser/`)
+- [ ] Load in embedded WebBrowser widget as demo/fallback solver UI
+
+### 1H — Browser Spatial Stack (13 JS repos)
+- [ ] Add all as npm dependencies or prebuilt bundles in `Content/Browser/`
+- [ ] Repos: `NuiLab/code-vr`, `pissang/claygl`, `pissang/clay-viewer`, `pmndrs/postprocessing`, `pmndrs/react-postprocessing`, `pmndrs/drei`, `pmndrs/uikit`, `pmndrs/three-stdlib`, `pmndrs/maath`, `pmndrs/zustand`, `pmndrs/leva`, `pmndrs/use-gesture`, `pmndrs/react-spring` + sub-packages
+- [ ] Build once via npm → bundle `browser-spatial-runtime.js`
+- [ ] Load bundle in `UHyperTwistBrowserWidget`
+- [ ] State bridge: UE `FJsonObject` ↔ JS `postMessage`
+
+### 1I — Analytics Stack (2 JS repos)
+- [ ] `ecomfe/zrender`, `ecomfe/echarts-gl`
+- [ ] Bundle into browser runtime; subordinate to already-landed `apache/echarts`
+- [ ] Expose chart data endpoint from UE analytics subsystem
+
+### 1J — Model-Viewer Sub-Packages (3 JS repos, runtime)
+- [ ] `google/model-viewer/packages/model-viewer-effects`, `space-opera`, `render-fidelity-tools`
+- [ ] Bundle into browser runtime alongside already-landed `google/model-viewer`
+- [ ] `render-fidelity-tools` → QA comparison pipeline only
+
+**Estimated actions:** 40–60 per repo (UHT regen on first include)
+**Estimated time:** 1–2 days per repo (build-debug cycles)
+
+---
+
+## Phase 2: Core Puzzle Renderer — The Missing Centerpiece
+
+**Goal:** HyperTwist becomes a visible, interactive product.
+
+**Principle:** This is the highest-priority functional gap. It blocks every user-facing feature.
+
+### 2A — Procedural Classic Cube Geometry
+- [ ] Create `AHyperTwistClassicCubeActor` : `AActor`
+- [ ] Generate 26 pieces (6 centers, 12 edges, 8 corners) as `UProceduralMeshComponent` or `UStaticMeshComponent` instances
+- [ ] Assign per-face materials (6 colors + black internals)
+- [ ] Place pieces in solved-state positions in a 3×3×3 grid
+- [ ] No animation yet — static correct geometry is the first proof
+
+### 2B — Face Rotation Logic
+- [ ] Implement `UHyperTwistClassicCubeComponent::RotateFace(ECubeFace Face, ERotationDirection Dir, bool bAnimate)`
+- [ ] Update piece position/orientation arrays (state math already exists in `HyperTwistCoreLibrary`)
+- [ ] Animate rotation using `FLatentActionManager` or tick-based quaternion interpolation
+- [ ] Duration: 0.15s per quarter-turn (standard cubing feel)
+
+### 2C — Mouse/Touch Input
+- [ ] Implement `AHyperTwistClassicCubeActor::OnClick(FVector RayOrigin, FVector RayDir)`
+- [ ] Raycast against cube pieces, determine which face was clicked
+- [ ] Map click position to face + direction (CW/CCW)
+- [ ] Support drag gestures for swipe-based turning
+- [ ] Automation test: simulate raycast, assert correct face rotates
+
+### 2D — Scramble Generation
+- [ ] Expose `UHyperTwistClassicCubeComponent::GenerateScramble(int32 Length)` → `TArray<FString>`
+- [ ] Apply scramble to visible geometry (animate each move)
+- [ ] Display scramble notation in HUD
+
+### 2E — Timer + HUD
+- [ ] Create `WBP_HyperTwistGameHUD` (UMG Widget)
+- [ ] Timer display (minutes:seconds.milliseconds)
+- [ ] Inspection countdown (15s standard)
+- [ ] Scramble notation panel
+- [ ] Bind timer start to first face turn, stop to solved-state detection
+
+**Estimated actions:** 80–120 (geometry + input + HUD)
+**Estimated time:** 3–5 days
+
+---
+
+## Phase 3: First Playable Level
+
+**Goal:** A level you can launch, scramble, solve, and time.
+
+### 3A — Level Creation
+- [ ] Create `L_HyperTwist_ClassicTraining` (`.umap`)
+- [ ] Place `AHyperTwistClassicCubeActor` at world origin
+- [ ] Add directional light + ambient environment (basic, not immersive yet)
+- [ ] Add `WBP_HyperTwistGameHUD` to viewport
+- [ ] Add camera pawn with orbit controls (mouse drag orbits, scroll zooms)
+
+### 3B — Game Mode
+- [ ] Create `AHyperTwistClassicGameMode` : `AGameModeBase`
+- [ ] Handle game state: `Idle`, `Inspecting`, `Solving`, `Solved`
+- [ ] On `Solved`: stop timer, show solve time, offer "New Scramble"
+
+### 3C — Build & Package Validation
+- [ ] Package `UnrealHyperTwist` for Windows (not just Editor build)
+- [ ] Launch packaged build on Windows host
+- [ ] Verify: cube visible, clickable, scramble applies, timer works, solve detected
+
+**Estimated actions:** 20–30
+**Estimated time:** 1–2 days
+
+---
+
+## Phase 4: Wire Solver into Training Pipeline
+
+**Prerequisite:** Phase 1A (rob-twophase) + Phase 2 (renderer)
+
+### 4A — Solver HUD Integration
+- [ ] Add "Hint" button to HUD
+- [ ] On click: query solver for next optimal move from current state
+- [ ] Animate hint (glow the suggested face)
+- [ ] Option: show full solution sequence as notation list
+
+### 4B — Training Mode: Follow-Along
+- [ ] Create `L_HyperTwist_FollowAlongTraining` (`.umap`)
+- [ ] Load a known scramble, show user the moves one at a time
+- [ ] User must match each move before advancing
+- [ ] Track accuracy and time
+
+### 4C — Solver Verification
+- [ ] After user solve, verify state is actually solved (not just timer stopped)
+- [ ] If not solved, show "DNF" (Did Not Finish)
+
+**Estimated actions:** 30–50
+**Estimated time:** 2–3 days
+
+---
+
+## Phase 5: Speech Pipeline (STT + TTS)
+
+**Prerequisite:** Phase 1B (freestyle) + Phase 1C (piper)
+
+### 5A — Voice Command Input
+- [ ] Add "Voice" button to HUD (or use freestyle global hotkey)
+- [ ] On hotkey hold: capture microphone audio → stream to freestyle loopback
+- [ ] On release: receive cleaned transcript from freestyle
+- [ ] Parse transcript for move notation: "R", "R prime", "R2", "slice M", etc.
+- [ ] Execute parsed move on cube
+- [ ] **Audio ducking active during entire hold duration**
+
+### 5B — Coach Narration Output
+- [ ] Add narration events: "Scramble ready", "Inspection time", "Go!", "Solved!"
+- [ ] Feed event text to piper → PCM16
+- [ ] Play PCM16 through UE `USoundWaveProcedural` or `FSoundSource`
+- [ ] Support multiple voice models (coach personality selection)
+- [ ] **Narration audio is NOT ducking candidate** — only background music/ambient
+
+### 5C — Voice Session Tests
+- [ ] Automation test: simulate hotkey hold, assert background `VolumeMultiplier < 0.2f`
+- [ ] Automation test: assert transcript "R prime" → parsed move `ECubeFace::R, ERotationDirection::CounterClockwise`
+- [ ] Automation test: "Solved!" → piper → assert PCM length > 0
+
+**Estimated actions:** 40–60
+**Estimated time:** 2–3 days
+
+---
+
+## Phase 6: Hypercube Renderer (4D/5D)
+
+**Prerequisite:** Phase 2 (classic renderer)
+
+### 6A — 2×2×2×2 Projection
+- [ ] Port Melinda 2×2×2×2 state math (already exists) to visible geometry
+- [ ] Implement cell-first projection (8 cells, each a 3D cube)
+- [ ] Color 16 stickers per cell using permutation/orientation state
+- [ ] Mouse interaction: click cell + axis → twist
+
+### 6B — 3×3×3×3 Projection
+- [ ] Extend to 3×3×3×3 (27 tesseracts, 81 cells visible in projection)
+- [ ] Use wireframe or transparent cells to avoid occlusion chaos
+- [ ] Keyboard shortcuts for axis rotation and slice twists
+
+### 6C — Magic120Cell & MagicCube5D
+- [ ] Decision gate: port roice3 code (Java/C#) or implement clean-room in UE
+- [ ] If port: host as external process, stream state via IPC
+- [ ] If clean-room: implement 120-cell dodecahedral projection from spec
+
+**Estimated actions:** 100–200
+**Estimated time:** 1–2 weeks
+
+---
+
+## Phase 7: Non-Euclidean Puzzles (MagicTile)
+
+**Prerequisite:** Phase 6 (hypercube renderer)
+
+### 7A — MagicTile Host Decision
+- [ ] Evaluate: port MagicTile Java/OpenTK to Unreal vs. host in embedded browser
+- [ ] If browser: wire `react-three-fiber` + `three.js` into embedded CEF
+- [ ] If port: implement spherical/hyperbolic tiling math from spec
+
+### 7B — Puzzle State Bridge
+- [ ] Unreal ↔ MagicTile state serialization
+- [ ] Shared scramble notation parser
+- [ ] Unified timer across puzzle types
+
+**Estimated actions:** 80–150
+**Estimated time:** 1–2 weeks
+
+---
+
+## Phase 8: Browser-Based Renderer
+
+**Prerequisite:** Phase 2 (classic renderer)
+
+### 8A — Embedded Browser Runtime
+- [ ] Add `WebBrowser` plugin to `.uproject`
+- [ ] Create `UHyperTwistBrowserWidget` wrapping `SWebBrowser`
+- [ ] Load local `three.js` + `react-three-fiber` build
+
+### 8B — State Synchronization
+- [ ] Bridge UE cube state to browser via `FJsonObject` → JavaScript `postMessage`
+- [ ] Browser renders cube using Three.js; UE handles input and logic
+- [ ] Alternative: full browser client with HTTP API to UE backend
+
+**Estimated actions:** 50–80
+**Estimated time:** 3–5 days
+
+---
+
+## Phase 9: Social & Export
+
+**Prerequisite:** Phase 3 (playable level)
+
+### 9A — Replay Recording
+- [ ] Record move sequence + timestamps during solve
+- [ ] Export to `.json` replay file
+- [ ] Load replay, reconstruct animation
+
+### 9B — Media Export
+- [ ] Integrate `remotion-dev/remotion` or UE `MovieRenderQueue` for video export
+- [ ] Export solve animation as MP4
+- [ ] Export scramble + time as shareable image
+
+### 9C — Leaderboard Stub
+- [ ] Local SQLite or JSON leaderboard (no backend yet)
+- [ ] Store best times per puzzle type + scramble length
+- [ ] Display in HUD
+
+**Estimated actions:** 40–60
+**Estimated time:** 2–3 days
+
+---
+
+## Phase 10: Validation Reconstruction
+
+**Principle:** Validation only verifies what actually exists.
+
+### 10A — Deprecate Structural-Only Tests
+- [ ] Mark all Phase J tests that only verify contract ID stability as `Deprecated`
+- [ ] Do not delete (preserves build history), but stop adding new ones
+
+### 10B — Behavior-Based Validation Tests
+- [ ] `FHyperTwistClassicCubeRotationTest`: Rotate R face, assert piece positions updated
+- [ ] `FHyperTwistClassicCubeSolveTest`: Apply known solution, assert solved-state
+- [ ] `FHyperTwistSolverAccuracyTest`: Feed 100 random states to solver, assert all solvable
+- [ ] `FHyperTwistTimerAccuracyTest`: Start timer, wait 5s, assert 4.9s < elapsed < 5.1s
+- [ ] `FHyperTwistSpeechTranscriptionTest`: Synthetic PCM "R prime" → assert move parsed
+
+### 10C — Integration Tests
+- [ ] Launch `L_HyperTwist_ClassicTraining`, simulate 10 moves, verify no crash
+- [ ] Package build test: verify `UnrealHyperTwist.exe` launches and cube is visible
+
+**Estimated actions:** 20–30
+**Estimated time:** 1–2 days
+
+---
+
+## Cross-Cutting Concerns
+
+### Licensing & Attribution
+- Each wired repo gets a `LICENSE.thirdparty` entry
+- GPL repos (brownan) remain IPC-only; never linked
+- MIT/Apache repos compile and link directly
+- Attribution bundles updated from metadata-only to runtime-provenance
+
+### Build Validation Doctrine
+- Every phase requires Windows Unreal build validation
+- Phase 0–1: expect 50–100 actions (infrastructure)
+- Phase 2–3: expect 150–250 actions (geometry + input)
+- Phase 4+: expect 80–150 actions (feature wiring)
+- Package validation (Phase 3C) is the real gate, not Editor build
+
+### Documentation Rule
+- Docs describe what IS implemented, not what MIGHT be
+- No new "packet" files for scaffolding
+- Architecture docs updated only after functional code is merged
+
+---
+
+## Summary: What Changes vs. Old Roadmap
+
+| Old Approach | New Approach |
+|--------------|--------------|
+| Add struct pairs (J-HG → J-HM) | Wire repos (freestyle, piper, rob-twophase) |
+| Tests verify contract IDs | Tests verify cube rotation, solve accuracy, speech |
+| Docs claim features are "landed" | Features are playable before documented |
+| 318 test files, 0 gameplay | 30 test files, 1 playable level |
+| 1,142 docs, 20 content assets | Docs trimmed to functional truth |
+| No donor repos linked | C++ repos compiled and linked |
+| No .uasset, .umap | Procedural geometry + playable level |
+
+---
+
+## Immediate Next Step
+
+**Phase 0A:** Create `.external/` and `ThirdParty/`, add `.gitmodules` for
+`freestyle-voice/freestyle` as the proof-of-concept speech integration.
+
+This is the smallest step that proves the repo-wiring infrastructure works.
--- a/docs/ops/HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md
+++ b/docs/ops/HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md
@ -0,0 +1,163 @@
+# HyperTwist — Unwired Repo Inventory & Wiring Schedule
+
+**Date:** 2026-06-10  
+**Source authority:** `HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md`, `HYPERTWIST_PHASE_0R_PACKET_0R_B_EVALUATION_2026-05-12.md`, `HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md`  
+**Status:** Reconstructed from canonical docs; counts verified against board totals.
+
+---
+
+## Executive Count
+
+| Bucket | Count |
+|--------|-------|
+| Implemented/live (all licenses, original 71-row set) | 29 |
+| **Selected, not live — permissive wiring queue** | **29** |
+| Reference / benchmark / discard (0R-E) | 13 |
+| Speech rows outside 71-row set (attribution-only) | 4 |
+| **Total non-live** | **46** |
+
+The **29 in the wiring queue** are the implementation targets. The 13 reference/discard rows and the 4 speech rows are accounted for but not scheduled for direct wiring unless a later decision changes their posture.
+
+---
+
+## The 29 — Permissive Wiring Queue (0R-B minus live promotions)
+
+These repos were evaluated in `Packet 0R-B` (36 repos). Seven later graduated to live status via Phase 3R and 6R packets. The remaining 29 are retained but **not yet wired** into the Unreal build.
+
+### Wave A — Solver & Recognition Adjuncts (2 repos)
+
+| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase |
+|---|------|---------|------|--------------|-----------------|--------------|
+| 1 | `cahidenes/rubiks-cube-solver` | MIT | Python | Classic cube solver with visualizer | IPC process or Python embedding; expose `Solve(FString State)` → moves | 4A (Solver HUD) |
+| 2 | `tentone/rubix-solver` | MIT | JS | Browser-based cube solver | Embedded browser runtime (CEF) or adapter layer; not direct C++ link | 4A (Solver HUD) |
+
+### Wave B — Spatial / Browser / XR Stack (13 repos)
+
+| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase |
+|---|------|---------|------|--------------|-----------------|--------------|
+| 3 | `NuiLab/code-vr` | MIT | JS | Code editor in VR (WebXR) | Embedded browser or WebXR bridge; evaluate vs. native UE VR | 8 (Browser renderer) |
+| 4 | `pissang/claygl` | BSD | JS | Lightweight WebGL engine | Embedded browser runtime; alternative to Three.js if needed | 8 (Browser renderer) |
+| 5 | `pissang/clay-viewer` | BSD | JS | glTF model viewer on ClayGL | Embedded browser runtime; asset QA preview | 8 (Browser renderer) |
+| 6 | `pmndrs/postprocessing` | Zlib | JS | Post-processing effects for Three.js | Embedded browser runtime; visual polish for browser view | 8 (Browser renderer) |
+| 7 | `pmndrs/react-postprocessing` | MIT | JS | React wrapper for postprocessing | Embedded browser runtime; only if R3F bridge is used | 8 (Browser renderer) |
+| 8 | `pmndrs/drei` | MIT | JS | Useful helpers for R3F | Embedded browser runtime; helper components | 8 (Browser renderer) |
+| 9 | `pmndrs/uikit` | MIT | JS | UI components for R3F | Embedded browser runtime; HUD in browser view | 8 (Browser renderer) |
+| 10 | `pmndrs/three-stdlib` | MIT | JS | Three.js standard library extensions | Embedded browser runtime; dependency of other pmndrs pkgs | 8 (Browser renderer) |
+| 11 | `pmndrs/maath` | MIT | JS | Math utilities for animation | Embedded browser runtime; animation easing | 8 (Browser renderer) |
+| 12 | `pmndrs/zustand` | MIT | JS | State management | Embedded browser runtime; state sync if browser view is standalone | 8 (Browser renderer) |
+| 13 | `pmndrs/leva` | MIT | JS | GUI controls for R3F | Embedded browser runtime; debug/inspector panel | 8 (Browser renderer) |
+| 14 | `pmndrs/use-gesture` | MIT | JS | Gesture hooks for React | Embedded browser runtime; touch/drag in browser view | 8 (Browser renderer) |
+| 15 | `pmndrs/react-spring` | MIT | JS | Spring physics animation | Embedded browser runtime; smooth transitions | 8 (Browser renderer) |
+
+### Wave C — Google Model-Viewer Sub-Packages (4 repos)
+
+| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase |
+|---|------|---------|------|--------------|-----------------|--------------|
+| 16 | `google/model-viewer/packages/model-viewer-effects` | Apache-2.0 | JS | Particle/effects system for model-viewer | Embedded browser runtime; decorative effects | 8 (Browser renderer) |
+| 17 | `google/model-viewer/packages/modelviewer.dev` | Apache-2.0 | JS | Documentation site | Not for runtime; reference docs only | — |
+| 18 | `google/model-viewer/packages/render-fidelity-tools` | Apache-2.0 | JS | Rendering comparison tools | Not for runtime; QA/benchmark pipeline | 10B (Validation) |
+| 19 | `google/model-viewer/packages/space-opera` | Apache-2.0 | JS | Model-viewer editor UI | Embedded browser runtime; editor interface | 8 (Browser renderer) |
+
+### Wave D — Analytics & Visualization (2 repos)
+
+| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase |
+|---|------|---------|------|--------------|-----------------|--------------|
+| 20 | `ecomfe/zrender` | BSD | JS | 2D rendering engine (ECharts dependency) | Embedded browser runtime; subordinate to apache/echarts | 9 (Social/Export) |
+| 21 | `ecomfe/echarts-gl` | BSD | JS | WebGL extension for ECharts | Embedded browser runtime; 3D charts/progress viz | 9 (Social/Export) |
+
+### Wave E — glTF Standards & Samples (2 repos)
+
+| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase |
+|---|------|---------|------|--------------|-----------------|--------------|
+| 22 | `KhronosGroup/glTF-Sample-Viewer` | Apache-2.0 | JS | Reference glTF viewer | Embedded browser runtime; standard compliance check | 8 (Browser renderer) |
+| 23 | `KhronosGroup/glTF-Sample-Renderer` | Apache-2.0 | C++ | Reference glTF renderer | **Direct C++ link** via `ThirdParty/`; evaluate for asset import pipeline | 2A (Geometry) |
+
+### Wave F — React-Spring Sub-Packages (6 repos)
+
+| # | Repo | License | Lang | What It Does | Wiring Approach | Target Phase |
+|---|------|---------|------|--------------|-----------------|--------------|
+| 24 | `@react-spring/core` | MIT | JS | Core spring physics | Embedded browser runtime; dependency | 8 (Browser renderer) |
+| 25 | `@react-spring/shared` | MIT | JS | Shared utilities | Embedded browser runtime; dependency | 8 (Browser renderer) |
+| 26 | `@react-spring/types` | MIT | TS | Type definitions | Dev dependency only; not shipped | — |
+| 27 | `@react-spring/parallax` | MIT | JS | Parallax scrolling | Embedded browser runtime; scroll UX if needed | 8 (Browser renderer) |
+| 28 | `@react-spring/rafz` | MIT | JS | RAF scheduling | Embedded browser runtime; dependency | 8 (Browser renderer) |
+| 29 | `@react-spring/animated` | MIT | JS | Animated component primitives | Embedded browser runtime; dependency | 8 (Browser renderer) |
+
+---
+
+## Wiring Rules by Runtime Posture
+
+### Direct C++ Link (Only for C/C++ repos)
+- `efrantar/rob-twophase`
+- `KhronosGroup/glTF-Sample-Renderer`
+- `rhasspy/piper`
+- `freestyle-voice/freestyle` (if embedding; otherwise IPC)
+
+### Embedded Browser Runtime (For JS/TS repos)
+- Requires `WebBrowser` plugin in `.uproject`
+- Requires Node.js build pipeline or prebuilt bundles in `Content/Browser/`
+- State bridge via `FJsonObject` ↔ JavaScript `postMessage`
+- All Wave B, C, D, E (JS), F repos use this path
+
+### IPC / Sidecar Process (For Python or restrictive repos)
+- `cahidenes/rubiks-cube-solver` (Python)
+- `brownan/Rubiks-Cube-Solver` (GPL, Python)
+- `freestyle-voice/freestyle` (if not embedded)
+
+### Reference-Only (No runtime wiring)
+- `google/model-viewer/packages/modelviewer.dev` — docs site
+- `@react-spring/types` — TypeScript dev dependency
+- `pmndrs/react-postprocessing` — only if R3F is primary path; may be redundant
+
+---
+
+## Speech Rows (Outside 71-Row Set)
+
+| Repo | License | Status | New Wiring Plan |
+|------|---------|--------|-----------------|
+| `ggml-org/whisper.cpp` | MIT | **Replaced** | No longer primary STT; retain as benchmark/reference |
+| `rhasspy/piper` | MIT | **Queued** | Phase 1C — compile as static lib, link directly |
+| `SYSTRAN/faster-whisper` | MIT | **Queued** | Retain as alternative STT benchmark; no active wiring |
+| `coqui-ai/TTS` | MPL-2.0 | **Queued** | Retain as TTS benchmark; piper is primary |
+
+**STT primary:** `freestyle-voice/freestyle` (MIT, cloud-API client)  
+**TTS primary:** `rhasspy/piper` (MIT, local C++ engine)
+
+---
+
+## Reference / Benchmark / Discard (13 repos — 0R-E)
+
+Not scheduled for wiring. Listed for completeness:
+
+| Repo | Posture |
+|------|---------|
+| `yakupbilen/drl-rubiks-cube` | Research benchmark only |
+| `brownan/Rubiks-Cube-Solver` | GPL oracle; IPC if ever used |
+| `efrantar/rob-twophase` | **Promoted to Phase 1A** — direct implementation |
+| `ShellPuppy/RCube` | Benchmark only |
+| `vwcwong/CubeSim` | Benchmark only |
+| `alinen/cube` | Benchmark only |
+| `ambisinister/blindsolve` | Benchmark only |
+| `AviKaufman/Rubix-cube-trainer` | Benchmark only |
+| `poliva/cubedex` | Restrictive comparison context |
+| And 4 others | Discard or deferred |
+
+---
+
+## Phase 1 Regenerated — All Wired Repos
+
+| Sub-Phase | Repo | Wiring Path | Build Type |
+|-----------|------|-------------|------------|
+| 1A | `efrantar/rob-twophase` | Static library, direct link | C++ |
+| 1B | `freestyle-voice/freestyle` | Sidecar HTTP or embedded | Rust/TS |
+| 1C | `rhasspy/piper` | Static library, direct link | C++ |
+| 1D | `brownan/Rubiks-Cube-Solver` | IPC process (GPL) | Python |
+| 1E | `KhronosGroup/glTF-Sample-Renderer` | Static library or header-only | C++ |
+| 1F | `cahidenes/rubiks-cube-solver` | IPC process | Python |
+| 1G | `tentone/rubix-solver` | Embedded browser | JS |
+
+---
+
+## Next Step
+
+**Phase 0:** Create `.external/`, `ThirdParty/`, `.gitmodules`, and `Build.cs` rules so that Phase 1 repos can actually compile and link.
				`@ -0,0 +1 @@`
				`Subproject commit 86456edc4b28494e5facbe75fc4f009fe8cf3f3e`
				`@ -0,0 +1 @@`
				`Subproject commit 5e3066734fcc6fdb333978c76baefc0b69c258c5`
				`@ -0,0 +1 @@`
				`Subproject commit 23204c26cc42cfda1de9705ab34649bd394cc168`
				`@ -0,0 +1 @@`
				`Subproject commit c9d3d0dc9473f026c83965a7eb8c7f7a1a1bf0ae`
				`@ -0,0 +1 @@`
				`Subproject commit 2bd401e7ca5e10cdfd96643c9b646fd7ee6ca04b`
				`@ -0,0 +1 @@`
				`Subproject commit bec106e53da4a6a398aa3205f0f96563519a657e`
				`@ -0,0 +1 @@`
				`Subproject commit 6b4012c8cd58f933565401fbe4404a40380ee0fb`
				`@ -0,0 +1 @@`
				`Subproject commit 402a1e9d0899e6d384993aaffe8dc0d2c39110e1`
				`@ -0,0 +1 @@`
				`Subproject commit 626d198fbae28ba82f2f1b184db7fcafd4d23846`
				`@ -0,0 +1 @@`
				`Subproject commit 35f94667db54d997264930f5cff1661eb969505d`