feat(brain): ripple engine — BFS-timed activation drives pulse shader on click

P4 of Constellation Lattice redesign.

- Add brain/easing.js — clamp01, easeOutCubic, easeInQuad, expDecay (canonical exp(-t/tau)), riseDecay (cubic rise to 1.0 over riseMs, then exp decay with tau).
- Add brain/RippleEngine.js — depth-capped BFS (cap = 2), per-hop delay 110ms, rise 80ms, tau 280ms, depth attenuation 0.55^depth, RIPPLE_LIFE_MS = depth*step + rise + 500ms tail. attachMesh binds the EdgeMesh activation buffer + DataTexture; buildAdjacency keys by edgeIndex from the mesh; fire(nodeId, now) runs BFS once and pushes a ripple; tick(now) zeroes the buffer, accumulates riseDecay × depth attenuation across active ripples, clamps at 1.0, sets texture.needsUpdate. Multiple ripples are additive. fireAmbient picks a random adjacency node (used in P5 for auto-rotate ambient firing). Observer hooks for fire / reach.
- Wire BrainVisualizer.jsx — instantiate RippleEngine on graphData change, attach to the merged edge mesh, run engine.tick(now) inside the existing edge-mesh rAF loop alongside tickEdgeMaterialTime. selectGraphNode now calls rippleEngineRef.current?.fire(nextNode.id, performance.now()) on selection — every click animates a propagating ripple along the edge shader.
- Tests: brain/__tests__/RippleEngine.test.js — depth cap, additivity + clamp, decay-to-zero after lifetime, fire/reach observers, fireAmbient. brain/__tests__/easing.test.js — boundaries, monotonic, exp decay points, riseDecay envelope. brain-visualizer.test.js — assert engine wiring (import, instantiate, attachMesh, buildAdjacency, tick, fire on click).

Tests: 144 passed. Build: vite green (BrainVisualizer 1.43MB / 384KB gzip).

Author: AdityaVG13

desktop/cortex-control-center/src/BrainVisualizer.jsx

@@ -11,6 +11,7 @@ import { applyShellLayout, createShellProjectionForce } from "./brain/ShellLayou
 import { BRAIN_LAYERS, assignLayer, markBloom } from "./brain/RenderLayers.js";
 import { attachBloom } from "./brain/PostFx.js";
 import { buildEdgeMesh, disposeEdgeMesh, tickEdgeMaterialTime } from "./brain/EdgeMesh.js";
+import { RippleEngine } from "./brain/RippleEngine.js";
 
 const BRAIN_NODE_COLORS = Object.freeze({
   memory: "#22d3ee",
@@ -206,6 +207,7 @@ function BrainVisualizerComponent({ api = null, cortexBase = "http://127.0.0.1:7
   const bloomRef = useRef(null);
   const edgeMeshRef = useRef(null);
   const edgeTickRef = useRef(null);
+  const rippleEngineRef = useRef(null);
   const [graphData, setGraphData] = useState({ nodes: [], links: [] });
   const [bloomActive, setBloomActive] = useState(true);
   const [useShellSplit, setUseShellSplit] = useState(true);
@@ -349,10 +351,17 @@ function BrainVisualizerComponent({ api = null, cortexBase = "http://127.0.0.1:7
       edgeMeshRef.current = mesh;
       bloomRef.current?.refreshSelection?.();
 
+      const engine = new RippleEngine();
+      engine.attachMesh(mesh);
+      engine.buildAdjacency(graphData.links);
+      rippleEngineRef.current = engine;
+
       const start = performance.now();
       const tick = () => {
-        const elapsedSec = (performance.now() - start) * 0.001;
+        const now = performance.now();
+        const elapsedSec = (now - start) * 0.001;
         tickEdgeMaterialTime(mesh, elapsedSec);
+        engine.tick(now);
         edgeTickRef.current = requestAnimationFrame(tick);
       };
       edgeTickRef.current = requestAnimationFrame(tick);
@@ -363,6 +372,10 @@ function BrainVisualizerComponent({ api = null, cortexBase = "http://127.0.0.1:7
         cancelAnimationFrame(edgeTickRef.current);
         edgeTickRef.current = null;
       }
+      if (rippleEngineRef.current) {
+        rippleEngineRef.current.reset();
+        rippleEngineRef.current = null;
+      }
       if (edgeMeshRef.current) {
         disposeEdgeMesh(edgeMeshRef.current);
         edgeMeshRef.current = null;
@@ -676,6 +689,7 @@ function BrainVisualizerComponent({ api = null, cortexBase = "http://127.0.0.1:7
 
     setAutoRotate(false);
     if (nextNode && graphRef.current) focusGraphNode(graphRef.current, nextNode);
+    if (nextNode) rippleEngineRef.current?.fire(nextNode.id, performance.now());
 
     selectedNodeRef.current = nextNode;
     if (selectionFrameRef.current) cancelAnimationFrame(selectionFrameRef.current);

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

@@ -171,4 +171,13 @@ describe("Brain visualizer", () => {
     expect(source).toContain("controls.dampingFactor = 0.085");
     expect(source).toContain("controls.zoomToCursor = true");
   });
+
+  it("BrainVisualizer instantiates RippleEngine, ticks per frame, and fires on click", () => {
+    expect(source).toContain("import { RippleEngine }");
+    expect(source).toContain("new RippleEngine()");
+    expect(source).toContain("engine.attachMesh(mesh)");
+    expect(source).toContain("engine.buildAdjacency(graphData.links)");
+    expect(source).toContain("engine.tick(now)");
+    expect(source).toContain("rippleEngineRef.current?.fire(nextNode.id, performance.now())");
+  });
 });

desktop/cortex-control-center/src/brain/RippleEngine.js

@@ -0,0 +1,168 @@
+import { riseDecay } from "./easing.js";
+
+const DEPTH_CAP = 2;
+const STEP_MS = 110;
+const RISE_MS = 80;
+const TAU_MS = 280;
+const DEPTH_ATTENUATION = 0.55;
+const RIPPLE_VISIBLE_TAIL_MS = 500;
+const RIPPLE_LIFE_MS = DEPTH_CAP * STEP_MS + RISE_MS + RIPPLE_VISIBLE_TAIL_MS;
+
+function endpointId(endpoint) {
+  if (endpoint && typeof endpoint === "object") return endpoint.id;
+  return endpoint;
+}
+
+function edgeKey(sourceId, targetId, type = "semantic") {
+  return `${sourceId}>${targetId}>${type}`;
+}
+
+export class RippleEngine {
+  constructor() {
+    this.adjacency = new Map();
+    this.edgeIndex = new Map();
+    this.activationData = null;
+    this.activationTexture = null;
+    this.edgeCount = 0;
+    this.ripples = [];
+    this.observers = { fire: new Set(), reach: new Set() };
+  }
+
+  attachMesh(mesh) {
+    if (!mesh?.userData) return;
+    this.edgeIndex = mesh.userData.edgeIndex || new Map();
+    this.activationData = mesh.userData.activationData || null;
+    this.activationTexture = mesh.userData.activationTexture || null;
+    this.edgeCount = mesh.userData.edgeCount || 0;
+  }
+
+  buildAdjacency(links) {
+    const adjacency = new Map();
+    for (const link of links || []) {
+      const sourceId = endpointId(link.source);
+      const targetId = endpointId(link.target);
+      const type = link.type || "semantic";
+      const key = edgeKey(sourceId, targetId, type);
+      const edgeId = this.edgeIndex.get(key);
+      if (edgeId === undefined) continue;
+
+      if (!adjacency.has(sourceId)) adjacency.set(sourceId, []);
+      if (!adjacency.has(targetId)) adjacency.set(targetId, []);
+      adjacency.get(sourceId).push({ neighborId: targetId, edgeId });
+      adjacency.get(targetId).push({ neighborId: sourceId, edgeId });
+    }
+    this.adjacency = adjacency;
+  }
+
+  bfs(sourceId) {
+    const visitedNodes = new Map();
+    const visitedEdges = new Map();
+    const reachOrder = [];
+    visitedNodes.set(sourceId, 0);
+
+    let frontier = [sourceId];
+    for (let depth = 1; depth <= DEPTH_CAP; depth += 1) {
+      const next = [];
+      for (const nodeId of frontier) {
+        const neighbors = this.adjacency.get(nodeId) || [];
+        for (const { neighborId, edgeId } of neighbors) {
+          if (!visitedEdges.has(edgeId)) {
+            visitedEdges.set(edgeId, depth - 1);
+          }
+          if (!visitedNodes.has(neighborId)) {
+            visitedNodes.set(neighborId, depth);
+            reachOrder.push({ neighborId, depth });
+            next.push(neighborId);
+          }
+        }
+      }
+      frontier = next;
+      if (!frontier.length) break;
+    }
+
+    return { visitedNodes, visitedEdges, reachOrder };
+  }
+
+  fire(sourceId, now = performance.now()) {
+    if (!this.adjacency.has(sourceId)) return null;
+    const result = this.bfs(sourceId);
+    const ripple = {
+      sourceId,
+      startTime: now,
+      visitedNodes: result.visitedNodes,
+      visitedEdges: result.visitedEdges,
+      reachOrder: result.reachOrder,
+      reached: new Set(),
+    };
+    this.ripples.push(ripple);
+    this.notify("fire", { sourceId, time: now });
+    return ripple;
+  }
+
+  fireAmbient(now = performance.now()) {
+    const ids = [...this.adjacency.keys()];
+    if (!ids.length) return null;
+    const id = ids[Math.floor(Math.random() * ids.length)];
+    return this.fire(id, now);
+  }
+
+  on(event, callback) {
+    this.observers[event]?.add(callback);
+    return () => this.observers[event]?.delete(callback);
+  }
+
+  notify(event, payload) {
+    const set = this.observers[event];
+    if (!set) return;
+    for (const cb of set) {
+      try { cb(payload); } catch { /* observer errors must not break ticks */ }
+    }
+  }
+
+  tick(now = performance.now()) {
+    if (!this.activationData || !this.activationTexture) return;
+
+    this.activationData.fill(0);
+    const next = [];
+
+    for (const ripple of this.ripples) {
+      const elapsed = now - ripple.startTime;
+      if (elapsed > RIPPLE_LIFE_MS) continue;
+
+      for (const [edgeId, depth] of ripple.visitedEdges) {
+        const t = elapsed - depth * STEP_MS;
+        if (t < 0) continue;
+        const value = riseDecay(t, RISE_MS, TAU_MS) * Math.pow(DEPTH_ATTENUATION, depth);
+        const current = this.activationData[edgeId] || 0;
+        this.activationData[edgeId] = Math.min(1, current + value);
+      }
+
+      for (const reach of ripple.reachOrder) {
+        if (ripple.reached.has(reach.neighborId)) continue;
+        const arrival = reach.depth * STEP_MS;
+        if (elapsed >= arrival) {
+          ripple.reached.add(reach.neighborId);
+          this.notify("reach", { nodeId: reach.neighborId, depth: reach.depth });
+        }
+      }
+
+      next.push(ripple);
+    }
+
+    this.ripples = next;
+    this.activationTexture.needsUpdate = true;
+  }
+
+  reset() {
+    this.ripples = [];
+    if (this.activationData) this.activationData.fill(0);
+    if (this.activationTexture) this.activationTexture.needsUpdate = true;
+  }
+
+  static get DEPTH_CAP() { return DEPTH_CAP; }
+  static get STEP_MS() { return STEP_MS; }
+  static get RISE_MS() { return RISE_MS; }
+  static get TAU_MS() { return TAU_MS; }
+  static get DEPTH_ATTENUATION() { return DEPTH_ATTENUATION; }
+  static get RIPPLE_LIFE_MS() { return RIPPLE_LIFE_MS; }
+}

desktop/cortex-control-center/src/brain/__tests__/RippleEngine.test.js

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { RippleEngine } from "../RippleEngine.js";
+
+function makeMesh(edgeIndex, edgeCount) {
+  return {
+    userData: {
+      edgeIndex,
+      edgeCount,
+      activationData: new Float32Array(edgeCount),
+      activationTexture: { needsUpdate: false },
+    },
+  };
+}
+
+function buildLineGraph(n) {
+  const links = [];
+  const edgeIndex = new Map();
+  for (let i = 0; i < n - 1; i += 1) {
+    const link = { source: `n${i}`, target: `n${i + 1}`, type: "semantic" };
+    edgeIndex.set(`n${i}>n${i + 1}>semantic`, i);
+    links.push(link);
+  }
+  return { links, edgeIndex, edgeCount: n - 1 };
+}
+
+describe("RippleEngine", () => {
+  it("respects depth cap of 2 hops on a long line graph", () => {
+    const graph = buildLineGraph(8);
+    const mesh = makeMesh(graph.edgeIndex, graph.edgeCount);
+    const engine = new RippleEngine();
+    engine.attachMesh(mesh);
+    engine.buildAdjacency(graph.links);
+
+    const ripple = engine.fire("n0", 0);
+    const visitedDepths = [...ripple.visitedNodes.values()];
+    expect(Math.max(...visitedDepths)).toBe(RippleEngine.DEPTH_CAP);
+    expect(ripple.visitedNodes.has("n4")).toBe(false);
+    expect(ripple.visitedNodes.get("n2")).toBe(2);
+  });
+
+  it("activations are additive across simultaneous ripples and clamp at 1.0", () => {
+    const graph = buildLineGraph(4);
+    const mesh = makeMesh(graph.edgeIndex, graph.edgeCount);
+    const engine = new RippleEngine();
+    engine.attachMesh(mesh);
+    engine.buildAdjacency(graph.links);
+
+    engine.fire("n0", 0);
+    engine.fire("n2", 0);
+    engine.tick(60);
+    const buffer = mesh.userData.activationData;
+    for (const value of buffer) {
+      expect(value).toBeGreaterThanOrEqual(0);
+      expect(value).toBeLessThanOrEqual(1);
+    }
+    expect(buffer[1]).toBeGreaterThan(0);
+  });
+
+  it("decays back to zero after RIPPLE_LIFE_MS", () => {
+    const graph = buildLineGraph(3);
+    const mesh = makeMesh(graph.edgeIndex, graph.edgeCount);
+    const engine = new RippleEngine();
+    engine.attachMesh(mesh);
+    engine.buildAdjacency(graph.links);
+    engine.fire("n0", 0);
+    engine.tick(RippleEngine.RIPPLE_LIFE_MS + 50);
+    for (const value of mesh.userData.activationData) {
+      expect(value).toBe(0);
+    }
+    expect(engine.ripples.length).toBe(0);
+  });
+
+  it("notifies fire and reach observers", () => {
+    const graph = buildLineGraph(3);
+    const mesh = makeMesh(graph.edgeIndex, graph.edgeCount);
+    const engine = new RippleEngine();
+    engine.attachMesh(mesh);
+    engine.buildAdjacency(graph.links);
+    const fired = [];
+    const reached = [];
+    engine.on("fire", payload => fired.push(payload));
+    engine.on("reach", payload => reached.push(payload));
+    engine.fire("n0", 0);
+    engine.tick(120);
+    expect(fired.length).toBe(1);
+    expect(fired[0].sourceId).toBe("n0");
+    expect(reached.some(r => r.nodeId === "n1" && r.depth === 1)).toBe(true);
+  });
+
+  it("fireAmbient picks a random node and produces a ripple", () => {
+    const graph = buildLineGraph(5);
+    const mesh = makeMesh(graph.edgeIndex, graph.edgeCount);
+    const engine = new RippleEngine();
+    engine.attachMesh(mesh);
+    engine.buildAdjacency(graph.links);
+    const ripple = engine.fireAmbient(0);
+    expect(ripple).not.toBeNull();
+    expect(ripple.visitedNodes.size).toBeGreaterThan(0);
+  });
+});

desktop/cortex-control-center/src/brain/__tests__/easing.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { clamp01, easeOutCubic, expDecay, riseDecay } from "../easing.js";
+
+describe("easing helpers", () => {
+  it("clamp01 caps to [0,1]", () => {
+    expect(clamp01(-2)).toBe(0);
+    expect(clamp01(0.4)).toBe(0.4);
+    expect(clamp01(2)).toBe(1);
+  });
+
+  it("easeOutCubic boundaries and monotonic", () => {
+    expect(easeOutCubic(0)).toBe(0);
+    expect(easeOutCubic(1)).toBe(1);
+    let prev = -Infinity;
+    for (let i = 0; i <= 20; i += 1) {
+      const v = easeOutCubic(i / 20);
+      expect(v).toBeGreaterThanOrEqual(prev);
+      prev = v;
+    }
+  });
+
+  it("expDecay matches exp(-t/tau) at canonical points", () => {
+    const tau = 280;
+    expect(Math.abs(expDecay(0, tau) - 1)).toBeLessThan(1e-6);
+    expect(Math.abs(expDecay(tau * Math.LN2, tau) - 0.5)).toBeLessThan(1e-3);
+    expect(Math.abs(expDecay(tau * Math.log(6), tau) - 1 / 6)).toBeLessThan(0.01);
+  });
+
+  it("riseDecay rises within riseMs then decays exp afterwards", () => {
+    const value0 = riseDecay(0, 80, 280);
+    const valueRise = riseDecay(80, 80, 280);
+    const valueAfter = riseDecay(80 + 280 * Math.LN2, 80, 280);
+    expect(value0).toBe(0);
+    expect(valueRise).toBeCloseTo(1, 5);
+    expect(Math.abs(valueAfter - 0.5)).toBeLessThan(1e-2);
+  });
+});