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

package/DOCS/OBS_SETUP_GUIDE.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # VIB3+ OBS Setup Guide
 
 Use VIB3+ as a live visualization overlay in OBS Studio.

package/DOCS/OPTIMIZATION_PLAN_MATH.md

@@ -0,0 +1,119 @@
+Last reviewed: 2026-02-17
+# Optimization Plan: Core Math Library
+
+## 1. Add `target` Parameters for Allocation-Free Operations
+
+**Status:** High Impact / Medium Effort
+**Currently:** `Mat4x4.multiply(m)` and `Mat4x4.multiplyVec4(v)` always return a `new` instance.
+**Proposed:** Add an optional `target` parameter to write the result into an existing object.
+
+### Implementation
+```javascript
+// Before
+multiply(m) {
+    const out = new Mat4x4();
+    // ... compute ...
+    return out;
+}
+
+// After
+multiply(m, target = null) {
+    const out = target || new Mat4x4();
+    // ... compute ...
+    return out;
+}
+```
+
+### Cascading Changes
+*   **Scene Graph (`Node4D.js`):** Update `updateWorldMatrix` to reuse a cached matrix instance instead of creating a new one every frame.
+*   **Physics/Animation:** Update loops to reuse vector/matrix instances.
+
+### Watch Outs
+*   **Aliasing:** If `a.multiply(b, a)` is called (writing result back to operand), ensure the implementation handles this correctly. The current `multiplyInPlace` implementation handles this by caching values in local variables before writing to the array. Ensure new methods do the same.
+*   **API Consistency:** Ensure `target` is consistently the last argument or follows a predictable pattern.
+
+## 2. Implement `Vec4` Object Pooling (or Lightweight Structure)
+
+**Status:** High Impact / High Complexity
+**Currently:** `Vec4` allocates a `Float32Array(4)` per instance. This is heavy for the JS engine and GC.
+**Proposed:**
+1.  **Object Pool:** `Vec4.create()` grabs from a pool, `Vec4.release(v)` returns it.
+2.  **Lightweight Class:** Use plain object `{x, y, z, w}` for intermediate math, only converting to `Float32Array` when uploading to GPU.
+
+### Implementation (Object Pool)
+```javascript
+class Vec4Pool {
+    static get() { return pool.pop() || new Vec4(); }
+    static release(v) { pool.push(v); }
+}
+```
+
+### Cascading Changes
+*   **Usage:** Requires changing *every* `new Vec4()` call to `Vec4Pool.get()` and ensuring `release()` is called when done.
+*   **Lifecycle Management:** Extremely error-prone in JS. Missing a release leaks memory; double-release corrupts data.
+
+### Watch Outs
+*   **Manual Memory Management:** This fights against the JS GC. Only worth it in extremely hot paths (e.g., particle systems, per-vertex operations).
+*   **Alternatives:** Consider simply using `Float32Array` offsets directly for bulk data (Structure of Arrays).
+
+## 3. Cache Common Constants
+
+**Status:** Medium Impact / Low Effort
+**Currently:** `Mat4x4.identity()` creates a new matrix every call.
+**Proposed:** Add static read-only constants.
+
+### Implementation
+```javascript
+class Mat4x4 {
+    static get IDENTITY() {
+        if (!this._identity) this._identity = new Mat4x4().setIdentity();
+        return this._identity;
+    }
+}
+```
+
+### Cascading Changes
+*   **Usage:** Replace `Mat4x4.identity()` with `Mat4x4.IDENTITY` where read-only access is needed.
+*   **Cloning:** If modification is needed, use `Mat4x4.IDENTITY.clone()`.
+
+### Watch Outs
+*   **Accidental Mutation:** If someone does `Mat4x4.IDENTITY.translate(...)`, it corrupts the constant for everyone.
+    *   *Mitigation:* `Object.freeze()` or similar protections (though this has a perf cost). Better to rely on convention or a `ReadonlyMat4x4` type if using TS.
+
+## 4. Optimize Scene Graph with In-Place Operations
+
+**Status:** High Impact / Medium Effort
+**Currently:** `Node4D.updateMatrix` often chains operations: `T * R * S`.
+**Proposed:** Use the new `multiplyInPlace` and `rotateXX` methods.
+
+### Implementation
+```javascript
+// Node4D.updateLocalMatrix
+this.localMatrix.setIdentity();
+this.localMatrix.translate(this.position); // Needs implementation
+this.localMatrix.rotateFromAngles(this.rotation); // Needs implementation/update
+this.localMatrix.scale(this.scale); // Needs implementation
+```
+
+### Cascading Changes
+*   **`Mat4x4` Extensions:** Need to implement `translate(v)`, `scale(v)` as in-place methods.
+*   **Logic Updates:** Rewrite `Node4D` transform logic to be imperative/stateful rather than functional/immutable.
+
+### Watch Outs
+*   **Order of Operations:** Ensure `T * R * S` vs `S * R * T` order is preserved correctly when converting to in-place calls.
+*   **Dirty Flags:** Ensure `localMatrix` update only happens when `position`, `rotation`, or `scale` changes.
+
+## 5. Bulk Operations for Geometry
+
+**Status:** High Impact / High Complexity
+**Currently:** `Mat4x4.multiplyVec4` processes one vector at a time.
+**Proposed:** `Mat4x4.multiplyArray(inputArray, outputArray, count)`
+
+### Implementation
+Operate directly on flat `Float32Array` buffers.
+
+### Cascading Changes
+*   **Geometry Generators:** Update to use bulk processing.
+
+### Watch Outs
+*   **SIMD:** Browsers are starting to support SIMD via WASM. This might be a better target for heavy bulk math than optimizing JS loops.

package/DOCS/PRODUCT_STRATEGY.md

@@ -0,0 +1,65 @@
+Last reviewed: 2026-02-17
+
+# 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/PROJECT_SETUP.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Project setup (GCP + Firebase)
 
 This document provides a professional, repeatable setup flow for creating and configuring a new

package/DOCS/README.md

@@ -0,0 +1,105 @@
+Last reviewed: 2026-02-17
+
+# 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-tracks/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-tracks/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-tracks/DEV_TRACK_SESSION_2026-02-06.md) **(SOT for active sprint log)**, [`DEV_TRACK_SESSION_2026-01-31.md`](./dev-tracks/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,99 @@
+Last reviewed: 2026-02-17
+
+# 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/RENDERER_LIFECYCLE.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Renderer lifecycle guide
 
 This document describes the renderer lifecycle architecture used by the core visualization systems

package/DOCS/REPO_MANIFEST.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Repository Manifest
 
 This document enumerates the repository's directory structure and provides a high-level purpose for

package/DOCS/ROADMAP.md

@@ -0,0 +1,113 @@
+Last reviewed: 2026-02-17
+
+# 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.