Grand Diomande Research · Full HTML Reader

Echelon World UI - Production Implementation Guide

Echelon is a **motion-driven, phrase-based generative performance engine** whose temporal structure emerges from embodied latent physics. The UI depicts a *world*, not tools. There are no decks, no crossfaders, no timelines—only a living latent space that responds to the dancer's body.

Embodied Trajectory Systems research note experiment writeup candidate score 32 .md

Full Public Reader

Echelon World UI - Production Implementation Guide

Overview

Echelon is a motion-driven, phrase-based generative performance engine whose temporal structure emerges from embodied latent physics. The UI depicts a world, not tools. There are no decks, no crossfaders, no timelines—only a living latent space that responds to the dancer's body.

The body is the timeline. LIM-RPS is the internal physics. Music emerges from latent curvature.

> Critical Principle: The Web UI never computes physics. It renders the Rust-computed latent world. All equilibrium solving, state machine logic, and lexicon computation happens in cc-brain. The UI is a pure visualization layer.

Architecture

Hybrid System Design

┌──────────────────────────────────────────────────────────────┐
│  RUST CORE (Performance-Critical - Real-Time Audio Path)    │
│                                                              │
│  ┌──────────────────┐          ┌─────────────────────┐     │
│  │ Sensor HTTP      │──────────▶│ cc-brain Processing │     │
│  │ (Port 3000)      │          │ (LIM-RPS encoder,   │     │
│  │                  │          │  equilibrium solver, │     │
│  │                  │          │  state machine)      │     │
│  └──────────────────┘          └──────────┬──────────┘     │
│                                            │                 │
│                                            ▼                 │
│  ┌────────────────────────────────────────────────────┐    │
│  │ Audio Thread (Real-time, lock-free ringbuffer)     │    │
│  │  ├─ Custom Synth (latent_synth.rs)                 │    │
│  │  ├─ SuperCollider OSC (supercollider.rs)           │    │
│  │  └─ JACK/CPAL output                               │    │
│  └─────────────┬──────────────────────────────────────┘    │
│                │                                             │
│                │ Audio goes directly to hardware            │
│                ▼                                             │
│        [Audio Interface]                                     │
│                                                              │
└───────────────────┬──────────────────────────────────────────┘
                    │
                    │ WebSocket broadcast (tokio::sync::broadcast)
                    │ @ 60fps (NON-BLOCKING - never blocks audio!)
                    │
                    ▼
┌──────────────────────────────────────────────────────────────┐
│  WEB UI (Echelon World - Visualization Only)                │
│                                                              │
│  React + Three.js + WebGL Shaders (Port 8080)               │
│                                                              │
│  COMPONENTS:                                                 │
│  ├─ LatentOrb        - The heart (deformable geometry)      │
│  ├─ ForceField       - Curvature lines around orb           │
│  ├─ PhraseSpine      - Ribbon flowing from orb              │
│  ├─ GenerativeHorizon - Predicted trajectory corridor       │
│  ├─ SomaticTimeline  - Trailing latent history              │
│  └─ AmbientAura      - Full-screen atmospheric color        │
│                                                              │
│  POST-PROCESSING:                                            │
│  ├─ Bloom (HDR glow)                                        │
│  ├─ ChromaticAberration (subtle distortion)                 │
│  └─ Vignette (focus)                                        │
└──────────────────────────────────────────────────────────────┘

Performance Guarantees

1. Audio Latency: Unchanged - real-time JACK/CPAL (< 10ms)
2. Sensor → Audio Path: No web browser in the loop
3. cc-brain Integration: Rust-native encoder + equilibrium solver
4. WebSocket Broadcast: Non-blocking `tokio::sync::broadcast::Sender::send()`

Temporal Cadence

Sensor ingestion: 100-200 Hz (smartphone IMU rate)
cc-brain processing: Per sensor frame (variable step)
UI visualization: 60fps downsampled snapshots for GPU stability

> Rust computes latent physics per sensor frame; visualization receives smoothed snapshots at 60fps.

Audio Engine Flexibility

The audio backend can operate in multiple modes:

Mode	Description	Use Case
Local DSP	Custom synth (latent_synth.rs)	Standalone performance
SuperCollider	OSC → SC server	Advanced synthesis
External	OSC/MIDI → Ableton/laptop	Studio integration
Hybrid	Local + external layers	Production shows

Early Echelon versions output generative-control signals that feed external engines.

UI Component Specifications

1. Latent Orb (Center - The Heart)

The core visualization - a deformable geometry reflecting LIM-RPS equilibrium.

Location: Center of screen (dominant)

Geometry:
- Icosahedron with 4 subdivisions (64+ vertices)
- Vertex displacement based on latent vector
- Elongation along motion direction
- Contraction under convergence

Visual Properties:
- Surface glow intensity = latent norm
- Ripple propagation for micro-tension
- Color gradient: cool blues (calm) → warm oranges/reds (intense)
- Breathing animation from physiological baseline

Animation Behaviors:
- Stretch forward on acceleration
- Relax to roundness on slowdown
- Twist on rotational energy
- Shiver on sudden direction change

Data Mapping:

javascript

position.x = curvature * 2      // Left-right balance
position.y = velocity * 2        // Up-down energy
scale = 1.0 + energy * 0.3      // Size from energy
rotation.y = phase * 2π         // Beat phase rotation

2. Force Field (Around Orb)

Thin filaments emanating from orb edges, like magnetic field lines.

Location: Radiating from orb perimeter

Rendering:
- 20-30 dynamic bezier curves
- Origins distributed around orb surface
- Length/curvature driven by instantaneous motion curvature

Behavior:
- Orbit during rotational energy
- Drift in/out with latent breathing
- Twitch briefly during uncertainty
- Stabilize into periodic patterns during groove

Data Mapping:

javascript

lineLength = 0.5 + rotationalEnergy * 2
lineCurvature = curvature * 0.8
lineIntensity = tension

3. Phrase Spine (Right of Orb)

A ribbon flowing RIGHT from the orb - the current generative phrase as topology.

Location: Extends from orb toward right edge

> Critical: Phrase Spine never represents musical time. It represents structural momentum inside the latent space. The spine is topology, not timeline.

Geometry:
- Bezier ribbon with variable width
- Continuous extrusion from orb present
- NOT a waveform - a trajectory through latent space

Mapping:
- Thickness = energy/intensity
- Color hue = harmonic density (from section_state)
- Curvature = phrase evolution (from divergence)
- Surface oscillations = rhythmic structure

States:
- Growing: Extends during active movement
- Stable: Consistent width during groove
- Warping: Turbulent before transitions
- Dissolving: Contracts back to orb during stillness

4. Generative Horizon (Above Spine)

Translucent corridor above the phrase spine showing predicted future.

Location: Upper right, above phrase spine

> Prediction Method: Predictions are produced using latent momentum and curvature extrapolation: `z(t) → estimate of z(t + Δt)`. This is dynamical extrapolation, not a learned future model.

Visualization:
- Gradient field from current → predicted color
- Elongates with anticipation (high convergence)
- Contracts with hesitation (low convergence)
- Striations during stable rhythm (periodicity)

Data Mapping:

javascript

horizonLength = convergenceScore * 3
horizonOpacity = 0.3 + excitement * 0.4
horizonHue = sectionStateColor
horizonBend = curvature * 2.0  // Direction of predicted motion

5. Somatic Timeline (Bottom Center)

Trailing path showing compressed latent history (last 5-10 seconds).

Location: Bottom center, trailing from orb

Visualization:
- Fading trail of recent movement
- Bright ember/gold at tension peaks
- Pale violet at quiet moments
- Smoky grey as memory fades

NOT a DAW timeline - embodied memory landscape

6. Ambient Aura (Full Screen)

Full-screen atmospheric color field.

Location: Background, entire viewport

Properties:
- Slowest animation (barely perceptible)
- Saturates with intensity
- Desaturates with introspection
- Long cinematic fades at section boundaries

Color Mapping:

javascript

stable:     'hsl(220, 60%, 8%)'   // Deep blue
divergence: 'hsl(30, 70%, 10%)'   // Warm orange
transition: 'hsl(280, 65%, 10%)'  // Purple
resolution: 'hsl(150, 55%, 10%)'  // Green

7. Phrase Reservoir (Deep Background)

Memory field providing continuity and depth of structure.

Location: Deep background, surrounding all components

Purpose:
- Provides visual continuity between phrases
- Helps performers feel structural momentum
- Gives the UI depth of embodied memory
- Shows accumulated phrase archetypes

Visualization:
- Floating particle clouds representing phrase families
- Gravitational drift toward active archetypes
- Glow intensifies as likelihood rises
- Muted colors (never dominate foreground)

Data Mapping:

javascript

particleDrift = divergence * 0.5
particleOpacity = 0.1 + convergenceScore * 0.2
particleGlow = excitement * 0.3

UI Snapshot Schema

The intermediate representation passed from cc-brain to Web UI:

rust

struct UISnapshot {
    // Orb deformation
    orb_position: [f32; 3],       // x, y, z position
    orb_scale: f32,               // Overall scale
    orb_elongation: [f32; 3],     // Directional stretch
    orb_ripple_intensity: f32,    // Surface tension waves
    orb_color: [f32; 4],          // RGBA

    // Spine parameters
    spine_length: f32,            // How far spine extends
    spine_thickness: f32,         // Base width
    spine_curvature: f32,         // Bend amount
    spine_turbulence: f32,        // Surface noise
    spine_color: [f32; 4],        // RGBA

    // Horizon parameters
    horizon_length: f32,          // Prediction distance
    horizon_bend: f32,            // Direction of future
    horizon_opacity: f32,         // Confidence
    horizon_striations: f32,      // Rhythmic pattern strength

    // Aura parameters
    aura_hue: f32,                // HSL hue (0-360)
    aura_saturation: f32,         // HSL saturation (0-1)
    aura_brightness: f32,         // HSL lightness (0-1)
    aura_transition_speed: f32,   // Fade rate

    // Reservoir parameters
    reservoir_drift: f32,         // Particle movement
    reservoir_glow: f32,          // Active archetype intensity

    // State flags
    section_state: SectionState,
    transition_active: bool,
    timestamp_micros: u64,
}

Shader Uniform Mapping

How lexicon values map to shader parameters:

Lexicon Field	Shader Uniform	Component	Effect
`tension`	`uTension`	Orb	Surface ripple amplitude
`tension`	`uBloomIntensity`	Post-process	Glow strength
`divergence`	`uDivergence`	Spine	Warping/turbulence
`divergence`	`uSpread`	Horizon	Width expansion
`convergence_score`	`uConvergence`	All	Stability/sharpness
`transition_intensity`	`uTransition`	Horizon	Collapse amount
`excitement`	`uExcitement`	All	Brightness/saturation
`excitement`	`uPulseRate`	Orb	Breathing speed
`rotational_energy`	`uRotation`	Orb	Twist deformation
`curvature`	`uCurvature`	Spine, Horizon	Bend direction
`velocity`	`uVelocity`	Orb	Position offset
`grounding`	`uGrounding`	Orb, Aura	Scale, desaturation
`phase`	`uPhase`	Orb	Rotation angle
`periodicity`	`uPeriodicity`	Horizon	Striation frequency

State Machine Integration

The UI responds to section states from cc-brain:

State	Orb	Spine	Horizon	Aura	Reservoir
Entry	Soft, breathing	Absent	Dim	Cool	Settled
MicroInitiation	Leaning	Forming	Brightening	Warming	Drifting
StableSection	Solid, pulsing	Consistent	Clear	Saturated	Orbiting
Divergence	Rippling	Warping	Bending	Shifting	Agitated
Transitional	Imploding	Fracturing	Collapsing	Flickering	Scattering
Reformation	Crystallizing	Re-forming	Expanding	Stabilizing	Coalescing
Resolution	Softening	Dissolving	Fading	Cooling	Settling

Color Physics

Section State Colors

javascript

const sectionColors = {
  stable:     new Color('#1E90FF'),  // Cool blue - coherent flow
  divergence: new Color('#FF8C00'),  // Warm orange - building tension
  transition: new Color('#9932CC'),  // Purple - transformation
  resolution: new Color('#32CD32'),  // Green - release/arrival
}

Tension Gradient

javascript

// Low tension (0.0) → High tension (1.0)
const tensionGradient = [
  '#4A90D9',  // Cool blue
  '#22C55E',  // Green
  '#EAB308',  // Yellow
  '#F97316',  // Orange
  '#DC2626',  // Deep crimson
]

Animation Timing Curves

Micro-Animations

Phase	Curve	Duration
Early Warning	ease-in-cubic	200ms
Pre-Transition	inverse-exponential	400ms
Horizon Bend	smoothstep	600ms
Reservoir Drift	elastic-low-damp	800ms
Transition Moment	reverse-exponential	150ms
Reformation	critically-damped-spring	500ms
Settling	sine-wave-decay	1000ms

Spring Physics

All major movements use spring physics for natural easing:

javascript

const springConfig = {
  mass: 1,
  stiffness: 100,
  damping: 10,
  precision: 0.01
}

Latent State Data Format

WebSocket messages from Rust backend:

json

{
  "type": "latent_state",
  "tension": 0.5,
  "velocity": 0.3,
  "curvature": -0.2,
  "periodicity": 0.7,
  "internal_tempo": 120,
  "phase": 0.75,
  "grounding": 0.4,
  "verticality": 0.6,
  "rotational_energy": 0.3,
  "left_energy": 0.7,
  "left_velocity": 0.5,
  "right_energy": 0.4,
  "right_velocity": 0.3,
  "transition_intensity": 0.2,
  "divergence": 0.3,
  "convergence_score": 0.7,
  "excitement": 0.5,
  "section_state": "stable",
  "timestamp_micros": 1234567890
}

Building and Running

Prerequisites

bash

# Build cc-brain with learned weights
cd cc-echelon
cargo build --release -p cc-brain

# Install web dependencies
cd apps/web-viz
npm install

Build Frontend

bash

cd apps/web-viz
npm run build
# Outputs to apps/web-viz/dist/

Run Full System

bash

# Terminal 1: Start Echelon Studio with web visualization
cd cc-echelon
cargo run --release --bin studio --features web-viz

# System starts:
# - Audio engine on JACK/CPAL
# - Motion bridge on HTTP :3000
# - WebSocket server on :8080
# - Web UI at http://localhost:8080

Development Mode

bash

# Terminal 1: Run backend
cargo run --bin studio --features web-viz

# Terminal 2: Run frontend dev server (hot reload)
cd apps/web-viz
npm run dev
# Opens at http://localhost:5173
# Connect to WebSocket at ws://localhost:8080/ws

File Structure

apps/web-viz/
├── src/
│   ├── App.jsx              # Main app with WebSocket connection
│   ├── main.jsx             # Entry point
│   ├── components/
│   │   ├── Scene.jsx        # Three.js canvas compositor (Echelon World)
│   │   ├── LatentOrb.jsx    # Central orb visualization (THE HEART)
│   │   ├── ForceField.jsx   # Curvature lines around orb
│   │   ├── PhraseSpine.jsx  # Ribbon trajectory from orb
│   │   ├── GenerativeHorizon.jsx  # Predicted future corridor
│   │   ├── SomaticTimeline.jsx    # Trailing history below
│   │   ├── AmbientAura.jsx        # Full-screen atmospheric color
│   │   ├── PhraseReservoir.jsx    # Deep background memory field
│   │   ├── PhaseIndicator.jsx     # (legacy)
│   │   ├── TrailParticles.jsx     # (legacy)
│   │   ├── SlowAttractor.jsx      # (legacy)
│   │   ├── LimbSatellites.jsx     # (legacy)
│   │   └── TelemetryOverlay.jsx   # Debug overlay
│   ├── shaders/
│   │   ├── orbVertex.glsl   # Deformable geometry (simplex noise)
│   │   └── orbFragment.glsl # Dynamic lighting/color (fresnel, glow)
│   ├── hooks/
│   │   └── useWebSocket.js  # WebSocket with auto-reconnection
│   └── store/
│       └── vizStore.js      # Zustand state management
├── dist/                    # Built production files
├── index.html
├── vite.config.js
└── package.json

Credits

Architecture: Hybrid Rust + Web design preserves real-time audio while enabling GPU visualization
Latent Physics: LIM-RPS equilibrium solver (cc-brain)
UI Vision: Based on docs/ui/ conceptual specifications
Shader Design: GPU-accelerated deformable geometry with simplex noise displacement

---

Status: ✅ Production implementation complete

Component	Status	Description
LatentOrb	✅	Deformable geometry with GPU shaders
ForceField	✅	Curvature lines around orb
PhraseSpine	✅	Ribbon trajectory visualization
GenerativeHorizon	✅	Predicted future corridor
SomaticTimeline	✅	Trailing latent history
AmbientAura	✅	Full-screen atmospheric color
PhraseReservoir	✅	Deep background memory field
Post-processing	✅	Bloom, chromatic aberration, vignette
WebSocket	✅	60fps non-blocking broadcast
cc-brain integration	✅	Learned encoder + equilibrium

Build: `npm run build` → 1.08 MB bundle (295 KB gzipped)

Promotion Decision

Attach run IDs, datasets, metrics, and reproduction commands.

Source Anchor

Comp-Core/core/audio-media/cc-echelon/docs/ECHELON_UI_IMPLEMENTATION.md

Detected Structure

Method · Evaluation · Code Anchors · Architecture