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>
1365 lines
92 KiB
Markdown
1365 lines
92 KiB
Markdown
# 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 & Click`,
|
||
appdetails' `"`), references with a semicolon only.
|
||
- `notes` loses the retired browser extension's two leading phrases,
|
||
`Has paid DLC` (what `has_paid_dlc` says, kept true by the store refresh)
|
||
and `[hover-add]` (`clean_notes()`); a note left with nothing becomes
|
||
`Not reviewed yet`, an empty one stays empty. `apply_overrides()` cleans an
|
||
override's notes too, or it would put the phrase back after every
|
||
normalisation and commit on every run.
|
||
|
||
Every rule must stay idempotent: one that changed anything on a second
|
||
pass would rewrite every shard on every run. `test_normalize.py` holds
|
||
that, and `refresh_store_data.py` compares fresh values in this form.
|
||
|
||
- **`MANUAL_FIELDS` are human judgements.** They are `anti_cheat`,
|
||
`anti_cheat_note`, `is_kernel_ac`, `notes`, `type_game`, `safe`, `genre`.
|
||
Two mechanisms protect them, and they are not the same thing:
|
||
|
||
1. *Fill-if-empty*, in `apply_details()` and `fetch_full()`: a scrape will
|
||
not overwrite a non-empty value. This is weak — it cannot tell a human
|
||
correction from earlier scraper output, so `normalize_genres.py --apply`,
|
||
which rewrites `genre` for every game, silently reverts corrections.
|
||
2. *Overrides*, below. This is the durable one.
|
||
|
||
The anti-cheat trio is the exception on purpose: `refresh_anticheat.py`
|
||
REPLACES `anti_cheat`/`anti_cheat_note`/`is_kernel_ac` with what the
|
||
developer declares on Steam (Pipeline, below), so for those three an
|
||
override is the only way to disagree with Steam. A writer that sets manual
|
||
fields on a schedule asks `OverrideGuard` first (`core/overrides.py`): a
|
||
field an active override covers, or a retired entry's value, would be undone
|
||
by `apply_overrides()` and bump `last_updated` on every run.
|
||
|
||
One stored genre is not a judgement: a value in `NOT_GENRES` ("Free To
|
||
Play", "Early Access"; `constants.py`), a price model or a release state.
|
||
Until v4.6.0 the skip list matched appdetails' names case-sensitively and
|
||
1,357 games were stored with "Free To Play". `fetcher.pick_genre()` compares
|
||
casefolded and never falls back to one, and Refresh Store Data replaces a
|
||
stored one (`is_stray_genre()`) from appdetails, guarded like any writer.
|
||
|
||
- **`data/overrides/<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 `"` 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.
|