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

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

1365 lines
92 KiB
Markdown
Raw Permalink Blame History

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