Add MIT license, contributing guide, CLAUDE.md, architecture notes and repo skills

This commit is contained in:
Frederic Jung 2026-10-25 07:07:00 +01:00
parent 06576357c9
commit 443202876a
No known key found for this signature in database
10 changed files with 457 additions and 1 deletions

View file

@ -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 (`<b>`, `<br>`, `<small>`) 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
```

View file

@ -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<version>`, 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 <frederic@jc-ix.net>" -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 <id> --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.

View file

@ -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.

66
CLAUDE.md Normal file
View file

@ -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 <frederic@jc-ix.net>`. 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.

62
CONTRIBUTING.md Normal file
View file

@ -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 <lang>` until it reports nothing missing, unused or broken.
## License
By contributing, you agree that your contributions are licensed under the
[MIT License](LICENSE).

21
LICENSE Normal file
View file

@ -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.

View file

@ -145,3 +145,11 @@ sites:
- domain: seriesoftub.es - domain: seriesoftub.es
origins: ["https://seriesoftub.es", "https://www.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

140
docs/ARCHITECTURE.md Normal file
View file

@ -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.

3
package-lock.json generated
View file

@ -12,7 +12,8 @@
}, },
"engines": { "engines": {
"node": ">=20" "node": ">=20"
} },
"license": "MIT"
}, },
"node_modules/@asamuzakjp/css-color": { "node_modules/@asamuzakjp/css-color": {
"version": "3.2.0", "version": "3.2.0",

View file

@ -3,6 +3,7 @@
"version": "1.16.0", "version": "1.16.0",
"description": "A cartoon browser game about building the internet.", "description": "A cartoon browser game about building the internet.",
"private": true, "private": true,
"license": "MIT",
"homepage": "https://seriesoftub.es/", "homepage": "https://seriesoftub.es/",
"repository": { "type": "git", "url": "git+https://github.com/fjaeckel/seriesoftubes.git" }, "repository": { "type": "git", "url": "git+https://github.com/fjaeckel/seriesoftubes.git" },
"scripts": { "scripts": {