fix(brainbar): energy-threshold early-exit in KG force-sim + onAppear timerActive reset (#249)

Root cause of 3 user 'BrainBar stuck' complaints — KGCanvasView.startSimulation pegs CPU at 96.8% because tick() runs a 30fps O(n²) loop with no early-exit and .onAppear doesn't reset timerActive after disappear.

Fix:

- Energy-threshold early-exit in the force sim — stop timer when KE < 0.01.

- Reset timerActive semantics through a restart-safe simulation controller.

- Double-start guard for repeated appearances.

Tests: stable-graph converges <2s; re-appear triggers restart.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: EtanHey

brain-bar/Sources/BrainBar/KnowledgeGraph/KGCanvasView.swift

@@ -8,7 +8,7 @@ struct KGCanvasView: View {
     @State private var scale: CGFloat = 1.0
     @State private var lastScale: CGFloat = 1.0
     @State private var draggedNodeId: String?
-    @State private var timerActive = true
+    @State private var simulation = KGSimulationController()
     @State private var canvasSize: CGSize = .zero
 
     var body: some View {
@@ -30,7 +30,7 @@ struct KGCanvasView: View {
             viewModel.loadGraph()
             startSimulation()
         }
-        .onDisappear { timerActive = false }
+        .onDisappear { simulation.stop() }
     }
 
     private var graphCanvas: some View {
@@ -136,12 +136,8 @@ struct KGCanvasView: View {
     // MARK: - Simulation timer
 
     private func startSimulation() {
-        Task { @MainActor in
-            while timerActive {
-                try? await Task.sleep(for: .milliseconds(33)) // ~30fps
-                viewModel.tick()
-            }
-        }
+        guard !simulation.timerActive else { return }
+        simulation.start { viewModel.tick() }
     }
 
     // MARK: - Stats overlay

brain-bar/Sources/BrainBar/KnowledgeGraph/KGSimulationController.swift

@@ -0,0 +1,58 @@
+import Foundation
+
+@MainActor
+final class KGSimulationController {
+    typealias TickHandler = @MainActor () -> CGFloat
+    typealias SleepHandler = @Sendable (Duration) async -> Void
+
+    static let defaultFrameDuration: Duration = .milliseconds(33)
+    static let defaultEnergyThreshold: CGFloat = 0.01
+
+    private(set) var timerActive = false
+
+    private let frameDuration: Duration
+    private let energyThreshold: CGFloat
+    private let sleep: SleepHandler
+    private var simulationTask: Task<Void, Never>?
+
+    init(
+        frameDuration: Duration = KGSimulationController.defaultFrameDuration,
+        energyThreshold: CGFloat = KGSimulationController.defaultEnergyThreshold,
+        sleep: @escaping SleepHandler = { duration in
+            try? await Task.sleep(for: duration)
+        }
+    ) {
+        self.frameDuration = frameDuration
+        self.energyThreshold = energyThreshold
+        self.sleep = sleep
+    }
+
+    func start(tick: @escaping TickHandler) {
+        guard !timerActive else { return }
+
+        timerActive = true
+        simulationTask = Task { @MainActor [weak self] in
+            guard let self else { return }
+            defer { self.simulationTask = nil }
+
+            while self.timerActive && !Task.isCancelled {
+                await self.sleep(self.frameDuration)
+                guard self.timerActive && !Task.isCancelled else { break }
+
+                if tick() < self.energyThreshold {
+                    self.timerActive = false
+                }
+            }
+        }
+    }
+
+    func stop() {
+        timerActive = false
+        simulationTask?.cancel()
+        simulationTask = nil
+    }
+
+    deinit {
+        simulationTask?.cancel()
+    }
+}

brain-bar/Sources/BrainBar/KnowledgeGraph/KGViewModel.swift

@@ -96,8 +96,8 @@ final class KGViewModel: ObservableObject {
 
     // MARK: - Force-Directed Layout
 
-    func tick() {
-        guard nodes.count > 1 else { return }
+    func tick() -> CGFloat {
+        guard nodes.count > 1 else { return 0 }
 
         var forces = Array(repeating: CGVector.zero, count: nodes.count)
         let center = canvasCenter
@@ -142,12 +142,18 @@ final class KGViewModel: ObservableObject {
         }
 
         // Apply forces with damping
+        var totalKineticEnergy: CGFloat = 0
         for i in 0..<nodes.count {
             nodes[i].velocity.dx = (nodes[i].velocity.dx + forces[i].dx) * damping
             nodes[i].velocity.dy = (nodes[i].velocity.dy + forces[i].dy) * damping
             nodes[i].position.x += nodes[i].velocity.dx
             nodes[i].position.y += nodes[i].velocity.dy
+
+            let speedSq = (nodes[i].velocity.dx * nodes[i].velocity.dx) + (nodes[i].velocity.dy * nodes[i].velocity.dy)
+            totalKineticEnergy += 0.5 * speedSq
         }
+
+        return totalKineticEnergy
     }
 
     // MARK: - Helpers

brain-bar/Tests/BrainBarTests/KnowledgeGraphTests.swift

@@ -315,3 +315,115 @@ final class KGViewModelTests: XCTestCase {
         XCTAssertTrue(vm.selectedEntityChunks.first?.snippet.contains("Alice") ?? false)
     }
 }
+
+@MainActor
+final class KGCanvasSimulationTests: XCTestCase {
+    var db: BrainDatabase!
+    var tempDBPath: String!
+
+    override func setUp() {
+        super.setUp()
+        tempDBPath = NSTemporaryDirectory() + "brainbar-kgcanvas-test-\(UUID().uuidString).db"
+        db = BrainDatabase(path: tempDBPath)
+    }
+
+    override func tearDown() {
+        db.close()
+        try? FileManager.default.removeItem(atPath: tempDBPath)
+        try? FileManager.default.removeItem(atPath: tempDBPath + "-wal")
+        try? FileManager.default.removeItem(atPath: tempDBPath + "-shm")
+        super.tearDown()
+    }
+
+    func testStableGraphStopsWithinTwoSecondsWorthOfFrames() async {
+        let vm = KGViewModel(database: db)
+        vm.canvasCenter = CGPoint(x: 300, y: 250)
+        vm.nodes = makeStableFixture(center: vm.canvasCenter)
+        vm.edges = []
+
+        let controller = KGSimulationController(
+            frameDuration: .milliseconds(33),
+            sleep: { _ in await Task.yield() }
+        )
+
+        var tickCount = 0
+        controller.start {
+            tickCount += 1
+            return vm.tick()
+        }
+
+        await waitForSimulationToStop(controller)
+
+        XCTAssertFalse(controller.timerActive, "Stable graph should auto-stop once kinetic energy is low")
+        XCTAssertLessThanOrEqual(
+            tickCount,
+            60,
+            "Stopping within 60 frames matches ~2s on the real 30fps timer"
+        )
+    }
+
+    func testRestartAfterIdleStartsSimulationAgain() async {
+        let controller = KGSimulationController(
+            frameDuration: .milliseconds(33),
+            sleep: { _ in await Task.yield() }
+        )
+
+        var tickCount = 0
+        let tick: @MainActor () -> CGFloat = {
+            tickCount += 1
+            return 0
+        }
+
+        controller.start(tick: tick)
+        await waitForSimulationToStop(controller)
+
+        XCTAssertFalse(controller.timerActive, "Controller should go idle after crossing the energy threshold")
+
+        controller.start(tick: tick)
+        await waitForSimulationToStop(controller)
+
+        XCTAssertEqual(tickCount, 2, "A previously idle simulation should restart on the next appearance")
+    }
+
+    private func waitForSimulationToStop(_ controller: KGSimulationController, iterations: Int = 200) async {
+        for _ in 0..<iterations where controller.timerActive {
+            await Task.yield()
+        }
+    }
+
+    private func makeStableFixture(center: CGPoint) -> [KGNode] {
+        let radius: CGFloat = 66.0
+        return [
+            KGNode(
+                id: "a",
+                name: "Alice",
+                entityType: "person",
+                importance: 5,
+                position: CGPoint(x: center.x + radius, y: center.y),
+                velocity: .zero
+            ),
+            KGNode(
+                id: "b",
+                name: "BrainLayer",
+                entityType: "project",
+                importance: 5,
+                position: CGPoint(
+                    x: center.x - radius / 2,
+                    y: center.y + (sqrt(3) * radius / 2)
+                ),
+                velocity: .zero
+            ),
+            KGNode(
+                id: "c",
+                name: "Codex",
+                entityType: "agent",
+                importance: 5,
+                position: CGPoint(
+                    x: center.x - radius / 2,
+                    y: center.y - (sqrt(3) * radius / 2)
+                ),
+                velocity: .zero
+            ),
+        ]
+    }
+}