feat(brain): add Beams — pooled merged-geometry pulse shader, bezier arcs

P4 of Cortex Brain v2.

  - brain-v2/util/bezierArc.js — quadratic bezier with control point
    lifted radially outward from origin (+18% mid-length). Returns
    segments+1 THREE.Vector3 points for any from→to pair.
  - brain-v2/PulseShader.js — ShaderMaterial with traveling pulse
    (uTime, head/trail smoothstep), per-vertex color attribute (aColor)
    fading to white at the head, RedFormat FloatType DataTexture for
    activation. Additive blending, depth-write off.
  - brain-v2/Beams.js — pre-allocated 64-slot pool, single merged
    LineSegments BufferGeometry (1088 verts: 64 × 17), attributes
    aProgress/aBeamId/aColor. fire({from, to, color, life}) writes 17
    bezier-arc verts into a slot + colors + activation. tick(now)
    advances uTime and decays activation per slot via riseDecay
    (rise 80 ms, τ 280 ms). Pool reuses oldest active slot when full.
    activeCount + dispose helpers.
  - brain-v2/index.jsx — mounts Beams alongside Satellites; tick fan-out
    drives both. Dev-only window.__brainFire(fromId, toId, color) for
    smoke testing.

Tests: 134 passed (vitest --run). Build: vite green.

Author: AdityaVG13

desktop/cortex-control-center/src/brain-v2/Beams.js

@@ -0,0 +1,142 @@
+import * as THREE from "three";
+import { bezierArcPoints } from "./util/bezierArc.js";
+import { createActivationTexture, createPulseMaterial } from "./PulseShader.js";
+import { riseDecay } from "./util/easing.js";
+
+const POOL_SIZE = 64;
+const SEGMENTS = 16;
+const VERTS_PER_BEAM = SEGMENTS + 1;
+const RISE_MS = 80;
+const TAU_MS = 280;
+const DEFAULT_LIFE_MS = 600;
+
+const _from = new THREE.Vector3();
+const _to = new THREE.Vector3();
+
+export function createBeams({ scene }) {
+  const totalVerts = POOL_SIZE * VERTS_PER_BEAM;
+  const positions = new Float32Array(totalVerts * 3);
+  const progresses = new Float32Array(totalVerts);
+  const beamIds = new Float32Array(totalVerts);
+  const colors = new Float32Array(totalVerts * 3);
+  const indices = new Uint16Array(POOL_SIZE * SEGMENTS * 2);
+
+  for (let beam = 0; beam < POOL_SIZE; beam += 1) {
+    for (let s = 0; s <= SEGMENTS; s += 1) {
+      const v = beam * VERTS_PER_BEAM + s;
+      progresses[v] = s / SEGMENTS;
+      beamIds[v] = beam;
+    }
+    for (let s = 0; s < SEGMENTS; s += 1) {
+      const i = (beam * SEGMENTS + s) * 2;
+      indices[i] = beam * VERTS_PER_BEAM + s;
+      indices[i + 1] = beam * VERTS_PER_BEAM + s + 1;
+    }
+  }
+
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+  geometry.setAttribute("aProgress", new THREE.BufferAttribute(progresses, 1));
+  geometry.setAttribute("aBeamId", new THREE.BufferAttribute(beamIds, 1));
+  geometry.setAttribute("aColor", new THREE.BufferAttribute(colors, 3));
+  geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+
+  const { texture, data } = createActivationTexture(POOL_SIZE);
+  const material = createPulseMaterial({
+    activationTexture: texture,
+    beamCount: POOL_SIZE,
+  });
+
+  const mesh = new THREE.LineSegments(geometry, material);
+  mesh.frustumCulled = false;
+  mesh.renderOrder = 1;
+  mesh.name = "brain-v2-beams";
+  scene.add(mesh);
+
+  const slots = Array.from({ length: POOL_SIZE }, () => ({
+    active: false,
+    startTime: 0,
+    lifeMs: DEFAULT_LIFE_MS,
+  }));
+
+  function findSlot(now) {
+    for (let i = 0; i < POOL_SIZE; i += 1) {
+      if (!slots[i].active) return i;
+    }
+    let oldestIdx = 0;
+    let oldestTime = Infinity;
+    for (let i = 0; i < POOL_SIZE; i += 1) {
+      if (slots[i].startTime < oldestTime) {
+        oldestTime = slots[i].startTime;
+        oldestIdx = i;
+      }
+    }
+    return oldestIdx;
+  }
+
+  function fire({ from, to, color = "#22d3ee", life = DEFAULT_LIFE_MS, now = performance.now() }) {
+    if (!from || !to) return -1;
+    _from.set(from.x, from.y, from.z);
+    _to.set(to.x, to.y, to.z);
+    const arc = bezierArcPoints(_from, _to, SEGMENTS, 0.18);
+    const slot = findSlot(now);
+    const baseVert = slot * VERTS_PER_BEAM;
+    const c = new THREE.Color(color);
+    for (let i = 0; i < arc.length; i += 1) {
+      const v = baseVert + i;
+      positions[v * 3 + 0] = arc[i].x;
+      positions[v * 3 + 1] = arc[i].y;
+      positions[v * 3 + 2] = arc[i].z;
+      colors[v * 3 + 0] = c.r;
+      colors[v * 3 + 1] = c.g;
+      colors[v * 3 + 2] = c.b;
+    }
+    geometry.attributes.position.needsUpdate = true;
+    geometry.attributes.aColor.needsUpdate = true;
+    slots[slot].active = true;
+    slots[slot].startTime = now;
+    slots[slot].lifeMs = life;
+    data[slot] = 0;
+    texture.needsUpdate = true;
+    return slot;
+  }
+
+  function tick(now = performance.now()) {
+    let dirty = false;
+    for (let i = 0; i < POOL_SIZE; i += 1) {
+      const slot = slots[i];
+      if (!slot.active) {
+        if (data[i] !== 0) {
+          data[i] = 0;
+          dirty = true;
+        }
+        continue;
+      }
+      const t = now - slot.startTime;
+      if (t >= slot.lifeMs) {
+        slot.active = false;
+        data[i] = 0;
+        dirty = true;
+        continue;
+      }
+      const value = riseDecay(t, RISE_MS, TAU_MS);
+      data[i] = Math.min(1, value);
+      dirty = true;
+    }
+    if (dirty) texture.needsUpdate = true;
+    material.uniforms.uTime.value = (now * 0.001) % 1000;
+  }
+
+  function activeCount() {
+    return slots.reduce((n, s) => n + (s.active ? 1 : 0), 0);
+  }
+
+  function dispose() {
+    scene.remove(mesh);
+    geometry.dispose();
+    material.dispose();
+    texture.dispose();
+  }
+
+  return { mesh, fire, tick, activeCount, dispose };
+}

desktop/cortex-control-center/src/brain-v2/PulseShader.js

@@ -0,0 +1,81 @@
+import * as THREE from "three";
+
+const VERTEX = /* glsl */ `
+attribute float aProgress;
+attribute float aBeamId;
+attribute vec3 aColor;
+uniform sampler2D uActivation;
+uniform float uBeamCount;
+varying float vProgress;
+varying float vActivation;
+varying vec3 vColor;
+
+void main() {
+  vProgress = aProgress;
+  vColor = aColor;
+  float u = (aBeamId + 0.5) / max(uBeamCount, 1.0);
+  vActivation = texture2D(uActivation, vec2(u, 0.5)).r;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+
+const FRAGMENT = /* glsl */ `
+precision mediump float;
+uniform float uTime;
+uniform float uHeadSpeed;
+uniform float uHeadWidth;
+uniform float uTrailWidth;
+uniform float uBaseOpacity;
+varying float vProgress;
+varying float vActivation;
+varying vec3 vColor;
+
+void main() {
+  float head = mod(uTime * uHeadSpeed, 1.0);
+  float lead = smoothstep(head - uHeadWidth, head, vProgress);
+  float trail = 1.0 - smoothstep(head, head + uTrailWidth, vProgress);
+  float pulse = lead * trail;
+
+  vec3 white = vec3(1.0);
+  vec3 color = mix(vColor, white, clamp(pulse, 0.0, 1.0));
+  float intensity = (uBaseOpacity + vActivation * 0.85 + pulse * vActivation * 1.4);
+  gl_FragColor = vec4(color * intensity, clamp(intensity, 0.0, 1.0));
+}
+`;
+
+export function createActivationTexture(slotCount) {
+  const size = Math.max(slotCount, 1);
+  const data = new Float32Array(size);
+  const texture = new THREE.DataTexture(data, size, 1, THREE.RedFormat, THREE.FloatType);
+  texture.needsUpdate = true;
+  texture.minFilter = THREE.NearestFilter;
+  texture.magFilter = THREE.NearestFilter;
+  texture.generateMipmaps = false;
+  return { texture, data };
+}
+
+export function createPulseMaterial({
+  activationTexture,
+  beamCount,
+  baseOpacity = 0.0,
+  headSpeed = 0.6,
+  headWidth = 0.1,
+  trailWidth = 0.22,
+} = {}) {
+  return new THREE.ShaderMaterial({
+    uniforms: {
+      uTime: { value: 0 },
+      uActivation: { value: activationTexture },
+      uBeamCount: { value: beamCount },
+      uHeadSpeed: { value: headSpeed },
+      uHeadWidth: { value: headWidth },
+      uTrailWidth: { value: trailWidth },
+      uBaseOpacity: { value: baseOpacity },
+    },
+    vertexShader: VERTEX,
+    fragmentShader: FRAGMENT,
+    transparent: true,
+    blending: THREE.AdditiveBlending,
+    depthWrite: false,
+  });
+}

desktop/cortex-control-center/src/brain-v2/index.jsx

@@ -2,13 +2,15 @@ import { useEffect, useRef, useState } from "react";
 import { createScene } from "./Scene.js";
 import { createCore, tickCore, disposeCore } from "./Core.js";
 import { createSatellites } from "./Satellites.js";
+import { createBeams } from "./Beams.js";
 import { buildTiers } from "./Tiers.js";
 
 export function BrainV2({ api = null, active = true }) {
   const containerRef = useRef(null);
   const sceneRef = useRef(null);
   const coreRef = useRef(null);
   const satellitesRef = useRef(null);
+  const beamsRef = useRef(null);
   const [dimensions, setDimensions] = useState({
     width: Math.max(window.innerWidth - 260, 400),
     height: Math.max(window.innerHeight - 20, 300),
@@ -45,13 +47,36 @@ export function BrainV2({ api = null, active = true }) {
     const satellites = createSatellites({ scene: sceneHandle.scene });
     satellitesRef.current = satellites;
 
+    const beams = createBeams({ scene: sceneHandle.scene });
+    beamsRef.current = beams;
+
+    if (typeof window !== "undefined") {
+      window.__brainFire = (fromId, toId, color) => {
+        const sats = satellitesRef.current;
+        if (!sats) return;
+        const a = sats.getSlotById(fromId);
+        const b = sats.getSlotById(toId) || { x: 0, y: 0, z: 0 };
+        if (!a) return;
+        beamsRef.current?.fire({ from: a, to: b, color: color || "#22d3ee" });
+        sats.pulseSlot(fromId);
+      };
+    }
+
     const unregister = sceneHandle.registerTick((t, now) => {
       tickCore(core, t, now);
       satellites.tick(t, now);
+      beams.tick(now);
     });
 
     return () => {
       unregister();
+      if (typeof window !== "undefined" && window.__brainFire) {
+        delete window.__brainFire;
+      }
+      if (beamsRef.current) {
+        beamsRef.current.dispose();
+        beamsRef.current = null;
+      }
       if (satellitesRef.current) {
         satellitesRef.current.dispose();
         satellitesRef.current = null;

desktop/cortex-control-center/src/brain-v2/util/bezierArc.js

@@ -0,0 +1,28 @@
+import * as THREE from "three";
+
+const _mid = new THREE.Vector3();
+const _control = new THREE.Vector3();
+
+export function bezierArcPoints(from, to, segments = 16, lift = 0.18) {
+  const points = [];
+  _mid.set(
+    (from.x + to.x) * 0.5,
+    (from.y + to.y) * 0.5,
+    (from.z + to.z) * 0.5,
+  );
+  const midLength = _mid.length();
+  if (midLength < 1e-3) {
+    _control.set(0, 1, 0).multiplyScalar(midLength * lift + 1);
+  } else {
+    _control.copy(_mid).normalize().multiplyScalar(midLength * (1 + lift));
+  }
+  for (let i = 0; i <= segments; i += 1) {
+    const t = i / segments;
+    const omt = 1 - t;
+    const x = omt * omt * from.x + 2 * omt * t * _control.x + t * t * to.x;
+    const y = omt * omt * from.y + 2 * omt * t * _control.y + t * t * to.y;
+    const z = omt * omt * from.z + 2 * omt * t * _control.z + t * t * to.z;
+    points.push(new THREE.Vector3(x, y, z));
+  }
+  return points;
+}

desktop/cortex-control-center/src/brain-visualizer.test.js

@@ -106,3 +106,42 @@ describe("Brain v2 scene scaffolding", () => {
     expect(fnv1a).toContain("16777619");
   });
 });
+
+describe("Brain v2 Beams + PulseShader", () => {
+  const beams = readFileSync(new URL("./brain-v2/Beams.js", import.meta.url), "utf8");
+  const pulseShader = readFileSync(new URL("./brain-v2/PulseShader.js", import.meta.url), "utf8");
+  const bezier = readFileSync(new URL("./brain-v2/util/bezierArc.js", import.meta.url), "utf8");
+
+  it("Beams pool 64 slots, single merged LineSegments, GLSL pulse material", () => {
+    expect(beams).toContain("POOL_SIZE = 64");
+    expect(beams).toContain("SEGMENTS = 16");
+    expect(beams).toContain("LineSegments");
+    expect(beams).toContain("createPulseMaterial");
+    expect(beams).toContain("createActivationTexture");
+    expect(beams).toContain("export function createBeams");
+    expect(beams).toContain("riseDecay");
+  });
+
+  it("PulseShader uses RedFormat FloatType DataTexture with NearestFilter", () => {
+    expect(pulseShader).toContain("export function createActivationTexture");
+    expect(pulseShader).toContain("export function createPulseMaterial");
+    expect(pulseShader).toContain("RedFormat");
+    expect(pulseShader).toContain("FloatType");
+    expect(pulseShader).toContain("NearestFilter");
+    expect(pulseShader).toContain("AdditiveBlending");
+    expect(pulseShader).toContain("uTime");
+    expect(pulseShader).toContain("vProgress");
+    expect(pulseShader).toContain("aColor");
+  });
+
+  it("bezierArcPoints returns segments+1 control-lifted points", () => {
+    expect(bezier).toContain("export function bezierArcPoints");
+    expect(bezier).toContain("normalize().multiplyScalar");
+  });
+
+  it("BrainV2 mounts Beams alongside Satellites and exposes window.__brainFire", () => {
+    expect(v2Index).toContain("createBeams");
+    expect(v2Index).toContain("beamsRef.current?.fire");
+    expect(v2Index).toContain("window.__brainFire");
+  });
+});