# CLAUDE.md — free-steam-games-list Load-bearing facts about this repo. Every claim here was verified against the code; if you change the code, change this file. ## What this is A dataset of free-to-play Steam games (`data/data_*.jsonl`) plus a SvelteKit app (`web/`), a Tauri 2 desktop/Android shell (`web/src-tauri/`), and a Python scraping pipeline (`scripts/`) driven by GitHub Actions. **Git is the source of truth for game data.** Nothing else is. Keep it that way. ## Project status: stable, maintenance only (since 2026-11-11) The project is finished, not abandoned. The pipeline, the site and the apps keep running; the code no longer grows. What that means for any change: - **No new features**, and no refactor or redesign for its own sake. A request for one is declined, whoever asks in an issue or a pull request. - **Code changes only for** a security advisory (CVE, CodeQL, RustSec, `npm audit`), a runtime or dependency update (Node, Python, Rust, npm / pip / cargo packages, pinned Actions), and whatever those break. A bug or an accessibility barrier gets the smallest fix that closes it. - **Issues and pull requests from others are for the data**: add a game (`scripts/temp_info.jsonl`), correct one (`data/overrides/`), remove one (`data/blocklist.jsonl`). The issue forms are `add_game`, `edit_game`, `delete_game`, `bug_report` and `accessibility`; blank issues are off (`.github/ISSUE_TEMPLATE/config.yml`). The About page links those five by file name, so renaming a form is a web change. - The policy is stated in `README.md` ("Project status"), `CONTRIBUTING.md`, `SECURITY.md` and the pull-request template: change them together. - **Release notes are one file per release**: `changelog/v/..x/.md`, and `changelog/beta/` for a pre-release (none so far). `CHANGELOG.md` is the index, and keeps `## [Unreleased]`, where every change writes its entry. A release moves that section into its new file (headings one level up, relative links prefixed `../../../`), adds its row to its major's table and empties [Unreleased]; what the file says below its title and back link is the GitHub release's notes. A released file is not reworded afterwards. - Every rule below still holds. Maintenance mode is when they matter most: the next change will be made by someone who has not touched the code for months. ## Data invariants — get these wrong and you corrupt the dataset - **`appid` is not a stored field.** It is parsed out of `link` with `/\/app\/(\d+)/` (`web/src/lib/data-store.ts`, `extract_appid` in `scripts/core/data_store.py`). Never add it as a column; derive it. It is ASCII digits on both sides: JavaScript's `\d` is ASCII, Python's is not, so `extract_appid` refuses a run of digits with any non-ASCII one in it (`/app/730٤` is `None`, never 730) and `normalize_link()` reads a queued line through NFKC first, which turns a Japanese keyboard's `5118700` into 5118700. A non-ASCII appid would miss every comparison and make `rotation.slice_of()` (`.encode("ascii")`) stop every refresh. - **Numeric-looking fields are formatted strings, not numbers.** `current_players: "492,197"`, `reviews: "86% (Very Positive)"`, `metacritic: "N/A"`. Parse before comparing or sorting. - **`save_main()` decides how values are WRITTEN** (`scripts/core/normalize.py`), before overrides, on every record of every write, never touching `last_updated`: - `release_date` has ONE shape, `Aug 21, 2012`. Any full date Steam writes, in either English order or any store language (`28 апр. 2025 г.`, `28 Thg04, 2025`, `2025年4月28日`…), comes out that way. Anything else (`Coming soon`, `Q1 2026`, `2026`) is kept verbatim. Steam's day/month order changes from response to response (`21 Aug, 2012` and `Aug 21, 2012` from the same client). Never store ISO: the released apps `Date.parse` the field, and `2012-08-21` parses as UTC midnight, a day early west of Greenwich. - name/developer/publisher/description lose invisible characters (ZWSP, bidi controls, zero-width watermark runs) and stray whitespace. Single ZWJ/ZWNJ and the ideographic space are spelling and stay; a developer left empty is dropped from its list. - Tags and descriptions are HTML-unescaped (`Point & Click`, appdetails' `"`), references with a semicolon only. - `notes` loses the retired browser extension's two leading phrases, `Has paid DLC` (what `has_paid_dlc` says, kept true by the store refresh) and `[hover-add]` (`clean_notes()`); a note left with nothing becomes `Not reviewed yet`, an empty one stays empty. `apply_overrides()` cleans an override's notes too, or it would put the phrase back after every normalisation and commit on every run. Every rule must stay idempotent: one that changed anything on a second pass would rewrite every shard on every run. `test_normalize.py` holds that, and `refresh_store_data.py` compares fresh values in this form. - **`MANUAL_FIELDS` are human judgements.** They are `anti_cheat`, `anti_cheat_note`, `is_kernel_ac`, `notes`, `type_game`, `safe`, `genre`. Two mechanisms protect them, and they are not the same thing: 1. *Fill-if-empty*, in `apply_details()` and `fetch_full()`: a scrape will not overwrite a non-empty value. This is weak — it cannot tell a human correction from earlier scraper output, so `normalize_genres.py --apply`, which rewrites `genre` for every game, silently reverts corrections. 2. *Overrides*, below. This is the durable one. The anti-cheat trio is the exception on purpose: `refresh_anticheat.py` REPLACES `anti_cheat`/`anti_cheat_note`/`is_kernel_ac` with what the developer declares on Steam (Pipeline, below), so for those three an override is the only way to disagree with Steam. A writer that sets manual fields on a schedule asks `OverrideGuard` first (`core/overrides.py`): a field an active override covers, or a retired entry's value, would be undone by `apply_overrides()` and bump `last_updated` on every run. One stored genre is not a judgement: a value in `NOT_GENRES` ("Free To Play", "Early Access"; `constants.py`), a price model or a release state. Until v4.6.0 the skip list matched appdetails' names case-sensitively and 1,357 games were stored with "Free To Play". `fetcher.pick_genre()` compares casefolded and never falls back to one, and Refresh Store Data replaces a stored one (`is_stray_genre()`) from appdetails, guarded like any writer. - **`data/overrides/.json` is human intent, and it is permanent.** `apply_overrides()` is called from inside `save_main()` — the single choke point through which all 15 data-writing scripts pass, and the only code that writes `data/data_*.jsonl`. An override is therefore re-imposed as the last act of every write, so it survives `refetch_all.py`, `refresh_anticheat.py` and `normalize_genres.py --apply` without those scripts knowing it exists. Add a new dataset writer and it inherits this for free — provided it goes through `save_main()`, which it must. Three rules that are not obvious: - **An override may not set a field empty.** The next scrape would refill it (fill-if-empty) and this layer would blank it again, flip-flopping shards on every run. To clear a field, *retire* the override. - **Retiring is not deleting.** Deleting the file leaves the field pinned to the human value forever, because fill-if-empty never restores the old one. A retired entry keeps `was` and writes it back once, then permanently no-ops because the values no longer match. - **`notes` is a hybrid field.** The pipeline appends its own segments to it (`MACHINE_NOTE_MARKERS`), and those appends are one-way — `mark_dead_games.py` only appends while `is_dead` is False, so a stripped marker is never re-added. `preserve_machine_notes()` re-attaches them; do not bypass it. - **`data/blocklist.jsonl` is the other kind of human intent: games taken OUT.** One line per game (`scripts/core/blocklist.py`; the Worker's twin is `web/shared/removal.ts`), written by `/admin/remove` and `scripts/delete_game.py`, READ by the pipeline. `save_main()` applies it FIRST, on every write and whatever `apply_human_overrides` says: a blocked record is left out of a NEW list (never the caller's - scripts hold indexes into theirs), so no writer can bring the game back - not a queued link, not a refetch. Rules that are easy to break: - **A drop is logged once.** `log_admin_removals()` writes `status_code: "admin_removed"` to `scripts/removed_games.jsonl`, built from the blocklist line alone with `removed_at = blocked_at`, so writing it again is byte-identical and nothing churns. It touches the file only when a row is missing. A later purge line for the same game keeps winning. `blocked_at` is whole seconds, like `now_iso()`: `dedup_removed()` compares the strings. - **More than 500 drops in one save raises before anything is written** (`BLOCKLIST_MAX_DROP`): a damaged file must fail the job, not empty the catalogue. `remove_games.py --max-drop` is the deliberate override. - **A line it cannot honour blocks nothing** (bad JSON, no `blocked_at`, an unknown reason); at save time that is one printed line in a job log - `delete_game.py --check` in `check-overrides.yml` is what makes it loud. The reasons in `blocklist.py` and `removal.ts` are held equal by a test; a code only one side knows blocks nothing. - **Never name the file `data_*`**: `save_main()` deletes shards it did not write. - **Writers append or delete whole lines**, never re-serialise the others. The line format (key order, compact JSON, U+2028/U+2029 escaped) is held byte-equal across Python and TypeScript by `scripts/tests/fixtures/blocklist_golden.jsonl`. - **Restore is the only way back**, and it is one commit: the line goes and the link is appended to `scripts/temp_info.jsonl`, so the ingest that follows cannot find the game still blocked. Deleting a line by hand leaves D1's `removed:` decision behind (discovery keeps skipping the game). - Overrides of a removed game stay, as orphans, and apply again after a restore. `ingest_new.py` skips blocked links before any Steam request, and discovery counts them as known. - **Shard assignment is unstable.** `save_main()` re-chunks the entire record list into 800-record files from scratch on every run and deletes leftovers. A game moves between `data_001.jsonl` and `data_005.jsonl` as records before it are added or removed. Never persist "game X lives in shard N". - **`data/index.json` is the client's whole cache contract.** Two fields, both computed by `_save_index()` and nothing else: - `last_updated` changes **if and only if** a shard's bytes, the shard list or the counts changed. A save that changed nothing keeps the old stamp, leaves `index.json` byte-identical, and so produces no commit (it used to force every visitor to re-download ~6 MB). - `files[].sha256` is the hash of each shard's exact committed bytes. `save_jsonl` writes with `newline="\n"` so a Windows run hashes the same LF bytes Git stores. The client will not cache a shard whose bytes do not match its entry, and the Worker caches a shard forever under that hash. Commit a shard without going through `save_main()` and every browser keeps serving pre-edit records. `scripts/tests/test_index_hash.py` pins both. - **The app reads shards PACKED; Git keeps them plain.** `/api/data/p1/data_NNN.bin` (and `removed_games.bin`) is the committed file run through `shared/data-pack.ts` at the edge: deflate-raw, then AES-GCM under a key that is PUBLIC in this repository. It is obfuscation and compression (~15% of the JSONL), never secrecy - do not call it protection, and never commit a pack: Git stays the readable source. A pack unpacks to the exact committed bytes, so the sha256 contract above is checked on the UNPACKED bytes; the pack itself is what the IndexedDB cache keeps (next bullet). The plain `/api/data/data/*.jsonl` paths must keep serving released apps (1.4.5 unversioned, 2.0.x `?v=`), which cannot unpack. Packs end in `.bin` so the zone's `.jsonl` Compression Rule never recompresses them. No WASM: installed apps' CSP has no `'wasm-unsafe-eval'`. - **The IndexedDB cache holds PACKS, never records or plain JSONL** (`web/src/lib/cache.ts`). Database `f2p-catalogue`: `f2p:index` (the DataIndex, readable - public metadata, so the generation compares without opening anything) and `f2p:records` (`Uint8Array[]`, each shard's pack exactly as `fetchShard` received it, in `index.files` order). Rules: - A generation is stored only if EVERY shard arrived packed; the browser never packs (compressing ~9.5 MB is main-thread work on a phone). A stored pack must carry its index entry's sha256 prefix as IV, or the cache is a miss. - The two key names are the ones `docs/PRIVACY_POLICY.md` lists. Renaming either is a policy edit, which reopens the consent gate. The new DATABASE is what keeps a tab still running app <= 2.1.x (which reads idb-keyval's default `keyval-store`) from handing Uint8Arrays to the page. - The legacy copy in `keyval-store` (parsed records) is read like any verified generation until the next one is written, which `delMany`s it - never `deleteDatabase`, which an old tab's open connection blocks. Look with `indexedDB.databases()` before touching it: opening a database creates it. - Records are decoded in the parser worker (`parsePack`), and only when the cached generation is actually used. A pack that will not open makes the whole generation a miss. The worker must never reply with an empty `error`: Chromium's failed AES-GCM decrypt is a DOMException with an EMPTY message, and `if (error)` once resolved a damaged pack as a shard with no records (`worker-pool.test.ts`, `jsonl-parser.test.ts`). - The worker refuses a message whose origin is non-empty and not its own (`if (e.origin && e.origin !== self.location.origin)`), replying with an error. The owner's messages arrive over the dedicated worker's implicit port with origin `""`, so `e.origin &&` is load-bearing: without it every message would be refused. The `!==` on `e.origin` is what CodeQL's `js/missing-origin-check` recognises; dismissing that alert instead does not last, because it reopens as a new alert whenever the handler moves (#3 dismissed, #20 reopened, 2026-10-03). - Obfuscation and compression (~1.4 MB stored instead of ~9.5 MB of objects), never protection - the key is public, like the wire packs'. - **`index.json` is rebuilt from scratch on every save.** `_save_index()` in `scripts/core/data_store.py` writes it from a fixed set of keys, so any key added to that file by anything else is silently dropped the next time the pipeline runs. Add a key there or not at all. (The browser-side `bumpedIndexFile()` that used to have the same flaw is gone, along with sign-in and in-app editing. The public app no longer writes anything.) - **`web/src/lib/schema.ts` mirrors `scripts/core/constants.py`.** `MANUAL_FIELDS` and the record shape exist in both, and `ANTI_CHEAT_PATTERNS` is mirrored by `web/src/lib/anti-cheat.ts` (+ the `ANTI_CHEAT_ENUM` order in `enums.ts`; `anti-cheat.test.ts` parses `constants.py` and holds them equal). Both sides match a key or a pattern only as WHOLE WORDS (`_has_term()` / `hasTerm()`): substring matching filed "space", "interface" and "FACEIT AC" under ACE. Change one, change the other. ## Pipeline - `update_data.py` only **enriches existing records**. It does not discover new games, and it skips every record `is_info_complete()` accepts - so, with `apply_details()`/`apply_scraped()` filling only EMPTY fields, a complete record's store data was never looked at again. - **`refresh_store_data.py` is what refreshes it** (daily, "Refresh Store Data"). A game is due when `crc32(appid) % cycle == day % cycle` - store page (tags, languages, `language_details`, `has_paid_dlc`) every 7 days, appdetails (name, header image, description, developer/publisher, release date, platforms, Metacritic, DRM notes) every 30. Never `appid % cycle`: appids are mostly multiples of 10, which leaves most slices empty. A cycle grows with the catalogue instead of the run (`rotation.cycle_for()`: past `PAGE_DAILY` 2,000 pages or `DETAILS_DAILY` 500 appdetails a day it becomes 14, 21, ... or 60, 90, ...) and is always a MULTIPLE of its base, so a game keeps its weekday and its day of the month and visits only ever thin out. The slice is visited in `rotation.daily_order()`, so a run that meets its time budget leaves a different tail each day. It replaces values only with NON-EMPTY ones, never writes `MANUAL_FIELDS` or `notes` - except a stray genre (above), read from appdetails every day, first after the page repairs, at most `GENRE_DAILY_CAP` a day, and left alone under an override - trusts `has_paid_dlc` only from a real store page (an age gate has no language table or tags) or a gated game's DLC prices, compares every value as stored (normalised, `description` truncated - and a blurb merely cut off somewhere else is written without counting as news: later, now that `"` is one character, or earlier, at a CJK sentence end since v4.6.0; `_fuller_cut()` takes two cuts of one text, never a rewrite), and bumps `last_updated` only on a real change. A game with empty tags, languages or `language_details` is in the page group EVERY day, first, capped at `MISSING_DAILY_CAP`; `--missing-only` runs just those. A game whose appdetails no longer call it free is LISTED in a `::warning::`, never written: purge removes a game only when the store API flags it too, and this is where the opposite case shows. A new field added to it must obey the same rules; `scripts/tests/test_refresh_store_data.py` holds them. - **A store page behind Steam's age gate is never parsed.** An 'Adult Only' game goes `/app// → /agecheck/app// → /login/?redir=…`, 200 at the end, and no cookie opens it (measured 2026-10-10). Read as a page, the gate had no languages, no tags and no DLC section: 25 games sat empty and every one had `has_paid_dlc=false`. `fetch_store_page_full()` classifies the whole redirect chain, and returns HTML only for the game's own page. Pages are fetched with age cookies (`STORE_AGE_COOKIES`, for the M-rated games the US runners were gated on), and the cookies go with store-page requests ONLY, so discovery's search results are unchanged. `fetcher.scrape_store_fields()` is the one path both `fetch_full()` and the refresh use. For a gated or redirected game it reads `IStoreBrowseService/GetItems`, which is keyless: tag ids are named by `IStoreService/GetTagList`, language ids by the tables in `core/store_items.py`, and an unknown id is skipped, never stored. It reads `has_paid_dlc` from the prices of the DLC appdetails lists. `None` means unknown and leaves the stored value. Never use a Steam login cookie in CI; it would expire silently, like the PAT did. appdetails is always asked with `l=english`: without it, a runner was once answered in Russian. - **`all_time_peak` only ever goes UP, and `refresh_peaks.py` is what raises it** (daily 19:30 UTC, "Refresh All-Time Peaks"). A `crc32(appid) % 30` slice (`core/rotation.py`, shared with `refresh_store_data.py`; 60, 90, ... past `PEAK_DAILY` 400 pages a day, never shorter) reads SteamCharts' recorded all-time peak - the only source older than our own sampling: SteamDB forbids scraping and Valve's APIs know only today. Every run also raises it from our samples (`peak_today`, which despite its name is never reset, only cleared by `refetch_all.py`, and `current_players`), and `apply_players()` raises it on every sample, never from a 0. SteamCharts has no API, terms or robots.txt, so: one page per game a month, 2-3 s apart, a User-Agent that names the project; 500 is an app it does not track (most of the long tail), 404 one it has never seen; a 403, 429 or challenge page, or the job's time budget, stops the run with a warning, not a failure. `refetch_all.py` must never clear the field - it cannot be fetched again - and nothing may lower it. The backfill is a manual run with `backfill` ticked (~4 h, start it in the evening UTC). DISCLAIMER section 6 names the source, so rewording it reopens the consent gate. `scripts/tests/test_refresh_peaks.py` holds the rules. - **Anti-cheat is what the developer declares on Steam, and `refresh_anticheat.py` re-reads it for EVERY game daily** (end of the Refresh Store Data job, its own commit; `only: anticheat` runs just it). Until v4.3.1 only the browser extension read the disclosure, so the 4,704 games added after it stopped (2026-06) had none. Steam shows it in two places (measured 2026-10-16, `core/anticheat.py`): `IStoreBrowseService/GetItems` with `include_extra_details` gives `extra_details.anticheat` (`kernel_mode`, `boot_protection`, `name`; false booleans omitted, `{}` = not kernel, no key = no disclosure), keyless and for gated games too, but with only Steam's own product names; the store page has one `div.anticheat_section` whose HEADING (`Uses Kernel Level Anti-Cheat` / `Uses Anti-Cheat Software`) decides kernel - never the class, `DRM_notice` also marks boot protection - with a `div.anticheat_name` per row; a `Boot Protection` row is not a product. The sweep asks GetItems for all games (~160 requests) and reads a page only for a disclosure without a name. Rules: Steam wins (another product or kernel flag is REPLACED, compared with `same_family()`, so "EAC" = "Easy Anti-Cheat"); an override wins over Steam and is never fought (`OverrideGuard`); NO disclosure never clears anything (Warframe, Overwatch 2, NARAKA declare none); a failed GetItems batch is unknown, never "none"; a disclosure with no name anywhere writes nothing. `fetch_full()` fills (never replaces) from the page it already fetched, else appdetails' VAC category. Labels are `ANTI_CHEAT_PATTERNS` keys, else Steam's name (cut at 40 characters); notes `" [Kernel]"` / `"[Non-Kernel]"`. Adding a key never rewrites a stored label: the old raw name and the new key are the same family, and a known label stays as it was written (so "Easy Anti-Cheat" and "EAC" both occur; the site groups them). `scripts/tests/test_anticheat.py` and `test_refresh_anticheat.py` hold it. - **Reviews are Steam's own summary, read for EVERY game daily** (`update_reviews.py`, "Update Reviews" 06:00): `GetItems` with `include_reviews`, fifty games a request (`SteamClient.fetch_items()`, the sweep the anti-cheat and purge jobs share), ~2 minutes. It asked `appreviews` one game at a time until v4.4.0 and, at 9,800 games, ran into GitHub's six-hour limit with nothing saved. Rules: the percentage is Steam's, FLOORED (`reviews_from_summary()` floors appreviews in integers too, so an ingest and the refresh agree; until v4.4.0 it was rounded, one point higher on ~40% of games); a GetItems count of 0 never replaces a percentage - its summary has said 0 for a game with thousands (845070) - so such a game is asked on appreviews (`ASK_CAP` 300 a run, daily order) and keeps its value when that gives no answer; "N/A" (never read) with a count of 0 becomes "No reviews"; no item, no usable summary or a failed batch keeps the value. **appreviews has answered with a 302 to the store front since 2026-10-23** (from here and from GitHub's runners; it worked on 10-17), so `fetch_full()` falls back to the same GetItems summary (`reviews_from_store_api()`) and an ingest no longer leaves "N/A". A record's `last_updated` moves on a change and on a HEARTBEAT: a game read whose stamp is 14-20 days old (crc32 jitter) is stamped again. The site calls a record older than 30 days stale (`web/src/lib/validation.ts`, `/health`), and this job used to stamp every game on every run; the heartbeat keeps "the pipeline confirmed this lately" true without rewriting every record daily. `scripts/tests/test_update_reviews.py` holds it. - **A game is purged only when two of Steam's answers agree** (`purge_unhealthy.py`, "Purge Unhealthy Games" daily 07:00). GetItems screens the whole catalogue (`store_items.screen_item()`: unknown to Steam, `visible` false, `unlisted`, `release.is_coming_soon`, no `is_free`; never `type` - a free mod is listed on purpose), and `check_game_health()` (appdetails) must confirm each flag. An `unavailable`/404 answer is asked again `RECHECK_AFTER` (5 min) later: appdetails answered `success:false` for 14 live games in two bursts on 2026-09-27. A failed batch or a network error is never "gone"; blocklisted games are not asked about. More than 500 flags or 100 confirmed removals exits non-zero BEFORE anything is written (`--max-candidates`, `--max-removals` to override). Removals are logged to `removed_games.jsonl` exactly as before - `reconcile.ts` reads them. A `::notice::` names earlier removals GetItems now sees free, listed and released (re-queue the link to bring one back: a purged game keeps its D1 decision and discovery never proposes it again). Check Dead Links is gone: HEAD on a delisted app's page ends on the store front with 200, so in its whole life it never found a dead link, and it took 5.5 hours. `scripts/tests/test_purge_unhealthy.py` holds it. - `ingest_new.py` only reads `scripts/temp_info.jsonl`, and a line is a store LINK and nothing else: every other key is ignored and the game is built from Steam (`merge_extension_data()` went with the archived browser extension; it let one queued line decide any field). The producer is `/admin` (the Worker appends via `createCommitOnBranch`: a reviewer's approvals, an auto-approve batch, a Restore), plus a link a pull request adds. The issue-template, Telegram and extension paths were removed. Writers APPEND; anything that overwrites this file destroys whatever another queued. It skips a blocklisted link before any Steam request, and rejects anything appdetails calls other than `type: "game"` (`status_code: not_a_game` in `removed_games.jsonl`) - the check that makes auto-approve safe, and why a queued link cannot add a free DLC, demo or tool. The check lives in ingest only: in `health_checker` it would make Purge delete old records every day. - **`ingest-new.yml` is also the removal job.** `bash/ingest.sh` runs `remove_games.py` (applies `data/blocklist.jsonl`) and then `ingest_new.py`, and commits once ("Apply removals" when `temp_info` did not change), so one commit to either file starts one run that settles both. The workflow checks out `ref: main`, not the triggering SHA, like every data-write workflow: a run that waited its turn would otherwise work on the data as it was when it was queued. It has no time budget: `clear_temp()` empties the whole queue file, so a game it had not reached would be lost. - New games ARE discovered automatically now, by `scripts/discover_new.py` into the D1 review queue — but discovery only PROPOSES. Publication is decided in `/admin`: by a reviewer, batch by batch, or by the auto-approve rule a reviewer turned on there (off by default, at most 500 a day). Either way it is a REQUEST in `temp_info.jsonl` that `ingest_new.py` still checks game by game. - **Discovery takes games in every language** (since v4.6.0). The store search (`SteamClient.fetch_search_page()`) sends no `supportedlang`; pinned to english it left out 1,592 of 18,790 free games (2026-10-30), mostly Chinese, Japanese or Korean only, and without it Steam filters on no language at all. Rules that are easy to break: - The search sends `l=english`. It fixes the language of the row TEXT, never which rows come back: discovery skips a row whose release reads "Coming soon" and the backfill parses English month names. - Every other request still asks Steam in English, so tags, genre, language names, review labels and dates stay English; a name or description the developer never wrote in English stays in their script. That is the record, not a parsing error. - A candidate's payload carries `languages` (appdetails' `supported_languages`, read by `appdetails_languages()`), which `/admin` shows with a "No English" badge. Auto-approve treats such a game like any other. Rows queued earlier have no list: the Worker never rewrites a queued row's `payload_json`. - Both workflows' guard step greps the two discovery scripts for `save_main|save_jsonl|clear_temp|fetch_full` as WORDS, comments and docstrings included: none of the four may appear in them at all. - The `discovery` group queues (`queue: max`) in both of its workflows, so backfill windows dispatched together wait in turn instead of cancelling each other; `pipeline.test.ts` holds a group to one setting. - A game that declares no language (29 of them) has empty `languages` once ingested: Refresh Store Data's repair group takes it every day and the admin Quality page flags it. Accepted. - **Auto-approve (`worker/lib/auto-approve.ts`, run by the cron after reconcile) commits a batch only when every gate says yes**, and a gate it cannot evaluate says no: enabled (or "Run one batch now"), its D1 lease, today's budget (`min(dailyLimit, AUTO_DAILY_CEILING)` - the 500 is in code and re-applied to whatever is stored, reserved with `bumpCounter` BEFORE the commit and given back if it fails), `temp_info.jsonl` on `main` EMPTY, no `data-write` workflow running or waiting, and something eligible (the SQL the page previews is the SQL that runs). The empty-file gate is checked again inside the commit (`requireEmptyQueue`), so a batch never lands mid-ingest; "no row is approved" would have stalled it for the 12 hours a skipped row stays approved. The idle gate dates from when a push while a data job waited EVICTED that job; with `queue: max` the ingest would only queue behind it, and the gate stays so a batch lands when its ingest can start at once. `shared/pipeline.ts` lists every `data-write` workflow by file, and `pipeline.test.ts` fails when a workflow joins the group without joining the list. Settings, limits and their validation are `shared/automation.ts`, imported by the Worker and the page. A scheduled batch's D1 actor is `auto-approve`; a failure is audited once per distinct cause, not every 15 minutes. - **Removing a game is a blocklist line plus D1, and Restore is its exact inverse** (`worker/routes/remove.ts`, ≤100 per request, both under the `blocklist` lease). The Worker may write `scripts/temp_info.jsonl`, `data/overrides/*.json` and `data/blocklist.jsonl` (`WRITABLE` in `git-commit.ts`) - never a shard or `index.json`. Remove sets the game's decision to `rejected`, reason `removed:`, even over `approved`, and every row for it that is not rejected to `rejected`: a leftover `committed` row would keep `publishedSql()` true, and the game locked, forever. Removing an already-blocklisted game commits nothing and re-applies D1, which is how a desync is repaired. Reopen refuses a `removed:` rejection (409, `removed`). Restore drops the line and queues the link in ONE commit, deletes only a `removed:` decision, and enters an approved row (source `restore`) for reconcile to promote - or to age to `failed`, which can be approved again. Name and link come from the catalogue, read server-side and sha256-checked per shard (`readCatalogue()`), never from the request. - **Queue rules live in `web/shared/queue-rules.ts`, imported by the Worker AND the admin UI.** A row is read-only when its status is not decidable (`approved` = the request is committed to Git, `committed` = the game was observed in `data/`, `rejected`) or when its GAME is already published (a committed row or an approved decision for the appid — per game, because one appid can have several rows). `/admin/api/decide` refuses such rows in its read AND in every UPDATE's WHERE, and returns each refused id in `skipped` with a reason; it never drops one silently. `queue-rules.test.ts` parses `0001_init.sql` so the constants cannot drift from the CHECK constraint or `uq_queue_open_appid`. - **`reconcile.ts` is still the only writer of `ingest_decisions('approved')`,** and it now also sweeps: a pending/deferred/failed row whose appid is in `data/` becomes `committed`, replacing a stale `rejected` decision. It holds a D1 lease (`admin_locks`) and skips the ~6 MB fetch while `data/index.json`'s generation is unchanged (`admin_state`). Migration `0002_admin_state.sql` is applied by hand, so `lib/locks.ts` treats a missing table as "unavailable" and every caller falls back — deploy order must never matter. Keep it that way for any future migration a Worker change depends on. - **Nothing `/admin` writes to Git may name a person.** Commit bodies, `data/overrides/*.json` and `data/blocklist.jsonl` lines say `ADMIN_ATTRIBUTION` ("admin", `web/shared/admin-api.ts`); a public repository keeps them forever. A removal's reason and note are public too, which the page says before anyone types one. `appendLinks()` takes no actor parameter at all, so the old `Approved in /admin by ` cannot come back by a call site forgetting. D1 still stores the real Access identity in `audit_log.actor`, `ingest_queue.decided_by`, `ingest_decisions.decided_by` and `commit_jobs.requested_by`, which is what `/admin/audit` filters on — do not "tidy" those to the constant too. - **`BLOCKED_COUNTRIES` is defence in depth, not the block.** The Worker refuses those countries (`worker/lib/geo.ts`), but it only ever sees the four `assets.run_worker_first` prefixes — every prerendered page is served without invoking it. A WAF custom rule on the zone is the boundary (`blocked-countries`, live since 2026-09-20; `docs/SECURITY_SETUP.md` §4, which also carries the `human-check-pages` Managed Challenge and every path it must keep excluding). `geo.ts` FAILS OPEN on an unknown country: `request.cf` is undefined under Vitest and under `wrangler dev` without `--remote`, and failing closed there 403s every test. - **Rate limiting has two layers, and the WAF rule is the first.** The zone's one Free-plan rate-limiting rule (IP, 10 s, Block 10 s; `docs/SECURITY_SETUP.md` §3a) refuses a burst before the Worker is invoked, and is the only limit on the prerendered pages. `worker/lib/rate-limit.ts` is the second: the `ratelimits` bindings in `wrangler.jsonc`, 60-second windows, one budget per surface (`RL_DATA`, `RL_IMG`, `RL_API`, `RL_HUMAN`, `RL_ADMIN`), keyed by IPv4 address or IPv6 /64, checked after the country block and before every route and the Access check, answering 429 with `Retry-After: 60`. Rules: - It FAILS OPEN (no binding, no `CF-Connecting-IP`, a throwing `limit()`). Vitest and `admin/mock` bind no limiter, which is why no other test sees it; the catalogue must never fail to load because of this layer. - Counts are effectively PER SERVER, whatever the docs say about "per location" (measured 2026-10-27, SIN): over one keep-alive connection a budget held exactly (121 then 429), with a new connection per request it refused nothing (175 human checks in 70 s against 20). So it stops browsers and connection-reusing scripts; a client that reconnects every time is the WAF rule's (which counted exactly 250). A limit is an abuse ceiling far above any client (a cold catalogue load is ~16 data requests), never a quota to tighten. Test it over ONE connection (`SECURITY_SETUP.md` §3b), or it looks broken. - Refusals are not logged: Workers Logs has the 429 status, and a line each would double a flood's log volume. - A 429 carries CORS only where its route does (`data`, `api`), never on the human check or the admin surface. - Every `period` stays 60 (the Retry-After), and a `namespace_id` is unique in the ACCOUNT - another Worker reusing one shares its counters. A new `run_worker_first` prefix needs a class, and a new binding needs its line in `worker-configuration.d.ts`. `rate-limit.test.ts` holds the periods, the namespaces, the binding names and the prefix coverage. - `audit_log` and `commit_jobs` are pruned daily after `ADMIN_RETENTION_DAYS` (wrangler.jsonc, 180). `docs/PRIVACY_POLICY.md` states the number: change both together. `ingest_queue` and `ingest_decisions` are never pruned — the decisions are what keep a rejected game out of the discovery sweep. - **Every workflow that writes to `data/` shares `concurrency: {group: data-write, cancel-in-progress: false, queue: max}`, checks out `ref: main`, and declares `timeout-minutes`.** `pipeline.test.ts` fails on a data-write workflow without any of them. A new data-writing workflow outside the group would race the others. - `queue: max` (GitHub, 2026-05-07) keeps up to 100 runs waiting, first in, first out. The default keeps ONE: a run queueing behind a running job cancelled the one already waiting - Update Reviews lost five of ten runs that way in October 2026. Mixing the two settings in one group is undocumented, so every member has `queue: max`. - `ref: main`: a run's commit is fixed when the run is CREATED. A scheduled run that waited behind another data job wrote shards from before that job's commit, and `commit_push.sh`'s rebase then conflicted on `data/index.json` - Auto Update JSON failed four days in ten that way. - Scheduled runs start up to an hour after their cron (2-5 hours in September). Waiting costs nothing now, but a long new job still goes where nothing long runs (Refresh Store Data is at 16:00 for that reason). - **Every long loop has a time budget** (`scripts/core/budget.py`). The workflow sets `JOB_BUDGET_MINUTES` at least 20 below its `timeout-minutes` (`pipeline.test.ts` checks); past it a loop starts no further game, the script saves what it did and the job commits it, and a loop that used more than three quarters says so in a `::warning::`. Loops visit their games in `rotation.daily_order()`, so a cut falls elsewhere the next day. A job stopped at its timeout commits nothing and concludes `cancelled`, which `notify-ci-failure.yml` (a reusable workflow in `poli0981/.github`) does not report: the budget is what keeps a growing catalogue from failing silently. `process_batch(pause=False)` for the keyed Web API (player counts); the 15-30 s rest between batches stays for store pages and appdetails. Never a budget for `ingest_new.py`. `refetch_all.py` runs in parts (`--part K/N`) and clears each game on a copy that replaces it only once appdetails has answered, so a cut part leaves every other game as it was. - **Every data job commits through `bash/commit_push.sh`.** The group serialises workflows, not `main`: a merged PR or an /admin commit can land during a long job, and a bare `git push` is then rejected and the run thrown away (purge-unhealthy, 2026-09-21). The helper rebases onto `origin/main` and retries; none of those writers touch the shards, so the rebase is clean. A new wrapper must use it, once per commit (Refresh Store Data commits twice: the store refresh, then the anti-cheat sweep). - Workflows push with the built-in `GITHUB_TOKEN`; each declares `permissions: {contents: write}`. Do not reintroduce a PAT — a PAT expiring silently is what stalled the pipeline for a month in 2026. - **CI installs only what is pinned, and runs no dependency's install code.** These jobs hold a write token, and the release jobs the signing keys. - Third-party actions are pinned to a commit SHA with the version in a comment (`@ # v2.9.2`), which Dependabot's github-actions updates keep current. `dtolnay/rust-toolchain` is pinned to a MASTER commit and given `toolchain: stable`: its other branches are regenerated on top of master, so a commit of `stable` can vanish. GitHub's own actions (`actions/*`, `github/*`) and `poli0981/.github` stay on tags. - Every `npm ci` is `npm ci --ignore-scripts`, and no workflow uses `npx` (`npm run cf:check`, `npm test -- `). Only fsevents, workerd and wrangler's esbuild have install scripts, and none is needed: the last two find their binary in their optional platform package anyway. A new dependency whose install script IS needed breaks the build here - which is the point; decide then, do not drop the flag. - `requirements.txt` pins every package the pipeline installs, transitive ones included, with the sha256 of every file on PyPI, and every install is `pip install --require-hashes --only-binary :all: -r requirements.txt` (bash/*.sh and the workflows that run Python). Hash mode is all-or-nothing per pip call: `requirements-test.txt` (pytest and pytest-cov, hashed the same way) goes in its own call in `python-tests.yml` and `sonarcloud.yml`, which run the pipeline's line first so a Dependabot bump is proven before a data job meets it, and `requirements-dev.txt` (unhashed local tools) is installed on its own. Adding a package means adding it and its dependencies with hashes: `uv pip compile --universal --generate-hashes --python-version 3.15`. - **One version of each runtime, and a test that holds them together** (`web/shared/toolchain.test.ts`; web-ci also runs on `.github/workflows/**` and `sonar-project.properties` so a pull request that only moves a pin meets it). `docs/plan/16-toolchain-2026.md` has the upgrade notes. - Node is the major in `web/.node-version` (26). Every `setup-node` repeats it as a quoted literal, never `node-version-file`: `release-android.yml` checks out the tag it rebuilds, and older tags have no such file. `engines.node` and the `@types/node` major follow it. Workers Builds reads the dashboard variable `NODE_VERSION=26`, the one copy the test cannot see (`docs/DEPLOYMENT.md`): change it with the file. - Python is the `python-version` of every `setup-python` (3.15), repeated by `sonar.python.version` and the `--python-version` above. `codeql.yml` alone stays on the newest Python CodeQL lists (3.14), named in the test's `PYTHON_EXCEPTIONS`. A version is always quoted: YAML reads 3.10 as 3.1. - Python 3.15 makes `open()` default to UTF-8 everywhere (PEP 686), but every text open in `scripts/` still names `encoding="utf-8"`: on Windows an older Python writes the locale's code page, and cp1252 cannot encode the leaderboards' emoji. - **SonarCloud analyses in CI (`sonarcloud.yml`), and its scope is `sonar-project.properties`.** Automatic analysis is OFF in the project's Administration > Analysis Method and must stay off: while it is on, every CI scan fails. The scanner reads the file from the commit it analyses. Code and tests both start at the root and are split by patterns: a new test-helper folder goes into `sonar.test.inclusions` AND `sonar.exclusions`, or it is analysed as code (and a file both include fails the scan). It leaves out the dataset, generated Android resources and the SQLite migrations (the PL/SQL analyser reads them as Oracle). `sonar.typescript.tsconfigPaths` names all six tsconfigs in `web/` (auto-detection finds only files named exactly `tsconfig.json`), and the job runs `npm ci --ignore-scripts` and `npm run build:admin` (which syncs SvelteKit) first: `web/tsconfig.json` extends the generated one, and without it the analyser logged "Failed to parse tsconfig" and read `web/src` untyped. A new tsconfig joins that list. The job skips commits that touch only what the data jobs write, and its `scan` job is skipped when `SONAR_TOKEN` is not available (forks, Dependabot). **Coverage is measured there, not in the test workflows.** The job runs pytest with `--cov` (`[tool.coverage.run]` in `pyproject.toml`: `scripts/` without its tests, relative paths, `coverage.xml` at the root) and `npm run test:coverage` (`test.coverage` in `web/vite.config.ts`: lcov with `projectRoot: ".."`, so the paths start `web/`). Both reports are named in `sonar-project.properties`; a path that does not resolve from the repository root is silently uncovered. Coverage is off for a plain `npm test`. The default "Sonar way" gate wants 80% on new code, and SonarCloud counts every executable line a report does not name as uncovered: without the reports `main` read 0.0% and failed it (2026-10-22). Suppressing a rule for a file is done in the SonarCloud UI, not in this file or with NOSONAR. - **Qodana analyses in CI too (`qodana.yml`), one Qodana Cloud project and token per linter**: `qodana-python` over `scripts/` (`QODANA_TOKEN_PYTHON`), `qodana-js` over `web/` (`QODANA_TOKEN_TS_JS`), `qodana-rust` over `web/src-tauri/` (`QODANA_TOKEN_RUST`), the setup free-games-itchio-list uses. Each project's settings are the `qodana.yaml` in its directory, with a gate of zero problems (`failureConditions`): a new finding fails its job, so fix it, or exclude the inspection there WITH its reason. All three need an Ultimate licence (a trial in November 2026; the Rust linter is Early Access): when it ends every job fails on it - renew, or delete `qodana.yml` and the three `qodana.yaml`. What the first runs cost: - Native `qodana-python` finds no interpreter by itself (`SDKs.json` empty, then every `dict[int, str]` and `X | None` is an "invalid type hint"): the job builds `.venv` and passes `QODANA_PYTHON_PATH`. `scripts/` is the project directory because `core` resolves only there. - The `qodana-rust` image has no C linker and none of Tauri's libraries, and runs as the runner's user ("Analysis scope: 0 packages", a Critical "Cargo project loading"): `-u root -e CARGO_HOME=/data/cache/cargo`, a `bootstrap` that installs the packages, and a stand-in `web/dist/index.html` so `generate_context!()` expands. It calls `serde_json` unused; the expansion needs it (`::serde_json::Value`). - `qodana-js` runs in Docker, not native: a `plugins:` entry (the Svelte plugin, without which no `.svelte` file is read) fails to install in native mode with every released CLI up to 2026.2.3 (QD-16701). With it, every `@lucide/svelte/icons/*` import reads as unused, so `ES6UnusedImports` is off (`noUnusedLocals` covers it). - A subdirectory project needs `--project-dir --repository-root .`, and each job its own cache keys (the default is one key per run). The SARIF and logs are the `qodana-report-*` artifact, a zip inside the artifact; `gh run view --log` is empty until the whole run has ended. ## Frontend gotchas - **Never pass a theme name to `echarts.init()`.** `echarts/core` ships no registered themes. Under echarts 6 an unregistered theme name silently stops every series from painting — axes and legends still draw, so charts look "empty" rather than broken, and nothing is logged. Charts set their own colors from the design tokens; see `web/src/lib/charts/echarts.ts`. - **A chart that initialises but paints no canvas looks identical to that bug and usually is not.** In Svelte 5 a value an `$effect` must react to has to be `$state`: a plain `let chart` meant the setOption effect ran once while it was still undefined and never re-ran. See the comment in `web/src/lib/charts/EChart.svelte`. - **zrender's wheel listeners are forced passive during `echarts.init()`.** It binds both `wheel` and `mousewheel` with no options object, unconditionally and regardless of `dataZoom`, which blocks scrolling over every chart — they sit inside the page's scroll container. `EChart.svelte` swaps `addEventListener` for exactly the duration of that one call. A passive listener cannot `preventDefault()`, so `dataZoom: {type: "inside"}` and `roam: true` would silently stop working; `charts.test.ts` fails if either appears. - **Scrollbars are themed by `scrollbar-slim`, never Tailwind's `scrollbar-thin`.** Tailwind 4.3 ships a core `scrollbar-thin` (a plain `scrollbar-width: thin`), and in Chromium 121+ any standard scrollbar property switches `::-webkit-scrollbar` off for that element - which is why every panel showed the OS's grey bar while the page bar was themed. `styles/theme.css` gives Firefox `scrollbar-color` (only where `::-webkit-scrollbar` is unsupported) and everyone else the pseudo-elements; the two must never meet on one element. The reader's "hide scrollbars" choice (Settings, `f2p:scrollbars`, ``) only reaches containers marked `.scrollbar-panel` or `.scrollbar-page`; a new scroll container takes one of them. Dialogs and the legal documents stay unmarked on purpose. `src/lib/scrollbars.test.ts` holds all three rules. - **Every layout grid declares its base column count:** `grid grid-cols-1 gap-2 sm:grid-cols-2`, never `grid gap-2 sm:grid-cols-2`. Below the first breakpoint the latter has one implicit `auto` track, as wide as its widest item's min-content, and a `truncate` name counts at full length there (the grid ITEM keeps `min-width:auto`, whatever `min-w-0` the span inside has). One long studio name pushed every card on /publishers past a phone's edge, and the dashboard lost its "View all" links and counts. A chart in such a grid makes it stick: zrender gives its root a pixel width, which becomes the track's minimum, so the chart can grow and never shrink back. `grid-cols-N` is `repeat(N, minmax(0, 1fr))` and cannot do either. Rows of fixed-width columns plus a `Badge` (which cannot shrink below its longest word) squeezed game names to nothing at 360px the same way - hide the extras below `sm`. `src/lib/mobile-layout.test.ts` fails on a grid without a base `grid-cols-N`. - **The Android app draws edge-to-edge, and the UI pads for it with `env(safe-area-inset-*)`.** targetSdk 36 and `enableEdgeToEdge()` put the webview under the status bar and the navigation bar. The shell root carries `pt-safe pl-safe pr-safe`, `
` `pb-safe`, the drawer `pt-safe pb-safe` and full-screen overlays `p-safe-or-4` (utilities in `styles/theme.css`). The React shell padded all four sides; the SvelteKit rewrite dropped three, which is how the top bar of every 2.x app sat under the clock. The status-bar ICONS follow the SYSTEM theme (`SystemBarStyle.auto`), not the one chosen in Settings, and the app defaults to dark - so the layout puts a `status-bar-strip` behind them, in the Android app only, keyed on `prefers-color-scheme` and never on `.dark`. The WebView reports the insets only from Android System WebView 136; an older one reads 0 and the top bar is under the clock again (the cure is a WebView update, or a native inset listener in `MainActivity`). `mobile-layout.test.ts` holds the shell and the strip's two colours. - **The Android app opts out of Auto Backup** (`android:allowBackup="false"` in `gen/android/app/src/main/AndroidManifest.xml`, from 2.2.1). Unset, it defaults to true, and Android copied the WebView's storage - consent, settings, the cached catalogue - to the user's Google account, while `docs/PRIVACY_POLICY.md` says none of it leaves the device. Fix the app, not the policy: a policy edit reopens the consent gate for everyone. Device-to-device transfer on Android 12+ still carries the data, which is the user's own copy between their own phones. - **Every chart colour must be one zrender can parse, which is stricter than what a canvas paints.** zrender splits `hsl()` on commas: space-separated `hsl(38 94% 60%)` paints, but every hover state derived from it comes back `undefined` and the hovered tile/bar/slice loses its fill; `hsl(var(--x))` never paints at all. Take colours from `chartTheme()` (it converts the bare channel tokens), never write `var(--…)` in an option, and use `gridBox()` rather than `containLabel`, which in echarts 6 leaves axis NAMES out of the layout. An option key whose component is not registered in `echarts.ts` (`markLine` was) is silently ignored. `chart-colors.test.ts` and `charts.test.ts` hold all three. - **A duplicate key in a keyed `{#each}` THROWS in a production build** — Svelte 5 does not only warn. The command palette crashed on open because one path was in two nav lists, and five records repeat a developer name. Deduplicate anything data-derived before keying on it. - **Use `resource.pending`, never `loading && !data`, to choose between a loading state and the page.** `loading` is false before a load starts — during prerender and until consent — so the old check prerendered empty states ("No game matches these filters.") as page content. Likewise no count may be interpolated into a `` description: at build time it is 0. `web/scripts/verify-dist.mjs` fails CI on either, and on any `{{placeholder}}` left in the HTML. - **i18n keys are literal.** `t(\`detail.${key}\`)` is how a suffix key rendered as a field label; `i18n.test.ts` rejects template-literal keys, a literal call that omits a `{{variable}}` its text needs, and any key-shaped string that does not resolve. Put key tables in code as literal strings. - `echarts-wordcloud` declares a stale `echarts@^5` peer. It runs fine on echarts 6 (all the legacy APIs it uses are still exported), so `package.json` carries an `overrides` entry. Do not "fix" it by pinning echarts back to 5. - `runed` 0.35 (bits-ui's) declares an optional `@sveltejs/kit ^2.21.0` peer, which npm enforces once kit is installed, so `package.json` overrides it to our kit. bits-ui uses none of runed's kit code (`useSearchParams`, the only part runed 0.38 changed for kit 3). Drop the entry once bits-ui depends on runed >= 0.38. - **SvelteKit 3 takes its options from its Vite plugin.** They are `sveltekitConfig(tauri)` in `web/build/sveltekit-config.ts`, which `vite.config.ts` passes as `sveltekit(sveltekitConfig(IS_TAURI))`; `sveltekit-config.test.ts` holds both flavours. `svelte.config.js` is refused (the build stops while the file exists), and what was `kit.*` there is a top-level option (`adapter`, `csp`, `paths`, `prerender`). Rules that are easy to break: - **`$lib` is gone; `#lib/*` is package.json `imports`.** A module import names `.js` even for a `.ts` file (`#lib/utils.js`), a component its `.svelte`. `tsconfig.json` repeats the mapping in `paths`, because `svelte-check --tsgo` redirects `.svelte` imports to the declarations it emits only through `paths`: without it every `#lib` component fell back to the `*.svelte` shim - props unchecked, no error. - **`src/params.ts` is imported by Node itself** (`vite build` uses `import()`, not Vite), so it and what it imports (`lib/legal.ts`, `lib/schema.ts`) name real `.ts` files and stay type-strippable; a `.js` or extensionless import there is ERR_MODULE_NOT_FOUND at build time. - **The PWA is `build/pwa.ts`**: vite-plugin-pwa wired into kit 3's `buildApp`. @vite-pwa/sveltekit never supported kit 3; it wrote the worker when the SERVER build closed, which kit 3 does first. Ours writes it in a default-order `buildApp` hook placed after `sveltekit()` - after kit's build-and-prerender, before the adapter's `post` hook copies `.svelte-kit/output/client` into `dist/`. Placed before `sveltekit()`, it would glob an empty output. - `goto` options are `replace` (not `replaceState`), `reset: false` (not `noScroll`/`keepFocus`, which THROW in dev) and `refreshAll` (not `invalidateAll`); `/games` writes its filters with `goto(url, {shallow: true, replace: true})`. `goto` rejects a URL that matches no route. - Hook types come from `@sveltejs/kit/hooks`. The client `handleError` gets `{kind, error, event}` for every error and returns nothing to keep kit's own status and message. - `version.pollInterval` is kit's default (an hour), and kit also checks `/_app/version.json` whenever the tab regains focus. A new version only sets `updated.current`; a navigation that then fails reloads natively. - **miniflare pins undici EXACTLY**, so an undici advisory in `npm audit` waits for a wrangler whose miniflare pins the fixed version. undici runs only in local tooling (`wrangler dev`, `cf:check`), never in the deployed Worker. A bridging override (`"miniflare": { "undici": "^x" }`) goes in the same commit that takes wrangler to such a release - left behind, it would hold undici on its major after miniflare moves on. The one for GHSA-xjj6-f33q-929c went with wrangler 4.156.0 (`npm ls undici`: 7.30.1, miniflare's own pin). - **The `"workbox-build": { "glob": "^14.0.2" }` and `"filelist": { "minimatch": "^11.0.1" }` overrides close GHSA-3g3m-2fjr-6pw4 and GHSA-g3hv-75wg-m249** (2026-10-30), fixed only in the new majors. workbox-build 7.4.1 asks glob `^11` and calls only `globSync(pattern, {cwd, follow, ignore})`, which glob 14 keeps; its one break that could touch us, an `ignore` starting with `/`, matches nothing in `vite.config.ts` or `build/pwa.ts`. The precache was compared URL by URL before and after (172 = 172). filelist is reached only through ejs's CLI (`ejs` → `jake` → `filelist`); the off-main-thread plugin calls `ejs.render`, which never loads jake. Delete each override once `npm ls glob minimatch` shows no version below the fixed one without it. `deepmerge` (GHSA-gcqx-w48m-w2h4, low) has no fixed release at all; it merges our own Vite/rollup config at build time, and its alert is dismissed as tolerable risk. - **TypeScript is two packages, on purpose.** TypeScript 7 (the Go compiler) has no JavaScript API, and svelte-check and `svelte-kit sync` (route `$types`) need one, so `typescript` stays 6 and 7 is the alias `@typescript/native` (`npm:typescript@~7.0.x`). svelte-check `--tsgo` finds 7 by that name and runs its bin; the `tsc -p` steps call `node node_modules/@typescript/native/bin/tsc` by path, because both packages declare a `tsc` bin and `node_modules/.bin/tsc` is whichever one npm linked last. `check:admin` stays on TypeScript 6: `--tsgo` cannot follow `.svelte` imports from outside its tsconfig's folder (`web/admin` imports `../src/lib/ui`), and a component it cannot map falls back to the ambient `*.svelte` shim - unchecked props, and no error. Dependabot ignores `typescript` majors and the alias (it mishandles `npm:` aliases): bump the two by hand. `~7.0` because 7.1 changes the API svelte-check's experimental mode uses. TypeScript 6 goes when svelte-check accepts 7 alone: `docs/plan/17-typescript-7.1.md` lists the conditions, the steps and the planted-error check that proves the switch. - **Real paths everywhere, including the packaged apps.** There is no HashRouter and no hash shim: `tauri::manager::get_asset()` falls back through `.html`, `/index.html`, then `index.html`, so the Tauri webview resolves `/games/730` on its own. The old claim that it "has no server-side fallback" was out of date. See `docs/plan/15-sveltekit-migration.md`. HashRouter-era `/#/…` URLs still arrive - from released 1.4.x builds, and from old links to the GitHub Pages site, whose tombstone redirect forwards the fragment - and `upgradeLegacyHashUrl()` upgrades them on load with `goto(…, {replace: true})`; a path that matches no route (kit 3's `goto` rejects it) goes to `/error/404`. The hash is resolved against the page's origin and ignored if it names another (`#//other.example`), and nothing from it may reach `location.*` - CodeQL flagged exactly that as XSS and an open redirect. Do not remove it, and do not reduce it to a `history.replaceState`: that fixed the address bar and left the dashboard rendered. - **`web/static/_headers` sets the browser cache, by path.** Hashed output (`/_app/immutable/*`, `/workbox-*`) is a year, immutable; the art and the manifest, which keep their names, are a day fresh plus a week of stale-while-revalidate; robots/sitemap an hour. HTML, `/sw.js` and `/_app/version.json` deliberately keep `max-age=0, must-revalidate`: a deploy, a changed legal document and a new service worker must show on the next load. Rules match the PATH, so the SPA fallback for a missing asset inherits them (accepted - only a tab open across a deploy sees it, and `hooks.client.ts` reloads it); two rules giving one path a Cache-Control are comma-joined. `src/lib/cache-headers.test.ts` holds all of it. - **Data-only and docs-only commits must not deploy** (Workers Builds watch paths): a deploy re-uploads every file and gives every open tab a Reload prompt. Docs stopped deploying on 2026-10-02; data commits still did, which the next bot commit's check runs show (a `Workers Builds` check means it deployed). But the legal documents are BUILD INPUTS (`build/legal-versions.ts` hashes them for the consent gate, `lib/server/markdown.ts` renders `/legal/*`). A commit touching only them must still trigger a build, or the site keeps the old text and hash; see `docs/DEPLOYMENT.md` "Which commits deploy" for a configuration that does both. Excludes beat includes there. - **The CSP lives in `web/build/sveltekit-config.ts` (`csp`), not in `_headers`.** SvelteKit emits one inline bootstrap script per page and hashes it there. A header CSP cannot coexist: browsers enforce the INTERSECTION of header and meta policies, so a `script-src 'self'` header blocks the script whatever the meta says, and the whole app renders its HTML and then fails to hydrate. `frame-ancestors` is ignored in a meta CSP, so `X-Frame-Options: DENY` in `web/static/_headers` is what stops framing. - **That CSP has TWO flavours, chosen by `TAURI_ENV_PLATFORM`.** Under Tauri the page origin is `tauri://localhost`, so `'self'` means the BUNDLE, not the site — a `connect-src 'self'` policy blocks every `/api/data/*` fetch and the packaged apps show an empty catalogue. `sveltekitConfig(true)` adds `https://free-steam-games.win`, `https://api.github.com`, `ipc:` and `http://ipc.localhost` only for that build; the web policy stays `'self'`, because dropping `api.github.com` from it was deliberate (`/api/activity` proxies it). Tauri sends its OWN policy as a header from `tauri.conf.json`, which is why that one carries `script-src 'unsafe-inline'`: the two intersect, and the meta policy's sha256 is what actually enforces. The web policy has four hosts the Tauri one must never gain: `https://static.cloudflareinsights.com` in `script-src` and `https://cloudflareinsights.com` in `connect-src`, for the analytics beacon, `https://challenges.cloudflare.com` in `script-src` AND `frame-src`, for the Turnstile human check (the widget is an iframe; without `frame-src` it falls back to `default-src 'self'` and is refused), and `https://media.free-steam-games.win` in `img-src`, for the minted art (see the `/img/*` entry below). The Tauri policy has no `frame-src` at all. `verify-dist.mjs` fails the web build without them and the Tauri build with any of them. - **Cloudflare Web Analytics must stay on "JS Snippet installation", never automatic.** Automatic injection adds an INLINE loader at the edge, after our response; the CSP is `mode: "hash"`, and CSP3 makes a `script-src` carrying a hash ignore `'unsafe-inline'` — so no policy can ever admit it. It was enabled that way for months, logging two CSP violations per page load and collecting nothing. `lib/analytics.ts` appends the beacon itself, from the `$effect` in the root layout that waits for consent and the human check, never under Tauri, and does nothing when `CF_BEACON_TOKEN` is empty. - **The Turnstile human check is web only, runs AFTER consent, and is soft by design.** `lib/common/HumanCheck.svelte` is an overlay like the consent gate (opens only after `humanCheck.hydrated`, so it is never prerendered; `verify-dist.mjs` fails a page containing its title), once per 24 h per browser (`f2p:human_check`). The catalogue fetch, service-worker registration, analytics and the `/welcome` redirect wait for `appReady()` (`lib/app-ready.ts`: consent accepted AND the check cleared), and every `Resource` passes it as `enabled`, so a page that calls `load()` itself (or refetches on focus) cannot jump the gates — `resource.test.ts` fails on a `new Resource` without it. The token is verified by `POST /api/human-check` (`worker/routes/human-check.ts`, secret `TURNSTILE_SECRET`, action and hostname checked; constants in `shared/human-check.ts`). Nothing on the server requires a pass, and nothing may: the pages never reach the Worker, and `docs/ToS.md` §9 promises `/api/data/*`, `/img/*` and the apps are never human-checked — making them require one breaks that promise and the packaged apps. It refuses only on a verdict (the route's 403, a 300xxx/600xxx widget error); a missing secret or a test widget's token meeting the real secret (503), siteverify trouble (502), a widget configuration error and being offline all let the reader through for that page load, unrecorded. Off under Tauri, under `npm run dev` (its `/api` proxy is production), and when `TURNSTILE_SITEKEY` is empty. The pure rules are in `lib/human-check.ts`, tested without Svelte. Never write the overlay's title into a legal document: the privacy policy is prerendered and would trip that verify-dist check. - **Every `` carries a literal `referrerpolicy="no-referrer"`.** The zone has Cloudflare Hotlink Protection on; it 403s `/img/*` for any Referer that is not this site, at the edge before the Worker, and allows a request with none. The Tauri webviews send `http://tauri.localhost/` (Windows, Android), which blanked every image in the 2.0.0 apps; 2.0.0 installs survive on a Configuration Rule (`docs/SECURITY_SETUP.md` §10). `src/lib/images.test.ts` fails on an `` without the attribute. Do not "fix" it with a `` or by relying on the webview's default. - **Never put `use:`, `onload` or `onerror` on an `` that can be prerendered.** Svelte then writes `onload="this.__e=event"` and `onerror="this.__e=event"` into the HTML, to replay an event that fired before hydration, and the CSP is a hash policy, which refuses inline event handlers: one CSP violation per page view (the game hero logged it on every page until it moved to an attachment). Use `{@attach}`, which writes nothing; `lib/img-fallback.ts` recovers a load that already failed from `complete && naturalWidth === 0` instead. `verify-dist.mjs` fails on `this.__e=event` in any page. - **`/img/*` NEVER transforms; only the cron does.** `worker/lib/img-mint.ts` mints AVIF (`s` 230 px q55, `d` 460 px q80) into R2 `f2p-media`, most-played first, from shards that hash to `index.json` - a list built from a lagging raw.githubusercontent shard would be stamped with the new generation and frozen. `worker/routes/img.ts` reads Cache API → R2 → Steam's JPEG and nothing else, so no request can create a billed transformation. Images Paid has no spend cap: `IMG_TRANSFORM_MONTHLY_CAP` (D1 counter `img_transforms:YYYY-MM`, counted BEFORE each call, fail closed) is the only one. Rules that are easy to break: - `s`/`d` are negotiated on `Accept` and always send `Vary: Accept`; the Cache API copy has no Vary (it ignores it), so the format is in the key. An AVIF browser gets the JPEG only as a PROVISIONAL answer: one day, no `X-Img-Final` - the service worker caches only responses carrying it, because CacheFirst ignores Cache-Control. - `t` and `d2` are ALWAYS the JPEG: released apps request them, and `d2` is og:image - a crawler may claim AVIF and not render it. - The R2 key AND the edge-cache key (`shared/img-keys.ts`) carry width, quality, path and Steam's `?t=`: new art or a new setting is a new key, so an old encoding can never be served for a new one. Changing one variant's quality re-mints only that variant (~5,600); `img/v2/` pins the format. Cloudflare's quality scale runs well below libavif's - `d` at q60 measured visibly soft (SSIM 0.960), which is why it is q80. - Never let `/cdn-cgi/image/` work on this zone. With zone Transformations on, the zone itself is ALWAYS an allowed source (it cannot be excluded), and `/img/*` proxies ANY Steam appid - so anyone could bill transformations with arbitrary options, outside `IMG_TRANSFORM_MONTHLY_CAP` (measured: `/cdn-cgi/image/width=77/img/d2/…` answered 200). `img.ts` therefore 403s any request whose `Via` names `image-resizing` (the resizer sends `1.1 image-resizing-proxy`); do not remove that check. Zone Transformations are OFF (since 2026-10-02: `/cdn-cgi/image/…` answers 404) and must stay off - the Images binding does not need them (the cron minted with them off), and while they are on the static files stay transformable (`docs/SECURITY_SETUP.md` §5). - **On the web, art comes from `media.free-steam-games.win`, the bucket's custom domain, not from `/img/*`.** A Worker always runs BEFORE the CDN cache, so no `s-maxage` on `/img` could ever save an invocation; an R2 custom domain is cached by Cloudflare like any origin, and repeat views cost neither a Worker run nor an R2 read. `lib/image.ts` builds the key with `shared/img-keys.ts` - the ONE definition the cron, the Worker and the page share - and every such `` carries `{@attach imgFallback(thumbFallback|heroFallback(...))}` with the `/img` URL: an unminted key is a 404 there and a browser without AVIF fails to decode, and both fire `error`. `images.test.ts` fails on an `` that lacks it. The packaged apps keep `/img/*` (their CSP has no media host). Everything in the bucket is public on that host, the mint marker included: never store anything private there. - The service worker's `/img/` rule is same-origin only: the media host shares the path prefix, but its responses are opaque no-cors loads it could never cache. Those objects' year of immutable Cache-Control is what keeps them, in the HTTP cache. - `/img` remembers an R2 miss in that data centre for one cron tick (`MISS_TTL`, 15 min) - the web's fallbacks and the apps ask for unminted art often during a backfill. - URLs keep `.jpg`: Hotlink Protection matches by extension. - Flip `IMG_TRANSFORM` in `wrangler.jsonc`, not the dashboard: there is no `keep_vars`, so the next deploy resets a dashboard value. - The bucket must exist before a deploy that binds it (code 10085). - **`adapter-static`'s `fallback` must not be named `index.html`.** It is written last and overwrites whatever shares its name, which silently replaced the prerendered home page with an empty shell. It is `200.html`. - **…and the service worker's `navigateFallback` must NOT be `/200.html`.** `generateFallback()` writes that file straight into `dist/`, after workbox has globbed `.svelte-kit/output`, so it can never be in the precache — `createHandlerBoundToURL()` threw `non-precached-url` on every load and abandoned the rest of the worker's setup. It is `/`, which is both precached and exactly what Cloudflare and Tauri already serve for an unmatched path, so `lib/fallback-route.ts` recovers the route offline the same way it does online. `verify-dist.mjs` now parses `dist/sw.js` and fails if the bound URL is not a precache entry. - **`paths.relative` must stay `false`.** SvelteKit defaults it to `true`, which gives every PRERENDERED page `./_app/...` asset URLs. Served as the fallback for `/games/730` those resolve to `/games/_app/...`, which misses, falls into the SPA handler, and comes back as `index.html` with `Content-Type: text/html` at HTTP 200 — so the browser refuses the module and the page never hydrates. Invisible until a route actually falls through, because `200.html` was always absolute. - **An unmatched path is answered with `index.html`, which is the prerendered DASHBOARD — and a prerendered page hydrates as its own route.** Cloudflare's `not_found_handling: "single-page-application"` names no file, and Tauri's `get_asset()` chain is compiled in, so neither can be pointed at `200.html`. `_redirects` cannot either: Workers Static Assets has no 200-status rewrite and honours `/games/* /200.html 200` as a REDIRECT (measured: the address bar became `/200`). The symptom is subtle — `page.route.id` and `page.url` are CORRECT, so the canonical tag and og:url look right; only the rendered components are the dashboard's. `web/src/lib/fallback-route.ts` re-navigates on first mount for the routes in `MAY_FALL_BACK` — unless the route's own page hydrated, which each of those pages announces by calling `markRouteRendered()` from its top-level script. That check is what lets a PRERENDERED `/games/730` skip the re-render while a game added after the last deploy, every Tauri game page and every studio page still recover. `fallback-route.test.ts` holds the list against the routes whose `prerender` is not literally `true`, and checks each one marks itself. A path that matches NO route hydrates the same way with `page.route.id === null`; the root layout renders the 404 view in place. Never `goto()` an unmatched URL: SvelteKit 3 rejects it (SvelteKit 2 fell back to a native load, the host answered with `index.html` again, and it looped forever). - **Game pages are prerendered from build-time seeds, through a UNIVERSAL load.** `build/game-seeds.ts` serves `virtual:game-seeds`: in the SSR build it reads `../data` and inlines a seed per game (slow-changing fields only — never players or reviews); in the client build `seedFor()` reads the page's own `#game-seed` JSON block, so the load returns the same value while hydrating. Do not turn it into `+page.server.ts`: client navigation would then fetch `__data.json`, which for a game added after the deploy is `index.html` at 200, and the page errors. `__PRERENDER_GAMES__` is false for Tauri. `prerender.handleHttpError` ignores 404s under `/img/` and `/api/` only, because the crawler follows the page's `` into a Worker route that does not exist at build time. That handler only decides pass/fail; the `[404] GET /img/…` line per game came from SvelteKit's DEFAULT server `handleError`, which no `handleHttpError` setting can silence. `src/hooks.server.ts` answers both prefixes before routing (no layout render, no log), and only ever runs at build time and under `vite dev`, whose proxy takes `/api` and `/img` first. Keep its prefixes identical to `handleHttpError`'s. - **Nothing may gate the markup behind `onMount`.** onMount does not run during prerender, so anything behind it ships an empty body and the SEO reason for prerendering is gone. The consent gate is an OVERLAY for this reason, not a replacement for the page. - **`/api/data/*` and `/api/activity` send `Access-Control-Allow-Origin: *` on purpose.** The Tauri apps fetch them cross-origin (`tauri://localhost`, `http://tauri.localhost`); without it they cannot load the catalogue or the activity feed at all. Never add CORS to `/admin/api/*`, `/api/ingest/*` or `/api/human-check` (same-origin by design; the apps never run the check), and never set `Cross-Origin-Resource-Policy` on Worker responses — the same apps load `/img/*` cross-site. - **Every page's `` comes from `web/src/lib/common/Seo.svelte`.** Do not hand-write `` in a route — two title elements resolve by DOM order, silently. `og:image`/`og:url` must stay absolute from `SITE_ORIGIN`, never `page.url.origin`, which during prerender is SvelteKit's internal `http://sveltekit-prerender` host. `seo.test.ts` enforces both. - **`sitemap.xml` is a prerendered route**, not a static file, driven by `import.meta.glob` over the route table. It needs `prerender.entries` because nothing links to it. Extra exports from a `+server.ts` must be `_`-prefixed or SvelteKit rejects the build. - **`static/` art is generated.** `icon.svg` is the only hand-edited mark; `scripts/gen-icons.py` derives the PNG icons and `og.png` from it. Social platforms do not render SVG previews, and `apple-touch-icon` never accepted SVG. - **The web app registers its service worker itself, after consent and the human check.** vite-plugin-pwa cannot inject a registration script — SvelteKit has no `index.html` for it to write into — so for the whole of 2.0.0 the worker was built and never registered, and the manifest was linked from no page. `lib/pwa-state.svelte.ts` calls `registerSW` (`registerType: "prompt"`, so a new version waits for the reader's Reload instead of reloading under them), and the root layout emits `pwaInfo.webManifest.linkTag`. The Tauri build gets no-op stubs for both virtual modules. `verify-dist.mjs` checks the manifest link on web and its absence in the Tauri build. - **The packaged apps must never register a service worker.** One registered at `tauri.localhost` can NEVER be updated — the update algorithm refetches the worker script bypassing the worker, and Tauri's custom protocol does not satisfy it ("An unknown error occurred when fetching the script"). The worker from whatever version ran FIRST then serves its own precache, including `index.html`, forever: the 2.0.0 build launched showing the 1.4.x React UI inside the new window. No frontend fix is possible, because the frontend that would do the fixing is the part being served stale. `vite.config.ts` omits the PWA plugin when `TAURI_ENV_PLATFORM` is set, and `src-tauri/src/lib.rs::purge_stale_webview_data` clears the webview's storage for an install whose previous version stamp is missing or older than 2.0.0 — ONLY those. It used to clear on every version change, which with a working updater would have wiped consent, theme, language and the cached catalogue on every release. `needs_purge` has unit tests (`cargo test --lib`). - **The desktop updater's feed is `/api/updates/desktop`, not GitHub's "latest" release.** This repository publishes dataset (`v*`), Android and desktop releases on one page, so `releases/latest/download/latest.json` was usually not a desktop release and 404ed. `worker/routes/updates.ts` reads `releases.atom` (drafts never appear, no API rate limit), picks the highest `desktop-vX.Y.Z`, validates its `latest.json` (version matches the tag, every artefact URL is this repo's release download) and answers 204 — the updater's "no update" — for anything unusable. Like `/api/activity` it is public and must never use the GitHub App token. A desktop release is offered only once its draft is published. tauri-action v1 writes API asset URLs (`api.github.com/repos/…/releases/assets/<id>`) into `latest.json`, which that check refuses, and has no setting to change it: the `updater-json` job of `release-desktop.yml` (`scripts/updater_json.py`) rewrites them to the release's download URLs once every platform is built, refusing any entry whose signature is not its file's `.sig`. Without it a desktop release is offered to nobody (desktop-v2.2.1, the first v1 build, needed a hand fix). Between the tag push and publishing the feed answers 204 anyway: the new tag is already in `releases.atom`, its `latest.json` not yet public. - **Legal consent is per-document content hashes, not one integer.** `build/legal-versions.ts` serves `virtual:legal-versions` (a hash per document, inlined) and `virtual:legal-sources` (the raw markdown, imported DYNAMICALLY by `ConsentGate.svelte` alone, so a normal page load never fetches those 25 KB). Editing `docs/EULA.md` now reopens the gate by itself, showing only that document as a `lib/diff.ts` diff against the copy in `f2p:legal_snapshot`. `TERMS_VERSION` survives only as the "make everyone read all six again" override — bumping it for a routine edit defeats the feature. The state lives in `lib/consent.svelte.ts`, NOT `prefs.svelte.ts`: the admin SPA imports the latter and its build cannot resolve a virtual module. Render the diff as text in a `<pre>`, never `{@html}`. - The app is behind a first-run legal consent gate (`web/src/lib/common/ConsentGate.svelte`). Only `/error/*` and `/legal/*` bypass it — the gate links to the legal documents it asks people to accept — and any new route that must be reachable pre-consent has to join that list, which is `isUngatedPath()` in `lib/gates.ts`, shared with the human check. The gate renders only after `consent.hydrated`: rendered before storage was read, it was baked into every prerendered page and flashed for returning visitors. - **Declining or leaving at the gate.** In the apps Decline calls `exit()` from `@tauri-apps/api/app` (capability `core:app:allow-exit` in `capabilities/default.json`), never `getCurrentWindow().close()`: on Android that resolves without closing anything (tao reports a destroyed window only from the Activity's `onDestroy`), so Decline did nothing there before 2.5.0. `exit()` finishes the activity on Android and ends the process on the desktop; the declined notice appears if the app is still alive 2 s later. On the web, "Leave site" (`lib/leave-site.ts`, hidden under Tauri) goes back to the page before the site, because no page may open the browser's own start page (`chrome://newtab`, `about:home`). Rules: - It steps over ALL of the site's entries at once, `history.go(-(navigation.currentEntry.index + 1))`: `entries()` is the contiguous same-origin run, other documents and SvelteKit's pushState entries included. Without the Navigation API it is one step back. - `history.go()` is silent when there is nowhere to go (the foreign entries can all be forward ones), so a 1.5 s watchdog shows "Nothing to go back to"; `beforeunload`, `pagehide` and `popstate` cancel it. `pagehide` matters: timers freeze in the back/forward cache and resume on restore. - When every entry is the site's, closing the tab is a SECOND, explicit click (`closeTab()`): closing the last tab closes the browser window with it. - `consent-gate.test.ts` holds the exit import, the capability and the two guarded Leave buttons; `leave-site.test.ts` holds the algorithm. - **`/welcome` is shown once, by the layout, and only to a visit that STARTED on `/`** (not a deep link, not `/#/…`, not mid-session), after consent and the human check. It uses `replaceState`, and the page marks itself seen on mount, so Back cannot loop into it. Crawlers never consent, so `/` stays the indexable page. - **`/legal/[doc=legaldoc]` has a param matcher** (`legaldoc` in `src/params.ts`). An unknown slug therefore matches NO route and gets the layout's translated 404; without it the host's fallback (the prerendered dashboard) hydrated as the doc route. Legal labels and hints in `lib/legal.ts` are i18n keys. - **`/games` mirrors its filters into the query string, browser-only**: `onMount` reads `location.search` (a link with filter parameters replaces the stored filters) and a debounced shallow `goto` writes back. Never read `url.search` in markup or a load - prerender throws on it. The page number lives in the filter store, keyed to the criteria (`filters.pageFor`), so Back from a game keeps the page and a changed filter starts again at page 1. The language filter (`?lang=`) offers the names stored in `languages`, Steam's English ones: data, never i18n keys. - **`/random` keeps its picks in memory, and only the reader rolls.** `lib/random.svelte.ts` holds appids, module-level so Back from a game shows the same games, and NO `f2p:*` key: the Privacy Policy lists every stored key, and editing it reopens the consent gate for everyone. Rules: - A roll happens in a handler, or once in an `untrack`ed effect when the catalogue first arrives - never in `$derived` or markup, which would roll again on every revalidation or language switch. `resolve()` is the deterministic part: it drops a pick that left the catalogue or stopped qualifying, and nothing tops it back up. - Randomness is `crypto.getRandomValues` with rejection sampling and a sparse Fisher-Yates (`lib/random-pick.ts`). Never `Math.random`: SonarCloud reports it as hotspot S2245, and an unreviewed hotspot fails the gate. - Never a game marked unsafe or without an appid; dead games only on request. The route is top-level on purpose: under `/games/` the header search would stop jumping to /games, `isActive` would light Games too, and the PWA's `globIgnores` would leave it out of the precache. - A plural key needs its base key (`random.pool` beside `random.pool_one`): `t()` falls back from `_other` to the base, and the i18n test requires every literal key to exist. - **Search folds; storage never does.** `lib/search-fold.ts` `fold()` is NFKC plus hiragana to katakana, applied to BOTH sides of every search box (`/games`' Fuse index, the palette, /developers, /publishers, the anti-cheat list), so `トロイ`, `とろい` and `トロイ` find one game and a full-width `4` or `:` its ASCII twin. Never apply it to stored text: NFKC rewrites U+3000 and half-width kana, which `save_main()` keeps as spelling. Rules: - Fuse gets one `getFn` per KEY. A wrapped `Fuse.config.getFn` hands back `{v, i}` objects for array fields (`tags`, `developer`, `publisher`), not strings, and folding those type-checks and then breaks. - Fold the query, THEN trim: NFKC turns U+3000 into a plain space. - Not Fuse's `ignoreDiacritics`: it strips the dakuten, making ガ equal カ. And no `includeMatches`: its positions would point into folded text. - The header search jumps to /games only once an input method has finished composing (`lib/layout/header-search.ts`); the value is still written on every keystroke, because Android keyboards compose Latin words too. The jump is `goto("/games", {reset: false})`: the default reset moved focus to `<body>` and the next keystroke was lost. The page scrolls inside `<main>`, which no reset touches, so focus is all `reset` changes there. - The palette takes one kanji, kana or Hangul syllable where Latin needs two. - A CSV download starts with a byte order mark (`csvForExcel()`), or Excel opens CJK names as mojibake. It is the escape `"\uFEFF"` in the source; the editing tools turn a typed escape into the raw character, so write it with a script and check the bytes. - **`safe` is classified by `lib/safety.ts`** (`y`, `n`, `?` = not reviewed, `""` = never set). `/games`, `/stats` and `/health` all use it; `?` is a to-do, not missing data, so /health reports it as its own group. - **`ACCESSIBILITY.md` (root) is a claim about this code, like this file.** Its "What works today" and "Known limitations" lists were checked against the code on 2026-11-09. A change that fixes a limitation, or adds one, edits the list and its "Last reviewed" line in the same pull request. Reports arrive through `.github/ISSUE_TEMPLATE/accessibility.yml` (label `accessibility`), and the About page links both the form and the statement. `src/lib/a11y.test.ts` holds the fixes it lists. Rules that are easy to break: - **The games table is an ARIA table only when it is complete.** That means `role="table"` with `aria-rowcount`/`aria-colcount`, a `rowgroup`, and `aria-rowindex` on every virtualised row. Every column needs a label or an `srLabel` (`games/columns.ts`). It used to be `<a role="row">` with nothing around it, which a screen reader read as neither a table nor a link. - **A row is not a link.** The name's `<a>` stretches over the row (`after:absolute after:inset-0`). Anything that must stay hoverable or clickable on its own sits above it with `relative z-[1]`: the tooltips, and the Steam `<a>`, which is `tabindex="-1"` so a row is one Tab stop. The row draws the focus ring (`has-[:focus-visible]`), because cells clip overflow. - **The first-run overlays report to `lib/overlays.svelte.ts`.** The layout makes the page behind them `inert`: the bare pages' wrapper, the skip link and the shell. Ctrl/Cmd+K stands down while they are open, because the palette would open under the gate and trap focus there. They are `role="dialog"`, focus themselves with `focusOnMount`, and title themselves with an h2. `BackToTop` is inside the shell so that it goes inert with the page. - **Kernel-level anti-cheat goes through `games/AntiCheatBadge.svelte`.** It adds a shield icon and the words, so the colour is not the only cue. - **Theme colours are checked by the WCAG formula.** The test computes 4.5:1 for text (badges on their /15 tint included) and 3:1 for `--input`/`--ring` in both themes. A token edit that drops below either fails. - **Desktop zoom needs both parts:** `zoomHotkeysEnabled` on the window, and `capabilities/zoom.json`. The latter is desktop-only, and macOS/Linux zoom through an injected script that calls `set_webview_zoom`. Svelte's a11y warnings never fail CI (`svelte-check` runs without `--fail-on-warnings`), so read them. ## Admin SPA (`web/admin/`) - **It is part of the Worker script, never of `dist/`.** `admin/vite.config.ts` builds it and `admin/build/emit-worker-bundle.ts` writes the gitignored `worker/generated/admin-bundle.ts`, which `worker/routes/admin-spa.ts` serves only after `worker/index.ts` has done the Access, credential-class and CSRF checks. `dist/` is readable by anyone, precached by the service worker and packaged into the apps, so admin code there would be public whatever Access says. `scripts/verify-dist.mjs` fails on `dist/admin` or any `/admin/api/` string in `dist/`. - **Its API lives at `/admin/api/*`, under the page, never beside it.** Cloudflare Access issues its cookie per application, and `fetch()` cannot follow its sign-in redirect, so an API behind an application of its own (it was `/api/admin/*`) answered every call with a login redirect: the SPA said "session expired" straight after signing in, incognito included. `ADMIN_API_PREFIX` in `shared/admin-routes.ts` is the one definition, and `worker/index.test.ts` drives it through the real router and Access check, which the handler tests never did. - **`npm run build` must keep running `build:admin`,** and `typecheck` builds it first: `worker/index.ts` imports the generated module, so a bare `wrangler deploy` or `tsc` without it fails. That failure is intended. `build:admin` runs `svelte-kit sync` first: the admin imports files under `web/src`, whose `tsconfig.json` extends `$app/tsconfig` (`node_modules/$app/tsconfig.json`), and on a clean checkout (CI) that file does not exist until SvelteKit has synced. The emitter reads the bundle in `writeBundle`, never the output directory in `closeBundle`, which also runs after a FAILED build and hid that error behind an ENOENT. - **One script, no code splitting.** The shell's CSP is `script-src` with a per-response nonce and nothing else, so a lazily imported chunk would be blocked. The emitter fails the build on a second script, an inline script or a second JS file. Do not add `'unsafe-inline'` or `'strict-dynamic'` to make a chunk load. - **Routes are `shared/admin-routes.ts`.** `serveAdmin` 404s every other path under `/admin` (the old Worker served the queue for any typo). A new page goes there AND in `App.svelte`'s `NAV`; `admin/security.test.ts` holds them equal. `/admin` is the Overview and the queue is `/admin/queue`; `legacyQueuePath()` sends an old `/admin?status=…` bookmark there with `replaceState`. - **No `/admin/api` route may answer 401 or 403 for anything but Access.** The SPA reads both as a lapsed session (next bullet) and reloads: GitHub trouble is a 502, missing D1 state or an unreadable catalogue a 503, each with a JSON `error`. The Overview calls the other pages' endpoints, one card each, so one failing endpoint blanks one card. - **It may import only pure modules of the public app**: `src/lib/ui/*`, `src/lib/utils.ts`, `src/lib/prefs.svelte.ts`, `src/fonts.css`, `src/styles/theme.css` (the design tokens, shared by both builds). Never `$app/*` (nor a module that imports it) and no virtual module; that build cannot resolve them. - **`admin/mock/` is a dev server, not a mode.** `npm run dev:admin` runs the real handlers against an in-memory D1 and fake GitHub; nothing under `worker/` or `admin/src` may import it, and the Worker has no flag that skips authentication. Keep it that way. - **No raw HTML.** Game names, reasons, payloads and audit detail are text other people wrote; `{@html}` and `innerHTML` are banned by `admin/security.test.ts`. - **`admin/src/lib/api.ts` fetches with `redirect: "manual"`.** An opaque redirect, 401 or 403 is a lapsed Access session and reloads the page ONCE (guarded in sessionStorage, so a persistent refusal cannot loop). A non-JSON body is a server error, never "session expired": that misreport hid real Worker crashes in the old admin pages.