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>
92 KiB
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 areadd_game,edit_game,delete_game,bug_reportandaccessibility; 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.mdand the pull-request template: change them together. - Release notes are one file per release:
changelog/v<major>/<major>.<minor>.x/<version>.md, andchangelog/beta/for a pre-release (none so far).CHANGELOG.mdis 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
-
appidis not a stored field. It is parsed out oflinkwith/\/app\/(\d+)/(web/src/lib/data-store.ts,extract_appidinscripts/core/data_store.py). Never add it as a column; derive it. It is ASCII digits on both sides: JavaScript's\dis ASCII, Python's is not, soextract_appidrefuses a run of digits with any non-ASCII one in it (/app/730٤isNone, never 730) andnormalize_link()reads a queued line through NFKC first, which turns a Japanese keyboard's5118700into 5118700. A non-ASCII appid would miss every comparison and makerotation.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 touchinglast_updated:release_datehas 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, 2012andAug 21, 2012from the same client). Never store ISO: the released appsDate.parsethe field, and2012-08-21parses 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. notesloses the retired browser extension's two leading phrases,Has paid DLC(whathas_paid_dlcsays, kept true by the store refresh) and[hover-add](clean_notes()); a note left with nothing becomesNot 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.pyholds that, andrefresh_store_data.pycompares fresh values in this form. -
MANUAL_FIELDSare human judgements. They areanti_cheat,anti_cheat_note,is_kernel_ac,notes,type_game,safe,genre. Two mechanisms protect them, and they are not the same thing:- Fill-if-empty, in
apply_details()andfetch_full(): a scrape will not overwrite a non-empty value. This is weak — it cannot tell a human correction from earlier scraper output, sonormalize_genres.py --apply, which rewritesgenrefor every game, silently reverts corrections. - Overrides, below. This is the durable one.
The anti-cheat trio is the exception on purpose:
refresh_anticheat.pyREPLACESanti_cheat/anti_cheat_note/is_kernel_acwith 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 asksOverrideGuardfirst (core/overrides.py): a field an active override covers, or a retired entry's value, would be undone byapply_overrides()and bumplast_updatedon 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. - Fill-if-empty, in
-
data/overrides/<appid>.jsonis human intent, and it is permanent.apply_overrides()is called from insidesave_main()— the single choke point through which all 15 data-writing scripts pass, and the only code that writesdata/data_*.jsonl. An override is therefore re-imposed as the last act of every write, so it survivesrefetch_all.py,refresh_anticheat.pyandnormalize_genres.py --applywithout those scripts knowing it exists. Add a new dataset writer and it inherits this for free — provided it goes throughsave_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
wasand writes it back once, then permanently no-ops because the values no longer match. notesis a hybrid field. The pipeline appends its own segments to it (MACHINE_NOTE_MARKERS), and those appends are one-way —mark_dead_games.pyonly appends whileis_deadis False, so a stripped marker is never re-added.preserve_machine_notes()re-attaches them; do not bypass it.
-
data/blocklist.jsonlis the other kind of human intent: games taken OUT. One line per game (scripts/core/blocklist.py; the Worker's twin isweb/shared/removal.ts), written by/admin/removeandscripts/delete_game.py, READ by the pipeline.save_main()applies it FIRST, on every write and whateverapply_human_overridessays: 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()writesstatus_code: "admin_removed"toscripts/removed_games.jsonl, built from the blocklist line alone withremoved_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_atis whole seconds, likenow_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-dropis 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 --checkincheck-overrides.ymlis what makes it loud. The reasons inblocklist.pyandremoval.tsare 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'sremoved:decision behind (discovery keeps skipping the game). - Overrides of a removed game stay, as orphans, and apply again after a
restore.
ingest_new.pyskips blocked links before any Steam request, and discovery counts them as known.
- A drop is logged once.
-
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 betweendata_001.jsonlanddata_005.jsonlas records before it are added or removed. Never persist "game X lives in shard N". -
data/index.jsonis the client's whole cache contract. Two fields, both computed by_save_index()and nothing else:last_updatedchanges if and only if a shard's bytes, the shard list or the counts changed. A save that changed nothing keeps the old stamp, leavesindex.jsonbyte-identical, and so produces no commit (it used to force every visitor to re-download ~6 MB).files[].sha256is the hash of each shard's exact committed bytes.save_jsonlwrites withnewline="\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.pypins both. -
The app reads shards PACKED; Git keeps them plain.
/api/data/p1/data_NNN.bin(andremoved_games.bin) is the committed file run throughshared/data-pack.tsat 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/*.jsonlpaths must keep serving released apps (1.4.5 unversioned, 2.0.x?v=), which cannot unpack. Packs end in.binso the zone's.jsonlCompression 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). Databasef2p-catalogue:f2p:index(the DataIndex, readable - public metadata, so the generation compares without opening anything) andf2p:records(Uint8Array[], each shard's pack exactly asfetchShardreceived it, inindex.filesorder). 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.mdlists. 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 defaultkeyval-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, whichdelManys it - neverdeleteDatabase, which an old tab's open connection blocks. Look withindexedDB.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 emptyerror: Chromium's failed AES-GCM decrypt is a DOMException with an EMPTY message, andif (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"", soe.origin &&is load-bearing: without it every message would be refused. The!==one.originis what CodeQL'sjs/missing-origin-checkrecognises; 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.jsonis rebuilt from scratch on every save._save_index()inscripts/core/data_store.pywrites 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.tsmirrorsscripts/core/constants.py.MANUAL_FIELDSand the record shape exist in both, andANTI_CHEAT_PATTERNSis mirrored byweb/src/lib/anti-cheat.ts(+ theANTI_CHEAT_ENUMorder inenums.ts;anti-cheat.test.tsparsesconstants.pyand 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.pyonly enriches existing records. It does not discover new games, and it skips every recordis_info_complete()accepts - so, withapply_details()/apply_scraped()filling only EMPTY fields, a complete record's store data was never looked at again.refresh_store_data.pyis what refreshes it (daily, "Refresh Store Data"). A game is due whencrc32(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. Neverappid % 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(): pastPAGE_DAILY2,000 pages orDETAILS_DAILY500 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 inrotation.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 writesMANUAL_FIELDSornotes- except a stray genre (above), read from appdetails every day, first after the page repairs, at mostGENRE_DAILY_CAPa day, and left alone under an override - trustshas_paid_dlconly 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,descriptiontruncated - 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 bumpslast_updatedonly on a real change. A game with empty tags, languages orlanguage_detailsis in the page group EVERY day, first, capped atMISSING_DAILY_CAP;--missing-onlyruns 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.pyholds 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 hadhas_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 bothfetch_full()and the refresh use. For a gated or redirected game it readsIStoreBrowseService/GetItems, which is keyless: tag ids are named byIStoreService/GetTagList, language ids by the tables incore/store_items.py, and an unknown id is skipped, never stored. It readshas_paid_dlcfrom the prices of the DLC appdetails lists.Nonemeans 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 withl=english: without it, a runner was once answered in Russian. all_time_peakonly ever goes UP, andrefresh_peaks.pyis what raises it (daily 19:30 UTC, "Refresh All-Time Peaks"). Acrc32(appid) % 30slice (core/rotation.py, shared withrefresh_store_data.py; 60, 90, ... pastPEAK_DAILY400 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 byrefetch_all.py, andcurrent_players), andapply_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.pymust never clear the field - it cannot be fetched again - and nothing may lower it. The backfill is a manual run withbackfillticked (~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.pyholds the rules.- Anti-cheat is what the developer declares on Steam, and
refresh_anticheat.pyre-reads it for EVERY game daily (end of the Refresh Store Data job, its own commit;only: anticheatruns 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/GetItemswithinclude_extra_detailsgivesextra_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 onediv.anticheat_sectionwhose HEADING (Uses Kernel Level Anti-Cheat/Uses Anti-Cheat Software) decides kernel - never the class,DRM_noticealso marks boot protection - with adiv.anticheat_nameper row; aBoot Protectionrow 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 withsame_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 areANTI_CHEAT_PATTERNSkeys, 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.pyandtest_refresh_anticheat.pyhold it. - Reviews are Steam's own summary, read for EVERY game daily
(
update_reviews.py, "Update Reviews" 06:00):GetItemswithinclude_reviews, fifty games a request (SteamClient.fetch_items(), the sweep the anti-cheat and purge jobs share), ~2 minutes. It askedappreviewsone 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_CAP300 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), sofetch_full()falls back to the same GetItems summary (reviews_from_store_api()) and an ingest no longer leaves "N/A". A record'slast_updatedmoves 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.pyholds 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,visiblefalse,unlisted,release.is_coming_soon, nois_free; nevertype- a free mod is listed on purpose), andcheck_game_health()(appdetails) must confirm each flag. Anunavailable/404 answer is asked againRECHECK_AFTER(5 min) later: appdetails answeredsuccess:falsefor 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-removalsto override). Removals are logged toremoved_games.jsonlexactly as before -reconcile.tsreads 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.pyholds it. ingest_new.pyonly readsscripts/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 viacreateCommitOnBranch: 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 thantype: "game"(status_code: not_a_gameinremoved_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: inhealth_checkerit would make Purge delete old records every day.ingest-new.ymlis also the removal job.bash/ingest.shrunsremove_games.py(appliesdata/blocklist.jsonl) and theningest_new.py, and commits once ("Apply removals" whentemp_infodid not change), so one commit to either file starts one run that settles both. The workflow checks outref: 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.pyinto 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 intemp_info.jsonlthatingest_new.pystill checks game by game. - Discovery takes games in every language (since v4.6.0). The store search
(
SteamClient.fetch_search_page()) sends nosupportedlang; 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 byappdetails_languages()), which/adminshows 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'spayload_json. - Both workflows' guard step greps the two discovery scripts for
save_main|save_jsonl|clear_temp|fetch_fullas WORDS, comments and docstrings included: none of the four may appear in them at all. - The
discoverygroup queues (queue: max) in both of its workflows, so backfill windows dispatched together wait in turn instead of cancelling each other;pipeline.test.tsholds a group to one setting. - A game that declares no language (29 of them) has empty
languagesonce ingested: Refresh Store Data's repair group takes it every day and the admin Quality page flags it. Accepted.
- The search sends
- 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 withbumpCounterBEFORE the commit and given back if it fails),temp_info.jsonlonmainEMPTY, nodata-writeworkflow 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; withqueue: maxthe ingest would only queue behind it, and the gate stays so a batch lands when its ingest can start at once.shared/pipeline.tslists everydata-writeworkflow by file, andpipeline.test.tsfails when a workflow joins the group without joining the list. Settings, limits and their validation areshared/automation.ts, imported by the Worker and the page. A scheduled batch's D1 actor isauto-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 theblocklistlease). The Worker may writescripts/temp_info.jsonl,data/overrides/*.jsonanddata/blocklist.jsonl(WRITABLEingit-commit.ts) - never a shard orindex.json. Remove sets the game's decision torejected, reasonremoved:<code>, even overapproved, and every row for it that is not rejected torejected: a leftovercommittedrow would keeppublishedSql()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 aremoved:rejection (409,removed). Restore drops the line and queues the link in ONE commit, deletes only aremoved:decision, and enters an approved row (sourcerestore) for reconcile to promote - or to age tofailed, 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 indata/,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/deciderefuses such rows in its read AND in every UPDATE's WHERE, and returns each refused id inskippedwith a reason; it never drops one silently.queue-rules.test.tsparses0001_init.sqlso the constants cannot drift from the CHECK constraint oruq_queue_open_appid. reconcile.tsis still the only writer ofingest_decisions('approved'), and it now also sweeps: a pending/deferred/failed row whose appid is indata/becomescommitted, replacing a stalerejecteddecision. It holds a D1 lease (admin_locks) and skips the ~6 MB fetch whiledata/index.json's generation is unchanged (admin_state). Migration0002_admin_state.sqlis applied by hand, solib/locks.tstreats 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
/adminwrites to Git may name a person. Commit bodies,data/overrides/*.jsonanddata/blocklist.jsonllines sayADMIN_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 oldApproved in /admin by <email>cannot come back by a call site forgetting. D1 still stores the real Access identity inaudit_log.actor,ingest_queue.decided_by,ingest_decisions.decided_byandcommit_jobs.requested_by, which is what/admin/auditfilters on — do not "tidy" those to the constant too. BLOCKED_COUNTRIESis defence in depth, not the block. The Worker refuses those countries (worker/lib/geo.ts), but it only ever sees the fourassets.run_worker_firstprefixes — 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 thehuman-check-pagesManaged Challenge and every path it must keep excluding).geo.tsFAILS OPEN on an unknown country:request.cfis undefined under Vitest and underwrangler devwithout--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.tsis the second: theratelimitsbindings inwrangler.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 withRetry-After: 60. Rules:- It FAILS OPEN (no binding, no
CF-Connecting-IP, a throwinglimit()). Vitest andadmin/mockbind 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
periodstays 60 (the Retry-After), and anamespace_idis unique in the ACCOUNT - another Worker reusing one shares its counters. A newrun_worker_firstprefix needs a class, and a new binding needs its line inworker-configuration.d.ts.rate-limit.test.tsholds the periods, the namespaces, the binding names and the prefix coverage.
- It FAILS OPEN (no binding, no
audit_logandcommit_jobsare pruned daily afterADMIN_RETENTION_DAYS(wrangler.jsonc, 180).docs/PRIVACY_POLICY.mdstates the number: change both together.ingest_queueandingest_decisionsare never pruned — the decisions are what keep a rejected game out of the discovery sweep.- Every workflow that writes to
data/sharesconcurrency: {group: data-write, cancel-in-progress: false, queue: max}, checks outref: main, and declarestimeout-minutes.pipeline.test.tsfails 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 hasqueue: 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, andcommit_push.sh's rebase then conflicted ondata/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 setsJOB_BUDGET_MINUTESat least 20 below itstimeout-minutes(pipeline.test.tschecks); 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 inrotation.daily_order(), so a cut falls elsewhere the next day. A job stopped at its timeout commits nothing and concludescancelled, whichnotify-ci-failure.yml(a reusable workflow inpoli0981/.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 foringest_new.py.refetch_all.pyruns 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, notmain: a merged PR or an /admin commit can land during a long job, and a baregit pushis then rejected and the run thrown away (purge-unhealthy, 2026-09-21). The helper rebases ontoorigin/mainand 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 declarespermissions: {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-toolchainis pinned to a MASTER commit and giventoolchain: stable: its other branches are regenerated on top of master, so a commit ofstablecan vanish. GitHub's own actions (actions/*,github/*) andpoli0981/.githubstay on tags. - Every
npm ciisnpm ci --ignore-scripts, and no workflow usesnpx(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.txtpins every package the pipeline installs, transitive ones included, with the sha256 of every file on PyPI, and every install ispip 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 inpython-tests.ymlandsonarcloud.yml, which run the pipeline's line first so a Dependabot bump is proven before a data job meets it, andrequirements-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.
- Third-party actions are pinned to a commit SHA with the version in a
comment (
- One version of each runtime, and a test that holds them together
(
web/shared/toolchain.test.ts; web-ci also runs on.github/workflows/**andsonar-project.propertiesso a pull request that only moves a pin meets it).docs/plan/16-toolchain-2026.mdhas the upgrade notes.- Node is the major in
web/.node-version(26). Everysetup-noderepeats it as a quoted literal, nevernode-version-file:release-android.ymlchecks out the tag it rebuilds, and older tags have no such file.engines.nodeand the@types/nodemajor follow it. Workers Builds reads the dashboard variableNODE_VERSION=26, the one copy the test cannot see (docs/DEPLOYMENT.md): change it with the file. - Python is the
python-versionof everysetup-python(3.15), repeated bysonar.python.versionand the--python-versionabove.codeql.ymlalone stays on the newest Python CodeQL lists (3.14), named in the test'sPYTHON_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 inscripts/still namesencoding="utf-8": on Windows an older Python writes the locale's code page, and cp1252 cannot encode the leaderboards' emoji.
- Node is the major in
- SonarCloud analyses in CI (
sonarcloud.yml), and its scope issonar-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 intosonar.test.inclusionsANDsonar.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.tsconfigPathsnames all six tsconfigs inweb/(auto-detection finds only files named exactlytsconfig.json), and the job runsnpm ci --ignore-scriptsandnpm run build:admin(which syncs SvelteKit) first:web/tsconfig.jsonextends the generated one, and without it the analyser logged "Failed to parse tsconfig" and readweb/srcuntyped. A new tsconfig joins that list. The job skips commits that touch only what the data jobs write, and itsscanjob is skipped whenSONAR_TOKENis not available (forks, Dependabot). Coverage is measured there, not in the test workflows. The job runs pytest with--cov([tool.coverage.run]inpyproject.toml:scripts/without its tests, relative paths,coverage.xmlat the root) andnpm run test:coverage(test.coverageinweb/vite.config.ts: lcov withprojectRoot: "..", so the paths startweb/). Both reports are named insonar-project.properties; a path that does not resolve from the repository root is silently uncovered. Coverage is off for a plainnpm 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 reportsmainread 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-pythonoverscripts/(QODANA_TOKEN_PYTHON),qodana-jsoverweb/(QODANA_TOKEN_TS_JS),qodana-rustoverweb/src-tauri/(QODANA_TOKEN_RUST), the setup free-games-itchio-list uses. Each project's settings are theqodana.yamlin 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 deleteqodana.ymland the threeqodana.yaml. What the first runs cost:- Native
qodana-pythonfinds no interpreter by itself (SDKs.jsonempty, then everydict[int, str]andX | Noneis an "invalid type hint"): the job builds.venvand passesQODANA_PYTHON_PATH.scripts/is the project directory becausecoreresolves only there. - The
qodana-rustimage 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, abootstrapthat installs the packages, and a stand-inweb/dist/index.htmlsogenerate_context!()expands. It callsserde_jsonunused; the expansion needs it (::serde_json::Value). qodana-jsruns in Docker, not native: aplugins:entry (the Svelte plugin, without which no.sveltefile 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, soES6UnusedImportsis off (noUnusedLocalscovers 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 theqodana-report-*artifact, a zip inside the artifact;gh run view --logis empty until the whole run has ended.
- Native
Frontend gotchas
-
Never pass a theme name to
echarts.init().echarts/coreships 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; seeweb/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
$effectmust react to has to be$state: a plainlet chartmeant the setOption effect ran once while it was still undefined and never re-ran. See the comment inweb/src/lib/charts/EChart.svelte. -
zrender's wheel listeners are forced passive during
echarts.init(). It binds bothwheelandmousewheelwith no options object, unconditionally and regardless ofdataZoom, which blocks scrolling over every chart — they sit inside the page's scroll container.EChart.svelteswapsaddEventListenerfor exactly the duration of that one call. A passive listener cannotpreventDefault(), sodataZoom: {type: "inside"}androam: truewould silently stop working;charts.test.tsfails if either appears. -
Scrollbars are themed by
scrollbar-slim, never Tailwind'sscrollbar-thin. Tailwind 4.3 ships a corescrollbar-thin(a plainscrollbar-width: thin), and in Chromium 121+ any standard scrollbar property switches::-webkit-scrollbaroff for that element - which is why every panel showed the OS's grey bar while the page bar was themed.styles/theme.cssgives Firefoxscrollbar-color(only where::-webkit-scrollbaris 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-panelor.scrollbar-page; a new scroll container takes one of them. Dialogs and the legal documents stay unmarked on purpose.src/lib/scrollbars.test.tsholds all three rules. -
Every layout grid declares its base column count:
grid grid-cols-1 gap-2 sm:grid-cols-2, nevergrid gap-2 sm:grid-cols-2. Below the first breakpoint the latter has one implicitautotrack, as wide as its widest item's min-content, and atruncatename counts at full length there (the grid ITEM keepsmin-width:auto, whatevermin-w-0the 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-Nisrepeat(N, minmax(0, 1fr))and cannot do either. Rows of fixed-width columns plus aBadge(which cannot shrink below its longest word) squeezed game names to nothing at 360px the same way - hide the extras belowsm.src/lib/mobile-layout.test.tsfails on a grid without a basegrid-cols-N. -
The Android app draws edge-to-edge, and the UI pads for it with
env(safe-area-inset-*). targetSdk 36 andenableEdgeToEdge()put the webview under the status bar and the navigation bar. The shell root carriespt-safe pl-safe pr-safe,<main>pb-safe, the drawerpt-safe pb-safeand full-screen overlaysp-safe-or-4(utilities instyles/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 astatus-bar-stripbehind them, in the Android app only, keyed onprefers-color-schemeand 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 inMainActivity).mobile-layout.test.tsholds the shell and the strip's two colours. -
The Android app opts out of Auto Backup (
android:allowBackup="false"ingen/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, whiledocs/PRIVACY_POLICY.mdsays 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-separatedhsl(38 94% 60%)paints, but every hover state derived from it comes backundefinedand the hovered tile/bar/slice loses its fill;hsl(var(--x))never paints at all. Take colours fromchartTheme()(it converts the bare channel tokens), never writevar(--…)in an option, and usegridBox()rather thancontainLabel, which in echarts 6 leaves axis NAMES out of the layout. An option key whose component is not registered inecharts.ts(markLinewas) is silently ignored.chart-colors.test.tsandcharts.test.tshold 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, neverloading && !data, to choose between a loading state and the page.loadingis 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.mjsfails 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-wordclouddeclares a staleecharts@^5peer. It runs fine on echarts 6 (all the legacy APIs it uses are still exported), sopackage.jsoncarries anoverridesentry. Do not "fix" it by pinning echarts back to 5. -
runed0.35 (bits-ui's) declares an optional@sveltejs/kit ^2.21.0peer, which npm enforces once kit is installed, sopackage.jsonoverrides 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)inweb/build/sveltekit-config.ts, whichvite.config.tspasses assveltekit(sveltekitConfig(IS_TAURI));sveltekit-config.test.tsholds both flavours.svelte.config.jsis refused (the build stops while the file exists), and what waskit.*there is a top-level option (adapter,csp,paths,prerender). Rules that are easy to break:$libis gone;#lib/*is package.jsonimports. A module import names.jseven for a.tsfile (#lib/utils.js), a component its.svelte.tsconfig.jsonrepeats the mapping inpaths, becausesvelte-check --tsgoredirects.svelteimports to the declarations it emits only throughpaths: without it every#libcomponent fell back to the*.svelteshim - props unchecked, no error.src/params.tsis imported by Node itself (vite buildusesimport(), not Vite), so it and what it imports (lib/legal.ts,lib/schema.ts) name real.tsfiles and stay type-strippable; a.jsor extensionless import there is ERR_MODULE_NOT_FOUND at build time.- The PWA is
build/pwa.ts: vite-plugin-pwa wired into kit 3'sbuildApp. @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-orderbuildApphook placed aftersveltekit()- after kit's build-and-prerender, before the adapter'sposthook copies.svelte-kit/output/clientintodist/. Placed beforesveltekit(), it would glob an empty output. gotooptions arereplace(notreplaceState),reset: false(notnoScroll/keepFocus, which THROW in dev) andrefreshAll(notinvalidateAll);/gameswrites its filters withgoto(url, {shallow: true, replace: true}).gotorejects a URL that matches no route.- Hook types come from
@sveltejs/kit/hooks. The clienthandleErrorgets{kind, error, event}for every error and returns nothing to keep kit's own status and message. version.pollIntervalis kit's default (an hour), and kit also checks/_app/version.jsonwhenever the tab regains focus. A new version only setsupdated.current; a navigation that then fails reloads natively.
-
miniflare pins undici EXACTLY, so an undici advisory in
npm auditwaits 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^11and calls onlyglobSync(pattern, {cwd, follow, ignore}), which glob 14 keeps; its one break that could touch us, anignorestarting with/, matches nothing invite.config.tsorbuild/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 callsejs.render, which never loads jake. Delete each override oncenpm ls glob minimatchshows 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, sotypescriptstays 6 and 7 is the alias@typescript/native(npm:typescript@~7.0.x). svelte-check--tsgofinds 7 by that name and runs its bin; thetsc -psteps callnode node_modules/@typescript/native/bin/tscby path, because both packages declare atscbin andnode_modules/.bin/tscis whichever one npm linked last.check:adminstays on TypeScript 6:--tsgocannot follow.svelteimports from outside its tsconfig's folder (web/adminimports../src/lib/ui), and a component it cannot map falls back to the ambient*.svelteshim - unchecked props, and no error. Dependabot ignorestypescriptmajors and the alias (it mishandlesnpm:aliases): bump the two by hand.~7.0because 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.mdlists 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, thenindex.html, so the Tauri webview resolves/games/730on its own. The old claim that it "has no server-side fallback" was out of date. Seedocs/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 - andupgradeLegacyHashUrl()upgrades them on load withgoto(…, {replace: true}); a path that matches no route (kit 3'sgotorejects 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 reachlocation.*- CodeQL flagged exactly that as XSS and an open redirect. Do not remove it, and do not reduce it to ahistory.replaceState: that fixed the address bar and left the dashboard rendered. -
web/static/_headerssets 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.jsand/_app/version.jsondeliberately keepmax-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, andhooks.client.tsreloads it); two rules giving one path a Cache-Control are comma-joined.src/lib/cache-headers.test.tsholds 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 Buildscheck means it deployed). But the legal documents are BUILD INPUTS (build/legal-versions.tshashes them for the consent gate,lib/server/markdown.tsrenders/legal/*). A commit touching only them must still trigger a build, or the site keeps the old text and hash; seedocs/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 ascript-src 'self'header blocks the script whatever the meta says, and the whole app renders its HTML and then fails to hydrate.frame-ancestorsis ignored in a meta CSP, soX-Frame-Options: DENYinweb/static/_headersis what stops framing. -
That CSP has TWO flavours, chosen by
TAURI_ENV_PLATFORM. Under Tauri the page origin istauri://localhost, so'self'means the BUNDLE, not the site — aconnect-src 'self'policy blocks every/api/data/*fetch and the packaged apps show an empty catalogue.sveltekitConfig(true)addshttps://free-steam-games.win,https://api.github.com,ipc:andhttp://ipc.localhostonly for that build; the web policy stays'self', because droppingapi.github.comfrom it was deliberate (/api/activityproxies it). Tauri sends its OWN policy as a header fromtauri.conf.json, which is why that one carriesscript-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.cominscript-srcandhttps://cloudflareinsights.cominconnect-src, for the analytics beacon,https://challenges.cloudflare.cominscript-srcANDframe-src, for the Turnstile human check (the widget is an iframe; withoutframe-srcit falls back todefault-src 'self'and is refused), andhttps://media.free-steam-games.wininimg-src, for the minted art (see the/img/*entry below). The Tauri policy has noframe-srcat all.verify-dist.mjsfails 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 ascript-srccarrying 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.tsappends the beacon itself, from the$effectin the root layout that waits for consent and the human check, never under Tauri, and does nothing whenCF_BEACON_TOKENis empty. -
The Turnstile human check is web only, runs AFTER consent, and is soft by design.
lib/common/HumanCheck.svelteis an overlay like the consent gate (opens only afterhumanCheck.hydrated, so it is never prerendered;verify-dist.mjsfails a page containing its title), once per 24 h per browser (f2p:human_check). The catalogue fetch, service-worker registration, analytics and the/welcomeredirect wait forappReady()(lib/app-ready.ts: consent accepted AND the check cleared), and everyResourcepasses it asenabled, so a page that callsload()itself (or refetches on focus) cannot jump the gates —resource.test.tsfails on anew Resourcewithout it. The token is verified byPOST /api/human-check(worker/routes/human-check.ts, secretTURNSTILE_SECRET, action and hostname checked; constants inshared/human-check.ts). Nothing on the server requires a pass, and nothing may: the pages never reach the Worker, anddocs/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, undernpm run dev(its/apiproxy is production), and whenTURNSTILE_SITEKEYis empty. The pure rules are inlib/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 literalreferrerpolicy="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 sendhttp://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.tsfails 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:,onloadoronerroron an<img>that can be prerendered. Svelte then writesonload="this.__e=event"andonerror="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.tsrecovers a load that already failed fromcomplete && naturalWidth === 0instead.verify-dist.mjsfails onthis.__e=eventin any page. -
/img/*NEVER transforms; only the cron does.worker/lib/img-mint.tsmints AVIF (s230 px q55,d460 px q80) into R2f2p-media, most-played first, from shards that hash toindex.json- a list built from a lagging raw.githubusercontent shard would be stamped with the new generation and frozen.worker/routes/img.tsreads 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 counterimg_transforms:YYYY-MM, counted BEFORE each call, fail closed) is the only one. Rules that are easy to break:s/dare negotiated onAcceptand always sendVary: 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, noX-Img-Final- the service worker caches only responses carrying it, because CacheFirst ignores Cache-Control.tandd2are ALWAYS the JPEG: released apps request them, andd2is 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 -dat 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, outsideIMG_TRANSFORM_MONTHLY_CAP(measured:/cdn-cgi/image/width=77/img/d2/…answered 200).img.tstherefore 403s any request whoseVianamesimage-resizing(the resizer sends1.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 nos-maxageon/imgcould 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.tsbuilds the key withshared/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/imgURL: an unminted key is a 404 there and a browser without AVIF fails to decode, and both fireerror.images.test.tsfails 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. /imgremembers 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_TRANSFORMinwrangler.jsonc, not the dashboard: there is nokeep_vars, so the next deploy resets a dashboard value. - The bucket must exist before a deploy that binds it (code 10085).
-
adapter-static'sfallbackmust not be namedindex.html. It is written last and overwrites whatever shares its name, which silently replaced the prerendered home page with an empty shell. It is200.html. -
…and the service worker's
navigateFallbackmust NOT be/200.html.generateFallback()writes that file straight intodist/, after workbox has globbed.svelte-kit/output, so it can never be in the precache —createHandlerBoundToURL()threwnon-precached-urlon 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, solib/fallback-route.tsrecovers the route offline the same way it does online.verify-dist.mjsnow parsesdist/sw.jsand fails if the bound URL is not a precache entry. -
paths.relativemust stayfalse. SvelteKit defaults it totrue, which gives every PRERENDERED page./_app/...asset URLs. Served as the fallback for/games/730those resolve to/games/_app/..., which misses, falls into the SPA handler, and comes back asindex.htmlwithContent-Type: text/htmlat HTTP 200 — so the browser refuses the module and the page never hydrates. Invisible until a route actually falls through, because200.htmlwas 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'snot_found_handling: "single-page-application"names no file, and Tauri'sget_asset()chain is compiled in, so neither can be pointed at200.html._redirectscannot either: Workers Static Assets has no 200-status rewrite and honours/games/* /200.html 200as a REDIRECT (measured: the address bar became/200). The symptom is subtle —page.route.idandpage.urlare CORRECT, so the canonical tag and og:url look right; only the rendered components are the dashboard's.web/src/lib/fallback-route.tsre-navigates on first mount for the routes inMAY_FALL_BACK— unless the route's own page hydrated, which each of those pages announces by callingmarkRouteRendered()from its top-level script. That check is what lets a PRERENDERED/games/730skip the re-render while a game added after the last deploy, every Tauri game page and every studio page still recover.fallback-route.test.tsholds the list against the routes whoseprerenderis not literallytrue, and checks each one marks itself. A path that matches NO route hydrates the same way withpage.route.id === null; the root layout renders the 404 view in place. Nevergoto()an unmatched URL: SvelteKit 3 rejects it (SvelteKit 2 fell back to a native load, the host answered withindex.htmlagain, and it looped forever). -
Game pages are prerendered from build-time seeds, through a UNIVERSAL load.
build/game-seeds.tsservesvirtual:game-seeds: in the SSR build it reads../dataand inlines a seed per game (slow-changing fields only — never players or reviews); in the client buildseedFor()reads the page's own#game-seedJSON 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 isindex.htmlat 200, and the page errors.__PRERENDER_GAMES__is false for Tauri.prerender.handleHttpErrorignores 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 serverhandleError, which nohandleHttpErrorsetting can silence.src/hooks.server.tsanswers both prefixes before routing (no layout render, no log), and only ever runs at build time and undervite dev, whose proxy takes/apiand/imgfirst. Keep its prefixes identical tohandleHttpError'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/activitysendAccess-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 setCross-Origin-Resource-Policyon Worker responses — the same apps load/img/*cross-site. -
Every page's
<head>comes fromweb/src/lib/common/Seo.svelte. Do not hand-write<title>in a route — two title elements resolve by DOM order, silently.og:image/og:urlmust stay absolute fromSITE_ORIGIN, neverpage.url.origin, which during prerender is SvelteKit's internalhttp://sveltekit-prerenderhost.seo.test.tsenforces both. -
sitemap.xmlis a prerendered route, not a static file, driven byimport.meta.globover the route table. It needsprerender.entriesbecause nothing links to it. Extra exports from a+server.tsmust be_-prefixed or SvelteKit rejects the build. -
static/art is generated.icon.svgis the only hand-edited mark;scripts/gen-icons.pyderives the PNG icons andog.pngfrom it. Social platforms do not render SVG previews, andapple-touch-iconnever 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.htmlfor 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.tscallsregisterSW(registerType: "prompt", so a new version waits for the reader's Reload instead of reloading under them), and the root layout emitspwaInfo.webManifest.linkTag. The Tauri build gets no-op stubs for both virtual modules.verify-dist.mjschecks 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.localhostcan 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, includingindex.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.tsomits the PWA plugin whenTAURI_ENV_PLATFORMis set, andsrc-tauri/src/lib.rs::purge_stale_webview_dataclears 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_purgehas 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, soreleases/latest/download/latest.jsonwas usually not a desktop release and 404ed.worker/routes/updates.tsreadsreleases.atom(drafts never appear, no API rate limit), picks the highestdesktop-vX.Y.Z, validates itslatest.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/activityit 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>) intolatest.json, which that check refuses, and has no setting to change it: theupdater-jsonjob ofrelease-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 inreleases.atom, itslatest.jsonnot yet public. -
Legal consent is per-document content hashes, not one integer.
build/legal-versions.tsservesvirtual:legal-versions(a hash per document, inlined) andvirtual:legal-sources(the raw markdown, imported DYNAMICALLY byConsentGate.sveltealone, so a normal page load never fetches those 25 KB). Editingdocs/EULA.mdnow reopens the gate by itself, showing only that document as alib/diff.tsdiff against the copy inf2p:legal_snapshot.TERMS_VERSIONsurvives only as the "make everyone read all six again" override — bumping it for a routine edit defeats the feature. The state lives inlib/consent.svelte.ts, NOTprefs.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 isisUngatedPath()inlib/gates.ts, shared with the human check. The gate renders only afterconsent.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(capabilitycore:app:allow-exitincapabilities/default.json), nevergetCurrentWindow().close(): on Android that resolves without closing anything (tao reports a destroyed window only from the Activity'sonDestroy), 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,pagehideandpopstatecancel it.pagehidematters: 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.tsholds the exit import, the capability and the two guarded Leave buttons;leave-site.test.tsholds the algorithm.
- It steps over ALL of the site's entries at once,
-
/welcomeis 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 usesreplaceState, 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 (legaldocinsrc/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 inlib/legal.tsare i18n keys. -
/gamesmirrors its filters into the query string, browser-only:onMountreadslocation.search(a link with filter parameters replaces the stored filters) and a debounced shallowgotowrites back. Never readurl.searchin 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 inlanguages, Steam's English ones: data, never i18n keys. -
/randomkeeps its picks in memory, and only the reader rolls.lib/random.svelte.tsholds appids, module-level so Back from a game shows the same games, and NOf2p:*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$derivedor 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.getRandomValueswith rejection sampling and a sparse Fisher-Yates (lib/random-pick.ts). NeverMath.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,isActivewould light Games too, and the PWA'sglobIgnoreswould leave it out of the precache. - A plural key needs its base key (
random.poolbesiderandom.pool_one):t()falls back from_otherto the base, and the i18n test requires every literal key to exist.
- A roll happens in a handler, or once in an
-
Search folds; storage never does.
lib/search-fold.tsfold()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-width4or:its ASCII twin. Never apply it to stored text: NFKC rewrites U+3000 and half-width kana, whichsave_main()keeps as spelling. Rules:- Fuse gets one
getFnper KEY. A wrappedFuse.config.getFnhands 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 noincludeMatches: 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 isgoto("/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 allresetchanges 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.
- Fuse gets one
-
safeis classified bylib/safety.ts(y,n,?= not reviewed,""= never set)./games,/statsand/healthall 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(labelaccessibility), and the About page links both the form and the statement.src/lib/a11y.test.tsholds 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"witharia-rowcount/aria-colcount, arowgroup, andaria-rowindexon every virtualised row. Every column needs a label or ansrLabel(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 withrelative z-[1]: the tooltips, and the Steam<a>, which istabindex="-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 theminert: 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 arerole="dialog", focus themselves withfocusOnMount, and title themselves with an h2.BackToTopis 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/--ringin both themes. A token edit that drops below either fails. - Desktop zoom needs both parts:
zoomHotkeysEnabledon the window, andcapabilities/zoom.json. The latter is desktop-only, and macOS/Linux zoom through an injected script that callsset_webview_zoom.
Svelte's a11y warnings never fail CI (
svelte-checkruns without--fail-on-warnings), so read them. - The games table is an ARIA table only when it is complete. That means
Admin SPA (web/admin/)
- It is part of the Worker script, never of
dist/.admin/vite.config.tsbuilds it andadmin/build/emit-worker-bundle.tswrites the gitignoredworker/generated/admin-bundle.ts, whichworker/routes/admin-spa.tsserves only afterworker/index.tshas 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.mjsfails ondist/adminor any/admin/api/string indist/. - Its API lives at
/admin/api/*, under the page, never beside it. Cloudflare Access issues its cookie per application, andfetch()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_PREFIXinshared/admin-routes.tsis the one definition, andworker/index.test.tsdrives it through the real router and Access check, which the handler tests never did. npm run buildmust keep runningbuild:admin, andtypecheckbuilds it first:worker/index.tsimports the generated module, so a barewrangler deployortscwithout it fails. That failure is intended.build:adminrunssvelte-kit syncfirst: the admin imports files underweb/src, whosetsconfig.jsonextends$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 inwriteBundle, never the output directory incloseBundle, 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-srcwith 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.serveAdmin404s every other path under/admin(the old Worker served the queue for any typo). A new page goes there AND inApp.svelte'sNAV;admin/security.test.tsholds them equal./adminis the Overview and the queue is/admin/queue;legacyQueuePath()sends an old/admin?status=…bookmark there withreplaceState. - No
/admin/apiroute 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 JSONerror. 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:adminruns the real handlers against an in-memory D1 and fake GitHub; nothing underworker/oradmin/srcmay 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}andinnerHTMLare banned byadmin/security.test.ts. admin/src/lib/api.tsfetches withredirect: "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.