The scan job now runs both suites with coverage before scanning: pytest --cov (pyproject.toml: scripts/ without its tests, relative paths, coverage.xml) and `npm run test:coverage` (vite.config.ts: v8, lcov with projectRoot "..", so paths start web/). sonar-project.properties names both reports and drops sonar.coverage.exclusions. requirements-test.txt gains pytest-cov 7.1.0 and coverage 7.16.2 with every file's hash (uv pip compile --universal --generate-hashes --python-version 3.15; the existing pins are unchanged). web gains @vitest/coverage-v8 5.0.5, matching vitest; none of its packages has an install script. Coverage stays off for a plain `npm test`. The token check is its own job, so the scan steps no longer each repeat the condition; the workflow grants nothing at the top and the scan job contents: read. `npm run build:admin` replaces the bare `svelte-kit sync`: it syncs too, and writes the admin bundle the Worker's tests load. Locally: 576 vitest tests at 58.35% of lines, 299 pytest tests at 57.7%. Against main's new-code lines (SonarCloud's isNew), the reports cover 92 of 114 coverable lines, 80.7%: the 80% gate is borderline. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
67 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.
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. -
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. - 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. It replaces values only with NON-EMPTY ones, never writesMANUAL_FIELDSornotes, 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 later, now that"is one character, is written without counting as news), 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 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) 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 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. 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 week.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). A separate removal workflow would keep evicting the ingest fromdata-write's single pending slot, and the ingest it. The workflow checks outref: main, not the triggering SHA: a run that waited its turn would otherwise work on the data as it was when it was queued.- 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. - 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 exists because a push while a data job waits EVICTS that job.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.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}. A new data-writing workflow without it will race jobs that run ~2 hours. The group holds ONE pending run - a second queueing run cancels the first - and scheduled runs here start 2-5 hours after their cron, so a new schedule goes where nothing long is running (the long jobs - reviews, dead links, purge - start mid-morning UTC and run 2-4 hours; Refresh Store Data is at 16:00 for that reason). - 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 four-hour 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.
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.- The
"@sveltejs/kit@2.70.3": { "cookie": "^0.7.2" }override closes GHSA-pxg6-pf52-xh8x (kit 2 declarescookie ^0.6.0; only kit 3 moved on). Kit imports justparse/serialize, which 0.7 keeps, and under adapter-static that code runs only at prerender and invite dev. The key names kit's EXACT version because npm refuses a range key for a direct dependency (EOVERRIDE). A kit bump therefore silently drops the override and the alert comes back: re-key it, or delete it once kit asks forcookie>= 0.7. Never carry it onto kit 3, which needscookie2. - 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(…, {replaceState}). 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/svelte.config.js(kit.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.svelte.config.jsaddshttps://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;
kit.cspismode: "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, andkit.cspis 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. kit.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 falls back to a native load, the host answers withindex.htmlagain, and it loops 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.kit.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 needskit.prerender.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-pwa/sveltekitcannot inject a registration script — SvelteKit has noindex.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. /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 (src/params/legaldoc.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 debouncedreplaceStatewrites 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.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.
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.svelte-kit/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/*or$lib/*; 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.