@vib3code/sdk 2.0.1 → 2.0.3-canary.0a63e71

package/DOCS/EXPANSION_DESIGN_ULTRA.md

@@ -0,0 +1,389 @@
+Last reviewed: 2026-02-17
+
+# VIB3+ Ultra — The Emergent Media Engine
+
+**Purpose**: This document defines the **Ultra Tier** expansion for VIB3+. While the Premium Tier (`EXPANSION_DESIGN.md`) focuses on professional visualization tools, the Ultra Tier transforms the SDK into a **full-stack emergent media engine** capable of powering 4D video games, generative cartoons, and multi-user hallucinations.
+
+**Status**: Vision Document / Technical Specification.
+**Dependencies**: Requires `@vib3code/sdk` (core) and `@vib3code/premium` (for fine-grained control).
+
+---
+
+## I. Architecture: The VIB3 Universe
+
+The core shift is from **Single Instance** to **Orchestrated Universe**.
+
+### The Concept
+Instead of "a canvas on a page," we treat the browser window as a **Universe** containing multiple **Entities** (VIB3 instances). These entities share a clock, a physics lattice, and a narrative context.
+
+### The `VIB3Orchestrator`
+A new singleton that manages the lifecycle and coordination of all VIB3 instances.
+
+```javascript
+class VIB3Orchestrator {
+    constructor() {
+        this.entities = new Map(); // id -> VIB3Entity
+        this.clock = new MasterClock({ bpm: 120 }); // Shared beat sync
+        this.physics = new LatticePhysicsEngine(); // 4D collision detection
+        this.link = new VIB3Link(); // WebRTC multi-user sync
+    }
+
+    // Spawn a new entity (actor, prop, or environment)
+    spawn(type, config) { ... }
+
+    // Global tick loop
+    tick(deltaTime) {
+        this.physics.update(this.entities, deltaTime);
+        this.entities.forEach(e => e.update(deltaTime));
+        this.link.sync(this.entities);
+    }
+}
+```
+
+---
+
+## II. HyperNarrative: Animating Stories & Cartoons
+
+VIB3+ can tell stories. Characters are not mesh rigs but **VIB3 Actors** — distinct visualization instances with "souls" (parameter personalities) that express emotion through math.
+
+### 1. The `VIB3Actor`
+Wraps a `VIB3Engine` instance with identity, role, and emotional state.
+
+```javascript
+class VIB3Actor {
+    constructor(engine, personalityProfile) {
+        this.engine = engine;
+        this.profile = personalityProfile; // e.g., 'AnxiousGlitch', 'StoicCrystal'
+        this.emotion = { valence: 0, arousal: 0 }; // -1 to 1
+        this.voice = new AudioEmitter(); // Spatial audio source
+    }
+
+    // Express an emotion (modulates parameters based on profile)
+    emote(emotionName, intensity) {
+        const params = this.profile.mapEmotion(emotionName, intensity);
+        this.engine.transition(params, 500, 'easeOut');
+    }
+
+    // "Speak" with audio-reactive mouth modulation
+    speak(audioBuffer) {
+        this.voice.play(audioBuffer);
+        this.voice.onAnalysis((amplitude) => {
+            // Modulate geometry to simulate speech/expression
+            this.engine.setParameter('morphFactor', 0.5 + amplitude * 1.5);
+            this.engine.setParameter('intensity', 0.6 + amplitude * 0.4);
+        });
+    }
+}
+```
+
+### 2. The Script Format (`.vib3script`)
+A JSON-based screenplay format that controls actors, cameras, and environment.
+
+```json
+{
+  "title": "The Geometric Encounter",
+  "bpm": 110,
+  "cast": {
+    "Hero": { "system": "faceted", "geometry": 0, "profile": "heroic" },
+    "Villain": { "system": "quantum", "geometry": 16, "profile": "chaotic" }
+  },
+  "sequence": [
+    {
+      "time": "0:00",
+      "action": "camera_cut",
+      "target": "Hero",
+      "shot": "close_up" // Adjusts zoom/projection
+    },
+    {
+      "time": "0:02",
+      "actor": "Hero",
+      "action": "speak",
+      "text": "Why do you disturb the lattice?",
+      "audio": "hero_line_1.mp3",
+      "emotion": "stern"
+    },
+    {
+      "time": "0:05",
+      "actor": "Villain",
+      "action": "emote",
+      "emotion": "rage",
+      "intensity": 0.8 // Triggers red hue, high chaos, spike geometry
+    }
+  ]
+}
+```
+
+### 3. LipSync & Performance
+Use `WebAudioAPI` analysis on dialogue tracks to drive `morphFactor` (mouth opening) and `intensity` (energy).
+- **Consonants (High Freq)**: Trigger `chaos` spikes (sharp edges).
+- **Vowels (Mid Freq)**: Trigger `morphFactor` swells (round shapes).
+- **Volume**: Drives `gridDensity` (louder = larger/closer).
+
+---
+
+## III. HyperGame: FPV Gameplay Engine
+
+Transform VIB3+ from a passive visualizer into an active **4D Game Engine**.
+
+### 1. 4D Player Controller (`FPVController`)
+Maps WASD + Mouse to 6D motion, allowing navigation *through* the hyperspace lattice.
+
+- **W/S**: Move forward/back in Z (depth).
+- **A/D**: Strafe in X.
+- **Space/Shift**: Move in Y (up/down).
+- **Q/E**: Rotate in XW plane (portal strafe).
+- **Mouse**: Rotate XY (look left/right) and YZ (look up/down).
+
+```javascript
+// Inside game loop
+if (input.forward) {
+    // Move "camera" through 4D noise space
+    // We don't move geometry; we offset the noise coordinate system!
+    uniforms.u_noiseOffset.z += speed * dt;
+}
+if (input.portalLeft) {
+    // Rotate the entire world in 4D
+    uniforms.u_rot4dXW += rotationSpeed * dt;
+}
+```
+
+### 2. Lattice Physics (`LatticeCollider`)
+Collision detection is not mesh-based (too expensive/abstract). It is **Function-Based**.
+Since VIB3+ geometries are defined by math functions (SDFs or lattice grids), we check the player's coordinate against the active function.
+
+```javascript
+function checkCollision(playerPos, activeGeometry) {
+    // Sample the density function at player position
+    const density = getDensityAt(playerPos, activeGeometry);
+    if (density > 0.8) {
+        // Hit a "solid" part of the fractal/lattice
+        return true;
+    }
+    return false;
+}
+```
+
+### 3. Entity System
+Game objects are lightweight VIB3 instances or simplified shader particles.
+- **Projectiles**: Small `Quantum` instances (single particle geometry) moving in XYZW.
+- **Pickups**: `Faceted` geometries (spinning crystals) that trigger events on collision.
+- **Enemies**: `Holographic` instances that track player position.
+
+### 4. Game State Manager
+Tracks score, health, and inventory.
+- **Health**: Low health = high `chromaticAberration` + desaturation + `glitch` effect.
+- **Powerup**: Ingesting a "hypercube" powerup transitions the player's view to `HyperMode` (geometry 17, max color).
+
+---
+
+## IV. Emergent Media: AI & Multi-User Sync
+
+The final frontier: VIB3+ experiences that are alive, shared, and intelligent.
+
+### 1. VIB3Link (Multi-User Hallucination)
+Uses WebRTC/WebSockets to synchronize the `VIB3Orchestrator` state across clients.
+- **Shared Seed**: All clients start with same RNG seed.
+- **Input Sync**: Player A's rotation is broadcast to Player B.
+- **State Consensus**: "If Player A explodes the star, Player B sees it explode."
+
+**Use Case**: A shared "VR" room (on flat screens) where users float in a 4D chatroom, represented by their `VIB3Actor` avatars.
+
+### 2. The Live Director (AI Agent)
+An autonomous agent (MCP-connected) that watches the "audience" (user input, webcam, mic) and adjusts the show.
+
+- **Sentiment Analysis**: If audience audio is loud/happy -> increase `speed` and `saturation`.
+- **Attention Tracking**: If user stops interacting -> trigger `FocusLock` or `Explosion` to regain attention.
+- **Generative Scripting**: The AI writes the `.vib3script` in real-time based on a prompt ("Make it scary", "Make it romantic").
+
+---
+
+## V. New MCP Tools for Ultra Tier
+
+To empower agents to build these experiences, we add the following tools:
+
+### `spawn_actor`
+Creates a `VIB3Actor` with a specific personality and role.
+```json
+{ "role": "protagonist", "personality": "glitch_witch", "system": "holographic" }
+```
+
+### `direct_scene`
+Issues a high-level direction to the `LiveDirector`.
+```json
+{ "mood": "increasing_tension", "pacing": "frenetic", "focus_target": "villain" }
+```
+
+### `configure_game_rules`
+Sets up the `HyperGame` mechanics.
+```json
+{ "physics": "lattice_heavy", "collision_damage": 10, "goal": "collect_shards" }
+```
+
+### `sync_session`
+Initializes `VIB3Link` for a multi-user session.
+```json
+{ "room_id": "lobby_1", "max_users": 4, "sync_mode": "strict" }
+```
+
+---
+
+## VI. Deep Multilayer Architecture
+
+To support `VIB3Universe`, we need a robust system for managing interactions between multiple VIB3 instances. This is not just visual layering; it's logic layering.
+
+### 1. Visual Compositing (`VIB3Compositor`)
+Managing 10+ layers (e.g., 2 instances × 5 holographic layers) requires a dedicated compositor to avoid DOM explosion and Z-fighting.
+
+*   **Render Targets**: Instead of rendering directly to the DOM, each VIB3 instance renders to an offscreen canvas.
+*   **Unified Stage**: The Compositor draws these offscreen buffers onto a single `GlobalCanvas` using WebGL blending.
+*   **Depth Sorting**: Instances are sorted by their "World Z" coordinate.
+*   **Masking**: Instances can mask each other (e.g., a character standing behind a portal).
+
+```javascript
+class VIB3Compositor {
+    registerInstance(instanceId, textureSource) { ... }
+    setLayerOrder(instanceIds) { ... }
+    render() {
+        // Draw background instances
+        // Draw foreground instances with blending
+        // Apply global post-processing (unifying the look)
+    }
+}
+```
+
+### 2. Logic Layering (`LoopCoordinator`)
+We have three distinct loops running at different frequencies:
+1.  **Physics Loop (Fixed Step, 60hz)**: Collision detection, movement integration. Deterministic for multiplayer sync.
+2.  **Narrative Loop (Event Driven)**: Script execution, state machine transitions.
+3.  **Reactive Loop (Frame Rate)**: Audio analysis, visual parameter smoothing.
+
+The `VIB3Orchestrator` must prioritize these:
+*   Physics updates *must* happen before Visual updates.
+*   Narrative events trigger Physics state changes.
+
+### 3. State Hydration (`UniverseSerializer`)
+Saving a multi-instance universe is complex. We need a schema that captures the relationships, not just individual parameters.
+
+```json
+{
+  "universe_id": "u_8823",
+  "timestamp": 12044,
+  "entities": [
+    { "id": "hero", "type": "actor", "pos": [0,0,0], "params": {...} },
+    { "id": "world", "type": "environment", "params": {...} }
+  ],
+  "global_state": {
+    "gravity": 9.8,
+    "tension": 0.4
+  }
+}
+```
+
+This allows "save games" for HyperGame and "bookmarks" for HyperNarrative.
+
+---
+
+## VII. VIB3Link Protocol
+
+VIB3Link uses WebRTC DataChannels for low-latency state synchronization between clients in a `VIB3Universe`.
+
+### Protocol Message Format
+
+Messages are JSON-encoded packets:
+```json
+{
+  "t": "type",  // 'update', 'event', 'sync'
+  "s": 1023,    // sequence number (for ordering)
+  "p": { ... }  // payload
+}
+```
+
+### Core Message Types
+
+1.  **Entity Update (`upd`)**: High-frequency (20Hz) updates of position/rotation.
+    ```json
+    { "t": "upd", "id": "actor_1", "pos": [x,y,z], "rot": [x,y,z,w] }
+    ```
+2.  **Parameter Delta (`prm`)**: When a visual parameter changes.
+    ```json
+    { "t": "prm", "id": "actor_1", "k": "chaos", "v": 0.8 }
+    ```
+3.  **Universe Event (`evt`)**: Narrative triggers or game events.
+    ```json
+    { "t": "evt", "n": "explosion", "loc": [10, 0, 5], "pow": 0.9 }
+    ```
+
+### Synchronization Strategy
+
+*   **Authority**: One client is the **Host** (orchestrator). Others are **Peers**.
+*   **Prediction**: Peers predict entity movement based on velocity.
+*   **Reconciliation**: If Peer state diverges > threshold from Host state, snap to Host.
+*   **Interpolation**: Visuals render at `t - buffer` to ensure smooth interpolation between network packets.
+
+---
+
+## VIII. HyperGame Engine
+
+The VIB3+ Ultra HyperGame Engine enables 4D First-Person View (FPV) experiences. It decouples the physics simulation from the render loop and provides a 4D-native player controller.
+
+### 1. The Game Loop (`GameLoop`)
+A fixed-timestep loop for physics and logic, separate from the variable-timestep render loop. This ensures deterministic physics and smooth rendering even under load.
+
+```javascript
+class GameLoop {
+    constructor(updateFn, renderFn) {
+        this.accumulator = 0;
+        this.step = 1 / 60; // 60hz physics
+    }
+    // ... accumulates time and calls update() multiple times if needed
+}
+```
+
+### 2. Lattice Physics (`LatticePhysics`)
+Physics in VIB3+ is not about mesh-mesh intersection. It is about **Point-Field intersection**. We define the world as a scalar field (density) and check if the player's 4D point is inside a high-density region.
+
+*   **Collision**: `getDensity(pos) > threshold`
+*   **Gravity**: Constant force in -Y (or arbitrary 4D vector)
+*   **Friction**: Velocity decay
+
+### 3. Player Controller 4D (`PlayerController4D`)
+Handles input mapping for 6-degree-of-freedom movement.
+
+*   **Input**: WASD (Translation), Mouse (Rotation), QE (Portal/4D Rotation).
+*   **State**: Position (Vec4), Rotation (Rotor4D/Quat).
+*   **Smoothing**: Inputs are smoothed to prevent motion sickness in 4D space.
+
+```javascript
+update(dt) {
+    // Apply inputs to velocity
+    // Apply physics (gravity, friction)
+    // Integrate position: pos += vel * dt
+    // Resolve collisions: if (collision) pos -= normal * penetration
+}
+```
+
+---
+
+## IX. Demo: The Crystal Labyrinth
+
+A vertical slice demo showcasing all Ultra capabilities in one cohesive experience.
+
+### Story & Premise
+The player is a **Lattice Runner** navigating a fractured 4D hyperspace maze. The goal is to collect **Resonance Crystals** (Facet engines) while avoiding **Void Shadows** (Holographic engines) that hunt based on noise (movement speed).
+
+### Gameplay Loop
+1.  **Explore**: Navigate the 4D maze using WASD+Mouse+QE.
+2.  **Collect**: Find blue crystals. Touching one triggers a `VIB3Actor` "Collection" animation (implosion + sound).
+3.  **Evade**: Red "Shadows" drift towards you. If they touch you, the screen glitches (`chromaticAberration` spike) and health drops.
+4.  **Win**: Collect 5 crystals to stabilize the universe (trigger "Victory" state).
+
+### Technical Integration
+*   **Universe**: One `VIB3Universe` managing the Player, 5 Crystal Actors, and 3 Shadow Actors.
+*   **Physics**: `LatticePhysics` handles wall collisions (fractal noise walls).
+*   **AI**: `LiveDirector` adjusts Shadow aggression based on player movement speed (stealth mechanic).
+*   **Networking**: (Optional) `VIB3Link` allows a spectator to watch the runner.
+
+---
+
+*VIB3+ Ultra — The Future of Emergent Media*
+*Draft v5.0 — Added Crystal Labyrinth Demo Design — Feb 16, 2026*

package/DOCS/EXPORT_FORMATS.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Export formats
 
 This reference documents the target export formats supported by the agentic pipelines and how they are validated.

package/DOCS/GPU_DISPOSAL_GUIDE.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # GPU disposal patterns
 
 This guide documents safe GPU resource disposal patterns to prevent memory leaks across rendering backends.

package/DOCS/HANDOFF_LANDING_PAGE.md

@@ -0,0 +1,156 @@
+Last reviewed: 2026-02-17
+
+# VIB3+ Landing Page & Marketing Handoff Prompt
+
+**Copy this entire document as the initial prompt when starting a new session focused on the landing page, marketing site, and forward-facing aspects.**
+
+---
+
+## Context
+
+You are continuing development on the **VIB3+ landing page** — the marketing/showcase site for the `@vib3code/sdk` npm package (a 4D visualization SDK). The landing page demonstrates the SDK's three rendering systems (Quantum, Faceted, Holographic) through an immersive scroll-driven experience with GSAP choreography.
+
+**Repository:** `Domusgpt/vib34d-xr-quaternion-sdk`
+**Landing page location:** `site/` directory (separated from SDK code as of 2026-02-13)
+**Live URL:** GitHub Pages deploy from `docs/` + root
+**Owner:** Clear Seas Solutions LLC / Paul Phillips
+
+## Architecture
+
+```
+site/
+├── index.html                    # Landing page (1977 lines, 9 scroll sections)
+├── styles/
+│   ├── overlay-accents.css       # CSS-only accent overlays (gradient washes, mirrors, particles)
+│   └── reveal-layers.css         # Multi-layer parallax reveal system (NEW)
+└── js/
+    ├── main.js                   # Boot script — GPU context pool + section initialization
+    ├── config.js                 # Section parameter presets (hero, morph stages, etc.)
+    ├── adapters.js               # SDK system adapters (Quantum/Holographic/Faceted + AmbientLattice)
+    ├── ContextPool.js            # WebGL context budget manager (max 3 concurrent)
+    ├── CardTiltSystem.js         # Mouse/touch → CSS 3D tilt + visualizer param mapping
+    ├── choreography.js           # Main GSAP ScrollTrigger choreography (83KB, all sections)
+    ├── overlay-choreography.js   # CSS accent overlays (gradient wash, mirror, glow, particles)
+    └── reveal-choreography.js    # Multi-layer parallax reveal transitions (NEW)
+
+Root SDK demo (separate):
+├── index.html                    # Clean SDK demo with toolbar (NOT the landing page)
+```
+
+**CDN Dependencies:** Lenis smooth scroll, GSAP 3.12.5, ScrollTrigger 3.12.5 (loaded dynamically with 5s timeout fallback)
+
+**SDK Imports:** `site/js/adapters.js` imports directly from `../src/` (Quantum, Holographic, Faceted engines). This is intentional since the site lives in the monorepo.
+
+## Current Page Sections (9 total, ~3050vh scroll)
+
+| Section | Height | GPU Contexts | Systems | Key Feature |
+|---------|--------|--------------|---------|-------------|
+| Opening Cinematic | 800vh | 1 | Quantum | SVG text mask ("VIB3CODE") + lattice parallax |
+| Hero | 100vh | 1 | Quantum | Title reveal + badge |
+| Morph Experience | 1200vh | 1 (swaps) | Q→H→F | 6-stage card morphing with system swaps |
+| Playground | static | 1 | User choice | Full parameter control (all 6D rotation planes) |
+| Triptych | 200vh | 3 | Q+H+F | 3-system split-screen simultaneous render |
+| Geometry Cascade | 400vh | 2+C2D | Q+H bg | Horizontal scroll cards with geometry showcase |
+| Energy Transfer | 250vh | 2 | Q bg + F card | Interactive sweep demo |
+| Agent Integration | static | 1 | Holographic | Download packs (MCP, Claude, OpenAI) |
+| CTA | 100vh | 2 | Q+F diagonal | Installation code + links |
+
+**Total GPU budget:** Max 3 concurrent WebGL contexts. ContextPool auto-evicts oldest.
+
+## What's Working
+
+### Choreography Engine (choreography.js — 83KB)
+- **Depth Illusion Engine** — gridDensity = distance metaphor + CSS scale/blur/shadow
+- **6 Coordination Modes** — opposition, convergence, call-response, heartbeat, energy-conservation, crossfade
+- **Mathematical parameter curves** — Lissajous rotation, sine interference, exponential ramps
+- **Section-specific timelines** — Each section has a pinned ScrollTrigger with multi-phase choreography
+- **System swaps** — Morph section smoothly transitions Q→H→F with flash effects
+
+### Overlay System (overlay-choreography.js — 35KB)
+- 5 accent systems: GradientWash, MirrorReflection, EdgeGlowRing, ParticleField, CrossfadeBridge
+- Quaternion-to-CSS bridge (feeds 4D rotation to CSS custom properties)
+- AccentChoreographer master controller
+
+### NEW: Reveal Layer System (reveal-choreography.js + reveal-layers.css)
+- **Replaces ugly SVG section dividers** with dynamic transitions
+- **8 transition patterns:** Iris aperture, diagonal bars, column split, glass panel retraction, bezel bar criss-cross, checkerboard dissolve
+- **Persistent parallax field** — Subtle geometric depth texture at 0.3x scroll speed
+- **Floating glassmorphic accent strips** — 3 colored lines at different parallax rates
+- **Glow lines** — Luminous accent lines at section boundaries (replace SVG curves)
+- **Section edge blending** — CSS gradient fades at section top/bottom (replace hard seams)
+
+## Known Issues & Priorities
+
+### HIGH PRIORITY — Visual Quality
+1. **Rectangular layout problem** — Despite excellent choreography math, everything is constrained to rectangular cards. Need organic shapes (SVG blob paths, fluid bezier boundaries, non-rectilinear clip-paths).
+2. **Predictable symmetry** — Triptych is perfect 33/33/33, CTA is 50/50 diagonal, energy is centered. Need asymmetry and visual tension.
+3. **Universal accent treatment** — Every card gets the same vignette+shadow+glow+chroma. Differentiate: some sections should get unique treatments while others stay minimal.
+4. **Mobile experience** — 3050vh total scroll on mobile is excessive. Canvas count should drop to 1 concurrent. Cascade horizontal scroll breaks at small viewports (6 cards at 88vw).
+
+### MEDIUM PRIORITY — Functionality
+5. **AmbientLattice anti-pattern** — 580-line Canvas2D renderer in adapters.js duplicates SDK geometry. Should use SDK's FacetedSystem with reduced GPU overhead instead.
+6. **No audio demo** — Audio reactivity is a key SDK feature but not demonstrated anywhere on the landing page. Add a toggle or auto-detect section.
+7. **No SpatialInput demo** — Device tilt/gyroscope is a selling point but not shown. Consider a "tilt your phone" section.
+8. **Agent section download links** — Point to `agent-config/` which may not exist in the site/ directory. Verify paths.
+
+### LOW PRIORITY — Polish
+9. **Performance profiling** — Mirror/MultiInstance overlays copy canvases via 2D context (CPU-bound). Profile on low-end devices.
+10. **Accessibility** — Many decorative elements lack `aria-hidden`. Heading hierarchy has duplicate `<h1>`. Keyboard navigation untested.
+11. **Cascade card clip-path morphing** — The 8-point polygon system (rect/hex/diamond/oct) is clever but all shapes share the same bounding box. More dramatic shape variation needed.
+
+## GSAP Pattern Reference (From Visual Codex)
+
+These patterns were studied and should inform future development:
+
+### Stagger Patterns
+- `from: "center"` with elastic easing for outward reveals
+- Grid-based: `stagger: { grid: [rows, cols], from: "edges", amount: 1.2 }`
+- Function-based: `each: (i) => i * 0.05 + Math.random() * 0.1`
+
+### 3D Transforms
+- Z-depth emergence: `fromTo(el, { z: -500, scale: 0 }, { z: 0, scale: 1 })`
+- Multi-axis spin: `{ rotationX: 720, rotationY: 540, rotationZ: 360 }` with elastic
+- `perspective: 1000px` on body, `transform-style: preserve-3d` on containers
+
+### Filter/Blur
+- Progressive blur reveal: `fromTo(el, { filter: "blur(20px)" }, { filter: "blur(0px)" })`
+- Layered blur stack: 3 layers at different blur levels, stagger `"<0.2"` relative timing
+- Glassmorphism: `backdrop-filter: blur(20px)` on panels
+
+### Multi-Visualizer Choreography
+- 5-phase scroll modes: Intro→Grid→Carousel→Expand→Finale
+- Impulse system: `targets.impulse = Math.min(targets.impulse + intensity, 1.5)`, decays at 92%/frame
+- Scrub smoothing: `scrub: 0.3` (300ms delay)
+
+## Design Direction
+
+The current page has **world-class mathematical choreography** trapped in a **rigid rectangular grid**. The goal is to break free with:
+
+1. **Multiple parallax layers** — Not just 2. Different areas should have different layer counts and behaviors (columns in one area, concentric iris in another, diagonal bars in a third).
+2. **Negative space** — Solid layers with cutouts that reveal visualizers. The visualizers shine THROUGH the design, not inside rectangular boxes.
+3. **Organic boundaries** — SVG blob paths, fluid beziers, non-rectangular clip-paths. Nothing should be a perfect rectangle.
+4. **Asymmetrical compositions** — Break the grid. Unequal column widths, off-center elements, visual tension.
+5. **Varied visual vocabulary** — Not every section needs every effect. Some should be minimal and clean, others dramatic and layered.
+6. **Glass morphism as a design language** — Frosted glass panels that slide, morph, and shatter to reveal content.
+
+## Commands
+
+```bash
+# From project root:
+pnpm dev                         # Opens dev server (default: docs gallery)
+# Then navigate to /site/index.html for landing page
+# Or / for SDK demo
+
+# To verify no SDK regressions:
+pnpm test
+```
+
+## Session Instructions
+
+1. Read `site/index.html` for the full HTML structure
+2. Read `site/js/choreography.js` for the existing scroll timeline (it's 83KB — skim the section-level functions)
+3. Read `site/js/reveal-choreography.js` for the new overlay layer system
+4. **Do not break existing choreography** — the new system layers ON TOP
+5. Test in browser after changes — the page relies on CDN-loaded GSAP
+6. Focus on the visual quality issues listed above
+7. Use the GSAP pattern reference for implementation guidance