The MCP server gains a second session, --browser: the game in the player's tab, reached through the agent relay npm run dev hosts at /agent (loopback unless --host; Host and Origin checked, no token). The player turns it on in Settings → Agent API, a section only the development page has, and picks the clock: a pace of 30 s to 5 min a day that nobody can pause, or the agent's own. Headless gets the running clock too (--clock realtime --pace MS) and both get a wait tool. All of it lives in src/agent/ (development page only). The game offers HOOKS, UI.clockLocked, setSpeed() and runClock(dt), the frame's day block moved out unchanged, and nothing more: the page players get grows by under 1 KB gzipped and runs exactly as before.
6.9 KiB
Series of Tubes: notes for Claude
A free cartoon browser game about how the internet works, live at
https://seriesoftub.es, hosted on GitHub Pages. The game is one static page with no framework.
Its source is many small files in src/ (src/styles/*.css, src/game/**/*.js, the shell
src/index.html); the build pastes them together, in path order, into a single index.html, the
same one-file page players have always loaded. Static files (dictionaries, icons, service worker)
live in site/. src/agent/ (the facade the MCP server plays through) goes into the development page only,
never into the page players get, and nothing in src/game/ may use it (docs/adr/0004-dev-only-code.md).
Read these before larger changes:
docs/ARCHITECTURE.md: where the code is, and how a day of simulation runs.docs/adr/: decisions that are settled (GitHub Pages only; one page assembled at build)..claude/skills/: step-by-step procedures (edit-the-game,github-pages, release, translations, tests, performance)..claude/skills/gameplay-rules/: the game's design rules (W1, N3, F2…), each enforced bytests/gameplay-rules.test.js; run it before changing cities, networks, cables, modes or balance.
Commands
npm ci # once: installs jsdom for the tests
npm run dev # play while developing: http://localhost:8080, reloads on save (--host to share)
npm test # node:test + jsdom, every tests/*.test.js, must stay green
node scripts/i18n-check.js # must report "0 missing, 0 unused, 0 broken" (and sorted dictionaries)
node scripts/i18n-add.js FILE.json # add/change/remove translations (see `add-strings`)
npm run build # builds _site/ for GitHub Pages (assembles src/, stamps version, bakes release notes)
npm run serve # build and serve the production site locally
npm run perf -- --base-ref origin/main # big-network benchmark vs main (see `performance`)
npm run perf -- --base-ref origin/main --browser # the same, also in real Chromium (desktop and phone)
npm run mcp # the game as a local MCP server for AI clients, stdio or --http (docs/MCP.md)
Hard rules
- GitHub Pages, always. The game is hosted on GitHub Pages and nowhere else. This is not up
for discussion: never propose or prepare another host, a CDN in front, a backend, server-side
rendering, redirects or custom headers. The build output stays plain static files from one
origin. If a feature seems to need a server, redesign the feature. See the
github-pagesskill anddocs/adr/0001-github-pages-only.md. - No runtime cost for structure. The page ships as one assembled
index.html. Organise code into files undersrc/freely (build time is cheap), but never in a way that adds requests or work to page load or to the game loop. - 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 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 thereleaseskill: 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, by label. Code uses
tr('area.label'),trn('area.label', n)orN_('area.label')(anything stored in a save:N_()), never English text. Add the English (src/i18n/en.js) and every translation (site/i18n/*.js) in the same change withscripts/i18n-add.js(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. - Performance is always demonstrated. Every change to
src/orsite/is measured on the big-network fixture againstmain(npm run perf -- --base-ref origin/main, see theperformanceskill), 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 (a new feature gets its owntests/<feature>.test.js). 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. The CHANGELOG is the one file every change touches; conflicts there are expected (keep both bullets).
Style of the code
- Dense JavaScript in small topic files under
src/game/(seeedit-the-game): a new feature gets its ownNN-name.jsin the folder of its topic, actions go in the matchingsrc/game/90-actions/*.js. All files share one top-level scope; top-level values may only use top-level values from earlier files. Match the surrounding style: short helper names, arrow functions, template-literal HTML, no new dependencies. - Lists people add to (cities, cables, networks, dictionaries) are one entry per line; id-keyed objects and dictionaries stay sorted, so additions do not collide.
- 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.