Files
free-steam-games-list/CLAUDE.md
T
poli0981andClaude Opus 5.5 d482013cf7 docs: name changelog/ where CHANGELOG.md is named
README's link, the export-ignore beside CHANGELOG.md's, the watch-paths
note in DEPLOYMENT.md, and a CLAUDE.md rule for where release notes go
and how a release moves [Unreleased] into its own file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 09:02:17 +07:00

92 KiB
Raw Blame History

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<major>/<major>.<minor>.x/<version>.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 &amp; Click, appdetails' &quot;), 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/<appid>.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 delManys 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 &quot; 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/<id>/ → /agecheck/app/<id>/ → /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 "<name> [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:<code>, 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 <email> 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 (@<sha> # 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 -- <file>). 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 <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, <html data-scrollbars="panels|all">) 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, <main> 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 <Seo> 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.tsrejects 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 <path>.html, <path>/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 <img> 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 <img> without the attribute. Do not "fix" it with a <meta name="referrer"> or by relying on the webview's default.

  • Never put use:, onload or onerror on an <img> 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 <img> 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 <img> 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 <img> 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 <head> comes from web/src/lib/common/Seo.svelte. Do not hand-write <title> 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 untracked 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.