feat: electric mode — spreading activation visualization

[nvandessel]

Summary

• Adds electric mode to the interactive graph view (floop graph --format html --serve): clicking a node runs the real Go spreading activation engine server-side and animates the results in the browser with flowing particles, node glow, and step-by-step playback controls
• New Engine.ActivateWithSteps() method captures per-step activation snapshots for animation timeline (initial seed → propagation steps → post-inhibition/sigmoid final)
• Lightweight HTTP server (visualization.Server) serves the graph HTML and handles /api/activate?seed=<id> requests — zero JS algorithm duplication, no risk of divergence from the Go engine

Architecture

Browser (JS)                    Go Server (localhost)
─────────────                   ────────────────────
Click node "b42"  ──GET────>   /api/activate?seed=b42
                                  │
                                  ├─ Engine.ActivateWithSteps(seed)
                                  │    └─ returns per-step snapshots
                                  │
                  <──JSON────   [{step:0, activation:{...}}, ...]
Animate particles,
glow, playback controls

Changes

File	What
internal/spreading/engine.go	ActivateWithSteps(), extracted propagateStep()/postProcess() shared methods
internal/spreading/engine_test.go	4 new tests for step snapshots
internal/visualization/server.go	New: HTTP server with cached HTML + /api/activate endpoint
internal/visualization/server_test.go	New: 5 server endpoint tests
internal/visualization/dot.go	RenderHTMLForServer(), APIBaseURL in template data
internal/visualization/dot_test.go	Tests for electric mode markers in HTML
internal/visualization/templates/graph.html.tmpl	Electric mode CSS + JS (~250 lines): particles, glow, playback toolbar
cmd/floop/cmd_graph.go	--serve flag, server lifecycle with graceful shutdown

Usage

# Static export (default, no electric mode)
floop graph --format html

# Server mode with electric activation
floop graph --format html --serve

Test plan

• go test ./internal/spreading/... — ActivateWithSteps tests pass
• go test ./internal/visualization/... — server + HTML marker tests pass
• go test ./... — all 29 packages pass, no regressions
• Manual: floop graph --format html --serve → click node → particles flow, toolbar works
• Manual: floop graph --format html → static file export still works (no server)
• Manual: Ctrl-C cleanly shuts down server

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR adds electric mode visualization to the graph view, allowing users to click nodes and watch spreading activation propagate in real-time with animated particles and glow effects. The implementation is well-architected: the Go engine was cleanly refactored to expose step-by-step activation snapshots via ActivateWithSteps(), a lightweight HTTP server handles activation requests, and the browser animates the results without duplicating any algorithm logic.

Key changes:

• Core engine refactored to share propagation logic between Activate() and new ActivateWithSteps() method
• New HTTP server with graceful shutdown and cached HTML rendering
• Electric mode JavaScript adds particle system, glow animations, and playback controls (~250 lines)
• --serve flag enables server mode with electric activation
• Comprehensive test coverage for engine snapshots and server endpoints
• Playwright-based integration tests for browser animation

Minor issues already noted in previous review threads:

• Store errors masked as 404 in server.go:125
• --serve flag silently ignored for non-HTML formats
• No error handling on fetch() call in template

Confidence Score: 4/5

• Safe to merge with comprehensive tests, but three minor issues from previous review should be addressed for production readiness
• The core implementation is solid with excellent test coverage (29 packages passing, 4 new engine tests, 5 server tests, Playwright integration tests). The refactoring of propagation logic is clean and maintains backward compatibility. However, three issues already identified in previous threads should be addressed: error handling conflation (500 vs 404), silent flag validation, and missing fetch error handling. These don't affect correctness but impact debuggability and user experience.
• internal/visualization/server.go (error handling), cmd/floop/cmd_graph.go (flag validation), internal/visualization/templates/graph.html.tmpl (fetch error handling) — all have issues noted in previous review threads

Important Files Changed

Filename	Overview
internal/spreading/engine.go	Adds ActivateWithSteps() method and refactors core propagation logic into reusable propagateStep() and postProcess() helpers — clean extraction with proper synchronous updates
internal/spreading/engine_test.go	Adds 4 comprehensive tests for ActivateWithSteps() covering linear chains, snapshot independence, sigmoid application, and empty seeds edge case
internal/visualization/server.go	New HTTP server with cached HTML rendering and /api/activate endpoint — graceful shutdown implemented correctly, minor error handling issue noted in previous review
internal/visualization/server_test.go	Comprehensive test suite covering server startup, HTML serving, activation endpoint with valid/invalid seeds, and graceful shutdown
internal/visualization/dot.go	Adds RenderHTMLForServer() variant that embeds API base URL for electric mode — clean separation between static and server modes
internal/visualization/dot_test.go	Adds tests verifying electric mode markers appear in server HTML but not in static HTML exports
internal/visualization/templates/graph.html.tmpl	Adds ~250 lines of electric mode CSS and JavaScript including particle animation, glow effects, playback controls — no error handling on fetch call noted in previous review
cmd/floop/cmd_graph.go	Adds --serve flag with server lifecycle management and graceful shutdown — minor issue with flag validation for non-HTML formats noted in previous review

Sequence Diagram

sequenceDiagram
    participant Browser
    participant Server as Go HTTP Server
    participant Engine as Spreading Engine
    participant Store as Graph Store

    Browser->>Server: GET /
    Server->>Store: GetNodes(), GetEdges()
    Store-->>Server: Graph data
    Server->>Server: RenderHTMLForServer(apiBaseURL)
    Server-->>Browser: HTML + embedded graph JSON

    Note over Browser: User clicks node "b42"

    Browser->>Server: GET /api/activate?seed=b42
    Server->>Store: GetNode(b42)
    Store-->>Server: Node exists
    Server->>Engine: ActivateWithSteps([{b42, 1.0}])
    
    Engine->>Engine: Step 0: Initialize seed
    loop For each propagation step
        Engine->>Store: GetEdges(active nodes)
        Store-->>Engine: Edge list
        Engine->>Engine: propagateStep()
        Engine->>Engine: Capture snapshot
    end
    
    Engine->>Engine: postProcess() - inhibition + sigmoid
    Engine-->>Server: []StepSnapshot (JSON)
    Server-->>Browser: Step-by-step activation data

    Note over Browser: Animate particles, glow, playback controls

Loading

_{Last reviewed commit: 7e18797}

[greptile-apps]

_{8 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[nvandessel]

New commit: reduce spark size and improve edge visibility

Smaller sparks:

• Base radius: 6 + sparkBright * 6 → 3 + sparkBright * 3 (halved)
• Halo multiplier: 2.5x → 1.8x, core: 1.8x → 1.2x
• Halo opacity reduced for subtler bloom

Better edge visibility:

• Fallback opacity: 0.10 → 0.18
• Energy decay floor: 0 → 0.06 (edges never fully vanish)
• Residual glow factor: 0.15 → 0.25

All 18 visual tests pass. Ready for visual review — run floop graph --format html --serve to check live.

[greptile-apps]

_{18 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}