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:
parent
052fdd713f
commit
05ff4ea7ad
15 changed files with 530 additions and 101 deletions
|
|
@ -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 `<style>`, one inline
|
||||
`<script>`), exactly the page players have always loaded ([ADR 0002](adr/0002-one-page-assembled-at-build.md)).
|
||||
|
||||
```
|
||||
/* ================= 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 + LV_REQ (13 levels, traffic eras)
|
||||
/* ================= 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()
|
||||
src/ the game page, in pieces
|
||||
index.html shell: <head>, static markup, the language loader, two @include lines
|
||||
styles/NN-*.css → pasted into the page's <style>, in path order
|
||||
game/NN-area/NN-*.js → pasted into the page's <script>, in path order
|
||||
site/ static files copied to the build as they are (dictionaries, icons, sw.js…)
|
||||
scripts/lib/page.js the assembler: <!-- @include DIR --> → every file under src/DIR, sorted
|
||||
scripts/build.js _site/ = site/ + the assembled page, version-stamped, release notes baked in
|
||||
```
|
||||
|
||||
Other files:
|
||||
Because the partials are concatenated into one classic script, they share one top-level scope, just as
|
||||
when they were one file: `S`, `CITY` or `compute()` are visible everywhere, function declarations are
|
||||
hoisted across files, and top-level statements run in path order. Find code by name
|
||||
(`grep -rn "function compute(" src/game`); the folders follow the game's layers:
|
||||
|
||||
| Folder under `src/game/` | What lives there |
|
||||
| --- | --- |
|
||||
| `00-core/` | `tr()`/`trn()`/`N_()` and the dictionary; version, release notes and the analytics counter |
|
||||
| `10-catalog/` | Prices and gear: POP and port costs, routers (`RG`), supply chain, port slots, dark fiber systems and optics (`OPT`), reach and subsea upgrades |
|
||||
| `20-world/` | Map projection, landmasses, coastline, city coordinates (`CITY_LL`), `CITIES`, `CABLES` |
|
||||
| `30-networks/` | Other ASes (`NETS`), rival exchanges (`XIX`), the long tail, traffic shares (`NSH`) |
|
||||
| `40-progress/` | Customer types (`BIZ_T`), `LEVELS` and their requirements, `GOALS` |
|
||||
| `50-state.js` | The globals `S`, `R`, `UI`; `emptyR()` |
|
||||
| `60-features/` | Banks and loans, scenarios and the weekly challenge, conferences, the tutorial, traceroute, the share card, `newGame()` |
|
||||
| `70-rules/` | Formatting helpers and market rules: exchanges, PNIs, the peering inbox, peering policy and snubs, DE-KICKS, sold-out routes, hot ports and the Tier 1/2/3 rank |
|
||||
| `80-simulation/` | Dijkstra, RouteScript, `compute()`, monthly prices, `sanitize()`/`migrate()`, customer requirements, events, geography pricing and latency, second sites and service |
|
||||
| `85-incidents/` | `addInc()`, DDoS and scrubbing, `fireFailure()`, `clearInc()`, `fireEvent()` |
|
||||
| `88-days/` | `dayTick()`, new offers, badges, `checkGoals()` |
|
||||
| `90-actions/` | The `ACT` map, one file per area (`const ACT` in `10-interface.js`, `Object.assign(ACT,…)` in the rest), and their helpers |
|
||||
| `91-save.js`, `92-audio.js` | Save, export and import; sound effects |
|
||||
| `93-ui/` | DOM helpers (`$`, `btn`, `morph`), the phone tab bar, install pitch, HUD, left panel, city and link panels, decommissioning |
|
||||
| `94-dashboard/` | Scenario and level progress, where to meet a network, customers and connections overviews, lease swaps, the NOC dashboard, the bank, hints |
|
||||
| `95-modals/` | Toasts, notifications, modals, title screen, what's new, help, the link and own-cable modals |
|
||||
| `96-map/` | The canvas: resize, land and clouds, settings, level of detail, link geometry, `draw()`, the world layer, cities, input and click delegation |
|
||||
| `99-loop.js` | `frame()` and `boot()` |
|
||||
|
||||
`src/styles/` holds the CSS the same way: base, HUD, drawers, toasts, modal, tablet, then phone.
|
||||
|
||||
Rules for the source (checked by `tests/build.test.js` and the assembler): files are named
|
||||
`NN-lower-case.js`/`.css`, end with a newline and never close their `<script>`/`<style>`; top-level code
|
||||
may only use top-level values from earlier files; tables people add to have one entry per line, the
|
||||
id-keyed ones sorted. New features get their own file in the right folder (`edit-the-game` skill).
|
||||
Development runs on `npm run dev` (assembles on every request, reloads on save);
|
||||
`npm run page -- -o FILE` writes the assembled page.
|
||||
|
||||
## Other files
|
||||
|
||||
| Path | What it is |
|
||||
| --- | --- |
|
||||
| `site/i18n/it.js` | Italian dictionary: English text → Italian, loaded when the language is `it` |
|
||||
| `site/i18n/pt.js` | Portuguese (Brazil) dictionary: English text → Portuguese, loaded when the language is `pt` |
|
||||
| `site/i18n/fr.js` | French dictionary: English text → French, loaded when the language is `fr` |
|
||||
| `site/i18n/it.js`, `pt.js`, `fr.js` | Dictionaries: English text → translation, one entry per line, sorted; loaded only for that language |
|
||||
| `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` |
|
||||
| `site/site.webmanifest`, icons, `404.html`, `CNAME`, `robots.txt`, `sitemap.xml`, `llms.txt` | PWA and GitHub Pages files, copied as they are |
|
||||
| `scripts/lib/page.js` | Assembles the page from `src/` (also from a git ref with `--ref`, for performance baselines) |
|
||||
| `scripts/build.js` | Builds `_site/` for GitHub Pages: copies `site/`, writes the page, stamps `__VERSION__`/`__BUILD_DATE__`, bakes release notes, writes `version.json` |
|
||||
| `scripts/dev.js` | `npm run dev`: development server, no dependencies |
|
||||
| `scripts/test.js` | `npm test`: runs every `tests/*.test.js` |
|
||||
| `scripts/release-notes.js` | Extracts a version's CHANGELOG bullets |
|
||||
| `scripts/perf-bench.js`, `scripts/perf-browser.js`, `scripts/perf-stats.js`, `scripts/perf-fixture.js` | Big-network benchmark, base vs head, headless and in Chromium as a desktop and a throttled phone, with a significance test per row (posted on every PR by `perf.yml` + `perf-comment.yml`), and the generator of its save, `tests/fixtures/big-network.json` |
|
||||
| `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 |
|
||||
| `scripts/perf-bench.js`, `perf-browser.js`, `perf-stats.js`, `perf-fixture.js` | Big-network benchmark, base vs head, headless and in Chromium as a desktop and a throttled phone, with a significance test per row (posted on every PR by `perf.yml` + `perf-comment.yml`), and the generator of its save, `tests/fixtures/big-network.json` |
|
||||
| `scripts/i18n-check.js`, `scripts/i18n-add.js`, `scripts/lib/dict.js` | Translation coverage and dictionary order; adding, renaming and removing entries |
|
||||
| `scripts/legacy/` | The splitter that made `src/` from the old `site/index.html`, and `port-branch.js`, which carries older branches over |
|
||||
| `tests/harness.js` | Loads the assembled 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 |
|
||||
| `.github/workflows/release.yml` | Builds and deploys to GitHub Pages, the only workflow that can |
|
||||
| `docs/adr/` | Decisions: GitHub Pages only (0001), one page assembled at build (0002) |
|
||||
|
||||
## Globals
|
||||
|
||||
|
|
@ -133,7 +158,8 @@ Served share per city (`sfOf`) drives eyeball revenue and customer mood.
|
|||
|
||||
## Tests
|
||||
|
||||
`tests/*.test.js` use `node:test` and `tests/harness.js`:
|
||||
`tests/*.test.js` use `node:test` and `tests/harness.js`, which assembles `src/` in memory, so tests
|
||||
never run a stale build. `npm test` runs every file in `tests/`; a new suite needs no registration:
|
||||
|
||||
```js
|
||||
const { load } = require('./harness');
|
||||
|
|
|
|||
54
docs/adr/0001-github-pages-only.md
Normal file
54
docs/adr/0001-github-pages-only.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
# ADR 0001: Series of Tubes is hosted on GitHub Pages, and only there
|
||||
|
||||
- Status: accepted, not open for renegotiation
|
||||
- Date: 2026-10-27
|
||||
- Decided by: Frederic Jung
|
||||
|
||||
## Decision
|
||||
|
||||
The game is served by **GitHub Pages**, from the custom domain in `site/CNAME`
|
||||
(https://seriesoftub.es). That is the only hosting. There is no second host, no fallback host and no
|
||||
plan to move.
|
||||
|
||||
Every change has to keep working there. A change that only works with a server, a different host,
|
||||
a CDN in front, edge functions, rewrites or custom response headers is the wrong design for this
|
||||
project, however good it is otherwise. Change the design, not the host.
|
||||
|
||||
## What GitHub Pages gives us, and what it does not
|
||||
|
||||
| We can rely on | We cannot have |
|
||||
| --- | --- |
|
||||
| Static files over HTTPS from one origin, with gzip | Any server code: no API routes, no SSR, no PHP, no edge or serverless functions |
|
||||
| The deploy in `release.yml` (`actions/upload-pages-artifact` + `actions/deploy-pages`) | Custom HTTP headers (`Cache-Control`, CSP, COOP/COEP): use `<meta>` tags or do without |
|
||||
| `404.html` for unknown paths | Redirect or rewrite rules (`_redirects`, `.htaccess`, `vercel.json`, `netlify.toml`) |
|
||||
| `CNAME` for the domain | Per-file caching rules: Pages sets its own short cache lifetime for everything |
|
||||
| A size limit of about 1 GB for the site and 100 MB per file | Secrets at runtime: everything in `_site/` is public |
|
||||
|
||||
Anything that needs data at runtime fetches it from the same origin as a static file
|
||||
(`version.json`), from the player's own browser (`localStorage`), or not at all.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **The build is the place for work.** Anything clever (assembling the page from `src/`, stamping the
|
||||
version, baking release notes) happens in `scripts/build.js`, at build time, in GitHub Actions.
|
||||
The build may get slower; what it produces must stay plain static files. See
|
||||
[ADR 0002](0002-one-page-assembled-at-build.md).
|
||||
- **Same origin for everything the game loads.** The page, the dictionaries, icons and the service
|
||||
worker all come from seriesoftub.es. The only cross-origin requests are the web fonts and the
|
||||
privacy-friendly analytics counter (its script and its endpoint), and the game works without both.
|
||||
Don't add more: no CDN-hosted libraries, no third-party APIs the game depends on.
|
||||
- **The service worker is the cache policy.** Since Pages decides HTTP caching, `site/sw.js` decides
|
||||
what is cached for offline play, versioned by the release.
|
||||
- **Deploys only come from releases.** `release.yml` is the only workflow with `pages: write`. Pushes to
|
||||
`main` never deploy.
|
||||
- **Tests guard it.** `tests/pages.test.js` checks that a build is plain static files that GitHub
|
||||
Pages can serve as they are: no server or host configuration files, every local reference resolving
|
||||
inside `_site/`, nothing over the size limits, `CNAME` and `404.html` in place, and the deploy going
|
||||
through the official Pages actions.
|
||||
|
||||
## Proposals that are out of scope
|
||||
|
||||
Moving to Netlify, Vercel, Cloudflare Pages or a VPS; putting a CDN or proxy in front; adding a
|
||||
backend for accounts, leaderboards or cloud saves; server-side rendering. Features in that direction
|
||||
must be built from static files and the browser (for example, an exported save file instead of a cloud
|
||||
save), or not at all.
|
||||
68
docs/adr/0002-one-page-assembled-at-build.md
Normal file
68
docs/adr/0002-one-page-assembled-at-build.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# ADR 0002: Source in many files, shipped as one page assembled at build
|
||||
|
||||
- Status: accepted
|
||||
- Date: 2026-10-27
|
||||
|
||||
## Context
|
||||
|
||||
Until 1.33 the whole game was `site/index.html`: about 900 KB and 5,100 lines of HTML, CSS and JavaScript
|
||||
in one file, edited by many contributors at once. Nearly every pull request touched that file, so
|
||||
pull requests conflicted with each other all the time, reviews meant scrolling a 900 KB file, and
|
||||
nobody could tell from a diff's file list what a change was about.
|
||||
|
||||
What had to stay: hosting on GitHub Pages ([ADR 0001](0001-github-pages-only.md)), load time and in-game
|
||||
speed (most players are on phones), saves, the tests that reach into the page's globals (`S`, `R`,
|
||||
`ACT`, `compute()`), and no new runtime dependencies.
|
||||
|
||||
## Decision
|
||||
|
||||
- The page's source lives in `src/`: a shell (`src/index.html`) with `<!-- @include DIR -->` lines,
|
||||
the styles in `src/styles/*.css` and the game script in `src/game/**/*.js`.
|
||||
- `scripts/lib/page.js` assembles them by **plain concatenation in path order** into the same single,
|
||||
self-contained `index.html` as before: one inline `<style>`, one inline classic `<script>`.
|
||||
The numeric prefixes (`10-`, `20-`…) set that order; gaps leave room to add files in between.
|
||||
- `scripts/build.js` builds `_site/` from that page plus the static files in `site/`.
|
||||
- Nothing else changes at runtime. When the split landed, the assembled page was byte-for-byte the old
|
||||
`site/index.html`.
|
||||
|
||||
## Why concatenation, and not ES modules or a bundler
|
||||
|
||||
- **Zero runtime cost.** One HTML request, as before. ES modules would mean many requests (or a bundler),
|
||||
module graph evaluation and a new loading order; at best they break even.
|
||||
- **The code is one script on purpose.** The partials share top-level names (`S`, `R`, `UI`, `CITY`,
|
||||
`tr`…) and function declarations are hoisted across the whole script. Concatenated, every partial
|
||||
sees exactly what it saw before, with no `import`/`export` lists to keep in sync (another source of
|
||||
conflicts) and no circular-import pitfalls.
|
||||
- **Tests keep working.** jsdom loads the assembled page, and tests still call into its globals and
|
||||
patch functions by their source text.
|
||||
- **No dependencies.** The assembler is about a hundred lines of Node with nothing to install, so it
|
||||
runs anywhere `npm test` does, including GitHub Actions.
|
||||
- **It is reversible.** If a bundler is ever worth it, the partials are already the modules it needs.
|
||||
|
||||
## Rules that come with it
|
||||
|
||||
- **Order matters for top-level code.** `const`/`let` and statements at the top level of a partial run
|
||||
in path order, so a partial can only use top-level *values* from partials that come before it (or
|
||||
inside functions that run later, after boot). Functions can be called from anywhere once the page
|
||||
has loaded.
|
||||
- **A partial is a complete set of statements.** Each file ends with a newline and never closes the
|
||||
`<script>`/`<style>` it is pasted into; the assembler refuses files that break this.
|
||||
- **Put new code where its topic is.** A new feature gets its own partial in the right folder (for
|
||||
example `src/game/70-rules/85-my-feature.js`), its actions go in the matching
|
||||
`src/game/90-actions/*.js`, its panel in `src/game/93-ui/` or `src/game/94-dashboard/`. Small files
|
||||
that own one topic are what keep pull requests apart.
|
||||
- **Keep lists one entry per line.** Tables people add to (cities, cables, networks, dictionaries) have
|
||||
one entry per line, and the id-keyed ones are sorted, so additions land in different places.
|
||||
- **The CHANGELOG is the one shared file every change touches**, on purpose: one bullet per change under
|
||||
`## [Unreleased]`. A conflict there is expected and easy: keep both bullets.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Development needs one command: `npm run dev` serves the page assembled on every request and reloads
|
||||
the browser on save. Opening a file straight from disk no longer runs the game.
|
||||
- Error line numbers in the browser refer to the assembled page; the dev server prints the matching
|
||||
`src/` file and line in the console.
|
||||
- Branches started before the split are carried over with `scripts/legacy/port-branch.js`
|
||||
(see CONTRIBUTING.md).
|
||||
- The performance workflow builds the base's page from git with that commit's own assembler
|
||||
(`node scripts/lib/page.js --ref REF`), so base and head are always compared as players get them.
|
||||
Loading…
Add table
Add a link
Reference in a new issue