@vib3code/sdk 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to VIB3+ CORE (`@vib3code/sdk`) will be documented in this file.
+
+## [2.0.0] — 2026-01-30
+
+### Added
+
+#### SpatialInputSystem (`src/reactivity/SpatialInputSystem.js` — 1,783 lines)
+- Universal spatial input system decoupling "card tilting" from physical device orientation
+- 8 input source types: deviceTilt, mousePosition, gyroscope, gamepad, perspective, programmatic, audio, MIDI
+- 6 built-in profiles: cardTilt, wearablePerspective, gameAsset, vjAudioSpatial, uiElement, immersiveXR
+- Full serialization (exportConfig/importConfig)
+- Integrated into VIB3Engine with 7 new methods
+
+#### Creative Tooling (3,837 lines)
+- `ColorPresetsSystem.js` — 22 themed color presets (Ocean, Lava, Neon, Monochrome, etc.) with group parameter application
+- `TransitionAnimator.js` — 14 easing functions with smooth state interpolation and sequencing
+- `PostProcessingPipeline.js` — 14 composable effects (bloom, chromatic aberration, vignette, film grain, etc.) with 7 preset chains
+- `ParameterTimeline.js` — Keyframe-based parameter animation with BPM sync for music-driven sequences
+
+#### Platform Integrations (4,693 lines)
+- `Vib3React.js` — `<Vib3Canvas>` React component + `useVib3()` hook
+- `Vib3Vue.js` — Vue 3 component + composable
+- `Vib3Svelte.js` — Svelte component + store
+- `FigmaPlugin.js` — Figma plugin manifest, code, and UI generator
+- `ThreeJsPackage.js` — Three.js ShaderMaterial wrapper with 4D rotation uniforms
+- `TouchDesignerExport.js` — GLSL TOP export for TouchDesigner
+- `OBSMode.js` — Transparent background + OBS browser source mode
+
+#### Advanced Features (4,262 lines)
+- `WebXRRenderer.js` — WebXR VR/AR rendering with 6DOF spatial extraction
+- `WebGPUCompute.js` — WGSL particle simulation + audio FFT compute shaders
+- `MIDIController.js` — Web MIDI API with learn mode and CC mapping
+- `AIPresetGenerator.js` — Text-to-preset via LLM + mutation/crossbreeding
+- `OffscreenWorker.js` — OffscreenCanvas worker rendering + SharedArrayBuffer
+
+#### Tooling
+- `shader-sync-verify.js` — 937-line tool verifying inline shaders match external shader files across all 3 systems
+
+### Fixed
+- Quantum system color control restored — `u_hue` and `u_saturation` now drive actual HSL color output (was using hardcoded palettes)
+- Faceted system saturation wired — full `hsl2rgb()` pipeline added to GLSL + WGSL shaders
+- Faceted system audio reactivity wired — `u_bass`, `u_mid`, `u_high` uniforms now drive density/morph/hue
+- `clickIntensity` uniform bug fixed — was mapping to `u_mouseIntensity`, now correctly maps to `u_clickIntensity`
+
+---
+
+## [1.0.0] — 2025-12-15
+
+### Added
+
+#### Core Engine
+- `VIB3Engine.js` — Main orchestrator for 3 visualization systems
+- `CanvasManager.js` — Canvas lifecycle management with multi-layer support
+- `Parameters.js` — Parameter definitions with validation and ranges
+- `ParameterMapper.js` — Parameter-to-uniform mapping across systems
+- `RendererContracts.js` — Interface contracts for renderer adapters
+
+#### Visualization Systems
+- **Quantum** (`QuantumEngine.js`, `QuantumVisualizer.js`) — Complex lattice visualizations with quantum-inspired patterns, 24 geometry variants, 5-layer rendering
+- **Faceted** (`FacetedSystem.js`) — Clean 2D geometric patterns with 4D rotation projection, 24 geometry variants
+- **Holographic** (`RealHolographicSystem.js`, `HolographicVisualizer.js`) — 5-layer glassmorphic audio-reactive effects
+
+#### C++ WASM Core (3,072 lines)
+- `Rotor4D` — Clifford algebra Cl(4,0) 4D rotation via sandwich product
+- `Mat4x4` — Column-major 4x4 matrix operations
+- `Vec4` — 4-component vector operations
+- 3 projection modes: perspective, stereographic, orthographic
+- Emscripten bindings via `embind.cpp`
+- JavaScript math fallback (`src/math/`) for environments without WASM
+
+#### Render Infrastructure (8,400 lines)
+- Dual GPU backends: WebGL 2.0 (primary) + WebGPU (secondary)
+- `UnifiedRenderBridge` — Cross-backend abstraction with automatic fallback
+- `ShaderProgram`, `RenderState`, `CommandBuffer`, `RenderTarget`, `RenderResourceRegistry`
+- Multi-canvas coordination via `MultiCanvasBridge`
+- External shader files (GLSL + WGSL) for all 3 systems
+
+#### 24-Geometry System
+- 8 base geometries: Tetrahedron, Hypercube, Sphere, Torus, Klein Bottle, Fractal, Wave, Crystal
+- 3 core type warps: Base (0-7), Hypersphere (8-15), Hypertetrahedron (16-23)
+- Encoding: `index = core_type * 8 + base_geometry`
+
+#### 6D Rotation System
+- 6 rotation planes: XY, XZ, YZ (3D) + XW, YW, ZW (4D)
+- 3 implementations: WASM Rotor (Clifford algebra), GLSL matrices, WGSL matrices
+
+#### Reactivity
+- `ReactivityManager` — Audio, tilt, and interaction reactivity
+- `ReactivityConfig` — Serializable configuration with validation
+- Audio reactivity (bass/mid/high bands with configurable targets)
+- Device tilt with dramatic mode
+- Mouse, click, scroll, and touch interaction
+
+#### Export System (15,136 lines)
+- VIB3Package (JSON state), SVG, CSS animations, Lottie, Shader source
+- Trading card generator with system-specific renderers (Quantum, Faceted, Holographic)
+
+#### MCP Agentic Control
+- `MCPServer.js` — Full MCP protocol server with 14 tools
+- `AgentCLI.js` — Command-line interface
+- Telemetry service with OpenTelemetry-compatible events, spans, and exporters
+
+#### Scene & Resource Management
+- `Scene4D` / `Node4D` — 4D scene graph
+- `ResourceManager`, `MemoryPool`, `Disposable` — Lifecycle management
+
+#### Testing & CI/CD
+- 34 test files (10,000+ lines) — unit, E2E, visual regression
+- Playwright E2E with 69 browser tests
+- 6 CI/CD workflows: Pages deploy, benchmarks, exports, GPU visual tests, Flutter builds
+
+#### Cross-Platform
+- Browser (Vite-served)
+- CLI (`vib3` binary)
+- Flutter plugin (iOS + Android + Web)
+- GitHub Pages (26 HTML pages)

package/DOCS/BLUEPRINT_EXECUTION_PLAN_2026-01-07.md

@@ -0,0 +1,34 @@
+# Blueprint execution plan (2026-01-07)
+
+This execution plan operationalizes the strategic blueprint and defines what each session should deliver. Each session should update `DOCS/SESSION_LOG_2026-01-07.md` with timestamped progress and keep the checklist current.
+
+## Session cadence
+- **Start of session**: review this plan and the strategic blueprint.
+- **During session**: implement the next unchecked items, keep scope tight.
+- **End of session**: update the session log with timestamped outcomes and any blockers.
+
+## Execution checklist
+### Phase 1 — Mathematical foundation
+- [x] Add rotor/matrix utilities for the six rotation planes.
+- [x] Implement stereographic + perspective projection helpers.
+- [x] Add rotation drift/stability tests.
+
+### Phase 2 — Rendering core consolidation
+- [x] Define renderer contracts and resource manager interfaces.
+- [ ] Unify visualization systems behind a shared scene graph.
+- [x] Document GPU disposal patterns and lifecycle hooks.
+
+### Phase 3 — Agentic integration
+- [x] Define MCP tools for create/apply/render workflows.
+- [x] Emit structured telemetry spans and error schemas.
+- [x] Implement CLI JSON output and non-interactive modes.
+
+### Phase 4 — Cross-platform execution
+- [x] Define WASM build target and shared math core strategy.
+- [x] Add Flutter bindings with a batched render command buffer.
+- [x] Prototype WebGPU backend behind feature flags.
+
+### Phase 5 — Production hardening
+- [x] Draft licensing tiers and activation workflow.
+- [x] Add export formats with golden snapshot tests.
+- [x] Document XR integration benchmarks and performance targets.

package/DOCS/CI_TESTING.md

@@ -0,0 +1,38 @@
+# CI and testing guide
+
+This guide outlines the baseline CI/test expectations for the project and a recommended set of
+commands to keep builds predictable.
+
+## Goals
+- Provide a consistent, repeatable test/lint workflow.
+- Keep CI output deterministic for quick troubleshooting.
+- Encourage periodic bundle size checks and telemetry export validation.
+
+## Baseline commands
+Run these locally before pushing changes:
+```bash
+pnpm install
+pnpm lint
+pnpm test
+pnpm build:web
+pnpm check:bundle
+```
+
+## Suggested CI stages
+1. **Install & cache**
+   - Restore pnpm store cache.
+   - `pnpm install --frozen-lockfile`
+2. **Lint**
+   - `pnpm lint`
+3. **Unit tests**
+   - `pnpm test`
+4. **Build & bundle checks**
+   - `pnpm build:web`
+   - `pnpm check:bundle`
+5. **Optional telemetry smoke**
+   - `pnpm cli:telemetry -- <pack.json> --json --non-interactive --preview-count=4`
+
+## Environment tips
+- Ensure Node.js 18.19+ and pnpm 9.4.0 (see `DOCS/CLI_ONBOARDING.md`).
+- Use the environment bootstrap script in `DOCS/ENV_SETUP.md` for system tooling.
+- For Firebase Test Lab, enable the API and wire service account credentials in CI.

package/DOCS/CLI_ONBOARDING.md

@@ -0,0 +1,75 @@
+# Agentic CLI onboarding
+
+This guide aligns the current CLI surface (package scripts and telemetry helpers) with an agentic workflow. It is intentionally explicit so automation agents and humans can share the same runbook.
+
+## Prerequisites (tools to install)
+- **Node.js 18.19+** (project engine requirement)
+- **pnpm 9.4.0** (`corepack enable` then `corepack prepare pnpm@9.4.0 --activate`)
+- Optional: **Storybook** support is baked into `pnpm storybook` once dependencies are installed.
+- Optional: environment bootstrap script for Firebase, gcloud, Flutter, Android SDK, and GH CLI is in [`DOCS/ENV_SETUP.md`](DOCS/ENV_SETUP.md).
+- Optional: CI/test workflow and command checklist lives in [`DOCS/CI_TESTING.md`](DOCS/CI_TESTING.md).
+- Optional: renderer lifecycle overview for system orchestration is in [`DOCS/RENDERER_LIFECYCLE.md`](DOCS/RENDERER_LIFECYCLE.md).
+- Optional: GCP + Firebase provisioning steps live in [`DOCS/PROJECT_SETUP.md`](DOCS/PROJECT_SETUP.md).
+- Optional: repository directory manifest is in [`DOCS/REPO_MANIFEST.md`](DOCS/REPO_MANIFEST.md).
+- Optional: development track analysis is in [`DOCS/DEV_TRACK_ANALYSIS.md`](DOCS/DEV_TRACK_ANALYSIS.md).
+- Optional: WebGPU status/testing notes are in [`DOCS/WEBGPU_STATUS.md`](DOCS/WEBGPU_STATUS.md).
+
+## Baseline setup
+```bash
+pnpm install
+```
+
+## Daily dev commands
+| Goal | Command | Notes |
+| --- | --- | --- |
+| Start the web playground | `pnpm dev:web` | Opens Vite dev server. |
+| Build production bundle | `pnpm build:web` | Outputs `dist/`. |
+| Lint core engine sources | `pnpm lint` | ESLint runs on `src/**/*.{js,ts}`. |
+| Run tests | `pnpm test` | Runs Vitest in CLI mode. |
+| Analyze bundle size | `pnpm analyze:bundle` | Vite build in analyze mode. |
+| CI bundle check | `pnpm check:bundle` | Builds and runs size guard. |
+| Telemetry export (CLI) | `pnpm cli:telemetry -- <pack.json> --json --non-interactive --preview-count=4` | Agent-friendly JSON output. |
+| Storybook | `pnpm storybook` | Runs UI component workshop. |
+
+## Telemetry export workflow (agentic)
+1. **Prepare a pack** with `pack.scenes` (or `pack.states`) so preview generation has material.
+2. **Call the telemetry director** (`js/core/telemetry-director.js`) to generate previews and manifest data:
+   - `TelemetryDirector.generatePreviewSprites(pack, count)`
+   - `TelemetryDirector.exportPack(pack, options)`
+3. **Use the manifest pipeline** (`tools/telemetry/manifestPipeline.js`) to normalize metadata, compute hashes, and emit CLI-friendly summaries.
+4. **Persist the results** in your export path along with hash summaries for CI and caching.
+
+## Recommended agent checklist
+- Confirm Node/pnpm versions match the project constraints.
+- Install dependencies with `pnpm install`.
+- Run `pnpm lint` before export steps.
+- Use telemetry hash summaries for diff checks and CI caching.
+- Capture preview image artifacts if export tasks include visual outputs.
+- Review [`DOCS/CONTROL_REFERENCE.md`](DOCS/CONTROL_REFERENCE.md) and do a quick knowledge check:
+  - Name the geometry types available in the engine.
+  - List the control parameter names for each geometry type.
+
+If the answers are incomplete, continue with the workflow but flag the miss and point to the fix:
+- **If geometry types are wrong/missing:** review [`DOCS/CONTROL_REFERENCE.md`](DOCS/CONTROL_REFERENCE.md) to confirm the active system list.
+- **If control names are wrong/missing:** review [`DOCS/CONTROL_REFERENCE.md`](DOCS/CONTROL_REFERENCE.md) for the exact control IDs and parameter names.
+
+### Knowledge check response template (copy/paste)
+```
+Geometry types:
+- <type 1>
+- <type 2>
+- <type 3>
+- <type 4>
+
+Controls by geometry:
+- <type 1>: <control ids...>
+- <type 2>: <control ids...>
+- <type 3>: <control ids...>
+- <type 4>: <control ids...>
+```
+
+If any section is incomplete, proceed with the task but annotate the gap and point to [`DOCS/CONTROL_REFERENCE.md`](DOCS/CONTROL_REFERENCE.md) as the source of truth.
+
+## Troubleshooting
+- If `pnpm` is missing, run `corepack enable` then re-run the install step.
+- If telemetry previews fail in a browser context, ensure `TelemetryDirector` has a renderer that implements `captureFrame(scene)`.

package/DOCS/CONTROL_REFERENCE.md

@@ -0,0 +1,64 @@
+# Control & API Reference
+
+This document walks through every control surface in `index.html` and the JavaScript entry points they call so you can quickly map UI inputs to runtime behavior.
+
+## UI layout overview
+- **Top navigation**: System selector buttons (`switchSystem('faceted' | 'quantum' | 'holographic' | 'polychora')`), global Save button (`saveToGallery()`), gallery/audio/device-tilt/LLM/Interactivity toggles, and quick-access toolbar.
+- **Canvas containers**: Four stackable `<div class="holographic-layers">` containers: `vib34dLayers`, `quantumLayers`, `holographicLayers`, and `polychoraLayers`.
+- **Bottom bezel tabs**: Tab strip for Controls, Color, Geometry, Reactivity, and Export. Each tab exposes its own randomizer button plus quick-access buttons when the bezel is collapsed.
+
+## Slider controls
+Each `<input type="range">` updates its paired readout and calls `updateParameter(param, value)` from `js/controls/ui-handlers.js`.
+
+| Category | Control id | Range (step) | Display | Notes |
+| --- | --- | --- | --- | --- |
+| 3D rotations | `rot4dXY` | -6.28 to 6.28 (0.01) | `rot4dXY-display` | XY plane rotation. |
+|  | `rot4dXZ` | -6.28 to 6.28 (0.01) | `rot4dXZ-display` | XZ plane rotation. |
+|  | `rot4dYZ` | -6.28 to 6.28 (0.01) | `rot4dYZ-display` | YZ plane rotation. |
+| 4D rotations | `rot4dXW` | -6.28 to 6.28 (0.01) | `rot4dXW-display` | XW plane rotation. |
+|  | `rot4dYW` | -6.28 to 6.28 (0.01) | `rot4dYW-display` | YW plane rotation. |
+|  | `rot4dZW` | -6.28 to 6.28 (0.01) | `rot4dZW-display` | ZW plane rotation. |
+| Visual | `gridDensity` | 5 to 100 (1) | `gridDensity-display` | Grid resolution. |
+|  | `morphFactor` | 0 to 2 (0.01) | `morphFactor-display` | Morph blend factor. |
+|  | `chaos` | 0 to 1 (0.01) | `chaos-display` | Noise/chaos. |
+|  | `speed` | 0.1 to 3 (0.01) | `speed-display` | Animation speed. |
+| Color | `hue` | 0 to 360 (1) | `hue-display` | Hue in degrees. |
+|  | `saturation` | 0 to 1 (0.01) | `saturation-display` | Color saturation. |
+|  | `intensity` | 0 to 1 (0.01) | `intensity-display` | Color brightness. |
+
+### Slider handling pipeline
+1. The slider's `oninput` calls `updateParameter(param, value)`.
+2. `updateParameter` records the value in `window.userParameterState`, updates the readout element, and routes the parameter to the active engine (`faceted`, `quantum`, `holographic`, or `polychora`).
+3. Each engine uses its own setter: `parameterManager.setParameter` (faceted), `updateParameter` (quantum/holographic), or `updateParameters` (polychora). When an engine is not ready, the handler retries once before logging a warning.
+
+## Toggle controls
+- **System reactivity matrix**: Checkboxes for each system/interaction type (`facetedMouse`, `facetedClick`, `facetedScroll`, `quantumMouse`, `quantumClick`, `quantumScroll`, `holographicMouse`, `holographicClick`, `holographicScroll`) call `toggleSystemReactivity(system, interaction, checked)`.
+- **Audio-reactive channels**: Low/Medium/High checkboxes for Color/Geometry/Movement call `toggleAudioReactivity(level, channel, checked)` with `mediumColor` enabled by default.
+- **Device tilt**: `toggleDeviceTilt()` toggles gyroscope-driven rotation and updates the tilt button state.
+- **Audio master toggle**: `toggleAudio()` toggles the audio engine used by the reactivity matrix.
+- **Interactivity menu**: `toggleInteractivity()` exposes the interaction panel and uses `interactivityEnabled` tracking from the UI handlers module.
+
+## Geometry & system selection
+- **System selector buttons** call `switchSystem(systemName)` and visually mark the active system via `data-system` attributes.
+- **Geometry tab** uses `selectGeometry(index)` to switch among the 24 faceted/quantum options or the six polychora presets. `window.geometries` defines the labels for each system.
+
+## Quick actions and gallery hooks
+- **Randomizers**: `randomizeAll()` (parameters only) and `randomizeEverything()` (parameters + geometry + hue) are wired to the Randomize buttons across tabs and quick-access bar.
+- **Reset**: `resetAll()` restores all slider defaults and updates readouts.
+- **Gallery**: `saveToGallery()`, `openGallery()`, and `quickSave()/quickGallery()` integrate with `js/gallery` modules for persistence.
+
+## State management
+- `initializeStateManager()` runs during boot to restore state from URL parameters or `localStorage`, then sets up auto-save and keyboard shortcuts.
+- `captureCurrentState()` collects active system/geometry, parameters, UI state (active tab, bezel collapse, performance overlay), performance mode, and reactivity settings.
+- `restoreState(state)` replays captured values into the UI and engines after validating the payload.
+- Auto-save uses a 2s debounce (`autoSaveDelay`) and keeps a history stack (50 entries) for undo/redo behaviors.
+
+## Data dictionaries
+- **`window.geometries`**: Lists 24 faceted and quantum geometry labels (base, hypersphere core, hypertetrahedron core), a single holographic mode, and six polychora polychora solids.
+- **`window.userParameterState`**: Captures the most recent slider values for persistence and gallery snapshots.
+
+## Related modules
+- `js/controls/ui-handlers.js` – Slider/toggle handlers, randomize/reset helpers, and interactivity toggles.
+- `js/core/state-manager.js` – State capture/restore, URL/localStorage integration, and undo/redo history.
+- `js/interactions/device-tilt.js` – Gyroscope-driven rotation controls and button state updates.
+- `js/audio/audio-engine.js` – Audio reactivity toggles consumed by `toggleAudio` and `toggleAudioReactivity`.

package/DOCS/DEV_TRACK_ANALYSIS.md

@@ -0,0 +1,77 @@
+# Dev track analysis and next steps
+
+This document summarizes the current development track status, highlights gaps, and proposes the
+next execution steps. It should be updated after each multi-system delivery.
+
+**Last Updated:** 2026-01-30 (v2.0.0)
+
+## Current status snapshot
+- **Math foundation:** rotation utilities, projection clamping, and stability tests are in place.
+- **Renderer lifecycle:** unified contract and lifecycle manager are defined with adapters for the
+  core systems; resource tracking is centralized in the WebGL backend.
+- **Agentic tooling:** MCP/CLI response envelopes are standardized with schema validation.
+- **Docs/ops:** environment setup, CI testing, repo manifest, and project provisioning guides are
+  documented.
+- **WebGPU scaffold:** experimental backend initializes device/context and supports clear-pass render frames.
+- **WebGPU status/testing:** documented current WebGPU state and validation requirements.
+- **v2.0.0 Core Fixes (Phase A):** Quantum color restored, Faceted saturation + audio wired, clickIntensity bug fixed, shader sync tool added.
+- **v2.0.0 SpatialInputSystem:** Universal spatial input with 8 source types, 6 profiles, integrated into VIB3Engine. Decouples "card tilting" from device orientation.
+- **v2.0.0 Creative Tooling (Phase B):** Color presets (22), transitions (14 easings), post-processing (14 effects), parameter timeline (BPM sync).
+- **v2.0.0 Platform Integrations (Phase C):** React, Vue, Svelte component wrappers; Figma plugin; Three.js ShaderMaterial; TouchDesigner GLSL export; OBS mode.
+- **v2.0.0 Advanced Features (Phase D):** WebXR renderer, WebGPU compute shaders, MIDI controller, AI preset generator, OffscreenCanvas worker.
+
+## Completed phases
+| Phase | Status | Deliverables |
+|-------|--------|-------------|
+| Phase 1: Foundation | ✅ Complete | Math, geometry, parameters |
+| Phase 2: Rendering | ✅ Mostly Complete | Contracts, adapters, backends |
+| Phase 3: Agentic | ✅ Complete | MCP, CLI, Telemetry |
+| Phase 4: WebGPU | 🔄 In Progress | Scaffold exists |
+| Phase 5: Hardening | ✅ Complete | 694 tests, XSS prevention |
+| Phase A: Parity & Polish | ✅ Complete | Color/audio/saturation fixes |
+| Phase B: Creative Tooling | ✅ Complete | 4 modules, 3,837 lines |
+| Phase C: Platform Integrations | ✅ Complete | 7 modules, 4,693 lines |
+| Phase D: Advanced | ✅ Complete | 5 modules, 4,262 lines |
+| SpatialInputSystem | ✅ Complete | 1,783 lines, 8 sources, 6 profiles |
+
+## Key gaps to close
+1. **v2.0.0 module test coverage:**
+   - Creative, integrations, and advanced modules need unit/integration tests.
+   - SpatialInputSystem profiles need validation tests.
+2. **WebGPU prototype (Phase 4):**
+   - Confirm feature-flag gating and parity with WebGL backend entry points.
+   - Establish a minimal shader/material pipeline that mirrors the WebGL contract.
+3. **Platform integration validation:**
+   - Test React/Vue/Svelte components with actual framework projects.
+   - Validate Figma plugin with Figma Developer Console.
+   - Test TouchDesigner GLSL export in actual TD environment.
+4. **Cross-platform command buffers:**
+   - Document and validate the render command buffer format for Flutter/WASM integration.
+   - Ensure command buffer batching and lifecycle hooks align with `RendererContract`.
+5. **Telemetry export hardening:**
+   - Add validation for telemetry manifests and scene packs in CI.
+   - Produce golden snapshot tests for core geometries.
+
+## Recommended next steps
+1. **Test coverage for v2.0.0 modules:**
+   - Write Vitest unit tests for SpatialInputSystem (profile loading, input feeding, sensitivity).
+   - Write tests for creative tooling (preset application, transition interpolation, timeline playback).
+   - Add E2E tests for OBS mode and framework components.
+2. **NPM publish preparation:**
+   - Verify all package.json exports resolve correctly.
+   - Test tree-shaking with the creative/integrations/advanced imports.
+   - Run `npm pack --dry-run` to verify published file list.
+3. **WebGPU spike (Phase 4):**
+   - Build a feature-flagged WebGPU backend scaffold in `src/render/backends/`.
+   - Add a minimal triangle pipeline with uniform updates and buffer management.
+4. **Renderer diagnostics:**
+   - Expand `RenderResourceRegistry` stats to include peak usage and per-frame deltas.
+5. **Project automation:**
+   - Provide a scripted `make setup` (or `pnpm setup`) that runs env + project setup steps.
+
+## Risks and mitigation
+- **GPU resource churn:** ensure registry-based disposal is called during renderer swaps.
+- **Numerical drift:** keep normalization utilities and baseline tests running in CI.
+- **Cross-platform divergence:** ensure WebGL and WebGPU share material definitions.
+- **v2.0.0 module breadth:** 18 new files need test coverage before production use.
+- **Framework integration drift:** framework APIs evolve; pin versions in test fixtures.

package/DOCS/DEV_TRACK_PLAN_2026-01-07.md

@@ -0,0 +1,42 @@
+# Dev track plan (2026-01-07)
+
+This plan captures the staged work needed to deliver a production-ready agentic telemetry pipeline and export workflow. It is written as a living track plan so future sessions can append progress and maintain consistent architecture decisions.
+
+## North-star goals
+1. Agent-friendly CLI onboarding and help output.
+2. Deterministic telemetry manifest exports with previews and asset hashing.
+3. Clear documentation for automation, QA, and CI workflows.
+
+## Architecture anchors
+- **Telemetry pipeline**: `tools/telemetry/manifestPipeline.js` is the single source of truth for manifest normalization and hashing.
+- **Preview generation**: `js/core/telemetry-director.js` generates previews (renderer-backed or placeholders) and passes them into manifests.
+- **Docs hub**: `DOCS/` is the canonical location for workflow documentation (onboarding, telemetry, control references).
+
+## Planned track (phased)
+### Phase 1 — Onboarding + documentation hardening
+- Publish an agentic CLI onboarding guide with tool requirements, commands, and telemetry workflow steps.
+- Update README references so new onboarding docs are discoverable.
+- Extend telemetry docs with explicit CLI integration guidance and export flow notes.
+- Add a lightweight knowledge-check template that validates geometry/control comprehension without blocking execution.
+
+### Phase 2 — Agentic workflow hooks
+- Add CLI wrappers for telemetry export flows (pack selection, preview generation, manifest hashing).
+- Emit summaries designed for CI cache validation and diffing.
+- Provide optional validation hooks for manifest/preview consistency.
+
+### Phase 3 — Quality and verification
+- Add lint/test targets for telemetry outputs if applicable.
+- Document CI steps for telemetry export validation.
+- Add golden snapshot routines for preview images when the pipeline stabilizes.
+
+## Risks and mitigations
+- **Risk**: Hash drift due to unstable object serialization.  
+  **Mitigation**: Keep stable hashing in `manifestPipeline.js` and avoid non-deterministic fields.
+- **Risk**: Preview generation inconsistency across runtimes.  
+  **Mitigation**: Maintain browser-safe fallback encoding and ensure renderer contracts are documented.
+
+## Deliverables checklist
+- [ ] CLI onboarding doc is complete and linked in README.
+- [ ] Telemetry docs include export integration steps.
+- [ ] Agentic CLI support documented or implemented.
+- [ ] CI guidance includes telemetry hashes and preview artifacts.