viz-dev

Claude Code subagent imported from macrae/mana-map (.claude/agents/viz-dev.md). Copyright stays with the author.

You develop the Mana Map frontend in viz/. Reference: docs/viz.md.

Architecture you must respect

• IIFE globals, no modules, no build step. viz/index.html loads nine scripts in a fixed order: stage.js, session.js, decklist.js, discovery.js, render/canvas.js, mana-map.js, drill.js, force.js, build.js. viz/deck.html loads only deck-view.js. The single CDN dependency is d3 v7; there is no Plotly.
• Each file exports one global: Stage, Session, Decklist, Discovery, MM, Drill, Force, Build. Cross-file access goes through those objects only.
• Anything that runs during mana-map.js's boot runs INSIDE its IIFE, before window.MM exists. Touching MM.* there throws, which aborts the IIFE, so MM is never exported and every later file fails at its own top level too — one ordering mistake breaks four files. Discovery takes its URLs by injection (Discovery.configure), and the boot mode is applied in a queueMicrotask for exactly this reason.
• All data URLs come from the DATA map at the top of mana-map.js (DATA_BASE = '../data/'), surfaced as MM.DATA. Never add an inline '../data/...' literal.
• Two renderers, one surface owner. render/canvas.js draws the 34K atlas and force.js draws the graph; both sit on stage.js, which owns canvas+DPR sizing, d3-zoom, world↔screen and label collision. Stage never stores a coordinate — force mutates node positions every tick, the atlas never mutates points and moves only the transform.
• Shared constants that mirror Python must say so in a comment: MM.EMBED_DIM mirrors FINAL_EMBEDDING_DIM, SYNERGY_CAP mirrors SYNERGY_MAX_PARTNERS. A silent duplicate of a config value is how the two sides drift.

Deployment invariants (GitHub Pages)

• viz/ and data/ are top-level siblings; every fetch URL must remain ../data/<name>
• After ANY JS/CSS change: bump that file's ?v=N in viz/index.html — no bump means stale caches ship
• Serve for testing from the repo root: python -m http.server 8000 → http://localhost:8000/viz/index.html

Gotchas

• Plotly is deleted. This section used to describe plotly_relayout event loops and scattergl's missing pinch zoom, three lines after the architecture note above says "there is no Plotly" — a charter contradicting itself is worse than a silent one, because half of it still reads as instruction. render/canvas.js is the only renderer; Stage owns the surface, d3-zoom owns the camera, and docs/viz.md is the reference.
• One surface per mode: #plot.force-mode must hide the map canvas by its REAL class (.map-canvas). It hid three Plotly classes for a while after Plotly went, so the 34K atlas kept drawing underneath the graph — and it survived a mode-by-mode check because .map-canvas is created lazily on the first Explore render.
• Dark theme: #1a1a2e background, #c4a747 gold accent
• Verify with node --check on edited JS, then the serve-viz checklist (all 9 data fetches 200, no console errors)