Docs and guard rails: GitHub Pages only, where code goes, updated skills

- docs/adr/0001: GitHub Pages is the only host, not open for renegotiation
- docs/adr/0002: source in many files, shipped as one page assembled at build
- tests/pages.test.js: builds stay static files Pages can serve, all local
  references resolve, only release.yml deploys and only via the Pages actions
- tests/build.test.js: partial naming and layout rules
- new skills: github-pages, edit-the-game; add-strings, performance, release
  and write-tests updated for src/, sorted dictionaries and --base-ref
- CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md (incl. porting older branches),
  README.md and the PR template describe the new layout
This commit is contained in:
Frederic Jung 2026-10-27 10:15:12 +01:00
parent 052fdd713f
commit 05ff4ea7ad
No known key found for this signature in database
15 changed files with 530 additions and 101 deletions

View file

@ -1,30 +1,43 @@
# 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).
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/`.
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).
- `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).
## 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)
npm run dev # play while developing: http://localhost:8080, reloads on save
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)
```
To play during development, open `site/index.html` directly or run `npm run serve`.
## 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-pages` skill
and `docs/adr/0001-github-pages-only.md`.
- **No runtime cost for structure.** The page ships as one assembled `index.html`. Organise code
into files under `src/` 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 as
`Frederic Jung <frederic@jc-ix.net>`. Never add `Co-Authored-By`, `Claude-Session`
or any other attribution trailers.
@ -42,25 +55,33 @@ To play during development, open `site/index.html` directly or run `npm run serv
- **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`).
and add every translation (`site/i18n/*.js`) in the same change with `scripts/i18n-add.js`
(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),
- **Performance is always demonstrated.** Every change to `src/` or `site/` is measured on the big-network
fixture against `main` (`npm run perf -- --base-ref origin/main`, 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.
fix (a new feature gets its own `tests/<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.
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, single-file JavaScript. Match the surrounding style: short helper names,
arrow functions, template-literal HTML, no new dependencies.
- Dense JavaScript in small topic files under `src/game/` (see `edit-the-game`): a new feature gets
its own `NN-name.js` in the folder of its topic, actions go in the matching
`src/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 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`.