From 05ff4ea7adf868c5416dc8e5ffca5aa73ecc1035 Mon Sep 17 00:00:00 2001 From: Frederic Jung Date: Tue, 27 Oct 2026 10:15:12 +0100 Subject: [PATCH] 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 --- .claude/skills/add-strings/SKILL.md | 30 +++--- .claude/skills/edit-the-game/SKILL.md | 67 ++++++++++++++ .claude/skills/github-pages/SKILL.md | 52 +++++++++++ .claude/skills/performance/SKILL.md | 17 ++-- .claude/skills/release/SKILL.md | 8 +- .claude/skills/write-tests/SKILL.md | 13 ++- .gitattributes | 3 + CLAUDE.md | 59 ++++++++---- CONTRIBUTING.md | 53 +++++++++-- README.md | 26 ++++-- docs/ARCHITECTURE.md | 96 +++++++++++++------- docs/adr/0001-github-pages-only.md | 54 +++++++++++ docs/adr/0002-one-page-assembled-at-build.md | 68 ++++++++++++++ tests/build.test.js | 13 +++ tests/pages.test.js | 72 +++++++++++++++ 15 files changed, 530 insertions(+), 101 deletions(-) create mode 100644 .claude/skills/edit-the-game/SKILL.md create mode 100644 .claude/skills/github-pages/SKILL.md create mode 100644 .gitattributes create mode 100644 docs/adr/0001-github-pages-only.md create mode 100644 docs/adr/0002-one-page-assembled-at-build.md create mode 100644 tests/pages.test.js diff --git a/.claude/skills/add-strings/SKILL.md b/.claude/skills/add-strings/SKILL.md index 52fb997..ab600c6 100644 --- a/.claude/skills/add-strings/SKILL.md +++ b/.claude/skills/add-strings/SKILL.md @@ -7,7 +7,7 @@ description: Add or change player-facing text in Series of Tubes and keep every 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). +(Italian `it.js`, Portuguese `pt.js`, French `fr.js`). The code is in `src/`. ## In the code @@ -23,21 +23,25 @@ through the translation helpers and have an entry in every dictionary in `site/i ## 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: +`site/i18n/.js` is one object, `"English":"Translation",` per line, **sorted by the English +text**. Sorted files mean two pull requests that add strings touch different lines instead of both +appending at the end. Don't edit the lines by hand; use the script, which quotes correctly, keeps the +order and works on every dictionary at once: -```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) +```bash +cat > /tmp/strings.json <<'JSON' +{ + "it": { "New English text": "Nuovo testo italiano", "Text that was removed": null }, + "pt": { "New English text": "Novo texto em português" }, + "fr": { "New English text": "Nouveau texte en français" } +} +JSON +node scripts/i18n-add.js /tmp/strings.json # a string adds or replaces, null removes +node scripts/i18n-add.js --rename "Old English" "New English" # English text changed: move the key everywhere ``` -When you **change** English text, rename the key in every dictionary too; when you -remove text, delete its entry. +If a dictionary got out of order anyway (a hand edit, a merge), `npm run i18n:fix` sorts it again; +`npm run i18n:check` fails until it is sorted. ## Italian style diff --git a/.claude/skills/edit-the-game/SKILL.md b/.claude/skills/edit-the-game/SKILL.md new file mode 100644 index 0000000..bfacf0e --- /dev/null +++ b/.claude/skills/edit-the-game/SKILL.md @@ -0,0 +1,67 @@ +--- +name: edit-the-game +description: Find, change and add game code in Series of Tubes, which lives in many small files under src/ that the build joins into one page. Use for any feature, fix or refactor in the game itself (anything in src/). +--- + +# Editing the game + +The game's source is `src/`. The build (`scripts/lib/page.js`) pastes the files together, in path order, +into one `index.html` with one inline `` at the start of a line. +File names are `NN-lower-case.js` / `.css`; `tests/build.test.js` checks both. + +## Still the same rules + +Everything in CLAUDE.md applies unchanged: translate every string (`add-strings`), sanitize saves, +phones first, a test with every change (`write-tests`), performance shown against `main` +(`performance`), hosting on GitHub Pages only (`github-pages`), a CHANGELOG bullet for players. +The CHANGELOG is the one file every change touches; a conflict there is expected: keep both bullets. diff --git a/.claude/skills/github-pages/SKILL.md b/.claude/skills/github-pages/SKILL.md new file mode 100644 index 0000000..3eafcfb --- /dev/null +++ b/.claude/skills/github-pages/SKILL.md @@ -0,0 +1,52 @@ +--- +name: github-pages +description: Series of Tubes is hosted on GitHub Pages and nowhere else, non-negotiably. Use before any change to hosting, deploys, the build output, caching, the service worker, new runtime requests or anything that would need a server, and whenever someone suggests another host. +--- + +# GitHub Pages, always + +Series of Tubes is served by GitHub Pages at https://seriesoftub.es and **only** there. This is settled +([docs/adr/0001-github-pages-only.md](../../../docs/adr/0001-github-pages-only.md)) and not up for +discussion: do not propose, prepare or "keep the door open" for another host, a CDN in front, a +backend or server-side rendering, even when asked to evaluate options. If a feature seems to need +one, redesign the feature. + +## What that means for a change + +- **The output is static files.** `npm run build` writes `_site/`: the assembled page, `site/`'s files, + `version.json`. No server code, no runtime secrets: everything there is public. +- **No HTTP headers, redirects or rewrites.** Pages ignores `_headers`, `_redirects`, `.htaccess`, + `vercel.json`, `netlify.toml`. Need a policy? Use a `` tag. Need a different URL? Add a + static file there. +- **Caching is Pages' (short, the same for every file) plus the service worker's.** Offline play and + updates are `site/sw.js`'s job; its cache name carries the version. When you add a file the game + needs offline, add it to `CORE` there. +- **Same origin.** The page, dictionaries, icons and data come from seriesoftub.es. Do not add CDN + libraries or third-party APIs the game needs to work; the web fonts and the analytics counter are + the only exceptions and the game runs without them. +- **More files are fine, from the same origin.** Pages serves many small files well over HTTP/2. + Still: the game page itself stays one assembled `index.html` (see + [ADR 0002](../../../docs/adr/0002-one-page-assembled-at-build.md)), and anything the first frame + needs must not add a round trip. +- **Limits:** about 1 GB for the whole site, 100 MB per file. +- **Paths:** the site lives at the domain root (`site/CNAME`), so `/` paths are fine; unknown paths get + `404.html`. + +## How it deploys + +Only releases deploy. Bumping `version` in `package.json` on `main` runs `auto-release.yml`, which tags, +publishes the GitHub release and starts `release.yml`: test, `REQUIRE_NOTES=1 npm run build`, +`actions/upload-pages-artifact` with `./_site`, `actions/deploy-pages`. That job is the only one with +`pages: write`. Pushes to `main` and pull requests build but never deploy. The `release` skill has the +steps. + +## Before you hand back a change that touches the build, deploy or loading + +```bash +npm run build && npm run serve # the production build, served as static files +npm test -- tests/pages.test.js # static-only, all references resolve, Pages-only deploy +``` + +`tests/pages.test.js` fails on host configuration files, files over the limits, local references +that do not exist in `_site/`, scripts loaded from other origins, and any workflow that deploys +anywhere else. Do not weaken it to make a change pass; change the change. diff --git a/.claude/skills/performance/SKILL.md b/.claude/skills/performance/SKILL.md index 1f1e598..c071f46 100644 --- a/.claude/skills/performance/SKILL.md +++ b/.claude/skills/performance/SKILL.md @@ -5,7 +5,7 @@ description: Measure and demonstrate the performance of every Series of Tubes ch # Performance is always demonstrated -Every change to the game (anything in `site/`) shows its performance on a very large network, +Every change to the game (anything in `src/` or `site/`) shows its performance on a very large network, compared with `main`, before it is merged or released. A speed claim without numbers does not count, and neither does "it feels fine on my small game". Most players who complain about lag have huge late-game networks, and most of them are on phones. @@ -13,11 +13,14 @@ have huge late-game networks, and most of them are on phones. ## Measure ```bash -git show origin/main:site/index.html > /tmp/base.html -npm run perf -- --base /tmp/base.html # headless only, a few minutes -npm run perf -- --base /tmp/base.html --browser # plus real Chromium, desktop and phone (what CI runs) +npm run perf -- --base-ref origin/main # headless only, a few minutes +npm run perf -- --base-ref origin/main --browser # plus real Chromium, desktop and phone (what CI runs) ``` +`--base-ref` assembles that commit's page with its own scripts (`node scripts/lib/page.js --ref REF`; +for commits from before the split it reads their `site/index.html`). `--base FILE` takes a built page +instead. The head is always this checkout's `src/`, assembled the way the build does it. + `scripts/perf-bench.js` loads `tests/fixtures/big-network.json` (about 100 POPs, 150 links, 950 PNIs, 830 cache boxes, 110 IX ports, 170 customers) into the base and into this checkout and times them in alternating turns, 15 runs each. It prints one table per environment: @@ -57,7 +60,7 @@ Without `--base` it just times this checkout. `--runs N`, `--md FILE`, `--json F save and a file from the in-game menu's Export save work: ```bash -npm run perf -- --save ~/Downloads/series-of-tubes-save.json --base /tmp/base.html +npm run perf -- --save ~/Downloads/series-of-tubes-save.json --base-ref origin/main ``` Routing speed-ups must also keep the two equivalence tests green: `tests/speed.test.js` (the fast @@ -70,10 +73,10 @@ incidents and failures). - **Every pull request**: the Performance workflow runs the same comparison and posts the table as a comment on the PR (updated on every push). Read it before merging. Locally, paste the table into the PR description or the commit summary you report. -- **Everything you hand back to Frederic** that touched `site/`: include the table, or at least the +- **Everything you hand back to Frederic** that touched `src/` or `site/`: include the table, or at least the rows that moved, in your summary. Say plainly when something got slower. - **Before a release**: compare the release against the previous tag - (`git show v:site/index.html > /tmp/base.html`) and mention notable changes. + (`npm run perf -- --base-ref v`) and mention notable changes. ## Read the table diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index 6307236..79087df 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -7,8 +7,10 @@ description: Cut and ship a Series of Tubes release (patch or minor) from main v 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). +that version's CHANGELOG section as notes, and dispatches `release.yml`, which builds +`_site/` (`npm run build`: the page assembled from `src/` plus `site/`) and deploys it +to GitHub Pages (https://seriesoftub.es). GitHub Pages is the only host, ever: see the +`github-pages` skill. ## Only release when Frederic says so @@ -53,7 +55,7 @@ gh api repos/fjaeckel/seriesoftubes/releases/latest --jq '.tag_name+" "+.publish - `package-lock.json` → top-level `"version"` and `packages[""].version` 4. `npm test` once more. Then compare performance with the previous release and mention anything notable to Frederic: - `git show v:site/index.html > /tmp/base.html && npm run perf -- --base /tmp/base.html`. + `npm run perf -- --base-ref v`. 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 \ diff --git a/.claude/skills/write-tests/SKILL.md b/.claude/skills/write-tests/SKILL.md index 4f0ce7c..b465835 100644 --- a/.claude/skills/write-tests/SKILL.md +++ b/.claude/skills/write-tests/SKILL.md @@ -5,8 +5,8 @@ description: Write deterministic jsdom tests for Series of Tubes features and fi # 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. +Tests use `node:test` and `tests/harness.js`, which assembles the game page from `src/` +(once per test file) and loads it in jsdom with the animation loop off, a seeded `Math.random` and a recording fake canvas. Code runs inside the page through `ev()`. ## Pattern @@ -29,8 +29,11 @@ test('what the player should see happen', () => { 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`. +`#NN …`), `regions`, `modes` (scenarios, sandbox, weekly), `i18n`, `pages` (hosting). +For a new feature, prefer a new file named after it (`tests/route-servers.test.js`): every +`tests/*.test.js` runs on its own (`scripts/test.js`), and a file of your own never conflicts +with someone else's tests. Appending to the big suites (`issues`, `regions`) is where +pull requests collide. Run one file with `npm test -- tests/route-servers.test.js`. ## Rules @@ -40,7 +43,7 @@ added to the `test` script in `package.json`. ```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. + Check the current source for the exact `pick` line first (`grep -rn "function fireFailure" src/game`); 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. diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..cb714b7 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# The assembler joins src/ byte for byte and refuses CR line endings; keep LF everywhere it reads. +src/** text eol=lf +site/i18n/*.js text eol=lf diff --git a/CLAUDE.md b/CLAUDE.md index 9eaf5e8..ea30581 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 `. 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/.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`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d945d44..3dcf1d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,19 +18,49 @@ Not sure yet whether something is a bug or an idea worth an issue? Ask in the ## Development -The game is one static page, `site/index.html`, with no framework and no build step -while developing. +The game is one static page with no framework, hosted on GitHub Pages. Its source is split into +small files under `src/` (styles in `src/styles/`, the game script in `src/game/`), which the build +joins, in path order, into a single `index.html`. Static files such as the translations live in `site/`. ```bash npm ci # installs jsdom for the tests -npm run serve # builds and serves the game locally +npm run dev # http://localhost:8080, reloads when you save a file npm test # all tests must pass -node scripts/i18n-check.js # translations must be complete +node scripts/i18n-check.js # translations must be complete and sorted +npm run serve # the production build, as GitHub Pages will serve it ``` -Opening `site/index.html` directly in a browser also works. +Where things are, and how a day of the simulation runs: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). -A tour of the code is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). +### Keeping pull requests apart + +Many people work on the game at once. A few habits keep your pull request from colliding with theirs: + +- Put a new feature in its own file in the folder of its topic (for example + `src/game/70-rules/85-route-servers.js`), and its tests in their own `tests/.test.js`. + New files in `src/` and `tests/` are picked up automatically; nothing needs registering. +- Add actions to the matching file in `src/game/90-actions/`, not wherever there is room. +- Lists (cities, cables, networks) take one entry per line; keep id-keyed tables sorted. +- Add translations with `node scripts/i18n-add.js` rather than by hand: it keeps the dictionaries + sorted, so your new strings don't land on the same lines as everyone else's. +- The `CHANGELOG.md` bullet is the one place everybody writes. If it conflicts, keep both bullets. + +### Your branch still edits `site/index.html`? + +Until version 1.33 the whole game was one file, `site/index.html`. If your branch was started before +the split, merge `main` and let a script move your changes into `src/`: + +```bash +git fetch origin +git merge origin/main # stops: site/index.html was deleted on main +node scripts/legacy/port-branch.js # moves your edits into the matching src/ files +git status # fix any conflict it lists, then +npm test && git commit +``` + +It splits your version of the page and the one you started from the same way `src/` was made, merges +each piece into `src/`, and applies your dictionary changes entry by entry. It only reports conflicts +where your change and `main` touched the same lines. ## Pull requests @@ -42,11 +72,14 @@ A tour of the code is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). must not depend on luck. - Add a bullet for players under `## [Unreleased]` in `CHANGELOG.md`, in plain English. Releases are cut by the maintainer. -- Show the performance of changes to `site/` on a big network. The Performance check posts a table +- Show the performance of changes to `src/` on a big network. The Performance check posts a table comparing your PR with `main` as a comment; to run it yourself: - `git show origin/main:site/index.html > /tmp/base.html && npm run perf -- --base /tmp/base.html` + `npm run perf -- --base-ref origin/main` (add `--browser` to also time it in Chromium as a desktop and a phone, like CI does). Anything marked slower needs an explanation. +- The game is hosted on GitHub Pages, and that will not change. Changes must work as plain static + files: no server code, no other host, no redirects or custom headers (see + [docs/adr/0001-github-pages-only.md](docs/adr/0001-github-pages-only.md)). - 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 @@ -64,8 +97,8 @@ A tour of the code is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## 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 +in `site/i18n/` (English text → translation, one entry per line, sorted). To add a language, copy +`it.js`, translate the values, register the language in the language list in `src/index.html`, and run `node scripts/i18n-check.js ` until it reports nothing missing, unused or broken. The CI job "translations" runs the same check on every pull request, shows each language's coverage in the run summary, and also fails if a new language is not added to the language list or to the offline cache in `site/sw.js`. Language pull requests must be reviewed by a human who speaks the language, and diff --git a/README.md b/README.md index 9940c8b..e64a010 100644 --- a/README.md +++ b/README.md @@ -36,10 +36,11 @@ an hour there than from a year of laying cartoon fiber here. ## Playing locally -It is a single static page with no build step for development: +It is a single static page, assembled from the files in `src/` by a small Node script: ```sh -open site/index.html # or: npm run serve +npm ci +npm run dev # http://localhost:8080 ``` Progress is saved in your browser's local storage. @@ -51,32 +52,39 @@ and remembers the one you pick under Settings or on the title screen. ```sh npm ci +npm run dev # development server: assembles src/ on every request, reloads on save npm test # headless tests: boot, geography, a year of play, every incident, every panel -npm run build # writes the deployable site to _site/ with version and date stamped in +npm run build # writes the site for GitHub Pages to _site/, with version and date stamped in npm run i18n:check # lists text missing from (or stale in) the translations ``` ``` -site/ everything that is deployed - index.html the whole game (HTML, CSS and JS in one file) +src/ the game page, in pieces (joined into one index.html at build) + index.html the shell: , static markup, @include lines + styles/ CSS + game/ the game script, by topic: world, networks, simulation, actions, UI, map… +site/ static files, deployed as they are i18n/it.js Italian translation, loaded only when the game runs in Italian i18n/pt.js Portuguese (Brazil) translation, loaded only when the game runs in Portuguese i18n/fr.js French translation, loaded only when the game runs in French images/og-image.png social preview (1200×630) favicon.*, icon-* favicons, app icons, manifest + sw.js service worker (offline play) robots.txt, sitemap.xml, llms.txt, 404.html, CNAME -scripts/build.sh copies site/ to _site/ and stamps __VERSION__ / __BUILD_DATE__ +scripts/build.js builds _site/ for GitHub Pages: site/ + the assembled page, stamped +scripts/lib/page.js joins src/ into the page tests/ node:test + jsdom -.github/workflows/ ci.yml (pushes to main and PRs) and release.yml (Pages deploy) +docs/ architecture and decisions (docs/adr/) +.github/workflows/ ci.yml (pushes to main and PRs) and release.yml (GitHub Pages deploy) ``` ## Translations -English is the source text. Player-facing strings in `index.html` go through +English is the source text. Player-facing strings in `src/` go through `tr('Unlocks at level {n}.', {n})` (or `trn(one, other, n)` for plurals); static markup uses `data-i18n`, and `aria-label`/`title` are translated at boot. Each language is a `site/i18n/.js` file mapping the English text to its translation, plus an entry in -`SOT_LANGS` (the language loader at the top of the page). Missing entries fall back to +`SOT_LANGS` (the language loader in `src/index.html`). Missing entries fall back to English, so new English text never breaks the game; `npm run i18n:check` lists what needs translating, and the tests make sure every translation keeps its `{placeholders}` and HTML tags. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bd626c8..39af49d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,50 +1,75 @@ # 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: +Series of Tubes is a static web game hosted on **GitHub Pages, and only there** +([ADR 0001](adr/0001-github-pages-only.md)). Its source is split into many small files under `src/`; +the build joins them into **one self-contained `index.html`** (one inline `