Immersive Cinematic Intro UI
Relevant source files
The following files were used as context for generating this wiki page:
The Immersive Cinematic Intro UI serves as the high-performance entry gate for the Isabella Villaseñor AI system. It provides a cinematic onboarding experience using WebGL 3D rendering, 2D canvas layers, and positional audio to establish the system's identity and territorial context.
This system manages complex visual sequences, adaptive quality scaling based on hardware capabilities, and user-triggered audio unlocking. It ensures accessibility by respecting system motion preferences and providing a clear path to bypass the introduction and enter the main application shell.
Sources: src/components/IsabellaImmersiveTrailer.tsx:1-15, src/immersive/ImmersiveScene.ts:1-18, README.md:148-154
Core Architecture and Orchestration
The system utilizes an orchestrated class structure to manage the lifecycle of the cinematic scene. The ImmersiveScene class acts as the central controller, managing WebGL renderers, perspective cameras, and audio contexts.
Scene Management Logic
The orchestration logic follows these principles:
- Single Instance: Only one instance exists per canvas to ensure performance.
- Adaptive Quality: The system detects device capabilities (GPU, pixel ratio) to set quality to low, medium, or high.
- State Management: It handles WebGL context loss and restoration events to prevent application crashes.
- Visibility Control: The scene pauses automatically when the browser tab is hidden and resumes when it becomes visible again.
Sources: src/immersive/ImmersiveScene.ts:10-23, src/immersive/ImmersiveScene.ts:133-145
The diagram shows the initialization and render loop lifecycle of the immersive engine. Sources: src/immersive/ImmersiveScene.ts:133-210
Visual Subsystems
The visual experience consists of multiple overlaid layers that simulate a "Cosmic Bloom" and territorial mapping.
Rendering Layers
| Layer | Technology | Description |
|---|---|---|
| 3D Starfield | WebGL (Three.js) | High-performance 3D particles with depth and parallax motion. |
| 2D Starfield | Canvas 2D | Lightweight "twinkle" effect for background stars. |
| HUD / Reticle | HTML/CSS | Interactive overlays displaying simulated coordinates and system status. |
| Cinematic Letterbox | CSS | Dramatic black bars that transition into view to create a cinema feel. |
Sources: src/immersive/ImmersiveScene.ts:145-175, src/components/Welcome/IsabellaCinematicTrailer.tsx:440-455, src/components/IsabellaImmersiveTrailer.tsx:90-110
Adaptive Quality Configuration
The system adjusts its rendering parameters based on the detectQuality utility and user settings:
- High Quality: Enables Bloom, higher star counts, and 4D motion effects.
- Reduced Motion: Disables camera shake, reduces star counts by ~55%, and sets static compositions.
Sources: src/immersive/ImmersiveScene.ts:148-160, src/components/IsabellaCinematicTrailer.tsx:14-20
Positional Audio Engine
Audio is strictly gated behind user interaction to comply with browser autoplay policies. The engine uses the Web Audio API to create a spatial soundscape.
Audio Component Workflow
- Lock State: The
AudioContextis created in a suspended state. - Unlock Trigger: A user click on "Activar experiencia sonora" triggers the
unlockAudio()method. - Frequency Analysis: An
AnalyserNodeprovides real-time byte frequency data used to modulate visual elements like glow intensity. - Spatial Setup: A
PositionalAudiosource is attached to a moving "audio emitter" group in the 3D scene.
Sources: src/immersive/ImmersiveScene.ts:250-280, src/components/IsabellaImmersiveTrailer.tsx:64-75
The sequence illustrates the user-initiated transition from a locked to an active audio state. Sources: src/immersive/ImmersiveScene.ts:316-335, src/components/IsabellaImmersiveTrailer.tsx:68-80
Navigation and Lifecycle Integration
The Intro UI is integrated into the main App.tsx shell and uses localStorage to track completion status.
User Flow Procedures
- Entry: Upon first visit, the
Appcomponent checkslocalStorage. Ifisabella_intro_doneis not set, it rendersIsabellaImmersiveTrailer. - Interaction: Users can watch the 30-second sequence or use the "Omitir intro" (Skip) control.
- Completion: Clicking "Entrar al sistema" (Enter system) calls
onComplete, which updateslocalStorageand triggers the transition to the main Dashboard. - Safety Timeout: If the onboarding sequence hangs for more than 60 seconds, a fallback mechanism forces completion to ensure the user can access the system.
Sources: src/App.tsx:390-415, src/components/Welcome/IsabellaCinematicTrailer.tsx:400-420
Component Properties
| Prop | Type | Default | Description |
|---|---|---|---|
onComplete | () => void | Required | Callback triggered when the intro is finished or skipped. |
enterLabel | string | "Entrar al sistema" | The text displayed on the main call-to-action button. |
Sources: src/components/IsabellaImmersiveTrailer.tsx:23-26
Summary of Cinematic Intro UI
The Immersive Cinematic Intro UI provides a high-fidelity visual and auditory gateway to the Isabella system. By leveraging a dedicated ImmersiveScene class, the project separates heavy WebGL orchestration logic from the React component lifecycle. This enables robust features such as adaptive quality, automatic pausing for resource conservation, and sophisticated positional audio, all while maintaining accessibility through motion-reduction support and explicit skip paths.