npm (web/): - undici 7.30.1 through a "miniflare" override (GHSA-xjj6-f33q-929c, GHSA-4qv8-2p9j-2685, GHSA-f72v-6w45-q472). miniflare pins undici exactly and wrangler 4.152.0, the newest, still ships 7.29.1. Local tooling only. - zod 4.6.7 (GHSA-mrhx-c7xc-m3w5, via knip). - Minor/patch: @lucide/svelte 1.61.0, @tanstack/svelte-virtual 3.13.48, bits-ui 2.20.2, vite 8.3.5, wrangler 4.152.0, knip 6.43.0, @tauri-apps/cli 2.12.4. cargo (web/src-tauri/Cargo.lock, targeted updates only): - rustls 0.23.46 (RUSTSEC-2026-0346..0349), rustls-webpki 0.103.16 (RUSTSEC-2026-0382), webpki-root-certs 1.0.11 (RUSTSEC-2026-0383), tokio 1.54.1 (RUSTSEC-2026-0386), anyhow 1.0.104 (RUSTSEC-2026-0190), event-listener 5.4.2 (RUSTSEC-2026-0221), plist 1.10.3 -> quick-xml 0.42.0 (RUSTSEC-2026-0194/0195). Dependabot had none of these. - Left upstream: zip 4 (tauri-plugin-updater 2.14.0 asks for ^4), glib 0.18 (GTK 3), unmaintained proc-macro-error/zbus_names/zvariant. pip: certifi 2026.10.23, coverage 7.17.0 (tests), with every file's hash. CI: actions/checkout v4/v5 -> v6 and actions/setup-python v5 -> v6 everywhere (the Node 20 majors warned on every data job), rust-cache 2.9.3 by SHA. dependabot.yml says why those majors are taken by hand. CLAUDE.md: the undici override and when to drop it; why SvelteKit stays on 2 (GHSA-27mw-82g8-phjj and GHSA-pfhg-q3qv-9q6r need setHeaders or use:enhance, which the app does not have). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Web App — Steam F2P Tracker
The public site at https://free-steam-games.win/, the Cloudflare Worker behind it, and the Tauri desktop/Android shells — all from this one directory.
It is read-only for visitors. Sign-in, in-browser editing and client-side
GPG signing were removed in September 2026; the only write path left is
/admin, a separate Svelte app (admin/) that is embedded in the Worker and
served only behind Cloudflare Access. See docs/ADMIN.md.
Stack
- SvelteKit 2 + Svelte 5 (runes), prerendered to static HTML by
@sveltejs/adapter-static - Vite 8 (Rolldown) + TypeScript
- Tailwind CSS 4 — as a Vite plugin; there is no
tailwind.config.tsand no PostCSS config - Bits UI primitives, @lucide/svelte icons, svelte-sonner toasts
- Apache ECharts 6 (
echarts/core+ an explicituse()list) andecharts-wordcloud - @tanstack/svelte-virtual for the 3,600-row table
- Fuse.js (fuzzy search), idb-keyval (IndexedDB cache)
- unified / remark / rehype — build time only, for
/legal/* - Three self-hosted variable typefaces: Bricolage Grotesque, IBM Plex Sans, JetBrains Mono
State is plain Svelte 5 runes in .svelte.ts modules. There is no store
library and no data-fetching library.
The browser contacts two third parties, both only after the reader accepts the
terms and neither in the packaged apps: the Cloudflare Web Analytics beacon,
and Cloudflare Turnstile for the once-a-day human check (src/lib/human-check.ts,
docs/SECURITY_SETUP.md section 12). Everything else
is same-origin, through the Worker.
Quick start
cd web
npm install
npm run dev # http://localhost:5173 — proxies /api and /img to production
npm run build # -> web/dist
npm run dev serves only the app. It does not run worker/; /api/* and
/img/* are proxied to the deployed site so you get real data and real images.
The human check is switched off there, because production would refuse a
localhost token (npm run preview proxies the same way and cannot pass it).
To exercise Worker code, run the Worker and the built assets together:
cp .dev.vars.example .dev.vars # once: Cloudflare's always-pass Turnstile test secret
node node_modules/wrangler/bin/wrangler.js dev --config wrangler.jsonc
Where the data comes from
The browser never talks to GitHub. Everything is same-origin through the Worker:
/api/data/data/index.json— shard manifest (max_per_file,total,last_updated,files)/api/data/p1/data_001.bin, … — the shards the app actually reads: each committed file deflated and wrapped byshared/data-pack.ts(AES-GCM under a public key - obfuscation and ~85% less transfer, not secrecy). The app unpacks them to the exact committed bytes before the usual hash check. The plain shards below stay for released apps; the readable dataset is the repository itself/api/data/data/data_001.jsonl, … — record shards/img/{s|d}/<appid>/...— Steam artwork: AVIF (230 / 460 px) for browsers that accept it, read from the R2 copies the Worker's cron mints, otherwise Steam's JPEG./img/{t|d2}/...are always the JPEG (released apps, og:image). The request path never transforms (worker/routes/img.ts)/img/gh/{u|in}/{id}— GitHub avatars for/activity/api/activity— recent commits, soapi.github.comis absent from the site'sconnect-src/api/human-check—POSTonly, same-origin only: verifies the Turnstile token with theTURNSTILE_SECRETsecret. It answers yes or no and grants nothing else; no route above requires a pass (docs/ToS.md§9)
index.json lists a SHA-256 for every shard. The app requests shards as
?v=<sha256> (packed or plain), which the Worker serves content-addressed and immutable (or 503s
while GitHub's CDN still has the previous bytes), and hashes what it receives
before caching it. IndexedDB holds the last generation that verified, as the
packs it arrived in (opaque Uint8Arrays, src/lib/cache.ts); the app
re-checks the index when the tab regains focus and every ten minutes while it is
visible, and falls back to that cache offline.
Layout
web/
├── src/
│ ├── routes/ # pages; +layout, +error, sitemap.xml
│ ├── params/ # route param matchers (legal document slugs)
│ ├── lib/
│ │ ├── *.svelte.ts # rune state: games, filters, prefs, i18n, pwa
│ │ ├── schema.ts # mirrors scripts/core/constants.py
│ │ ├── games-loader.ts # verified shard generations, offline fallback
│ │ ├── cache.ts # IndexedDB read/write
│ │ ├── fallback-route.ts # re-renders routes served the SPA shell
│ │ ├── consent.svelte.ts # legal consent, hashed per document
│ │ ├── diff.ts # the line diff the consent gate shows
│ │ ├── analytics.ts # the beacon, appended only after consent
│ │ ├── human-check.ts # the Turnstile check's rules (+ -state.svelte.ts, turnstile.ts)
│ │ ├── gates.ts # the routes no first-run gate covers
│ │ ├── charts/ # EChart wrapper, registration, ChartPage
│ │ ├── common/ # Seo, ConsentGate, HumanCheck, QueryState, ErrorView, …
│ │ ├── games/ # virtualised table, columns, filtering
│ │ ├── server/markdown.ts # /legal/* rendering, BUILD TIME ONLY
│ │ └── ui/ # Button, Badge, Input (also used by admin/)
│ ├── styles/theme.css # design tokens, shared with admin/
│ ├── workers/jsonl-parser.ts # Web Worker
│ ├── i18n/locales/{en,vi}.json
│ ├── app.html
│ └── index.css
├── admin/ # the /admin app: own Vite build, embedded in the Worker
├── worker/ # the Cloudflare Worker (routes, lib, migrations)
├── shared/ # queue rules, API types, the human check's constants
├── build/game-seeds.ts # build-time seeds for the prerendered game pages
├── build/legal-versions.ts # content hashes + sources for the legal documents
├── src-tauri/ # desktop + Android shell
├── static/ # _headers, robots.txt, security.txt, generated art
├── scripts/verify-dist.mjs # checks the built output (run in CI)
├── scripts/gen-fontface.py # subsetted @font-face rules
├── scripts/gen-icons.py # icons + og.png, from static/icon.svg
├── svelte.config.js # adapter, CSP, prerender entries
└── wrangler.jsonc # Worker + static-asset config
src/static/ art is generated — icon.svg is the only mark you edit by hand.
Rendering
Every route is prerendered, including one page per game on the web build: the
gameSeeds Vite plugin (build/game-seeds.ts) reads ../data at build time,
and each page carries the slow-changing fields as a #game-seed block that
the same universal load reads back while hydrating. Player counts and reviews
are never seeded; they come from the live catalogue. The Tauri build
prerenders no game pages, and /developers/[name] and /publishers/[name] are
never prerendered: those are served the app shell and rendered from the
catalogue.
Two things about that are load-bearing and easy to break — both are explained
at length in svelte.config.js and src/lib/fallback-route.ts:
kit.paths.relativeis false. The default (true) gives prerendered pages relative asset URLs, which resolve against the wrong directory the moment a page is served as the fallback.- Both hosts answer an unmatched path with
index.html— the prerendered dashboard — and a prerendered page hydrates as its own route.fallback-route.tscorrects that on first mount for the routes that can fall back, and an unmatched URL renders the 404 in place.
Content-Security-Policy
Owned by kit.csp in svelte.config.js and emitted as a <meta> tag with the
sha256 of SvelteKit's inline bootstrap. It is deliberately not in
static/_headers: browsers enforce the intersection of header and meta
policies, so a script-src 'self' header blocks that script whatever the meta
says, and the app renders but never hydrates.
The policy has two flavours, selected by TAURI_ENV_PLATFORM. Under Tauri the
origin is tauri://localhost (or http://tauri.localhost on Windows and
Android), so 'self' is the bundle rather than the site and the packaged apps
need the site's origin named explicitly. The web flavour alone names
static.cloudflareinsights.com in script-src and cloudflareinsights.com in
connect-src, for the analytics beacon (lib/analytics.ts), and
challenges.cloudflare.com in script-src and frame-src, for the Turnstile
human check (lib/turnstile.ts); verify-dist.mjs fails the web build without
them and the Tauri build with any of them.
Cloudflare's automatic Web Analytics injection can never be used here: it
adds an inline loader at the edge, after this response, and CSP3 makes a
script-src carrying a hash ignore 'unsafe-inline'. The dashboard must stay
on "Enable with JS Snippet installation".
frame-ancestors is ignored in a meta CSP, so X-Frame-Options: DENY in
static/_headers is what stops framing.
PWA
@vite-pwa/sveltekit builds a Workbox service worker, registered only after
the legal consent step and the human check, and never in the Tauri build (a
worker at tauri.localhost can never update).
- Updates prompt ("Update available" → Reload) rather than swapping the app under an open page, and the worker checks for a new version hourly.
/api/data/*is not cached by the worker. IndexedDB is the offline store, and only for a generation whose hashes verified./img/*is CacheFirst for 30 days, status 200 only. Steam's?t=is an asset mtime, so a changed image arrives as a different URL.- The prerendered game pages are left out of the precache (they would add about 120 MB).
navigateFallbackis/, not/200.html.adapter-staticwrites the fallback after Workbox has globbed the build output, so/200.htmlcould never be a precache entry andcreateHandlerBoundToURL()threw on every load./is both precached and what Cloudflare and Tauri already serve for an unmatched path, solib/fallback-route.tsrecovers the route offline exactly as it does online.verify-dist.mjschecks the two agree./api/*,/img/*and/adminare on the navigation-fallback denylist. An installed worker answering/adminfrom the app shell would serve the public shell where the Access gate belongs.
i18n
Two bundles in src/i18n/locales/{en,vi}.json, loaded by src/lib/i18n.svelte.ts.
English is statically bundled as the fallback so prerendered HTML contains real
strings; a Vietnamese visitor's bundle swaps in on hydration. The choice
persists in localStorage under f2p:lang.
Long-form legal copy stays English on purpose — keeping the wording byte-identical across languages avoids weakening it in translation.
src/lib/i18n.test.ts scans the source and fails on a key that does not
exist, a placeholder a call site does not fill, a template-literal key, an
English key nothing uses any more, and a Vietnamese value that is just the
English copied across (names and formats are allowlisted there).
Legal consent, and showing what changed
lib/common/ConsentGate.svelte is an overlay, not a replacement for the page —
onMount does not run during prerender, so gating the markup behind it would
ship an empty body. Only /error/* and /legal/* are exempt (lib/gates.ts,
shared with the human check): the gate links to the documents it asks people
to accept.
Each binding document is hashed at build time. build/legal-versions.ts serves
two virtual modules:
virtual:legal-versions— a hash per document slug. Tiny, imported statically, so the gate can decide whether anything changed without a fetch.virtual:legal-sources— the raw markdown, ~25 KB. Imported dynamically, by the gate alone, so a page load that never opens it never downloads it.
When a hash differs from the one stored at acceptance, the gate reopens by
itself and lists only those documents, each as a line diff (lib/diff.ts)
against the copy in f2p:legal_snapshot — rendered as text in a <pre>, never
{@html}. With no snapshot (storage cleared, or an acceptance predating the
feature) it links to the full document instead.
TERMS_VERSION in lib/consent.svelte.ts survives only as the "make everyone
re-read all six" override; an ordinary edit no longer needs anyone to remember
it. Consent lives in its own module rather than lib/prefs.svelte.ts because
the admin SPA compiles that file with its own Vite config, which cannot resolve
a virtual module.
The human check
After consent, lib/common/HumanCheck.svelte — the same kind of overlay —
asks each browser to pass Cloudflare Turnstile at most once every 24 hours,
and the Worker verifies the token at /api/human-check. It is web only, off
under npm run dev, and soft by design: it keeps automated browsers from
using the app, but nothing on the server requires a pass, because the pages
are static and docs/ToS.md §9 keeps /api/data/* and /img/* open. It
refuses only on a verdict from Cloudflare and lets the reader through, for that
page load, whenever the fault is the site's or the reader is offline.
lib/human-check.ts has the rules and their reasons;
docs/SECURITY_SETUP.md section 12 has the widget
settings, the secret and the local test keys.
Analytics
lib/analytics.ts appends the Cloudflare Web Analytics beacon from the same
$effect that gates the catalogue fetch and the service worker on
consent.accepted and the human check, so nothing reaches a third party before
the reader accepts. It returns early under isTauri() and when
CF_BEACON_TOKEN is empty, which is what a fork gets.
Desktop and Android
npm run tauri:dev
npm run tauri:build # -> src-tauri/target/release/bundle
npm run tauri:android:build # -> APK
Needs a Rust toolchain locally; the release workflows install one. The window is 1280×860, resizable, minimum 880×600 — it was pinned to a fixed 1400×900 until 2.0.0.
The packaged apps use real paths, not hash routes:
tauri::manager::get_asset() resolves /games/730 through its own fallback
chain. Hash URLs from released 1.4.x builds are still upgraded on load by
upgradeLegacyHashUrl().
To cut a release, push a desktop-v* or android-v* tag. Both workflows
publish a draft release — smoke-test the binaries before publishing.
Schema sync
MANUAL_FIELDS and the record shape in
src/lib/schema.ts mirror
scripts/core/constants.py, and so do the
anti-cheat patterns in src/lib/anti-cheat.ts
(anti-cheat.test.ts holds those equal). Change one, change the other.
Deployment
Pushing to main triggers Cloudflare Workers Builds, which runs the build and
deploys the Worker together with dist/ as static assets. The reliable signal
is the Workers Builds: free-steam-games-list check run — wrangler deployments list lags several minutes behind reality.
.github/workflows/deploy-pages.yml no longer deploys anything; GitHub Pages
serves a client-side redirect to the new domain while old inbound links drain.
See docs/DEPLOYMENT.md and docs/ADMIN.md.
Checks
npm run typecheck # builds admin/, then svelte-check (app on TS 7, admin on TS 6) and TS 7's tsc (Worker, tests)
npm test # vitest
npm run knip # dead code and dependencies
npm run build # site, then admin/
node scripts/verify-dist.mjs --web
node node_modules/wrangler/bin/wrangler.js deploy --dry-run --config wrangler.jsonc