@vib3code/sdk 2.0.1-canary.261ce59

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (258) hide show
  1. package/CHANGELOG.md +118 -0
  2. package/DOCS/BLUEPRINT_EXECUTION_PLAN_2026-01-07.md +34 -0
  3. package/DOCS/CI_TESTING.md +38 -0
  4. package/DOCS/CLI_ONBOARDING.md +75 -0
  5. package/DOCS/CONTROL_REFERENCE.md +64 -0
  6. package/DOCS/DEV_TRACK_ANALYSIS.md +77 -0
  7. package/DOCS/DEV_TRACK_PLAN_2026-01-07.md +42 -0
  8. package/DOCS/DEV_TRACK_SESSION_2026-01-31.md +220 -0
  9. package/DOCS/ENV_SETUP.md +189 -0
  10. package/DOCS/EXPORT_FORMATS.md +417 -0
  11. package/DOCS/GPU_DISPOSAL_GUIDE.md +21 -0
  12. package/DOCS/LICENSING_TIERS.md +275 -0
  13. package/DOCS/MASTER_PLAN_2026-01-31.md +570 -0
  14. package/DOCS/OBS_SETUP_GUIDE.md +98 -0
  15. package/DOCS/PROJECT_SETUP.md +66 -0
  16. package/DOCS/RENDERER_LIFECYCLE.md +40 -0
  17. package/DOCS/REPO_MANIFEST.md +121 -0
  18. package/DOCS/SESSION_014_PLAN.md +195 -0
  19. package/DOCS/SESSION_LOG_2026-01-07.md +56 -0
  20. package/DOCS/STRATEGIC_BLUEPRINT_2026-01-07.md +72 -0
  21. package/DOCS/SYSTEM_AUDIT_2026-01-30.md +738 -0
  22. package/DOCS/SYSTEM_INVENTORY.md +520 -0
  23. package/DOCS/TELEMETRY_EXPORTS.md +34 -0
  24. package/DOCS/WEBGPU_STATUS.md +38 -0
  25. package/DOCS/XR_BENCHMARKS.md +608 -0
  26. package/LICENSE +21 -0
  27. package/README.md +478 -0
  28. package/docs/.nojekyll +0 -0
  29. package/docs/01-dissolution_of_euclidean_hegemony.html +346 -0
  30. package/docs/02-hyperspatial_ego_death.html +346 -0
  31. package/docs/03-post_cartesian_sublime.html +346 -0
  32. package/docs/04-crystalline_void_meditation.html +346 -0
  33. package/docs/05-quantum_decoherence_ballet.html +346 -0
  34. package/docs/06-dissolution_of_euclidean_hegemony.html +346 -0
  35. package/docs/07-hyperspatial_ego_death.html +346 -0
  36. package/docs/08-post_cartesian_sublime.html +346 -0
  37. package/docs/09-crystalline_void_meditation.html +346 -0
  38. package/docs/10-quantum_decoherence_ballet.html +346 -0
  39. package/docs/11-dissolution_of_euclidean_hegemony.html +346 -0
  40. package/docs/12-hyperspatial_ego_death.html +346 -0
  41. package/docs/13-post_cartesian_sublime.html +346 -0
  42. package/docs/index.html +794 -0
  43. package/docs/test-hub.html +441 -0
  44. package/docs/url-state.js +102 -0
  45. package/docs/vib3-exports/01-quantum-quantum-tetrahedron-lattice.html +489 -0
  46. package/docs/vib3-exports/02-quantum-quantum-hypersphere-matrix.html +489 -0
  47. package/docs/vib3-exports/03-quantum-quantum-hypertetra-fractal.html +489 -0
  48. package/docs/vib3-exports/04-faceted-faceted-crystal-structure.html +407 -0
  49. package/docs/vib3-exports/05-faceted-faceted-klein-bottle.html +407 -0
  50. package/docs/vib3-exports/06-faceted-faceted-hypertetra-torus.html +407 -0
  51. package/docs/vib3-exports/07-holographic-holographic-wave-field.html +457 -0
  52. package/docs/vib3-exports/08-holographic-holographic-hypersphere-sphere.html +457 -0
  53. package/docs/vib3-exports/09-holographic-holographic-hypertetra-crystal.html +457 -0
  54. package/docs/vib3-exports/index.html +238 -0
  55. package/docs/webgpu-live.html +702 -0
  56. package/package.json +369 -0
  57. package/src/advanced/AIPresetGenerator.js +777 -0
  58. package/src/advanced/MIDIController.js +703 -0
  59. package/src/advanced/OffscreenWorker.js +1051 -0
  60. package/src/advanced/WebGPUCompute.js +1051 -0
  61. package/src/advanced/WebXRRenderer.js +680 -0
  62. package/src/agent/cli/AgentCLI.js +615 -0
  63. package/src/agent/cli/index.js +14 -0
  64. package/src/agent/index.js +73 -0
  65. package/src/agent/mcp/MCPServer.js +950 -0
  66. package/src/agent/mcp/index.js +9 -0
  67. package/src/agent/mcp/tools.js +548 -0
  68. package/src/agent/telemetry/EventStream.js +669 -0
  69. package/src/agent/telemetry/Instrumentation.js +618 -0
  70. package/src/agent/telemetry/TelemetryExporters.js +427 -0
  71. package/src/agent/telemetry/TelemetryService.js +464 -0
  72. package/src/agent/telemetry/index.js +52 -0
  73. package/src/benchmarks/BenchmarkRunner.js +381 -0
  74. package/src/benchmarks/MetricsCollector.js +299 -0
  75. package/src/benchmarks/index.js +9 -0
  76. package/src/benchmarks/scenes.js +259 -0
  77. package/src/cli/index.js +678 -0
  78. package/src/config/ApiConfig.js +88 -0
  79. package/src/core/CanvasManager.js +217 -0
  80. package/src/core/ErrorReporter.js +117 -0
  81. package/src/core/ParameterMapper.js +333 -0
  82. package/src/core/Parameters.js +396 -0
  83. package/src/core/RendererContracts.js +200 -0
  84. package/src/core/UnifiedResourceManager.js +370 -0
  85. package/src/core/VIB3Engine.js +636 -0
  86. package/src/core/renderers/FacetedRendererAdapter.js +32 -0
  87. package/src/core/renderers/HolographicRendererAdapter.js +29 -0
  88. package/src/core/renderers/QuantumRendererAdapter.js +29 -0
  89. package/src/core/renderers/RendererLifecycleManager.js +63 -0
  90. package/src/creative/ColorPresetsSystem.js +980 -0
  91. package/src/creative/ParameterTimeline.js +1061 -0
  92. package/src/creative/PostProcessingPipeline.js +1113 -0
  93. package/src/creative/TransitionAnimator.js +683 -0
  94. package/src/export/CSSExporter.js +226 -0
  95. package/src/export/CardGeneratorBase.js +279 -0
  96. package/src/export/ExportManager.js +580 -0
  97. package/src/export/FacetedCardGenerator.js +279 -0
  98. package/src/export/HolographicCardGenerator.js +543 -0
  99. package/src/export/LottieExporter.js +552 -0
  100. package/src/export/QuantumCardGenerator.js +315 -0
  101. package/src/export/SVGExporter.js +519 -0
  102. package/src/export/ShaderExporter.js +903 -0
  103. package/src/export/TradingCardGenerator.js +3055 -0
  104. package/src/export/TradingCardManager.js +181 -0
  105. package/src/export/VIB3PackageExporter.js +559 -0
  106. package/src/export/index.js +14 -0
  107. package/src/export/systems/TradingCardSystemFaceted.js +494 -0
  108. package/src/export/systems/TradingCardSystemHolographic.js +452 -0
  109. package/src/export/systems/TradingCardSystemQuantum.js +411 -0
  110. package/src/faceted/FacetedSystem.js +963 -0
  111. package/src/features/CollectionManager.js +433 -0
  112. package/src/gallery/CollectionManager.js +240 -0
  113. package/src/gallery/GallerySystem.js +485 -0
  114. package/src/geometry/GeometryFactory.js +314 -0
  115. package/src/geometry/GeometryLibrary.js +72 -0
  116. package/src/geometry/buffers/BufferBuilder.js +338 -0
  117. package/src/geometry/buffers/index.js +18 -0
  118. package/src/geometry/generators/Crystal.js +420 -0
  119. package/src/geometry/generators/Fractal.js +298 -0
  120. package/src/geometry/generators/KleinBottle.js +197 -0
  121. package/src/geometry/generators/Sphere.js +192 -0
  122. package/src/geometry/generators/Tesseract.js +160 -0
  123. package/src/geometry/generators/Tetrahedron.js +225 -0
  124. package/src/geometry/generators/Torus.js +304 -0
  125. package/src/geometry/generators/Wave.js +341 -0
  126. package/src/geometry/index.js +142 -0
  127. package/src/geometry/warp/HypersphereCore.js +211 -0
  128. package/src/geometry/warp/HypertetraCore.js +386 -0
  129. package/src/geometry/warp/index.js +57 -0
  130. package/src/holograms/HolographicVisualizer.js +1073 -0
  131. package/src/holograms/RealHolographicSystem.js +966 -0
  132. package/src/holograms/variantRegistry.js +69 -0
  133. package/src/integrations/FigmaPlugin.js +854 -0
  134. package/src/integrations/OBSMode.js +754 -0
  135. package/src/integrations/ThreeJsPackage.js +660 -0
  136. package/src/integrations/TouchDesignerExport.js +552 -0
  137. package/src/integrations/frameworks/Vib3React.js +591 -0
  138. package/src/integrations/frameworks/Vib3Svelte.js +654 -0
  139. package/src/integrations/frameworks/Vib3Vue.js +628 -0
  140. package/src/llm/LLMParameterInterface.js +240 -0
  141. package/src/llm/LLMParameterUI.js +577 -0
  142. package/src/math/Mat4x4.js +708 -0
  143. package/src/math/Projection.js +341 -0
  144. package/src/math/Rotor4D.js +637 -0
  145. package/src/math/Vec4.js +476 -0
  146. package/src/math/constants.js +164 -0
  147. package/src/math/index.js +68 -0
  148. package/src/math/projections.js +54 -0
  149. package/src/math/rotations.js +196 -0
  150. package/src/quantum/QuantumEngine.js +906 -0
  151. package/src/quantum/QuantumVisualizer.js +1103 -0
  152. package/src/reactivity/ReactivityConfig.js +499 -0
  153. package/src/reactivity/ReactivityManager.js +586 -0
  154. package/src/reactivity/SpatialInputSystem.js +1783 -0
  155. package/src/reactivity/index.js +93 -0
  156. package/src/render/CommandBuffer.js +465 -0
  157. package/src/render/MultiCanvasBridge.js +340 -0
  158. package/src/render/RenderCommand.js +514 -0
  159. package/src/render/RenderResourceRegistry.js +523 -0
  160. package/src/render/RenderState.js +552 -0
  161. package/src/render/RenderTarget.js +512 -0
  162. package/src/render/ShaderLoader.js +253 -0
  163. package/src/render/ShaderProgram.js +599 -0
  164. package/src/render/UnifiedRenderBridge.js +496 -0
  165. package/src/render/backends/WebGLBackend.js +1108 -0
  166. package/src/render/backends/WebGPUBackend.js +1409 -0
  167. package/src/render/commands/CommandBufferExecutor.js +607 -0
  168. package/src/render/commands/RenderCommandBuffer.js +661 -0
  169. package/src/render/commands/index.js +17 -0
  170. package/src/render/index.js +367 -0
  171. package/src/scene/Disposable.js +498 -0
  172. package/src/scene/MemoryPool.js +618 -0
  173. package/src/scene/Node4D.js +697 -0
  174. package/src/scene/ResourceManager.js +599 -0
  175. package/src/scene/Scene4D.js +540 -0
  176. package/src/scene/index.js +98 -0
  177. package/src/schemas/error.schema.json +84 -0
  178. package/src/schemas/extension.schema.json +88 -0
  179. package/src/schemas/index.js +214 -0
  180. package/src/schemas/parameters.schema.json +142 -0
  181. package/src/schemas/tool-pack.schema.json +44 -0
  182. package/src/schemas/tool-response.schema.json +127 -0
  183. package/src/shaders/common/fullscreen.vert.glsl +5 -0
  184. package/src/shaders/common/fullscreen.vert.wgsl +17 -0
  185. package/src/shaders/common/geometry24.glsl +65 -0
  186. package/src/shaders/common/geometry24.wgsl +54 -0
  187. package/src/shaders/common/rotation4d.glsl +85 -0
  188. package/src/shaders/common/rotation4d.wgsl +86 -0
  189. package/src/shaders/common/uniforms.glsl +44 -0
  190. package/src/shaders/common/uniforms.wgsl +48 -0
  191. package/src/shaders/faceted/faceted.frag.glsl +129 -0
  192. package/src/shaders/faceted/faceted.frag.wgsl +164 -0
  193. package/src/shaders/holographic/holographic.frag.glsl +406 -0
  194. package/src/shaders/holographic/holographic.frag.wgsl +185 -0
  195. package/src/shaders/quantum/quantum.frag.glsl +513 -0
  196. package/src/shaders/quantum/quantum.frag.wgsl +361 -0
  197. package/src/testing/ParallelTestFramework.js +519 -0
  198. package/src/testing/__snapshots__/exportFormats.test.js.snap +24 -0
  199. package/src/testing/exportFormats.test.js +8 -0
  200. package/src/testing/projections.test.js +14 -0
  201. package/src/testing/rotations.test.js +37 -0
  202. package/src/ui/InteractivityMenu.js +516 -0
  203. package/src/ui/StatusManager.js +96 -0
  204. package/src/ui/adaptive/renderers/webgpu/BufferLayout.ts +252 -0
  205. package/src/ui/adaptive/renderers/webgpu/PolytopeInstanceBuffer.ts +144 -0
  206. package/src/ui/adaptive/renderers/webgpu/TripleBufferedUniform.ts +170 -0
  207. package/src/ui/adaptive/renderers/webgpu/WebGPURenderer.ts +735 -0
  208. package/src/ui/adaptive/renderers/webgpu/index.ts +112 -0
  209. package/src/variations/VariationManager.js +431 -0
  210. package/src/viewer/AudioReactivity.js +505 -0
  211. package/src/viewer/CardBending.js +481 -0
  212. package/src/viewer/GalleryUI.js +832 -0
  213. package/src/viewer/ReactivityManager.js +590 -0
  214. package/src/viewer/TradingCardExporter.js +600 -0
  215. package/src/viewer/ViewerPortal.js +374 -0
  216. package/src/viewer/index.js +12 -0
  217. package/src/wasm/WasmLoader.js +296 -0
  218. package/src/wasm/index.js +132 -0
  219. package/tools/agentic/mcpTools.js +88 -0
  220. package/tools/cli/agent-cli.js +92 -0
  221. package/tools/export/formats.js +24 -0
  222. package/tools/math/rotation-baseline.mjs +64 -0
  223. package/tools/shader-sync-verify.js +937 -0
  224. package/tools/telemetry/manifestPipeline.js +141 -0
  225. package/tools/telemetry/telemetryEvents.js +35 -0
  226. package/types/adaptive-sdk.d.ts +185 -0
  227. package/types/advanced/AIPresetGenerator.d.ts +81 -0
  228. package/types/advanced/MIDIController.d.ts +100 -0
  229. package/types/advanced/OffscreenWorker.d.ts +82 -0
  230. package/types/advanced/WebGPUCompute.d.ts +52 -0
  231. package/types/advanced/WebXRRenderer.d.ts +77 -0
  232. package/types/advanced/index.d.ts +46 -0
  233. package/types/core/ErrorReporter.d.ts +50 -0
  234. package/types/core/VIB3Engine.d.ts +204 -0
  235. package/types/creative/ColorPresetsSystem.d.ts +91 -0
  236. package/types/creative/ParameterTimeline.d.ts +74 -0
  237. package/types/creative/PostProcessingPipeline.d.ts +109 -0
  238. package/types/creative/TransitionAnimator.d.ts +71 -0
  239. package/types/creative/index.d.ts +35 -0
  240. package/types/integrations/FigmaPlugin.d.ts +46 -0
  241. package/types/integrations/OBSMode.d.ts +74 -0
  242. package/types/integrations/ThreeJsPackage.d.ts +62 -0
  243. package/types/integrations/TouchDesignerExport.d.ts +36 -0
  244. package/types/integrations/Vib3React.d.ts +74 -0
  245. package/types/integrations/Vib3Svelte.d.ts +63 -0
  246. package/types/integrations/Vib3Vue.d.ts +55 -0
  247. package/types/integrations/index.d.ts +52 -0
  248. package/types/reactivity/SpatialInputSystem.d.ts +173 -0
  249. package/types/reactivity/index.d.ts +394 -0
  250. package/types/render/CommandBuffer.d.ts +169 -0
  251. package/types/render/RenderCommand.d.ts +312 -0
  252. package/types/render/RenderState.d.ts +279 -0
  253. package/types/render/RenderTarget.d.ts +254 -0
  254. package/types/render/ShaderProgram.d.ts +277 -0
  255. package/types/render/UnifiedRenderBridge.d.ts +143 -0
  256. package/types/render/WebGLBackend.d.ts +168 -0
  257. package/types/render/WebGPUBackend.d.ts +186 -0
  258. package/types/render/index.d.ts +141 -0
package/README.md ADDED
@@ -0,0 +1,478 @@
1
+ # VIB3+ SDK
2
+
3
+ **General-purpose 4D rotation visualization SDK** for plugins, extensions, wearables, and agentic AI integration.
4
+
5
+ [![Tests](https://img.shields.io/badge/tests-933%20passing-brightgreen)](#testing)
6
+ [![Version](https://img.shields.io/badge/version-2.0.1-blue)](https://www.npmjs.com/package/@vib3code/sdk)
7
+ [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
8
+ [![npm](https://img.shields.io/npm/v/@vib3code/sdk)](https://www.npmjs.com/package/@vib3code/sdk)
9
+
10
+ ---
11
+
12
+ ## Quick Reference
13
+
14
+ | Metric | Value |
15
+ |--------|-------|
16
+ | **Active Systems** | 3 (Quantum, Faceted, Holographic) |
17
+ | **Rotation Planes** | 6 (XY, XZ, YZ + XW, YW, ZW) |
18
+ | **Geometries** | 24 per system (8 base × 3 cores) |
19
+ | **Canvas Layers** | 5 per system |
20
+ | **MCP Tools** | 20 agent-accessible tools |
21
+
22
+ ---
23
+
24
+ ## Features
25
+
26
+ - **3 Active Visualization Systems:** Quantum lattices, Faceted patterns, Holographic effects
27
+ - **24 Geometry Variants:** 8 base shapes × 3 core warp types (Base, Hypersphere, Hypertetrahedron)
28
+ - **6D Rotation:** Full control over 3D planes (XY/XZ/YZ) and 4D hyperspace planes (XW/YW/ZW)
29
+ - **Audio Reactivity:** Real-time visualization response to audio input (all 3 systems)
30
+ - **Agentic Integration:** MCP server with 20 tools for AI agent control
31
+ - **Cross-Platform:** Web, WASM, Flutter support
32
+
33
+ ### New in v2.0.0
34
+
35
+ - **Universal Spatial Input:** 8 input sources (tilt, gyroscope, gamepad, mouse, MIDI, audio, programmatic, perspective) with 6 built-in profiles (card tilt, wearable, game, VJ, UI, XR)
36
+ - **Creative Tooling:** 22 color presets, 14 easing transitions, 14 post-processing effects, keyframe timeline with BPM sync
37
+ - **Platform Integrations:** React, Vue, Svelte components; Figma plugin; Three.js ShaderMaterial; TouchDesigner GLSL export; OBS transparent background
38
+ - **Advanced Features:** WebXR VR/AR, WebGPU compute shaders, MIDI controller mapping, AI preset generation, OffscreenCanvas worker rendering
39
+ - **Shader Sync Tool:** Verifies inline shaders match external files across all systems
40
+
41
+ ---
42
+
43
+ ## Quick Start
44
+
45
+ ### 1. Install
46
+
47
+ ```bash
48
+ npm install @vib3code/sdk
49
+ ```
50
+
51
+ ### 2. Render in 5 lines
52
+
53
+ ```javascript
54
+ import { VIB3Engine } from '@vib3code/sdk/core';
55
+
56
+ const engine = new VIB3Engine();
57
+ (async () => {
58
+ await engine.initialize();
59
+ await engine.switchSystem('quantum');
60
+ engine.setParameter('geometry', 10); // Hypersphere + Sphere
61
+ engine.setParameter('hue', 200);
62
+ })();
63
+ ```
64
+
65
+ ### 3. Complete working example
66
+
67
+ Copy this into an HTML file and open it:
68
+
69
+ ```html
70
+ <!DOCTYPE html>
71
+ <html>
72
+ <body style="margin:0;background:#000;">
73
+ <div id="vib3" style="width:100vw;height:100vh;"></div>
74
+ <script type="module">
75
+ import { VIB3Engine } from '@vib3code/sdk/core';
76
+ const engine = new VIB3Engine();
77
+ (async () => {
78
+ await engine.initialize('vib3');
79
+ await engine.switchSystem('quantum');
80
+ engine.setParameter('geometry', 10);
81
+ engine.setParameter('rot4dXW', 1.57);
82
+ })();
83
+ </script>
84
+ </body>
85
+ </html>
86
+ ```
87
+
88
+ ### 4. Or scaffold a full project
89
+
90
+ ```bash
91
+ npx @vib3code/sdk init my-app
92
+ cd my-app
93
+ npm install
94
+ npm run dev
95
+ ```
96
+
97
+ ### Development (this repo)
98
+
99
+ ```bash
100
+ npm install
101
+ npm run dev # Start dev server
102
+ npm run build:web # Build for production
103
+ npm run build:lib # Build UMD + ESM for CDN/npm
104
+ npm test # Run unit tests
105
+ npm run test:e2e # Run E2E tests (Playwright)
106
+ npm run storybook # Component browser
107
+ npm run verify:shaders # Verify shader sync
108
+ ```
109
+
110
+ **Requirements:** Node.js 18.19+
111
+
112
+ ---
113
+
114
+ ## Visualization Systems
115
+
116
+ ### Active Systems
117
+
118
+ | System | Description | Geometries |
119
+ |--------|-------------|------------|
120
+ | **Quantum** | Complex lattice visualizations with quantum-inspired patterns | 24 |
121
+ | **Faceted** | Clean 2D geometric patterns with 4D rotation projection | 24 |
122
+ | **Holographic** | 5-layer audio-reactive holographic effects | 24 |
123
+
124
+ ### Placeholder (TBD)
125
+
126
+ | System | Status | Description |
127
+ |--------|--------|-------------|
128
+ | **Polychora** | TBD | 4D polytopes - not production ready |
129
+
130
+ ---
131
+
132
+ ## Geometry Encoding
133
+
134
+ ```
135
+ geometry_index = core_index * 8 + base_index
136
+ ```
137
+
138
+ ### Base Geometries (0-7)
139
+ | Index | Name | Description |
140
+ |-------|------|-------------|
141
+ | 0 | Tetrahedron | 4-vertex lattice |
142
+ | 1 | Hypercube | 4D cube (16 vertices, 32 edges) |
143
+ | 2 | Sphere | Radial harmonic sphere |
144
+ | 3 | Torus | Toroidal field |
145
+ | 4 | Klein Bottle | Non-orientable surface |
146
+ | 5 | Fractal | Recursive subdivision |
147
+ | 6 | Wave | Sinusoidal interference |
148
+ | 7 | Crystal | Octahedral structure |
149
+
150
+ ### Core Warp Types
151
+ | Index | Name | Geometry Range | Effect |
152
+ |-------|------|----------------|--------|
153
+ | 0 | Base | 0-7 | No warp |
154
+ | 1 | Hypersphere | 8-15 | 4D sphere wrap |
155
+ | 2 | Hypertetrahedron | 16-23 | 4D tetrahedron wrap |
156
+
157
+ ---
158
+
159
+ ## 6D Rotation System
160
+
161
+ | Plane | Type | Parameter | Range |
162
+ |-------|------|-----------|-------|
163
+ | XY | 3D Space | `rot4dXY` | -6.28 to 6.28 |
164
+ | XZ | 3D Space | `rot4dXZ` | -6.28 to 6.28 |
165
+ | YZ | 3D Space | `rot4dYZ` | -6.28 to 6.28 |
166
+ | XW | 4D Hyperspace | `rot4dXW` | -6.28 to 6.28 |
167
+ | YW | 4D Hyperspace | `rot4dYW` | -6.28 to 6.28 |
168
+ | ZW | 4D Hyperspace | `rot4dZW` | -6.28 to 6.28 |
169
+
170
+ ---
171
+
172
+ ## API Reference
173
+
174
+ ### JavaScript API
175
+
176
+ ```javascript
177
+ import { VIB3Engine } from '@vib3code/sdk/core';
178
+
179
+ // Initialize engine
180
+ const engine = new VIB3Engine();
181
+ await engine.initialize();
182
+
183
+ // Switch visualization system
184
+ await engine.switchSystem('quantum'); // 'quantum' | 'faceted' | 'holographic'
185
+
186
+ // Set geometry (0-23)
187
+ engine.setParameter('geometry', 10); // hypersphere + sphere
188
+
189
+ // Set 6D rotation
190
+ engine.setParameter('rot4dXW', 1.57);
191
+ engine.setParameter('rot4dYW', 0.5);
192
+
193
+ // Set visual parameters
194
+ engine.setParameter('hue', 200);
195
+ engine.setParameter('speed', 1.5);
196
+ engine.setParameter('chaos', 0.3);
197
+
198
+ // Get all parameters
199
+ const params = engine.getAllParameters();
200
+
201
+ // Randomize
202
+ engine.randomizeAll();
203
+
204
+ // Reset to defaults
205
+ engine.resetAll();
206
+ ```
207
+
208
+ ### Spatial Input API (v2.0.0)
209
+
210
+ ```javascript
211
+ // Enable spatial input with a profile
212
+ engine.enableSpatialInput('cardTilt'); // Traditional card tilt
213
+ engine.enableSpatialInput('vjAudioSpatial'); // Audio-reactive spatial
214
+
215
+ // Feed external spatial data
216
+ engine.feedSpatialInput({ pitch: 0.5, yaw: -0.3, roll: 0.1 });
217
+
218
+ // Adjust sensitivity and dramatic mode
219
+ engine.setSpatialSensitivity(2.0);
220
+ engine.setSpatialDramaticMode(true); // 8x amplification
221
+
222
+ // Available profiles: cardTilt, wearablePerspective, gameAsset,
223
+ // vjAudioSpatial, uiElement, immersiveXR
224
+ ```
225
+
226
+ ### Framework Integration (v2.0.0)
227
+
228
+ ```javascript
229
+ // React
230
+ import { Vib3Canvas, useVib3 } from '@vib3code/sdk/integrations/react';
231
+
232
+ // Vue
233
+ import { Vib3Canvas } from '@vib3code/sdk/integrations/vue';
234
+
235
+ // Svelte
236
+ import { Vib3Canvas } from '@vib3code/sdk/integrations/svelte';
237
+
238
+ // Three.js
239
+ import { Vib3ShaderMaterial } from '@vib3code/sdk/integrations/threejs';
240
+ ```
241
+
242
+ ### Parameter Reference
243
+
244
+ | Parameter | Range | Default | Description |
245
+ |-----------|-------|---------|-------------|
246
+ | `geometry` | 0-23 | 0 | Geometry index (coreIndex * 8 + baseIndex) |
247
+ | `rot4dXY` | -6.28 to 6.28 | 0 | XY plane rotation (radians) |
248
+ | `rot4dXZ` | -6.28 to 6.28 | 0 | XZ plane rotation |
249
+ | `rot4dYZ` | -6.28 to 6.28 | 0 | YZ plane rotation |
250
+ | `rot4dXW` | -6.28 to 6.28 | 0 | XW hyperplane rotation |
251
+ | `rot4dYW` | -6.28 to 6.28 | 0 | YW hyperplane rotation |
252
+ | `rot4dZW` | -6.28 to 6.28 | 0 | ZW hyperplane rotation |
253
+ | `gridDensity` | 5-100 | 15 | Grid resolution |
254
+ | `morphFactor` | 0-2 | 1.0 | Shape morph blend |
255
+ | `chaos` | 0-1 | 0.2 | Noise/turbulence |
256
+ | `speed` | 0.1-3 | 1.0 | Animation speed |
257
+ | `hue` | 0-360 | 200 | Color hue (degrees) |
258
+ | `saturation` | 0-1 | 0.8 | Color saturation |
259
+ | `intensity` | 0-1 | 0.5 | Brightness |
260
+
261
+ ---
262
+
263
+ ## MCP Server API (Agentic Integration)
264
+
265
+ The SDK includes an MCP (Model Context Protocol) server for AI agent integration.
266
+
267
+ ### Tools
268
+
269
+ | Tool | Description |
270
+ |------|-------------|
271
+ | `get_sdk_context` | Get SDK overview and onboarding quiz |
272
+ | `verify_knowledge` | Multiple choice quiz to verify understanding |
273
+ | `create_4d_visualization` | Create new visualization scene |
274
+ | `set_rotation` | Set 6D rotation values |
275
+ | `set_visual_parameters` | Adjust visual properties |
276
+ | `switch_system` | Change visualization system |
277
+ | `change_geometry` | Change geometry type (0-23) |
278
+ | `get_state` | Get current engine state |
279
+ | `randomize_parameters` | Randomize all parameters |
280
+ | `reset_parameters` | Reset to defaults |
281
+ | `save_to_gallery` | Save to gallery slot |
282
+ | `load_from_gallery` | Load from gallery slot |
283
+ | `search_geometries` | Query available geometries |
284
+ | `get_parameter_schema` | Get parameter validation schema |
285
+
286
+ ### Example MCP Usage
287
+
288
+ ```json
289
+ // Get SDK context (call first)
290
+ { "tool": "get_sdk_context" }
291
+
292
+ // Verify understanding
293
+ {
294
+ "tool": "verify_knowledge",
295
+ "args": {
296
+ "q1_rotation_planes": "c",
297
+ "q2_geometry_formula": "b",
298
+ "q3_canvas_layers": "c",
299
+ "q4_active_systems": "a",
300
+ "q5_base_geometries": "b",
301
+ "q6_core_types": "b"
302
+ }
303
+ }
304
+
305
+ // Create visualization
306
+ {
307
+ "tool": "create_4d_visualization",
308
+ "args": {
309
+ "system": "quantum",
310
+ "geometry_index": 10
311
+ }
312
+ }
313
+
314
+ // Set rotation
315
+ {
316
+ "tool": "set_rotation",
317
+ "args": {
318
+ "XW": 1.57,
319
+ "YW": 0.5,
320
+ "ZW": 0.3
321
+ }
322
+ }
323
+ ```
324
+
325
+ ---
326
+
327
+ ## CLI API
328
+
329
+ ```bash
330
+ # Start CLI in streaming mode
331
+ echo '{"type":"ping"}' | node src/cli/index.js
332
+
333
+ # Set parameter
334
+ echo '{"type":"set_parameter","param":"hue","value":200}' | node src/cli/index.js
335
+
336
+ # Get metrics
337
+ echo '{"type":"get_metrics"}' | node src/cli/index.js
338
+
339
+ # Simple text commands
340
+ echo 'ping' | node src/cli/index.js
341
+ echo 'status' | node src/cli/index.js
342
+ echo 'set hue 200' | node src/cli/index.js
343
+ echo 'geometry 10' | node src/cli/index.js
344
+ ```
345
+
346
+ ### CLI Commands
347
+
348
+ | Command | Description |
349
+ |---------|-------------|
350
+ | `ping` | Health check |
351
+ | `status` | Get engine status |
352
+ | `help` | List commands |
353
+ | `set <param> <value>` | Set parameter |
354
+ | `get <param>` | Get parameter |
355
+ | `rotate <plane> <angle>` | Rotate on plane |
356
+ | `geometry <index>` | Set geometry (0-23) |
357
+ | `system <name>` | Switch system |
358
+ | `metrics` | Get telemetry |
359
+
360
+ ---
361
+
362
+ ## Project Structure
363
+
364
+ ```
365
+ ├── src/ # Core SDK
366
+ │ ├── core/ # Engine orchestration
367
+ │ │ ├── VIB3Engine.js # Main unified engine (+ SpatialInput)
368
+ │ │ └── RendererContracts.js
369
+ │ ├── quantum/ # Quantum visualization
370
+ │ ├── faceted/ # Faceted visualization (+ audio/saturation)
371
+ │ ├── holograms/ # Holographic visualization
372
+ │ ├── geometry/ # 24-geometry system
373
+ │ ├── math/ # 4D math utilities
374
+ │ ├── render/ # Rendering pipeline
375
+ │ ├── agent/ # MCP/CLI/Telemetry
376
+ │ │ ├── mcp/ # MCP server
377
+ │ │ ├── cli/ # CLI interface
378
+ │ │ └── telemetry/ # Instrumentation
379
+ │ ├── export/ # Export generators
380
+ │ ├── reactivity/ # Reactivity + SpatialInputSystem (v2.0.0)
381
+ │ ├── creative/ # Color presets, transitions, post-FX, timeline (v2.0.0)
382
+ │ ├── integrations/ # React, Vue, Svelte, Figma, Three.js, TD, OBS (v2.0.0)
383
+ │ └── advanced/ # WebXR, WebGPU compute, MIDI, AI, Worker (v2.0.0)
384
+ ├── tools/ # Tooling (+ shader-sync-verify.js)
385
+ ├── cpp/ # C++ math core (WASM)
386
+ ├── js/ # Client-side integration
387
+ ├── tests/ # Test suite (933 tests)
388
+ ├── DOCS/ # Documentation
389
+ │ ├── SYSTEM_INVENTORY.md # Complete system reference
390
+ │ ├── SYSTEM_AUDIT_2026-01-30.md # Full system audit
391
+ │ ├── CLI_ONBOARDING.md # Agent CLI setup
392
+ │ └── CONTROL_REFERENCE.md # UI parameters
393
+ └── types/ # TypeScript definitions
394
+ ```
395
+
396
+ ---
397
+
398
+ ## Testing
399
+
400
+ ```bash
401
+ # Run all tests
402
+ npm test
403
+
404
+ # Run with coverage
405
+ npm test -- --coverage
406
+
407
+ # Run specific test
408
+ npm test -- tests/agent/AgentCLI.test.js
409
+ ```
410
+
411
+ **Current Status:** 933 tests passing
412
+
413
+ ---
414
+
415
+ ## Bundle Size
416
+
417
+ | Import | Gzipped | Description |
418
+ |--------|---------|-------------|
419
+ | Full package (npm) | ~653 KB | All systems, integrations, advanced features |
420
+ | `@vib3code/sdk/core` | ~15 KB | Engine only, no visualization systems |
421
+ | `+ quantum` | ~45 KB | Core + Quantum system |
422
+ | `+ faceted` | ~40 KB | Core + Faceted system |
423
+ | `+ holographic` | ~50 KB | Core + Holographic system |
424
+
425
+ Run `npm run analyze:bundle` to inspect your specific imports.
426
+
427
+ ---
428
+
429
+ ## Documentation
430
+
431
+ **Start here:**
432
+
433
+ | Document | What you'll learn |
434
+ |----------|-------------------|
435
+ | [`CLAUDE.md`](CLAUDE.md) | Full technical reference — architecture, shader system, all APIs |
436
+ | [`DOCS/SYSTEM_INVENTORY.md`](DOCS/SYSTEM_INVENTORY.md) | Complete system inventory with line counts and capabilities |
437
+ | [`DOCS/CONTROL_REFERENCE.md`](DOCS/CONTROL_REFERENCE.md) | Every parameter, its range, and what it does |
438
+
439
+ **Deep dives:**
440
+
441
+ | Document | What you'll learn |
442
+ |----------|-------------------|
443
+ | [`DOCS/SYSTEM_AUDIT_2026-01-30.md`](DOCS/SYSTEM_AUDIT_2026-01-30.md) | Full system audit — what works, what doesn't, what's planned |
444
+ | [`DOCS/CLI_ONBOARDING.md`](DOCS/CLI_ONBOARDING.md) | Setting up the agent CLI interface |
445
+ | [`DOCS/GPU_DISPOSAL_GUIDE.md`](DOCS/GPU_DISPOSAL_GUIDE.md) | WebGL context lifecycle and resource management |
446
+ | [`DOCS/EXPORT_FORMATS.md`](DOCS/EXPORT_FORMATS.md) | VIB3Package, Trading Card, Lottie export specs |
447
+ | [`DOCS/OBS_SETUP_GUIDE.md`](DOCS/OBS_SETUP_GUIDE.md) | OBS browser source integration |
448
+ | [`24-GEOMETRY-6D-ROTATION-SUMMARY.md`](24-GEOMETRY-6D-ROTATION-SUMMARY.md) | Geometry encoding formula and all 24 variants |
449
+
450
+ ---
451
+
452
+ ## Agent Onboarding Quiz
453
+
454
+ When connecting via MCP, agents should call `get_sdk_context` then `verify_knowledge`:
455
+
456
+ ```
457
+ Q1: How many rotation planes? → c) 6
458
+ Q2: Geometry formula? → b) core*8+base
459
+ Q3: Canvas layers per system? → c) 5
460
+ Q4: Active systems? → a) quantum, faceted, holographic
461
+ Q5: Base geometries? → b) 8
462
+ Q6: Core types? → b) base, hypersphere, hypertetrahedron
463
+ ```
464
+
465
+ ---
466
+
467
+ ## License
468
+
469
+ [MIT](LICENSE) — © 2025-2026 Paul Phillips / Clear Seas Solutions LLC
470
+
471
+ ---
472
+
473
+ ## Contact
474
+
475
+ - **Email:** Paul@clearseassolutions.com
476
+ - **Website:** [Parserator.com](https://parserator.com)
477
+
478
+ > *"The Revolution Will Not be in a Structured Format"*
package/docs/.nojekyll ADDED
File without changes