Neuro-Weaver

Neuro-Weaver is a brain-visualization engine for comparative neural storytelling. Its primary renderer is WebGPU, and it now ships with a toggleable WebGL2 fallback for debugging, automation, and renderer-port work. Both paths render the same 32x32x32 tensor field as animated cortex, fibers, somas, and thermal volume, then layer routines, stimuli, audio reactivity, ONNX inference, and optional C++ WASM simulation on top.

SynaptiX First

SynaptiX is the fastest way to understand the project. It mirrors a human tensor against a synthetic or AI-driven tensor and highlights:

• resonance: where the fields align
• divergence: where synthetic activation drifts from human activity
• anatomy mapping: occipital for early visual features, temporal/parietal for mid-level integration, frontal for deeper reasoning traces

Out of the box, SynaptiX ships with built-in "phantom" activations, so first-time users do not need external tensor files.

Live EEG / BCI

The BCI tab connects Muse 2, Muse S Classic/Athena, and OpenBCI Cyton/Cyton+Daisy streams to the human tensor. It includes local band-power processing, calibration, editable anatomical channel mapping, estimated signal quality, raw-plus-processed .nwbci recording, and deterministic replay. In SynaptiX mode, the live stream remains the human side while the existing AI source drives the comparison.

OpenBCI GUI uses the bundled localhost bridge:

npm run bci:bridge

See docs/bci-device.md for headset setup, bridge options, privacy notes, routine events, and verification.

WebXR VR / AR

Open the XR tab with ?renderer=webgl&openTab=xr to enter immersive VR or tabletop AR. The XR path renders stereo Organic and Connectome views, follows existing routine camera/spline events, supports controller orbit and lobe viewpoints, and turns trigger/hand-pinch rays into tensor stimuli.

See docs/webxr.md for controls, headset requirements, fallback behavior, and verification.

Quick Start

npm install
npm run dev

Open the local URL in Chrome or Edge with WebGPU enabled.

Renderer selection:

• ?renderer=webgpu forces the full WebGPU pipeline.
• ?renderer=webgl forces the WebGL2 fallback/debug renderer.
• The control-panel backend dropdown persists your last selection in localStorage.

Then try one of these:

1. Press X to run the SynaptiX showcase.
2. Open the SynaptiX tab and click Run SynaptiX Showcase (X).
3. Load /routines/synaptix_resonance.json or /routines/synaptix_hallucination.json through the routine UI.

What You’ll See

• Organic, Cyber, Connectome, and Heatmap are the baseline render styles.
• SynaptiX adds a second AI tensor buffer and comparative shader path.
• Built-in phantoms include aligned-prefrontal, hallucination-spike, visual-mismatch, and full-resonance.
• The showcase animates camera moves, bilateral stimuli, blend shifts, and resonance transitions without requiring external assets.

Switching Modes

A segmented pill selector sits at the top of the control panel and is always visible. Click a pill, or use the keyboard:

Key	Mode	Description
1	Organic	Smooth volumetric cortical surface shell.
2	Cyber	Glowing wireframe circuit lattice.
3	Connectome	Symmetrical glowing DTI fibre tracts (see below).
4	Heatmap	Volumetric thermal activity field.
5	SynaptiX	AI ↔ Human mirror comparison (X still runs the full showcase).

The active mode is highlighted with a glow and a brief mode toast. Switching only updates a uniform — no pipeline rebuild — so rapid toggling is glitch-free in both the WebGPU and WebGL2 backends. Mode hotkeys are ignored while typing in a text field or slider.

Connectome modes

The Connectome view defaults to anatomical tractography: bilaterally symmetric fibre bundles coloured by local orientation (DTI-style L-R red / I-S green / A-P blue) with a luminous emissive core. Three sliders tune it (Activity tab):

• Connectome Variant — 0 Anatomical DTI tracts ↔ 1 abstract Reasoning Pathways routing for SynaptiX storytelling.
• Fiber Symmetry — 0 free/organic ↔ 1 mirrored hemispheres.
• Bundle Coherence — higher values tighten fibres within each tract for a cleaner look.

All three keep the existing real-time signal pulsing, soma scaling, and spark pipelines intact.

Common Commands

npm install
npm run dev              # dev server, http://localhost:5173
npm run build            # web-only production build (default, no toolchain needed)
npm run build:full       # web + optional C++ WASM hybrid engine (requires Emscripten)
npm run preview
python3 scripts/test_run.py
python3 verification/verify_synaptix.py
python3 verification/verify_bci_device.py
python3 verification/verify_webxr.py

Build tiers

Neuro-Weaver's WASM engine is an optional runtime feature (src/wasm-engine.js falls back to the WebGPU/WebGL compute path when the module is absent), so it is never required to produce a working build:

Tier	Command	Requires Emscripten?	Produces
Dev	npm run dev	No	Vite dev server with hot reload
Web-only production	npm run build (alias: npm run build:web)	No	dist/ — Vite bundle only
Full hybrid	npm run build:full	Yes	dist/ + public/wasm/brain_tensor_engine.{mjs,wasm}

npm run build runs a prebuild check (scripts/check_wasm.sh) that prints an advisory notice — never a failure — when public/wasm/ hasn't been built. To build the WASM engine on its own (e.g. after installing Emscripten via .jules/setup.sh), run npm run build:wasm; it locates em++ via $EMSDK, an emsdk checkout in the repo root or $HOME, or an already-activated shell, instead of a hardcoded path. See docs/wasm-engine.md for details.

WebGL2 Fallback

Use the WebGL2 path when you need a visually inspectable reference renderer:

• easier agent and CI smoke checks
• debug helpers for wireframe, tensor points, and layer isolation
• comparison target while porting scientific 3D features back into WGSL/WebGPU

The WebGL2 path shares the same geometry generator, tensor buffers, camera state, style controls, and SynaptiX inputs, and — since the neural-field contract landed — the same physics: updateTensorSimulation() calls the shared CPU reference stepper in src/physics/tensor-field.js, which implements docs/tensor-physics.md alongside the C++/WASM engine. It used to carry a simplified approximation of its own, so CI screenshots rendered different physics from the app. Its rendering is still intentionally simpler than the WebGPU path.

Continuous Integration

.github/workflows/ci.yml runs on every push and pull request to main:

1. npm ci
2. npm test — headless Node assertions (uniform layout, shaders, and the neural-field golden fixture).
3. npm run test:golden — compiles the C++ neural-field engine with the runner's own C++17 compiler (no Emscripten) and compares it against the same fixture.
4. npm run build (equivalent to npx vite build) — frontend-only production build. CI does not provision an Emscripten SDK, so it never runs build:full/build:wasm; the WASM engine is optional at runtime (see docs/wasm-engine.md).
5. python3 scripts/test_run.py — dev server smoke test.
6. pip install playwright + playwright install chromium — sets up the Python Playwright runtime used by the verification scripts.
7. python3 verification/verify_suite.py — runs the Playwright-based visual verification suite against the ?renderer=webgl fallback (WebGPU/SwiftShader is too unreliable for headless CI).

node_modules and the Playwright browser cache are cached between runs. On failure, any screenshots written to verification/ are uploaded as a build artifact for debugging. The WASM build is never a CI gate — it stays a local/manual step until an Emscripten toolchain is added to the workflow.

Custom Neuromodulator UI

In Phase 21, we introduced a live-editable neuromodulator interface. Located in the right-side control panel, you can now toggle between predefined chemical profiles (Dopamine, Serotonin, Acetylcholine, GABA) or create your own custom profile. These parameters directly map to WebGPU compute uniforms and affect:

• Diffusion Rate: How fast signal spreads between voxels.
• Decay Rate: How long activity persists.
• Pulse Saturation & Trail Length: Visual properties of the signaling.
• Regional Retention Biases: Allow defining lobe-specific biases, mimicking specific functional states like high frontal-lobe retention during a dopamine flow state.

SynaptiX Notes

• Human activity lives in tensorBuffer; AI activity lives in aiTensorBuffer.
• The renderer blends them visually using aiInfluence, resonanceThreshold, and aiLayer.
• Non-32^3 activations are projected into the brain volume by src/synaptix-engine.js.
• Story routines for SynaptiX are served from public/routines.

See docs/synaptix.md for the mapping table, routine vocabulary, and instructions for recording your own activations. See docs/webgl-fallback.md for backend selection, debug controls, and WebGL-to-WebGPU porting notes.

More Documentation

See CONTRIBUTING.md for a full map of where to look, and docs/ROADMAP.md for phase history, open items, and the future-ideas backlog.