diff --git a/.claude/skills/add-strings/SKILL.md b/.claude/skills/add-strings/SKILL.md new file mode 100644 index 0000000..52fb997 --- /dev/null +++ b/.claude/skills/add-strings/SKILL.md @@ -0,0 +1,53 @@ +--- +name: add-strings +description: Add or change player-facing text in Series of Tubes and keep every translation (site/i18n/*.js) complete. +--- + +# Adding or changing player-facing text + +The English text is the translation key. Every string a player can see must go +through the translation helpers and have an entry in every dictionary in `site/i18n/` +(currently `it.js`, Italian). + +## In the code + +- `tr('Text with {name}', {name})`: translate now and fill placeholders. +- `trn('{n} router', '{n} routers', n, vars)`: plurals; both forms are keys. +- `N_('Text')`: marks a literal kept in a table for later `tr()` (e.g. labels stored in + constants). Call `tr(x)` where it's shown. +- Static HTML: add `data-i18n` to the element; `aria-label` and `title` attributes are + collected automatically. +- Text must be a string literal inside the call, or the checker can't see it. +- Keep HTML (``, `
`, ``) and `{placeholders}` identical in translations. +- Don't build sentences by concatenating translated fragments; translate whole sentences. + +## In the dictionary + +`site/i18n/it.js` is one object, `"English": "Italiano",` per line, ending with `};`. +Append new entries before the closing `};`. A small script avoids quoting mistakes: + +```python +import json +it = {"New English text": "Nuovo testo italiano"} +q = 'site/i18n/it.js'; t = open(q).read().rstrip() +assert t.endswith('};') +t = t[:-2] + ''.join(json.dumps(k, ensure_ascii=False) + ':' + json.dumps(v, ensure_ascii=False) + ',\n' + for k, v in it.items() if json.dumps(k, ensure_ascii=False) + ':' not in t) + '};\n' +open(q, 'w').write(t) +``` + +When you **change** English text, rename the key in every dictionary too; when you +remove text, delete its entry. + +## Italian style + +Natural, friendly Italian, informal "tu". Keep networking terms that Italian engineers +use in English (peering, transit, router, POP, PNI, LAG, dark fiber). Translate puns +into an Italian joke when one fits; otherwise keep the pun name and translate the rest. + +## Check + +```bash +node scripts/i18n-check.js # must say: 0 missing, 0 unused, 0 broken +npm test # includes tests/i18n.test.js +``` diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md new file mode 100644 index 0000000..fb36044 --- /dev/null +++ b/.claude/skills/release/SKILL.md @@ -0,0 +1,55 @@ +--- +name: release +description: Cut and ship a Series of Tubes release (patch or minor) from main via the auto-release workflow. +--- + +# Releasing Series of Tubes + +Bumping `version` in `package.json` on `main` is the release button. The +`auto-release.yml` workflow tests, tags `v`, publishes a GitHub release with +that version's CHANGELOG section as notes, and dispatches `release.yml`, which deploys +to GitHub Pages (https://seriesoftub.es). + +## Pick the version + +- Patch (`x.y.Z`): fixes, small tweaks, wording, icons. +- Minor (`x.Y.0`): new features or content. + +## Steps + +1. Make sure `main` is green: `npm test` and `node scripts/i18n-check.js` + ("0 missing, 0 unused, 0 broken"). +2. In `CHANGELOG.md`, move the bullets from `## [Unreleased]` into a new section + right below it: `## [x.y.z] — YYYY-MM-DD` (em dash, today's date). Keep an empty + `## [Unreleased]` heading above it. The build fails if the section has no bullets. +3. Bump the version in **both** files: + - `package.json` → `"version"` + - `package-lock.json` → top-level `"version"` and `packages[""].version` +4. `npm test` once more. +5. Commit on `main` as Frederic, with no attribution trailers: + ```bash + git -c user.name="Frederic Jung" -c user.email="frederic@jc-ix.net" commit \ + --author="Frederic Jung " -m "Short summary (x.y.z)" + git push origin main + ``` +6. Watch the workflows until both finish: + ```bash + gh run list --repo fjaeckel/seriesoftubes --limit 4 + gh run watch --repo fjaeckel/seriesoftubes + ``` +7. Confirm it is live: `https://seriesoftub.es/version.json` shows the new version. + +## Release notes rules + +- Written for players, in plain English. One bullet per change, issue numbers like `(#37)`. +- Never mention hidden easter eggs or explain jokes. +- No internal function names. + +## If something fails + +- "not newer than the latest release": the version was not bumped, or was bumped + backwards. +- "CHANGELOG.md has no notes under ## [x.y.z]": the heading doesn't match the version + exactly or has no bullets. +- Tests fail in the workflow but pass locally: look for unseeded randomness in a test. +- Fix forward with a new patch version; never move or delete an existing tag. diff --git a/.claude/skills/write-tests/SKILL.md b/.claude/skills/write-tests/SKILL.md new file mode 100644 index 0000000..4f0ce7c --- /dev/null +++ b/.claude/skills/write-tests/SKILL.md @@ -0,0 +1,49 @@ +--- +name: write-tests +description: Write deterministic jsdom tests for Series of Tubes features and fixes in tests/*.test.js. +--- + +# Writing tests + +Tests use `node:test` and `tests/harness.js`, which loads `site/index.html` in jsdom +with the animation loop off, a seeded `Math.random` and a recording fake canvas. +Code runs inside the page through `ev()`. + +## Pattern + +```js +const test = require('node:test'); +const assert = require('node:assert/strict'); +const { load } = require('./harness'); + +test('what the player should see happen', () => { + const { ev, errors } = load(); + ev("ACT.start({});S.cash=1e8;for(const g of GOALS)S.done[g.id]=0;ACT.launchBB({city:'fra'})"); + ev("ACT.buyTransit({city:'fra',net:'cog',tier:1});compute()"); + assert.ok(ev("R.served") > 0); + assert.deepEqual(errors, []); // always: no page errors +}); +``` + +## Where to put it + +Pick the suite by topic: `game` (core loop), `build`, `persist` (save/import/migrate), +`services` (customers), `peering`, `issues` (GitHub issue regressions, name them +`#NN …`), `regions`, `modes` (scenarios, sandbox, weekly), `i18n`. A new file must be +added to the `test` script in `package.json`. + +## Rules + +- **Deterministic.** Never rely on luck. Use the default seed, `window.__reseed(n)`, + or set state directly (`S.day=…`, `S.ev.x=…`). +- **Force a specific random failure or event** by patching the picker: + ```js + ev("eval('('+fireFailure.toString().replace('const e=pick(opts);',\"const e='crash';\")+')')()"); + ``` + Check the current source for the exact `pick` line first; it may differ. +- **Drive the game through `ACT`** like a player would, then `compute()` or `dayTick()`. +- **Saves:** for persistence changes, round-trip `JSON.stringify(S)` through + `parseSave()`/`migrate()`, and test that an *old* save without the new field still loads. +- **UI:** render with `renderAll()` and query `dom.window.document`; check phone + layouts by setting `window.innerWidth = 390` before rendering. +- Run `npm test`; the whole suite must pass, not just the new test. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fee591a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,66 @@ +# 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 +``` + +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 `. Never add `Co-Authored-By`, `Claude-Session` + or any other attribution trailers. +- **Releases** happen by bumping `version` in `package.json` on `main` (see the + `release` skill). Small fixes or tweaks get a patch release (`x.y.Z`); new features a + minor release. +- **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. +- **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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2300aa0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing to Series of Tubes + +Thanks for wanting to help build the cartoon internet. Bug reports, ideas, puns, +translations and code are all welcome. + +## Reporting bugs and ideas + +Open an issue on GitHub. For bugs, include what you did, what you expected and what +happened. If it involves a game in progress, attach an export of your save (menu → +Export), which lets us load your exact network. + +Ideas are best when they say what happens in real networks and how that could become +a fun mechanic. + +## Development + +The game is one static page, `site/index.html`, with no framework and no build step +while developing. + +```bash +npm ci # installs jsdom for the tests +npm run serve # builds and serves the game locally +npm test # all tests must pass +node scripts/i18n-check.js # translations must be complete +``` + +Opening `site/index.html` directly in a browser also works. + +A tour of the code is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). + +## Pull requests + +- Keep each pull request focused on one change, and target `main`. +- Add or update a test in `tests/` for every feature or fix. Tests are seeded and + must not depend on luck. +- Add a bullet for players under `## [Unreleased]` in `CHANGELOG.md`, in plain English. + Releases are cut by the maintainer. +- Old saves must keep loading. New state needs a default for new games and a check in + `sanitize()`. +- Check your change on a phone-sized screen (about 360 px wide). Most players are on + phones. + +## House rules for content + +- **Every name is a pun.** No real company names for networks, vendors, cables, banks, + data centers or exchanges. Real conference names (NANOG, RIPE, DENOG…) are fine. + Please don't use lazy "-ish" names; find a proper pun or use a plain word. +- **Accurate underneath the jokes.** Mechanics should be recognisable to a network + engineer: exaggerated, not invented. +- **Friendly humour.** Punch at technology, bureaucracy and ourselves, not at people. + +## Translations + +Every player-facing string goes through `tr()`, `trn()` or `N_()`. Dictionaries live +in `site/i18n/` (English text → translation). To add a language, copy `it.js`, translate +the values, register the language in the language list in `site/index.html`, and run +`node scripts/i18n-check.js ` until it reports nothing missing, unused or broken. + +## License + +By contributing, you agree that your contributions are licensed under the +[MIT License](LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3f4c52c --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Frederic Jung + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index e817a43..4474050 100644 --- a/README.md +++ b/README.md @@ -145,3 +145,11 @@ sites: - domain: seriesoftub.es origins: ["https://seriesoftub.es", "https://www.seriesoftub.es"] ``` + +## Contributing + +Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). + +## License + +[MIT](LICENSE) © 2026 Frederic Jung diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..b12eb49 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,140 @@ +# Architecture + +Everything that runs in the browser lives in `site/index.html`. It is large (several +thousand lines), so find things by the section banners rather than by line number: + +``` +/* ================= PHONES ================= */ phone CSS +/* ================= LANGUAGE ================= */ tr(), trn(), N_(), dictionary loading +/* ================= ANALYTICS ================= */ privacy-friendly event counter +/* ================= CONSTANTS ================= */ prices, ports (PORT), routers (RG), optics +/* ================= WORLD ================= */ CITIES, CABLES, display nudges +/* ================= NETWORKS ================= */ NETS (other ASes), traffic shares (NSH) +/* ================= BUSINESSES ================= */ BIZ_T customer types, LEVELS +/* ================= GOALS ================= */ GOALS checklist +/* ================= STATE ================= */ S, R, UI globals +/* ================= BANKS & LOANS ================= */ + scenarios (SCN), conferences, tutorial, traceroute, share card +/* ================= HELPERS ================= */ formatting, geometry, small queries +/* ================= SIMULATION ================= */ RouteScript, compute(), costs, sanitize() + failures & events, daily tick, badges +/* ================= ACTIONS ================= */ the ACT map: every player action +/* ================= SAVE ================= */ +/* ================= AUDIO ================= */ +/* ================= DOM RENDER ================= */ HUD, left panel, side panel, modals, toasts +/* ================= PHONE ================= */ tab bar, bottom sheets +/* ================= INSTALL (PWA) ================= */ +/* ================= CANVAS ================= */ map drawing, level of detail +/* ================= LOOP ================= */ frame(), boot() +``` + +Other files: + +| Path | What it is | +| --- | --- | +| `site/i18n/it.js` | Italian dictionary: English text → Italian, loaded when the language is `it` | +| `site/sw.js` | Service worker: network-first for pages, stale-while-revalidate for assets. Cache name is stamped with the version | +| `site/site.webmanifest`, icons | PWA install metadata | +| `scripts/build.sh` | Copies `site/` to `_site/`, stamps `__VERSION__`/`__BUILD_DATE__`, bakes release notes, writes `version.json` | +| `scripts/release-notes.js` | Extracts a version's CHANGELOG bullets | +| `scripts/i18n-check.js` | Compares every `tr`/`trn`/`N_` literal and `data-i18n` text with each dictionary | +| `tests/harness.js` | Loads the page in jsdom with a seeded `Math.random` and a fake canvas | +| `.github/workflows/ci.yml` | Tests and build on every push and PR | +| `.github/workflows/auto-release.yml` | On a `package.json` version bump on `main`: test, tag, GitHub release from the CHANGELOG, start the deploy | +| `.github/workflows/release.yml` | Builds and deploys to GitHub Pages | + +## Globals + +- **`S`**: the whole saved game (one JSON object). Cash, day, POPs, links, transit, + IX ports, PNIs, caches, customers (`biz`), offers, incidents (`inc`), live events + (`ev`), stats, settings. Saved to `localStorage` key `sot-save-v1`. +- **`R`**: results of the last `compute()`: per-link load, per-exit use, served and + demanded traffic, reach, costs and revenue. Never saved; always rebuilt. +- **`UI`**: view state (selection, open tabs, speed, confirmations). Not game state. +- **`cam`**: map camera (x, y, zoom). + +Lookup tables built at load: `CITY[id]`, `NET[id]`, `CABLE`, `FAB`, `BIZ_T`, `REQS`. + +## The life of a day + +`frame()` (requestAnimationFrame) accumulates time; every `DAY_MS × speed` it calls +`dayTick()`, at most four times per frame, each inside a try/catch so one bad tick +never freezes the game. + +`dayTick()`: + +1. Advances `S.day`, runs scheduled world events (conferences, IX price wars, licences). +2. Runs `compute()` to route today's traffic. +3. Records history for 95th-percentile billing, stats and streaks. +4. Rolls failures (`fireFailure()`) and events (`fireEvent()`) when their timers run out, + and expires incidents. +5. Updates customer mood, churn and new offers; IX members join; loans tick. +6. Every 30 days: bills the month (revenue minus costs) and checks for bankruptcy. +7. Checks goals, level, badges and scenario end conditions. + +## compute(): the traffic model + +1. Builds a graph from your live links: parallel links between the same two cities + merge into one edge with summed capacity. Link metrics set weights; Dijkstra gives + shortest paths from each POP. +2. Builds the exit list `E`: embedded caches (rank 0), PNIs (1), IX ports (2), + transit (3). Each exit has a capacity, the networks it can reach (`ok(net)`) and an + egress preference (`high`, `normal`, `low` = backup only). +3. Builds flows: for every POP, its demand (eyeballs and customers) split across + destination networks by their traffic share (`NSH`, with regional variants for + China, Russia and Korea). Incidents can add junk flows or scale demand. +4. Routes flows rank by rank: the nearest usable exit first, ECMP across equal exits, + consuming link, router (`nodeCap`) and exit capacity. With Auto-TE, overflow spills + onto alternate paths; RouteScript rules (`teRules()`) can prefer, avoid, cap, drain + or blackhole. +5. Layer-2 customers (L2VPN, SD-WAN, waves) are carved out of link capacity first. +6. Totals costs (`R.cost`) and revenue (`R.rev`) per month. + +Served share per city (`sfOf`) drives eyeball revenue and customer mood. + +## Actions and rendering + +- Player actions live in `ACT`. Buttons render as `btn(label, act, args, cls, disabled)` + and a delegated click handler calls `ACT[act](JSON args)`. +- An action validates its inputs (they come from the DOM), mutates `S`, shows a + `toast()` and calls `after()`. +- `after()` = `purgeInc()` + `compute()` + `checkGoals()` + `renderAll()` + `save()`. +- `renderLeft()` draws the left tabs (deals, NOC, customers…), `renderPanel()` the + selection panel (city, link, network). On phones these become bottom sheets + controlled by `renderTabbar()`. +- The map is a canvas drawn every frame by `draw()`. Zoomed out (`lodFar()`) it uses + a simplified style; parallel waves are grouped by `linkGroups()`. + +## Saves, imports and migration + +- `save()` writes `S` to localStorage every few seconds and after actions. +- `boot()` loads the save through `migrate()` → `sanitize()`. If loading throws, the + damaged save is kept under `sot-save-broken` and the player starts fresh. +- `sanitize(s)` is the gate for all untrusted state (saves and imported files): it + drops unknown ids, clamps numbers, repairs references and fills defaults. Every new + field in `S` needs a line there. + +## Translations + +- `tr(text, vars)` looks up `DICT[text]` and fills `{placeholders}`; `trn(one, other, n)` + picks the plural; `N_(text)` marks a literal for the checker and translates later. +- Static markup uses `data-i18n`; `i18nDom()` swaps it at boot. +- The English text is the key, so changing English text means updating the key in + every dictionary. + +## Tests + +`tests/*.test.js` use `node:test` and `tests/harness.js`: + +```js +const { load } = require('./harness'); +const { ev, errors } = load(); // seeded, deterministic +ev("ACT.start({});S.cash=1e8;ACT.launchBB({city:'fra'})"); +ev("compute()"); +assert.equal(ev("R.reach>0"), true); +assert.deepEqual(errors, []); +``` + +`ev()` runs code inside the page. To force a specific random failure, patch the +picker, e.g. evaluate `fireFailure` with `.replace('const e=pick(opts);', "const e='x';")`. +Use `window.__reseed(n)` to reset the random sequence mid-test. diff --git a/package-lock.json b/package-lock.json index 09451a5..78df2f9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,8 @@ }, "engines": { "node": ">=20" - } + }, + "license": "MIT" }, "node_modules/@asamuzakjp/css-color": { "version": "3.2.0", diff --git a/package.json b/package.json index c5f2c0d..eb64b5c 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "version": "1.16.0", "description": "A cartoon browser game about building the internet.", "private": true, + "license": "MIT", "homepage": "https://seriesoftub.es/", "repository": { "type": "git", "url": "git+https://github.com/fjaeckel/seriesoftubes.git" }, "scripts": {