# Overnight build — notes & questions for Jason

> **For the current state of the work, see [`HANDOVER.md`](HANDOVER.md).** This
> file is the historical overnight-build log; its open questions (§"Questions I'd
> value your advice on") are still unanswered, but later sessions' work is
> recorded in the handover.

A running log of decisions I took autonomously and the few things I'd value your
steer on. **None of these are blocking** — I've chosen sensible defaults and kept
going. Read this first when you wake.

## Morning summary — what got built overnight

Everything in the plan, plus your heat-map request, all tested and verified:

- The full **unified library** (engine + numerics + geometry + 2-D & 3-D
  renderers) covering all five shapes, bundled to one file `dist/dynamo.js`.
- **Speed heat maps** (your request): a background speed field *and* speed-coloured
  flow, in both 2-D and 3-D, with a legend and explorer toggles.
- **N-D rest points & stability** — the cube, tetrahedron and prism now find and
  classify rest points too (tetrahedron coordination shows the exact 4 sinks / 10
  saddles / 1 source).
- **Basins of attraction** — coloured basin maps (an explorer toggle).
- **Maximum Lyapunov exponent** + speed contour fields.
- Interactive **`showcase.html`** (explorer + gallery across all five shapes,
  self-contained — just open it) and **`docs/index.html`** (~2,400 lines: guides,
  the mathematics of every dynamic, a full API reference).
- **13 test suites, all passing**; 402 render variants verified clean.
- README, CONVENTIONS.md, this file, a 3S-verification writeup, and a placeholder
  LICENSE (awaiting your choice — see below).

The only planned thing I deliberately did **not** build is the per-dynamic
`StableGameLyapunov` contour functions; the speed heat map covers the common case,
and I'd rather add the dynamic-specific Lyapunov functions on your say-so. I have
**not** committed anything to git (left that for you).

## Where things stand

The unified library `dynamo-js/` covers **all five** Dynamo notebooks through one
engine (the maths) plus per-geometry renderers (the pictures):

| Notebook | dims | shape | status |
|---|---|---|---|
| 2x2 | [2,2] | square | ✅ engine + 2D portrait + rest points/stability |
| 3S | [3] | triangle | ✅ engine + 2D portrait + rest points/stability |
| 4S | [4] | tetrahedron | ✅ engine + 3D portrait (rest points: see TODO) |
| 3x2 | [3,2] | prism | ✅ engine + 3D portrait |
| 2x2x2 | [2,2,2] | cube | ✅ engine + 3D portrait |

All 14 dynamics, the integrator, rest points + stability (2-D so far), the
seeded PRNG, the geometry layer, both renderers, a single bundle (`dist/dynamo.js`),
and a self-contained interactive `showcase.html`. 138 engine tests pass; 135/135
shape×game×dynamic render combinations are clean.

## Questions I'd value your advice on

1. **Licence.** The notebooks credit *Sandholm, Dokumacı & Franchetti* (Univ.
   Wisconsin–Madison) and NSF grants, but carry **no explicit licence text**. I have
   **not** invented one. The README credits them and frames this as an in-memoriam
   port; `LICENSE` is a placeholder. Please tell me which licence to apply — the
   original was distributed freely from Sandholm's site, so an attribution-preserving
   permissive licence (MIT-with-attribution, or CC-BY) would fit.
   **Resolved 2026-07-08:** Jason chose **GPL-3.0-or-later** — the original's
   site described Dynamo as free, open-source software with a pointed link to
   gnu.org, and the GPL honours that intent. `LICENSE` now carries the full
   GPLv3 text; `package.json` and the README record the grant and attribution.

2. **Cube/prism preset games.** I transcribed the 3S triangle presets *exactly* from
   the notebook (Rock-Paper-Scissors, Good/Bad RPS, Coordination, Zeeman, Young) and
   the 3×2 "coordination with outside option". The **cube** presets (three-way
   coordination / anti-coordination) are illustrative ones I designed, since the
   2×2×2 notebook's example payoffs are a trilinear tensor I didn't fully transcribe.
   Say the word and I'll pull the notebook's exact cube examples.

3. **Congestion & quadratic games.** The notebooks also support congestion games
   (all editions) and quadratic games (4S). I've done normal-form (every shape), the
   trilinear cube, and a general `Game.nonlinear` hook, but haven't wired congestion
   or quadratic as first-class constructors. Want them?

4. **The 3S "sphere" view.** The 3S notebook offers an alternative *spherical* (Akin)
   projection of the simplex. I've built the standard triangle; the sphere is a nice
   optional extra — shall I add it?

5. **Docs format.** I'm writing extensive HTML documentation. Default plan: one large,
   well-sectioned page plus the live showcase. Tell me if you'd prefer a multi-page site.

## Decisions taken (with rationale)

- **One unified library, not five ports.** Your "single bundled module, clean
  interface" requirement plus the fact that the notebooks differ *only* in geometry
  made this the right call. The maths is written and verified once.
- **Renamed `dynamo-2x2/` → `dynamo-js/`** (my own WIP scaffold) to house the unified
  library. The prior 3S files (`evolutionary-dynamics.js`, `simplex-plot.js`) are
  untouched, per your conservative-file-ops preference.
- **Heat maps of trajectory speed** (your request): implemented two complementary
  forms — a background speed-field heat map, and trajectories tinted by local speed.
- **3-D portraits are SVG** (projected, rotatable) rather than canvas, so they're
  testable in Node and export identically to the 2-D ones.
- **Bundler is hand-rolled** (zero dependencies) — wraps each module in its own scope.

## 3S prior-port verdict (you asked me to check)

The prior `evolutionary-dynamics.js`/`simplex-plot.js` implement ~9 of the dynamics
with formulae that **match the notebook exactly**, and correct barycentric geometry —
but they **omit** SampleBR, SelMut, ExcessPayoff and Combined as registered dynamics,
**all** the Lyapunov/contour functions, a trajectory integrator, and a seeded PRNG
(they use `Math.random()`). The unified library supplies every one of those, so it
supersedes them cleanly. I have **not** deleted the originals.

## Known limitations / TODO (being worked through overnight)

- Rest-point dots + stability currently render for the 2-D shapes (square, triangle).
  Generalising to 3-D (cube/tetra/prism) is in progress (needs N-D root-finding +
  3×3 eigenvalues).
- Basins of attraction, Lyapunov exponents, and the StableGameLyapunov contour
  functions: in progress.
- `sampleBR` is currently 2-strategy only (binomial); multinomial generalisation pending.
- Comprehensive HTML docs: in progress.