@vib3code/sdk 2.0.1

package/DOCS/PROJECT_SETUP.md

@@ -0,0 +1,66 @@
+# Project setup (GCP + Firebase)
+
+This document provides a professional, repeatable setup flow for creating and configuring a new
+Google Cloud + Firebase project for this repo. Follow these steps once per project.
+
+## Prerequisites
+- Google Cloud SDK (`gcloud`)
+- Firebase CLI (`firebase`)
+- GitHub CLI (`gh`) if you plan to wire CI secrets
+- Access to a GCP billing account
+
+See `DOCS/ENV_SETUP.md` if you need to install tooling first.
+
+## 1) Authenticate and select project
+```bash
+gcloud auth login --no-launch-browser
+gcloud auth application-default login --no-launch-browser
+gcloud config set project gen-lang-client-0544919502
+```
+
+## 2) Enable required APIs
+```bash
+gcloud services enable \
+  cloudresourcemanager.googleapis.com \
+  serviceusage.googleapis.com \
+  firebase.googleapis.com \
+  firestore.googleapis.com \
+  cloudfunctions.googleapis.com \
+  cloudbuild.googleapis.com \
+  artifactregistry.googleapis.com
+```
+
+## 3) Initialize Firebase
+```bash
+firebase login --no-localhost
+firebase use --add
+```
+
+## 4) Optional: Firebase Test Lab (device testing)
+```bash
+gcloud services enable testing.googleapis.com
+```
+
+## 5) Optional: CI service account
+Create a service account for CI workflows that need deploy/test access:
+```bash
+gcloud iam service-accounts create vib3-ci \
+  --description="CI service account for Vib3 project automation" \
+  --display-name="vib3-ci"
+
+gcloud projects add-iam-policy-binding gen-lang-client-0544919502 \
+  --member="serviceAccount:vib3-ci@gen-lang-client-0544919502.iam.gserviceaccount.com" \
+  --role="roles/editor"
+```
+
+Export a key (store securely in your CI secrets manager):
+```bash
+gcloud iam service-accounts keys create vib3-ci-key.json \
+  --iam-account="vib3-ci@gen-lang-client-0544919502.iam.gserviceaccount.com"
+```
+
+## 6) Next steps
+- If you are using Firebase Functions, initialize `firebase init functions`.
+- If you are using Firestore, initialize `firebase init firestore`.
+- For CI automation, add the JSON key to your secret store and configure
+  `GOOGLE_APPLICATION_CREDENTIALS`.

package/DOCS/RENDERER_LIFECYCLE.md

@@ -0,0 +1,40 @@
+# Renderer lifecycle guide
+
+This document describes the renderer lifecycle architecture used by the core visualization systems
+and how to integrate new renderers safely. It is intended to keep renderer activation, resizing, and
+resource cleanup predictable across Faceted, Holographic, Polychora, and Quantum systems.
+
+## Goals
+- Centralize renderer activation/deactivation so systems can be swapped without double-render loops.
+- Provide a consistent `renderFrame()` entry point for external orchestration and tooling.
+- Track GPU resources with a shared registry to prevent leaks and enable diagnostics.
+
+## Key concepts
+### Renderer contract
+Renderers should expose the following behaviors:
+- `setActive(isActive)` — start/stop internal animation loops (or mark the renderer inactive).
+- `renderFrame()` — render a single frame without starting a new loop.
+- `resize(width, height)` — update canvas size and viewport.
+
+### Lifecycle manager
+Use the lifecycle manager to:
+- register renderers by id
+- activate one renderer at a time
+- forward resize events
+- render an explicit frame on demand
+
+### Resource registry
+GPU-backed resources (programs, textures, buffers, framebuffers, VAOs, renderbuffers) should be
+tracked and disposed through the shared registry to keep memory stable during renderer switching.
+
+## Recommended integration checklist
+1. Ensure your renderer implements `setActive()` and `renderFrame()` without side effects.
+2. Register the renderer with the lifecycle manager once the system is constructed.
+3. Route all resize events through the manager to keep viewports in sync.
+4. Use the resource registry in your WebGL backend integration so disposal is centralized.
+5. Validate lifecycle behavior by toggling active systems while monitoring resource counts.
+
+## Troubleshooting
+- **Duplicate animation loops:** verify `setActive(false)` stops any timers or rAF loops.
+- **Black frames on switch:** call `resize()` before `renderFrame()` when activating a renderer.
+- **GPU memory growth:** ensure resource creation and deletion always passes through the registry.

package/DOCS/REPO_MANIFEST.md

@@ -0,0 +1,121 @@
+# Repository Manifest
+
+This document enumerates the repository's directory structure and provides a high-level purpose for
+each folder. Use it as a navigation guide when onboarding or auditing the codebase.
+
+## Top-level Folders
+
+| Folder | Purpose |
+|--------|---------|
+| `.git/` | Git metadata and internal state |
+| `.github/` | GitHub Actions workflows and CI configuration |
+| `DOCS/` | Authored documentation (onboarding, setup, CI, lifecycle guides) |
+| `archive/` | Archived/legacy code (old implementations, TBD systems like Polychora) |
+| `cpp/` | Native C++ core (WASM sources, headers, bindings, math) |
+| `demo-assets/` | Demo assets and sandbox content |
+| `docs/` | Documentation site sources and static docs assets |
+| `examples/` | Example applications (flutter_demo, etc.) |
+| `flutter/` | Flutter plugin and platform integration |
+| `scripts/` | Build and utility scripts |
+| `src/` | Primary engine source tree (core, renderers, math, tooling) |
+| `styles/` | CSS and style assets |
+| `tests/` | Unit/integration tests (Playwright, Jest) |
+| `tools/` | CLI/tooling scripts (telemetry, export, math utilities) |
+| `types/` | Shared TypeScript type declarations |
+| `wasm/` | WebAssembly artifacts and related assets |
+
+## Depth-2 Directory Manifest
+
+### `cpp/`
+- `cpp/bindings/` — Native bindings and interop layers
+- `cpp/include/` — Public C++ headers (vib3_ffi.h)
+- `cpp/math/` — Math utilities for the native core
+- `cpp/src/` — Native engine sources (Rotor4D, Mat4x4, Vec4)
+
+### `docs/`
+- `docs/src/` — Documentation site sources
+- `docs/wasm/` — WebAssembly-related docs assets
+
+### `examples/`
+- `examples/flutter_demo/` — Complete Flutter demo application
+
+### `flutter/`
+- `flutter/android/` — Android plugin implementation (Kotlin + OpenGL ES 3.0)
+- `flutter/ios/` — iOS plugin implementation and podspec
+- `flutter/lib/` — Dart package sources (vib3_engine.dart, widgets)
+
+### `src/`
+- `src/agent/` — Agentic tooling and MCP integration
+  - `src/agent/cli/` — Agent CLI interface
+  - `src/agent/mcp/` — MCP server and tools (MCPServer.js, tools.js)
+  - `src/agent/telemetry/` — Telemetry services and exporters
+- `src/advanced/` — **NEW v2.0.0** Advanced features
+  - WebXRRenderer.js, WebGPUCompute.js, MIDIController.js, AIPresetGenerator.js, OffscreenWorker.js
+- `src/benchmarks/` — Performance benchmarks
+- `src/cli/` — CLI entry points
+- `src/config/` — Configuration helpers
+- `src/core/` — Core engine orchestration
+  - VIB3Engine.js (+ SpatialInputSystem integration), CanvasManager.js, ParameterMapper.js, Parameters.js
+- `src/creative/` — **NEW v2.0.0** Creative tooling
+  - ColorPresetsSystem.js, TransitionAnimator.js, PostProcessingPipeline.js, ParameterTimeline.js
+- `src/export/` — Export pipeline
+  - TradingCardGenerator, VIB3PackageExporter, SVGExporter, LottieExporter
+  - `src/export/systems/` — System-specific card generators
+- `src/faceted/` — Faceted visualization system (FacetedSystem.js — with audio + saturation v2.0.0)
+- `src/features/` — Feature flags and optional subsystems
+- `src/gallery/` — Gallery rendering and orchestration
+- `src/geometry/` — Geometry generation and definitions
+  - `src/geometry/buffers/` — Buffer builders
+  - `src/geometry/generators/` — Shape generators (Tesseract, Torus, etc.)
+  - `src/geometry/warp/` — Core warps (HypersphereCore, HypertetraCore)
+- `src/holograms/` — Holographic visualization system
+  - RealHolographicSystem.js, HolographicVisualizer.js
+- `src/integrations/` — **NEW v2.0.0** Platform integrations
+  - `src/integrations/frameworks/` — Vib3React.js, Vib3Vue.js, Vib3Svelte.js
+  - FigmaPlugin.js, ThreeJsPackage.js, TouchDesignerExport.js, OBSMode.js
+- `src/llm/` — LLM integrations (LLMParameterInterface, LLMParameterUI)
+- `src/math/` — Math primitives (Vec4, Mat4x4, Rotor4D, Projection)
+- `src/quantum/` — Quantum visualization system
+  - QuantumEngine.js, QuantumVisualizer.js
+- `src/reactivity/` — Reactivity configuration, management, and spatial input
+  - ReactivityConfig.js, ReactivityManager.js, SpatialInputSystem.js (**NEW v2.0.0**)
+- `src/render/` — Rendering backends and registries
+  - `src/render/backends/` — WebGL and WebGPU backends
+  - `src/render/commands/` — Render command buffer
+- `src/scene/` — Scene composition helpers (Scene4D, Node4D, ResourceManager)
+- `src/schemas/` — JSON schemas for tooling/validation
+- `src/testing/` — Testing utilities
+- `src/ui/` — UI integration and components
+- `src/variations/` — Visual variations and presets
+- `src/viewer/` — Viewer-facing wrappers (AudioReactivity, CardBending, GalleryUI)
+- `src/wasm/` — WASM-specific entry points (WasmLoader)
+
+### `tests/`
+- `tests/agent/` — Agent/tooling tests
+- `tests/e2e/` — End-to-end browser tests
+- `tests/geometry/` — Geometry unit tests
+- `tests/math/` — Math stability/unit tests
+- `tests/render/` — Rendering tests
+- `tests/scene/` — Scene tests
+
+### `tools/`
+- `tools/agentic/` — Agentic helper scripts
+- `tools/cli/` — CLI tooling scripts
+- `tools/export/` — Export pipeline tools
+- `tools/math/` — Math test baselines/utilities
+- `tools/telemetry/` — Telemetry tooling
+
+### `types/`
+- `types/render/` — Render-related type definitions
+
+### `archive/` (Archived Code)
+- `archive/polychora/` — TBD Polychora system (not production ready)
+- `archive/duplicate-engines/` — Old engine implementations
+- `archive/duplicate-holographic/` — Old holographic system variants
+- `archive/legacy-docs/` — Historical documentation
+- `archive/sdk-old/` — Previous SDK implementation (superseded by src/)
+- `archive/platforms/` — Experimental platform targets
+
+---
+
+*Last updated: 2026-01-30 (v2.0.0)*

package/DOCS/SESSION_014_PLAN.md

@@ -0,0 +1,195 @@
+# VIB3+ SDK - Session 014 Plan & Status
+
+**Date:** 2026-01-25
+**Branch:** `claude/phase-5-hardening-a4Wzn`
+**Session:** 014
+
+---
+
+## Executive Summary
+
+This session completed a comprehensive system review and implemented agent onboarding improvements. The VIB3+ SDK is a **general-purpose 4D rotation visualization SDK** for plugins, extensions, wearables, and agentic AI integration.
+
+---
+
+## System Architecture (Verified)
+
+### Core Metrics
+| Component | Value |
+|-----------|-------|
+| **Active Systems** | 3 (Quantum, Faceted, Holographic) |
+| **Placeholder Systems** | 1 (Polychora - TBD) |
+| **Rotation Planes** | 6 (XY, XZ, YZ + XW, YW, ZW) |
+| **Base Geometries** | 8 |
+| **Core Warp Types** | 3 (Base, Hypersphere, Hypertetrahedron) |
+| **Total Geometries** | 24 (8 base × 3 cores) |
+| **Canvas Layers** | 5 per system |
+| **MCP Tools** | 14 |
+| **Tests Passing** | 693+ |
+
+### Geometry Encoding Formula
+```
+geometry_index = core_index * 8 + base_index
+
+Where:
+- core_index: 0 (Base), 1 (Hypersphere), 2 (Hypertetrahedron)
+- base_index: 0-7 (tetrahedron, hypercube, sphere, torus, klein, fractal, wave, crystal)
+```
+
+---
+
+## Changes Made This Session
+
+### 1. UI: Full 24 Geometry Support
+**File:** `sdk/index.html`
+- Added Core Type dropdown (Base, Hypersphere, Hypertetrahedron)
+- Implemented proper geometry encoding: `coreType * 8 + baseGeometry`
+- Updated geometry display to show "Geometry X / 24"
+- Fixed geometry buttons to work with core type selector
+
+### 2. Documentation: System Inventory
+**File:** `DOCS/SYSTEM_INVENTORY.md`
+- Complete technical inventory
+- Architecture diagram
+- All 4 systems documented
+- 24 geometry encoding explained
+- 6D rotation system documented
+- MCP tools reference
+- Agent onboarding quiz
+
+### 3. MCP: Agent Onboarding Tools
+**Files:** `src/agent/mcp/tools.js`, `src/agent/mcp/MCPServer.js`
+
+New tools added:
+- `get_sdk_context` - Returns essential SDK context on first connection
+- `verify_knowledge` - Multiple choice quiz to verify understanding
+
+Quiz format (answers: c, b, c, a, b, b):
+```
+Q1: How many rotation planes? a)3 b)4 c)6 d)8
+Q2: Geometry formula? a)base*3+core b)core*8+base c)base+core d)core*base
+Q3: Canvas layers per system? a)3 b)4 c)5 d)6
+Q4: Which are the 3 ACTIVE systems? a)quantum,faceted,holographic b)quantum,faceted,polychora c)all four d)none
+Q5: How many base geometry types? a)6 b)8 c)10 d)24
+Q6: Core warp types? a)base,sphere,cube b)base,hypersphere,hypertetrahedron c)2D,3D,4D d)none
+```
+
+### 4. Polychora Marked as TBD
+- Polychora system marked as placeholder/TBD in MCP responses
+- Quiz updated to test knowledge that only 3 systems are ACTIVE
+- System exists but not production-ready
+
+---
+
+## Phase Status
+
+| Phase | Status | Notes |
+|-------|--------|-------|
+| **Phase 1: Foundation** | ✅ Complete | Math, geometry, parameters |
+| **Phase 2: Rendering** | ✅ Mostly Complete | Contracts exist, 4 adapters |
+| **Phase 3: Agentic** | ✅ Complete | MCP, CLI, Telemetry |
+| **Phase 4: WebGPU** | 🔄 Scaffold | Needs shader pipeline |
+| **Phase 5: Hardening** | 🔄 In Progress | 693 tests passing |
+
+---
+
+## Known Issues
+
+1. **Polychora not production-ready** - Keep as TBD placeholder
+2. **WebGPU backend incomplete** - Scaffold exists, needs shader pipeline
+3. **Timing test flaky** - `withTiming` test sometimes fails by <1ms
+4. **Playwright test config** - Browser tests don't run in vitest
+
+---
+
+## Planned Future Work
+
+### Phase 2 Consolidation (Rendering)
+- [ ] Audit all 4 systems for RendererContract compliance
+- [ ] Extract shared scene graph code
+- [ ] Document lifecycle rules in code
+- [ ] Add contract compliance tests
+
+### Phase 4 (WebGPU)
+- [ ] Complete WebGPU shader pipeline
+- [ ] Port shaders from WebGL to WGSL
+- [ ] Benchmark WebGL vs WebGPU
+
+### Phase 5 (Hardening)
+- [ ] Fix flaky timing test
+- [ ] Separate Playwright tests from vitest
+- [ ] Add more integration tests
+- [ ] Browser rendering verification
+
+### Documentation
+- [ ] Consolidate scattered docs
+- [ ] Archive outdated docs
+- [ ] Create "Start Here" guide for new agents
+- [ ] Add code examples to SYSTEM_INVENTORY.md
+
+---
+
+## File References
+
+### Primary Documentation
+| File | Purpose |
+|------|---------|
+| `DOCS/SYSTEM_INVENTORY.md` | Complete system reference |
+| `DOCS/CLI_ONBOARDING.md` | Agent CLI setup |
+| `DOCS/CONTROL_REFERENCE.md` | UI parameters |
+| `24-GEOMETRY-6D-ROTATION-SUMMARY.md` | Geometry encoding |
+
+### Core Source Files
+| File | Purpose |
+|------|---------|
+| `src/core/VIB3Engine.js` | Main unified engine |
+| `src/core/RendererContracts.js` | Shared interfaces |
+| `src/quantum/QuantumEngine.js` | Quantum system |
+| `src/faceted/FacetedSystem.js` | Faceted system |
+| `src/holograms/RealHolographicSystem.js` | Holographic system |
+| `src/core/PolychoraSystem.js` | Polychora (TBD) |
+| `src/agent/mcp/MCPServer.js` | MCP server |
+| `src/agent/mcp/tools.js` | MCP tool definitions |
+| `src/agent/cli/AgentCLI.js` | CLI interface |
+
+---
+
+## Git Commits This Session
+
+1. `feat(ui): Add full 24 geometry support with core type selector`
+2. `docs(sdk): Add comprehensive system inventory and agent onboarding tools`
+3. (pending) `feat(mcp): Add multiple choice quiz and mark Polychora as TBD`
+
+---
+
+## Testing Commands
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npm test -- tests/agent/AgentCLI.test.js
+
+# Run with coverage
+npm test -- --coverage
+
+# Start dev server
+npm run dev:web
+```
+
+---
+
+## Quiz Answers Reference
+
+For agent onboarding quiz (`verify_knowledge`):
+- Q1 (rotation planes): **c** (6)
+- Q2 (geometry formula): **b** (core*8+base)
+- Q3 (canvas layers): **c** (5)
+- Q4 (active systems): **a** (quantum, faceted, holographic)
+- Q5 (base geometries): **b** (8)
+- Q6 (core types): **b** (base, hypersphere, hypertetrahedron)
+
+---
+
+*Document generated: Session 014, 2026-01-25*

package/DOCS/SESSION_LOG_2026-01-07.md

@@ -0,0 +1,56 @@
+# Session log (2026-01-07)
+
+## 18:40:40
+- Logged required tooling and onboarding plan for agentic CLI workflows.
+- Created a dated dev track plan to anchor upcoming work.
+- Documented telemetry export flow in the onboarding guide.
+
+## 23:19:52
+- Added onboarding verification prompts to ensure agents can name geometry types and controls.
+
+## 23:34:16
+- Clarified the onboarding knowledge check to allow continuation while pointing to the correct reference docs.
+
+## 23:37:38
+- Added a copy/paste knowledge-check template and planned it in the dev track.
+
+## 02:07:46
+- Captured the unified SDK strategic blueprint and linked it from the README.
+
+## 02:10:12
+- Expanded the strategic blueprint into detailed actions and created an execution plan checklist.
+
+## 02:42:14
+- Added 4D rotation matrices, projection helpers, and stability tests; checked off Phase 1 math foundation items.
+
+## 02:42:36
+- Ran `pnpm test` to validate rotation and projection math helpers.
+
+## 02:46:57
+- Added renderer and resource manager contracts and checked off the Phase 2 interface definition.
+
+## 02:53:28
+- Implemented Phase 3 agentic integration: MCP tool definitions, telemetry spans/error schema, and agent CLI JSON/non-interactive export.
+
+## 02:53:50
+- Added CLI error handling for invalid pack JSON with structured telemetry errors.
+
+## 03:09:19
+- Completed Phase 4 cross-platform scaffolding: WASM target, Flutter render command buffer, and WebGPU feature flags.
+
+## 03:13:25
+- Completed Phase 5 deliverables: licensing tiers, export formats with golden snapshot coverage, and XR benchmark docs.
+
+## 03:13:48
+- Ran `pnpm test` to update export format snapshots and validate test coverage.
+
+## 13:19:14
+- Added scene graph scaffolding and documented GPU disposal patterns for Phase 2.
+
+## 2026-01-23 22:04 (Session 011)
+- Fixed rotation stability test precision tolerance (Float32Array drift over 2000 iterations).
+- Expanded LICENSING_TIERS.md with implementation details: key format, activation flow, token schema, offline validation, feature gating.
+- Expanded EXPORT_FORMATS.md with format specifications, golden snapshot test implementation, and CI integration.
+- Expanded XR_BENCHMARKS.md with metrics collection, benchmark runner, regression detection, and performance overlay.
+- Added CLI `validate` command for validating scene packs, manifests, and tool responses.
+- All 584 tests passing.

package/DOCS/STRATEGIC_BLUEPRINT_2026-01-07.md

@@ -0,0 +1,72 @@
+# Strategic development blueprint (2026-01-07)
+
+This document captures the unified SDK direction for VIB3+ and provides an actionable architecture spine for agentic-first development.
+
+## Unified architecture stack
+- **Rendering core**: WebGL engine becomes the renderer of record.
+- **Agentic wrapper**: MCP/automation layer orchestrates workflows, telemetry, and validation.
+- **SDK scaffolding**: Public API layer with modular packages for core, math, geometry, materials, webgl, webgpu, agent, and cli.
+
+## Package layout target
+```
+@vib3/core      → Scene graph, resource management, abstract renderer
+@vib3/math      → 4D vectors, rotors, matrices, projections
+@vib3/geometry  → Polychora, tesseracts, slicing algorithms
+@vib3/materials → Shaders, holographic/quantum rendering modes
+@vib3/webgl     → WebGL 2.0 backend
+@vib3/webgpu    → WebGPU backend (experimental)
+@vib3/agent     → MCP server, tools, telemetry
+@vib3/cli       → Agent-friendly CLI interface
+```
+
+## Math + rendering principles
+- 4D rotations require rotors or 4×4 matrices; avoid storing orientation as Euler angles.
+- Provide stereographic and perspective projections with singularity clamping.
+- Renormalize rotors/matrices periodically to avoid drift.
+
+## Agentic API design
+- Prefer workflow-oriented tools (create scene, apply rotations, render preview) over low-level API exposure.
+- Emit structured telemetry with explicit error codes, suggestions, and valid options.
+- Add JSON output mode, non-interactive flags, and streaming progress events to the CLI.
+
+## Cross-platform strategy
+- Plan a shared core (Rust/C++/WASM) with thin platform bindings (web, Flutter, native).
+- Batch render commands to avoid per-frame FFI overhead.
+- Share shader sources and cross-compile to target platforms.
+
+## Licensing direction (draft)
+- MIT runtime for core packages with paid tiers for advanced tooling and exports.
+- Provide transparent changelogs, pricing notices, and grandfathering policies.
+
+## Phased roadmap
+1. **Math foundation**: rotors, projections, core polychora generators.
+2. **Rendering core**: renderer abstraction, system consolidation, resource disposal.
+3. **Agentic integration**: MCP tools, telemetry, CLI JSON outputs.
+4. **Cross-platform**: WASM core, Flutter bindings, WebGPU backend.
+5. **Production hardening**: licensing, editor tooling, export formats, XR integration.
+
+## Detailed blueprint actions
+### Phase 1 — Mathematical foundation
+- Implement rotor/matrix utilities for all six rotation planes.
+- Provide stereographic + perspective projection helpers with clamping.
+- Add automated stability tests for rotation drift.
+
+### Phase 2 — Rendering core consolidation
+- Extract renderer contracts and resource manager interfaces.
+- Unify the four visualization systems behind a shared scene graph.
+- Document disposal patterns to prevent GPU leaks.
+
+### Phase 3 — Agentic integration
+- Define MCP tools around workflows (create scene, apply rotation, render preview).
+- Add telemetry spans and error schemas for validation and tooling.
+- Implement CLI JSON output modes and non-interactive flags.
+
+### Phase 4 — Cross-platform execution
+- Formalize a WASM target and shared math core.
+- Add Flutter bindings with a batched render command buffer.
+- Prototype WebGPU backend behind feature flags.
+
+### Phase 5 — Production hardening
+- Draft licensing tiers and activation flow.
+- Add export format support with golden snapshot tests.
+- Document XR integration and performance benchmarks.