4.1 KiB
4.1 KiB
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
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
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 asFrederic Jung <frederic@jc-ix.net>. Never addCo-Authored-By,Claude-Sessionor any other attribution trailers. - Releases happen by bumping
versioninpackage.jsononmain(see thereleaseskill). Small fixes or tweaks get a patch release (x.y.Z); new features a minor release. Not everything needs a release: docs, skills, CI, tests and refactors are just pushed, and small player-facing tweaks wait under## [Unreleased]for a real release. At most one release per hour: until the hour is up, push work with its CHANGELOG bullets under## [Unreleased]and batch it into the next release. Only a broken live game justifies an immediate hotfix. - 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()orN_()and add the Italian tosite/i18n/it.jsin the same change (seeadd-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 insanitize(); renamed fields are migrated there. - 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 callafter()(recompute, check goals, re-render, save). Buttons arebtn(label, actName, args, cls, disabled), which dispatch toACT[actName](args)throughdata-act/data-args. - Never trust saved or imported state: anything read from
Sthat came from a save must already have been validated insanitize(). - 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.