seriesoftubes/CLAUDE.md
Frederic Jung c76dd4d556
Benchmark in real Chromium too, and only call a row slower when the samples say so
npm run perf -- --browser times the same workloads in Chromium as a desktop
and as a phone (390x844 at 3x, CPU slowed 4x), one browser per version. Each
run collects garbage first and ends by forcing layout and the map canvas, so
deferred work counts. The jsdom DOM is about 30x slower than a browser's and
has no layout, so the interface rows need this.

Shared machines swing single runs by 30% on identical code, CPU time
included. A row now counts as slower or faster only when it moved 15% and a
Mann-Whitney U test gives p < 0.01 (15 runs a side by default). Identical
code: no flags in three full runs; a routing slowdown planted in a copy is
flagged in jsdom and on the phone.

The panel workload renders both selections every run instead of alternating,
which split its samples in two. CI drives the runner's Chrome through
playwright-core, no browser download.
2026-10-26 12:04:57 +01:00

76 lines
4.4 KiB
Markdown

# Series of Tubes: notes for Claude
A free cartoon browser game about how the internet works, live at
https://seriesoftub.es. The whole game is one static page: `site/index.html`
(HTML, CSS and JS in one file, no framework, no build step for development).
Read these before larger changes:
- `docs/ARCHITECTURE.md`: how the code is laid out and how a day of simulation runs.
- `.claude/skills/`: step-by-step procedures (release, translations, tests).
## Commands
```bash
npm ci # once: installs jsdom for the tests
npm test # node:test + jsdom, all suites, must stay green
node scripts/i18n-check.js # must report "0 missing, 0 unused, 0 broken"
npm run build # builds _site/ (stamps version, bakes release notes)
npm run serve # build and serve locally
npm run perf -- --base /tmp/base.html # big-network benchmark vs another version (see `performance`)
npm run perf -- --base /tmp/base.html --browser # the same, also in real Chromium (desktop and phone)
```
To play during development, open `site/index.html` directly or run `npm run serve`.
## Hard rules
- **Git:** work on `main`, no branches. Commits are authored and committed as
`Frederic Jung <frederic@jc-ix.net>`. Never add `Co-Authored-By`, `Claude-Session`
or any other attribution trailers.
- **Releases only when Frederic says so.** Never bump the version on your own: push finished
work with its CHANGELOG bullets under `## [Unreleased]` and say it is ready. When he asks
for a release, follow the `release` skill: small fixes get a patch (`x.y.Z`), features a
minor, at most one release per hour. Docs, skills, CI, tests and refactors never need one.
- **Release notes in the app are short**: only the first sentence of each CHANGELOG bullet
(and at most five bullets) shows in "What's new", with a link to the full GitHub
release. Write that first sentence so it stands on its own.
- **Names are puns.** No real company names for networks, vendors, cables, banks,
data centers or exchanges (Cogentle, Goggle, NetChill, Junipurr, Arrrhipster…).
Real conference names (NANOG, RIPE, DENOG) are fine. Avoid lazy "-ish" names: find
a real pun, or keep the plain word.
- **Easter eggs stay secret.** Never mention hidden jokes or easter eggs (for example
whatever `elephant()` does) in commit messages, release notes or the CHANGELOG.
- **Every player-facing string is translated.** Wrap it in `tr()`, `trn()` or `N_()`
and add the Italian to `site/i18n/it.js` in the same change (see `add-strings`).
- **Phones first.** About 70% of players are on phones. Every new panel, button and
modal must work at 360 px wide, in portrait and landscape, using the phone tab bar
and bottom sheets. Check `isPhone()` layouts, not just desktop.
- **Saves are sacred.** Old saves must keep loading. Any new state field gets a default
in `newGame()` and a check/repair in `sanitize()`; renamed fields are migrated there.
- **Performance is always demonstrated.** Every change to `site/` is measured on the big-network
fixture against `main` (`npm run perf -- --base /tmp/base.html`, see the `performance` skill),
and the numbers go into the PR and into your summary. Every PR also gets them as a comment from
CI. Anything slower needs a reason or a fix.
- **Tests come with features.** Add or extend a test in `tests/` for every feature or
fix. Tests are seeded, so they must not depend on luck.
- **CHANGELOG style:** plain English, written for players, one bullet per change,
issue numbers in parentheses like `(#37)`. No internal names, no jokes explained.
## Style of the code
- Dense, single-file JavaScript. Match the surrounding style: short helper names,
arrow functions, template-literal HTML, no new dependencies.
- UI is rebuilt from state: change `S`, then call `after()` (recompute, check goals,
re-render, save). Buttons are `btn(label, actName, args, cls, disabled)`, which
dispatch to `ACT[actName](args)` through `data-act`/`data-args`.
- Never trust saved or imported state: anything read from `S` that came from a save
must already have been validated in `sanitize()`.
- Keep comments short and about *why*.
## Tone
Friendly, nerdy and accurate underneath the jokes. Mechanics should follow how
networks really work (95th-percentile billing, peering policies, LAGs, DWDM reach,
route leaks, RPKI) and then exaggerate for fun. When unsure how something works in
real life, look it up before modelling it.