@vib3code/sdk 2.0.1 → 2.0.3-canary.75a3290

package/DOCS/PRODUCT_STRATEGY.md

@@ -0,0 +1,63 @@
+# Product Strategy
+
+## Purpose
+VIB3+ SDK is positioned as a programmable 4D/6D visualization platform for product teams, creative technologists, and AI-native experiences that need high-fidelity real-time graphics with practical integration pathways.
+
+## Target Users & Personas
+
+| Persona | Primary Goals | Key Needs from VIB3+ |
+|---|---|---|
+| **Creative Developer** (web/interactive engineer) | Ship differentiated visual experiences quickly | Stable core engine APIs, fast iteration, framework adapters, predictable performance |
+| **Experience Designer / Technical Artist** | Produce immersive scenes and effects with minimal low-level shader work | Rich preset system, post-processing/easing/timeline controls, export options |
+| **Platform Integrator** (SaaS/product team) | Embed visuals into production apps with operational confidence | Clear lifecycle model, telemetry hooks, testability, long-term compatibility |
+| **AI/Agent Builder** | Automate generation, tuning, and operation of visual scenes | Agent tooling, MCP/CLI interfaces, machine-readable docs, guardrails |
+| **Immersive/XR Team** | Extend visuals to VR/AR and spatial interfaces | Advanced rendering path, input abstraction, GPU-aware architecture |
+
+## Core Use-Cases
+1. **Interactive Product Surfaces:** add performant, controllable visual systems to dashboards, landing pages, and app canvases.
+2. **Creative Production Pipelines:** drive visuals via presets, timelines, and reactive input for streaming/live-performance contexts.
+3. **Cross-Framework SDK Embeds:** integrate once and deploy in React/Vue/Svelte and custom JS runtimes.
+4. **AI-Orchestrated Visual Systems:** use agent APIs to generate, mutate, and validate visual behaviors programmatically.
+5. **Advanced Runtime Modes:** run high-end features (WebXR, compute, worker rendering, MIDI, AI preset generation) where supported.
+
+## Differentiation
+- **Unified 4D/6D control model** across multiple systems instead of one-off demos.
+- **Production-oriented SDK structure** with clear module boundaries for core, integrations, advanced capabilities, and agent tooling.
+- **Agent-first operability** (MCP + CLI + telemetry orientation) to support autonomous and assisted workflows.
+- **Breadth of integration targets** (frameworks, creative tools, exports) that reduce adoption friction.
+- **Performance-conscious architecture** that can scale from standard web canvases to XR/compute-enabled environments.
+
+## Monetization & Licensing Assumptions
+- **Open-core distribution assumption:** MIT-licensed base SDK remains the adoption driver.
+- **Commercial expansion assumptions:** monetizable add-ons can include premium integrations, enterprise support, managed tooling, and hosted collaboration/telemetry services.
+- **Tiering hypothesis:**
+  - **Community:** core engine + basic integrations.
+  - **Pro:** advanced feature packs, commercial support SLA, enhanced export/tooling.
+  - **Enterprise:** governance features, private support, compliance-oriented integration hardening.
+- **Success dependency:** maintain low-friction developer onboarding while creating high-value operational capabilities for teams running VIB3+ at scale.
+
+## Success Metrics
+
+### Adoption Metrics
+- Weekly active projects using VIB3+ SDK.
+- Net-new installs and retained projects after 30/90 days.
+- Conversion rate from prototype usage to production deployment.
+
+### Performance Metrics
+- Median and P95 frame-time under representative scenes.
+- GPU/CPU utilization envelopes across supported devices.
+- Initialization latency and system-switch latency.
+
+### Integration Usage Metrics
+- Usage distribution across framework integrations (`react`, `vue`, `svelte`, etc.).
+- Activation rate of advanced modules (XR, WebGPU, worker, MIDI, AI).
+- Agent tooling usage (CLI commands, MCP tool call volume, successful automated workflows).
+
+## Strategy-to-Architecture Alignment
+Strategy execution depends on keeping the following module families healthy and composable:
+- **Engine/core quality:** `src/core/`
+- **Integrations:** `src/integrations/`
+- **Advanced features:** `src/advanced/`
+- **Agent tooling:** `src/agent/`
+
+Roadmap-level epics that operationalize these goals are documented in [`DOCS/ROADMAP.md`](./ROADMAP.md).

package/DOCS/README.md

@@ -0,0 +1,103 @@
+# Documentation Index
+
+## Strategy & Planning
+- [`PRODUCT_STRATEGY.md`](./PRODUCT_STRATEGY.md) — product direction, personas, differentiation, monetization assumptions, and success metrics.
+- [`ROADMAP.md`](./ROADMAP.md) — strategy goals mapped to technical epics and module ownership.
+
+## Core References
+- [`SYSTEM_INVENTORY.md`](./SYSTEM_INVENTORY.md)
+- [`CONTROL_REFERENCE.md`](./CONTROL_REFERENCE.md)
+- [`CLI_ONBOARDING.md`](./CLI_ONBOARDING.md)
+- [`REPO_MANIFEST.md`](./REPO_MANIFEST.md)
+
+## Performance / Rendering / Platform
+- [`WEBGPU_STATUS.md`](./WEBGPU_STATUS.md)
+- [`XR_BENCHMARKS.md`](./XR_BENCHMARKS.md)
+- [`RENDERER_LIFECYCLE.md`](./RENDERER_LIFECYCLE.md)
+- [`GPU_DISPOSAL_GUIDE.md`](./GPU_DISPOSAL_GUIDE.md)
+
+## Setup / Operations
+- [`ENV_SETUP.md`](./ENV_SETUP.md)
+- [`PROJECT_SETUP.md`](./PROJECT_SETUP.md)
+- [`CI_TESTING.md`](./CI_TESTING.md)
+# Documentation index
+
+This folder contains active and archived project documentation.
+
+## Archive policy
+
+To keep links stable while allowing historical retention:
+
+- **Active docs** live at `DOCS/<name>.md` and are referenced by default from onboarding and root docs.
+- **Archived docs** live at `DOCS/archive/<name>.md` and must be labeled as archived anywhere they are linked.
+- Before moving any doc to `DOCS/archive/`, update all inbound markdown links with:
+  - `rg -n "<doc-name>.md" -g '*.md'`
+- If a document is still intended as a primary reference, keep or restore a canonical copy at `DOCS/<name>.md` and add an archive notice in the archived variant.
+- For date-stamped reports, prefer linking directly to `DOCS/archive/...` from inventories and READMEs with `(archived)` in the description.
+
+## Link maintenance checklist
+
+1. Search all markdown references before and after a move.
+2. Update stale links in `README.md`, onboarding docs, and inventories first.
+3. Confirm no stale references remain with:
+   - `rg -n "DOCS/(SYSTEM_AUDIT_2026-01-30|DEV_TRACK_ANALYSIS)\.md" -g '*.md'`
+# Documentation Index
+
+This file is the root index for all project documentation.
+
+## Start Here
+
+Use these canonical documents first:
+
+| Topic | Canonical document | Source of truth | Owner | Last reviewed |
+|---|---|---|---|---|
+| Architecture | [`DOCS/SYSTEM_INVENTORY.md`](./SYSTEM_INVENTORY.md) | ✅ System boundaries, modules, and capabilities | SDK Architecture | 2026-02-12 |
+| Product Strategy | [`DOCS/LICENSING_TIERS.md`](./LICENSING_TIERS.md) | ✅ Packaging, positioning, and commercial model | Product | 2026-02-12 |
+| Master Plan | [`DOCS/MASTER_PLAN_2026-01-31.md`](./MASTER_PLAN_2026-01-31.md) | ✅ Program-level priorities and sequencing | Program Management | 2026-02-12 |
+| Dev Track | [`DOCS/DEV_TRACK_SESSION_2026-02-06.md`](./DEV_TRACK_SESSION_2026-02-06.md) | ✅ Current implementation log and execution status | Engineering | 2026-02-12 |
+
+## Reading Paths by Persona
+
+### New engineer
+1. [`DOCS/PROJECT_SETUP.md`](./PROJECT_SETUP.md)
+2. [`DOCS/ENV_SETUP.md`](./ENV_SETUP.md)
+3. [`DOCS/SYSTEM_INVENTORY.md`](./SYSTEM_INVENTORY.md)
+4. [`DOCS/CONTROL_REFERENCE.md`](./CONTROL_REFERENCE.md)
+5. [`DOCS/CI_TESTING.md`](./CI_TESTING.md)
+
+### AI agent
+1. [`DOCS/CLI_ONBOARDING.md`](./CLI_ONBOARDING.md)
+2. [`DOCS/REPO_MANIFEST.md`](./REPO_MANIFEST.md)
+3. [`DOCS/SYSTEM_INVENTORY.md`](./SYSTEM_INVENTORY.md)
+4. [`DOCS/MASTER_PLAN_2026-01-31.md`](./MASTER_PLAN_2026-01-31.md)
+5. Latest dev track session (currently [`DOCS/DEV_TRACK_SESSION_2026-02-06.md`](./DEV_TRACK_SESSION_2026-02-06.md))
+
+### Product lead
+1. [`DOCS/LICENSING_TIERS.md`](./LICENSING_TIERS.md)
+2. [`DOCS/MASTER_PLAN_2026-01-31.md`](./MASTER_PLAN_2026-01-31.md)
+3. [`DOCS/WEBGPU_STATUS.md`](./WEBGPU_STATUS.md)
+4. [`DOCS/XR_BENCHMARKS.md`](./XR_BENCHMARKS.md)
+5. [`DOCS/TELEMETRY_EXPORTS.md`](./TELEMETRY_EXPORTS.md)
+
+### Contributor
+1. [`CONTRIBUTING.md`](../CONTRIBUTING.md)
+2. [`DOCS/PROJECT_SETUP.md`](./PROJECT_SETUP.md)
+3. [`DOCS/CI_TESTING.md`](./CI_TESTING.md)
+4. [`DOCS/RENDERER_LIFECYCLE.md`](./RENDERER_LIFECYCLE.md)
+5. [`DOCS/GPU_DISPOSAL_GUIDE.md`](./GPU_DISPOSAL_GUIDE.md)
+
+## Documentation Taxonomy
+
+| Category | Scope | Primary files |
+|---|---|---|
+| Architecture | Runtime model, systems, lifecycles, controls | [`SYSTEM_INVENTORY.md`](./SYSTEM_INVENTORY.md) **(SOT)**, [`RENDERER_LIFECYCLE.md`](./RENDERER_LIFECYCLE.md), [`CONTROL_REFERENCE.md`](./CONTROL_REFERENCE.md), [`GPU_DISPOSAL_GUIDE.md`](./GPU_DISPOSAL_GUIDE.md) |
+| Planning | Strategy, roadmap, execution direction | [`MASTER_PLAN_2026-01-31.md`](./MASTER_PLAN_2026-01-31.md) **(SOT)**, [`DEV_TRACK_SESSION_2026-02-06.md`](./DEV_TRACK_SESSION_2026-02-06.md) **(SOT for active sprint log)**, [`DEV_TRACK_SESSION_2026-01-31.md`](./DEV_TRACK_SESSION_2026-01-31.md), [`LICENSING_TIERS.md`](./LICENSING_TIERS.md) **(SOT for product packaging)** |
+| Operations | Setup, CI, runbooks, observability | [`PROJECT_SETUP.md`](./PROJECT_SETUP.md) **(SOT for project bootstrap)**, [`ENV_SETUP.md`](./ENV_SETUP.md), [`CI_TESTING.md`](./CI_TESTING.md), [`OBS_SETUP_GUIDE.md`](./OBS_SETUP_GUIDE.md), [`TELEMETRY_EXPORTS.md`](./TELEMETRY_EXPORTS.md) |
+| Analysis | Benchmarks, visual analysis, design studies | [`WEBGPU_STATUS.md`](./WEBGPU_STATUS.md), [`XR_BENCHMARKS.md`](./XR_BENCHMARKS.md), [`CROSS_SITE_DESIGN_PATTERNS.md`](./CROSS_SITE_DESIGN_PATTERNS.md), `VISUAL_ANALYSIS_*.md`, [`REFERENCE_SCROLL_ANALYSIS.md`](./REFERENCE_SCROLL_ANALYSIS.md) |
+| Archive | Historical plans and audits retained for traceability | [`archive/`](./archive/) including [`archive/SYSTEM_AUDIT_2026-01-30.md`](./archive/SYSTEM_AUDIT_2026-01-30.md), [`archive/STRATEGIC_BLUEPRINT_2026-01-07.md`](./archive/STRATEGIC_BLUEPRINT_2026-01-07.md), [`archive/SESSION_LOG_2026-01-07.md`](./archive/SESSION_LOG_2026-01-07.md) |
+
+## Source of Truth Rules
+
+- Each topic should have one authoritative file; supporting docs should link back to that canonical file.
+- When creating a new doc, assign it to a taxonomy category and mark whether it is canonical or supporting.
+- If a canonical file changes, update `Last reviewed` and verify inbound links from this index.

package/DOCS/REFERENCE_SCROLL_ANALYSIS.md

@@ -0,0 +1,97 @@
+# Reference Site Scroll Effect Analysis
+
+**Updated: 2026-02-10**
+**Status**: COMPLETE — Visual analysis via Playwright screenshots + source-code parsing.
+
+---
+
+## Methodology
+
+### Phase 1: Source-Code Analysis (HTML/CSS parsing)
+Extracted CSS transition durations, easing functions, framework IDs, class patterns.
+
+### Phase 2: Visual Analysis (Playwright screenshots)
+Captured real Chromium screenshots at 8-11 scroll positions per site using wheel-based scrolling (triggers Lenis/GSAP animations). Tool: `tools/site-analyzer.mjs` with local proxy forwarder.
+
+---
+
+## Sites Analyzed
+
+| # | URL | Framework | Status |
+|---|-----|-----------|--------|
+| 1 | weare-simone.webflow.io | Webflow + GSAP + Lenis + SplitType | COMPLETE |
+| 2 | facetad.com | Wix Thunderbolt + Lenis | COMPLETE |
+| 3 | clickerss.com | Wix Thunderbolt + View Transitions API | COMPLETE |
+| 4 | tableside.com.au | Wix Thunderbolt | COMPLETE |
+| 5 | wix.com/studio/inspiration/space | Wix Studio | 404 (page removed) |
+
+### Detailed Analysis Documents
+- `DOCS/VISUAL_ANALYSIS_SIMONE.md` — Frame-by-frame + 7 design patterns
+- `DOCS/VISUAL_ANALYSIS_FACETAD.md` — Frame-by-frame + 6 design patterns
+- `DOCS/VISUAL_ANALYSIS_CLICKERSS.md` — Frame-by-frame + 5 design patterns
+- `DOCS/VISUAL_ANALYSIS_TABLESIDE.md` — Frame-by-frame + 5 design patterns
+- `DOCS/CROSS_SITE_DESIGN_PATTERNS.md` — Synthesized actionable patterns + priority actions
+
+---
+
+## Source-Code Findings (Verified from HTML/CSS)
+
+### CSS Transition Patterns
+
+**clickerss.com:**
+- View Transition API with named groups (header-group, footer-group, page-group)
+- Slide transitions: 0.6s `cubic-bezier(.83,0,.17,1)`
+- Multi-state opacity classes with different easings per state
+- Marquee animation: `40s linear infinite` with pause-on-hover
+- **Visual confirmation**: Massive B&W hero photo, serif text-image interweaving, typography-as-CTA footer
+
+**facetad.com:**
+- Lenis smooth scroll: `lerp: 0.1`, `wheelMultiplier: 0.7`
+- 4-layer background compositing (base + masked image + blend overlay + shadow)
+- Dynamic z-index via `data-z-counter` attributes
+- **Visual confirmation**: Parallelogram clip-path images, diagonal section dividers, scattered gallery with z-stacking, diagonal cream→red color transition
+
+**tableside.com.au:**
+- Blur-to-sharp load: `blur(9px) → blur(0)` over 0.8s
+- Fixed pinned overlay layer system
+- 9+ hamburger icon animation variants with multi-line stagger
+- **Visual confirmation**: Bold coral/cream/navy three-tone palette, variable-size portfolio cards, split-color footer (vertical cream/navy)
+
+**weare-simone.webflow.io:**
+- SplitType character-level text reveals with `y: "100%"` stagger
+- Dark/light mode threshold switching at 2% viewport band
+- GSAP Flip.js navigation shape morphing (0.4s power2.out)
+- **Visual confirmation**: Giant wordmark hero, hard cream→dark-teal mode switch, zigzag asymmetric case study cards, floating product images, marquee CTA, outlined typography echo at footer
+
+---
+
+## Visual Findings Summary
+
+### Pattern Verification Results
+
+| Pattern (from CSS) | Visual Result |
+|---|---|
+| Multi-stage opacity | Could not test — requires interaction capture |
+| Character reveal from below | SplitType present but needs JS trigger, not visible in static screenshots |
+| Blur rack-focus | Not visible in screenshots — happens at load time |
+| 4-layer compositing depth | Facetad confirms depth via parallelogram z-stacking, not traditional parallax |
+| Dark/light threshold (Simone) | CONFIRMED — hard snap at section boundary, very dramatic |
+| Card overlap stacking | CONFIRMED (Simone) — creates real depth with zigzag alternation |
+| Lenis momentum | Cannot test in screenshots — requires scroll-feel testing |
+
+### Newly Discovered Patterns (Not in source code)
+
+These patterns were discovered through visual analysis that could NOT be inferred from source code:
+
+1. **Parallelogram clip-path galleries** (Facetad) — images all use skewed non-rectangular shapes
+2. **Diagonal section dividers** (Facetad) — 30-40deg angle, consistent site-wide
+3. **Text-image interweaving** (Clickerss) — massive text overlaps/shares space with images
+4. **Variable card sizing** (Tableside) — portfolio cards deliberately vary in height
+5. **Split-color sections** (Tableside) — vertical cream/navy split in footer
+6. **Extreme negative space** (Facetad) — hero is 95% empty, one line of text
+7. **Typography-as-CTA** (Clickerss) — viewport-filling text IS the call-to-action
+8. **Footer typography echo** (Simone) — hero's filled wordmark becomes outlined strokes at footer
+
+---
+
+*Analysis complete. See CROSS_SITE_DESIGN_PATTERNS.md for actionable VIB3+ implementation plan.*

package/DOCS/ROADMAP.md

@@ -0,0 +1,111 @@
+# Strategic Roadmap
+
+This roadmap maps product strategy goals from [`DOCS/PRODUCT_STRATEGY.md`](./PRODUCT_STRATEGY.md) to technical epics and the primary module ownership areas.
+
+## Goal-to-Epic Mapping
+
+| Strategy Goal | Technical Epic | Primary Module(s) | Representative Outcomes |
+|---|---|---|---|
+| Increase developer adoption and time-to-first-value | **Epic A: Engine Reliability & DX Foundation** | `src/core/` | Faster setup, safer defaults, stronger API consistency, fewer integration regressions |
+| Expand production integrations across frameworks and tools | **Epic B: Integration Surface Expansion** | `src/integrations/` | Stable adapters, clearer compatibility matrix, improved framework lifecycle parity |
+| Deliver differentiated high-end capabilities | **Epic C: Advanced Runtime Capability Layer** | `src/advanced/` | Maturity of XR/WebGPU/worker/MIDI/AI features with progressive enhancement |
+| Enable AI-native and autonomous workflows | **Epic D: Agent Tooling & Automation Plane** | `src/agent/` | More robust MCP/CLI operations, automation-safe contracts, better observability |
+| Prove performance and enterprise readiness | **Epic E: Measurable Quality & Operability** | `src/core/`, `src/integrations/`, `src/advanced/`, `src/agent/` | Telemetry-driven performance baselines, integration usage analytics, release confidence |
+
+## Epic Details
+
+### Epic A — Engine Reliability & DX Foundation (`src/core/`)
+- Harden lifecycle management and error semantics.
+- Improve parameter validation and migration compatibility.
+- Establish performance budgets (frame-time, init time, memory envelopes).
+- Expand deterministic test coverage for system switching and geometry/rotation paths.
+
+### Epic B — Integration Surface Expansion (`src/integrations/`)
+- Standardize adapter contracts across React/Vue/Svelte and other supported integrations.
+- Improve SSR/hydration safety and runtime capability detection.
+- Publish integration-level examples and troubleshooting baselines.
+- Track adapter usage and breakage signals by runtime/framework version.
+
+### Epic C — Advanced Runtime Capability Layer (`src/advanced/`)
+- Mature feature gating and fallback behavior for XR/WebGPU/worker contexts.
+- Define quality levels for advanced features with explicit hardware constraints.
+- Improve interoperability between advanced modules and core parameter controls.
+- Add scenario-based benchmarks for high-complexity scenes.
+
+### Epic D — Agent Tooling & Automation Plane (`src/agent/`)
+- Stabilize MCP and CLI command contracts for autonomous agents.
+- Improve schema validation, command discoverability, and failure diagnostics.
+- Add policy and safety guardrails for generated presets/actions.
+- Instrument end-to-end agent workflows for reliability and latency.
+
+### Epic E — Measurable Quality & Operability (Cross-cutting)
+- Create a unified KPI pipeline for adoption, performance, and integration usage.
+- Define release gates tied to strategy metrics (P95 frame-time, integration pass rates).
+- Establish long-running regression suites across representative environments.
+- Align docs and onboarding with telemetry-informed friction points.
+
+## Suggested Milestones
+
+| Milestone | Focus | Success Signal |
+|---|---|---|
+| **M1: Core Confidence** | Epic A + baseline Epic E instrumentation | Reduced regressions, improved startup latency, stronger API stability |
+| **M2: Integration Scale** | Epic B + cross-framework QA | Higher integration adoption and lower support burden |
+| **M3: Advanced Differentiation** | Epic C with measurable fallback quality | Increased use of advanced modules without reliability drop |
+| **M4: Agentic Operations** | Epic D + operational telemetry | Reliable automated workflows and growing agent-tooling utilization |
+
+## Module Ownership Summary
+- **`src/core/`** anchors reliability, performance, and API continuity.
+- **`src/integrations/`** drives ecosystem reach and developer adoption.
+- **`src/advanced/`** delivers premium differentiation and future-facing capabilities.
+- **`src/agent/`** enables AI-native operation, orchestration, and scale.
+# VIB3 SDK Roadmap
+
+This roadmap tracks delivery milestones by quarter with explicit status signals, ownership, and dependencies to active code paths.
+
+## Status Legend
+
+- **Planned**: Not started, scoped for target quarter.
+- **In Progress**: Active engineering work is underway.
+- **Blocked**: Waiting on dependency, design decision, or infra.
+- **Done**: Delivered and verified.
+
+## What changed this week
+
+- Consolidated historical session logs into `DOCS/dev-tracks/` so day-to-day notes are archived but still discoverable from milestones.
+- Added this quarterly roadmap as the single front door for progress and status.
+- Linked current milestones to concrete code-path dependencies and evidence docs to reduce context-hunting.
+
+## 2026 Q1 Milestones
+
+| Milestone | Status | Owner | Target date | Dependency links (code paths) | Evidence |
+|---|---|---|---|---|---|
+| Stabilize core rendering + lifecycle contracts | **In Progress** | Core Runtime Team | 2026-03-31 | `src/core/`, `src/core/renderers/`, `src/viewer/` | [Dev Track 2026-02-06](dev-tracks/DEV_TRACK_SESSION_2026-02-06.md), [Renderer lifecycle notes](RENDERER_LIFECYCLE.md) |
+| Ship MCP/agent integration hardening | **In Progress** | Agent Platform Team | 2026-03-31 | `src/agent/`, `src/integrations/`, `tools/` | [Dev Track 2026-02-06](dev-tracks/DEV_TRACK_SESSION_2026-02-06.md), [CLI onboarding](CLI_ONBOARDING.md) |
+| Eliminate known export + packaging regressions | **Done** | Release Engineering | 2026-02-15 | `src/export/`, `types/`, `tools/` | [Dev Track 2026-01-31](dev-tracks/DEV_TRACK_SESSION_2026-01-31.md), [Master plan](MASTER_PLAN_2026-01-31.md) |
+
+## 2026 Q2 Milestones
+
+| Milestone | Status | Owner | Target date | Dependency links (code paths) | Evidence |
+|---|---|---|---|---|---|
+| Advanced visualization subsystem parity | **Planned** | Graphics Team | 2026-06-30 | `src/advanced/`, `src/shaders/`, `src/holograms/` | [WebGPU status](WEBGPU_STATUS.md), [XR benchmarks](XR_BENCHMARKS.md) |
+| Cross-platform integration SDK examples refresh | **Planned** | Developer Experience Team | 2026-06-15 | `src/integrations/`, `examples/`, `tools/` | [Project setup](PROJECT_SETUP.md), [Env setup](ENV_SETUP.md) |
+| Observability + telemetry export baseline | **Blocked** | Data & Ops | 2026-06-30 | `src/telemetry/`, `tools/`, `src/core/` | [Telemetry exports](TELEMETRY_EXPORTS.md), [CI testing](CI_TESTING.md) |
+
+## 2026 Q3 Milestones
+
+| Milestone | Status | Owner | Target date | Dependency links (code paths) | Evidence |
+|---|---|---|---|---|---|
+| Public API reference + docs site automation | **Planned** | Documentation Team | 2026-09-30 | `src/`, `types/`, `tools/` | [Repo manifest](REPO_MANIFEST.md), [System inventory](SYSTEM_INVENTORY.md) |
+| Production-ready web tooling for builders | **Planned** | Tooling Team | 2026-09-15 | `tools/`, `src/integrations/`, `src/cli/` | [CLI onboarding](CLI_ONBOARDING.md), [Export formats](EXPORT_FORMATS.md) |
+
+## 2026 Q4 Milestones
+
+| Milestone | Status | Owner | Target date | Dependency links (code paths) | Evidence |
+|---|---|---|---|---|---|
+| Platform reliability + perf hardening | **Planned** | Platform Team | 2026-12-15 | `src/core/`, `src/advanced/`, `tools/` | [GPU disposal guide](GPU_DISPOSAL_GUIDE.md), [CI testing](CI_TESTING.md) |
+| Community and ecosystem expansion package | **Planned** | Ecosystem Team | 2026-12-31 | `src/integrations/`, `examples/`, `tools/` | [Cross-site design patterns](CROSS_SITE_DESIGN_PATTERNS.md), [Multiviz choreography](MULTIVIZ_CHOREOGRAPHY_PATTERNS.md) |
+
+## Historical log policy
+
+- Detailed, date-based implementation logs live in `DOCS/archive/` or `DOCS/dev-tracks/`.
+- Roadmap milestones link to those logs as evidence, so progress is visible without opening multiple dated files.

package/DOCS/SCROLL_TIMELINE_v3.md

@@ -0,0 +1,269 @@
+# VIB3+ Landing Page — Complete Scroll Timeline v3
+
+## GPU-First Redesign: Real Visualizers Everywhere
+
+**Core principle**: Canvas2D (AmbientLattice) is ONLY for the cascade cards (small cards where GPU contexts would be wasted). Every section background, every dramatic moment uses REAL GPU systems — Quantum, Holographic, Faceted — in coordinated multi-system arrangements.
+
+**ContextPool budget**: Max 3 concurrent. Sections are sequential + pinned, so we acquire/release at boundaries.
+
+---
+
+## SCROLL MAP (Approximate vh positions)
+
+```
+Position    Section              GPU Contexts Active        Multi-System Events
+─────────── ──────────────────── ─────────────────────────── ─────────────────────────
+0-800vh     OPENING              1: Quantum (opening)        Solo: canvas → text mask → lattice
+~800vh      divider              0→1 swap                    Portal glow transition
+800-900vh   HERO                 1: Quantum (hero)           Solo: parameter arc builds energy
+~900vh      divider              1→1 swap                    Flash handoff hero→morph
+900-2100vh  MORPH (pinned)       1: Q→H→F rotating          System swap choreography
+~2100vh     divider              1→1                         Portal out
+2100-2400vh PLAYGROUND           1: user-controlled          Interactive — user drives
+~2400vh     divider              1→3 acquire                 Three-system awakening
+2400-2600vh TRIPTYCH             3: Q+H+F split-screen       ★ CLIP-PATH TERRITORY WAR
+~2600vh     divider              3→2 swap                    ★ TRIPTYCH→CASCADE HANDOFF
+2600-3000vh CASCADE (pinned)     2: Q+H background           ★ DUAL GPU BEHIND CARDS
+                                  + Canvas2D cards            GPU systems react to active card
+~3000vh     divider              2→2 swap                    ★ CASCADE→ENERGY HANDOFF
+3000-3250vh ENERGY (pinned)      2: Q bg + F card            ★ TWO-SYSTEM ENERGY EXCHANGE
+~3250vh     divider              2→1                         Drain → agent
+3250-3400vh AGENT                1: H background             GPU holographic behind code
+~3400vh     divider              1→2 acquire                 ★ FINALE BUILDS
+3400-3500vh CTA                  2: Q+F dueling              ★ DUAL SYSTEM FINALE
+~3500vh     footer               0                           Silence
+```
+
+---
+
+## SECTION-BY-SECTION CHOREOGRAPHY
+
+### 1. OPENING (0-800vh) — Solo Quantum
+
+**GPU**: 1 context (Quantum → `opening-canvas`)
+**Multi-system**: None (intentional — solo introduction)
+
+| Scroll %  | Phase                    | Parameters                          |
+|-----------|--------------------------|-------------------------------------|
+| 0-12%     | Dark canvas, subtle      | intensity: 0.3→0.5, geo: 11        |
+| 12-35%    | Text letters cascade in  | hue: 220→280, rot4dXW accelerates   |
+| 28-48%    | SVG mask: canvas through text | chaos: 0.05→0.4, speed rises    |
+| 45-75%    | Lattice parallax layers  | gridDensity oscillates, dimension drops |
+| 74-96%    | Text fades, lattice locks| speed settles, intensity peaks 0.85 |
+| 96-100%   | Everything fades out     | intensity→0                         |
+
+---
+
+### 2. HERO (800-900vh) — Solo Quantum
+
+**GPU**: 1 context (Quantum → `hero-canvas`)
+
+| Scroll %  | Phase                    | Parameters                          |
+|-----------|--------------------------|-------------------------------------|
+| 0-25%     | Calm lattice, badges in  | geo: 3, speed: 0.4, chaos: 0.05    |
+| 25-55%    | Geometry shift, energy builds | geo: 2→4, rot4dXW ramps, density↑ |
+| 55-80%    | Peak energy              | hue sweeps 210→290, chaos↑, morph peaks |
+| 80-100%   | Dramatic 4D rotation burst | rot4dZW spike, dimension drops     |
+
+Content: Badge → title chars → subtitle → system label → scroll indicator
+
+---
+
+### 3. MORPH (900-2100vh pinned) — Rotating Single System
+
+**GPU**: 1 context, swaps Q(stages 0-1) → H(stages 2-3) → F(stages 4-5)
+
+6 stages, each ~200vh:
+- **Emergence**: Low density, slow, Quantum
+- **Dimensional Shift**: rot4dXW ramps, Quantum
+- **Three Voices**: Voice labels appear, Holographic
+- **Convergence**: Card grows, density peaks, Holographic
+- **Spectral Rupture**: Card near-fullscreen, max chaos/speed, Faceted
+- **Resolution**: Card shrinks, calm, Faceted
+
+Card morphs: circle → rounded rect → holds → grows → near-fullscreen → medium
+
+---
+
+### 4. PLAYGROUND (2100-2400vh) — User-Controlled
+
+**GPU**: 1 context (user picks Q/H/F)
+No choreography — user drives all params via sliders.
+
+---
+
+### 5. TRIPTYCH (2400-2600vh) — ★ THREE-SYSTEM SPLIT-SCREEN
+
+**GPU**: 3 contexts (Quantum left, Holographic center, Faceted right)
+
+This is the first multi-system moment. All 3 visualization engines running simultaneously.
+
+| Scroll %  | Phase                        | Coordination Event                      |
+|-----------|------------------------------|-----------------------------------------|
+| 0-15%     | Columns slide in             | Left dominates (40% width), right small (26%) |
+| 15-30%    | Systems differentiate        | Triadic hue rotation, phase-locked 4D rotation at 120° offsets |
+| 30-50%    | ★ CONVERGENCE                | Columns equalize, shared heartbeat peaks, hues pull toward unity |
+| 50-70%    | Call & response              | Left chaos → center speed → right morph (chain reaction) |
+| 70-85%    | Right dominates              | Split lines shift: right takes 40%, left shrinks to 26% |
+| 85-100%   | ★ CRYSTALLIZATION BRIDGE     | All 3 systems: density↑↑, speed→0, chaos→0 (frozen moment) |
+
+**Coordination signals** (all running simultaneously):
+1. **Shared heartbeat**: `sin(p * PI * 2)` — pulse all 3 systems breathe to
+2. **Energy conservation**: total intensity ≈ 2.0 distributed across 3 systems
+3. **Triadic hue**: base rotates, each system 120° apart, converges at midpoint
+4. **Phase-locked 4D**: rot4dXW at 0°, 120°, 240° — a coordinated 4D dance
+5. **Density cross-feed**: left ramps up, right ramps down, center bridges
+6. **Call & response**: left chaos → center speed → right morphFactor chain
+7. **Mouse X shifts split lines**: cursor position moves column boundaries ±6%
+
+---
+
+### 6. CASCADE (2600-3000vh pinned) — ★ DUAL GPU + Canvas2D Cards
+
+**GPU**: 2 contexts (Quantum + Holographic as shared background)
+**Canvas2D**: AmbientLattice for individual card faces only
+
+**NEW**: Two real GPU systems render as a SPLIT-SCREEN BACKGROUND behind the scrolling cards. As the active card changes, the GPU backgrounds react — one mirrors the card's geometry, the other plays the complementary opposite. The card scroll position drives the split line between the two GPU backgrounds.
+
+| Scroll %  | Phase                         | GPU Background Behavior                |
+|-----------|-------------------------------|----------------------------------------|
+| 0-10%     | Cards enter with stagger      | Q+H backgrounds fade in, split 50/50   |
+| 10-30%    | Card 0 active (Tetra, 190°)   | Q mirrors: geo 0, hue 190. H opposes: geo 16, hue 10 |
+| 30-50%    | Card 1 active (HTorus, 300°)  | Q: geo 11, hue 300. H: geo 5, hue 120  |
+| 50-70%    | Card 2 active (HTetra, 35°)   | Q: geo 16, hue 35. H: geo 2, hue 215   |
+| 70-90%    | Card 3+ active                | Split line tracks card position         |
+| 90-100%   | Cards exit, GPUs crystallize  | Both systems converge to same params    |
+
+**Card-GPU coordination**:
+- Active card's AmbientLattice params echo into GPU backgrounds (dampened)
+- GPU backgrounds' rotation drives CSS `--q-xw` for card tilt effects
+- Split between Q and H follows mouse X position ±15% from center
+- When cards cross the GPU split line: flash transition, hue swap
+
+---
+
+### 7. ENERGY (3000-3250vh pinned) — ★ TWO-SYSTEM ENERGY EXCHANGE
+
+**GPU**: 2 contexts (Quantum background + Faceted card)
+
+Two real GPU systems that actively EXCHANGE energy through the GSAP timeline.
+
+| Scroll %  | Phase                         | Multi-System Event                      |
+|-----------|-------------------------------|-----------------------------------------|
+| 0-15%     | BG awakens, card enters       | Q bg: low intensity. F card: rising from below |
+| 15-30%    | Card overshoot + settle       | Q bg: responds to card motion — intensifies as card peaks |
+| 30-50%    | Hold — tilt interactive       | Q bg + F card: counter-rotation. Card chaos → bg brightness |
+| 50-60%    | ★ ENERGY DRAIN                | Card intensity drains TO background. Q bg: max intensity, hue shifts |
+| 60-75%    | ★ GEOMETRY MORPH              | Card & bg swap geometries — card gets bg's geo, bg gets card's |
+| 75-88%    | ★ ENERGY RETURN               | Background drains back TO card. Inverse of drain phase |
+| 88-100%   | Card spins out                | Q bg fades, card exits with rotation    |
+
+**"Energy Transfer" button**: Triggers full drain→morph→return cycle as a GSAP timeline independent of scroll:
+1. Card: intensity 0.6→0.05, density 30→4, chaos spikes
+2. Background: intensity 0.2→0.8, density 16→55, hue shifts 90°
+3. Both: geometry swap, rot4dXW = PI
+4. Reverse: everything smoothly returns over 2.5s
+
+---
+
+### 8. AGENT (3250-3400vh) — Single GPU Background
+
+**GPU**: 1 context (Holographic → `agent-canvas`)
+
+**NEW**: Replace Canvas2D with Holographic GPU system. The 5-layer glassmorphic holographic system is perfect behind glassmorphic agent cards — visual language matches.
+
+| Scroll %  | Phase                        | GPU Behavior                           |
+|-----------|------------------------------|----------------------------------------|
+| 0-20%     | Header reveals               | H: low intensity, geo 3, slow          |
+| 20-60%    | Agent cards stagger in       | H: each card reveal triggers a density pulse |
+| 60-80%    | Code block reveals           | H: hue shifts toward code-highlight colors |
+| 80-100%   | ★ CRESCENDO BUILD            | H: speed↑↑, chaos↑↑, density↑↑, vignette closes |
+
+**Speed crescendo** (pre-CTA dramatic tension):
+- 60% → 80%: All params accelerate exponentially
+- 80% → 88%: THE SILENCE — everything drops to zero, full black
+- 88% → 100%: Gentle rebirth — minimal intensity, slow speed, setting up CTA
+
+---
+
+### 9. CTA (3400-3500vh) — ★ DUAL SYSTEM FINALE
+
+**GPU**: 2 contexts (Quantum + Faceted as dueling finales)
+
+**NEW**: The final section gets TWO real GPU systems that DUEL — split screen, opposing parameters, converging at the end to create a unified "come together" moment.
+
+| Scroll %  | Phase                         | Multi-System Event                      |
+|-----------|-------------------------------|-----------------------------------------|
+| 0-20%     | Emerge from silence           | Q left, F right — both at intensity 0.1, slowly rising |
+| 20-40%    | Systems differentiate         | Q: cool hues, high density, slow. F: warm, low density, fast |
+| 40-60%    | ★ OPPOSITION                  | Q + F: opposing rotations, complementary hues, fighting |
+| 60-80%    | ★ CONVERGENCE                 | Systems pull toward matching params — hues merge, speed syncs |
+| 80-100%   | ★ UNITY                       | Both match: same hue, same rotation, same geometry — ONE SYSTEM |
+
+**Split line**: Diagonal (not vertical) — rotates from 45° to 0° (horizontal) to vertical during scroll.
+
+---
+
+## CROSS-SECTION COORDINATION EVENTS
+
+### A. Triptych → Cascade Handoff (~2600vh)
+1. Triptych's 3 GPUs crystallize (density max, speed zero, frozen)
+2. Release 1 GPU (Faceted), keep Quantum + acquire Holographic for cascade BG
+3. Flash transition on divider SVG
+4. Cascade cards stagger-appear with chaos burst
+
+### B. Cascade → Energy Handoff (~3000vh)
+1. Cascade's dual BG systems converge to identical params
+2. Release Holographic, swap Quantum to energy-bg, acquire Faceted for energy card
+3. Energy card enters from below through cascade's frozen background
+
+### C. Energy → Agent Handoff (~3250vh)
+1. Energy's dual GPUs drain (card spins out, background fades)
+2. Release both, acquire 1 Holographic for agent background
+3. Agent section fades in over holographic backdrop
+
+### D. Agent → CTA Handoff (~3400vh)
+1. Agent Holographic accelerates in speed crescendo
+2. THE SILENCE — everything drops to black
+3. Release Holographic, acquire Quantum + Faceted for CTA finale
+4. Dual systems emerge from darkness
+
+---
+
+## GPU CONTEXT LIFECYCLE (Max 3 Concurrent)
+
+```
+Section     | Slot 1          | Slot 2          | Slot 3
+─────────── | ─────────────── | ─────────────── | ───────────────
+Opening     | Quantum         |                 |
+Hero        | Quantum         |                 |
+Morph       | Q/H/F rotating  |                 |
+Playground  | Q/H/F user      |                 |
+Triptych    | Quantum         | Holographic     | Faceted
+Cascade     | Quantum         | Holographic     |
+Energy      | Quantum         | Faceted         |
+Agent       | Holographic     |                 |
+CTA         | Quantum         | Faceted         |
+```
+
+Peak usage: Triptych at 3/3. All other multi-system sections use 2/3.
+
+---
+
+## MOUSE/TOUCH REACTIVITY (Global)
+
+Every visible GPU system responds to mouse position:
+- **Triptych**: Mouse X shifts clip-path split lines (columns fight for space)
+- **Cascade**: Mouse X shifts GPU background split line
+- **Energy**: Mouse drives card tilt + background counter-rotation
+- **CTA**: Mouse shifts diagonal split line angle
+- **All sections**: Mouse Y drives subtle intensity modulation on visible GPU systems
+
+---
+
+## CANVAS2D (AmbientLattice) — MINIMAL USAGE
+
+AmbientLattice ONLY used for:
+1. **Cascade card faces** (4-6 small cards — GPU contexts would be wasted on small canvases)
+
+NOT used for: energy background, agent background, CTA background (all now GPU)