VIB3+ SDK Development

Help extend, refactor, test, and build new features for the VIB3+ 4D visualization engine.

Development Workflow

1. Read Before Writing

• •CLAUDE.md — Architecture, shader system, C++ core, uniforms, projections
• •Module-specific docs in DOCS/ (see References below)
• •Existing source in the target module directory

2. Analyze Existing Patterns

• •Constructor: new Module(options = {})
• •Callbacks: (paramName, value) => void
• •ES Modules throughout, JSDoc on public APIs
• •No hidden globals beyond window.Vib3Core

3. Plan Changes

VIB3+ is highly interconnected — identify ALL affected files:

• •Shader changes → GLSL + WGSL variants + inline shader sync
• •New parameters → MCP tool schema + agent-config updates
• •New systems → engine registration + keyboard shortcut + MCP enum

4. Implement → Test → Verify Shaders → Update Docs

Architecture

index.html / js/core/app.js
    ↓
VIB3Engine (src/core/VIB3Engine.js)
    ├→ QuantumEngine (src/quantum/)
    ├→ FacetedSystem (src/faceted/)
    └→ RealHolographicSystem (src/holograms/)
    ↓
ReactivityManager + SpatialInputSystem (src/reactivity/)
    ↓
WebGLBackend / WebGPUBackend (src/render/backends/)
    ↓
ShaderProgram (GLSL/WGSL) → Math Layer (src/math/)
    ↓
C++ WASM Core (cpp/) — Clifford algebra Cl(4,0)
    ├→ cpp/math/       Rotor4D, Mat4x4, Vec4, Projection
    ├→ cpp/geometry/   8 generators + WarpFunctions
    ├→ cpp/bindings/   embind.cpp
    ├→ cpp/include/    vib3_ffi.h
    ├→ cpp/src/        vib3_ffi.cpp
    └→ cpp/tests/      Rotor4D_test, Mat4x4_test, etc.

Full details in CLAUDE.md.

Checklists

New Geometry

• • Generator in src/geometry/generators/
• • Register in src/geometry/GeometryFactory.js
• • Metadata in src/geometry/GeometryLibrary.js
• • GLSL in src/shaders/common/geometry24.glsl
• • WGSL in src/shaders/common/geometry24.wgsl
• • Update inline shaders in QuantumVisualizer.js, FacetedSystem.js, HolographicVisualizer.js
• • C++ generator in cpp/geometry/ if WASM-accelerated
• • Tests in tests/geometry/
• • npm run verify:shaders

Warning: A 9th base geometry shifts all hypersphere (9-17) and hypertetra (18-26) indices — breaking change.

New Shader

• • Both .glsl and .wgsl variants
• • Standard uniforms (u_time, u_resolution, u_geometry, u_rot4d*, etc.)
• • 6D rotation: rotateXY * rotateXZ * rotateYZ * rotateXW * rotateYW * rotateZW
• • 4D→3D projection (perspective/stereographic/orthographic)
• • Sync inline shaders with external files
• • npm run verify:shaders

New MCP Tool

• • Definition in src/agent/mcp/tools.js (name, description, inputSchema)
• • Handler in src/agent/mcp/MCPServer.js handleToolCall()
• • Update agent-config/claude-agent-context.md
• • Update agent-config/openai-agent-context.md
• • Tests in tests/agent/

New Visualization System

1. •Create src/newsystem/ directory
2. •Renderer following src/core/RendererContracts.js
3. •Adapter in src/core/renderers/
4. •Register in VIB3Engine.js switchSystem()
5. •GLSL + WGSL shaders in src/shaders/newsystem/
6. •Keyboard shortcut (next number key)
7. •MCP switch_system enum in tools.js
8. •Tests + CLAUDE.md update

New Platform Integration

• • Follow src/integrations/frameworks/Vib3React.js pattern
• • Lifecycle: init, update, destroy
• • Map VIB3+ params to integration props
• • GPU resource disposal (see DOCS/GPU_DISPOSAL_GUIDE.md)

Commands

npm test              # Unit tests (Vitest + happy-dom)
npm run test:e2e      # E2E browser tests (Playwright)
npm run verify:shaders # Shader sync (GLSL/WGSL inline vs external)
npm run lint          # ESLint
npm run bench         # Performance benchmarks
npm run dev           # Vite dev server
cd cpp && ./build.sh  # Build WASM core

Key Rules

1. •6D rotation order: Always XY → XZ → YZ → XW → YW → ZW
2. •WASM optional: JS fallbacks in src/math/
3. •WebGPU optional: Falls back to WebGL
4. •3 active systems: Quantum, Faceted, Holographic (Polychora is TBD)
5. •Shader sync enforced: Pre-commit hook on .glsl/.wgsl changes
6. •Column-major: C++ Mat4x4 = float m[16] column-major
7. •Rotor normalization: Normalize after composition to prevent drift

References

• •CLAUDE.md — Full technical reference (architecture, C++ types, shader uniforms, projections)
• •DOCS/STATUS.md — Current release status
• •DOCS/CI_TESTING.md — Test infrastructure, CI config
• •DOCS/GPU_DISPOSAL_GUIDE.md — GPU cleanup patterns
• •DOCS/RENDERER_LIFECYCLE.md — Render pipeline lifecycle
• •DOCS/WEBGPU_STATUS.md — WebGPU feature support matrix
• •DOCS/REPO_MANIFEST.md — Complete project structure
• •DOCS/ENV_SETUP.md — Dev environment setup
• •DOCS/AGENT_HARNESS_ARCHITECTURE.md — MCP tool catalog, feedback loop
• •DOCS/MASTER_PLAN_2026-01-31.md — Roadmap priorities
• •src/agent/mcp/tools.js — MCP tool definitions with JSON schemas
• •tools/shader-sync-verify.js — Shader sync verification tool