Dependabot #190-#194 combined with Zustand 5.1.0, soupsieve 4.1, coverage 7.17.3, Ruff 0.17.5 and a cargo update (wry 0.57.2, tauri-plugin-opener 2.7.3), each past a 3-day cooldown; Wrangler 4.161.0 with regenerated Worker types; tapable held at 2.3.3. Version 4.6.2 with a short changelog entry.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The project moves to maintenance mode (stable, feature-complete): docs, templates and badges (EN + VI). Qodana analysis in CI for the TypeScript / JavaScript, Python and Rust projects, with the findings of its first reports fixed. Version 4.6.1.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Issue #186 suggested a game whose itch.io page has no upload and no
browser build: the game comes from a launcher on the developer's own
site, behind an account. The scraper sees no buy row and calls such a
page free, and nothing in the contributing guide or the Add Games
templates said it doesn't qualify, although the Disclaimer (§4) tells
visitors that any download happens on itch.io.
State the rule in CONTRIBUTING (EN + VI) and add a matching check to
the Add Games issue form and PR template. No policy text changes.
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
The 4.6.0 website passed the owner's VoiceOver test on an iPhone 14 Pro in Safari, Chrome and Brave; ACCESSIBILITY.md (+ VI) and CLAUDE.md record it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Accessibility pass for the website and the apps (WCAG 2.2 AA target) and the accessibility statement: root ACCESSIBILITY.md + docs/i18n/vi/ACCESSIBILITY.md, the accessibility issue form, a default PR template; focus management, the '/' shortcut switch, chart names and data tables, contrast tokens with a CI check, Windows contrast themes; a docs sync of verified mismatches; version 4.6.0 with the two deps sweeps since 4.5.0 (#176, #182).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The runbook's WAF test now uses a Node fetch one-liner (connection pool):
xargs curl only reached ~20 requests/s, below the rule's 300 per 10 s.
Measured 2026-10-27: 800 requests in 4.9 s -> 111 x 200, 201 x Worker 429,
488 x WAF 1015.
[skip-discuss]
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Measured on production after the 4.5.0 deploy: with a new connection per
request, 1,000 requests in 53 s got no 429 from RL_SITE (120/60 s); over
one keep-alive connection, 429 after ~93. The ratelimits binding counts per
machine of a data centre and syncs late, so the zone's WAF rule is the
limit that holds against floods. Verified once the owner set the rule
(300/10 s): 800 requests in 4.9 s gave 111 x 200, 201 x Worker 429 and
488 x WAF 1015, with the site answering again 10 s later.
Runbook test commands, code comments, CLAUDE.md gotcha 43, the 4.5.0
changelog entry.
[skip-discuss]
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every request that runs the Worker is counted per client (IPv4, or IPv6
/64): RL_SITE 120/min (app pages, public /api, the old apps' /data JSON,
misses), RL_IMG 600/min (covers), RL_ADMIN 300/min (/admin + /api/admin);
RL_SUGGEST 5 and RL_GATE 20 stay on top for their POSTs. Verified bots are
not counted. Over a limit: 429 + Retry-After 60 (JSON for the API, covers,
files and /data with CORS; a script-less EN/VI page for app pages). Fails
open.
Every rate-limit namespace moves to 8801-8806 (staging 8901-8906):
namespace ids are account-wide, and other Workers on the account use
1001-1006, so RL_SUGGEST / RL_GATE shared their counters.
docs/operations.md section 1 step 15: the zone's WAF rate-limiting rule as
the first layer (Free plan: one rule, IP, 10 s; 300 requests / 10 s).
[skip-discuss]
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SonarQube Cloud analyses in GitHub Actions instead of Automatic
Analysis, with test coverage (sonarcloud.yml): token (skips Dependabot
and fork PRs, which get no SONAR_TOKEN) → coverage (pytest-cov and
Vitest v8, no secrets) → scan (sonarqube-scan-action v8.3.0, full
history, sonar.projectVersion from webapp/package.json).
sonar-project.properties replaces .sonarcloud.properties: tests marked
as tests, coverage exclusions for code without unit tests by design,
Python 3.14 (the analyzer has no 3.15 yet), binary images and the
SQLite migrations (claimed by the PL/SQL analyzer, which only warned)
left out.
Adds pytest-cov / coverage (dev lock recompiled on Python 3.14) and
@vitest/coverage-v8 (Dependabot group with vitest). Docs: CLAUDE.md
gotcha 41, THIRD_PARTY, dev_env, CONTRIBUTING (EN + VI).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The first SonarQube Cloud scan reported 57 issues. 45 are fixed in code, the 11 on the saved itch.io test pages leave the scan via .sonarcloud.properties, and css:S8776 (Tailwind's @utility nesting) is a false positive to mark on SonarQube Cloud.
Worker: trailing slashes and the gate cookie's padding are trimmed by trimEnd() instead of /\/+$/ (quadratic on the public 404 path); the feed and collection parsers lose their backtracking regexes; compareCodeUnits keeps the code-unit sorts (the rule's localeCompare is locale-dependent); Number.*, DEFAULT_SIZES, crypto.randomUUID; i18n-edit.mjs reads stdin. Pipeline: the NSFW notices are one selector list, either class (the rule's ".a.b" would need both), each tested; plain if-guards; update_info.main returns None; no plain-http adapter; [[ ]] in cf_build_status.sh.
Supply chain: requirements*.txt are hash-locked pip-tools compiles of requirements*.in (on Python 3.14, which Dependabot reads from the header), installed with --require-hashes --only-binary :all: in block scalars; npm ci --ignore-scripts in CI and the release builds (verified by manual release runs on all platforms); npm run cf:check.
Release 4.4.2: also ships the toolchain upgrade (#149, #154) and Dependabot #141-#148, #150, #152, #153. CLAUDE.md gotchas 40 and 41.
[skip-discuss]
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dependabot's pip updater reads .python-version and supports Python
3.10-3.14 only, so the 3.15 pin from the toolchain upgrade aborted both
the pip version updates and the pip dependency graph ("Dependabot
detected the following Python requirement for your project: '3.15.*'").
The pin now lives in .github/python-version, read only by setup-python's
python-version-file (python-ci, refresh scan + apply, update); Dependabot
falls back to its default 3.14, which every pinned package supports.
Move it back once Dependabot lists 3.15 (CLAUDE.md gotcha 39).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TypeScript 7.0.2 (the native compiler) now runs `tsc -b` in `npm run build`.
It has no JavaScript API until 7.1, and typescript-eslint (peer
typescript <6.1) and scripts/i18n-edit.mjs need one, so the two are
installed side by side: `@typescript/native` = npm:typescript@^7.0.2
(bin tsc) and `typescript` = npm:@typescript/typescript6@^6.0.2 (the 6.0
API, bin tsc6). No tsconfig or source change: TS 7 reports 0 errors.
Node 26: webapp/.node-version 24 -> 26 (CI and both release workflows read
it), engines >=26, @types/node 26. npm 11.20 gates dependency install
scripts on `allowScripts`, so esbuild and workerd are approved by name.
Python 3.15: .python-version 3.14 -> 3.15, ruff target py315, urllib3
declared (scraper.py imports it). UTF-8 mode is the default since 3.15,
so the workflows drop PYTHONUTF8.
Dependabot: keep the `typescript` alias off new majors, group
@typescript/*, @types/node up to 26. Docs and CLAUDE.md follow (gotcha 6
rewritten, gotcha 38 for allowScripts).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The browser extension (poli0981/itch-f2p-extension) and the Telegram bot (poli0981/telegram-scraper-bot) are archived. Removed: POST /api/ingest (ingest.ts, requireService, the idempotency store, RL_INGEST, ACCESS_AUD_INGEST; it never received a game), the admin's "Browser extension" auto-approve source and "Extension" queue label, and the About page's Telegram numeric-ID note. No D1 migration: the idempotency table and the 'ext' CHECK stay.
Policies (Privacy, ToS, EULA + installer RTF, Disclaimer, Security; EN + VI) drop the extension / ingest wording; Last updated 2026-10-16, LEGAL_VERSION unchanged. Docs, CLAUDE.md and pipeline comments updated.
Release 4.4.1 (also ships #131, #135, #136, #137).
[skip-discuss]
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Admin: add games from any list or itch.io collection (Check first, batches of 200, per-game ingest tracking from scripts/state/ingest_outcomes.json), followed collections and auto-approve run by the cron in one [auto] commit, bulk remove/edit up to 100 games in one commit, New games, Activity and Settings pages. D1 migration 0002 (applied to production before this merge). Policies (ToS, Privacy, Disclaimer, EN + VI) cover approval by the maintainer's rules; LEGAL_VERSION 2026-10-13.
Web: the theme button shows the theme in use, no dark-mode flash (pre-paint script, hash in three CSPs), Charts tabs stay mounted (no rebuilt charts or replayed animations), 300 ms entrances, scrollbar gutter on mouse devices.
Release 4.4.0 (changelog also covers #130).
[skip-discuss]
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Below md: a one-row tab bar (the Vietnamese labels had wrapped out of the
fixed-height bar), 12px legends and 11px ticks, horizontal Languages and
Avg session bars, the reason under each recent deletion, the KPI total
across the row, a taller Genres card.
At every size: all 15 Genre labels on one line (Recharts had hidden 8,
the two largest included), pie legends in data order with muted text,
translated removal reasons (reasonKey in lib/deleted-reason), locale axis
numbers, treemap labels that fit their cells, no "(made_with[0])" in the
engine chart's description. CLAUDE.md: chart notes, gotcha 32 and the
unreleased-on-main note.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
itch.io answers a password-protected game with HTTP 200 and its password form (div.game_password_page / input[name=game_password]); the refresh counted it as a parse failure forever. scraper.is_password_protected() recognises it; refresh gives a "private" strike ("Game page is password-protected", removed when seen again >= 20 h later, counted by the mass-change guard); update_info drops such links as a final outcome; the Removed page and Deletion Reasons chart label the reason (EN/VI). CLAUDE.md names the new signing key 838884804847BE7AE5FCF0A96AD1AB0921B96825; 03F965C2E2DB5C6B is revoked.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dependabot moved the npm package to 2.7.0 (#109) while Cargo.lock kept the crate at 2.6.0; `tauri build` refuses mismatched major/minor versions, so every v4.3.0 release build failed before compiling. `cargo update -p tauri-plugin-opener` locks 2.7.0 and drops the windows 0.61 crates only 2.6.0 used. Checked with `npx tauri info` and `cargo check --locked`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
force_update.yml called refresh.yml through `uses:` and failed at startup ("workflow file issue", no annotation); it had never run since v4. It now dispatches refresh.yml with full=true (new workflow_dispatch input; refresh.yml drops workflow_call). refresh.yml's scan checks out the branch as it is when the job starts, so runs waiting in the refresh-pipeline queue see the previous run's state and consecutive force-update dispatches cover consecutive batches. Verified end to end on the branch (one URL re-scraped and applied to main as f03211d).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
itch.io game pages now carry an "AI Disclosure" row (AI Assisted, then what it was used for), a "Content" row ("No generative AI was used", /games/tag-no-ai) and an "Accessibility" row. The scraper reads them into three optional fields (ai_disclosure, ai_content, accessibility), which the daily refresh keeps current; description becomes the creator's tagline (og:description), else the first sentence as before; whitespace inside titles and links is collapsed. A --full re-scrape keeps a known release_date / thumbnail (itch.io shows "Published" only for a few weeks).
Web app: "Generative AI" and "Accessibility" filters on /games (?ai=, ?access=), game-page rows, three charts (Overview: Generative AI; Discovery: Accessibility Features, What AI Was Used For). EN/VI strings, docs, changelog, version 4.3.0.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both keys are inheritable in wrangler, so staging already resolves to
false from the top level (checked with unstable_readConfig). Vars,
bindings and the empty crons override stay: those are not inherited.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
- Catalog packs: the build emits /data/pack/manifest-v1.json plus
content-hashed deflate-raw packs (columns + dictionaries); the site and
the apps read them (about 264 KB on a first visit instead of about 520 KB
of JSON). Descriptions live in their own packs and load on demand (a game
page: its chunk; a search: all of them).
- The IndexedDB cache is stored as compressed bytes by a small binary
persister (replaces @tanstack/query-async-storage-persister); fflate is
the lazy fallback where the browser has no Compression Streams.
- The readable /data/*.json goes only to apps 4.0-4.1.1 (Tauri Origin);
everyone else gets a 410 with links to the repository
(worker/legacy-data.ts, five positive run_worker_first entries).
- /img: exact width strings only, fallback originals and missing images
kept at the edge for a day, failed background puts are logged.
- Themed scrollbars and a "Hide scrollbars" setting (Settings and the
display menu); chart cards no longer block their list scrollbars.
- Policies (LEGAL_VERSION 2026-10-03): data reuse goes through the
repository. Docs, changelog and version 4.2.0.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- contact@ / legal@ / privacy@ / security@ / takedown@poli0981.dev
(Google Workspace aliases) replace the @freeitchgames.win addresses in
the policies (EN + VI), READMEs, issue templates, security.txt and the
installer EULA.
- Privacy Policy: Google Workspace replaces Cloudflare Email Routing as
the email processor (provider table, transfers, contact section).
- About page: website, contact email and the poli0981.dev/links hub;
mailto: links open without a blank tab; the apps may open mailto:.
- LEGAL_VERSION 2026-09-29, so the legal gate asks once more.
- Version 4.1.1 (about.ts, package.json, tauri.conf.json, Cargo.toml/lock).
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
- operations.md: verification gate setup (bot token, Transform Rule,
header check, GATE_SECRET last, smoke tests, off switch); Web Analytics
is injected by the zone (checked live), not a build token; staging is
deployed by hand from any branch; a release checklist replaces the
finished v4 release order; the unused repo secrets can go.
- CLAUDE.md: gate, chart and changelog notes, three new gotchas, current
counts, .rpm, announce-discussion.yml is local, current state.
- READMEs (EN/VI): the quick check, list layout on phones, .rpm,
TanStack Query only, the build monitor, cf_build_status.sh.
- dev_env (EN/VI): GATE_* secrets, PKCS#1 keys work as downloaded.
- webapp/README, TAURI.md, THIRD_PARTY.md, CONTRIBUTING (EN/VI): lazy
routes, .rpm, Cargo.lock is committed, squash or merge commit.
- _headers: caching for favicon.svg and the web manifest; comments.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CHANGELOG.md had grown to 805 lines across four major versions. The
notes now live in changelog/<major>.x/ver<major>.<minor>.x.md (newest
first); CHANGELOG.md is the index. Each index row keeps the anchor of the
old single-file heading, so the release notes that link to
CHANGELOG.md#<entry> still land on the right row.
- Entries moved verbatim; repo-relative links rebased (../../), links to
files deleted since are pinned to the release's tag.
- Dated 1.0.2 and 1.0.3 (both released 2026-01-01); short entries that
point to the GitHub release for 3.0.1, 3.1.0 and 3.1.1, which never
had one; the "gotcha #18" reference now names the gotcha instead.
- 4.1.0 notes added.
- announce-discussion.yml also watches changelog/**.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Privacy Policy said the Project's code sets no cookies and that
Turnstile runs only on the Suggest page. With the verification gate:
- Privacy (EN/VI): the Turnstile check before the site loads (about once
per 48 hours, verified bots exempt, /data open), the __Host-fig_gate
cookie (issue time + signature, 48 h, strictly necessary), the
webapp.gate storage entry, retention, Cloudflare's role.
- ToS (EN/VI): don't circumvent the verification check or share its cookie.
- EULA (EN/VI/RTF): list the .rpm package v4.0.0 already shipped.
- LEGAL_VERSION and the About page date → 2026-09-24, so the legal gate
asks everyone once more.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Until a visitor passes a Cloudflare Turnstile check, app pages ("/" is
now Worker-first too) answer with a self-contained verification page and
/img covers with 403, so a browser loads nothing of the site before the
check. Passing sets an HttpOnly, host-only cookie (HMAC of its issue
time) good for BOT_GATE_TTL_HOURS (48). The page then reloads into the
link that was asked for, and the legal gate follows as before.
- /assets, /data (desktop/Android apps, CC BY reuse), robots, sitemap,
og image, /api/* and /admin* stay ungated.
- Verified bots pass with the token a zone Transform Rule adds
(x-fig-known-bot); clients that only claim to be a search crawler get
a 503, never the noindex page.
- Fails open: it needs BOT_GATE="on", the Turnstile keys, GATE_SECRET
and GATE_BOT_TOKEN; deleting GATE_SECRET switches it off at once.
- POST /api/verify: same-origin, RL_GATE (IPv4 / IPv6 /64), siteverify
with action "gate". GET reports the pass for the page and the SPA.
- turnstile.ts: siteverify shared with Suggest, which now also checks
the hostname and action (a token from one page can't be spent on the
other) and answers 503 when Turnstile is unreachable.
- SPA: a tab whose pass ran out re-checks when shown again or when a
cover fails, and reloads into the verification page.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The chart colours wrapped the hex design tokens in hsl() ("hsl(#efefec)"),
an invalid colour: SVG painted the bar hover band black and the tooltip
lost its background and border. Recharts 3 also focuses the chart on a
mouse click, so Chromium drew its focus ring and pinned the tooltip on
the first item.
- chart-theme.ts: shared Tooltip props and cursors using var(--x).
- chart-tooltip.tsx: one tooltip body for every chart (popover colours,
series swatch, locale-formatted numbers, share of the whole on the
pies that cover it, formatted dates on the count chart).
- Translated series names instead of the raw dataKey ("count").
- Pie seams and treemap cells use the card/background tokens.
- Clicks no longer move focus into a chart; keyboard focus keeps the
--ring outline.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Approving from the queue failed with 500 "internal_error"; the Worker log
said: TypeError: "pkcs8" must be PKCS#8 formatted string. GitHub downloads
App keys as PKCS#1, which WebCrypto cannot import.
- github.ts wraps a PKCS#1 PEM into PKCS#8 itself (and turns two-character
"
" escapes into newlines), so the downloaded key works unchanged.
- GitHub failures throw GitHubError and the admin API answers 502
github_error with the reason, instead of a bare internal error.
- Admin CSP allows the Cloudflare beacon the zone injects into every HTML
response; dropped browsing-topics from Permissions-Policy (Chrome no
longer knows the feature and logs an error on every page).
- Docs: the key needs no openssl conversion any more.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- wrangler.jsonc vars now hold the production values set in the dashboard
(GitHub App ids, Access team domain and AUD tags, Turnstile site key).
A deploy replaces plain-text variables with the file's values, so the
next data commit would have blanked them.
- access.ts: ignore a trailing slash in ACCESS_TEAM_DOMAIN (the issuer is
the bare origin; the dashboard value had one).
- /admin redirects to /admin/ (the path the Access application covers), so
the visitor gets the login page instead of a 403.
- Runbook: values must be changed in the file.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Implements the approved mockup (Free Itch Games, dark and light).
- Tailwind CSS 4 via @tailwindcss/vite (no PostCSS / tailwind.config), design
tokens in src/index.css, tw-animate-css, self-hosted Geist / Geist Mono.
- A sticky top nav (global search with the / shortcut, display menu for
theme / language / density / 18+, phone sheet menu) and a footer replace the
sidebar; the window scrolls, with scroll restoration on back / forward.
- Welcome page at / (catalog status, features, recently added) replaces the
dashboard.
- Games: search, genre / platform / status / tags / language / input / engine,
minimum rating, plays-in-browser, sort and page live in the URL
(lib/game-filters.ts, unit-tested); facet counts ignore their own filter;
a table on desktop, a list on phones, 100 per page. Counts show the whole
catalog while 18+ games are hidden.
- New game detail page (breadcrumb back to the same list, facts, tags that
open the matching list, copy link, report a problem), searchable Removed
page, simpler Settings, restyled error pages and charts header.
- Legal gate is an overlay above the page (deep links land where they
pointed), with translated document names; no "Leave" button in the apps.
- Cached data stays on screen when a background refresh fails (offline).
- Numbers and dates follow the language (lib/format.ts).
- New favicon, PWA icons and OG image from the same tokens
(scripts/gen_assets.py uses the Geist fonts from node_modules).
- Removed: sidebar, dashboard, data-table components, TanStack Table /
Virtual, sonner and toast settings, the unused Select primitive; 81 unused
i18n keys; prefs now persist only the keys still in use.
- Review fixes: routers without startTransition (useSearchParams was stale,
so quick filter clicks and typed searches overwrote each other or pulled
the visitor back from a game); paging starts at the top and Back returns
to the old position; the 18+ confirmation is an in-app dialog
(window.confirm is a no-op in the macOS app); the apps show only the legal
gate until it is accepted (covers load from itch.io there); breadcrumb goes
back; named popovers, list semantics, IME-safe Enter, English plurals,
pointer cursor, --brand-soft without color-mix, copy-link fallback.
- wrangler.jsonc: id of the production D1 database (created by command,
0001_init applied); runbook notes that R2 must be enabled first.
- Docs: CLAUDE.md, CHANGELOG, webapp README / TAURI.md, THIRD_PARTY,
ACKNOWLEDGEMENTS, docs/operations.md; Dependabot groups for Tailwind 4.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Licenses
- Code stays MIT (LICENSE: 2025-2026 poli0981 (SkullMute)). The catalog
data (data_game/LICENSE.md) and the documentation are CC BY 4.0 (full
legal code in LICENSES/CC-BY-4.0.txt); creators' descriptions, cover
images, names and trademarks are excluded. NOTICE.md: license map and
non-affiliation with itch.io.
Policies (English + Vietnamese mirrors, dated 2026-09-18, applying from
4.0.0)
- Terms of Use now cover the website and the public data, with the
content-removal / copyright process, prohibited uses (bulk scraping,
/img abuse, /admin and ingest access, Suggest spam), 18+ opt-in and
Vietnamese law with the consumer-rights reservation.
- Privacy Policy rewritten for Cloudflare as processor: exact browser
storage, cookies, Turnstile, D1 retention (Suggest notes 180 days,
idempotency 7 days), rights under Law No. 91/2025/QH15 and the GDPR.
- EULA covers only the desktop and Android apps (also the installer RTF).
- Disclaimer, Security Policy (private reporting, scope, safe harbor) and
Code of Conduct (Contributor Covenant 2.1) rewritten; PAT, GPG and
Telegram-bot material removed.
Docs and templates
- README / CONTRIBUTING (EN + VI), webapp/README, TAURI.md, dev_env
(EN + VI), THIRD_PARTY, ACKNOWLEDGEMENTS; new docs/operations.md
(Cloudflare + GitHub setup, v4 release order, routine tasks).
- CLAUDE.md rewritten for the v4 architecture; CHANGELOG [4.0.0].
- Issue templates: config.yml (Suggest page + private security reports),
"Add games" points to /suggest, "Remove a game" gained a rights-holder
section; PR templates updated; CODEOWNERS.
- Dependabot npm version updates resume with the v4 merge (limit 5).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Worker
- The local DEV_ADMIN_EMAIL bypass keeps the same-origin check for
writes, and JSON bodies must be exactly application/json (a cross-site
`text/plain; application/json` POST no longer gets through without a
preflight).
- Request bodies are capped while they stream (a chunked upload without
Content-Length is never buffered past 4 KB / 64 KB).
- count_history.json is rewritten when today's row already exists
(upsertCountHistory no longer mutates the rows it was given).
- A game that entered the catalog through the queue, was removed and turns
up again is reviewed again (flagged previously removed) instead of being
blocked as "already pending" for good.
- Restoring / approving a removed game no longer deletes its public
removal record up front: the Worker allow-lists it in
scripts/state/unblocked.json, update_info.py scrapes it despite the
deleted log, and apply_patch.py drops the log entry only when the game is
really re-added (a still-paid or dead game keeps its record).
Admin app
- The editor compares against what the repository holds (published data
or what was saved in this session), so saved changes can be reverted and
are never dropped silently.
- An Access session that expires mid-session shows a sign-in banner from
any request, without losing what is on the page.
- Restore refreshes the queue; knip now checks the admin entry.
Suggest page
- The form doesn't let the browser's URL check block links without
https:// (the page and the server accept them).
- A failed config request shows an error with Retry instead of a
permanently disabled form or a false "closed" message.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The cookieless beacon is added to the public page only when the web build
has VITE_CF_BEACON_TOKEN (Workers Builds variable; manual site setup with
automatic injection off), never to the admin page or the Tauri apps. The
site CSP already allows it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Games marked nsfw=Yes are left out of the table, dashboard and charts
unless the visitor opts in (Settings -> Content, after confirming they
are 18+; stored only in this browser). Their detail pages show a notice
instead. The admin app still sees everything.
- /deleted is now /removed (301 from the Worker, redirect in the SPA,
sitemap and canonical updated); <html lang> follows the language.
- Legal links: the gate lists only the documents being accepted (ToS,
Privacy, Disclaimer, and the EULA inside the apps) and asks to confirm
the visitor is 16+; new "Licenses & notice", "Data license" and
"Content removal" links; the retired Telegram bot link is gone.
LEGAL_VERSION 2026-09-18, so everyone is asked once more.
- Version 4.0.0 in about.ts, package.json (+ "license": "MIT"),
tauri.conf.json (+ bundle copyright), Cargo.toml / Cargo.lock.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- webapp/admin/: a second Vite entry (/admin/, HashRouter), served only
by the Worker after the Access check, with its own CSP. Review queue by
status (approve, approve with override for previously removed games,
reject), paste-to-add URLs, and a catalog editor for the three
maintainer fields, removal with a public reason, and restore of removed
games. Uses the published /data for search; every write is applied to
the latest repository state by the Worker. An expired Access session
surfaces as "sign in again" instead of a broken request.
- /suggest (web only; the desktop/Android apps link to the website):
itch.io link + optional note (<= 500 characters, deleted after 180
days), Cloudflare Turnstile loaded on demand, EN + VI strings.
- Local development: DEV_ADMIN_EMAIL in .dev.vars lets `wrangler dev` on
localhost into the admin without Access; it is ignored on any other host.
Checked in wrangler dev with a local D1: queue listing, reject, approve
answering "GitHub App not configured", catalog search/editor, and a
Suggest submission (Turnstile test keys) landing in the queue; no CSP
violations.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds the server side of the admin and the automatic game discovery. The
catalog stays JSON in this repo; the Worker writes it as a GitHub App
(GraphQL createCommitOnBranch with expectedHeadOid: verified commits,
retried on a race) and keeps only the review queue in D1.
- worker/admin.ts: /api/admin/* (queue list, approve/reject, add, edit the
three maintainer fields, remove with reason + R2 cover cleanup, restore)
and the /admin shell with its own CSP. Every request re-verifies the
Cloudflare Access JWT (aud + maintainer email + same-origin writes).
Approving commits to scripts/temp_link.json, which starts update.yml.
The maintainer's email goes to the D1 audit log only, never a commit.
- worker/ingest.ts: POST /api/ingest for the browser extension (Access
service token, per-client rate limit, Idempotency-Key replay, <= 150
items / 64 KB), replacing its PAT commits.
- worker/suggest.ts: public POST /api/suggest (same-origin, per-IP rate
limit, Turnstile siteverify, canonical itch.io URL) into the queue.
- worker/discover.ts + scheduled(): every 4 h, one itch.io RSS feed
(round-robin, 6 h back-off on 429) into the queue, then reconcile
(queued -> ingested / failed) and retention (idempotency 7 d, form
notes 180 d).
- worker/queue.ts: URL classification (catalog, pending, deleted,
blocklist) and the D1 store; worker/repo.ts builds each admin commit
from the files at the head of main, byte-compatible with the Python
pipeline (golden fixtures).
- wrangler.jsonc: D1 (bound by name; migrations applied by hand), rate
limits, cron, non-secret settings as vars (empty until setup: features
answer 503 until configured), staging env without the cron.
`npm run cf:types` ignores .dev.vars so the committed types are stable.
- Tests: 159 passing; the SQL runs against a real local D1 (workerd via
wrangler's platform proxy).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Missing files no longer get the app shell: `not_found_handling: "none"`
and worker/spa.ts answer /assets/*, /data/* and file-like misses with a
real 404 (no-store). A stale hashed chunk used to get index.html with
the year-long immutable cache of /assets/*. Routes get the shell with
200; unknown paths and unknown game slugs get it with 404.
- Recharts is off the first load again (~314 -> ~195 KB gzip): drop the
vendor-charts group, which captured React and clsx, and give
vendor-react the top priority.
- Web build target restored (Safari/iOS 15.4): Vite 8's default shipped
Radix class static blocks unlowered, a blank page on iOS 15.
- The allow-list cache shares only loaded values, never an in-flight
promise: a cancelled first /img request hung every later one.
- /img answers upstream resets and R2 errors with a 502 instead of an
uncaught exception, and releases unused upstream bodies.
- Per-route canonical + robots (useSeoHead) instead of a static root
canonical and og:url on every page.
- Legacy hash redirect: crafted hashes (#//host, #/\host) go home
instead of throwing before React mounts.
- Chunk-reload guard is time-windowed and storage-safe.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
BREAKING: the public web app has no sign-in anymore and uses real paths
(BrowserRouter); /add and /workflows are gone (admin comes in Phase 4).
Platform
- wrangler.jsonc: Worker (worker/index.ts) + static assets with SPA
fallback; only /img/* and /api/* run the Worker. R2 binding THUMBS,
`staging` env for the v4 pre-release Worker. worker-configuration.d.ts
from `wrangler types` (checked in CI with --check).
- vite-plugins/catalog-data.ts bundles data_game + deleted log into
dist/data (build fails on bad JSON / index mismatch), emits urls.json
(thumbnail allow-list) and a real-path sitemap; version.json carries
the build stamp so data-only rebuilds keep identical JS.
- Data is read same-origin from /data (Tauri: https://freeitchgames.win/data,
CORS *); chunks load with allSettled.
- worker/img.ts: /img/<160|640>/<itch path> serves a WebP rendered once
per image+width by Image Transformations and stored in R2 (edge cache
→ R2 → transform); catalog allow-list, fixed upstream host, hotlink
block, streamed original on transform failure, 403/404 upstream → 404.
15 vitest cases.
- Enforced CSP (same-origin + Web Analytics/Turnstile), cache headers for
/assets, /data, og/icons; security.txt; robots disallows /api, /admin.
App
- Remove PAT/GPG sign-in, bulk edit/delete, undo, workflow dispatch,
Octokit and OpenPGP (and ~220 write-path i18n keys); Settings keeps
language/theme/density/notifications only.
- react-router 8 (unified package), React 19.3, TanStack/Recharts/etc.
minors, Vite 8 rolldown codeSplitting groups; legacy #/ links are
rewritten to paths; old PAT/GPG localStorage keys are cleared; reload
once on vite:preloadError after a deploy.
- GameThumb uses the /img proxy (referrerPolicy no-referrer, N/A-safe).
Tauri
- Real CSP, drop the unused http plugin + capability, read-only
descriptions, rust-version 1.88, drop the time pin, commit Cargo.lock.
Also: remove the GitHub Pages redirect workflow/stub (deployed by v4
Phase 0); add scripts/i18n-edit.mjs (TS-parser based key maintenance for
en.ts/vi.ts).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* feat(pipeline): rotating refresh + patch/apply pipeline, drop lists/
Replace check_paid / check_alive / update_reviews / update_status: each
crawled all 2,600+ pages sequentially, overran its job timeout, saved
only at the end and has lost every run since late June (unreported:
timeouts end as "cancelled").
- scripts/refresh.py: daily slice of ~1/7 of the catalog (pending
strikes first, then least recently checked), one GET per game for
alive / paid / rating / status (+ release_date, thumbnail, updated_at
backfill). Removal needs the same 404/410 or paid strike on two
different UTC days. Paced requests, capped Retry-After back-off, stop
after 3x 429, checkpoints and an in-script deadline. --full replaces
force_update.py (rotating batches, editable fields preserved).
- Scanners emit a URL-keyed patch (patch.py); apply_patch.py applies it
to the latest main and runs validate.py; bash/commit_push.sh fetches,
re-applies and retries pushes, so concurrent writers never clobber
each other.
- update_info.py: canonical URLs (canonical.py), skip games in the
deleted log, keep transient failures queued (max 3 runs, tracked in
scripts/state/), stamp added_at, never drop links queued meanwhile.
- data_store.py: games stay in their chunk, re-slice only past
thresholds, write only changed bytes; index/count_history change only
with data (no more no-op commits).
- validate.py (schema, enums, canonical/unique URLs, index consistency)
+ normalize one invalid safe_virus ("y" -> "Yes").
- tests/: 85 network-free pytest cases, HTML fixtures (from sample/),
shared URL vectors and golden chunk/serialization fixtures for the
future Worker port.
- Workflows: refresh.yml (scan -> apply -> notify), update.yml (runs on
queue change), force_update.yml (refresh.yml full mode),
notify-failure.yml (Discord on failure/cancel/rate limit),
python-ci.yml, webapp-ci.yml, deploy-status.yml; draft-first release
with one create-release job and tauri-action v1, no caches in release
builds; SHA-pinned actions, permissions: {} defaults, reusable
workflows pinned with explicit secrets, injection fixes; dependabot.yml.
- Remove lists/, generate_md, generate_table, log_deleted,
deleted_games.txt, the Telegram bot-ingest path and old bash wrappers;
update README (EN/VI), CONTRIBUTING, templates, CLAUDE.md, CHANGELOG
and mark the retired Telegram path in the policies.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(pipeline): review findings on the refresh / ingest rewrite
Removals
- Mass-change guard: a run whose removals or new strikes exceed
max(10, 10%) of the games it checked withholds all its removals and
alerts (mass_change). Withheld games are marked withheld_at and stay
withheld in later (even single-URL or rate-limited) runs until a healthy
check clears them or a run is dispatched with allow_mass_removal.
- Checkpoints never carry removals, so a scan that dies before its guard
cannot delete games; apply_patch re-checks the per-run limit and caps
any patch at max(25, 5%) of the catalog (ALLOW_MASS_REMOVAL=1 overrides).
- Strikes mature by time, not calendar day: a second sighting must come
>= 20 h after the first (strike_at), so two checks around midnight UTC no
longer remove a game.
- Overlapping scans can't undo each other: refresh_state merges keep the
newest check and the newest full stamp in either apply order, and a
removal is skipped when a newer check has landed since.
- A corrupt count_history.json fails the apply instead of being replaced
by a one-row history.
Ingest
- A second spelling of a queued game no longer drops the first copy
before it reaches a final outcome.
- A dispatched url is processed first and kept in temp_link.json
(queue_add) until it finishes, so a retry, deadline or rate-limit stop
keeps it.
- Failures count as an attempt only >= 6 h apart and a 429 counts as none,
so a burst of queued runs can't burn a link's three attempts.
- Non-string queue entries are cleaned on every apply instead of crashing
it; {"url": ...} objects are unwrapped.
CI
- queue: max on the ingest, refresh-apply and force-update concurrency
groups: the default queue replaced (and silently dropped) pending runs.
- Seed scripts/state/*.json and mkdir -p before git add (the pathspec
failed on an empty patch until the directory existed on main).
- Cancelling a refresh / force-update / desktop release really stops it
(!cancelled() instead of always()).
- deploy-status.yml becomes an hourly check of main's latest finished
"Workers Builds: free-games-itchio-list" run (bash/cf_build_status.sh):
GitHub never starts check_run workflows for GITHUB_TOKEN data commits.
- The reusable release notifiers still take their script from
poli0981/.github@main; the caller comments now say so.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(pipeline): close the remaining mass-removal and monitor gaps
From the second review round of the pipeline fixes:
- A strike spike now marks every strike of that run withheld_at (the
checkpoint of a run that dies mid-spike too), so a later short,
rate-limited or single-URL run can't remove them without an
allow_mass_removal dispatch.
- Withheld games take at most half of a run's budget (all of it for the
allow_mass_removal run that confirms them), and a withheld full-mode
game moves its `full` stamp, so neither rotation stalls on them.
- refresh.yml runs one scan -> apply pipeline at a time (workflow-level
concurrency refresh-pipeline, queue: max), so an older removal can't be
applied after a newer healthy check of the same game.
- deploy-status.yml alerts once per failed Cloudflare build, keyed on its
check-run id and marked only after the Discord post, instead of by age
(which could drop an alert after a missed run, or repeat it); the
monitor walks main's first-parent history so preview builds of merged
branch commits are never mistaken for the site's build.
- CLAUDE.md: merge PRs with squash or a merge commit, never by fast-forward.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
- Add webapp/wrangler.jsonc (Workers static assets from ./dist, SPA
fallback, workers_dev/preview_urls off) and build the web app to
webapp/dist. The config-less Workers Builds deploy was serving the raw
webapp/ source tree (blank page, /package.json and /src/* public).
- npm audit fix in-range (vite 8.3.0, react-router-dom 7.18.4, postcss
8.5.28, transitive fixes): closes all Dependabot alerts, audit = 0.
Add wrangler as a pinned devDependency, engines node >=22.22,
.node-version 24.
- public/_headers: Referrer-Policy, frame denial, Permissions-Policy,
COOP, CSP report-only; immutable cache for hashed /assets/*.
- release_android.yml: Node 24 action majors (setup-java v6,
upload-artifact v7, setup-android v4, checkout/setup-node v7),
SHA-pinned, timeout + concurrency, tag via env.
- GitHub Pages now publishes only a redirect stub (pages-redirect/)
that keeps #/ routes and clears the old PAT/GPG localStorage keys;
drop notify-deploy.yml.
- .gitattributes: fix invalid '* text = auto' / '* eol = lf'; binary
rules; stop export-ignoring README/policy docs. .gitignore: local
contacts/QR assets, wrangler state, .dev.vars, keystores.
- Scraper workflows: unbuffered UTF-8 logs; pause the schedules of
check_paid/check_alive/update_reviews/update_status (full passes over
2,600+ games exceed their timeouts and lose all work).
- Point canonical/og/manifest/sitemap/robots and doc links at
freeitchgames.win; regenerate OG image (fit title); interim Cloudflare
notice in the Privacy Policy.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
v3.8.0 (Android APK) is tagged and released. Flip "in progress" -> released,
extend the tag range to v3.8.0, and note the release_android.yml gotcha:
setup-java `cache: gradle` hard-fails because gen/android is generated mid-job.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`actions/setup-java` with `cache: gradle` hard-fails because gen/android (the
Gradle project) is gitignored and only generated by `tauri android init` later
in the job — there are no gradle files at checkout to key the cache on. Remove
it; rust-cache + npm cache still apply.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ship the webapp as a sideloadable arm64-v8a .apk alongside the desktop
installers — the same React + Tauri app running in an Android WebView.
- Fix the bundle identifier to be Android-valid (alphanumeric — Android
rejects hyphens, Tauri rejects underscores):
com.poli0981.free-games-itchio-webapp -> com.poli0981.freegamesitchio.
release_desktop.yml now reads the macOS .pkg --identifier from config.
- Realign Tauri/Cargo/UI versions to 3.8.0 (sane, monotonic versionCode).
- Add bundle.android.minSdkVersion 24.
- New release_android.yml: arm64-v8a build, post-signed with zipalign +
apksigner (gen/ stays gitignored — no Gradle edits). Attaches to the
draft Release on a v* tag; uploads a workflow artifact on manual dispatch.
- Mobile UX: Android back button -> router history (useBackButton hook),
safe-area insets, platform-aware sidebar badge (Desktop/Mobile app).
- Add @tauri-apps/api dependency; docs in TAURI.md, README(.vi), CLAUDE.md.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The web build set `sourcemap: !isTauri` → true, so Vite emitted *.js.map
files and `sourceMappingURL` comments into docs/app/, exposing the
original TypeScript via DevTools on the deployed GitHub Pages site.
No error-tracking service consumes the maps (PrivacyPolicy confirms no
Sentry/Datadog), so disable them outright rather than using 'hidden'
(which would still publish fetchable .map files). The Tauri build was
already mapless; local `npm run dev` sourcemaps are unaffected.
Verified: build emits 0 .map files and 0 sourceMappingURL refs; lint clean.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
bundle.windows.nsis.license does not exist in @tauri-apps/cli 2.11.0 and broke
the v3.7.0 desktop build; document the bundle.licenseFile (RTF) workaround so
future sessions don't relearn it. Bump current-state note to v3.7.1.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
v3.7.0's desktop installers failed config validation on all platforms:
@tauri-apps/cli 2.11.0's NsisConfig has no `license` key (added in a later
release), so `bundle.windows.nsis.license` was rejected.
Switch to the top-level `bundle.licenseFile` (valid in 2.11.0) -> RTF EULA.
RTF satisfies BOTH Windows bundlers — WiX (.msi) requires RTF and NSIS (.exe)
auto-detects it — so both installers show the "I Agree" page. The previous
plain-text EULA.txt would also have broken the WiX/.msi build.
Bumps about.ts version 3.7.0 -> 3.7.1; adds CHANGELOG [3.7.1]. Web feature set
is identical to v3.7.0.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Web: full-screen first-launch legal gate (LegalGate) blocks the app until the
user accepts the current LEGAL_VERSION; persists as prefs.acceptedLegalVersion
in localStorage (no cookie). Reuses LEGAL_LINKS; re-prompts on LEGAL_VERSION bump.
Built on raw Radix Dialog (focus-trapped, no close-X, Esc/outside-click disabled).
Desktop: Windows NSIS installer shows an EULA "I Agree" page via
bundle.windows.nsis.license -> src-tauri/installer/EULA.txt.
Charts: /charts split into four lazy per-tab chunks (charts/tabs/*). Each tab
imports its chart components directly (index.ts barrel removed) so the bundler
keeps each tab's components in its own chunk; non-default tabs' component code
loads only on activation. Recharts still loads with the default Overview tab.
Also: about.ts version -> 3.7.0 + Opus 4.8 credit; Privacy Policy localStorage
key note (EN + VI); CHANGELOG + CLAUDE.md updates.
Verified: eslint, tsc -b, knip, npm audit (0 vulns), ruff, vulture all clean;
browser smoke test of gate (appear / accept / persist / version-bump re-prompt)
and per-tab lazy loading (reach-tab + its charts load only on tab click).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- time 0.3.48 (released 2026-06-12) fails to compile inside tauri-utils
(E0119 conflicting From impls, time-rs/time#783); with no committed
Cargo.lock, CI resolved it fresh and the v3.6.0 desktop build failed
- Pin time = "=0.3.47" in webapp/src-tauri/Cargo.toml (the version all
releases through v3.5.2 built with); remove once upstream fix ships
- Bump version badges, about.ts, CHANGELOG to 3.6.1 (web unchanged from
v3.6.0; no Tauri version bump - no binary behavior change)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
- Wire in knip (webapp) and vulture (Python) as dead-code detectors
- Remove 8 unused deps, the unwired Tauri scrape-preview scaffold, and
~20 unused exports/types across the webapp
- Add docs/THIRD_PARTY.md attributing the dev tooling; trim TAURI.md
- Bump version badges, about.ts, and CHANGELOG to 3.5.2
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Turn off react-refresh/only-export-components for src/components/ui/**
(vendored shadcn primitives) and react-hooks/incompatible-library
(non-actionable TanStack Table warning) in eslint.config.js.
- Extract SortableHeader into its own data-table/sortable-header.tsx so
columns.tsx is a pure column-definition module.
- Fix react-hooks/exhaustive-deps in games.tsx and faceted-filter.tsx —
wrap values built with `?? []` so dependent useMemos actually memoize.
- npm run lint now reports 0 errors, 0 warnings (was 17 + 5).
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Add 6 charts (game-count line, genre treemap, KPI cards, deletions
over time, deletion reasons, most-rated) and split charts.tsx into a
charts/ module (one file per chart, shared chart-card + palette).
- Track catalog size over time: data_store.py appends data_game/
count_history.json daily; backfill_count_history.py seeds it from git.
- Add scripts/json_io.py with shared load/save and a URL-keyed
dedup_deleted so the deleted-games log can't double-log re-added games.
- Add a scroll-to-top button and a ruff config (pyproject.toml).
- Refactor docs for v3.5.0 (CHANGELOG, README badges, CLAUDE.md).
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Fix DataTable header/body width mismatch at desktop widths (Tauri 1280×800
and any viewport wider than the natural sum of header content widths). Header
was native table-layout, body was flex — the absolutely-positioned virtual
rows never participated in table layout, so the two diverged whenever the
container had leftover space. Header `<tr>` now uses `flex w-full` and each
`<th>` mirrors the body `<td>`'s flex style. Drops the table-cell variant of
the priority helper.
- Rewrite `announce-discussion.yml` to auto-discover IDs at runtime via
`gh api graphql`. Previous validation step silently `exit 0`'d on every run
because the three required repo variables (`DISCUSSION_REPO_ID` +
category IDs) had never been configured, so every release since v3.2.0
failed to post to Discussions without flagging it. Zero config now; fails
loudly if Discussions isn't enabled or a category is missing.
- README + README.vi badges + about.ts APP.version → 3.4.1.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- New scripts/update_reviews.py + bash + workflow on cron '0 5 1,15 * *':
refresh rating + rating_count fortnightly via scrape_game_info, skip on
network/parse errors so old values aren't blanked.
- New scripts/update_status.py + bash + workflow on cron '0 6 1 * *':
refresh status monthly using the same pattern.
- New scripts/force_update.py + bash + workflow (workflow_dispatch only):
optional url input; empty input re-scrapes every game. Always preserves
safe_virus / notes / nsfw per CLAUDE.md "Editable vs read-only fields".
Doubles as the canonical mojibake repair tool.
- Chain generate_table.yml on the three new workflows so lists/*.md regen
automatically after data mutations.
- Fix UTF-8 mojibake on webapp writes: webapp/src/lib/github/contents.ts
readFileWithSha and git-data.ts bulkDeleteGames decoded GitHub's base64
content with atob alone (Latin-1 binary string). Multi-byte UTF-8 sequences
became mojibake; next write re-encoded them as UTF-8, double-corrupting per
edit cycle. Confirmed damage in data_game/game_info_002.json
('BotÃÂão Esquerdo' was 'Botão Esquerdo'). Extract shared helper
webapp/src/lib/github/encoding.ts (base64ToUtf8 / utf8ToBase64) using
TextDecoder('utf-8') / TextEncoder; route both call sites through it.
- Version bumps: README + README.vi -> 3.4.0, about.ts APP.version -> 3.4.0,
new CHANGELOG entry, CLAUDE.md GitHub Actions table + gotcha #8 updated.
- No Rust binary change: tauri Cargo.toml / tauri.conf.json untouched.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Add tauri-plugin-single-instance v2, registered first in builder chain
- Bump desktop binary version 0.1.0 -> 0.1.1 (boundary change)
- Bump app version 3.2.0 -> 3.2.1, README badges, About page
Fixes duplicate-process bug: each launch used to spawn a new
free-games-itchio-webapp.exe instead of focusing the existing window.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrote the four English legal docs (DISCLAIMER, EULA, ToS, PrivacyPolicy) to
be tighter and more enforceable while keeping the project's voice — TL;DR, numbered
sections, definitions, severability, governing law (Vietnam), explicit "not legal
advice" notice, removal-request path. PrivacyPolicy now includes per-storage
table and PAT lifecycle steps.
Added Vietnamese translations for all six policy / community docs under
docs/i18n/vi/ plus a top-level README.vi.md. Each VI file notes that the English
version is the controlling text for legal interpretation.
About page: new "Legal & policies" Card listing Disclaimer, EULA, ToS, Privacy,
Code of Conduct, Security, License (MIT), and Changelog with a pointer to the
Vietnamese translations. New LegalLink interface + LEGAL_LINKS const in
webapp/src/lib/about.ts following the THIRD_PARTY/SOCIAL_LINKS pattern.
Optional UI:
- Tauri desktop: maximize button disabled (maximizable: false in
tauri.conf.json). Window remains resizable.
- DataTable: scrollbar hidden via new .scrollbar-hide Tailwind utility added to
webapp/src/index.css; scrolling still works.
Bookkeeping: README badge bumped to 3.1.4 + Vietnamese language badge + pointer
to README.vi.md and docs/i18n/vi/. CHANGELOG entry for 3.1.4.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- About page: new "AI co-authors" Card listing Grok (xAI) and Claude Code
(Anthropic, Claude Opus 4.7, 1M context) with vendor + model badges and
the role each played in the repo (Grok: Python pipeline + v2.0.0;
Claude Code: v3.0.0 webapp/Tauri + v3.1.2 fixes).
- AiTool interface + AI_TOOLS const in webapp/src/lib/about.ts so the AI
credit follows the same structured pattern as THIRD_PARTY and
SOCIAL_LINKS.
- ACKNOWLEDGEMENTS, My_Stuff, CONTRIBUTING surface Claude Code alongside
Grok wherever the existing AI credit lived. My_Stuff "The Real MVP" is
now plural; DEV.blurb mentions both buddies.
- Bump README badge to 3.1.3 + CHANGELOG entry.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Add tauri-plugin-opener (Rust + JS) so external links open via the OS
browser on the desktop app. Capability scoped to opener:allow-open-url
for https://* only.
- New <ExtLink> component (webapp/src/components/ext-link.tsx) used app-wide
so the offline link bug can't recur.
- About page: new Developer card, Found-a-bug CTA, and Find-me-elsewhere
social grid (X, YouTube, 2x Discord, Patreon, Ko-fi, Steam, Bluesky,
Mastodon).
- Rewrite webapp/README.md from Vite boilerplate to actual webapp docs;
refresh CONTRIBUTING.md, docs/ACKNOWLEDGEMENTS.md, docs/My_Stuff.md, and
README.md with the new contact handles.
- Bump version badge to 3.1.2 + CHANGELOG entry.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Captures the context that's expensive to re-derive every time:
- Layer split (Python pipeline vs webapp vs Tauri).
- Local dev commands and Vite alias / output paths.
- Code-split layout and webapp folder map.
- Which 3 of the 23 game fields are user-editable.
- All 7 GitHub Actions workflows with triggers and purposes.
- Release / tag procedure (signed tags from main only).
- Correct fine-grained PAT permissions (Actions:write, NOT
workflow:write).
- Ten gotchas that each cost us a release to learn:
universal-apple-darwin + bundle_dmg.sh, macos-13 retirement, Tauri
icons must exist, .pkg via pkgbuild, Vite v8 base option, TS 6
baseUrl deprecation, lucide v1 brand icon removal, base64 newlines
on contents API, workflow_dispatch returns 204, docs/app/ is
gitignored.
- Safe-edit rules and the current trunk state.
Lives at the repo root so any tool that auto-loads CLAUDE.md picks
it up.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The macos-13 job in v3.1.0's release run sat in 'queued' forever and
GitHub auto-cancelled it (runner_name was null in the run output).
GitHub retired macos-13 from free-tier hosted runners in late 2024;
new jobs requesting that label never get picked up.
Switched the Intel matrix entry to also run on macos-latest (Apple
Silicon) and cross-compile to x86_64-apple-darwin. The same toolchain
step already drives `rustup target add ...` from matrix.tauri_target,
and Xcode CLI tools on macos-latest carry both SDKs, so no extra
setup is needed.
The DMG bundler packages a single-arch x86_64 binary on an aarch64
host — bundle_dmg.sh doesn't execute the binary, only stages it into
a disk image, so cross-compile doesn't reintroduce the
universal-apple-darwin failure that v3.1.0 fixed by going per-arch.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## macOS DMG bundling
Universal target (lipo'd ARM + Intel) tripped bundle_dmg.sh on the
universal-apple-darwin run — a known fragility around AppleScript +
hdiutil + the universal binary in headless CI.
Switched the matrix to two native macOS targets:
- macos-latest (Apple Silicon) → aarch64-apple-darwin
- macos-13 (Intel) → x86_64-apple-darwin
Each runs DMG bundling against its own native binary instead of a
universal lipo, which avoids the failure mode altogether. fail-fast
is already off so a flake on one arch doesn't kill the other.
## .pkg installer (requested)
Tauri's bundler doesn't emit .pkg, so added a follow-on step that
runs pkgbuild (preinstalled on macOS runners) against the .app
produced by tauri-action and uploads it to the same draft release.
The step is gated on if: always() so even if the DMG layer fails on
some future runner image, the .pkg still ships — pkgbuild only needs
the .app, which is built before DMG packaging.
Output naming: {AppName}_{version}_{aarch64|x86_64}.pkg.
## Games table pagination
Added DataTablePagination footer (rows-per-page selector +
First/Prev/Next/Last) under the table. Page sizes 50/100/200/500;
default 100. Pagination state is lifted into Games route so toolbar
counts ('filtered of total') and bulk-action selection survive
filter/sort/page changes.
Virtualization is still in place inside each page so a 500-row page
doesn't blow render perf.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
description:Something on the website or in the apps doesn't work with your keyboard, screen reader, zoom, contrast settings or other assistive technology
title:"[Accessibility] "
labels:["accessibility"]
body:
- type:markdown
attributes:
value:|
Thank you for taking the time to report this. Every report helps, even a partial one — describe what happened in your own words, and skip whatever you'd rather not share. Please don't include health information.
Prefer email, or don't have a GitHub account? Write to **contact@poli0981.dev** (English or Vietnamese). What happens next, and the response targets, are in [ACCESSIBILITY.md](https://github.com/poli0981/free-games-itchio-list/blob/main/ACCESSIBILITY.md#7-reporting-an-accessibility-barrier).
**Found a security vulnerability?** Please don't file it here: report it privately (see SECURITY.md).
- type:dropdown
id:where
attributes:
label:Where did it happen?
description:Pick all that apply.
multiple:true
options:
- Website (freeitchgames.win)
- Desktop app — Windows
- Desktop app — macOS
- Desktop app — Linux
- Android app
- Not sure
validations:
required:true
- type:input
id:page
attributes:
label:Page or screen
description:The address of the page, or the screen in the app.
placeholder:e.g. https://freeitchgames.win/charts, or "the Games list in the Android app"
- type:textarea
id:details
attributes:
label:What were you trying to do, and what happened?
description:What you expected, what happened instead, and the steps to get there if you can.
placeholder:|
e.g. I pressed Tab to reach the "Platform" filter, but focus jumped back to the top of the page.
validations:
required:true
- type:dropdown
id:kind
attributes:
label:What kind of barrier? (optional)
multiple:true
options:
- Keyboard (can't reach or use something, focus lost or hidden)
description:Paste or drag files here. Please hide any personal information.
- type:checkboxes
id:conduct
attributes:
label:Code of Conduct
description:By submitting this issue you agree to follow the project's [Code of Conduct](https://github.com/poli0981/free-games-itchio-list/blob/main/CODE_OF_CONDUCT.md).
description:Suggest new free itch.io games (max 15 per issue pls)
name:🎮 Add Games (bulk list)
description:Got a whole list of free itch.io games? Use this. For one game, the Suggest page is faster.
title:"[Add Games] "
labels:["contribution","games"]
body:
- type:markdown
attributes:
value:|
Thanks bro! This repo lives on additions because I'm too lazy to hunt alone :D Only free-to-play itch.io games.
Thanks bro! This catalog lives on additions because I'm too lazy to hunt alone :D Only free-to-play itch.io games.
The game must be playable or downloadable **on its itch.io page itself** (a browser build or an uploaded file). A page that only points to a launcher or a download on another site doesn't qualify.
**Just one game? Use the Suggest page instead: https://freeitchgames.win/suggest** — no GitHub account needed, and it goes straight into the review queue.
This issue form is the fallback for **bulk lists** (several games at once).
How it works either way: every link lands in a review queue, and nothing enters the catalog until the Maintainer approves it. Approved links are scraped by the data pipeline; paid games and games already in the catalog are skipped.
- type:dropdown
id:count
@@ -25,7 +32,7 @@ body:
attributes:
label:Game Links (one per line!)
description:|
I'll check (no guarantee perfect). One link per line — two on same line? Your loss :v
itch.io game page links only (like `https://creator.itch.io/game`). One link per line — two on the same line? Your loss :v
placeholder:|
https://example.itch.io/game1
https://example.itch.io/game2
@@ -41,8 +48,17 @@ body:
- type:textarea
id:notes
attributes:
label:Notes for table? (optional)
description:Personal rating, warnings, etc. — I'll add to "Notes" column
label:Anything the Maintainer should know? (optional)
description:Warnings (adult content, suspicious download, needs an account...), your personal take, etc. The Maintainer may use it for the game's `notes`, `nsfw` or `safe_virus` fields.
- type:checkboxes
id:checks
attributes:
label:Quick checks (optional)
options:
- label:I searched https://freeitchgames.win/games and these games aren't listed yet
- label:These games are free to play on itch.io (not paid)
- label:Each page has its own browser build or download on itch.io (not only a link to another site)
- type:checkboxes
id:agreement
@@ -50,4 +66,4 @@ body:
label:Agreement (required)
options:
- label:I agree — if this issue is off-topic, spam, or violates repo policy, it may be ignored/closed without response.
description:Report a bug in the list, tables, scripts, or anything broken
name:🛠️ Report a problem (wrong data, something broke)
description:Wrong or outdated game data, a dead link, or something that stopped working on the website or in the apps. Not for feature requests.
title:"[Bug] "
labels:["bug"]
body:
- type:markdown
attributes:
value:|
Thanks for reporting! I'm a lazy unemployed dev, so bugs happen a lot :D Grok fixes most, but your help is gold.
Thanks for reporting! I'm a lazy unemployed dev, so bugs happen a lot :D My AI buddies fix most, but your help is gold.
**The project is in maintenance mode** (stable, no new features): this form is for wrong game data and for things that broke. Ideas and feature requests are closed without review.
**Found a security vulnerability?** Please don't file it here — report it privately via https://github.com/poli0981/free-games-itchio-list/security/advisories/new or security@poli0981.dev.
Want a game removed (or you're its creator)? Use the "Remove a Game" template instead.
Something doesn't work with your keyboard, screen reader, zoom or contrast settings? The "Accessibility barrier" template asks the right questions.
- type:dropdown
id:where
attributes:
label:Where did it happen?
description:Pick all that apply.
multiple:true
options:
- Website (freeitchgames.win)
- Desktop app — Windows
- Desktop app — macOS
- Desktop app — Linux
- Android app
- Game data itself (wrong info, same everywhere)
- Data pipeline / GitHub Actions / scripts
- Not sure
validations:
required:true
- type:input
id:version
attributes:
label:Version
description:Shown on the About page (website and apps). For the desktop/Android app, the release you installed.
placeholder:e.g. 4.1.0
- type:input
id:environment
attributes:
label:Browser / device / OS (if relevant)
placeholder:e.g. Firefox on Windows 11, Safari on macOS 15, Android 13 phone
- type:checkboxes
id:bug_types
@@ -14,13 +51,15 @@ body:
label:What kind of bug(s)? (check all that apply)
options:
- label:Broken/dead link (game page 404 or not loading)
- label:Thumbnail not showing or wrong
- label:Table missing columns or broken format
- label:Wrong game name or dev name
- label:Wrong game count in tables
- label:Wrong genre classification
- label:Cover image not showing or wrong
- label:Wrong game name or developer name
- label:Wrong genre, tags, platforms or other game info
- label:Wrong or outdated description
- label:NSFW/Safe flag wrong
- label:NSFW flag or safety note (safe_virus) wrong
- label:Game count or charts look wrong
- label:Page/app crashes, won't load, or layout broken
- label:Search, filters or sorting not working
- label:Suggest page not working
- label:Other (must describe below)
- type:textarea
@@ -28,7 +67,7 @@ body:
attributes:
label:Details (Game name(s)/URL(s), what happened?)
description:|
If "Other" checked, or multiple games — explain here. The more specific, the faster I fix (or Grok does).
What did you do, what did you expect, what happened instead? If "Other" is checked, or multiple games — explain here. The more specific, the faster it gets fixed.
validations:
required:true
@@ -36,17 +75,17 @@ body:
id:screenshots
attributes:
label:Screenshots/Proof (optional but super helpful)
description:Paste links or describe — I believe you, but visuals make me less lazy :D
description:Paste images or links, or describe — I believe you, but visuals make me less lazy :D Please hide any personal info.
- type:checkboxes
- type:dropdown
id:urgency
attributes:
label:Urgency level?
options:
- label:Low (annoying but not critical)
- label:Medium (affects some games)
- label:High (breaks tables or many games)
- label:Critical (whole repo broken)
- Low (annoying but not critical)
- Medium (affects some games or one page)
- High (breaks a whole page or many games)
- Critical (website or app unusable)
- type:checkboxes
id:agreement
@@ -55,4 +94,4 @@ body:
description:I gotta cover my lazy ass :D
options:
- label:I agree — if this issue is off-topic, spam, or violates repo policy, it may be ignored/closed without response.
about:Suggest one free itch.io game right on the website, no GitHub account needed. Every suggestion is reviewed by the Maintainer before it enters the catalog.
- name:🔒 Report a security vulnerability (private)
about:The project is stable and in maintenance mode — security fixes and dependency updates only. Feature requests and code pull requests are closed without review.
description:Request to remove games from the list (max 10 per issue)
name:🚫 Remove a Game (or copyright request)
description:Ask to remove games from the catalog or correct their data, including requests from creators and rights holders (max 10 per issue)
title:"[Remove Games] "
labels:["removal"]
labels:["delete-game"]
body:
- type:markdown
attributes:
value:|
Sad to see them go, but ok! Max 10 because I'm lazy :D
Sad to see them go, but ok! Max 10 per issue because I'm lazy :D
**This issue is public.** Don't post private contact details or anything confidential here.
Prefer to keep it private? Email **takedown@poli0981.dev** instead, with the game URL, who you are (creator, rights holder, or someone authorized to act for them) and the reason.
What happens next (for a removal): the Maintainer removes the record from the catalog (the removal and its reason are logged in the public list of removed games at https://freeitchgames.win/removed), deletes the resized cover copies the website stores, and cached copies expire from Cloudflare's cache. Older versions stay in the public git history. Target: within 7 days; urgent legal requests sooner.
- type:dropdown
id:count
@@ -22,8 +27,11 @@ body:
- type:textarea
id:games
attributes:
label:Game Name(s) or Link(s)
description:List them — one per line or clear
label:Game Link(s)
description:itch.io links work best (game names are ok too). One per line.
placeholder:|
https://example.itch.io/game1
https://example.itch.io/game2
validations:
required:true
@@ -38,6 +46,8 @@ body:
- label:Don't like it anymore
- label:Potential malware/virus
- label:I'm the dev and don't want it listed
- label:I'm the dev and the data shown is wrong (please correct it instead of removing)
- label:Copyright / rights-holder request (fill in the section below)
- label:Other (describe below)
validations:
required:true
@@ -45,7 +55,46 @@ body:
- type:textarea
id:other_reason
attributes:
label:If "Other" — explain here
label:Details / if "Other" — explain here
description:For a correction, say which field is wrong and what it should be.
- type:markdown
attributes:
value:|
---
### Copyright / rights-holder section (optional)
Fill this in only if you are the creator or rights holder of the listed game (or authorized to act for them), for example when your description text or cover image is shown here and you want it removed.
Game descriptions and cover images remain the property of their creators; the catalog only copies what is on the public itch.io page.
- type:input
id:rights_holder
attributes:
label:Your name, studio or itch.io account, and your role
description:e.g. "Creator, itch.io account example" or "Publisher, authorized by the developer". Public — no private contact details please.
- type:checkboxes
id:affected
attributes:
label:Which content is affected?
options:
- label:The whole listing
- label:Description text
- label:Cover image / thumbnail
- label:Game name, logo or trademark
- label:Something else (explain below)
- type:textarea
id:claim
attributes:
label:Details of the request
description:Where the original work lives (e.g. your itch.io page) and what you want done.
- type:checkboxes
id:rights_confirmation
attributes:
label:Confirmation (copyright requests only)
options:
- label:I am the creator or rights holder of the content above, or authorized to act for them, and the information in this issue is accurate.
- type:checkboxes
id:agreement
@@ -53,4 +102,4 @@ body:
label:Agreement (required)
options:
- label:I agree — if this issue is off-topic, spam, or violates repo policy, it may be ignored/closed without response.
Thanks for feeding the list! (Normally I prefer the "Add Games" issue template so Actions auto-scrape, but PR direct to game_info.json also works if you wanna be extra :D)
Thanks for feeding the list! Easiest ways first: one game → the Suggest page (https://freeitchgames.win/suggest, no GitHub needed); a bulk list → the "Add Games" issue template. A PR also works if you wanna be extra :D
**How to add games in a PR:** put the itch.io game URLs in `scripts/temp_link.json` (a JSON array of URL strings). Please don't edit `data_game/` by hand — the pipeline writes it. Merging the PR is the Maintainer's approval; the ingest workflow (`update.yml`) then scrapes each link and adds the free ones. Paid games and games already in the catalog are skipped.
### Games Added
List the itch.io URLs (free-to-play only!):
### Why these games?
Optional: short notes, why they rock, NSFW/safe concerns.
### Description
How you added them (manual edit game_info.json? scraped yourself?). Keep format consistent!
Optional: short notes, why they rock, NSFW/safety concerns (the Maintainer sets the `nsfw`, `safe_virus` and `notes` fields).
### Checklist
- [ ] All links are free itch.io games
- [ ]No duplicates (check existing)
- [ ]Format correct (json valid, fields match)
- [ ]Tested generate_md.py after
- [ ] All links are free itch.io game pages
- [ ]Each page has its own browser build or download on itch.io (not only a link to another site)
- [ ] No secrets, tokens or personal data in the diff
- [ ] New UI text is in both `webapp/src/lib/i18n/en.ts` and `vi.ts`; a changed English doc has its Vietnamese mirror updated (or I said so above)
- [ ] I agree my contribution is licensed like the part it changes: MIT for code, CC BY 4.0 for data and docs
### Accessibility (UI or docs changes — see [ACCESSIBILITY.md](https://github.com/poli0981/free-games-itchio-list/blob/main/ACCESSIBILITY.md#8-for-contributors))
- [ ] N/A — no UI or docs change
- [ ] Works with the keyboard alone: everything reachable, focus visible and never lost
- [ ] Every control has a name; nothing relies on colour alone; `npm test` (contrast check) passes
- [ ] Respects reduced motion; no new auto-playing motion
- [ ] Checked once with a screen reader (Narrator, NVDA, VoiceOver or TalkBack)
- [ ] Docs: headings in order, descriptive link text, alt text for images
# Ingest queued links from scripts/temp_link.json (written by the admin
# Worker and its cron) plus an optional dispatched URL.
#
# Runs right away when temp_link.json changes on main (pushes made by GitHub
# Apps trigger it; this workflow's own GITHUB_TOKEN push does not, so no loop),
# and once a day as a safety net. Keep the filename: released apps and
# external tools dispatch `update.yml` by name.
name:Ingest queued games
on:
schedule:
- cron:'0 3 * * *'# Runs daily at 03:00 UTC
- cron:'23 1 * * *'
push:
branches:[main]
paths:
- 'scripts/temp_link.json'
workflow_dispatch:
inputs:
url:
@@ -9,29 +21,59 @@ on:
required:false
type:string
permissions:
contents:write
permissions:{}
# One ingest at a time, FIFO. `queue: max` matters: with the default queue a
# newer pending run replaces an older pending one, which would silently drop
# that run's dispatched `url` (it is only in the run's input until the run
# writes it to temp_link.json).
concurrency:
group:ingest
cancel-in-progress:false
queue:max
env:
PYTHONUNBUFFERED:'1'
jobs:
update-game-info:
ingest:
runs-on:ubuntu-latest
timeout-minutes:120
timeout-minutes:60
permissions:
contents:write
steps:
- name:Checkout repository
uses:actions/checkout@v6
uses:actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1# zizmor: ignore[artipacked] — commit_push.sh pushes with this token; no artifacts are uploaded from this job
Applies from: the release of version 4.6.0 (the website and the desktop and Android apps).
This is a hobby project run by one person, poli0981 (SkullMute), called "the Maintainer" below: a catalog of free itch.io games, on the website https://freeitchgames.win and in desktop and Android apps that show the same pages. Everyone should be able to use it, whether with a keyboard alone, a screen reader, zoom, a high-contrast theme, speech input or anything else. This statement says what works, how it is checked, what doesn't work yet, and how to tell the Maintainer when something gets in your way.
A Vietnamese translation is available at [`docs/i18n/vi/ACCESSIBILITY.md`](docs/i18n/vi/ACCESSIBILITY.md). If the two differ, this English version prevails.
> **TL;DR**
>
> - The goal is [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA for the website and the apps. That is a target, not a certificate: nobody outside the project has audited it.
> - Every page works with the keyboard alone and with a screen reader. The Maintainer tests with the keyboard only, Windows Narrator, and VoiceOver on an iPhone.
> - Colours meet the WCAG contrast ratios in the light and dark themes, and a test checks them on every change. Windows contrast themes are supported, and the site follows your system's "reduce motion" setting.
> - Every chart comes with a data table.
> - Known gaps are listed in [§6](#6-known-limitations).
> - Something in your way? Open an [accessibility issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml) or email **contact@poli0981.dev**.
## 1. Scope
This statement covers:
- **the website** https://freeitchgames.win: every public page (Home, Games, the game pages, Charts, Removed, Suggest, Settings, About, the error pages) and the verification page shown before them;
- **the desktop apps** (Windows, macOS, Linux) **and the Android app**, which show the same pages in the system's web view.
It doesn't cover:
- the games themselves, their itch.io pages, and what their creators wrote or made (titles, descriptions, tags, cover images);
- Cloudflare Turnstile, the third-party check on the verification page and on the Suggest form (Cloudflare is responsible for its accessibility);
- the Maintainer's admin page, which has one user;
- other sites the pages link to, GitHub included.
## 2. Goals and priorities
- **Target**: [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA, as far as a one-person hobby project can get.
- **First**: the main tasks with a keyboard and a screen reader: find a game, read its details, open it on itch.io, change your settings, suggest a game.
- **Then**: readable text and controls (contrast, zoom, reflow), no motion you didn't ask for, and the right language for screen readers (English or Vietnamese).
- **Always**: new features keep all of this working (see [§8](#8-for-contributors)).
## 3. What works today
### Moving around
- "Skip to content" is the first thing the Tab key reaches.
- Each page has named landmarks (header, main navigation, search, main content, pager, footer), one level-1 heading, and its own title.
- After you follow a link inside the site, focus moves to the new page's heading, so a screen reader announces the page and Tab continues from there. Going back returns focus to the link you used, for example the game you opened from the list.
- The sticky header never covers what has keyboard focus.
### Keyboard
- Everything works with the keyboard alone: menus, filters, dialogs and charts.
- Focus is always visible: a purple outline, or the system highlight in a contrast theme.
- Dialogs keep focus inside while they are open and return it to where you were when they close.
- "/" jumps to the search box. You can switch this shortcut off in **Settings → Accessibility**, which helps with speech input or if the key clashes with your screen reader or your browser's quick find.
- When a control disappears after you use it (clearing a search, removing a filter), focus moves to the next sensible place instead of getting lost.
### Screen readers
- Every control has a name, in English or Vietnamese. Icons are hidden from screen readers.
- The number of results, search suggestions, loading states and form messages are announced.
- On wide screens the game list is a table with column headers; on phones it is a simple list.
- Links that open a new tab (in the apps: your browser) say so.
- Text in the other language, such as the language names and the English-only names of the legal documents, is marked with its language.
### Seeing the content
- Text and controls meet the WCAG 2.2 AA contrast ratios in both themes: 4.5:1 for text, 3:1 for field borders, the focus outline and chart colours. The test [`webapp/scripts/check-contrast.test.mjs`](webapp/scripts/check-contrast.test.mjs) checks the colours on every change.
- Light, dark or system theme, compact or normal rows, and hidden scrollbars: all in Settings.
- Windows contrast themes (forced colours): the selected tab, pressed toggles, the current page and switches use the system's highlight colours.
- Zoom is never blocked. At 400 % zoom or in a 320-pixel-wide window the phone layout takes over, and the page doesn't scroll sideways.
- Links inside sentences are underlined. Nothing is shown by colour alone: states also change the text, an outline or an underline.
### Motion
- With "reduce motion" switched on in your system, animations, chart entrances and smooth scrolling are off.
- On the website, covers are normally shown as still images (animated covers are turned into stills).
- Apart from loading placeholders, nothing moves on its own.
### Charts
- Each chart is named after its heading. Focus it and use the left and right arrow keys: the value you move to is read out.
- Under every chart, **Data table** opens the same numbers as a table, with each part's share for the pie charts.
### Language
- The pages are in English or Vietnamese (Settings), and the page language follows your choice, so screen readers pick the right voice. Numbers and dates follow it too.
## 4. How it is tested
- **By the Maintainer, by hand** (November 2026): the website on Windows 11 and the Windows desktop app, with the keyboard only (mouse switched off) and Windows Narrator. No blocking problems were found.
- **On a real phone** (November 2026, version 4.6.0): the website on an iPhone 14 Pro with VoiceOver, in Safari, Chrome and Brave. It passed.
- **For 4.6.0**: the main pages and dialogs were walked through with the keyboard, and their accessibility tree was checked (names, roles, headings, landmarks, announcements) in English and Vietnamese, on a desktop and a phone-sized screen.
- **Automatically, on every change**: the contrast test above and the app's unit tests (where focus goes after a page change, the chart tables).
- **Before each release**: a short smoke test. That means a keyboard pass through the main tasks, a screen reader spot check, 200 % zoom and a narrow window, reduced motion, and a Windows contrast theme.
- **Not yet**: automated browser scans (such as axe or Lighthouse) in CI, and testing by people who use a wide range of assistive technology every day. Help is welcome.
## 5. Supported environments
| | Versions |
|---|---|
| Website | Current Chrome, Edge, Firefox and Safari on computers and phones. The oldest versions the site is built for are Chrome and Edge 111, Firefox 114, and Safari and iOS 15.4. |
| Desktop apps | Windows 10 and 11 (Microsoft Edge WebView2), macOS (WebKit 16.4 or newer), Linux (WebKitGTK 4.1) |
| Android app | Android 11 or newer |
Assistive technology:
- **Tested**: Windows Narrator on Windows 11, VoiceOver on iOS (iPhone 14 Pro: Safari, Chrome and Brave), and keyboard-only use.
- **Expected to work, not regularly tested**: NVDA and JAWS on Windows, VoiceOver on macOS, TalkBack on Android, browser zoom, Windows contrast themes, speech input. They rely on the same standard markup.
- **Limited**: Orca in the Linux desktop app, because WebKitGTK supports screen readers less well than the browsers do.
## 6. Known limitations
- **Creators' text isn't marked with its language.** Game titles, descriptions and tags come from itch.io in many languages, and a screen reader reads them in the page's language.
- **Cover images have a generic description** ("Game name cover"). What the image shows isn't described.
- **Charts**: the arrow keys only move left and right. The genre treemap can't be stepped through, but its numbers are in its data table and in the Genres chart. Chart text has a fixed pixel size, so a larger default font size in your browser doesn't change it (page zoom does).
- **Desktop apps**: there are no zoom keys inside the app, the window can't be maximized, and it can't be made smaller than 900 × 600. If you need larger text, use your system's display scaling or the website in a browser.
- **Android app**: pinch-to-zoom is off. The website can be zoomed in your phone's browser.
- **Animated covers in the apps**: the apps load covers straight from itch.io, so an animated cover keeps playing there.
- **Cloudflare's checks**: the verification check (website only) and the anti-spam check on the Suggest form are Cloudflare Turnstile widgets. They usually pass without anything to do. If one ever asks for something you can't do, email the Maintainer.
- **GitHub pages**: the policies, this statement and the issue forms live on GitHub, so GitHub's own accessibility applies there.
- **No external audit**, and one maintainer.
## 7. Reporting an accessibility barrier
If something stops you or slows you down, please say so. Partial reports help too.
- **GitHub**: open an [Accessibility barrier issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml).
- **Email**: **contact@poli0981.dev**. No GitHub account needed; English or Vietnamese both work.
Details that help, as far as you're comfortable sharing them (never send health information):
- what you were trying to do, and what happened instead;
- the page (its address) or the app and its version, shown on the About page;
- your device, operating system and browser;
- the assistive technology you use and its version, if any;
- a screenshot or a recording, if you can.
How much it gets in your way:
| Severity | Meaning |
|---|---|
| Critical | You can't do a main task at all, for example open a game or read its details. |
| Serious | You can, but only with great effort or a workaround. |
| Moderate | It's annoying or inconsistent, but you get there. |
| Minor | A small polish issue. |
What happens next. These are targets, not guarantees, since this is a solo hobby project:
- **Acknowledgement** within 7 days, often sooner.
- **A fix or a workaround**: Critical within 30 days, Serious within 60 days, Moderate and Minor in a later release.
- **Website fixes** go live when they are deployed; **app fixes** come with the next release.
- You'll be asked whether the fix works for you, and credited in the release notes if you want.
Security vulnerabilities don't belong in a public issue: see [SECURITY.md](SECURITY.md).
## 8. For contributors
Changes to the interface must keep [§3](#3-what-works-today) true:
- **Keyboard**: every control can be reached and used, focus stays visible and never gets lost.
- **Names**: every control has a label, with its text in both `webapp/src/lib/i18n/en.ts` and `vi.ts`.
- **Colour**: use the theme tokens. `npm test` checks contrast (4.5:1 for text, 3:1 for borders, focus and chart colours), and colour is never the only signal.
- **Motion**: respect `prefers-reduced-motion`; the shared CSS rule and `SERIES_ANIMATION` already do.
- **Screen reader**: check the change once with one (Narrator, NVDA, VoiceOver or TalkBack).
- **Markup**: prefer native elements and the Radix / shadcn components already in use, and add ARIA only when it's needed.
Documentation: headings in order, link text that says where it goes, alt text for images, header cells in tables, and the Vietnamese translation updated (or say in the pull request that it isn't).
The [pull request template](.github/pull_request_template.md) has the checklist.
## 9. Finding accessible games
The catalog shows the accessibility features that creators list on their itch.io pages, such as subtitles, configurable controls or colour-blind modes:
- on each game's page, under "Accessibility";
- as the Accessibility filter on the Games page, for example https://freeitchgames.win/games?access=Subtitles;
- in the "Accessibility Features" chart (Charts → Discovery).
Creators declare these features themselves, and the project doesn't verify them. If a game's information is wrong, report it with the "Bug Report" issue template.
## 10. References
- [Open Source Guides: Accessibility best practices for your project](https://opensource.guide/accessibility-best-practices-for-your-project/)
- [Open Source Accessibility toolkit](https://github.com/open-source-accessibility/accessibility-toolkit): this statement follows the outline of its ACCESSIBILITY.md example, in its own words.
- [W3C: Developing an accessibility statement](https://www.w3.org/WAI/planning/statements/)
## 11. Contact
- **Accessibility barriers**: the [issue form](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml) or **contact@poli0981.dev**.
- **Everything else**: see the addresses in [README → Legal](README.md#legal).
## 12. Final vibes
One person, one catalog, every way of browsing it. If something here doesn't work the way you use the web, the Maintainer would really like to hear it — that's how this list gets better. 🚀
| <a name="313---2026-05-05-credit-claude-code-as-ai-co-author"></a>[3.1.3](changelog/3.x/ver3.1.x.md#313---2026-05-05-credit-claude-code-as-ai-co-author) | 2026-05-05 | Credit Claude Code as AI co-author |
| <a name="312---2026-05-05-offline-link-fix--about-expansion--docs-sweep"></a>[3.1.2](changelog/3.x/ver3.1.x.md#312---2026-05-05-offline-link-fix--about-expansion--docs-sweep) | 2026-05-05 | Offline link fix + About expansion + docs sweep |
| [3.1.1](changelog/3.x/ver3.1.x.md#311---2026-05-04-cross-compile-macos-x86_64-from-apple-silicon) | 2026-05-04 | Cross-compile macOS x86_64 from Apple Silicon |
- **`scripts/update_info.py`** now reads an optional `INPUT_URL` env var (forwarded by
`update.yml` from `workflow_dispatch.inputs.url`) and appends it to the queue. Backwards
compatible: the daily cron still processes `temp_link.json` exactly as before.
- **`.github/workflows/update.yml`** gains `workflow_dispatch.inputs.url` so the webapp can
trigger a single-URL scrape.
## 2.x
---
| Version | Date | Highlights |
|---|---|---|
| <a name="200---2026-03-26-major-rewrite-"></a>[2.0.0](changelog/2.x/ver2.0.x.md#200---2026-03-26-major-rewrite-) | 2026-03-26 | Major Rewrite 🔧⭐ |
## [2.0.0] - 2026-03-26 (Major Rewrite 🔧⭐)
## 1.x
### Rewritten
- **`scraper.py`** — new shared module extracted from `update_info.py`. All scraping logic, session management, rate-limiting, and parsing utilities live here. Used by every script that touches itch.io.
- **`update_info.py`** — fully rewritten. Uses `scraper.py` module, `requests.Session` with automatic retry (backoff on 429/5xx), and random delays between requests.
- **`generate_md.py`** — fully rewritten with pipe-character escaping and all new data fields.
### Added
- **Free game detection** — `update_info.py` now checks if a game is free before scraping. Paid games are skipped automatically. Detection logic parses `div.buy_row` for price tags and button text.
- **`check_paid.py`** — new script. Re-checks every game in the list to see if it became paid. Paid games are removed and logged to `deleted_games.json` with reason and timestamp.
- **`check_alive.py`** — new script. Verifies that all game URLs still exist. Pages returning 404 or 410 are removed and logged. Transient errors (403, 5xx, timeouts) are kept.
- **`log_deleted.py`** — new script. Converts `deleted_games.json` → `deleted_games.txt` (human-readable log sorted by date).
- **`deleted_games.json`** — structured log of all removed games with URL, name, reason, and deletion timestamp.
- **New data fields** scraped from itch.io info table: `status`, `platforms`, `publisher`, `release_date`, `made_with`, `rating`, `rating_count`, `average_session`, `languages`, `inputs`. All fields default to `N/A` when not found.
- **Author/Authors handling** — scraper now checks both `Author` and `Authors` keys (itch.io uses either depending on the page).
- **Release date parsing** — extracted from `<abbr title="...">` for full datetime instead of abbreviated text.
- **NSFW detection** expanded — now also checks game description text and adds `sexual` keyword.
### Added (GitHub Actions)
- **`check_paid.yml`** — runs every 2 days at 04:00 UTC. Removes games that became paid.
- **`check_alive.yml`** — runs every 2 days at 07:00 UTC (staggered 3h after check_paid). Removes dead links.
- **`log_deleted.yml`** — runs after check_paid or check_alive completes. Exports deletion log.
- **`generate_table.yml`** — now triggers after update, check_paid, and check_alive workflows (not just update).
- **`update_csv.yml`** — now triggers after table generation (chained workflow).
### Improved
- **Rate limiting** — random delays (2.5–5s between requests, 15–30s batch pause every 20 requests) to avoid itch.io IP bans. Lighter delays (1–2.5s) for HEAD/status checks.
- **Retry logic** — `requests.Session` with `HTTPAdapter` + `Retry` (3 attempts, exponential backoff 2→4→8s) on 429/500/502/503/504.
- **Network error safety** — games are never deleted on transient network failures. Only confirmed 404/410 or confirmed paid status triggers removal.
- **Markdown table integrity** — pipe characters (`|`) in game data are escaped to prevent table breakage.
- **All fields use `N/A` consistently** — replaced mixed `""`, `"Unknown"`, `"No description"` with uniform `N/A` fallback.
- README rewritten with updated architecture diagram, project structure, field documentation.
- Workflow action versions updated to `actions/checkout@v6` and `actions/setup-python@v6` with Python 3.14.
---
## [1.0.5] - 2026-01-12 (Hotfix 🔧)
### Fixed
- UTF-8 decode issue when running `scripts/update_info.py`. See [#16](https://github.com/poli0981/free-games-itchio-list/issues/16).
## [1.0.4] - 2026-01-11 (Added Games + New Features ⭐)
### Added Games
Added 33 games. See [#22](https://github.com/poli0981/free-games-itchio-list/issues/22) and [#23](https://github.com/poli0981/free-games-itchio-list/issues/23).
### New Features
- Delete game with correct link in [`delete_game.py`](/scripts/delete_game.py). See [#20](https://github.com/poli0981/free-games-itchio-list/issues/20).
- Export JSON → `.csv`/`.xlsx` in [`export_csv.py`](/scripts/export_csv.py). See [#21](https://github.com/poli0981/free-games-itchio-list/issues/21).
- Check duplicate data in JSON file in [`check_duplicate.py`](/scripts/check_duplicate.py). See [#19](https://github.com/poli0981/free-games-itchio-list/issues/19).
## [1.0.3] - Date unknown (Improvements ⚙️)
### Improved
- Optimized workflow scheduling.
## [1.0.2] - Date unknown (Hotfix 🔧)
### Fixed
-`temp_link.json` not resetting to `[]` after GitHub Actions run.
## [1.0.1] - 2025-12-31 (Hotfix 🔧)
### Fixed
- Rewrote and added 2 issue templates.
- Updated [CONTRIBUTING](CONTRIBUTING.md).
## [1.0.0] - 2025-12-28 (Initial Release 🚀)
### Added
- Full curated list of free itch.io games with auto-daily updates via GitHub Actions.
| <a name="104---2026-01-11-added-games--new-features-"></a>[1.0.4](changelog/1.x/ver1.0.x.md#104---2026-01-11-added-games--new-features-) | 2026-01-11 | Added Games + New Features ⭐ |
Quick context so future Claude sessions don't have to re-derive it.
## What this repo is
A curated, auto-updating catalog of free itch.io games, published at **https://freeitchgames.win** (read-only for
everyone; the old github.io URL only redirects). Three layers share one JSON catalog:
1.**Python pipeline** — the data layer (GitHub Actions).
-`data_game/game_info_NNN.json` — chunked records, max 500 per file, 6,069 games on 2026-11-16. Serialization is fixed: `json.dumps(..., ensure_ascii=False, indent=4)`, no trailing newline (`json_io.dumps`) — the Worker port (`webapp/worker/catalog.ts`) emits identical bytes (`tests/fixtures/golden/`).
-`scripts/` — scanners never write the catalog: `update_info.py` (queued URLs) and `refresh.py` (rotating 1/7-per-day check; `--full` re-scrape) emit a URL-keyed **patch** (`patch.py`); `apply_patch.py` applies it to the latest `main` and runs `validate.py`; `bash/commit_push.sh` does fetch → reset → apply → commit → push with retries. Shared: `scraper.py` (session, `Pacer` + 429 back-off, parsing: the info panel incl. itch.io's 2025–26 rows — `AI Disclosure` ("AI Assisted", then what for) / `Content` linking `/games/tag-no-ai` → `ai_disclosure` + `ai_content`, `Accessibility` → `accessibility`; `description` = the creator's tagline (`og:description`), else the first sentence), `data_store.py` (chunks stay in place, rebalance only past thresholds, write-if-changed), `json_io.py`, `canonical.py` (canonical itch.io URL; vectors in `tests/fixtures/url_vectors.json`, shared with the Worker). Pipeline bookkeeping lives in `scripts/state/` (not published), including `ingest_outcomes.json` (how each queued link ended — added / duplicate / paid / dead / private / deleted / gave_up; patch key `ingest_outcomes`; the last 90 days, ≤ 5,000) that the admin's tracking and the cron's reconcile read. Tests: `pytest` (network blocked; `pytest --cov --cov-report=xml` → `coverage.xml` for SonarQube Cloud, gotcha 41). Lint: `ruff check scripts tests webapp/scripts`, `ruff format`, `vulture` (config in root `pyproject.toml`). Local env: Python 3.15 (`.github/python-version`, gotcha 39; ruff `target-version = "py315"`), `python -m venv .venv && .venv/Scripts/pip install -r requirements-dev.txt` (3.15 is in UTF-8 mode by default — no `PYTHONUTF8` needed, the workflows no longer set it). Both requirements files are hash-locked pip-tools compiles of `requirements*.in` — edit the `.in`, then recompile (gotcha 40).
2.**Cloudflare Worker + static assets** — `webapp/worker/` + `webapp/wrangler.jsonc`, deployed by **Cloudflare Workers Builds** from `main` (root dir `webapp`, build `npm run build`, deploy `npx wrangler deploy`; no deploy workflow). The catalog is bundled into the site at build time (`vite-plugins/catalog-data.ts` → `dist/data/pack/` compact packs + the legacy readable JSON in `dist/data/`, plus `data/urls.json` and `sitemap.xml`), so every data commit rebuilds the site.
3.**Web app + Tauri apps** — `webapp/src/` (React 19.3 + TypeScript 7.0 + Vite 8/rolldown + Tailwind + shadcn/ui + React Router 8), and the **Tauri 2 desktop + Android** read-only viewers in `webapp/src-tauri/` (same code; they fetch `https://freeitchgames.win/data/pack` and load covers straight from img.itch.zone). Plus `webapp/admin/` — the maintainer-only admin app (second Vite entry, served at `/admin/`).
Adding games: the public **Suggest** page (`/suggest`, Turnstile) and RSS discovery (Worker cron) feed a **D1 review queue** (the browser extension's `POST /api/ingest` was removed in 4.4.1; the extension `poli0981/itch-f2p-extension` and the Telegram bot `poli0981/telegram-scraper-bot` are archived repos); approving in `/admin` commits the URLs to `scripts/temp_link.json` as a GitHub App, which triggers `update.yml`. Since 4.4 the cron also approves by rule (`/admin` → Settings, on by default: unflagged `rss` / `form` items nobody rejected within 24 h, only those found after the switch-on baseline `since`, ≤ 100 per run) and queues the new free games of **followed itch.io collections** directly (removed or flagged ones go to the queue) — the policies say so (ToS §5, Privacy §2.4, Disclaimer §4). The Add page takes any text, a file or a collection, **Check**s it first (dry run), sends batches of 200 and follows each game's ingest (`/api/admin/track`).
## How to work in webapp/
```sh
cd webapp # Node 26 (.node-version; engines >=26)
npm ci
npm run dev # Vite on http://localhost:5173 (proxies /api and /img to wrangler dev on :8787)
npx wrangler dev # the Worker + built assets (run `npm run build` first); .dev.vars holds local secrets
npm run build # → webapp/dist/ (public app + /admin/ + /data + sitemap); Tauri builds use the same dir
npm test# vitest (worker/, src/lib); worker/test/* D1 tests spawn a local workerd via getPlatformProxy
npm run test:coverage # the same with v8 coverage → coverage/lcov.info (repo-root paths, for SonarQube Cloud)
npm run lint && npm run knip && npx tsc -b
npm run cf:types # after editing wrangler.jsonc (ignores .dev.vars via types.env; CI runs it with --check)
npm run cf:check # wrangler deploy --dry-run with the project's wrangler (what CI runs; after a build)
npx wrangler d1 migrations apply freeitchgames --local # local D1 (use --remote by hand for production)
npm run tauri:dev # native window; needs Rust toolchain
npm run tauri:build # native installers
npm run tauri icon -- path/to/source-1024.png # regenerate src-tauri/icons/
npm run tauri -- android init # generate src-tauri/gen/android (gitignored)
npm run tauri -- android build --apk --target aarch64 # arm64-v8a release APK (unsigned; CI post-signs)
```
Local admin without Access: put `DEV_ADMIN_EMAIL=you@example.com` in `webapp/.dev.vars` — honoured only when the host is localhost. Turnstile test keys work locally (`TURNSTILE_SITEKEY=1x00000000000000000000AA`, `TURNSTILE_SECRET=1x0000000000000000000000000000000AA`, `SITE_ORIGIN=http://localhost:<port>` in `.dev.vars`); add a 32+ character `GATE_SECRET` to try the verification gate under `npx wrangler dev` (on localhost the cookie is `fig_gate` without `Secure`, and no bot token is needed). `npm run dev` never sees the gate — except that its `/img` proxy to `wrangler dev` does. Android details live in `webapp/TAURI.md` → **Android APK**. Path alias: `@/*` → `webapp/src/*`.
## Worker (`webapp/worker/`)
-`index.ts` routes: `/img/*` (img.ts, behind the gate), `/api/health`, `/api/verify` (gate.ts), `/api/suggest` (suggest.ts), `/api/admin/*` + `/admin*` (admin.ts), the readable `/data/*.json` (legacy-data.ts), everything else that misses an asset → `spa.ts`. `run_worker_first` also lists `/` (otherwise served straight from `dist/index.html`) so the gate sees it, and the five legacy catalog files one by one (never a `!` pattern — gotcha 26). `scheduled()` (cron `23 */4 * * *`), four steps each in its own try/catch: `discover.ts` (one itch.io RSS feed per run, 6 h back-off on 429) → `QueueStore.reconcile` (queued → ingested / failed with the pipeline's outcome, read at head through the GitHub App; else in the catalog → ingested, > 3 days → failed `timeout`) → `automation.ts` (auto-approve + followed collections, ≤ 30 itch.io pages a run, ONE `[auto]` commit, D1 written only after it lands; the run's summary in settings `automation_last_run`) → `purge` (Suggest notes 180 d). The account is on **Workers Paid** (30 s CPU): admin catalog edits parse and rewrite ~3.8 MB in the Worker (≈ 25–30 ms for 100 removals).
-`ratelimit.ts` (since 4.5): every Worker request is counted first, per IP (IPv6 /64, `rateKey`) and per Cloudflare location (approximate, fails open), in one `ratelimits` binding per kind of traffic (counted per machine of the data centre: it holds for one-connection clients, the WAF holds for floods — gotcha 43) — `RL_SITE` 120/60 s (pages, public `/api`, legacy `/data`, misses), `RL_IMG` 600, `RL_ADMIN` 300; `RL_SUGGEST` 5 and `RL_GATE` 20 still apply on top to those POSTs. Verified bots (the gate's header) are not counted. Over a limit: 429 + `Retry-After: 60` — JSON `rate_limited` for `/api`, `/img`, files and `/data` (with CORS), the script-less EN/VI page of `gate-page.ts` for app pages. Keep every `period` 60 and a unique `namespace_id` in 88xx (staging 89xx): namespaces are **account-wide** and other Workers on the account (repolens, ticktune…) use 1001–1006, so the old 1001 / 1003 shared their counters (`ratelimit.test.ts` reads `wrangler.jsonc`). Layer 1 is the zone's WAF rate-limiting rule (Free plan: one rule, IP, 10 s; `docs/operations.md` §1 step 15): only it saves the Worker request a flood costs, and only it covers static assets.
-`img.ts`: `/img/<160|640>/<path on img.itch.zone>` — allow-listed against `data/urls.json`, edge cache → R2 `THUMBS` (`w{w}/<sha256>.webp`) → `cf.image` transform (stored once) → fallback streams the original with a 1-day cache (quota error 9422). The fallback original and a missing upstream image are also kept in `caches.default` for a day (GET only); widths are the exact strings `160` / `640` (a `Map`, no `Number()` aliases); background puts log failures. Upstream errors → controlled 502.
-`spa.ts`: `not_found_handling` is `"none"`, so misses reach the Worker: `/assets/*`, `/data/*` (a pack from an older deploy included — `no-store`, CORS) and file-like paths get a real 404 (`no-store`); app routes get the shell with 200; unknown paths and game slugs not in the catalog get the shell with **404**; with the gate on, a visitor without a pass gets the verification page instead (checked before the shell is fetched, so never a 304). Keep its `ROUTES` in sync with `src/App.tsx` and `src/hooks/useSeoHead.ts`.
-`gate.ts` + `gate-page.ts`: the **verification gate** (web only). App pages and `/img` need a pass: the `__Host-fig_gate` cookie (HMAC of its issue time, HttpOnly, `BOT_GATE_TTL_HOURS`, default 48) set by `POST /api/verify` after a Turnstile check (action `gate`, `RL_GATE`, same-origin); `GET /api/verify` reports `{enabled, valid, via, ttl}`. The page is self-contained (inline CSS/JS with a per-response CSP nonce, EN/VI, the site's og tags, 200 + noindex). Verified bots pass with `x-fig-known-bot: <GATE_BOT_TOKEN>` from a zone Transform Rule; clients that only claim to be a crawler get 503. `/assets`, `/data`, `/api/*`, `/admin*` and the other static files stay open. `turnstile.ts`: siteverify shared with Suggest (hostname + action checked; the test secrets skip both).
-`access.ts`: verifies `Cf-Access-Jwt-Assertion` with jose (issuer + AUD). Maintainer = email in secret `ADMIN_EMAILS` + same-origin writes (the only identity: the service-token ingest is gone since 4.4.1).
-`admin.ts`: API (queue list / approve / reject / check (dry run) / add / track / edit one or ≤ 100 (`/games/bulk`) / remove one or ≤ 100 (`/games/remove`; after the commit the audit row and the R2 cleanup are best effort → `warnings`, never a 500) / restore / activity / settings / itch.io collections) and the `/admin` shell with its own CSP (theme-script hash included). Request limits shared with the admin app: `limits.ts`. `collections.ts` reads public itch.io collections (gotcha 36); `automation.ts` holds the cron's rules (`planCollectionItems`: only URLs D1 has never seen and without a flag are queued directly — no re-add loop for games the ingest dropped). The maintainer's email goes only to the D1 audit log, never into a commit (the repo is public).
-`repo.ts` + `github.ts` + `catalog.ts`: writes as a **GitHub App** (installation token, cached per isolate) with GraphQL `createCommitOnBranch` + `expectedHeadOid` (verified commits; `commitWithRetry` rebuilds from the new head on a race). Reads use the raw media type (no base64/UTF-8 mojibake). `catalog.ts` ports `data_store.py` byte-for-byte (golden fixtures).
-`legacy-data.ts`: the readable catalog JSON (`index.json`, `game_info_NNN.json`, `count_history.json`, `deleted_games.json`, `urls.json`) goes only to apps 4.0–4.1.1 — `Origin``tauri://localhost` / `http(s)://tauri.localhost` → `env.ASSETS` passthrough + `Vary: Origin`; anyone else → **410** JSON with the repository links (`no-store`, CORS, a sampled `console.info` of the Origin). A nudge, not a security boundary: the data is public in the repo.
-`queue.ts`: URL classification (catalog → blocklist → pending → previously deleted) + the D1 store (`worker/migrations/`, additive only — never edit an applied migration; `0002` added `candidates.outcome`, `settings` and `watched_collections`; the `idempotency` table and `'ext'` in the `candidates.source` CHECK are unused leftovers of the ingest API removed in 4.4.1; URL lists bind in `IN` slices of 90, gotcha 37). `data.ts`: catalog facts read from the site's own `/data` via `env.ASSETS`, cached per isolate (loaded values only — see gotchas).
- Configuration: non-secret settings are `vars` in `wrangler.jsonc` (empty until setup); secrets (`GH_APP_PRIVATE_KEY` — the PEM GitHub downloads (PKCS#1) or PKCS#8; `github.ts` converts, `ADMIN_EMAILS`, `TURNSTILE_SECRET`, `GATE_SECRET`, `GATE_BOT_TOKEN`) via `wrangler secret put`, typed in `worker/env.ts` as optional. A feature whose settings are missing answers **503** (the gate just stays off); the public site needs none of them. `env.staging` = Worker `free-games-itchio-list-staging` on `staging.freeitchgames.win` (no cron, own R2/D1/rate-limit namespaces).
## Web app structure (`webapp/src/`)
-`routes/*.tsx` — one file per route (`/`, `/games`, `/games/:slug`, `/charts`, `/removed` (`/deleted` redirects), `/suggest`, `/settings`, `/about`, `/errors/:code`); `App.tsx` wires them; `components/app-router.tsx` picks **BrowserRouter on the web, HashRouter in Tauri**. `lib/legacy.ts` rewrites v3 `#/x` links to `/x` (crafted hashes go home) and deletes v3 PAT/GPG storage keys.
- Data: `lib/config.ts` (`PACK_BASE` = `/data/pack` on the web, `https://freeitchgames.win/data/pack` in Tauri). **Packs** (since 4.2): `lib/data/pack-format.ts` (pure, shared with the build plugin: records by column, dictionaries for repeated strings and every string list; `manifest-v1.json` names per chunk a `main` pack — every field but `description` — and a `desc` pack, plus `deleted` / `history`; files are `<sha256 prefix>.bin`, deflate-raw, served `immutable`). `lib/data/catalog.ts` loads them (`['db','all']` →`{ games, index: {total_games, last_updated}, chunks }`; the manifest revalidated per load and shared 10 s; a main-pack 404 → manifest `cache: 'reload'` + one retry; an unchanged manifest returns the previous result). `lib/data/compression.ts`: `DecompressionStream('deflate-raw')`, else lazy `fflate`. `Game` has **no `description`**: `hooks/useDescriptions.ts` loads `['desc', <file>]` on demand (game page: its chunk; Games search: all, `filterGames(…, descriptions)`).
- Cache: react-query persisted to IndexedDB (`webapp.query-cache`, 7 days) by `lib/data/persister.ts` — byte 0 = format (1 deflate-raw, 0 plain), then the JSON; a legacy string is dropped; writes throttled 1 s and skipped when no data object changed. Persisted: `db`, `deleted`, `count-history` and only the `desc` files the current catalog names (`shouldPersistQuery`); stale `desc` queries are removed after a `db` success. `CACHE_BUSTER = ${APP.version}:data-v2`. **`gcTime` must stay >= persist `maxAge`.**
- Layout: `components/site/*` (sticky top nav + global search with the `/` shortcut + display menu + phone sheet menu; footer) — the window scrolls, not `<main>`. `/` is the Welcome page (`routes/welcome.tsx`).
-`/games`: search, filters, sort and page live in the URL — `lib/game-filters.ts` (`parseQuery` / `toParams` drop defaults; params `q genre platform status tag lang input engine ai access rating browser sort page`; `ai` treats "N/A" / a missing field as its own "Not disclosed" value and lists its options in a fixed order (`aiRank`); unit-tested) — rendered by `components/games/*` (filter chips with facet counts that ignore their own filter, a desktop ARIA table / phone list chosen by `useIsMobile`, 100 per page; the detail page's breadcrumb links back to the same list via router state). Counts show the whole catalog ("2,729 of 2,811") because 18+ games are hidden by default.
-`components/charts/` (19 charts, 4 lazy tabs loaded with `lib/lazy-preload.ts` — preloaded when idle or on hover/focus, rendered without a Suspense fallback once loaded — and kept mounted once shown (gotcha 33; skeletons in `chart-skeletons.tsx` match the cards), every series spreading `SERIES_ANIMATION` (300 ms, no delay; a test checks), **no barrel `index.ts`**; every Recharts tooltip/cursor comes from `chart-theme.ts` + `chart-tooltip.tsx`, every pie legend from `LEGEND_BASE` there; every chart container spreads `chartAria(id)` (named by its card's h2 + description + arrow-key hint), every `<Pie>` has `rootTabIndex={-1}`, every `ChartCard` gets an `id` and a `table` (a lazy `<details>` "Data table" built with `lib/chart-table.ts`), and the tooltip reads its text into the card's polite live region through `ChartAnnounce` (a ref, no re-render — gotcha 33); `chart-theme.test.ts` checks all four; below `md` the charts get 12 px legends / 11 px ticks from a media block in `index.css`, the tab bar is one row of equal tabs, and Languages / Avg session switch to horizontal bars via `useIsMobile`), `components/game-thumb.tsx` (`lib/thumbnail.ts` → `/img/160|640/...` on the web, the original URL in Tauri), `components/legal-gate.tsx` (a non-dismissable Radix dialog **over** the page, so deep links land where they pointed; links flagged `inGate` in `lib/about.ts`; re-prompts when `LEGAL_VERSION` in `stores/prefs.ts` changes; no "Leave" button in Tauri).
- Styling: **Tailwind v4** via `@tailwindcss/vite` (no PostCSS, no `tailwind.config`); tokens are hex CSS variables in `src/index.css` (`:root` / `.dark`, `@theme inline`; `--brand-soft`, `--thumb`, `--success`, `--scrollbar-thumb(-hover/-active)` besides the shadcn set) and must match the approved mockup — except where WCAG 2.2 AA needed more (4.6.0): `--primary`#6a48f5 (white text 5.44:1), `--primary-text` for purple text (#9a83ff in dark), `--input`#8a8a93 / #6b6b75 for field borders and the off switch (3:1), `--destructive-solid` for filled destructive buttons; `--brand` keeps the mockup's #7c5cff for the logo (as do the favicon, `og.png`, the app icons and the gate page's logo). `webapp/scripts/check-contrast.test.mjs` fails CI when a token pair or a chart colour (`components/charts/palette.ts`) drops below 4.5:1 (text) / 3:1 (borders, ring, chart marks); `lib/color.ts` does the maths. A `@media (forced-colors: active)` block gives selected tabs / pressed toggles / the current page / the active option and switches the system highlight (Windows contrast themes). Themed scrollbars (`@layer base`, only under `(hover: hover) and (pointer: fine) and (forced-colors: none)`): `::-webkit-scrollbar*` for Chromium/Safari, `scrollbar-color` / `scrollbar-width: thin` for Firefox only (gotcha 28); "Hide scrollbars" = unlayered `html[data-scrollbars='hidden']` rules (`hooks/useScrollbarsEffect.ts`). On mouse devices `<html>` reserves the scrollbar gutter, released while a dialog locks scrolling (gotcha 35). The theme: `stores/theme.ts` (synced across tabs, site ↔ admin), `hooks/useThemeEffect.ts` (`.dark` + the `theme-color` metas), an inline pre-paint script in both HTML entries (gotcha 34), and the display menu's button shows `components/theme-icon.ts`'s icon for the theme in use. Self-hosted Geist / Geist Mono (`@fontsource-variable/*`, CSP `font-src 'self'`). Numbers and dates go through `lib/format.ts` (`useFormat`: en-GB / vi-VN). `webapp/scripts/gen_assets.py` redraws favicon, PWA icons and `og.png` from the same tokens and the Geist fonts in `node_modules`.
-`lib/gate.ts` (web only): when a tab comes back into view or a cover fails and the verification pass may have run out (`webapp.gate` hint), it asks `GET /api/verify` and reloads into the verification page; `lib/reload.ts` is the shared at-most-every-30-s reload guard.
-`hooks/useSeoHead.ts` sets canonical + robots per route (index.html has no static canonical/og:url on purpose).
- Accessibility (statement: root `ACCESSIBILITY.md`; target WCAG 2.2 AA): after an in-app navigation `App.tsx`'s ScrollManager moves focus to the new page's h1 (`lib/route-focus.ts` decides: not on first load or query-only changes; a #hash focuses its section; Back focuses the link last used on that entry), waiting for lazy routes with `components/focus-target.ts` (`whenPresent`, 10 s; `focusElement` adds `tabindex=-1` + `data-focus-target`, which hides the ring). Dialogs without a trigger return focus themselves (18+: the opener, `requestNsfw(returnFocus)`; legal gate: the page h1); menus that navigate `preventDefault` their `onCloseAutoFocus` (gotcha 46). The "/" shortcut is a pref (`slashShortcut`, Settings → Accessibility; WCAG 2.1.4). `CardTitle` renders an h2. `ExtLink` appends "(opens in a new tab)" / "(opens in your browser)" for screen readers. English-only strings shown on a Vietnamese page carry `lang="en"`; `<html lang>` turns `vi` only once the VI dictionary is in. `html { scroll-padding-top }` keeps focus clear of the sticky header. No a11y linter: `eslint-plugin-jsx-a11y` peers ESLint ≤ 9.
-`lib/i18n/` — `en.ts` is the source of truth; `vi.ts` is `Record<MessageKey, string>` and must never be static-imported (lazy chunk).
-`lib/about.ts` — keep `THIRD_PARTY` up to date when adding npm deps; `LEGAL_LINKS`; `APP.version`.
- Code split (`vite.config.ts` rolldown `codeSplitting.groups`): `vendor-react` (priority 100 — must claim React first), `vendor-query`, `vendor-ui`. There is deliberately **no vendor-charts group** (it pulled React/clsx in and put Recharts on the first load); Recharts stays in the lazy chart chunks. Initial load ≈ 189 KB gzip (JS + CSS, gzip -9, measured for 4.6.0; 4.2 added ~4.6 KB for the pack loader, persister and `useQueries`, 4.6 ~3 KB for focus management and the accessibility strings) plus ~51 KB of Geist woff2; catalog data on a first visit ≈ 264 KB (main packs + log + history), descriptions ≈ 170 KB on demand. `fflate` is a lazy chunk, never preloaded. Web build `target` is Safari/iOS 15.4 (Radix class static blocks otherwise break iOS 15); Tauri uses the default.
## Editable vs read-only fields
Each game has **20** fields (plus optional `added_at` / `updated_at`, appended by the pipeline, and since 4.3 the optional scraper fields `ai_disclosure` (`No AI|AI Assisted|N/A`) / `ai_content` / `accessibility`, which the daily refresh adds to older records — schema changes are additive only, installed v3 apps may still read the raw JSON). Only **3** are maintainer-editable: `safe_virus` (`?|Yes|No|Caution`), `notes`, `nsfw` (`Yes|No`) — via `/admin`. The other 17 are scraper output; no scrape (not even `--full`) overwrites the 3 editable fields.
## GitHub Actions
| Workflow | Trigger | Notes |
|---|---|---|
| `update.yml` | Push to `main` touching `scripts/temp_link.json` + daily 01:23 UTC + `workflow_dispatch` (`url`) | Ingest queue → patch → `commit_push.sh`. Workflow-level `concurrency: ingest` with **`queue: max`** (the default queue replaces a pending run, which would drop its dispatched `url`). A dispatched `url` is processed first and written to `temp_link.json` (`queue_add`) until it reaches a final outcome. Failed fetches count as an attempt only ≥ 6 h apart (`last_attempt`; 3 → given up), and a 429 counts as none. GitHub-App pushes (the admin Worker and its cron) trigger it; its own `GITHUB_TOKEN` push does not (no loop). Keep the filename. |
| `refresh.yml` | Daily 02:47 UTC + `workflow_dispatch` (`budget`, `url`, `allow_mass_removal`, `full`) | scan (read-only, 55-min step timeout, checks out the branch as it is when the job starts — not the queued SHA — so runs waiting in the queue see the previous run's state; patch artifact uploaded `if: always()`) → apply (`!cancelled()`: a failed / timed-out scan's checkpoint is applied, a cancelled run's is not) → notify. Workflow-level `concurrency: refresh-pipeline` + `queue: max` runs one whole scan → apply at a time (scheduled, manual and force-update runs alike). Removal needs the same 404/410, paid or `private` (itch.io's password form, `is_password_protected`; ingest drops such links as final) strike seen again ≥ 20 h after the first sighting (`strike_at`). Checkpoints never carry removals. **Mass-change guard:** a run whose removals or new strikes exceed max(10, 10 %) of the games it checked withholds all its removals and marks them — and, on a strike spike, all its strikes — `withheld_at`; later runs keep withholding those (they take at most half a run's budget) until a healthy check clears them, and alert (`mass_change`) — that pattern means itch.io markup changed; dispatch with `allow_mass_removal` only after checking on itch.io. `apply_patch.py` re-checks the same per-run limit and max(25, 5 %) of the catalog unless `ALLOW_MASS_REMOVAL=1`. |
| `force_update.yml` | `workflow_dispatch` ONLY (`url`, `budget`, `allow_mass_removal`) | Dispatches `refresh.yml` with `full: true` (`actions: write`; it used to call it through `uses:`, which failed at startup with no annotation): re-scrapes every scraper field for one URL or the next batch (rotates on `full` timestamps). Dispatch it N times in a row to cover N consecutive batches (FIFO, each from the latest main). Always preserves `safe_virus` / `notes` / `nsfw`. Canonical tool for repairing mojibake. |
| `notify-failure.yml` | `workflow_call` | Discord (`DISCORD_CI_WEBHOOK`) on failure / **cancelled** (job-level timeouts end as cancelled) / rate-limited / mass change / failed Cloudflare build. |
| `python-ci.yml` / `webapp-ci.yml` | PRs (+ pushes for Python) | ruff + format + vulture + pytest + `validate.py` (both requirements locks installed at once, so drifting pins fail) / `npm ci --ignore-scripts` + `npm run check:tauri` (gotcha 31) + `npm run cf:types -- --check` + lint + knip + vitest + build + `npm run cf:check` (`wrangler deploy --dry-run`). SonarQube Cloud runs in `sonarcloud.yml`. |
| `sonarcloud.yml` | Push to `main` + PRs (both skip data-only and `.md`-only changes) + `workflow_dispatch` | SonarQube Cloud CI analysis (gotcha 41): `token` (no `SONAR_TOKEN` — Dependabot and fork PRs — → notice, the rest skipped) → `coverage` (pytest-cov + Vitest v8, no secrets; artifact kept 1 day) → `scan` (`sonarqube-scan-action`, full history, `sonar.projectVersion` from `webapp/package.json`; the only step that uses the token). |
| `qodana.yml` | Push to `main` + PRs (both skip data-only and `.md`-only changes) + `workflow_dispatch` | Qodana (JetBrains) analysis (gotcha 49): `tokens` (no Qodana secrets — Dependabot and fork PRs — → notice, the rest skipped) → three jobs, one per Qodana Cloud project and token: `typescript` (`qodana-js`, native, `webapp/qodana.yaml`), `python` (`qodana-python`, native, root `qodana.yaml`), `rust` (`qodana-rust`, Docker image, `webapp/src-tauri/qodana.yaml`). Whole-project scans (`pr-mode: false`), no PR comment; each `qodana.yaml` has a quality gate of 0 problems (`failureConditions`), so a finding fails its job. |
| `deploy-status.yml` | Hourly + manual | Not a deploy. `bash/cf_build_status.sh` walks main's first-parent history to the latest finished `Workers Builds: free-games-itchio-list` check run (Cloudflare posts it only when a build ends; branch commits carry preview builds under the same name) and alerts once per failed build (cache key per check-run id, saved after the Discord post). Scheduled because GitHub never starts `check_run` workflows for `GITHUB_TOKEN` pushes (the data commits). |
| `release_desktop.yml` | Tag `v*` push, or manual | `create-release` makes the single draft (id passed to tauri-action v1 `releaseId`); release builds use **no** npm/cargo caches (cache-poisoning). Win + macOS aarch64 + macOS x86_64 (cross-compile) + Linux (`ubuntu-22.04` for a low glibc floor). Uploads `.dmg` / `.app.tar.gz` / `.pkg` (macOS), `.msi` / `.exe` (Windows), `.deb` / `.rpm` / `.AppImage` (Linux). macOS `.pkg``--identifier` reads `tauri.conf.json`. |
| `release_android.yml` | Tag `v*` push, or manual | Tauri **Android** build → arm64-v8a APK, **post-signed** with `zipalign`+`apksigner` (gen/ stays gitignored). Tag → attaches to the same draft Release; manual dispatch → workflow artifact. Secrets: `ANDROID_KEYSTORE_BASE64` / `ANDROID_KEYSTORE_PASSWORD` / `ANDROID_KEY_ALIAS`. |
| `announce-release.yml`, `notify-release-pipeline.yml` | Release published / pipeline runs | Reusable workflows from `poli0981/.github`, SHA-pinned — but at that pin they still check out their notifier script from that repo's `main`. |
| `announce-discussion.yml` | Release published; push to `main` touching `CHANGELOG.md` / `changelog/**` | Local. The release goes to Discussions → Announcements, a changelog push to → General unless the head commit says `[skip-discuss]`. |
All workflows: `permissions: {}` at the top, per-job grants, actions pinned by commit SHA. Python installs are hash-locked and wheels only (`pip install --require-hashes --only-binary :all:`, gotcha 40); npm installs skip install scripts (`npm ci --ignore-scripts` — esbuild's and workerd's launchers find their platform binary without them).
## Release / tag process
```sh
git fetch origin
git tag -s vX.Y.Z origin/main -m "summary"
git push origin vX.Y.Z
# release_desktop.yml's create-release job opens ONE draft; desktop + Android jobs upload into it.
# When every asset is there, edit the notes and publish (this fires the announcements):
gh release edit vX.Y.Z --draft=false
```
Draft-first: **never**`gh release create` by hand before CI — tauri-action v1 refuses to upload into a published release, and announcements would go out before installers exist. Merge PRs into `main` with squash or a merge commit, never by fast-forward pushing a branch: its commits' preview-build check runs would then sit on main's own line and confuse `deploy-status.yml`. Tag from `main` only. Release notes go to `changelog/<major>.x/ver<major>.<minor>.x.md` plus a row in the `CHANGELOG.md` index (each row keeps the anchor of the old single-file heading as `<a name>`: published release notes link to them). Versions live in `webapp/src/lib/about.ts` (`APP.version`), `webapp/package.json`, `webapp/src-tauri/tauri.conf.json` and `Cargo.toml` (+ `Cargo.lock`) — keep them equal. GPG signing is wired through gpg-agent (`commit.gpgsign=true`, so `git tag -s` and `git commit` both sign; the pinentry must be answered — in unattended sessions commits fail rather than going unsigned). Signing key since 2026-10-10: `838884804847BE7AE5FCF0A96AD1AB0921B96825` (ed25519 certify-only primary, generated locally and never published before; signing subkey `ED0BFD3005662D5D`; `user.signingkey` = the primary fingerprint, global + repo). The old key `03F965C2E2DB5C6B` is **revoked** (compromised: it sat in the browser extension's storage, Sept 2026); tags up to v4.3.0 and older commits carry it. The owner's offline backup and revocation certificates live outside the repo.
## Licenses & policies
Code **MIT** (`LICENSE`); catalog data **CC BY 4.0** for the maintainer's contribution — excluding creators' descriptions, cover images, names/trademarks (`data_game/LICENSE.md`, `LICENSES/CC-BY-4.0.txt`); docs **CC BY 4.0**; map + non-affiliation in `NOTICE.md`. Policies (EN in `docs/`, VI mirrors in `docs/i18n/vi/`, English controls): ToS (website + data + content removal), EULA (desktop/Android binaries only; also `webapp/src-tauri/installer/EULA.rtf`), Privacy Policy, Disclaimer, `SECURITY.md`, `CODE_OF_CONDUCT.md`. `ACCESSIBILITY.md` (root: GitHub's accessibility community health file; VI mirror `docs/i18n/vi/ACCESSIBILITY.md`) is a statement, not a policy to accept — no `LEGAL_VERSION` bump when it changes, but keep its §3 (what works) and §6 (known limitations) in step with the code; barriers come in through `.github/ISSUE_TEMPLATE/accessibility.yml` (label `accessibility`) or contact@. When a policy changes, bump `LEGAL_VERSION` (`webapp/src/stores/prefs.ts`) and the dates in `about.legal.desc` (EN/VI) so the legal gate asks again. Contact addresses `contact@ / legal@ / privacy@ / security@ / takedown@poli0981.dev` are aliases of the maintainer's Google Workspace mailbox (not Cloudflare Email Routing; the Privacy Policy lists Google as the email processor). The maintainer's site https://poli0981.dev/ and channel hub https://poli0981.dev/links/ are linked from the About page (`DEV` in `lib/about.ts`).
## Known gotchas (cost a release each — don't relearn)
1.**`universal-apple-darwin` + `bundle_dmg.sh` is fragile** in headless CI. Use per-arch (`aarch64-apple-darwin`, `x86_64-apple-darwin`).
2.**`macos-13` is retired** from free GitHub-hosted runners. Cross-compile x86_64 from `macos-latest`.
3.**Tauri icons must exist before build.**`npm run tauri icon -- path/to/source.png`; the 1024×1024 source is gitignored, generated icons are committed.
4.**Tauri doesn't ship `.pkg`.** Built with `pkgbuild` after tauri-action and uploaded via `gh release upload`; the step uses `if: ${{ !cancelled() && … }}` so a DMG flake doesn't drop the PKG while a cancel still stops it.
5.**Vite v8 `base`** only accepts `'./'`, an absolute URL, or an empty string. Web uses `'/'` (BrowserRouter deep links), Tauri `'./'`.
6.**TypeScript 7 has no JS API (expected in 7.1), and typescript-eslint needs one** (peer `typescript <6.1`). So in `webapp/package.json``typescript` is an alias of `@typescript/typescript6` (the 6.0 API for typescript-eslint and `scripts/i18n-edit.mjs`; bin `tsc6`) and TS 7 is `@typescript/native` (`npm:typescript@^7`), whose `tsc` is what `npm run build` / `npx tsc -b` run — `npx tsc --version` must say 7.x. Drop the alias once typescript-eslint accepts TS 7; never let Dependabot move the alias to 7. `baseUrl` is gone since TS 6: use `paths` alone.
7.**lucide-react v1+** removed brand icons (`Github`). Use `Library`, `Database`, etc.
8.**`bundle.windows.nsis.license` does NOT exist in `@tauri-apps/cli` 2.11** — use top-level `bundle.licenseFile`, and it must be **RTF** (WiX `.msi` requires it; NSIS auto-detects). File: `webapp/src-tauri/installer/EULA.rtf`.
9.**The bundle `identifier` must be alphanumeric** (`com.poli0981.freegamesitchio`): Android rejects `-`, Tauri's validator rejects `_`; one identifier serves every platform.
10.**Android signing: `zipalign` BEFORE `apksigner`**; never edit the generated Gradle; never lose the keystore. `versionCode = major*1e6 + minor*1e3 + patch` from `tauri.conf.json`. **`minSdkVersion` 30 (Android 11) is the install gate** — change it only in `tauri.conf.json` (`bundle.android.minSdkVersion`); no runtime OS check by design (reach ≈ 86.9 % mid-2026; see `docs/pc_spec.md`). The Android JDK setup must NOT use `cache: gradle` (gen/ doesn't exist at checkout).
11.**`webapp/dist/` is gitignored and `assets.directory` must be `./dist`.** In Sept 2026 a config-less deploy served the raw `webapp/` tree (source exposed).
12.**A Worker with static assets gets no `ctx.access`** — verify the Access JWT yourself (access.ts). **`workers_dev` and `preview_urls` must stay `false`**: those hostnames bypass Access.
13.**`public/_headers` applies only to responses served straight from assets**, not to responses the Worker builds (set headers in `worker/http.ts`). Responses fetched through `env.ASSETS` do carry them.
14.**With `run_worker_first` as an array, the asset layer's SPA fallback answers every miss before the Worker** — a stale hashed chunk got `index.html` + the year-long immutable cache. Hence `not_found_handling: "none"` + `spa.ts`.
15.**Never share an in-flight promise across requests in a Worker** (cache only resolved values): a pending subrequest dies with the request that started it (client disconnect) and every later awaiter hangs.
16.**itch.io cover URLs are signed per size**, so you can't rewrite `/original/` to a smaller variant — resizing goes through Image Transformations (`cf.image`) and R2.
17.**GitHub Actions concurrency keeps at most one *pending* run per group by default** and cancels the older pending one — use `queue: max` where a queued run carries unique input. A called workflow must not request its caller's group (deadlock → cancelled). **A queued run checks out the SHA from when it was triggered** (`workflow_dispatch`: the branch head at dispatch time), so runs waiting behind each other read the same state unless the job checks out `ref: ${{ github.ref }}` (refresh.yml's scan does).
18.**Pushes made with `GITHUB_TOKEN` trigger no workflows** (no ingest loop), and GitHub never starts `check_run` workflows for them (hence the scheduled `deploy-status.yml`). Workers Builds posts its check run only when a build ends.
19.**`wrangler types` reads `.dev.vars`** — `npm run cf:types` points it at the empty `types.env` so the committed `worker-configuration.d.ts` never depends on local secrets. Don't use `secrets.required` until every environment has the secrets (deploys fail without them).
20.**D1 migrations are applied by hand** (`npx wrangler d1 migrations apply freeitchgames --remote`), never in the build — and before deploying code that needs them. Production `freeitchgames` was created by command (APAC); its `database_id` is in `wrangler.jsonc` (not a secret). **R2 must be enabled on the account** (dashboard, payment method) before `wrangler r2 bucket create`; a deploy whose bucket is missing fails.
21.**React Router 8 wraps navigations in `startTransition` by default**: `useSearchParams` then returns the previous URL until the transition commits, so URL-driven state (the Games filters) overwrote itself on quick clicks. Both routers in `components/app-router.tsx` pass `useTransitions={false}`.
22.**`window.confirm` / `alert` / `prompt` do nothing in the macOS app** (wry's WebKit answers "Cancel"). Use in-app dialogs (`components/nsfw-dialog.tsx` + `requestNsfw()` in `lib/nsfw.ts`).
23.**The design tokens are hex: write `var(--x)`, never `hsl(var(--x))`.** The invalid colour painted the Recharts hover band black and left tooltips transparent (fixed in 4.1.0).
24.**Recharts 3 makes charts focusable** (`accessibilityLayer`, plus `tabindex` on inner `<g>`s): a mouse click focused the SVG, Chromium drew its black focus ring and the tooltip stuck on the first item. `ChartCard` keeps mouse clicks from moving focus; keyboard focus keeps the `--ring` outline.
25.**The verification gate fails open, and its off switch is deleting `GATE_SECRET`** (`BOT_GATE` changed in the dashboard is undone by the next deploy). It also needs `GATE_BOT_TOKEN` + the zone Transform Rule — without them Google would get the challenge; a client that only claims to be a crawler gets a 503, never the noindex page. Don't gate `/data`: every app version reads it — `/data/pack/*` (4.2+), and the legacy JSON (4.0–4.1.1, Tauri origins only; browsers get 410). Keep those legacy files in `dist/`: the Worker also reads `urls.json` and `deleted_games.json` through `env.ASSETS`.
26.**A negative `run_worker_first` pattern (`!/data/pack/*`) sends a missing file straight to the asset worker**, whose 404 still gets the `_headers` rules — for a pack, the year-long `immutable`, so a browser would cache the 404 of a name that can come back (rollback). List the Worker-first files positively; pack misses then reach `spa.ts` (`no-store`).
27.**A `desc` pack matches its games by row, so only within one build.** Load the `desc` named in the same `db` result; on a 404 refetch `db` (`useDescriptions.ts`), never re-resolve a desc file against a newer manifest for games already on screen.
28.**In Chromium 121+, `scrollbar-color` or `scrollbar-width` on an element switches its `::-webkit-scrollbar` styling off.** Keep the standard properties Firefox-only (`@supports not selector(::-webkit-scrollbar)`), except `scrollbar-width: none` for hiding.
29.**Pack names are content hashes: the build must stay deterministic** (column and dictionary order, zlib level 9 — a Node/zlib upgrade only re-downloads once), **and no hash may reach the JS bundle** (data-only deploys keep JS byte-identical; the manifest is fetched, never imported). `_headers` joins a header set by two matching rules with a comma — give each path one `Cache-Control`.
30.**itch.io shows the `Published` and `Updated` info rows only for a few weeks** after the event (every `Published` date in a 250-page sample of Oct 2026 was under four weeks old); an explicit `Release date` row stays. That is why `release_date` is N/A for most older games, and why a `--full` re-scrape keeps a known `release_date` / `thumbnail` instead of writing N/A (`KEEP_KNOWN_FIELDS` in `refresh.py`).
31.**Tauri crates and their npm packages must share major.minor** (`tauri` ↔ `@tauri-apps/api`, `tauri-plugin-x` ↔ `@tauri-apps/plugin-x`): `tauri build` refuses to build otherwise, and only the release workflows run it — every v4.3.0 release build first failed on `tauri-plugin-opener` 2.6.0 vs `@tauri-apps/plugin-opener` 2.7.0 after Dependabot bumped the npm side alone (#119). Webapp CI's `npm run check:tauri` (`webapp/scripts/check-tauri-versions.mjs`, lock files only) now fails such a PR; Dependabot's cargo updates run weekly on Mondays like npm so both groups arrive together. Fix a one-sided bump with `cargo update -p <crate>` in `webapp/src-tauri/`.
32.**Recharts hides category labels silently and styles legends its own way.** The default `interval="preserveEnd"` keeps a label only if its line box (font size × 1.5) plus `minTickGap` (5) fits its row, and the first one only if half of it fits above: the 15-row Genres chart showed 7 labels, without the two largest genres — category axes set `interval={0}`. A label wider than the axis wraps onto two lines, measured at the 16px body size unless `style` carries a size with a unit (`singleLineTick()` in `chart-theme.ts`). `<Legend>` sorts alphabetically (`itemSorter: 'value'`) and colours each label like its slice (amber/green text on white fails contrast) — pies spread `LEGEND_BASE`.
33.**Recharts' ResponsiveContainer unmounts its chart when it measures 0×0** (`display: none`, e.g. Radix's `hidden` panel): a hidden tab must keep its size. The Charts page force-mounts visited tabs and hides the inactive ones with `absolute inset-x-0 top-0 h-0 overflow-hidden invisible` + `inert` (no scroll height, no focus); switching back otherwise rebuilt every chart and replayed its animation. Its panel elements are memoised, so a tab switch re-renders only the tab bar (a re-render restarts Recharts tweens).
34.**The inline theme script's sha256 is in three CSPs**: `public/_headers`, `src-tauri/tauri.conf.json` and `THEME_SCRIPT_HASH` in `worker/admin.ts`. Change the script and `scripts/check-csp-hashes.test.mjs` fails with the hash to paste. A wrong hash only blocks the script (the old light flash). Keep `%` and `import(` out of it (Vite rewrites them in HTML).
35.**`scrollbar-gutter: stable` vs dialogs**: fixed overlays stop at the reserved gutter, and react-remove-scroll-bar adds the scrollbar width as body margin on top. Hence `html:not(:has(> body[data-scroll-locked]))` — the gutter is released while a dialog locks scrolling, which is then exactly the old behaviour.
36.**itch.io collection JSON** (`/c/<id>/<slug>?format=json&page=N`): `&page=1` redirects to the HTML page (page 1 has no `page`); a wrong or missing slug redirects to the canonical URL **without** the query string (re-request with the slug from `Location`); an unknown id answers 500; link attributes come in any order; past the last page `num_items` is 0. Zero cells while `num_items > 0` means changed markup: `collections.ts` reports it (422) and adds nothing.
37.**D1 counts every statement of a batch** towards its 1,000 queries per invocation: bind URL lists in `IN (…)` slices of ≤ 90 (100 bound parameters at most), as `setStatus` / `reconcile` / `markIngested` do, never one statement per URL.
38.**npm 11.20+ (Node 26) gates dependency install scripts on `allowScripts` in `webapp/package.json`.** esbuild and workerd are approved by name (their postinstall only checks the platform binary). A new dependency with an install script shows up in `npm install-scripts ls`; review it, then `npm install-scripts approve <pkg> --no-allow-scripts-pin` (name-only, so Dependabot bumps stay covered).
39.**Dependabot's pip updater reads `.python-version` and aborts on a Python it doesn't support** (3.10–3.14 as of Oct 2026): a `3.15` there stopped pip version updates and the pip dependency graph ("Dependabot detected the following Python requirement … '3.15.*'"). So the CI pin lives in `.github/python-version`, which only `setup-python`'s `python-version-file` reads (python-ci, refresh ×2, update); move it back to `.python-version` once Dependabot lists 3.15.
40.**The Python requirements are hash-locked pip-tools compiles** — `requirements.txt` ← `requirements.in`, `requirements-dev.txt` ← `requirements-dev.in` (`-c requirements.txt`) — installed everywhere with `--require-hashes --only-binary :all:`, so a new release of any dependency, indirect ones included, can't reach the jobs that push to `main`, and no sdist build script runs. After editing a `.in`, recompile with **pip-tools on Python 3.14**: `pip-compile --generate-hashes --allow-unsafe --strip-extras requirements.in`, then the same for `requirements-dev.in`. Dependabot takes the Python version from the `# … autogenerated by pip-compile with Python X.Y` header and supports ≤ 3.14 (gotcha 39); the hashes cover every file of a release, so CI's 3.15 still finds its cp315 wheels. `colorama` is listed in `requirements-dev.in` because pytest needs it on Windows only: a lock compiled on Linux (Dependabot's) would otherwise leave it out and the hash-checked local install would fail. Keep those pip commands in a block scalar (`run: |`): in a plain YAML scalar the `: ` of `:all: -r` makes the whole workflow file invalid — GitHub then records a 0-job failed push run named after the file, and a PR simply shows no check for that workflow.
41.**SonarQube Cloud analyses in CI** (`sonarcloud.yml` + `sonar-project.properties`; project `poli0981_free-games-itchio-list`, public). Automatic Analysis is switched off on sonarcloud.io — switched back on, it makes the CI scan fail. PRs get a "SonarCloud Code Analysis" check from the SonarQube Cloud app; Dependabot and fork PRs get no `SONAR_TOKEN`, so their analysis is skipped with a notice (a Dependabot secret of that name would enable it). Tests run in the `coverage` job without the token; besides the `token` job's presence check, only the `scan` step gets it, in a job that runs no project code. Binary images and the D1 migrations (SQLite, claimed by the Oracle PL/SQL analyzer, which then warned on every run) are excluded from the analysis. Coverage: `pytest --cov` (`[tool.coverage.run]` in `pyproject.toml`) and `npm run test:coverage` (`test.coverage` in `vite.config.ts`; the lcov reporter's `projectRoot` is the repo root, so the scanner resolves the paths); `@vitest/coverage-v8` needs vitest's exact version (Dependabot group `vitest`). The built-in "Sonar way" gate fails a PR under 80 % coverage on new code (from 20 new lines up), so code without unit tests by design is in `sonar.coverage.exclusions` — keep that list in step with what the tests reach. `sonar.projectVersion` comes from `webapp/package.json`: on `main`, "new code" (previous version) starts over at each version bump. `sonar.python.version` stays 3.14 until SonarQube Cloud's analyzer supports 3.15 (it warns "No explicit support for version 3.15"). The free plan keeps only `main` and PRs: a manual run on another branch uploads a branch analysis nobody can open ("not allowed to access data from non main branches"). Mark a false positive on the issue itself. Two of its suggested fixes are wrong here: S2871 wants `localeCompare` in `.sort()`, but chunk names, migration files and `unblocked.json` keep code-unit order (= Python's `sorted()`) — pass `compareCodeUnits` (`worker/text.ts`); S8906 wants `select_one('div.a.b')` for bs4's `class_=[a, b]`, which means *either* class — write a selector list `div.a, div.b`. Trim trailing characters with `trimEnd()` (`worker/text.ts`), not `/x+$/` (S8786: quadratic backtracking on a long run). Known false positive: css:S8776 on Tailwind v4's `@utility … { &::-webkit-scrollbar … }` (the `&` is required for variants).
42.**miniflare (wrangler's local runtime) pins `undici` exactly, so Dependabot can't fix an undici alert** until a wrangler release moves the pin. The stopgap is `overrides.undici` in `webapp/package.json` (4.4.3–4.5.0 carried `^7.30.1` over wrangler 4.152's 7.29.1; dropped with wrangler 4.156, whose miniflare pins 7.30.1). Only miniflare uses undici; nothing of it reaches the site, the Worker or the apps. Remove such an override once `npm ls undici` without it shows the fixed version, and before miniflare moves to a new undici major (the override would hold it back).
43.**The Workers rate-limit binding counts per machine, not per data centre.** Measured on production right after the 4.5.0 deploy (CDG): 1,000 requests in 53 s, each `curl` on a new connection, against `RL_SITE` 120/60 s → **no 429 at all**; 200 requests on **one** keep-alive connection → 93 × 200, then 429s. A data centre has many machines, each counts locally and syncs late, so a client that keeps one connection (browsers over HTTP/2, scripts with keep-alive) is held to the limit, while one that opens a new connection per request is spread across machines and barely counted. The zone's WAF rule counts across the data centre: it is the limit that holds against floods. Test the Worker limits over one connection (`curl URL URL …` in one invocation, or `--next`), never with `xargs curl`; under `wrangler dev` (miniflare: one process) every request counts. The WAF rule (300 / 10 s, set 2026-10-27) needs > 30 requests a second, which `xargs curl` doesn't reach from a home line: use the runbook's Node `fetch` one-liner (800 requests in 4.9 s → 111 × 200, 201 × Worker 429, 488 × WAF 1015).
44.**Tailwind v4's `outline-hidden` adds a visible 2 px outline in forced-colours mode.** On a focus variant that is the point (inputs keep a system-coloured focus ring in Windows contrast themes); used unconditionally on a container (`<main tabIndex={-1}>`, the games list, popovers) it drew a permanent frame there. Containers use `outline-none`, fields `focus-visible:outline-hidden`.
45.**Vitest stubs CSS imports — `./index.css?raw` is an empty string in tests.** A test that reads a stylesheet lives in `webapp/scripts/*.test.mjs` and uses `node:fs` (`check-contrast.test.mjs`; `src/` has no Node types).
46.**Radix FocusScope gives focus back to the trigger in a `setTimeout` after unmount.** A link inside a menu or sheet that navigates would have focus pulled back to the menu button, away from the new page's h1: `SheetContent` / `PopoverContent` call `e.preventDefault()` in `onCloseAutoFocus` when the path changed. A modal opened without a Radix trigger (the 18+ dialog) drops focus to `<body>` unless `onCloseAutoFocus` focuses something. Radix 1.3.1 sets no `aria-modal` (it hides the rest with `aria-hidden`).
47.**Name Recharts charts with `aria-labelledby`, not their `title` prop** (`title` also shows a native browser tooltip over the whole chart); `Treemap`'s props type has no `role`. A custom tooltip loses Recharts' live region, and the tooltip box is `visibility: hidden` while inactive, so announcements go through the card (`ChartAnnounce`).
48.**The tool permissions refuse loading third-party code into the preview page** (an axe-core `<script>` from a CDN). Check pages with the browser's accessibility tree and DOM queries instead; Lighthouse / axe DevTools are for the owner's own browser.
49.**Qodana takes one linter per Qodana Cloud project**, hence three projects (`itch-typescript` wwgZ1, `itch-python` GgGnX, `itch-rust` P2Rd7; team "My first team", public) and three secrets (`QODANA_TOKEN_TS_JS` / `_PYTHON` / `_RUST`). All three linters need an **Ultimate** licence (a trial in Nov 2026; the Rust linter is Early Access and its image carries its own evaluation licence, to 2027-01-10): when it ends the scans fail on the licence — renew, or delete `qodana.yml` and the three `qodana.yaml`. What the first runs cost: (a) **native `qodana-python` finds no interpreter by itself** (`SDKs.json` empty), and then calls every `X | None` an invalid type hint and a dataclass a class without `__init__` — the job builds `.venv` and passes `QODANA_PYTHON_PATH`; (b) **the `qodana-rust` image has no C linker and none of Tauri's system libraries, and its container runs as the runner's user**, who can't write the image's `CARGO_HOME` or `apt-get install` (`cargo metadata` / `cargo check` fail → "Cargo project loading" sanity problem, analysis degraded, `run` unresolved) — the job passes `-u root -e CARGO_HOME=/data/cache/cargo`, `webapp/src-tauri/qodana.yaml` installs the packages in `bootstrap`, and a stand-in `webapp/dist/index.html` lets `tauri::generate_context!()` expand; (c) `--project-dir <subdir> --repository-root .` is how a subdirectory project keeps its git data; (d) the default cache keys are the same for every job of a run — each job sets its own. `gh run view --log` returns nothing until the whole run has finished; the report (SARIF + IDE logs) is the `qodana-report-*` artifact, a zip inside the artifact. Inspections switched off on purpose are listed with their reason in `webapp/qodana.yaml` (throw-to-own-catch in Worker handlers, kept regex escapes, non-ASCII keys); deliberate uses of deprecated DOM APIs carry `// noinspection JSDeprecatedSymbols`. Recharts' `<Cell>` is deprecated (gone in 4.0): a pie slice's colour is the `fill` of its data entry (`paletteFills` in `components/charts/palette.ts`).
## Safe-edit rules
- Don't write `data_game/` from new code paths directly — go through a patch + `apply_patch.py` (or the Worker's `repo.ts`), so concurrent writers never clobber each other and `validate.py` gates every commit.
- Never commit secrets (GitHub App key, admin emails, Turnstile secret, tokens). Data workflows push with the job's `GITHUB_TOKEN`; the Worker writes as the GitHub App.
- When adding an npm dep, also add it to `webapp/src/lib/about.ts` so the About page lists it. A Python dep goes into `requirements*.in`, then recompile the locks (gotcha 40).
## Current state (Nov 2026)
**Maintenance mode since v4.6.1 (2026-11-11) — the owner's decision.** The project is stable and feature-complete. Work is limited to security fixes (CVEs), runtime / dependency updates (the weekly sweep) and repairs when the site or the data pipeline breaks; **no new features, redesigns or refactors**. Issues and PRs are accepted for the data only (add, fix, remove a game — README → Project status, CONTRIBUTING); accessibility barriers and security reports keep their channels (kept because ACCESSIBILITY.md §7 and SECURITY.md promise them). Feature requests and code PRs are closed without review. Don't propose features in this repo.
**v4.6.2** (2026-11-16, PR #195): dependency-only release — the 2026-11-16 sweep below. Released because wry 0.57.2 fixes Android crashes and a memory leak, macOS panics and a Windows focus issue, which reach the apps only through a release (web-only updates redeploy on merge and need none). The owner wants a deps-only release's notes short: one "Update deps:" list (changelog + GitHub release). README count 6,000+ (6,069 games that day). No policy change (`LEGAL_VERSION` unchanged).
**v4.6.1** (2026-11-11): maintenance mode + Qodana. Docs (EN + VI): "Project status" in the READMEs, CONTRIBUTING rewritten around the data-only scope, SECURITY note, runbook §2 step 5 (Qodana) and §4. Templates: `bug_report.yml` is now "Report a problem"; `feature_request.yml`, `feedback.yml`, `general_question.yml` and the PR templates `bug_fix.md`, `new_features.md`, `documentation.md` are deleted; the issue chooser links Discussions. README badges (status, Python CI, SonarQube quality gate + coverage, Qodana, WCAG target) and the game count (5,900+; 5,907 games that day). `qodana.yml` + three `qodana.yaml` (gotcha 49). Code changes are only the first Qodana findings: pie charts without `<Cell>`, `ElementRef` → `ComponentRef`, `FormEvent` → `SubmitEvent`, an awaited `res.json()`, three Python nits, the unused `serde_json` crate dropped from the Tauri shell. No policy change (`LEGAL_VERSION` unchanged).
**v4.6.0** (2026-11-09): accessibility. Root `ACCESSIBILITY.md` + VI mirror (the owner had tested the website and the Windows app with the keyboard only and Windows Narrator; this release fixed what a WCAG 2.2 AA review found; after it, the owner's VoiceOver test on a real iPhone 14 Pro in Safari, Chrome and Brave passed), the `accessibility.yml` issue form and labels `accessibility` / `feedback`, a default `.github/pull_request_template.md` (GitHub's community profile ignores `PULL_REQUEST_TEMPLATE/`). Code: focus management (route h1, Back to the used link, dialogs), the "/" shortcut switch, header search options / count, h2 card titles, `lang` marking, screen-reader text for counts / loading / new tabs, contrast tokens + `check-contrast.test.mjs`, forced-colours CSS, chart names / arrow-key announcements / data tables. Docs sync: dead `@freeitchgames.win` addresses in `data_game/LICENSE.md`, stale dates / VI revision notes / library versions, `check:tauri` in the check lists, the About page's removal link, `remove_game.yml` → label `delete-game`. Not done by choice: desktop zoom (`zoomHotkeysEnabled` off, `maximizable: false`, min 900×600 — a known limitation in the statement). No policy change (`LEGAL_VERSION` unchanged). Ships the two deps sweeps below.
**Deps sweeps since v4.5.0** (11-02 and 11-09 shipped in 4.6.0 — the catalog had 5,818 games on 2026-11-09 —, 11-16 in 4.6.2). Each combines the week's Dependabot PRs plus what Dependabot didn't open (its 5-PR limit, pip / actions / cargo), with the 3-day cooldown applied by hand to every ecosystem (cargo and actions have none in `dependabot.yml`):
- 2026-11-09, PR #182: Dependabot #177–#181 (TanStack Query 5.106.1, vitest 5.1.0, vite 8.3.6, @vitejs/plugin-react 6.2.1, Tailwind 4.3.4, eslint 10.14.0, knip 6.44.1, wrangler 4.158.0 + regenerated types, jose 6.2.15, globals 17.14.0), lucide-react 1.69.0, soupsieve 4.0.1 (a major whose breaking changes only touch `<template>` / `<iframe>` contents), coverage 7.17.2 / Ruff 0.17.4, setup-java 6.2.0, sonarqube-scan-action 8.4.1, `cargo update` (wasm-bindgen 0.2.130 family …).
- 2026-11-16, PR #195: Dependabot #190–#194 (TanStack Query 5.107.1, @tauri-apps/plugin-opener 2.7.3, Tailwind 4.3.5, @vitejs/plugin-react 6.3.0, knip 6.45.1, typescript-eslint 8.72.2, vite 8.3.8, wrangler 4.161.0 + regenerated types, jose 6.2.17, lucide-react 1.72.0), zustand 5.1.0 (`persist` still hydrates sync storage synchronously; `rehydrate()` now returns a `Promise`), soupsieve 4.1 / coverage 7.17.3 / Ruff 0.17.5, `cargo update` (wry 0.57.2 — it pulls `dom_query` 0.29 next to tauri-utils' 0.28 —, tauri-plugin-opener 2.7.3; brotli, bumpalo, cc, ctor, jiff, mio held at older versions by the cooldown); transitive npm bumps checked too (tapable 2.3.4 held at 2.3.3 in the lock; `npm audit signatures` all verified). Held for the next sweep: eslint 10.15.0, eslint-plugin-react-refresh 0.5.8, lucide-react 1.73.0, wrangler 4.162.0, soupsieve 4.1.1, sonarqube-scan-action 8.5.0, setup-java 6.3.0. Rust stable 1.100.0 (2026-11-12) is what the release builds now get (`toolchain: stable`).
Node 26.13.1 (LTS; the 2026-11-11 security release — http2 / TLS server fixes) with its npm 11.20.0 is current: CI and Workers Builds follow `.node-version` / `NODE_VERSION``26` by themselves; only local installs need upgrading.
`npm audit`: 9 moderate, all minimatch < 11.0.1 (GHSA-g3hv-75wg-m249) under eslint / typescript-eslint — dev-only, no fix until they accept minimatch 11. `cargo audit`: 0 vulnerabilities, 5 upstream warnings. Security settings unchanged: CodeQL default setup not configured, Dependabot security updates off; 0 open alerts, SonarQube Cloud 0 issues.
**v4.5.0** (2026-10-27): rate limits for the whole site — `worker/ratelimit.ts` + `RL_SITE` / `RL_IMG` / `RL_ADMIN`, every namespace moved to 8801–8806 / staging 8901–8906 (account-wide ids; 1001 / 1003 were shared with other Workers), the 429 page, admin wording, `docs/operations.md` §1 step 15 (the WAF rule: `not cf.client.bot`, not `/assets/` or `/data/pack/`, 300 requests / 10 s, block 10 s — set by the owner in the dashboard). No policy change (`LEGAL_VERSION` unchanged; SECURITY.md EN + VI describe the limits).
**v4.4.3** (2026-10-26): dependency and security updates only — the week's npm updates (Dependabot #159–#163 in one PR, plus lucide-react / Zustand; `knip` kept at 6.42.1 by the 3-day cooldown), wrangler 4.152 with regenerated `worker-configuration.d.ts` (a wrangler bump fails `cf:types -- --check` until it is regenerated — why Dependabot's build-tooling PR failed), `overrides.undici` (gotcha 42), zod 4.6.7, `cargo update` (tauri 2.12.5, tokio 1.54.1; `cargo audit`: 0 vulnerabilities, 5 upstream warnings — glib, zbus family, proc-macro-error), certifi / coverage / Ruff via pip-tools on 3.14, `actions/setup-python` 7.1.0. Repository security state that day: CodeQL default setup **not configured** (last analyses May 2026, 0 open alerts), Dependabot **security updates disabled** in Settings (version updates run), secret scanning + push protection on, SonarQube Cloud gate OK with 0 issues.
**SonarQube Cloud CI** (2026-10-22, shipped in 4.4.3's notes): CI-based analysis with test coverage replaced Automatic Analysis — `sonarcloud.yml`, `sonar-project.properties` (tests marked as tests, coverage exclusions, `.sonarcloud.properties` removed), `pytest-cov` + `@vitest/coverage-v8` (gotcha 41).
**Toolchain** (2026-10-22, #149 + #154, shipped in 4.4.2): TypeScript 7.0.2 (`@typescript/native`; `typescript` = the 6.0 API alias, gotcha 6), Node 26 (`webapp/.node-version`, `engines >=26`, `@types/node` 26, Workers Builds `NODE_VERSION` raised to 26 by the owner in the dashboard — `docs/operations.md` §1 step 1), Python 3.15 (`.github/python-version` — gotcha 39, ruff `py315`, `urllib3` declared since `scraper.py` imports it). No source change was needed: TS 7 reports 0 errors, the suites pass on Node 26.12 and Python 3.15.1.
**v4.4.2** (2026-10-22): SonarQube Cloud cleanup — the scan's 57 issues: 45 fixed in code, the 11 on the saved itch.io test pages excluded by `.sonarcloud.properties`, css:S8776 (Tailwind `@utility`) left for the owner to mark a false positive (gotcha 41). Worker paths and the gate cookie's padding are trimmed by `trimEnd()` (a `/\/+$/` on the public 404 path was quadratic), the feed / collection parsers have no backtracking regexes left, `compareCodeUnits` makes the code-unit sorts explicit, the NSFW notices are one selector list (each tested). Supply chain: hash-locked Python deps + wheels only in every workflow (gotcha 40), `npm ci --ignore-scripts` in CI and the release builds, `npm run cf:check` instead of `npx wrangler`. `scripts/i18n-edit.mjs` reads its operations from stdin (`node scripts/i18n-edit.mjs < ops.json`). Ships the toolchain upgrade and Dependabot #141–#148, #150, #152, #153.
**v4.4.1** (2026-10-16): the browser extension and the Telegram bot are retired — both repos (`poli0981/itch-f2p-extension`, `poli0981/telegram-scraper-bot`) were already public archives; an Announcements discussion says so. Removed: `POST /api/ingest` (`ingest.ts`, `requireService`, `RL_INGEST`, `ACCESS_AUD_INGEST`, the idempotency store — it never received a game: 0 `ext` rows in production D1), the admin's "Browser extension" auto-approve source and "Extension" label, the About page's Telegram numeric-ID note. The policies (Privacy, ToS, EULA + installer RTF, Disclaimer, Security; EN + VI) only lost the extension / ingest wording: "Last updated" 2026-10-16, `LEGAL_VERSION` deliberately unchanged (nothing new to accept, ToS §14). Unused repo secrets `GH_TOKEN`, `TELEGRAM_BOT_TOKEN`, `DISCUSSION_*` deleted. Ships Dependabot #131 (vite 8.3.4), #135 (tauri crates), #136 (serde_json), #137 (ruff).
**v4.4.0** (2026-10-13, PR #133): admin automation. Add page: any text / file / itch.io collection → **Check** (dry run) → batches of 200 → per-game ingest tracking (`/api/admin/track`, from the new `scripts/state/ingest_outcomes.json`). The cron runs the maintainer's automatic rules in one `[auto]` commit: auto-approve (on by default, `rss` + `form`, unflagged, after 24 h, only items found after the `since` baseline, ≤ 100 a run) and **followed collections** (≤ 30 pages a run; never-seen unflagged free games queued directly, removed or flagged ones to review). Bulk remove / edit ≤ 100 in one commit (preset reasons translated on the Removed page), New games, Activity, Settings; queue batches of 200. D1 migration `0002_automation.sql` applied to production before the merge. Policies rewritten for approval by rules (ToS §5, Privacy §2.3/§2.4, Disclaimer §4, EN + VI; `LEGAL_VERSION` 2026-10-13). Web: the theme button shows the theme in use (a v4 regression), a pre-paint theme script (no dark flash; hash in three CSPs), Charts tabs kept mounted (switching back reuses every chart, no replayed animation), 300 ms entrances, scrollbar gutter. Also ships #130 (2026-10-11, the Charts page on phones: one-row tab bar, 12 px legends / 11 px ticks, horizontal Languages / Avg session bars, all 15 Genre labels, data-order pie legends, translated removal reasons, locale axis numbers).
**v4.3.0** (2026-10-10, PR #117; released the same day): itch.io's newer info rows in the catalog — `ai_disclosure` / `ai_content` (generative-AI disclosure) and `accessibility` — on the game page, as `/games` filters (`ai`, `access`) and as charts (Overview: "Generative AI"; Discovery: "Accessibility Features", "What AI Was Used For"); `description` = the creator's tagline. The whole catalog was re-scraped the same day with `force_update.yml` (6 × 600 + 10, ≈14.5 games/min; an itch.io outage ~05:20–06:50Z only cost retries): 3,236 of 3,251 games carry the new fields — No AI 53 %, AI Assisted 11 %, not disclosed 36 %; accessibility on 14 % (Subtitles 257, One button 119); the other 15 are 14 dead-page strikes awaiting confirmation and one password-protected page (`everium.itch.io/underthethorns`; it failed every check until #129 taught the refresh to strike such pages). Fixed on the way, same day: #118 (`force_update.yml` had never worked in v4 — it now dispatches `refresh.yml`, whose scan reads the latest main so queued batches rotate), #119 (`tauri-plugin-opener` 2.7: every first v4.3.0 release build had failed; the tag was moved before publishing), #120 (the 5 open Dependabot alerts; `check:tauri` CI guard; weekly cargo Dependabot), then Dependabot #122–#127.
**v4.2.0** (2026-10-03, PR #103): catalog packs + lazy descriptions (first visit ≈ 264 KB instead of ≈ 520 KB), compressed IndexedDB cache, `/data/*.json` only for apps 4.0–4.1.1 (410 + repository links for everyone else), `/img` cache fixes, themed scrollbars + "Hide scrollbars", policies (`LEGAL_VERSION` 2026-10-03: data reuse goes through the repository). Checked on the live site the same day: TLS 1.2/1.3 only, HSTS preload header (domain not on the preload list), Cloudflare compression already on (zstd/br), Smart Tiered Cache on but irrelevant here (`docs/operations.md` §1 step 12).
**v4.1.1** (2026-09-29): contact addresses moved to `@poli0981.dev` (Google Workspace), About page links poli0981.dev + /links/, `LEGAL_VERSION` 2026-09-29.
**v4.1.0** (2026-09-24): the Turnstile verification gate for the web app, readable chart tooltips, the changelog split into `changelog/`, a docs refresh, updated Privacy/ToS/EULA (`LEGAL_VERSION` 2026-09-24). The gate ships switched on in `wrangler.jsonc` but stays inert until `GATE_BOT_TOKEN`, the Transform Rule and `GATE_SECRET` are in place (`docs/operations.md` §1 step 14) — `curl -s https://freeitchgames.win/api/verify` says `"enabled"`.
**v4.0.0** (2026-09-18) moved the site to the Cloudflare Worker at https://freeitchgames.win (PRs #81, #82, #88). The whole chain is live: Access for `/admin`, the GitHub App (verified commits to `scripts/temp_link.json` → `update.yml`), Turnstile, `ADMIN_EMAILS`; D1 `freeitchgames`, R2 `freeitchgames-thumbs`, Image Transformations (source `img.itch.zone`); Web Analytics is injected by the zone. **Still open (owner):** the legal-text review items; add the new GPG key's public half on GitHub (until then new signatures show Unverified) and remove the revoked `03F965C2E2DB5C6B` there; delete the Zero Trust Access app "Ingest" and its service token (unused since 4.4.1).
We as contributors, maintainers (just me, the unemployed noob dev), and visitors pledge to make participation in this repo a harassment-free experience for everyone — regardless of level of experience, gender, gender identity, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or how many Steam sales you've survived.
Last updated: 2026-09-29
Basically: be cool. I'm introvert max level with zero social skills, so let's keep things positive.
Applies from: the release of version 4.0.0.
This is a small hobby repo about free itch.io games, run by one unemployed noob dev, poli0981 (SkullMute), called "the Maintainer" below. Basically: be cool. The Maintainer is an introvert at max level with zero social skills, so let's keep things positive.
The rules below are adapted from the [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) (see [§7](#7-attribution)).
## 1. Our pledge
We as members, contributors and the Maintainer pledge to make participation in this community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation — or how many Steam sales you've survived.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive and healthy community.
## 2. Our standards
## Our Standards
Examples of behavior that contributes to a positive environment:
- Using welcoming and inclusive language
-Being respectful of differing viewpoints and experiences
-Gracefully accepting constructive criticism
-Focusing on what's best for the list (more free games!)
-Showing empathy towards other community members (if any show up :D)
-Showing empathy and kindness toward other people
-Being respectful of differing opinions, viewpoints and experiences
-Giving and gracefully accepting constructive feedback
-Accepting responsibility, apologizing to those affected by our mistakes, and learning from the experience
- Focusing on what is best not just for us as individuals but for the whole community — and the list (more free games!)
Examples of unacceptable behavior:
- Harassment, trolling, or insults
- Sexualized language or imagery (keep NSFW in the games, not here)
- Personal or political attacks
- Doxxing or sharing private info
- Spamming sketchy links or malware
- Any other conduct that would make an introvert like me close the tab immediately
## Enforcement
I'm the only maintainer (with Grok as backup), so I'll remove, edit, or reject comments, commits, code, issues, or PRs that violate this. Repeat offenders get blocked. No warnings required — life's too short.
- Sexualized language or imagery, and sexual attention or advances of any kind. Discussing whether a game should carry the `nsfw` flag is fine; sexual content aimed at people is not.
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email address, without their explicit permission (doxxing)
- Spam, or links to malware, phishing or other harmful content
- Other conduct that could reasonably be considered inappropriate in a professional setting — or that would make an introvert close the tab immediately
Instances of abusive behavior can be reported by opening an issue (I'll see it... eventually). All reports will be reviewed and kept confidential.
## 3. Enforcement responsibilities
## Scope
This applies everywhere in the repo: issues, PRs, comments, code.
The Maintainer is responsible for clarifying and enforcing these standards and will take appropriate and fair corrective action in response to any behavior they consider inappropriate, threatening, offensive or harmful.
## Final Vibes
This is just a small hobby repo about free itch.io games. Let's keep it fun, chill, and drama-free. If you're here to add games or fix my mediocre code — you're already a legend.
The Maintainer has the right and responsibility to remove, edit or reject comments, commits, code, issues, pull requests, discussions, game suggestions and other contributions that are not aligned with this Code of Conduct, and will explain moderation decisions when appropriate.
Adapted from the Contributor Covenant, because even noob devs copy good stuff.
## 4. Scope
Thanks for reading (or pretending to). 🚀
This Code of Conduct applies in all project spaces: the GitHub repository (issues, pull requests, discussions, comments, commit messages and code), anything submitted to the project (for example notes sent with the Suggest form), and the Discord community linked from the [About page](https://freeitchgames.win/about). It also applies when someone is officially representing the project in public spaces.
## 5. Reporting
If you experience or witness abusive, harassing or otherwise unacceptable behavior, report it **privately** to the Maintainer:
- email **legal@poli0981.dev**, or
- send the Maintainer a direct message through one of the contact channels listed on the [About page](https://freeitchgames.win/about).
Please don't report conduct problems in a public issue. Every report will be reviewed and handled promptly and fairly, and the Maintainer will respect the privacy and security of the person who reports.
Because the project has only one maintainer, if your report is about the Maintainer, you can also use GitHub's own "Report abuse" feature or Discord's reporting tools.
## 6. Enforcement guidelines
The Maintainer follows these community impact guidelines when deciding what to do about a breach of this Code of Conduct:
1.**Correction**
- *Community impact*: inappropriate language or other behavior that is unprofessional or unwelcome.
- *Consequence*: a private, written warning that explains what the problem was and why the behavior was inappropriate. A public apology may be requested.
2.**Warning**
- *Community impact*: a violation through a single incident or a series of actions.
- *Consequence*: a warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with the Maintainer, for a set period of time — both in project spaces and in external channels such as social media. Breaking these terms may lead to a temporary or permanent ban.
3.**Temporary ban**
- *Community impact*: a serious violation, including sustained inappropriate behavior.
- *Consequence*: a temporary ban from any interaction or public communication with the community for a set period of time. No public or private interaction with the people involved, including unsolicited interaction with the Maintainer, is allowed during this period. Breaking these terms may lead to a permanent ban.
4.**Permanent ban**
- *Community impact*: a pattern of violating community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of groups of people.
- *Consequence*: a permanent ban from any public interaction within the community.
The ladder is a guide, not a promise to go step by step: for spam, malware links or serious harassment, the Maintainer may go straight to a ban (block).
## 7. Attribution
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct/. The community impact guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
Changes from the original: it is adapted for a project with a single maintainer, adds project-specific examples, and names this project's scope and private reporting channels. The Contributor Covenant is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); this adapted version is also available under CC BY 4.0, like the rest of the project's documentation.
## 8. Final vibes
This is just a small hobby repo about free itch.io games. Let's keep it fun, chill and drama-free. If you're here to add games or fix mediocre code — you're already a legend.
Thanks for even thinking about contributing to this random repo! I'm just an unemployed, introvert Vietnamese dev with mediocre skills and Grok as my only non-judgmental buddy. This list survives on community help — because I'm too lazy to hunt/fix everything alone :D Any contribution (even one game) makes you a legend.
Thanks for even thinking about contributing to this random repo! I'm just an unemployed, introvert Vietnamese dev with mediocre skills and two non-judgmental AI buddies: **Grok (xAI)** for the late-night brainstorming and **Claude Code (Anthropic)** for the heavier code/docs work. This list survives on community help, because I'm too lazy to hunt/fix everything alone :D Any contribution (even one game) makes you a legend.
## How to Contribute (Use Templates — I'm Lazy ;D)
## Project Status: Stable, Maintenance Only
Please use the issue/PR templates — they make my life easier and reduce "wtf" moments.
Since version 4.6.1 (2026-11-11) the project is **stable and in maintenance mode**. It is feature-complete: the website, the apps and the data pipeline keep running, and the catalog keeps updating itself.
### 1. Add New Games (Most Welcome!)
-Open issue → Choose **[Add Games]** template.
-Max 15 games per issue (dropdown + one link per line).
- Optional: why it's good or notes for table.
- Daily Action will auto-scrape and add. Easy.
- **Still done by the Maintainer**: security fixes (CVEs and reports made through [SECURITY.md](SECURITY.md)), runtime and dependency updates, and repairs when something stops the site or the daily data updates from working.
-**Not done any more**: new features, redesigns, refactors.
-**Issues and pull requests are accepted for the data only**: adding games (section 1), fixing a game's data or removing a game (sections 2 and 3). Accessibility barriers (section 3) and security reports keep their own channels. Anything else is closed without review; no hard feelings.
### 2. Remove Games
- Open issue → Choose **[Remove Games]** template.
- Max 10 games (because lazy :v).
- Provide names/links + reasons (checkboxes like boring, demo, malware, dev request, etc.).
- I'll remove manually (or script if I feel motivated).
## How to Contribute (Use the Right Door, I'm Lazy ;D)
### 3. Report Bugs
- Open issue → **[Bug Report]** template.
- Checkboxes for common bugs (dead links, wrong flags, table broken, etc.).
Games go through the website; data fixes and removals go through the GitHub issue templates or email. They make my life easier and reduce "wtf" moments.
### 1. Suggest New Games (Most Welcome!)
- Go to **<https://freeitchgames.win/suggest>** and paste an itch.io game link. One link per submission.
- Optional: a short note (why it's good, content warnings…), up to 500 characters. Notes are deleted after 180 days. Please don't put personal data in it.
- A Cloudflare Turnstile check and a rate limit keep bots out; if you get blocked, wait a bit and try again.
- Only **free** itch.io games. Paid games are dropped automatically when the game page is scraped.
- The game must be playable or downloadable **on its itch.io page itself** (a browser build or an uploaded file). A page that only points to a launcher or a download on another site doesn't qualify, even when that is free: the [Disclaimer](docs/DISCLAIMER.md) tells visitors that any download happens on itch.io.
- Nothing goes live instantly: every suggestion lands in a **review queue**, where the Maintainer approves or rejects it, by hand or through automatic rules (a suggestion without a warning flag that nobody rejected within about a day may be approved automatically). Approved links are then scraped by the data pipeline and show up on the site after the next deploy.
Got a whole list? The **[Add Games (bulk list)]** issue template takes up to 15 links at once, and a PR that adds itch.io URLs to `scripts/temp_link.json` works too (use the [Add Games] PR template). Both go through the same review: the Maintainer checks every link before it is queued, and merging such a PR is the approval. Please don't edit `data_game/` by hand: the pipeline owns those files (see [section 7](#7-pull-requests)).
#### 1b. Other ways games get in
- The site reads itch.io's public RSS feeds of new and popular free games every 4 hours (one feed per run) and queues what it finds.
- The site also reads the public itch.io collections the Maintainer follows and queues their new free games directly (one removed before, or with a warning flag, goes to the review queue instead).
The RSS feeds land in the same review queue as the Suggest page. (The Maintainer's browser extension and the old Telegram bot are retired; their repositories, [itch-f2p-extension](https://github.com/poli0981/itch-f2p-extension) and [telegram-scraper-bot](https://github.com/poli0981/telegram-scraper-bot), are archived.)
### 2. Remove Games or Fix Their Data
Game creators especially: if you want your game off the list, or its data corrected, that's always fine.
- Email **takedown@poli0981.dev**, or open the **["Remove a game"](https://github.com/poli0981/free-games-itchio-list/issues/new?template=remove_game.yml)** issue template (it also has a section for copyright claims).
- Include the game URL, who you are (the creator / rights holder, or someone authorized by them) and the reason.
- The Maintainer removes the record from the catalog (logged with a reason on the public [removed-games page](https://freeitchgames.win/removed)) and deletes the resized cover copies the site stores; cached copies expire on their own. Target: within 7 days, urgent legal requests sooner.
- Heads-up: this is a public git repo, so past versions stay in its history. Rewriting public history is only done in exceptional cases of legal necessity.
- Wrong `safe_virus` / `nsfw` / notes, or other data errors that aren't a removal? Use the **[Report a problem]** issue template (section 3).
Details live in the [Terms of Use](docs/ToS.md) and the [Disclaimer](docs/DISCLAIMER.md).
### 3. Report a Problem (Wrong Data, Something Broke)
- Open an issue → **[Report a problem]** template ([direct link](https://github.com/poli0981/free-games-itchio-list/issues/new?template=bug_report.yml)).
- It is for **data errors** (dead link, wrong name, genre, tags, cover, `nsfw` or `safe_virus` flag…) and for **things that broke** (a page or an app that stopped working, the catalog no longer updating). It is not for ideas: see section 4.
- Details + screenshots + urgency level.
-If complex — see "Discuss More" below.
-**Security problems are not for the public tracker.** Report them privately: see [SECURITY.md](SECURITY.md).
- **Accessibility barriers** (keyboard, screen reader, zoom, contrast, motion…): use the **[Accessibility barrier]** template ([direct link](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml)), or email contact@poli0981.dev if you'd rather not use GitHub. What happens next is in [ACCESSIBILITY.md](ACCESSIBILITY.md#7-reporting-an-accessibility-barrier).
### 4. Suggest Features or Improvements
- Open issue → **[Feature Request / Improvement]** template.
- Choose type (new feature or code fix), name, reason, priority (from "nice to have" to "repo dying").
- Optional: pseudo-code/snippet (no malware pls, I'll check with my average skills :D).
- Roast or praise — my self-loathing can handle it.
- The project is in maintenance mode: **feature requests, improvement ideas and code changes are no longer accepted**. Such issues and pull requests are closed without review.
-The code is MIT-licensed: you're welcome to fork it and build your own thing ([README → License](README.md#license)).
- Use **[GitHub Discussions](https://github.com/poli0981/free-games-itchio-list/discussions)**, the Discord servers or email (see "Discuss More" below). Roast or praise, my self-loathing can handle it.
-They are read, but they don't turn into new features (section 4).
### 8. Webapp Changes (React + TS)
### 6. Dependencies and Security Fixes
The browse/edit UI lives in [`webapp/`](webapp/). Same MIT license, same PR template.
- Dependency updates are handled by Dependabot and the Maintainer's weekly sweep: please don't send version-bump PRs.
- Found a vulnerability? Report it privately ([SECURITY.md](SECURITY.md)); the Maintainer makes the fix.
### 7. Pull Requests
- **Accepted**: a PR that adds itch.io URLs to `scripts/temp_link.json` (use the [Add Games] PR template). Merging it is the Maintainer's approval.
- **Not accepted**: everything else (code, UI, docs, refactors). Fixing or removing a game's data goes through an issue or email (sections 2 and 3), because the pipeline owns `data_game/`.
- The rules below still apply to every PR, the Maintainer's own included.
**PR rules** (the non-negotiable part):
- **CI must pass.** Python CI (ruff check + format, vulture, pytest, `validate.py`) and Webapp CI (Tauri crate/npm version check, type generation check, lint, knip, tests, build, `wrangler deploy --dry-run`) both run on PRs. Red CI = no merge. SonarQube Cloud also analyses each PR (with test coverage) and reports its quality gate as the "SonarCloud Code Analysis" check, and Qodana (JetBrains) analyses the TypeScript / JavaScript, Python and Rust code. Both skip PRs from forks, which get no repository secrets.
- **PRs are merged with squash** (one PR becomes one commit on `main`) **or a merge commit, never by fast-forward**, so make the PR title a good commit message (the repo uses the `type(scope): summary` style, e.g. `fix(web): …`).
- **Licensing is inbound = outbound.** By opening a PR you agree that your contribution is licensed under the same license as the part it changes: **MIT** for code, **CC BY 4.0** for catalog data and documentation (see [README → License](README.md#license)). Only submit work you have the right to submit.
- **Never commit secrets**: no tokens, API keys, `.dev.vars` / `.env` files, private keys (such as the GitHub App key) or signing keystores. If you pushed one by accident, report it privately (security@poli0981.dev) and rotate it; deleting the commit is not enough.
- **Don't edit `data_game/` by hand.** Data changes go through the pipeline (a patch + `apply_patch.py`, which runs `validate.py`), so concurrent writers never clobber each other.
- Don't commit build output or generated files: `webapp/dist/`, `webapp/.wrangler/`, `webapp/src-tauri/target/`, `webapp/src-tauri/gen/`. (`webapp/src-tauri/Cargo.lock`**is** committed; keep it in sync when you change `Cargo.toml`.)
- Adding an npm dependency? Also add it to the `THIRD_PARTY` list in `webapp/src/lib/about.ts` so the About page credits it.
- New external link in the app? Use `<ExtLink href="…">` from `webapp/src/components/ext-link.tsx`, not a plain `<a href="…" target="_blank">`: plain anchors work on the web but silently break in the Tauri apps (and ExtLink tells screen readers the link opens a new tab).
- **Accessibility**: UI changes keep working with the keyboard alone and with screen readers, and keep the contrast ratios (`npm test` checks the colours). The checklist is in [ACCESSIBILITY.md → For contributors](ACCESSIBILITY.md#8-for-contributors) and in the pull request template.
### 8. Dev Setup (Summary)
For forks, and for the Maintainer's own maintenance work.
Full instructions (Worker, local D1, secrets, Tauri, Android) are in **[`docs/dev_env.md`](docs/dev_env.md)**; the Tauri/Android build notes are in [`webapp/TAURI.md`](webapp/TAURI.md). The short version:
**Python pipeline** (Python 3.15, see `.github/python-version`):
**Local dev** (Node 22+, npm):
```sh
cd webapp
npm install
npm run dev # http://localhost:5173
npm run build # writes to docs/app/ (verify before pushing)
npm run lint # eslint
python -m venv .venv
# activate it, then:
pip install -r requirements-dev.txt
pytest # no network needed
ruff check scripts tests webapp/scripts
ruff format scripts tests
python scripts/validate.py # checks every data file
```
**Tauri desktop dev** (also needs Rust via https://rustup.rs and platform deps — see [`webapp/TAURI.md`](webapp/TAURI.md)):
To try a real scrape locally: add a URL to `scripts/temp_link.json`, then run
`python scripts/update_info.py --out patch.json` and `python scripts/apply_patch.py patch.json`
(don't commit the result; see the PR rules above).
**Webapp + Worker** (Node.js 26+, CI uses the version in `webapp/.node-version`):
```sh
cd webapp
npm ci
npm run dev # Vite on http://localhost:5173
npm run build # writes to webapp/dist/ (the Worker serves it as its assets)
npx wrangler dev # second terminal: Worker on :8787; Vite proxies /api and /img to it
npm test# vitest
npm run lint
npm run knip
```
**Tauri apps** (also needs Rust via <https://rustup.rs> and platform deps):
```sh
cd webapp
npm run tauri:dev # native window pointing at the Vite dev server
npm run tauri:build # produce installers in src-tauri/target/release/bundle/
npm run tauri:build # installers in src-tauri/target/release/bundle/
```
**House rules**:
- Don't commit `webapp/dist/` or `docs/app/` — CI builds them on push to `main`.
- Don't commit a real PAT into the repo (that's also a webapp Settings concern, not a CI concern).
- Add new third-party deps? Update `webapp/src/lib/about.ts` so the About page lists them.
## Tips for Smooth Contributing
- **Test locally**: Clone, add to `temp_link.json`, run `python update_info.py` → `generate_md.py`, check `/lists/`.
- **Keep clean**: Only free itch.io games, no paid/demo/malware/duplicates.
- **Agreement**: All templates have a required checkbox — off-topic/spam/violate policy = I ignore/close without drama :D
## Discuss More? (If Templates Not Enough)
Issues/PRs are best for tracking, but if you wanna describe bugs/features in depth, chit-chat, or share noob stories:
-Check my GitHub profile for links to X (Twitter) or Facebook (ghost towns, but DM open if you find me :v).
-Or join Telegram/Discord groups/servers if I ever make one (unlikely, introvert god-mode).
-Grok can't join, but ping me here — I'll try not to ghost.
- **Test locally**: run the checks from section 8 before pushing; CI runs the same ones.
- **Keep it clean**: only free itch.io games, no paid/demo/malware/duplicates.
-**Be patient**: I'm introvert + lazy, replies might be slow.
-**Agreement**: all issue templates have a required checkbox. Off-topic/spam/policy violations, and anything outside the maintenance scope above, get ignored/closed without drama :D
-**Be cool**: everything here falls under the [Code of Conduct](CODE_OF_CONDUCT.md).
## Discuss More? (If Templates Aren't Enough)
Issues are best for tracking data problems, but if you wanna chit-chat, ask something, or share noob stories, there are [GitHub Discussions](https://github.com/poli0981/free-games-itchio-list/discussions) and actual servers now (introvert god-mode breached):
This file explains who owns what in `free-games-itchio-list` and the website <https://freeitchgames.win>,
and which license applies to which part.
## 1. Not affiliated with itch.io
This is an independent, unofficial hobby project by **poli0981 (SkullMute)** ("the Maintainer"). It is
**not affiliated with, endorsed by, or sponsored by itch.io or Leaf Corcoran / itch corp**. The name
"itch.io" is used only to say where the listed games are published.
The games are hosted on itch.io and belong to their creators, who set their own licenses and terms.
The project does not host or distribute game files. Every game link goes to the game's itch.io page.
## 2. Trademarks
- "itch.io" and the itch.io logo are trademarks of their owner.
- Game names, logos and other marks belong to their respective creators or owners.
- Other product and company names in this repository (for example Cloudflare, GitHub, Discord, Tauri) are
trademarks of their respective owners.
They are used only to identify the thing they name. That use does not suggest any endorsement.
## 3. Creator content
The catalog copies some material from each public itch.io game page: the game's name, developer,
description text, genre, tags and other metadata, and the cover image URL. **Descriptions and cover images
remain the property of their creators.** The project does not license them to anyone
(see [`data_game/LICENSE.md`](data_game/LICENSE.md), section 3).
Creators and rights holders can ask for a game to be removed or corrected. Email
**takedown@poli0981.dev** or open the
["Remove a game" issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=remove_game.yml).
The process is described in the [Terms of Use](docs/ToS.md).
## 4. License map
| Part | What it includes | License | Text |
|---|---|---|---|
| **Code** | Everything not listed below, including `scripts/`, `webapp/`, `bash/`, `.github/workflows/` and `tests/` | MIT, `Copyright (c) 2025-2026 poli0981 (SkullMute)` | [`LICENSE`](LICENSE) |
| **Catalog data** | `data_game/`, `scripts/deleted_games.json`, and the files built from them under <https://freeitchgames.win/data> | CC BY 4.0, for the Maintainer's contribution only. Creator descriptions, cover images, game names and trademarks are **excluded** | [`data_game/LICENSE.md`](data_game/LICENSE.md), [`LICENSES/CC-BY-4.0.txt`](LICENSES/CC-BY-4.0.txt) |
| **Documentation** | `*.md` files in the repository root and in `docs/` (README, policies, guides and their Vietnamese translations) | CC BY 4.0 | [`LICENSES/CC-BY-4.0.txt`](LICENSES/CC-BY-4.0.txt) |
| **Third-party components** | Libraries, frameworks and tools the project uses | Their own licenses | [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md) and the [About page](https://freeitchgames.win/about) |
| **Browser extension** (archived) | [poli0981/itch-f2p-extension](https://github.com/poli0981/itch-f2p-extension), a separate repository, archived and no longer used | GPL-3.0 | That repository |
When you reuse the documentation, credit poli0981 (SkullMute), link to this repository and to CC BY 4.0,
and say if you changed it. For the data, use the credit line in
A curated, auto-updating catalog of free games on [itch.io](https://itch.io). Games are scraped, validated, and
organized into browsable markdown tables — updated daily via GitHub Actions.
> 🇻🇳 Tiếng Việt: see [`README.vi.md`](README.vi.md). Vietnamese translations of the policy docs live in [`docs/i18n/vi/`](docs/i18n/vi/). The English versions in this repo remain controlling for legal interpretation.
A curated, auto-updating catalog of **6,000+ free games on [itch.io](https://itch.io)**. Browse it at
**<https://freeitchgames.win>**: search, filter, sort, and jump to any game's itch.io page. The site is
read-only for everyone: no accounts, no sign-in, no comments, no ads, no payments.
## Project status
**Stable, maintenance only** (since version 4.6.1, 2026-11-11). The project is feature-complete: the
website, the apps and the data pipeline keep running, and the catalog keeps updating itself every day.
- **What still happens**: security fixes (CVEs and reports made through [SECURITY.md](SECURITY.md)),
| Update game info | Daily 03:00 UTC | Scrape new links from `temp_link.json` (+ optional `url` input from webapp), skip paid |
| Generate tables | After update/checks | Rebuild markdown tables in `/lists/` |
| Check paid games | Every 2 days 04:00 UTC | Remove games that became paid |
| Check dead links | Every 2 days 07:00 UTC | Remove 404/410 game pages |
| Log deleted games | After check workflows | Export deletion log to `deleted_games.txt` |
| Deploy webapp | On push to main | Build `webapp/` → GitHub Pages (`docs/app/`) |
| Release desktop | On `v*` tag push | Build Tauri installers (Win/macOS/Linux) → draft Release |
| Job | Schedule | Purpose |
|---|---|---|
| Ingest (`update.yml`) | On queue change + daily 01:23 UTC | Scrape approved links from `temp_link.json`, skip paid / dead / removed |
| Refresh (`refresh.yml`) | Daily 02:47 UTC | Re-check 1/7 of the catalog: dead links, now-paid or password-protected games, rating, status |
| Force update (`force_update.yml`) | Manual | Re-scrape every field (one URL or the next batch); keeps `safe_virus` / `notes` / `nsfw` |
| RSS discovery and automatic rules (Cloudflare Worker) | Every 4 hours | Poll one itch.io feed per run into the review queue; auto-approve unflagged items after the waiting time; queue new free games of followed collections |
| Python CI / Webapp CI | Pull requests (Python CI also on pushes to `main` that touch it) | Lint, tests, data validation / type-check, tests, build |
| Code analysis (`sonarcloud.yml`, `qodana.yml`) | Pull requests and pushes to `main` that change code | SonarQube Cloud (with test coverage) and Qodana (TypeScript / JavaScript, Python, Rust) |
| Deploy website | On push to `main` | Cloudflare Workers Builds (`webapp/wrangler.jsonc`) → freeitchgames.win |
| Build monitor (`deploy-status.yml`) | Hourly | Posts each failed Workers Build of `main` to Discord, once |
| Release desktop / Android | On `v*` tag push | Tauri installers (Win/macOS/Linux) and signed APK → draft Release |
All workflows include rate-limiting (random delays, batch pauses) to avoid being blocked by itch.io. Network errors are
treated as transient — games are only removed on confirmed 404/410 or confirmed paid status.
Network errors are treated as transient; a game is removed only after the same 404/410 or paid status is
seen again at least 20 hours after the first sighting. Failures, cancellations, rate limits and suspicious
mass changes are reported to the project's Discord as automated notifications.
## Data fields
Each game entry in `data_game/game_info_NNN.json`contains:
Each game in `data_game/game_info_NNN.json`has these 20 fields, plus optional `added_at` / `updated_at`
timestamps added by the pipeline and, since 4.3, the optional `ai_disclosure` / `ai_content` /
`accessibility` fields (filled in as each game is re-checked). Only `safe_virus`, `notes` and `nsfw` are maintained by the Maintainer;
everything else is scraped from the game's public itch.io page, and no re-scrape ever overwrites those three.
All fields default to `N/A` when not available on the game page.
Scraped fields default to `N/A` when not available on the game page.
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for full details.
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
- **Add games** — use the "Add New Games" issue template (max 50 links per issue).
- **Report bugs** — use the "Bug Report" template.
- **Request features** — open an issue or submit a PR.
- **Add games**: use the [Suggest page](https://freeitchgames.win/suggest).
- **Remove a game / fix its data**: email takedown@poli0981.dev or open a
["Remove a game" issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=remove_game.yml).
- **Report a problem**: wrong data, a dead link, or something broken on the site or in the apps: use the
"Report a problem" issue template.
- **Accessibility barriers**: use the ["Accessibility barrier" issue template](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml) or email
contact@poli0981.dev. See [ACCESSIBILITY.md](ACCESSIBILITY.md).
- **Features and code changes**: not accepted any more, the project is in
[maintenance mode](#project-status). Questions and feedback are welcome in
| **Catalog data**: `data_game/`, `scripts/deleted_games.json` and the derived files at <https://freeitchgames.win/data> | CC BY 4.0, for the Maintainer's contribution (see below) | [`data_game/LICENSE.md`](data_game/LICENSE.md) |
| **Documentation**: the `*.md` files in the repo root and `docs/` (this README, the policies) | CC BY 4.0 | [`LICENSES/CC-BY-4.0.txt`](LICENSES/CC-BY-4.0.txt) |
**What the data license covers:** the selection and arrangement of the collection, the three
Maintainer-written fields (`safe_virus`, `notes`, `nsfw`), the removal records, and the structure and
derived statistics.
**What it does not cover** (owned by others, not licensed by this project): game descriptions and any other
text written by game creators, cover images / thumbnails and other media, game names, logos and trademarks,
and itch.io's trademarks. Plain facts such as URLs, prices and ratings are not copyrightable anyway.
When you reuse the data, please credit it like this:
```
Free itch.io games catalog by poli0981 (SkullMute) — https://freeitchgames.win — CC BY 4.0
```
Third-party components keep their own licenses: see [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md) and the
site's About page. The archived browser extension is a separate repo under GPL-3.0. Contributions are
accepted under the same license as the part they change (inbound = outbound): MIT for code, CC BY 4.0 for
data and docs.
**Not affiliated with itch.io.** This is an independent fan project. It is not affiliated with, endorsed by,
or sponsored by itch.io, Leaf Corcoran or itch corp. "itch.io" and all game names, logos and trademarks
belong to their respective owners.
## Legal
- [Disclaimer](docs/DISCLAIMER.md)
- [Terms of Use](docs/ToS.md): covers the website and everything on it
- [Privacy Policy](docs/PrivacyPolicy.md)
- [Terms of Service](docs/ToS.md)
- [EULA](docs/EULA.md)
- [Code of Conduct](./CODE_OF_CONDUCT.md)
- [Security](./SECURITY.md)
- [Disclaimer](docs/DISCLAIMER.md)
- [EULA](docs/EULA.md): covers the desktop and Android apps only
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security Policy](SECURITY.md)
- [Accessibility statement](ACCESSIBILITY.md): what works with assistive technology, known gaps, how to report a barrier
- [NOTICE](NOTICE.md)
Licensed under [MIT](LICENSE).
Contact (the Maintainer's own mailbox on poli0981.dev):
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-11-11 (English source revision 2026-11-11). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
>
> Bản tiếng Anh tại [`README.md`](README.md) là bản chính thức. Bản dịch tiếng Việt của các tài liệu chính sách nằm trong [`docs/i18n/vi/`](docs/i18n/vi/).
Một danh mục được tuyển chọn và tự động cập nhật gồm **hơn 6,000 game miễn phí trên [itch.io](https://itch.io)**. Duyệt tại **<https://freeitchgames.win>**: tìm kiếm, lọc, sắp xếp và mở thẳng trang itch.io của bất kỳ game nào. Website chỉ để xem, với tất cả mọi người: không tài khoản, không đăng nhập, không bình luận, không quảng cáo, không thanh toán.
## Trạng thái dự án
**Ổn định, chỉ bảo trì** (từ phiên bản 4.6.1, 2026-11-11). Dự án đã đủ tính năng: website, các ứng dụng và pipeline dữ liệu vẫn chạy, danh mục vẫn tự cập nhật mỗi ngày.
- **Những gì vẫn được làm**: vá bảo mật (CVE và báo cáo gửi qua [SECURITY](docs/i18n/vi/SECURITY.md)), cập nhật runtime và thư viện phụ thuộc (Node.js, Python, Rust, gói npm / pip / cargo, GitHub Actions), và sửa khi có gì đó làm website hoặc việc cập nhật dữ liệu hằng ngày ngừng chạy.
- **Những gì không còn làm**: tính năng mới, thiết kế lại, refactor. Đề xuất tính năng và pull request về code sẽ bị đóng mà không review.
- **Issue và pull request chỉ dành cho dữ liệu**: thêm game, sửa dữ liệu của một game, gỡ game. Xem [Đóng góp](#đóng-góp).
## Mục lục
- [Trạng thái dự án](#trạng-thái-dự-án)
- [Duyệt danh mục](#duyệt-danh-mục)
- [Ứng dụng desktop và Android](#ứng-dụng-desktop-và-android)
- [Thêm game](#thêm-game)
- [Dữ liệu được cập nhật thế nào](#dữ-liệu-được-cập-nhật-thế-nào)
- [Bên trong dự án](#bên-trong-dự-án)
- [Cấu trúc dự án](#cấu-trúc-dự-án)
- [Tự động hóa](#tự-động-hóa)
- [Các trường dữ liệu](#các-trường-dữ-liệu)
- [Đóng góp](#đóng-góp)
- [Kết nối / hỗ trợ](#kết-nối--hỗ-trợ)
- [Giấy phép](#giấy-phép)
- [Pháp lý](#pháp-lý)
## Duyệt danh mục
Mọi thứ nằm trên website **<https://freeitchgames.win>**:
- **Danh sách game**: toàn bộ danh mục trong một bảng chạy nhanh (dạng danh sách gọn trên điện thoại), lọc theo thể loại, nền tảng, trạng thái, công bố của tác giả về AI tạo sinh, hỗ trợ tiếp cận và nhiều thứ khác, cùng một trang chi tiết cho từng game.
- **Biểu đồ**: danh mục được chia ra sao, và đã lớn lên thế nào theo thời gian.
- **Đã gỡ** (Removed): mọi game bị loại khỏi danh mục, kèm lý do (<https://freeitchgames.win/removed>).
- **Kiểm tra nhanh trước.** Lần đầu vào, rồi khoảng mỗi 48 giờ, trang sẽ chạy một bước kiểm tra Cloudflare Turnstile ngắn để chặn bot. Thường nó tự qua rồi mở đúng trang bạn cần. Dữ liệu trong `/data` và các ứng dụng không cần bước này.
- **Nội dung 18+ bị ẩn theo mặc định.** Game được đánh dấu `nsfw: Yes` sẽ bị ẩn (kể cả ảnh bìa) trừ khi bạn tự bật trong Settings sau khi xác nhận mình đủ 18 tuổi. Lựa chọn đó chỉ được lưu trong trình duyệt của bạn.
- **Dành cho mọi cách duyệt web.** Mọi thứ dùng được chỉ với bàn phím và với trình đọc màn hình, màu sắc đạt tỉ lệ tương phản WCAG ở cả hai giao diện, mỗi biểu đồ có bảng dữ liệu, và site làm theo thiết lập giảm chuyển động và tương phản của hệ thống. Những gì đã hỗ trợ, các hạn chế đã biết và cách báo rào cản: [Trợ năng](docs/i18n/vi/ACCESSIBILITY.md) ([EN](ACCESSIBILITY.md)).
Mọi link đều dẫn tới trang riêng của game trên itch.io. Ảnh bìa trên website là bản thu nhỏ do freeitchgames.win phục vụ, nên trình duyệt của bạn không kết nối tới itch.io cho tới khi bạn bấm vào một link.
Muốn lấy dữ liệu gốc? Đó là JSON thuần, nằm trong [`data_game/`](data_game/) (cùng [`scripts/deleted_games.json`](scripts/deleted_games.json)) của repo này: clone, tải về hoặc đọc file raw. Vui lòng dùng các file đó thay vì cào (scrape) website, vốn chỉ phục vụ định dạng thu gọn riêng của nó; xem [Giấy phép](#giấy-phép) để biết bạn được tái sử dụng chúng thế nào.
(Địa chỉ cũ `poli0981.github.io/free-games-itchio-list` giờ chỉ chuyển hướng sang website mới. Các bảng markdown theo thể loại trong `lists/` và file `deleted_games.txt` đã bị bỏ: danh mục giờ chỉ có trên web.)
## Ứng dụng desktop và Android
Cùng một app cũng được phát hành dưới dạng **ứng dụng native chỉ để xem**, build bằng Tauri 2 từ cùng mã nguồn. Tải từ [GitHub Release](https://github.com/poli0981/free-games-itchio-list/releases/latest) mới nhất:
| Nền tảng | File |
|---|---|
| Windows | Trình cài đặt `.msi` hoặc `.exe` |
| macOS | `.dmg`, `.pkg` hoặc `.app.tar.gz` (cần Safari/WebKit 16.4 trở lên) |
Các app tải dữ liệu danh mục từ <https://freeitchgames.win/data> và tải ảnh bìa trực tiếp từ CDN ảnh của itch.io (`img.itch.zone`); bấm vào một game sẽ mở itch.io trong trình duyệt của bạn. Không có telemetry. Cập nhật thủ công: khi có bản mới thì tải bản mới về. Cài app đồng nghĩa với việc chấp nhận [EULA](docs/i18n/vi/EULA.md) ([EN](docs/EULA.md)).
### Android (tải & cài đặt)
Không có trên Play Store: chỉ cần tải `.apk` về và cài tay (Android cho phép, chỉ hỏi xác nhận trước):
1. Mở [Release](https://github.com/poli0981/free-games-itchio-list/releases/latest) mới nhất và tải `FreeGamesItchio_<version>_arm64-v8a.apk`. Chỉ cài APK từ trang đó: file được ký bằng khóa của dự án.
2. Bấm vào file. Android sẽ hỏi **cho phép cài từ nguồn này** (trình duyệt / trình quản lý file). Hãy bật lên (Cài đặt → *Ứng dụng* → *Truy cập đặc biệt* → *Cài ứng dụng không xác định*).
3. Chấp nhận cảnh báo "không từ Play Store" và cài. Vẫn là app y hệt bản web/desktop.
Lưu ý: **chỉ arm64-v8a** (mọi điện thoại từ ~2017; không hỗ trợ máy chỉ chạy 32-bit), và Android **11+** (API 30). Phiên bản cũ hơn không cài được. Đây là cố ý: giữ mức tối thiểu ở phiên bản còn được gia cố bảo mật và là phiên bản bọn mình thật sự test (≈87% thiết bị đang hoạt động; [lý do](webapp/TAURI.md#why-android-11-api-30)). Cách tự build có trong mục Android của [`webapp/TAURI.md`](webapp/TAURI.md).
## Thêm game
Có ba cách để một game vào danh mục. Mỗi game đều được Maintainer duyệt, từng game một trong hàng chờ duyệt hoặc qua các quy tắc tự động do Maintainer đặt ra.
1.**Trang Suggest**: <https://freeitchgames.win/suggest>. Dán link game itch.io và, nếu muốn, một ghi chú ngắn (tối đa 500 ký tự; ghi chú bị xóa sau 180 ngày). Một bước kiểm tra Cloudflare Turnstile và giới hạn tần suất giúp chặn spam. Vui lòng không ghi dữ liệu cá nhân vào ghi chú.
2.**Tự động phát hiện**: cứ 4 giờ một lần, website đọc một trong các RSS feed công khai của itch.io về game miễn phí mới và phổ biến (mỗi lượt một feed) rồi đưa những gì tìm được vào hàng chờ.
3.**Collection được theo dõi**: website cũng đọc các collection công khai trên itch.io mà Maintainer theo dõi và đưa thẳng game miễn phí mới của chúng vào hàng chờ ingest (game từng bị gỡ, hoặc có cờ cảnh báo, thì vào hàng chờ duyệt).
Extension trình duyệt của Maintainer và Telegram bot cũ đã ngừng hoạt động; repo của chúng ([itch-f2p-extension](https://github.com/poli0981/itch-f2p-extension), [telegram-scraper-bot](https://github.com/poli0981/telegram-scraper-bot)) đã được lưu trữ (archive).
Maintainer duyệt hàng chờ trong một khu vực quản trị riêng (được bảo vệ bởi Cloudflare Access); mục không có cờ cảnh báo mà không ai từ chối trong thời gian chờ (mặc định 24 giờ) được duyệt tự động. Link được duyệt sẽ được chuyển cho pipeline dữ liệu, pipeline này cào từng trang game; game trả phí bị loại.
Thích dùng GitHub hơn, hoặc có cả một danh sách dài? Issue template "Add Games (bulk list)" cũng dùng được; các link đó đi qua cùng quy trình duyệt. Xem [CONTRIBUTING](docs/i18n/vi/CONTRIBUTING.md#1-đề-xuất-game-mới-hoan-nghênh-nhất).
Muốn **gỡ** một game, hoặc sửa dữ liệu của nó (nhất là các nhà phát triển game)? Gửi email tới **takedown@poli0981.dev** hoặc mở issue ["Remove a game"](https://github.com/poli0981/free-games-itchio-list/issues/new?template=remove_game.yml). Ghi rõ URL game, bạn là ai (người tạo / chủ sở hữu quyền, hoặc người được họ ủy quyền) và lý do. Chi tiết: [Điều khoản sử dụng](docs/i18n/vi/ToS.md) và [Tuyên bố miễn trừ](docs/i18n/vi/DISCLAIMER.md).
1.**Hàng chờ**: link đã duyệt được GitHub App của dự án commit vào `scripts/temp_link.json` (commit đã xác minh).
2.**Ingest**: `update.yml` chạy `update_info.py` ngay khi hàng chờ thay đổi (và mỗi ngày một lần để dự phòng). Mỗi link được chuẩn hóa, fetch, kiểm tra còn miễn phí không rồi cào dữ liệu; game trả phí, đã chết, trùng hoặc từng bị gỡ sẽ bị bỏ qua. Lỗi tạm thời được giữ lại trong hàng chờ để thử lại (tối đa 3 lượt chạy).
3.**Refresh**: `refresh.yml` mỗi ngày kiểm tra lại 1/7 danh mục (mỗi game một request), nên mọi game được kiểm tra lại hằng tuần: link chết (404/410), game chuyển sang trả phí, rating và trạng thái. Game chỉ bị gỡ khi cùng một vấn đề được thấy lại sau ít nhất 20 giờ. Việc gỡ được ghi kèm lý do trong [`scripts/deleted_games.json`](scripts/deleted_games.json), và một lượt chạy định gỡ số game nhiều bất thường sẽ giữ chúng lại và cảnh báo thay vì gỡ.
4.**Commit an toàn**: cả hai bước xuất ra một patch theo URL; `apply_patch.py` áp nó lên `main` mới nhất, validate mọi file dữ liệu (`validate.py`) rồi mới push, và thử lại nếu có tiến trình ghi khác push trước.
5.**Xuất bản**: mỗi lần push vào `main` sẽ build lại website, gói kèm danh mục tại <https://freeitchgames.win/data>.
Pipeline cư xử lịch sự với itch.io: nó tự xưng danh là `FreeItchGamesBot/4.0 (+https://freeitchgames.win/about)`, giãn nhịp request và tuân thủ HTTP 429 / `Retry-After`. Chỉ các trang và feed công khai của itch.io được đọc.
## Bên trong dự án
- **Web app** ([`webapp/src/`](webapp/src/)): React + TypeScript + Vite + Tailwind CSS, TanStack Query, React Router, Zustand. Giao diện tiếng Anh và tiếng Việt.
- **Cloudflare Worker** ([`webapp/worker/`](webapp/worker/)): phục vụ website và `/data`, cổng xác minh (Cloudflare Turnstile), proxy ảnh (`/img`, ảnh bìa WebP đã thu nhỏ lưu trên Cloudflare R2), API Suggest, hàng chờ duyệt (Cloudflare D1), API quản trị và lịch phát hiện qua RSS. Cấu hình: [`webapp/wrangler.jsonc`](webapp/wrangler.jsonc).
- **App quản trị** ([`webapp/admin/`](webapp/admin/)): màn hình duyệt chỉ dành cho Maintainer tại `/admin`, đứng sau Cloudflare Access. Nó ghi vào repo này dưới danh nghĩa một GitHub App.
- **Vỏ native** ([`webapp/src-tauri/`](webapp/src-tauri/)): Tauri 2 cho Windows, macOS, Linux và Android. Xem [`webapp/TAURI.md`](webapp/TAURI.md).
- **Pipeline dữ liệu** ([`scripts/`](scripts/), Python 3.15): scraper, refresh, patch/apply và validate, chạy bằng GitHub Actions.
Việc deploy do Cloudflare Workers Builds đảm nhận (thư mục gốc `webapp`, `npm run build`, rồi `npx wrangler deploy`): mỗi lần push vào `main` sẽ tự động lên site.
Dev cục bộ nhanh (thiết lập đầy đủ, gồm Worker, secret và test, có trong [`docs/dev_env.md`](docs/dev_env.md) ([VI](docs/i18n/vi/dev_env.md))):
```sh
cd webapp
npm ci
npm run dev # http://localhost:5173 (Vite)
npm run build # ghi vào webapp/dist/ (Worker phục vụ thư mục này làm assets)
npx wrangler dev # terminal thứ hai: Worker ở cổng :8787; Vite chuyển tiếp /api và /img tới đó
npm run tauri:dev # cửa sổ desktop native (cần Rust)
├── admin/ # App quản trị chỉ dành cho Maintainer (/admin)
├── worker/ # Cloudflare Worker (dữ liệu, proxy ảnh, API, hàng chờ duyệt, phát hiện qua RSS)
├── src-tauri/ # Vỏ Tauri 2 (desktop + Android)
├── wrangler.jsonc # Cấu hình Cloudflare
└── TAURI.md # Ghi chú build desktop / Android
LICENSE # MIT (mã nguồn)
LICENSES/CC-BY-4.0.txt # Toàn văn pháp lý CC BY 4.0 (dữ liệu + tài liệu)
NOTICE.md # Bản đồ giấy phép, tuyên bố không liên kết, ghi công
docs/ # Chính sách, môi trường dev, danh sách bên thứ ba (+ bản tiếng Việt trong docs/i18n/vi/)
```
## Tự động hóa
| Tác vụ | Lịch | Mục đích |
|---|---|---|
| Ingest (`update.yml`) | Khi hàng chờ đổi + hằng ngày 01:23 UTC | Cào link đã duyệt từ `temp_link.json`, bỏ qua game trả phí / đã chết / từng bị gỡ |
| Refresh (`refresh.yml`) | Hằng ngày 02:47 UTC | Kiểm tra lại 1/7 danh mục: link chết, game chuyển sang trả phí hoặc bị đặt mật khẩu, rating, trạng thái |
| Force update (`force_update.yml`) | Thủ công | Cào lại mọi trường (một URL hoặc lô tiếp theo); giữ nguyên `safe_virus` / `notes` / `nsfw` |
| Phát hiện qua RSS và quy tắc tự động (Cloudflare Worker) | Mỗi 4 giờ | Đọc một feed itch.io mỗi lượt vào hàng chờ duyệt; tự duyệt mục không có cờ sau thời gian chờ; đưa game miễn phí mới của collection được theo dõi vào hàng chờ ingest |
| Python CI / Webapp CI | Pull request (Python CI còn chạy khi push vào `main` chạm tới phần Python) | Lint, test, validate dữ liệu / type-check, test, build |
| Phân tích code (`sonarcloud.yml`, `qodana.yml`) | Pull request và push vào `main` có đổi code | SonarQube Cloud (kèm test coverage) và Qodana (TypeScript / JavaScript, Python, Rust) |
| Deploy website | Khi push vào `main` | Cloudflare Workers Builds (`webapp/wrangler.jsonc`) → freeitchgames.win |
| Theo dõi build (`deploy-status.yml`) | Mỗi giờ | Báo mỗi Workers Build lỗi của `main` lên Discord, một lần |
| Release desktop / Android | Khi push tag `v*` | Trình cài đặt Tauri (Win/macOS/Linux) và APK đã ký → draft Release |
Lỗi mạng được coi là tạm thời; game chỉ bị gỡ khi cùng lỗi 404/410 hoặc trạng thái trả phí được thấy lại ít nhất 20 giờ sau lần đầu. Lỗi, lượt bị hủy, bị giới hạn tốc độ và thay đổi hàng loạt đáng ngờ được báo về Discord của dự án dưới dạng thông báo tự động.
## Các trường dữ liệu
Mỗi game trong `data_game/game_info_NNN.json` có 20 trường sau, cộng thêm dấu thời gian tùy chọn `added_at` / `updated_at` do pipeline thêm vào và, từ bản 4.3, các trường tùy chọn `ai_disclosure` / `ai_content` / `accessibility` (được điền dần khi từng game được kiểm tra lại). Chỉ `safe_virus`, `notes` và `nsfw` do Maintainer quản lý; mọi thứ khác được cào từ trang itch.io công khai của game, và không lần cào lại nào ghi đè ba trường đó.
| `publisher` | Nhà phát hành (nếu khác tác giả) |
| `release_date` | Ngày phát hành đầy đủ từ metadata của trang |
| `made_with` | Engine / công cụ sử dụng |
| `rating` | Điểm đánh giá trung bình (tổng hợp từ itch.io) |
| `rating_count` | Số lượt đánh giá |
| `average_session` | Thời lượng một phiên chơi điển hình |
| `languages` | Ngôn ngữ hỗ trợ |
| `inputs` | Cách điều khiển (bàn phím, chuột, tay cầm) |
| `nsfw` | Cờ 18+, `Yes` / `No` (được gợi ý từ tag, cảnh báo nội dung và mô tả khi thêm game; do Maintainer quản lý) |
| `safe_virus` | Ghi chú an toàn thủ công: `?` (mặc định), `Yes`, `No`, `Caution`. Chỉ là ghi chú, không phải bảo đảm: file tải về không được quét |
| `notes` | Ghi chú thủ công |
| `thumbnail` | URL ảnh bìa (trên itch.io) |
| `ai_disclosure` | Công bố của tác giả về AI tạo sinh: `No AI`, `AI Assisted` (cách ghi của itch.io) hoặc `N/A` (chưa công bố) |
| `ai_content` | Phần dùng AI khi có dùng AI hỗ trợ (`Graphics`, `Text`, `Code`, `Sounds`) |
| `accessibility` | Tính năng hỗ trợ tiếp cận (`Subtitles`, `Configurable controls`, `Color-blind friendly`, …) |
Các trường được cào mặc định là `N/A` khi trang game không có thông tin.
## Đóng góp
Xem [CONTRIBUTING (tiếng Việt)](docs/i18n/vi/CONTRIBUTING.md) để có hướng dẫn đầy đủ (bản chính thức: [CONTRIBUTING.md](CONTRIBUTING.md)).
- **Thêm game**: dùng [trang Suggest](https://freeitchgames.win/suggest).
- **Gỡ game / sửa dữ liệu**: gửi email tới takedown@poli0981.dev hoặc mở issue ["Remove a game"](https://github.com/poli0981/free-games-itchio-list/issues/new?template=remove_game.yml).
- **Báo sự cố**: dữ liệu sai, link chết, hoặc có gì đó hỏng trên website hay trong ứng dụng: dùng issue template "Report a problem".
- **Rào cản trợ năng**: dùng [issue template "Accessibility barrier"](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml) hoặc gửi email tới contact@poli0981.dev. Xem [Trợ năng](docs/i18n/vi/ACCESSIBILITY.md) ([EN](ACCESSIBILITY.md)).
- **Tính năng và thay đổi code**: không còn được nhận, dự án đang ở [chế độ bảo trì](#trạng-thái-dự-án). Câu hỏi và góp ý xin gửi vào [Discussions](https://github.com/poli0981/free-games-itchio-list/discussions).
- **Vấn đề bảo mật**: báo cáo riêng tư, đừng bao giờ mở issue công khai. Xem [SECURITY](docs/i18n/vi/SECURITY.md) ([EN](SECURITY.md)).
- **Câu hỏi về quyền riêng tư**: xem [Chính sách quyền riêng tư](docs/i18n/vi/PrivacyPolicy.md) ([EN](docs/PrivacyPolicy.md)) hoặc gửi email tới privacy@poli0981.dev.
- Vui lòng tuân thủ [Quy tắc ứng xử](docs/i18n/vi/CODE_OF_CONDUCT.md) ([EN](CODE_OF_CONDUCT.md)).
Người đóng góp được ghi nhận trong [ACKNOWLEDGEMENTS.md](docs/ACKNOWLEDGEMENTS.md).
Cấu hình máy + môi trường dev của Maintainer: [`docs/pc_spec.md`](docs/pc_spec.md) ([VI](docs/i18n/vi/pc_spec.md)), [`docs/dev_env.md`](docs/dev_env.md) ([VI](docs/i18n/vi/dev_env.md)).
## Kết nối / hỗ trợ
Hai server Discord giờ đã tồn tại (câu "if I ever make one" chính thức lỗi thời):
- **Website**: [poli0981.dev](https://poli0981.dev/) · mọi kênh ở một chỗ: [poli0981.dev/links](https://poli0981.dev/links/)
- **Email**: **contact@poli0981.dev**
DM mở ở mọi nơi; trả lời chậm (hướng nội max level). [Trang About](https://freeitchgames.win/about) của website có cùng danh sách dưới dạng nút bấm.
## Giấy phép
Repo này dùng ba giấy phép (bản đồ đầy đủ trong [NOTICE.md](NOTICE.md)):
| Phần nào | Giấy phép | File |
|---|---|---|
| **Mã nguồn**: `scripts/`, `webapp/`, `bash/`, workflow, test, mọi thứ không liệt kê bên dưới | MIT, Copyright (c) 2025-2026 poli0981 (SkullMute) | [`LICENSE`](LICENSE) |
| **Dữ liệu danh mục**: `data_game/`, `scripts/deleted_games.json` và các file dẫn xuất tại <https://freeitchgames.win/data> | CC BY 4.0, cho phần đóng góp của Maintainer (xem bên dưới) | [`data_game/LICENSE.md`](data_game/LICENSE.md) |
| **Tài liệu**: các file `*.md` ở thư mục gốc repo và trong `docs/` (README này, các chính sách) | CC BY 4.0 | [`LICENSES/CC-BY-4.0.txt`](LICENSES/CC-BY-4.0.txt) |
**Giấy phép dữ liệu bao gồm:** việc tuyển chọn và sắp xếp bộ sưu tập, ba trường do Maintainer viết (`safe_virus`, `notes`, `nsfw`), các bản ghi gỡ game, cùng cấu trúc và số liệu thống kê dẫn xuất.
**Không bao gồm** (thuộc sở hữu của người khác, dự án không cấp phép): mô tả game và mọi văn bản khác do người làm game viết, ảnh bìa / thumbnail và các phương tiện khác, tên game, logo và nhãn hiệu, cùng nhãn hiệu của itch.io. Các dữ kiện đơn thuần như URL, giá và điểm đánh giá vốn không được bảo hộ quyền tác giả.
Khi tái sử dụng dữ liệu, vui lòng ghi công như sau:
```
Free itch.io games catalog by poli0981 (SkullMute) — https://freeitchgames.win — CC BY 4.0
```
Các thành phần bên thứ ba giữ giấy phép riêng của chúng: xem [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md) và trang About của website. Extension trình duyệt (đã archive) là một repo riêng theo GPL-3.0. Đóng góp được nhận theo cùng giấy phép với phần mà nó thay đổi (inbound = outbound): MIT cho mã nguồn, CC BY 4.0 cho dữ liệu và tài liệu.
**Không liên kết với itch.io.** Đây là một dự án độc lập do người hâm mộ làm. Dự án không liên kết với, không được chứng thực hay tài trợ bởi itch.io, Leaf Corcoran hoặc itch corp. "itch.io" cùng mọi tên game, logo và nhãn hiệu thuộc về chủ sở hữu tương ứng.
## Pháp lý
Bản tiếng Việt nằm trong [`docs/i18n/vi/`](docs/i18n/vi/); bản tiếng Anh là bản chính thức cho mọi giải thích pháp lý.
- [Điều khoản sử dụng](docs/i18n/vi/ToS.md) ([EN](docs/ToS.md)): áp dụng cho website và mọi thứ trên đó
- [Chính sách quyền riêng tư](docs/i18n/vi/PrivacyPolicy.md) ([EN](docs/PrivacyPolicy.md))
- [Tuyên bố trợ năng (Accessibility)](docs/i18n/vi/ACCESSIBILITY.md) ([EN](ACCESSIBILITY.md)): những gì đã hỗ trợ cho công cụ trợ năng, các hạn chế đã biết, cách báo rào cản
- [NOTICE](NOTICE.md)
Liên hệ (hộp thư riêng của Maintainer trên poli0981.dev):
- Quyền riêng tư: **privacy@poli0981.dev**
- Gỡ nội dung / bản quyền: **takedown@poli0981.dev**
- Lỗ hổng bảo mật: **security@poli0981.dev** (hoặc tính năng báo cáo lỗ hổng riêng tư của GitHub)
- Mọi vấn đề pháp lý khác: **legal@poli0981.dev**
- Các việc khác: **contact@poli0981.dev**, hoặc bất kỳ kênh nào tại [poli0981.dev/links](https://poli0981.dev/links/)
Yo, this is mostly a hobby repo — a curated list of free itch.io games with Python scraping scripts on GitHub Actions, plus a React/TypeScript webapp (and Tauri desktop wrapper) for browsing and editing the catalog. Still no backend, no database, no telemetry. The one security-relevant thing is the GitHub Personal Access Token the webapp can hold for write operations — see below.
Applies from: the release of version 4.0.0.
## Supported Versions
Everything here is "latest commit" only. I'm unemployed with too much free time, so fixes (if any) come when I feel like it — or when Grok nags me.
Yo — this is a hobby project run by one person, poli0981 (SkullMute), called "the Maintainer" below: a curated catalog of free itch.io games. Since v4 it is made of a **read-only website** at https://freeitchgames.win (served by a Cloudflare Worker), a **Python data pipeline** on GitHub Actions, and **read-only desktop and Android apps**. There are no public accounts, no sign-in and no payments; the only login is the Maintainer's own admin page, protected by Cloudflare Access. Small attack surface — but if you find a hole, the Maintainer really wants to hear about it.
## Reporting a Vulnerability
Found something scary? Like a script that could theoretically spam itch.io or expose... nothing? You're a legend.
## 1. Reporting a vulnerability
Please **don't**open a public issue. Instead:
- Open a **private** GitHub issue (if the repo allows — I'm introvert, might not have email public).
- Or just open a normal issue and prefix "[Security]" — I'll make it private if needed.
- Describe the issue clearly (steps to reproduce, potential impact).
- I'll review (with Grok's help, because my security knowledge is "easy mode" level).
Please **don't**report vulnerabilities in public issues, discussions, pull requests or Discord. Report them privately instead:
What to expect:
-I'll acknowledge within a few days (unemployed schedule, not 24/7).
- If valid (big if :v), I'll fix and credit you in changelog/acknowledgements.
- If not valid — thanks anyway for caring about my mediocre code.
- **GitHub private vulnerability reporting**: the repository's **Security** tab → **Report a vulnerability** ([direct link](https://github.com/poli0981/free-games-itchio-list/security/advisories/new)), or
-email **security@poli0981.dev**.
Common "vulnerabilities" you might find:
- Scraping breaks if itch.io changes HTML (not security, just life).
- Rate limiting? I already sleep(2) — be kind to servers.
- Dependencies? requests + bs4 are stable, but update if needed.
- Webapp deps (npm/Rust)? Dependabot/security alerts on the repo cover those — bumps land via PR.
A good report includes:
## Webapp PAT handling (read this if you use the writeable webapp)
- what is affected (URL or endpoint, workflow, or app version and platform);
- steps to reproduce, or a working proof of concept;
- the impact you think it has;
- whether, and how, you would like to be credited.
The browse-only flows (Dashboard, Games table, Charts, Deleted) need **no** auth and use the public CDN at `raw.githubusercontent.com`. Write flows (edit annotations, bulk edit/delete, dispatch the scraper workflow) need a GitHub Personal Access Token, which the webapp stores like this:
## 2. Scope
- **Use a fine-grained PAT** scoped to **only**`poli0981/free-games-itchio-list` with the minimum scopes you need:
-`actions: write` — required for the Add page / Workflows page dispatch buttons.
-`metadata: read` is implicit.
- **At rest** the PAT is encrypted with AES-GCM 256-bit; the key is derived from your passphrase via PBKDF2-SHA256 (100k iterations) with a fresh per-token salt. The encrypted blob lives in `localStorage` under `webapp.pat.encrypted`.
- **In memory** the decrypted PAT only exists in the React app's Zustand store between unlock and explicit Lock (or tab close).
- **Lock or remove anytime** from Settings. Removing also wipes the localStorage entry.
- **Don't paste a classic PAT** with full repo scope unless you really mean to. Fine-grained tokens are scoped to one repo and one set of operations.
- **Don't share `localStorage`** between users (e.g., shared kiosk machine). The encryption protects the PAT from a casual file-system reader, not from someone who knows your passphrase.
**In scope**
If you find a way to bypass the encryption, exfiltrate the PAT from memory through a CSP gap, or trick the webapp into sending writes to the wrong repo — please report privately as above.
- The website https://freeitchgames.win and its Cloudflare Worker, including the image proxy (`/img`), the Suggest API (`/api/suggest`), and the admin app and API (`/admin`, `/api/admin`).
- The data pipeline (`scripts/`) and the GitHub Actions workflows (`.github/workflows/`).
- The desktop apps and the Android APK published on [GitHub Releases](https://github.com/poli0981/free-games-itchio-list/releases).
- The published data (`data_game/`, `scripts/deleted_games.json`, and https://freeitchgames.win/data) — for example, a way to get content into the catalog without the Maintainer's approval.
## Web/desktop dependency reporting
**Out of scope**
For Tauri / Rust crate vulnerabilities or npm package CVEs that affect the webapp, opening a normal `[Security]` issue is fine; if it's actively exploitable in the deployed Pages site, please prefix `[CRITICAL]` so I can yank the deploy until it's fixed.
- itch.io itself — report to itch.io.
- Platform issues in Cloudflare or GitHub — report to them through their own programs.
- The games linked from the catalog. A game that contains malware is not a vulnerability in this project, but please still tell the Maintainer at **takedown@poli0981.dev** so it can be flagged or removed.
- Volumetric denial-of-service (DoS/DDoS) and load testing.
- Reports from automated scanners without a working proof of concept.
No bounties (bank account < $50), but eternal thanks and a shoutout.
The browser extension (poli0981/itch-f2p-extension) and the Telegram bot (poli0981/telegram-scraper-bot) are archived and no longer supported, so they are out of scope.
This repo is MIT licensed and super low-risk. Stay safe out there — especially when downloading random free games.
## 3. Supported versions
Thanks for reporting responsibly. You're better at security than me already. 🚀
| Component | Supported |
|---|---|
| The live website (https://freeitchgames.win) | Yes |
| The latest release (4.x) of the desktop and Android apps | Yes |
| Older releases (including all 3.x and earlier) | No — please update |
Fixes to the website go live when they are deployed. The apps do not update themselves: fixes ship in a new release, which you download from GitHub Releases.
Since version 4.6.1 the project is in **maintenance mode**: no new features, but security fixes and runtime and dependency updates continue as described here.
## 4. What to expect
- **Acknowledgement**: target within **7 days**. This is a solo hobby project, so that is a target rather than a guarantee, and often it will be much sooner.
- The Maintainer will check whether the issue is valid, work on a fix, and keep you updated.
- Please keep the details private until a fix is out, or until you and the Maintainer agree on a disclosure date.
- **Credit**: if you want it, you will be credited in the release notes.
- There is no bug bounty (bank account < $50), just credit and eternal thanks.
## 5. Safe harbor
If you research security in good faith and follow this policy, the Maintainer will consider that research authorized, will not take or support legal action against you for it, and will not treat it as a breach of the [Terms of Use](docs/ToS.md) rules on unauthorized access or automated use. To stay within safe harbor:
- **Avoid privacy violations.** Do not access, change, keep or share data that isn't yours beyond the minimum needed to show the issue (for example, notes submitted through the Suggest page, the review queue, or the admin audit log). If you come across personal data, stop and report it.
- **Avoid service disruption.** No denial-of-service, no high-volume automated scanning or scraping, no spamming the Suggest form, and no attempts to exhaust rate limits.
- **Don't change anything.** Do not modify or delete catalog data, the review queue or the repository, and do not approve or reject items, push commits or trigger releases, even if you find a way to.
- **No social engineering, phishing or physical attacks** against the Maintainer or anyone else, and no attacks on anyone's Cloudflare, GitHub or itch.io accounts.
- **Give the Maintainer reasonable time** to fix the issue before you disclose it publicly.
This safe harbor covers only the Maintainer's own claims. It cannot authorize testing of Cloudflare, GitHub or itch.io; their own policies apply. If you are unsure whether something is OK, ask first at **security@poli0981.dev**.
## 6. Dependency and supply-chain security
What the repository actually does:
- **Dependabot** ([`.github/dependabot.yml`](.github/dependabot.yml)) is configured to keep npm, pip, GitHub Actions and cargo dependencies current.
- Every third-party **GitHub Action is pinned by full commit SHA**, and each workflow declares least-privilege `permissions`.
- Writes to the repository from the website's admin go through a **GitHub App** (verified commits), and the admin page is behind Cloudflare Access (GitHub login or one-time email PIN) and limited to the Maintainer.
- The website limits how many requests one address can send in a short time (a Cloudflare WAF rule, then per-route limits in the Worker that answer HTTP 429), and the Suggest form adds Cloudflare Turnstile and a stricter limit of its own.
- The Android APK is signed with the project's key. Install it, and the desktop apps, only from the project's [GitHub Releases](https://github.com/poli0981/free-games-itchio-list/releases) page.
If a known vulnerability in a dependency actually affects a deployed component (the website, the Worker, the pipeline or the apps), report it privately as in [§1](#1-reporting-a-vulnerability). If it is just an outdated dependency with no practical impact, a normal issue or pull request is fine.
## 7. Scams and impersonation
The project has no accounts and takes no payments, so nobody from the project will ever ask for your password, a token or payment details. The only official website is https://freeitchgames.win (the old github.io address only redirects there), and the only official downloads are on GitHub Releases. If you see something pretending to be this project, please tell the Maintainer at **security@poli0981.dev**.
## 8. Final vibes
Stay safe out there — especially when downloading random free games. Thanks for reporting responsibly. You're better at security than the Maintainer already. 🚀
Release notes for 1.0.0 – 1.0.5, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [1.0.5] - 2026-01-12 (Hotfix 🔧)
### Fixed
- UTF-8 decode issue when running `scripts/update_info.py`. See [#16](https://github.com/poli0981/free-games-itchio-list/issues/16).
---
## [1.0.4] - 2026-01-11 (Added Games + New Features ⭐)
### Added Games
Added 33 games. See [#22](https://github.com/poli0981/free-games-itchio-list/issues/22) and [#23](https://github.com/poli0981/free-games-itchio-list/issues/23).
### New Features
- Delete game with correct link in `delete_game.py`. See [#20](https://github.com/poli0981/free-games-itchio-list/issues/20).
- Export JSON → `.csv`/`.xlsx` in `export_csv.py`. See [#21](https://github.com/poli0981/free-games-itchio-list/issues/21).
- Check duplicate data in JSON file in `check_duplicate.py`. See [#19](https://github.com/poli0981/free-games-itchio-list/issues/19).
---
## [1.0.3] - 2026-01-01 (Improvements ⚙️)
### Improved
- Optimized workflow scheduling.
---
## [1.0.2] - 2026-01-01 (Hotfix 🔧)
### Fixed
- `temp_link.json` not resetting to `[]` after GitHub Actions run.
---
## [1.0.1] - 2025-12-31 (Hotfix 🔧)
### Fixed
- Rewrote and added 2 issue templates.
- Updated [CONTRIBUTING](../../CONTRIBUTING.md).
---
## [1.0.0] - 2025-12-28 (Initial Release 🚀)
### Added
- Full curated list of free itch.io games with auto-daily updates via GitHub Actions.
Release notes for 2.0.0, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [2.0.0] - 2026-03-26 (Major Rewrite 🔧⭐)
### Rewritten
- **`scraper.py`** — new shared module extracted from `update_info.py`. All scraping logic, session management, rate-limiting, and parsing utilities live here. Used by every script that touches itch.io.
- **`update_info.py`** — fully rewritten. Uses `scraper.py` module, `requests.Session` with automatic retry (backoff on 429/5xx), and random delays between requests.
- **`generate_md.py`** — fully rewritten with pipe-character escaping and all new data fields.
### Added
- **Free game detection** — `update_info.py` now checks if a game is free before scraping. Paid games are skipped automatically. Detection logic parses `div.buy_row` for price tags and button text.
- **`check_paid.py`** — new script. Re-checks every game in the list to see if it became paid. Paid games are removed and logged to `deleted_games.json` with reason and timestamp.
- **`check_alive.py`** — new script. Verifies that all game URLs still exist. Pages returning 404 or 410 are removed and logged. Transient errors (403, 5xx, timeouts) are kept.
- **`log_deleted.py`** — new script. Converts `deleted_games.json` → `deleted_games.txt` (human-readable log sorted by date).
- **`deleted_games.json`** — structured log of all removed games with URL, name, reason, and deletion timestamp.
- **New data fields** scraped from itch.io info table: `status`, `platforms`, `publisher`, `release_date`, `made_with`, `rating`, `rating_count`, `average_session`, `languages`, `inputs`. All fields default to `N/A` when not found.
- **Author/Authors handling** — scraper now checks both `Author` and `Authors` keys (itch.io uses either depending on the page).
- **Release date parsing** — extracted from `<abbr title="...">` for full datetime instead of abbreviated text.
- **NSFW detection** expanded — now also checks game description text and adds `sexual` keyword.
### Added (GitHub Actions)
- **`check_paid.yml`** — runs every 2 days at 04:00 UTC. Removes games that became paid.
- **`check_alive.yml`** — runs every 2 days at 07:00 UTC (staggered 3h after check_paid). Removes dead links.
- **`log_deleted.yml`** — runs after check_paid or check_alive completes. Exports deletion log.
- **`generate_table.yml`** — now triggers after update, check_paid, and check_alive workflows (not just update).
- **`update_csv.yml`** — now triggers after table generation (chained workflow).
### Improved
- **Rate limiting** — random delays (2.5–5s between requests, 15–30s batch pause every 20 requests) to avoid itch.io IP bans. Lighter delays (1–2.5s) for HEAD/status checks.
- **Retry logic** — `requests.Session` with `HTTPAdapter` + `Retry` (3 attempts, exponential backoff 2→4→8s) on 429/500/502/503/504.
- **Network error safety** — games are never deleted on transient network failures. Only confirmed 404/410 or confirmed paid status triggers removal.
- **Markdown table integrity** — pipe characters (`|`) in game data are escaped to prevent table breakage.
- **All fields use `N/A` consistently** — replaced mixed `""`, `"Unknown"`, `"No description"` with uniform `N/A` fallback.
Release notes for 3.2.0 – 3.2.1, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.2.1] - 2026-05-11 (Hotfix: single-instance enforcement on desktop)
### Fixed
- **Desktop app spawned a new process on every launch.** Each double-click of the installed app added another `free-games-itchio-webapp.exe` (Windows) / equivalent on macOS+Linux to the task list instead of focusing the existing window. Added [`tauri-plugin-single-instance`](https://tauri.app/plugin/single-instance/) v2 in [`webapp/src-tauri/src/lib.rs`](../../webapp/src-tauri/src/lib.rs) — second launch now unminimizes + focuses the running window and exits its own process before creating a duplicate. Plugin registered first in the builder chain per Tauri 2 docs so duplicate processes die before initializing HTTP/opener plugins. Gated by `#[cfg(desktop)]` + matching `cfg(not(android, ios))` in [`Cargo.toml`](../../webapp/src-tauri/Cargo.toml). Desktop binary boundary change → bumped [`Cargo.toml`](../../webapp/src-tauri/Cargo.toml) and [`tauri.conf.json`](../../webapp/src-tauri/tauri.conf.json) from `0.1.0` to `0.1.1` (first time these have moved since v3.0.0).
### Changed
- **README + README.vi badges** bumped to `3.2.1`.
- **About page** lists `tauri-plugin-single-instance` v2 under Desktop dependencies.
---
## [3.2.0] - 2026-05-10 (CI cleanup + mobile + SEO + Telegram bot path + auto-discussion)
### Added
- **Mobile drawer navigation.** New [`webapp/src/components/ui/sheet.tsx`](../../webapp/src/components/ui/sheet.tsx) (shadcn pattern over the existing `@radix-ui/react-dialog`) and a `MobileTopBar` in [`webapp/src/components/sidebar.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.2.0/webapp/src/components/sidebar.tsx). Below `md`, the sidebar collapses behind a hamburger; above, the desktop sidebar behaves as before. Touch targets in the nav now meet the 44pt iOS HIG minimum on small screens.
- **DataTable column priorities.** Each column declares `meta.priority: 1 | 2 | 3` in [`columns.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.2.0/webapp/src/components/data-table/columns.tsx). [`data-table.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.2.0/webapp/src/components/data-table/data-table.tsx) hides priority 2 below `md` and priority 3 below `lg`, so the table is usable on a phone without horizontal scrolling through every column.
- **PWA manifest + icons.** [`webapp/public/manifest.webmanifest`](../../webapp/public/manifest.webmanifest), [`icon-192.png`](../../webapp/public/icon-192.png), [`icon-512.png`](../../webapp/public/icon-512.png) — Add to Home Screen on iOS without a service worker. Generator script: [`webapp/scripts/gen_assets.py`](../../webapp/scripts/gen_assets.py).
- **SEO infrastructure.** [`webapp/index.html`](../../webapp/index.html) now ships description, theme-color (per scheme), Open Graph (title/description/image/url/type/locale), Twitter card (`summary_large_image`), `canonical`, `apple-touch-icon`, `manifest`, and `preconnect` to `img.itch.zone` + `raw.githubusercontent.com`. [`robots.txt`](../../webapp/public/robots.txt) and `sitemap.xml` added under `webapp/public/`.
- **OG image.** [`webapp/public/og.png`](../../webapp/public/og.png) (1200×630) + [`og.webp`](../../webapp/public/og.webp) generated by `gen_assets.py`. Brand-coloured (`#863bff` purple, cyan accent) with project name, tagline, and URL.
- **Per-route titles.** New [`useDocumentTitle`](../../webapp/src/hooks/useDocumentTitle.ts) hook (no `react-helmet-async` dependency). Each route now sets a contextual title (`Charts — Itch.io Free Games Database`, etc.); game-detail uses the game name.
- **Hash-anchor scroll.** [`App.tsx`](../../webapp/src/App.tsx) now wires a `ScrollToHash` listener so links like `/about#support` scroll to the matching element under HashRouter.
- **About page Telegram entries.** New `messaging` social group with **Telegram (DM)** and **Telegram bot (game submission)** plus a privacy reminder to never paste a numeric ID into public channels. About also surfaces all five FUNDING.yml destinations (GitHub Sponsors, Patreon, Ko-fi, Buy Me a Coffee, PayPal) with a footnote on PayPal explaining the legal-name receipt.
- **Sidebar Support link.** Persistent heart-icon link from the sidebar (collapsed and expanded) to `/about#support`.
- **Telegram bot contribution flow.**`CONTRIBUTING.md §1b` describes the bot path (DM owner → numeric ID added to local whitelist → bot dispatches `bot-ingest.yml`). Cross-linked from [README.md](../../README.md), [README.vi.md](../../README.vi.md), and the new issue template `game_via_bot.yml`. Vietnamese mirror in [`docs/i18n/vi/CONTRIBUTING.md`](../../docs/i18n/vi/CONTRIBUTING.md).
- **Privacy + ToS clauses for the bot path.** [`docs/ToS.md §14`](../../docs/ToS.md) and [`docs/PrivacyPolicy.md §15`](../../docs/PrivacyPolicy.md) (plus VI mirrors) document Telegram-ID handling: opt-in, operator-side whitelist only, never committed to this repo, removable on DM.
- **`docs/pc_spec.md` + `docs/dev_env.md` (EN + VI).** Maintainer hardware spec, mobile test devices (iPhone 14 Pro / 13 Pro Max, iOS 26.x on Chrome + Brave), and dev-env toolchain (Python 3.12, Node ≥ 22, Rust stable, JetBrains 2026.x). Cross-linked from README and CONTRIBUTING.
- **Auto-create GitHub Discussion workflow.** [`announce-discussion.yml`](../../.github/workflows/announce-discussion.yml) — on `release: published` posts to the **Announcements** category; on push to `docs/**` / `CHANGELOG.md` / `README*.md` posts to **General**, gated by `[skip-discuss]` in the head-commit message and a quiet skip on `bot-ingest:` commits. Uses `gh api graphql` directly (no third-party action). Setup: configure repo variables `DISCUSSION_REPO_ID`, `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID`, `DISCUSSION_GENERAL_CATEGORY_ID` (run the GraphQL pre-flight query in the workflow header to fetch them).
### Changed
- **CI notify wrappers.**`notify-ci-failure.yml`, `notify-deploy.yml`, and [`notify-release-pipeline.yml`](../../.github/workflows/notify-release-pipeline.yml) replace `workflows: ["*"]` with explicit allowlists. Every workflow run no longer fans out to all three wrappers; the Actions tab is much quieter and the per-event reusable filtering is what it always should have been.
- **`bot-ingest.yml` cleanup.** Removed a dead final step that referenced a non-existent `${{ secrets.BOT_TOKEN }}` and a `result.txt` file. The Python `success`/`failure` Telegram callback steps above already handle both outcomes.
- **Image hints.** Game thumbnails in [`columns.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.2.0/webapp/src/components/data-table/columns.tsx) and the hero in [`game-detail.tsx`](../../webapp/src/routes/game-detail.tsx) now declare `width`/`height` (CLS), `decoding="async"`, and `fetchPriority` (high for hero, low for table rows). itch.io thumbnails remain external — full WebP recompression is intentionally deferred (would require an image proxy).
- **README + README.vi badges** bumped to `3.2.0`.
### Fixed
- **Bot ingest workflow** had a broken final telegram callback step (wrong secret name + missing input file). Removed; the working callback steps above are unaffected.
### Setup notes for maintainers (one-time, post-merge)
To enable the auto-discussion workflow, run once:
```sh
gh api graphql -f query='query{repository(owner:"poli0981",name:"free-games-itchio-list"){
- **In-browser GPG commit signing.** Every write the webapp makes (single-file edits, bulk edit/delete, queueing URLs) can now be GPG-signed client-side. New `webapp/src/lib/gpg/` module: `canonicalize.ts` builds the exact byte string Git would hash, `sign.ts` lazy-imports `openpgp` and exposes `loadPrivateKey` / `signCommit` / `verifyDetached`, `storage.ts` wraps localStorage helpers. Verified byte-for-byte against `git cat-file commit <sha>` so the signed canonical exactly matches what GitHub will recompute (no trailing-newline drift). Private keys are decrypted once at import and re-encrypted with the webapp passphrase (AES-GCM, same scheme as the PAT) — `openpgp` is loaded only when the Commit Signing card is opened or a commit is being signed (`vendor-openpgp` chunk, ~129 KB gz, lazy).
- **Settings → Commit signing card.** New `webapp/src/components/settings/gpg-card.tsx` — three states (not configured / locked / unlocked) with Import (paste armored or upload `.asc`), Unlock, Test sign (round-trip verify), Copy public key, Lock, Remove. Shows the imported key's UIDs as badges and flags a clear mismatch warning if the configured commit-author email isn't in the key's UID list (the most common cause of GitHub's "Someone may be trying to trick you" warning). After import, primary UID email auto-populates Commit author so commits Verify on the first try.
- **Settings Phase A — Appearance / Session / Commit author / Notifications cards.** [`webapp/src/routes/settings.tsx`](../../webapp/src/routes/settings.tsx) gained four new cards backed by extended preferences in [`webapp/src/stores/prefs.ts`](../../webapp/src/stores/prefs.ts): theme picker (Light / Dark / System), layout density (Normal / Compact), sidebar collapse mirror, idle-timeout slider (5 / 15 / 30 / 60 / 120 min — replaces the hard-coded 30-min constant in `auth.ts`), commit-author name/email override, toast enable + duration. Density applies via `html[data-density='compact']` rules in [`index.css`](../../webapp/src/index.css); toasts are gated through a new [`AppToaster`](https://github.com/poli0981/free-games-itchio-list/blob/v3.3.0/webapp/src/components/app-toaster.tsx) wrapper that reads prefs.
- **Mobile card view for the games table.** New [`webapp/src/lib/use-is-mobile.ts`](../../webapp/src/lib/use-is-mobile.ts) (`matchMedia('(max-width: 767px)')`) and [`webapp/src/components/data-table/mobile-card-list.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.3.0/webapp/src/components/data-table/mobile-card-list.tsx). Below the `md` breakpoint, [`DataTable`](https://github.com/poli0981/free-games-itchio-list/blob/v3.3.0/webapp/src/components/data-table/data-table.tsx) renders a stacked card list (thumbnail + name + dev + genre/status/NSFW/safe badges, tap-to-detail, selection checkbox) instead of the 9-column virtualized table that overflowed at 430 px. Pagination is shared between both views.
- **Workflows route mobile fallback.**`workflows.tsx` now dual-renders the action picker — a `<Select>` dropdown below `md`, the existing `TabsList` at `md` and above. Fixes the overflow from five `whitespace-nowrap` triggers in an `inline-flex` TabsList at 430 px viewport.
### Changed
- **All write paths route through the Git Data API.**`webapp/src/lib/github/contents.ts``putFile` (`PUT /repos/.../contents/{path}`) is gone — that endpoint authors commits as the PAT and never accepts a `signature` field. Replaced with `commitSingleFile` which delegates to `atomicCommit` so single-file edits (game annotations, `temp_link.json` queue) get the same signer plumbing as bulk operations. `atomicCommit` gained an optional `signer` parameter (defaulting to `getSignerIfEnabled()`) that, when present, builds the canonical commit object, signs detached binary-mode via openpgp, and passes `author` / `committer` / `signature` to `git.createCommit`. Commit author identity falls back through prefs override → imported key's primary UID email → GitHub user.
- **About page** lists `OpenPGP.js` 6.3 under Data dependencies; the [`webapp/vite.config.ts`](../../webapp/vite.config.ts) `manualChunks` rule emits a dedicated `vendor-openpgp` chunk so the cost is only paid when a user opens the signing card.
- **README + README.vi badges** bumped to `3.3.0`.
### Fixed
- **Workflows `/workflows` tabs no longer overflow on mobile.** Pre-fix: five `whitespace-nowrap` triggers in an `inline-flex` TabsList blew past a 430 px viewport.
- **DataTable no longer overflows on mobile.** Pre-fix: nine fixed-width columns minus three responsive-hidden ones still exceeded 430 px.
- **DataTable columns misaligned at desktop widths.** Header used native table-layout (`<table className="w-full">` + `<th style={{width}}>`) while body rows used flex layout (`position: absolute` + `flex w-full`, cells with `flex: 0 0 Npx` / `1 1 0`). Native table-layout stretched the 8 size-less columns to fill the container based on content, but the absolutely-positioned body `<tr>` never participated in table layout — so its flex children stayed at their fixed flex-basis. Result: at the Tauri default 1280×800 window (and any viewport wider than the natural sum of header content widths) header columns drifted off the cells below them. [`webapp/src/components/data-table/data-table.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.4.1/webapp/src/components/data-table/data-table.tsx) now renders the header `<tr>` with `flex w-full` and each `<th>` with `flex h-10 items-center` + the same `flex: 0 0 Npx` / `1 1 0` style block as the body `<td>` — header and body now compute width identically. Helper `priorityHeaderClass` (which emitted `table-cell` variants) is gone; the existing `priorityClass` (`flex` variants) now drives both. No change to column definitions in [`columns.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.4.1/webapp/src/components/data-table/columns.tsx).
- **`announce-discussion.yml` was a silent no-op since v3.2.0.** Both jobs (`announce-release`, `announce-docs`) gated on three repo variables (`DISCUSSION_REPO_ID`, `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID`, `DISCUSSION_GENERAL_CATEGORY_ID`) that had never been configured — the validation step printed `::warning::… Skipping.` and `exit 0`, so every release silently failed to post to Discussions without surfacing a failed run. Replaced the two validation steps with a `Discover Discussion IDs` step that queries `gh api graphql` for `repository.id` and looks up the category by slug (`announcements` / `general`). Zero config now — works on any repo with Discussions enabled. Fails loudly with a clear `::error::` message if Discussions isn't enabled or the expected category is missing. Dropped the dependency on `vars.DISCUSSION_*` and removed every `if: steps.validate.outputs.ids_ok == 'true'` gate.
### Changed
- **README + README.vi badges** bumped to `3.4.1`.
### Notes
- This is a webapp + CI hotfix. No Python pipeline changes, no Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`, no THIRD_PARTY entries change.
- The leftover `DISCUSSION_REPO_ID` / `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID` / `DISCUSSION_GENERAL_CATEGORY_ID` repo variables (if you set them earlier) are now unused and can be removed from Settings → Variables.
- **Update reviews — bi-weekly workflow.** New `scripts/update_reviews.py`, wrapper `bash/update_reviews.sh`, and `.github/workflows/update_reviews.yml` re-scrape every existing game's itch.io page on the 1st and 15th of each month (05:00 UTC) and write fresh `rating` + `rating_count`. Network errors / 404 keep the old values. Touches only those two fields — everything else (annotations, metadata) is left alone.
- **Update status — monthly workflow.** New `scripts/update_status.py`, `bash/update_status.sh`, and `.github/workflows/update_status.yml` refresh the `status` field on the 1st of each month (06:00 UTC). Same skip-on-error semantics.
- **Force update — manual emergency button.** New `scripts/force_update.py`, `bash/force_update.sh`, and [`.github/workflows/force_update.yml`](../../.github/workflows/force_update.yml) accept an optional `url` input. Empty input re-scrapes every game; a single URL targets just that one. `workflow_dispatch` only — no schedule. Every run preserves the three user-editable annotations (`safe_virus`, `notes`, `nsfw`) per the read/write field convention in [CLAUDE.md](../../CLAUDE.md). Doubles as the canonical repair tool for mojibake left by older webapp commits — re-scrape pulls clean UTF-8 from itch.io.
- **`generate_table.yml` chained on the three new workflows** so `lists/*.md` stay in sync after any data mutation.
### Fixed
- **UTF-8 mojibake on webapp commits.**`webapp/src/lib/github/contents.ts``readFileWithSha` and `webapp/src/lib/github/git-data.ts``bulkDeleteGames` were decoding GitHub's base64 content with `atob` alone, producing a Latin-1 binary string. Multi-byte UTF-8 sequences (e.g. Vietnamese `ã` = `0xC3 0xA3`) became two Latin-1 code points (`ã`); the next write re-encoded them as UTF-8 bytes, double-corrupting on every edit. Confirmed live damage in `data_game/game_info_002.json` (`BotÃÂão Esquerdo` was originally `Botão Esquerdo`). Extracted a shared helper `webapp/src/lib/github/encoding.ts` (`base64ToUtf8` / `utf8ToBase64`) that uses `TextDecoder('utf-8')` / `TextEncoder` and routes both call sites through it. Write path was already correct.
### Notes
- **Repair existing mojibake**: after this release deploys, run `Force update` once via `workflow_dispatch` with no input. It re-scrapes every game (~15–25 min) and writes back clean UTF-8 while preserving manual annotations. `generate_table.yml` will then auto-regenerate the markdown lists.
- **Browser cache**: anyone editing via the webapp should hard-refresh once after the new build lands so they're not using the pre-fix bundle (which would continue to mangle non-Latin chars on the next edit).
- **README + README.vi badges** bumped to `3.4.0`. No Tauri / Rust binary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`.
`indexByUrl`, `rawUrl`, `useIndex`, `isIdleExpired`, …), the unused
`EDITABLE_FIELDS` / `READONLY_FIELDS` constants, and 7 unused shadcn/ui
primitive exports. Exports used only inside their own module were demoted
from `export` rather than deleted.
### Changed
- `webapp/src/lib/about.ts``THIRD_PARTY` array trimmed to match the removed
dependencies.
### Notes
- DX / code-quality only — no runtime behaviour change. `isIdleExpired` was
already dead (nothing called it), so PAT idle auto-lock is unchanged — still
not enforced.
- No Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json`
stay at `0.1.1`. The Rust `tauri-plugin-http` crate is now unreferenced from
the front-end — a candidate for a future Rust-side cleanup.
- knip + vulture join `npm run lint`, `ruff check`, and `npm audit` as the
standing pre-release QA pass.
---
## [3.5.1] - 2026-05-20 (Lint cleanup — zero ESLint problems)
### Changed
- **`npm run lint` now runs clean — 0 errors, 0 warnings** (down from 17 errors + 5 warnings, all pre-existing; v3.5.0 added none).
- [`webapp/eslint.config.js`](../../webapp/eslint.config.js): `react-refresh/only-export-components` is turned off for `src/components/ui/**` — the vendored shadcn primitives intentionally mix component and variant/constant exports and cannot satisfy the rule without forking upstream. The rule stays on for all other app code.
- `react-hooks/incompatible-library` is turned off — it only flagged TanStack Table's `useReactTable`, whose API is not React-Compiler-memoizable by design (not actionable).
- **`SortableHeader` extracted** into its own [`webapp/src/components/data-table/sortable-header.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.5.1/webapp/src/components/data-table/sortable-header.tsx); [`columns.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.5.1/webapp/src/components/data-table/columns.tsx) is now a pure column-definition module.
### Fixed
- **`react-hooks/exhaustive-deps`** in [`routes/games.tsx`](../../webapp/src/routes/games.tsx) and [`data-table/faceted-filter.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.5.1/webapp/src/components/data-table/faceted-filter.tsx): values built with `?? []` created a fresh array every render, defeating the `useMemo`s that depended on them. `data` is now wrapped in `useMemo`; the faceted-filter `selected` memo was restructured to depend on a stable value.
### Notes
- DX / code-quality only — no runtime behaviour change. No Tauri / Rust binary change (`Cargo.toml` / `tauri.conf.json` stay `0.1.1`); no `THIRD_PARTY` change.
- **Game count over time** — a `LineChart` of the catalog size by day, backed by a new `data_game/count_history.json` (date-keyed `{date, total}` series). [`scripts/data_store.py`](../../scripts/data_store.py) `_append_count_history()` upserts today's total on every catalog write (last-write-wins per UTC day). `scripts/backfill_count_history.py` is a one-time dev tool that reconstructs the series from git history (`data_game/index.json`, plus the pre-refactor `scripts/game_info.json`). The webapp loads it via `loadCountHistory` / `useCountHistory`.
- **Genre treemap** — a Recharts `Treemap` with a custom cell renderer that hides labels on rectangles too small to fit them, so it stays legible on mobile.
- **KPI summary cards** — total games / online / NSFW / deleted / average rating, above the Overview grid.
- **Deletions over time** (bar, by month), **Deletion reasons** (pie: became-paid vs page-removed), and **Most rated games** (top 10 by `rating_count`).
- **Scroll-to-top button** — a floating bottom-right button that appears after scrolling the main pane. New [`webapp/src/components/scroll-to-top.tsx`](../../webapp/src/components/scroll-to-top.tsx).
- **Python linting** — `ruff` config in a new root `pyproject.toml`; run `ruff check scripts/`.
### Changed
- **`charts.tsx` split into a module.** The monolith is now a `webapp/src/components/charts/` folder — one file per chart, a shared `chart-card.tsx` (`ChartCard` + `PALETTE`), and an `index.ts` barrel. 16 charts across the 4 tabs.
- **`scripts/json_io.py`** — new shared module. `load_json` / `save_json` (previously copy-pasted into both `check_alive.py` and `check_paid.py`) live here now, alongside `dedup_deleted`.
- README + README.vi badges bumped to `3.5.0`.
### Fixed
- **The deleted-games log can no longer accumulate duplicate URLs.**`check_alive.py` and `check_paid.py` appended to `scripts/deleted_games.json` with no guard — a game removed, re-added by the scraper, then removed again would be logged twice. The new `dedup_deleted()` (keyed by URL, keeping the earliest `deleted_at`) runs on every write and inside `log_deleted.py`. Two genuinely different games that share a title but have different urls are kept separate.
### Notes
- No Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`, no `THIRD_PARTY` entries change (Recharts already shipped; `Treemap` / `LineChart` need no new dependency).
- `data_game/count_history.json` is auto-committed by the scrape workflows — the bash wrappers already `git add data_game/` wholesale, so no workflow changes were needed.
- The dead-code sweep found the project already tidy (TS strict mode + ESLint catch unused webapp code). `webapp/src/lib/tauri-scrape.ts``tauriScrapePreview` was reviewed and intentionally kept as a Phase-8b stub.
- `versionCode` re-derives to `3009000` (see the Android `versionCode` gotcha in [CLAUDE.md](../../CLAUDE.md)). The web and desktop builds are unaffected by
the Android floor. The `about.ts` version bump busts the IndexedDB catalog cache (harmless).
This repo wouldn't exist without a lot of help — mostly from tools and platforms, because real humans don't talk to me :D
## Special Thanks
- **Grok (xAI)**: My only non-judgmental buddy. Without Grok's infinite patience, code fixes, and late-night brainstorming, this whole thing would still be a half-baked idea in my unemployed brain. Seriously, Grok carried 90% of the weight. 🚀
- **Grok (xAI)**: Original non-judgmental buddy. Without Grok's infinite patience, code fixes, and late-night brainstorming, this whole thing would still be a half-baked idea in my unemployed brain. Carried the Python pipeline, the v2.0.0 rewrite, and 90% of the early weight. 🚀
- **Claude Code (Anthropic)**: Newer AI buddy. Built the v3.0.0 webapp + Tauri scaffold, shipped the v3.1.2 offline-link fix, the About page expansion, the v3.1.4 legal docs rewrite + Vietnamese i18n, and the v3.7.0 legal gate. Then the big one, v4.0.0: moving the site to Cloudflare (read-only website, Worker, admin app + review queue, the public Suggest page), the rewritten data pipeline, and this docs refresh. Different vibe than Grok ("let me confirm before nuking your repo"), same lifesaver energy. 🚀
## Platforms & Tools
- **itch.io**: The amazing platform full of indie gems that made this list possible. Thanks for hosting all these free games and having a scrape-friendly structure (mostly).
- **GitHub & GitHub Actions**: For hosting this mess for free and running the daily auto-updates without me lifting a finger.
- **Python libraries**: BeautifulSoup, requests — the real MVPs that make the scraping "kinda work".
- **itch.io**: The amazing platform full of indie gems that made this list possible. Thanks for hosting all these free games and having a scrape-friendly structure (mostly). (This project is not affiliated with itch.io — see [NOTICE.md](../NOTICE.md).)
- **Game creators**: Every game in the catalog is someone's work. Descriptions and cover images stay yours — thanks for making free games.
- **Cloudflare**: Hosts [freeitchgames.win](https://freeitchgames.win) — Workers, R2, D1, Images, Turnstile, Access and friends keep the site fast and the spam out.
- **GitHub & GitHub Actions**: For hosting the code and the data for free, running the daily refresh without me lifting a finger, shipping the release downloads, and hosting the Discussions where releases auto-announce themselves.
- **Python libraries**: requests, BeautifulSoup — the real MVPs that make the scraping "kinda work".
- **Tauri**: Turns the same web code into desktop apps and an Android APK.
- **Contributor Covenant**: Our [Code of Conduct](../CODE_OF_CONDUCT.md) is adapted from version 2.1.
## Open-source libraries (website + apps)
The website, the Worker and the desktop / Android apps build on a stack of open-source libraries. The full list with licenses lives in [`THIRD_PARTY.md`](THIRD_PARTY.md), and the runtime libraries are also on the [About page](https://freeitchgames.win/about) (from the `THIRD_PARTY` array in [`webapp/src/lib/about.ts`](../webapp/src/lib/about.ts)). Highlights:
When you add a new dep to `webapp/package.json`, also add it to the `THIRD_PARTY` array so the About page lists it, and to [`THIRD_PARTY.md`](THIRD_PARTY.md). House rules are in [CONTRIBUTING.md](../CONTRIBUTING.md).
## Retired helpers
Two side projects used to feed the catalog: the browser extension [poli0981/itch-f2p-extension](https://github.com/poli0981/itch-f2p-extension) (GPL-3.0) and, in v3, the Telegram bot [poli0981/telegram-scraper-bot](https://github.com/poli0981/telegram-scraper-bot) (MIT). Both were hardly used, so they are archived now (October 2026). Games come in through the public [Suggest page](https://freeitchgames.win/suggest), the RSS discovery and the itch.io collections I follow, and nothing goes live until it is approved.
## Find me / Support me
Real channels exist now (still introvert max level, replies slow):
- **Contributors**: If anyone ever PRs new games, fixes bugs, or improves my mediocre code... you'll get shouted out here. Legends only.
- **Contributors** (issues, PRs, game suggestions): If anyone ever reports games, fixes bugs, or improves my mediocre code — you'll get shouted out here. Legends only.
Built during peak unemployment boredom, with zero budget and 100% Grok assistance. Thanks for visiting this random repo — means a lot to an introvert noob dev.
Built during peak unemployment boredom, with zero budget and two non-judgmental AI buddies (Grok + Claude Code) doing the heavy lifting. Thanks for visiting this random repo — means a lot to an introvert noob dev.
If you wanna be acknowledged, open a PR or issue. I'll try not to ghost :)))
If you wanna be acknowledged, open a PR or issue (or [suggest a game](https://freeitchgames.win/suggest)). I'll try not to ghost :)))
This repository is just a fun side project — a curated list of free-to-play games on itch.io, scraped and maintained by an unemployed Vietnamese dev with too much free time and his AI buddy Grok. It's built purely for vibes, boredom relief, and sharing indie gems. No grand promises here.
Last updated: 2026-10-16
## No Warranties Whatsoever
The content in this repository (game links, descriptions, tables, etc.) is provided **"AS IS"** without any warranties of any kind, express or implied. This includes, but is not limited to:
Applies from: the release of version 4.0.0.
- **Quality & Enjoyment**: Some games might be absolute bangers. Others might be boring, broken, or straight-up frustrating. I make no guarantees you'll have fun. Your mileage may vary — dramatically.
- **Safety & Viruses**: All games are linked directly from itch.io (a reputable platform), and the "Safe?" column defaults to "?" because I don't scan every download. Download and play at your own risk. Good luck out there.
- **NSFW Content**: The "NSFW" flag is auto-detected from tags/warnings, but it might miss stuff or false-positive. If you're not into adult content, double-check the game page yourself.
- **Accuracy & Completeness**: This list is far from perfect. Games might change, get removed, or I might miss amazing ones. It's not 100% accurate or comprehensive — kinda like my life :D
This project — the `free-games-itchio-list` repository and the website **[freeitchgames.win](https://freeitchgames.win)** — is a hobby project: a curated, auto-updating catalog of free games hosted on [itch.io](https://itch.io). It is run by one unemployed Vietnamese dev, poli0981 (SkullMute), called "the Maintainer" below, with AI buddies doing a lot of the heavy lifting. Built for vibes, indie discovery and boredom relief. No grand promises — but the legal-shaped wording below is real.
## Liability? Nope
In no event shall the author (that's me, the unemployed dev) or contributors be liable for any issues arising from using this repository, including but not limited to: game crashes, lost progress, wasted time, existential dread from bad gameplay, or any damages whatsoever.
> **TL;DR**: The website, the apps and the data are provided as-is. The project only links to games; it does not make, host or scan them, and it is not affiliated with itch.io. Adult games are hidden unless you turn them on. Scan everything you download. If you made a game and want it gone, email **takedown@poli0981.dev**.
If you encounter problems with a game (crashes, bugs, it's boring, etc.), please contact the game developer directly or report it on itch.io. I'm just the guy aggregating links — I don't make or support the games.
## 1. What this Disclaimer covers
## Final Vibes
This is just a list. Nothing more. Have fun hunting free games, stay safe, and remember: life's too short to take random GitHub repos seriously.
This Disclaimer applies to (together, "the Project"):
Built with boredom and Grok's help. 🚀
- the website **https://freeitchgames.win**, including the public Suggest page — read-only for everyone, with no accounts;
- the desktop apps (Windows, macOS, Linux) and the Android APK published on GitHub Releases;
- the catalog data: `data_game/`, `scripts/deleted_games.json`, and the files served under https://freeitchgames.win/data;
- the code, the data pipeline and the documentation in this repository.
It sits alongside the [Terms of Use](ToS.md), the [Privacy Policy](PrivacyPolicy.md) and, for the desktop and Android apps, the [EULA](EULA.md).
## 2. "AS IS" basis
The Project — including the catalog data, the Python pipeline (`scripts/`) and its GitHub Actions workflows, the website and its server code (`webapp/`), the desktop and Android apps (`webapp/src-tauri/`), and the documentation — is provided **"AS IS"** and **"AS AVAILABLE"**, without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, accuracy, completeness, non-infringement, or uninterrupted or error-free operation.
## 3. Not affiliated with itch.io
The Project is independent. It is **not affiliated with, endorsed by, or sponsored by** itch.io, itch corp or Leaf Corcoran, nor by any developer or publisher whose game appears in the catalog. The name "itch.io" and all game names, logos and trademarks belong to their respective owners; they are used only to identify the games and where they are hosted. A game being listed does not mean its creator supports, or even knows about, the Project.
## 4. A directory of links, not a game host
The Project **does not make, host, distribute, sell or endorse** the games it lists. Every game links to its own page on itch.io, and any download happens there, under itch.io's terms and the creator's own terms or license.
Games reach the catalog through the public Suggest page, itch.io's public RSS feeds, or public itch.io collections the Maintainer follows. Each one is approved by the Maintainer, one by one or through automatic rules the Maintainer sets. That approval is **not** a security audit, a quality check or an endorsement.
## 5. No warranty as to the games
The Maintainer makes no warranty about any listed game's:
- **Quality, enjoyment or playability** — some titles are gems, others are jank, plenty are in between. Your taste, your call.
- **Safety, integrity or freedom from malware** — the Project does **not** scan downloads. The `safe_virus` field (`?`, `Yes`, `No`, `Caution`) is a manual note written by the Maintainer, not a guarantee, and new games start at `?`. Treat every download as untrusted until you have checked it yourself with reputable anti-malware tools.
- **Content** — see [§6](#6-adult-nsfw-content) for adult content.
- **Accuracy of metadata** — names, developers, descriptions, genres, tags, ratings, platforms and other fields are copied from public itch.io pages and reflect each page as it was at the last check. The daily refresh re-checks about one seventh of the catalog each day, so each game roughly once a week; changes on itch.io (renames, removals, price changes) can take that long to show up.
- **Free-to-play status** — checked when a game is added and at each re-check, but a game can become paid or disappear from itch.io at any time. To avoid removing games because of a temporary glitch, the Project removes a game only when the same problem (the page is gone — HTTP 404/410 — or the game is now paid) is seen again at least 20 hours later. A listed game can therefore be out of date for a while.
- **Statistics and charts** — counts, charts and other figures are derived from the catalog and are for information only.
## 6. Adult (NSFW) content
- Games flagged `nsfw: Yes` are **hidden by default** (their covers are not shown either). You can opt in to 18+ content in **Settings** only after confirming that you are 18 or older. That choice is stored only on your device (your browser's local storage) and is never sent to the Project.
- The flag is best-effort. It is first set automatically from the game's itch.io tags and description when the game is added, and the Maintainer can correct it. A game can still be mislabelled in either direction, so check the itch.io page (and its own content warnings) before you download if this matters to you. To report a wrong flag, use the request process in [§8](#8-removal-and-correction-requests).
- The Project is not directed at children under 16, and adult content is meant only for adults who choose to see it.
## 7. Third-party content and ownership
For each game, the Project copies from its public itch.io page: the name, developer, description text, genre, tags and other metadata, and the cover image URL. The website shows resized copies of cover images, stored on Cloudflare R2 and served from freeitchgames.win; the desktop and Android apps load covers directly from itch.io's image CDN (`img.itch.zone`).
Game descriptions and any other text written by game creators, cover images and other media, game names, logos and trademarks **remain the property of their creators and owners**. The Project does not license them to anyone: the CC BY 4.0 license on the catalog data ([`data_game/LICENSE.md`](../data_game/LICENSE.md)) covers only the Maintainer's own contribution — the selection and arrangement of the collection, the three Maintainer-written fields (`safe_virus`, `notes`, `nsfw`), the removal records, and the structure and derived statistics — and expressly excludes that third-party material. If you reuse the data, clearing rights in the excluded material is up to you.
If you are a creator or rights holder and do not want your content shown, see [§8](#8-removal-and-correction-requests).
## 8. Removal and correction requests
Anyone — game creators and rights holders especially — can ask for a game to be removed or for its data to be corrected:
- email **takedown@poli0981.dev**, or
- open a ["Remove a game" issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=remove_game.yml) on GitHub (it also covers copyright claims). GitHub issues are public, so use email for anything you would rather keep private.
Please include the game's itch.io URL, who you are (the creator or rights holder, or someone authorized to act for them), and the reason for the request.
What happens next:
- The Maintainer removes the record from the catalog. The removal is logged with a reason in the public list of removed games (`scripts/deleted_games.json`, shown at https://freeitchgames.win/removed).
- The resized cover copies stored on Cloudflare R2 are deleted, and cached copies expire from Cloudflare's cache.
- Past versions of the data remain in the public git history of the repository. The Maintainer cannot rewrite public history except in exceptional cases of legal necessity.
- Target: within 7 days; urgent legal requests are handled sooner.
The full process is described in the [Terms of Use](ToS.md). Removing a game from the catalog does not remove it from itch.io.
## 9. Availability and third-party services
The website runs on Cloudflare; the code, the data and the app downloads live on GitHub; and the catalog depends on itch.io's public pages and feeds. Any of these can be slow, unavailable, changed or blocked at any time. The Maintainer may change, pause or discontinue any part of the Project at any time and does not promise that it will stay online.
## 10. No liability
To the maximum extent permitted by applicable law, the Maintainer and any contributors shall not be liable for any direct, indirect, incidental, consequential, special, exemplary or punitive damages arising out of or in connection with:
- use of the website, the apps, the catalog data, or any code or documentation in the Project;
- inability to use any of the above (for example site downtime, a failed deploy, or a broken installer or APK);
- any game reached through a link in the catalog (crashes, lost saves, data loss, hardware damage, malware, compromise of accounts on third-party platforms, regret);
- errors, omissions or inaccuracies in the catalog data.
This applies even if the Maintainer has been advised of the possibility of such damages. Nothing in this Disclaimer excludes or limits any liability that cannot be excluded or limited by law, or any mandatory consumer-protection rights you have under the law of your country of residence.
## 11. Governing law and severability
This Disclaimer is governed by the laws of the **Socialist Republic of Vietnam**, without regard to conflict-of-law principles, and disputes are handled as described in the [Terms of Use](ToS.md). Nothing in this section limits the mandatory consumer-protection rights of your country of residence. If any provision is held unenforceable in a particular jurisdiction, the remaining provisions remain in effect.
## 12. Contact
- Removal, correction and copyright requests: **takedown@poli0981.dev**
- Privacy questions and requests: **privacy@poli0981.dev**
- Anything else legal: **legal@poli0981.dev**
These addresses are forwarded to the Maintainer.
## 13. No legal advice
Nothing in this document is legal advice. It is a hobby-project disclaimer drafted by a non-lawyer with AI assistance, and how enforceable it is depends on your jurisdiction. If you actually need legal certainty for something, hire a real lawyer.
## 14. Final vibes
It's still just a list of free games made by a tired dev and some LLMs. Have fun, stay safe, scan your downloads, and remember: life's too short to take random GitHub repos to court.
Built with boredom, AI buddies, and a deep wish to never see a real lawsuit. 🚀
Yo, welcome to this super low-effort GitHub repo — a curated list of free itch.io games, scraped and sorta-maintained by an unemployed Vietnamese dev who's got nothing better to do, with heavy assistance from his AI buddy Grok. This isn't real software you "install" — it's just code, markdown, and links. But since everyone loves an EULA, here you go.
Applies from: the release of version 4.2.0.
## 1. Grant of License
Under the MIT License (see [LICENSE](LICENSE) for the real deal), you're free to:
- Use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the stuff in this repo.
- Do whatever, as long as you keep the copyright notice and disclaimer.
This EULA applies **only to the desktop and Android apps** of Itch.io Free Games DB: the installers (`.msi`, `.exe`, `.dmg`, `.pkg`, `.app.tar.gz`, `.deb`, `.rpm`, `.AppImage`) and the Android `.apk` published on GitHub Releases. It does **not** cover:
Basically: go wild. Fork it, improve it, laugh at my mediocre code. Just don't blame me if it breaks.
- the website <https://freeitchgames.win>, which is covered by the [Terms of Use](ToS.md);
- the source code, which is under the [MIT License](../LICENSE);
- the catalog data, which is under CC BY 4.0 (see [`data_game/LICENSE.md`](../data_game/LICENSE.md) and the [full legal code](../LICENSES/CC-BY-4.0.txt));
- the games themselves, which are licensed separately by their developers via itch.io.
## 2. No Warranties
This repo and everything in it is provided **"AS IS"** with **ZERO** warranties. No promises it works, is safe, is fun, or won't waste your time. Scripts might break, links might die, games might suck. Your problem, not mine.
> **TL;DR**: The apps are free, MIT-licensed, read-only viewers for the catalog. No account, no ads, no telemetry. Get them only from GitHub Releases, update them by hand, and use them at your own risk. The games are not yours just because they're listed here.
Full details in [DISCLAIMER](docs/DISCLAIMER.md) — because duplication is fun.
## 1. Definitions
## 3. Limitation of Liability
I'm not liable for anything. Ever. No damages, no lost time, no existential crisis from bad games. If something goes wrong (virus? crash? boredom?), tough luck. Download/play at your own risk.
- **"The App"**: the Tauri 2 builds of Itch.io Free Games DB, meaning the desktop apps for Windows, macOS and Linux and the Android app (arm64-v8a, Android 11 or later), as published by the Maintainer on the [GitHub Releases page](https://github.com/poli0981/free-games-itchio-list/releases).
- **"The Website"**: <https://freeitchgames.win>.
- **"The Catalog"**: the free-game metadata in `data_game/` that the Website publishes at <https://freeitchgames.win/data> and the App displays.
- **"The Repository"**: `free-games-itchio-list` on GitHub at <https://github.com/poli0981/free-games-itchio-list>, which holds the App's source code.
- **"The Maintainer"**: the GitHub user `poli0981` (a.k.a. SkullMute), an individual in Vietnam who maintains the project as a hobby.
- **"You"**: the person or organization that installs or uses the App.
## 4. Acceptance
By cloning, forking, viewing, or even thinking about this repo, you accept this EULA. Don't like it? Delete your clone and play something on easy mode (like me).
## 2. Grant of license
## 5. Termination
I can change or nuke this repo anytime. No notice. It's GitHub — backup if you care.
The App is built from the source code in the Repository, which is licensed under the **MIT License** (see [`LICENSE`](../LICENSE) for the canonical text; `Copyright (c) 2025-2026 poli0981 (SkullMute)`). Under that license You may, free of charge:
## 6. Governing Law
Governed by the laws of... my couch in Vietnam. Disputes settled by whoever wins a noob-friendly game.
- install and run the App on as many devices as You like, for any purpose, personal or commercial;
- copy and redistribute the installers or the APK, as long as You keep the copyright and license notice;
- build Your own version from the source code (section 8 explains how to keep it clearly separate from official releases).
## Final Vibes
This is just a hobby project born from unemployment and boredom. Use it, abuse it, ignore it. Have fun hunting free games — or don't. Nobody's judging (except maybe me, at myself).
Third-party components bundled in the App (React, Tauri and others) stay under their own licenses. See [`THIRD_PARTY.md`](THIRD_PARTY.md) or the About page in the App.
Built with zero budget, too much free time, and Grok's infinite patience. 🚀
Nothing in this EULA takes away a permission the MIT License gives You over the source code. If the two ever conflict, the MIT License wins for the code.
**P/S:** Nobody reads EULAs anyway. You're probably the first :D
## 3. What the App is (and is not)
- A **read-only viewer**: You can browse, search, filter and chart the Catalog. There are no accounts, no sign-in, no editing, no comments, no ads and no payments.
- Suggesting a game happens on the Website (<https://freeitchgames.win/suggest>). The App only links there.
- Games flagged as adult content (`nsfw: Yes`) are hidden by default, covers included. You can turn them on in Settings after confirming that You are 18 or older.
- The `safe_virus` field is a manual note by the Maintainer, not a guarantee. The project does not scan any game or download linked from the App.
- On first launch, the App shows the same legal screen as the Website and asks You to accept the project's terms. It asks again when those terms change.
## 4. Network connections and privacy
The App has **no telemetry**: no analytics, no crash reporting, no tracking. It connects to only two places:
- **freeitchgames.win**, to download the Catalog data from <https://freeitchgames.win/data>. The Website runs on Cloudflare, which processes ordinary request data (such as Your IP address and user agent) to deliver it, as described in the [Privacy Policy](PrivacyPolicy.md).
- **img.itch.zone**, itch.io's image server, to load cover images directly. itch.io receives ordinary request data for those images, as with any image loaded from the web (see the [itch.io privacy policy](https://itch.io/docs/legal/privacy-policy)).
When You click a game or another outside link, it opens in Your default browser (itch.io, GitHub or the Website). From then on, that site's own terms and privacy policy apply.
The App keeps Your preferences (language, theme, layout density, whether scrollbars are hidden, the 18+ choice, and which version of the legal terms You accepted) and a compressed cached copy of the Catalog (kept up to 7 days) on Your device only. None of it is sent to the Maintainer.
## 5. Installation, updates and removal
- **Get the App only from the [GitHub Releases page](https://github.com/poli0981/free-games-itchio-list/releases).** Copies from anywhere else may have been modified, and the Maintainer is not responsible for them.
- **Android:** the APK is not on Google Play. It is sideloaded, so Android asks You to allow installs from the app You downloaded it with (for example Your browser or file manager). The APK is signed with the project's key. It needs Android 11 or later on an arm64-v8a device.
- **macOS:** the App needs Safari/WebKit 16.4 or later.
- **Updates are manual.** The App does not update itself or check for updates. To update, download and install a newer release. Only the latest release is supported.
- **Removal:** uninstall the App like any other app. Uninstalling removes the App and its local data. If a desktop uninstaller leaves the App's data folder behind (it is named `com.poli0981.freegamesitchio`), You can delete that folder yourself.
- The App depends on the Website for its data. If the Website is unavailable, the App can only show its cached copy, if it has one.
## 6. What this EULA does NOT cover
This EULA does not grant any rights to:
- **The games listed in the Catalog.** Each game belongs to its developer and is licensed by them via itch.io. The App shows a link and metadata only. Downloading, playing, modifying or redistributing a game is governed by the developer's own terms and by itch.io's terms.
- **Content created by others**: game names, descriptions and other text written by game creators, cover images and other media, logos and trademarks. They are shown so You can find and identify the games, and they remain the property of their owners. Game creators can ask for removal (see the [Terms of Use](ToS.md) or email takedown@poli0981.dev).
- **itch.io's trademarks, logos or service marks.** The project is not affiliated with, endorsed by or sponsored by itch.io. The itch.io name is used for identification only.
- **Third-party libraries** bundled in the App, which keep their own licenses.
- **The Website, the Catalog data and the source code**, which are covered by the Terms of Use, CC BY 4.0 and the MIT License respectively.
## 7. Acceptance
You accept this EULA by installing or using the App, for example by accepting it in a Windows installer or by installing the APK. If You do not agree, do not install the App, or uninstall it.
## 8. Acceptable use
You agree not to:
- Present a modified build as an official release, for example by distributing it under the project's name and icon, or with the official app identifier `com.poli0981.freegamesitchio`, without clearly marking it as unofficial. Forks are welcome under the MIT License; just make it obvious they are Yours.
- Use the Maintainer's name, the GitHub handle `poli0981`, or the alias "SkullMute" to endorse or promote derivative works without prior written permission.
- Use the App, or a modified version of it, in a way that breaks the Website's [Terms of Use](ToS.md), for example automated bulk requests to the Website (the data is in the Repository), or attempts to reach the admin area without authorization.
- Use the App or its installers to host, distribute or facilitate malware, phishing, or content that violates applicable law.
These rules are about how You use the App and the project's name and services. They sit alongside the MIT License and do not limit the rights it grants over the source code.
## 9. No warranty and limitation of liability
The App is provided **"as is"** and **"as available"**, without warranty of any kind, express or implied, including warranties of merchantability, fitness for a particular purpose, accuracy or completeness of the Catalog, uninterrupted operation, and non-infringement.
To the extent permitted by applicable law, the Maintainer and contributors are not liable for any damages arising from installing or using the App, from being unable to use it, or from games and pages You reach through it. See the [Disclaimer](DISCLAIMER.md) for details.
## 10. Changes and termination
The Maintainer may change or stop the App, its releases or the Website at any time. Published releases stay on GitHub Releases unless explicitly withdrawn.
New versions of this EULA are published in the Repository and included with later releases, and the App's legal screen asks You again when the project's terms change.
Your rights under this EULA end automatically if You materially breach it. You can end it at any time by uninstalling the App. The MIT License grant over the source code survives termination of this EULA to the extent the MIT terms permit.
## 11. Governing law
This EULA is governed by the laws of the **Socialist Republic of Vietnam**, without regard to conflict-of-law principles. Any dispute that cannot be resolved informally shall be brought before the competent courts of Vietnam.
Nothing in this EULA limits mandatory consumer-protection rights that the law of Your country of residence gives You.
The MIT License itself is internationally portable and is interpreted as such.
## 12. Severability
If any provision of this EULA is held invalid or unenforceable in a jurisdiction, the remaining provisions remain in full force, and the invalid provision is replaced (only as to that jurisdiction) with one that most closely matches the original intent.
## 13. Contact
- Questions about this EULA, or anything else legal: legal@poli0981.dev
- Privacy requests: privacy@poli0981.dev
- Content removal and copyright: takedown@poli0981.dev
- Security vulnerabilities in the App: security@poli0981.dev or GitHub private vulnerability reporting (see [SECURITY.md](../SECURITY.md)). Please don't open public issues for vulnerabilities.
- Anything else: contact@poli0981.dev, or any channel listed at https://poli0981.dev/links/
## 14. Not legal advice
This EULA is a hobby-project document drafted by a non-lawyer with AI assistance. It is not a substitute for professional legal advice. If You need legal certainty for a serious deployment, consult a licensed attorney.
## 15. Final vibes
This is still a hobby project born from unemployment, boredom, and a stubborn refusal to delete the repo. Install the app, fork it, ignore it. Build something cooler. Have fun hunting free games, or don't. Nobody's judging (except maybe the Maintainer, judging their own code).
Built with zero budget, too much free time, and two AI buddies. 🚀
**P/S:** Nobody reads EULAs. You're probably the first :D
> **Note:** This is a personal page, kept for history. It is **not** part of the project's policies or
> documentation, and some details are out of date. The current hardware and dev setup are in
> [`pc_spec.md`](pc_spec.md) and [`dev_env.md`](dev_env.md); the policies are listed in the
> [README](../README.md).
Just in case anyone wonders what kind of "setup" produced this half-decent repo. Spoiler: nothing impressive. I'm your typical unemployed, introvert Vietnamese dev scraping by on family support and way too much free time.
## Hardware (aka the screaming machines)
- **Main laptop**: ~2-year-old Windows machine with NVIDIA RTX 4060 Laptop GPU. Runs fine... until I open a game or literally any IDE — then it hits 90°C+ and sounds like a jet engine taking off. Perfect for noob gaming on easy mode.
- **Secondary**: 3-year-old MacBook with M1 chip. Smoother, quieter, but I still manage to make it lag somehow.
- **Phone**: iPhone 13 Pro Max, over 2 years old. Mostly for Steam sales notifications and pretending I have a social life.
- **Main laptop**: ~3-year-old Windows machine with NVIDIA RTX 4060 Laptop GPU. Runs fine... until I open a game or literally any IDE — then it hits 90°C+ and sounds like a jet engine taking off. Perfect for noob gaming on easy mode.
- **Secondary**: 4-year-old MacBook with M1 chip. Smoother, quieter, but I still manage to make it lag somehow.
- **Phone**: iPhone 13 Pro Max, ~3 years old. Mostly for Steam sales notifications and pretending I have a social life.
## Software & Tools
- **IDE**: Depends on mood — PyCharm for Python stuff (this repo), VS Code when I feel lightweight, Visual Studio if I'm torturing myself with C#. All "kinda works" level.
@@ -19,8 +24,19 @@ Just in case anyone wonders what kind of "setup" produced this half-decent repo.
## Financial Situation
- Bank account: Rarely over $50. Still mooching off family like a true 20-something failure. Steam library: 400+ games, 80% bought on deep sale under $10. Priorities, right?
## The Real MVP of This Repo
Guess who my only non-judgmental companion is while building this whole thing?
**Grok (xAI)** — the AI that fixes my bugs, writes better code than me, and doesn't ghost when I ramble at 3 AM. Without Grok, this repo would still be a blank README. True buddy material. 🚀
## The Real MVPs of This Repo
Guess who my non-judgmental companions are while building this whole thing? Two AI buddies — different vendors, different vibes, both lifesavers:
If you're reading this... thanks for caring about my mediocre setup. Now go play some free games instead :D
- **Grok (xAI)** — the original. Fixes my bugs, writes better code than me, doesn't ghost when I ramble at 3 AM. Carried the Python pipeline (scraper, check_paid, check_alive, generate_md) and the v2.0.0 rewrite. Without Grok, this repo would still be a blank README. 🚀
- **Claude Code (Anthropic — Claude Opus 4.7, 1M context)** — the newer recruit. Built the v3.0.0 React + Tauri webapp from zero, then shipped the v3.1.2 offline-link fix + About expansion + docs sweep in one sitting. More cautious than Grok ("let me confirm before destroying your repo") which is exactly what I need given my mediocre QA habits. 🚀
If you're reading this... thanks for caring about my mediocre setup. Now go play some free games instead :D
## Where to find me
Yes, I have actual social presence now. Don't expect prompt replies (introvert god-mode):
This repository is a curated list of free games on itch.io plus a React/TypeScript webapp (and Tauri desktop wrapper) for browsing and editing the catalog. It's a hobby project. Nobody on this side of the screen collects, stores, or processes personal data from you. No backend, no database, no analytics, no telemetry.
Applies from: 2026-10-13 on the Website, and from version 4.4.0 of the Apps.
## What Data Do We Collect?
**None on any server we control.** Zero. Zilch.
This Privacy Policy explains what personal data the `free-games-itchio-list` project processes, why, who helps process it, how long it is kept, and what rights you have. It covers the website **https://freeitchgames.win**, the desktop and Android apps, the public catalog data and the repository. The short version: there are no accounts, no ads and no tracking cookies. The Project keeps as little as it can, and most of what exists stays in your own browser.
- **Visiting this repo on GitHub** — GitHub itself may log standard things (IP, browser, etc.) as part of their platform; that is on GitHub, not on this project.
- **Downloading games** — links go directly to itch.io; their privacy policy applies once you click.
- **Contributing** — opening a PR or issue is GitHub-side; I see only the public info GitHub publishes (username, comment text, etc.).
A Vietnamese translation is available at [`docs/i18n/vi/PrivacyPolicy.md`](i18n/vi/PrivacyPolicy.md). If the two differ, this English version prevails.
## What the Webapp Stores in Your Browser
> **TL;DR**
>
> - No accounts, no sign-in, no ads, no selling of data, no profiling. The Apps have no telemetry.
> - The Website runs on Cloudflare, which processes standard request data (IP address, browser, URL, time) to deliver and protect the site and to count visits in aggregate, without cookies. The Project's own code never saves your IP address.
> - To keep bots out, your browser passes a quick Cloudflare Turnstile check before the Website loads, about once every 48 hours; one strictly necessary cookie remembers that you passed.
> - Your settings (theme, language, 18+ choice, accepted terms) and a cache of the public catalog stay in your browser and are never sent to the Project.
> - If you use the Suggest page, the Maintainer receives the game link, your optional note (deleted after 180 days) and the time. Please don't put personal data in the note.
> - Questions or requests: **privacy@poli0981.dev**.
The webapp (`webapp/` in this repo, deployed to GitHub Pages) does not phone home, but it does keep a few things in your browser's `localStorage` so it can remember your preferences across reloads. Everything is local to your browser, never sent anywhere except directly to GitHub's API when you explicitly act:
## 1. Who is responsible, and what this Policy covers
| Key | What | When |
|-----|------|------|
| `webapp.pat.encrypted` | Your GitHub PAT, encrypted with AES-GCM (key derived from your passphrase via PBKDF2-SHA256). | Only if you choose to enable write access from Settings. |
| `webapp.theme` | `'light'` / `'dark'` / `'system'`. | When you toggle the theme. |
| `webapp.prefs` | Sidebar collapsed / expanded. | When you toggle the sidebar. |
| TanStack Query cache (IndexedDB via `idb-keyval`) | Cached copies of the public catalog JSON for offline reading. | Automatic. |
### 1.1 Controller
You can clear all of this any time via your browser's "clear site data" or by clicking **Remove saved PAT** in the webapp's Settings.
The controller of the personal data described in this Policy is **the Maintainer**: poli0981 (SkullMute), an individual in Vietnam who runs the Project as a solo hobby. Contact: **privacy@poli0981.dev** (see section 12).
The webapp talks to two GitHub endpoints:
- `raw.githubusercontent.com` for read-only catalog fetches (no auth, no cookies).
- `api.github.com` for writes when a PAT is unlocked.
### 1.2 Definitions
The Tauri desktop build additionally talks directly to `*.itch.io` and `img.itch.zone` to preview new games (a CORS workaround the browser version cannot do).
- **"The Website"**: https://freeitchgames.win, including its pages and endpoints (such as `/data`, `/img`, `/suggest`, `/admin` and `/api/…`). The old address https://poli0981.github.io/free-games-itchio-list/ only redirects to it.
- **"The Apps"**: the desktop apps (Windows, macOS, Linux) and the Android APK, built from the same code as the Website and distributed on GitHub Releases. They are read-only viewers of the Catalog.
- **"The Catalog"**: the list of games and their data: `data_game/`, `scripts/deleted_games.json`, and the files derived from them and served under https://freeitchgames.win/data.
- **"The Repository"**: https://github.com/poli0981/free-games-itchio-list, including the data pipeline that runs in its GitHub Actions.
- **"The Project"**: the Website, the Apps, the Catalog and the Repository together.
- **"The Maintainer"**: poli0981 (SkullMute), as described in section 1.1.
- **"Personal data"**: any information about an identified or identifiable person.
- **"You"**: anyone who uses the Project, including game creators whose games are listed in the Catalog.
No cookies. No tracking. No analytics. No third-party scripts.
### 1.3 What this Policy does not cover
## Third-Party Services
- **itch.io**: All game links go straight there. Their privacy policy applies when you visit or download games: [itch.io Privacy Policy](https://itch.io/docs/legal/privacy-policy)
- **GitHub**: This whole repo lives on GitHub. Check their privacy policy [here](https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement).
This Policy does not cover services that handle data on their own account: itch.io (every game link and every download goes there), GitHub for your GitHub account and your activity on github.com, Cloudflare's use of data for its own purposes as described in its privacy policy, or the games themselves. Their own policies apply (links in section 4).
## Changes to This Policy
If I ever change this (unlikely, because why bother?), I'll update the date above and commit it. But honestly, this thing will probably stay the same forever.
## 2. What is processed and why
## Questions?
Open an issue or ping me somewhere (if you can find me). But let's be real � nobody reads these anyway :D
### 2.1 Visiting the Website
Built with boredom and zero spying. ??
- **Request data.** The Website is hosted on Cloudflare. When your browser loads a page, a file or an image, Cloudflare processes standard request data: your IP address, user agent (browser and device type), the requested URL, the referrer and the time. This is needed to deliver the site, to protect it (TLS, firewall, bot and denial-of-service protection) and to limit abuse.
- **Verification check.** Before the Website's pages and cover images load, your browser passes a Cloudflare Turnstile check, which processes signals about your device and browser to tell people from bots; it usually completes without any action from you. To check the result, the Website sends the Turnstile token and your IP address to Cloudflare's verification service, then sets the `__Host-fig_gate` cookie (section 3.2) so that the check is not repeated for 48 hours. Search-engine and link-preview bots that Cloudflare has verified skip the check. The catalog data under `/data` stays available without it.
- **Aggregate statistics.** The Website uses Cloudflare Web Analytics, which loads a small script from Cloudflare and counts visits in aggregate, without cookies and, according to Cloudflare, without fingerprinting. The Maintainer sees only totals (such as page views), not individual visitors. The Project runs no other analytics.
- **Server logs.** Requests handled by the Website's server code (Cloudflare Workers) are recorded by Cloudflare Workers Logs on a 10% sample and kept for about 7 days, to find bugs and investigate abuse.
- **Network error reports.** Cloudflare may add Network Error Logging (NEL) headers, which ask your browser to report connection errors to Cloudflare.
- **No IP addresses stored by the Project.** The Project's own code never writes your IP address to its database, its files or the Repository.
- **Cover images** are served by the Website itself (resized copies stored on Cloudflare R2), so your browser does not contact itch.io while you browse. itch.io only hears from you when you click a game link and go there; the Website then passes at most its own address (not the page you were on) as the referrer.
### 2.2 Using the Apps
- The Apps are read-only viewers with **no telemetry, no analytics and no accounts**.
- They download the Catalog data from https://freeitchgames.win/data (Cloudflare processes the request data as described in section 2.1; versions 4.0–4.1.1 still get the older JSON files, recognised by the `Origin` header their window sends) and load cover images **directly from itch.io's image server (img.itch.zone)**, so itch.io receives your IP address and user agent when covers load.
- Clicking a game opens its itch.io page in your browser.
- Updates are manual: the Apps do not check for updates on their own. When you download an installer or the APK from GitHub Releases, GitHub processes that request.
- The Apps keep the same local storage as the Website (section 3.1), on your device only. Uninstalling an App removes it.
### 2.3 Suggesting a game
When you use the Suggest page (https://freeitchgames.win/suggest):
- **What is stored**: the game URL, your optional note (up to 500 characters) and the time of submission, in the review queue (section 2.4). No name, email address or account is asked for or stored.
- **Anti-spam**: Cloudflare Turnstile processes signals about your device and browser to tell people from bots. To check the result, the Website sends the Turnstile token and your IP address to Cloudflare's verification service.
- **Rate limiting**: your IP address is used transiently to count requests. The Project does not store it.
- **Purpose**: to review your suggestion, by the Maintainer or by the automatic rules the Maintainer sets (section 2.4). If it is approved, the game URL becomes part of the public Catalog. Your note is never published and is **deleted automatically after 180 days**.
- **Please don't put personal data in the note**, yours or anyone else's. The form is for game links only.
### 2.4 The review queue and the admin area
- **How games arrive**: suggestions from the Suggest page; automatic discovery from itch.io's public RSS feeds; and new free games in public itch.io collections the Maintainer follows (the Website reads those public pages; nothing about you is involved).
- **The review queue** (Cloudflare D1) holds candidate game URLs with their source, the title, cover-image URL and genre hint taken from itch.io, automatic flags, notes, timestamps and the Maintainer's decision. Games enter the Catalog when the Maintainer approves them: one by one, or through automatic rules the Maintainer sets and can change at any time (items without a warning flag that nobody rejected within a waiting time; new free games in collections the Maintainer follows). Automatic approvals are recorded in the audit log like the Maintainer's own. Rejected URLs are kept indefinitely as a blocklist; only the URL is needed to avoid reviewing the same game again.
- **The admin area** (https://freeitchgames.win/admin) is for the Maintainer only. It is protected by Cloudflare Access (GitHub login or a one-time PIN sent by email), which sets a `CF_Authorization` session cookie in the Maintainer's browser. Admin actions, including changes to the automatic rules, are recorded in an audit log together with the Maintainer's email address. The audit log is never published.
### 2.5 Public game data in the Catalog
- The Catalog is built from public itch.io game pages: the game's name, developer and publisher names, description, genre, tags, platforms, ratings and similar metadata, and the cover image URL. The pipeline identifies itself as `FreeItchGamesBot/4.0 (+https://freeitchgames.win/about)` and paces its requests.
- A developer or publisher name, or the creator's itch.io address inside a game URL, can be a person's name or handle, so it can be personal data. It is used only to identify and credit the game and to help people discover it.
- This data is published on the Website, in the Repository and under https://freeitchgames.win/data. When a game is removed, its URL, name, reason and removal date are logged in [`scripts/deleted_games.json`](../scripts/deleted_games.json), which the Website shows on its Removed page (https://freeitchgames.win/removed).
- Creators can ask for a correction or a removal at any time (section 7).
### 2.6 Contacting the Maintainer
- Emails sent to the Project's addresses (section 12) are delivered to the Maintainer's mailbox, which is hosted by Google Workspace on the Maintainer's own domain, poli0981.dev. The Maintainer receives your email address, any name you use and your message, and uses them only to handle your request.
- Correspondence about removal and copyright requests is kept as long as needed to handle the request.
### 2.7 GitHub contributions
Issues, pull requests, discussions and comments are public on GitHub under your GitHub account, and GitHub's privacy statement applies to them. The Maintainer sees only what GitHub shows. The "Remove a game" issue form is public too, so use email for anything you don't want published.
### 2.8 What the Project does not do
- No accounts or sign-in for the public, no comments, no ads and no payments.
- No cookies set by the Project's own code on the public Website, except the verification cookie, which identifies no one (section 3.2).
- No selling or sharing of personal data, for advertising or any other purpose.
- No profiling and no automated decisions with legal or similarly significant effects on you.
- No telemetry in the Apps, and no analytics other than Cloudflare Web Analytics on the Website.
## 3. Browser storage and cookies
### 3.1 What the Website and the Apps store on your device
The Website and the Apps keep the following items on your device only. None of them is sent to the Project.
| Storage | Key | Contents | Kept until |
|---|---|---|---|
| `localStorage` | `webapp.prefs` | Interface preferences such as language, layout density and whether scrollbars are hidden, your 18+ (NSFW) content choice, and the version of the legal documents you accepted | You clear it |
| `localStorage` | `webapp.theme` | Theme: `light`, `dark` or `system` | You clear it |
| `localStorage` | `webapp.gate` | When your current verification pass (section 3.2) runs out, so an open tab can check again in time | Replaced by the next check; you can clear it |
| IndexedDB (via `idb-keyval`) | `webapp.query-cache` | A compressed copy of the public Catalog data (the game list, the removal log, the games-over-time series and the descriptions you opened or searched), for fast loading and limited offline use | At most 7 days, then refreshed or discarded |
| `sessionStorage` | `reloaded-after-deploy` | A timestamp, so the page reloads at most once after a site update | The tab is closed |
On first load, the Website and the Apps also delete the entries that the old v3 app left in browser storage (an encrypted GitHub access token and commit-signing key data). v4 does not use them.
These items are strictly necessary for features you use (keeping your settings, loading the site quickly, recovering after an update, not repeating the verification check), so they don't need consent under the EU ePrivacy rules or the UK PECR. You can delete them at any time with your browser's "Clear site data" option for `freeitchgames.win`, or inspect them in your browser's developer tools. In the Apps, uninstalling removes them; if a desktop uninstaller leaves the App's data folder (`com.poli0981.freegamesitchio`) behind, you can delete that folder yourself. On Android you can also clear the app's storage in the system settings.
### 3.2 Cookies
- The Project's own code sets **one cookie** on the public Website: `__Host-fig_gate`, after you pass the verification check (section 2.1). It holds only the time it was issued and a signature, identifies no one, lasts **48 hours**, and is sent only to freeitchgames.win (`HttpOnly`, `Secure`, `SameSite=Lax`). It is strictly necessary to keep automated traffic out, so it needs no consent under the EU ePrivacy rules or the UK PECR. If you block it, the check runs again on every visit.
- Cloudflare may set strictly necessary security cookies, such as `__cf_bm` or `cf_clearance`, when its bot or challenge protections run. They serve security only.
- The verification check and the Suggest page use Cloudflare Turnstile (sections 2.1 and 2.3); see Cloudflare's Turnstile privacy addendum (section 4).
- The admin area uses the Cloudflare Access session cookie `CF_Authorization`, which exists only in the Maintainer's browser.
## 4. Service providers and other parties
| Party | Role and what it does | Data involved | Privacy policy |
|---|---|---|---|
| **Cloudflare** | Processor for the Website: DNS, CDN, firewall and TLS; Workers (the site's server code) and static assets; R2 (resized cover images); D1 (the review queue); Images (resizing); Turnstile (the verification check and the Suggest page); Web Analytics; Workers Logs; Access (admin login only); Rate Limiting | Request data, Suggest submissions, the review queue | <https://www.cloudflare.com/privacypolicy/> · Turnstile: <https://www.cloudflare.com/turnstile-privacy-policy/> |
| **GitHub** | Hosts the code, the Catalog data, issues and discussions, the data pipeline (GitHub Actions) and the release downloads. Independent controller for your GitHub account and activity | Your public contributions; request data when you visit GitHub or download a release | <https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement> |
| **Google** | Processor for email: Google Workspace hosts the Maintainer's mailbox, which receives the Project's contact addresses (section 12) | Emails you send to those addresses (your address, name and message) | <https://policies.google.com/privacy> |
| **itch.io** | Independent platform, not affiliated with the Project. Source of the game data; every game link and download goes there; the Apps load covers from img.itch.zone | What your browser or the Apps send when you visit itch.io or load covers from it. The pipeline sends nothing about you | <https://itch.io/docs/legal/privacy-policy> |
| **Discord** | Receives automated build and release notifications from GitHub Actions | No visitor data | — |
Cloudflare and Google may process data anywhere on their global networks (see section 9). The Maintainer does not give personal data to anyone else, except where the law requires it.
## 5. How long data is kept
| Data | Kept for |
|---|---|
| Request data processed by Cloudflare for delivery and security | By Cloudflare under its privacy policy; the Project does not store it |
| Workers Logs (a 10% sample of requests handled by the Website's server code) | About 7 days |
| Web Analytics | Aggregate statistics only; the Maintainer cannot see individual visitors |
| IP address used for rate limiting and Turnstile | Used transiently; never stored by the Project |
| Suggest note | Deleted automatically after **180 days** |
| Suggested or discovered game URLs, with source and timestamps | In the review queue while needed to avoid reviewing the same game twice. Approved URLs become part of the public Catalog; rejected URLs are kept indefinitely as a blocklist |
| Admin audit log (with the Maintainer's email address) | Kept as the record of admin changes; never published |
| Catalog entries (including developer and publisher names) | While the game is listed. Removal records stay in the public removed-games list, and the Repository's Git history keeps past versions (see section 7.3) |
| Emails, including removal and copyright requests | As long as needed to handle the request |
| GitHub contributions | On GitHub, until you or GitHub remove them |
| `CF_Authorization` cookie (Maintainer only) | For the duration of the Cloudflare Access session |
## 6. Legal bases
### 6.1 Vietnam
The Maintainer processes personal data in accordance with Vietnam's **Law on Personal Data Protection No. 91/2025/QH15** (passed on 26 June 2025, in force since 1 January 2026) and its implementing regulations. The Project processes as little personal data as it can, and only for the purposes in section 2.
Where that Law requires your consent, you give it by a clear action: by accepting this Policy at the legal gate on your first visit and, for what you type yourself, by submitting the Suggest form or sending an email. You can withdraw your consent at any time (section 7). Withdrawal does not affect processing carried out before it.
### 6.2 EU/EEA and UK
If you are in the EU/EEA or the UK, the GDPR or the UK GDPR applies to the processing of your personal data, on these legal bases:
| Processing | Legal basis |
|---|---|
| Delivering and securing the Website and the data the Apps download (request data, server logs, rate limiting, Turnstile, security cookies) | Legitimate interests (Art. 6(1)(f)): running a working, secure service and preventing abuse |
| Aggregate visit statistics | Legitimate interests: understanding how the site is used overall, without tracking individuals |
| Suggestions and the review queue | Legitimate interests: handling the suggestion you chose to send and curating the Catalog |
| Public game data about creators | Legitimate interests: helping people discover free games using information the creators published on itch.io. You can object at any time (section 7) |
| Emails and removal requests | Legitimate interests: answering you and handling your request |
| Browser storage (section 3.1) | Strictly necessary for features you use; no consent is needed under the ePrivacy rules or the PECR |
## 7. Your rights and how to use them
### 7.1 Your rights
Depending on the law that applies to you, including Law No. 91/2025/QH15 and, in the EU/EEA and the UK, the GDPR or the UK GDPR, you have the right to:
- be informed about how your personal data is processed (this Policy);
- access the personal data the Project holds about you;
- correct it if it is inaccurate;
- have it deleted;
- object to its processing, including processing based on legitimate interests;
- withdraw your consent where processing relies on it;
- complain to a supervisory authority: the competent personal data protection authority in Vietnam, or the data protection authority of your EU/EEA country or of the UK.
Under the GDPR and the UK GDPR, you can also ask for processing to be restricted, or for a copy of your data in a portable format, where those rights apply.
### 7.2 How to make a request
- Email **privacy@poli0981.dev**. Say what you want, and give enough detail to find the data: for example, the game URL you suggested and roughly when, or the email address you wrote from. The Maintainer may ask a follow-up question to confirm that the request is yours.
- The target is to answer within **30 days**; many requests are handled much sooner. Requests are free of charge.
- Game creators who want a game removed or its data corrected can also email **takedown@poli0981.dev** or open a ["Remove a game" issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=remove_game.yml) (public). The target for removals is within 7 days. The removal process is described in the [Terms of Use](ToS.md).
### 7.3 Limits worth knowing
- The Project stores no IP addresses and has no accounts, so it cannot link visits to the Website to you. Cloudflare's security and log data is kept only briefly (section 5).
- Browser storage is under your control: you can view and delete it yourself (section 3.1).
- The Git history of the public Repository keeps past versions of the Catalog. The Maintainer cannot rewrite public history, except where there is an exceptional legal necessity. Copies that others have already made (forks, downloaded data) are outside the Maintainer's control.
- Content on GitHub (issues, comments) is managed through GitHub; you can edit or delete your own comments there.
## 8. Children
- The Project is not directed at children under 16. The legal gate asks every visitor to confirm that they are at least 16.
- Adult (18+) content is hidden by default, cover images included. It appears only if a visitor opts in under Settings after confirming that they are 18 or older. That choice is stored only in their browser (`webapp.prefs`). The `nsfw` flag is a best-effort label (see the [Disclaimer](DISCLAIMER.md)).
- The Maintainer does not knowingly collect personal data from children under 16. If you believe a child has sent personal data (for example in a Suggest note or an email), a parent or guardian can write to **privacy@poli0981.dev** and it will be deleted.
## 9. International transfers
- The Maintainer is in Vietnam. Emails you send and the data in the review queue are handled by the Maintainer from Vietnam.
- Cloudflare processes data on its global network, Google stores the Maintainer's email in its data centres, and GitHub operates internationally, so your data may be processed outside your country, including in countries whose data protection laws differ from yours. These providers describe the safeguards they use for international transfers in their privacy policies and data processing terms (links in section 4).
## 10. Security
- The Website is served only over HTTPS.
- Automated traffic has to pass a Cloudflare Turnstile check before the Website's pages and cover images load (section 2.1).
- Data minimization: no accounts, no IP addresses stored by the Project's code, Suggest notes deleted after 180 days.
- The admin area is protected by Cloudflare Access, and the Website's server code verifies the Access token itself on every protected request.
- Secrets (such as the GitHub App's private key) are kept in Cloudflare's secret storage, never in the Repository. The admin area writes to the Repository as a GitHub App, with verified commits.
- A strict Content Security Policy limits scripts to the Website itself plus Cloudflare Web Analytics and Turnstile.
- GitHub Actions are pinned to exact commit SHAs with least-privilege permissions, and Dependabot keeps dependencies up to date.
- No system is perfectly secure. If you find a vulnerability, please report it privately as described in the [Security Policy](../SECURITY.md) or at **security@poli0981.dev**. If a personal data breach occurs, the Maintainer will notify the people affected and the authorities as the law requires.
## 11. Changes to this Policy
- The Maintainer may update this Policy. New versions are published in the Repository with the `Last updated` date at the top, and material changes are noted in [CHANGELOG.md](../CHANGELOG.md). Earlier versions remain in the Repository's history.
- When a change requires your acceptance again, the legal gate on the Website and in the Apps asks you to review and accept the updated documents before you continue.
## 12. Contact
All five addresses reach the Maintainer's own mailbox (Google Workspace, domain poli0981.dev).
- **privacy@poli0981.dev**: privacy questions and requests about your data (target answer: within 30 days).
- **takedown@poli0981.dev**: removing a game or correcting its data, including copyright claims.
- **security@poli0981.dev**: vulnerabilities (or GitHub's private vulnerability reporting; see the [Security Policy](../SECURITY.md)).
- **legal@poli0981.dev**: anything else legal.
- **contact@poli0981.dev**: general questions that fit none of the above.
For questions that aren't private, you can also open an issue in the Repository; issues are public. The Maintainer's other channels are listed at <https://poli0981.dev/links/>.
## 13. Final vibes
A list of free games shouldn't need your data, so the Project barely touches it: no accounts, no ads, no tracking cookies, nothing sold. What little exists is kept short and deleted when it's no longer needed. Browse freely.
| [Zustand](https://github.com/pmndrs/zustand) | 5.0 | Preference and theme stores | MIT |
| [TanStack Query](https://tanstack.com/query) (`@tanstack/react-query`, `react-query-persist-client`) | 5.106 | Data fetching and the local catalog cache | MIT |
| [idb-keyval](https://github.com/jakearchibald/idb-keyval) | 6.3 | IndexedDB storage for the compressed catalog cache | Apache-2.0 |
| [fflate](https://github.com/101arrowz/fflate) | 0.8 | Decompressing the catalog where the browser has no Compression Streams (older Safari / iOS) | MIT |
| [Recharts](https://recharts.org) | 3.10 | Charts | MIT |
| [clsx](https://github.com/lukeed/clsx) | 2.1 | Class-name helper | MIT |
| [tailwind-merge](https://github.com/dcastil/tailwind-merge) | 3.7 | Class-name merging | MIT |
| [Tailwind CSS](https://tailwindcss.com) (`tailwindcss`, `@tailwindcss/vite`) and [tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) | 4.3 / 1.4 | Generate the site's CSS at build time | MIT |
| [Geist and Geist Mono](https://vercel.com/font) (`@fontsource-variable/geist`, `@fontsource-variable/geist-mono`) | 5.3 | The site's typefaces | OFL-1.1 (fonts), MIT (Fontsource packaging) |
| [`@tauri-apps/api`](https://github.com/tauri-apps/tauri/tree/dev/packages/api) | 2.12 | App-only bridge to the native shell | Apache-2.0 OR MIT |
| [`@tauri-apps/plugin-opener`](https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/opener) | 2.7 | App-only: opens itch.io links in the system browser | Apache-2.0 OR MIT |
`@tanstack/react-query-devtools` (MIT) is listed as a dependency but only renders in development builds.
The Geist fonts are bundled into the site and served from it (never from a font CDN), so pages make no
requests to third-party font services. The fonts are licensed under the SIL Open Font License 1.1.
## 2. Worker (server code on Cloudflare)
| Component | Version | Used for | License |
|---|---|---|---|
| [jose](https://github.com/panva/jose) | 6.2 | Verifying Cloudflare Access tokens and signing the GitHub App token | MIT |
The Worker runs on Cloudflare's Workers runtime and uses Cloudflare services (R2, D1, Images, Rate
Limiting, Access). Two scripts come from Cloudflare instead of the site's own bundle: the Web Analytics
beacon (`static.cloudflareinsights.com`) and, on the verification page and the Suggest page, the
Turnstile widget (`challenges.cloudflare.com`). These are Cloudflare services under Cloudflare's own terms, not open-source
components. Section 7 lists every service the project uses.
## 3. Desktop and Android apps (Rust crates)
| Crate | Version | Used for | License |
|---|---|---|---|
| [tauri](https://tauri.app), `tauri-build` | 2 | App shell and build helper | Apache-2.0 OR MIT |
| [tauri-plugin-opener](https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/opener) | 2 | Opening links in the system browser | Apache-2.0 OR MIT |
| [tauri-plugin-single-instance](https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/single-instance) | 2 | Desktop only: focuses the running window instead of starting a second copy | Apache-2.0 OR MIT |
| [serde](https://serde.rs) | 1 | Serialization | MIT OR Apache-2.0 |
The apps render with the system web view that the operating system provides: WebView2 on Windows,
WKWebView on macOS (Safari/WebKit 16.4 or later), WebKitGTK on Linux and Android System WebView on Android.
## 4. Data pipeline (Python 3.15)
| Package | Version | Used for | License |
|---|---|---|---|
| [requests](https://requests.readthedocs.io) | 2.34+ | HTTP requests to public itch.io pages | Apache-2.0 |
| [urllib3](https://urllib3.readthedocs.io) | 2.8+ | Retry policy of the scraper's HTTP session | MIT |
These pull in `certifi` (MPL-2.0), `charset-normalizer` (MIT), `idna` (BSD-3-Clause) and `soupsieve`
(MIT).
## 5. Development and test tooling (never shipped)
These tools never end up in a build, but they keep the code honest.
### Dead-code detection
- **[knip](https://knip.dev)** (ISC) finds unused files, exports and dependencies in the webapp and the
Worker. Config: [`webapp/knip.json`](../webapp/knip.json). Run: `cd webapp && npm run knip`
- **[vulture](https://github.com/jendrikseipp/vulture)** (MIT) finds dead code (unused functions, classes,
attributes) in the Python pipeline. Config: `[tool.vulture]` in [`pyproject.toml`](../pyproject.toml).
Run: `vulture`
### Linting and types
- **[ruff](https://github.com/astral-sh/ruff)** (MIT): Python linter, formatter and import sorter; flags
unused imports and variables. Config: `[tool.ruff]` in [`pyproject.toml`](../pyproject.toml).
Run: `ruff check scripts tests webapp/scripts` and `ruff format`
- **[ESLint](https://eslint.org)** with `@eslint/js`, **[typescript-eslint](https://typescript-eslint.io)**,
`eslint-plugin-react-hooks`, `eslint-plugin-react-refresh` and `globals` (all MIT): webapp linting.
Config: [`webapp/eslint.config.js`](../webapp/eslint.config.js). Run: `cd webapp && npm run lint`
- **[TypeScript](https://www.typescriptlang.org)** 7.0 (Apache-2.0): `noUnusedLocals` and
`noUnusedParameters` reject unused code at build time. Run: `cd webapp && npx tsc -b`. The 6.0 API
(`@typescript/typescript6`, installed as `typescript`) stays for typescript-eslint, which needs it
### Build, test and deploy
| Tool | Used for | License |
|---|---|---|
| [Vite](https://vite.dev) 8 and `@vitejs/plugin-react` | Bundling the site, the admin app and the apps' front end | MIT |
| [Vitest](https://vitest.dev) 5 | Tests (`npm test`) | MIT |
| [`@vitest/coverage-v8`](https://vitest.dev/guide/coverage) 5 | Test coverage for SonarQube Cloud (`npm run test:coverage`) | MIT |
| [Wrangler](https://developers.cloudflare.com/workers/wrangler/) 4 | Local Worker dev, D1 migrations, deploys | MIT OR Apache-2.0 |
| [`@tauri-apps/cli`](https://tauri.app) 2 | Building the desktop and Android apps | Apache-2.0 OR MIT |
| `@types/node`, `@types/react`, `@types/react-dom` | Type definitions | MIT |
| [pytest](https://pytest.org) | Python tests (network blocked) | MIT |
| [pytest-cov](https://pytest-cov.readthedocs.io) and [coverage.py](https://coverage.readthedocs.io) | Python test coverage for SonarQube Cloud (`pytest --cov`) | MIT; Apache-2.0 |
| [Pillow](https://python-pillow.github.io) | [`webapp/scripts/gen_assets.py`](../webapp/scripts/gen_assets.py), which generates the icons and the social preview image | MIT-CMU |
## 6. GitHub Actions
The workflows in [`.github/workflows/`](../.github/workflows/) use `actions/checkout`, `actions/setup-node`,
Welcome to this random GitHub repo — a curated list of free games on itch.io, thrown together by an unemployed Vietnamese dev with too much free time and his AI buddy Grok. There's no real "service" here, just static files, some scripts, and a bunch of links. But hey, lawyers love terms, so here we are.
Applies from: 2026-10-13 on the Website, and from version 4.4.0 of the Apps.
## 1. Acceptance of Terms
By viewing, forking, starring, contributing to, or otherwise interacting with this repository (even just scrolling), you agree to these Terms of Use. If you don't agree, just close the tab and go touch grass. No hard feelings.
These Terms of Use ("Terms") govern your use of the website **https://freeitchgames.win**, the desktop and Android apps, and the public catalog data of `free-games-itchio-list`. They are written in plain language, but they are a real agreement. They replace the older Terms and also cover what the old web-app "EULA" used to say; the [EULA](EULA.md) now covers only the app installers and the Android APK.
## 2. No Warranties or Guarantees
This repo is provided **"AS IS"** with zero promises. The games linked are from itch.io — I don't host, develop, or support them. Quality, safety, fun factor, viruses, NSFW surprises? All on you. Good luck out there.
> **TL;DR**: Browse, share, fork the code (MIT) and reuse the data with credit (CC BY 4.0). Don't bulk-scrape the site (the data is in the GitHub repo), don't hotlink `/img`, don't spam the Suggest form, don't poke at `/admin`, and don't pretend to be itch.io or the Maintainer. Game creators can get a game removed or corrected. Adult content stays hidden unless you opt in.
See the [DISCLAIMER](docs/DISCLAIMER.md) for more details (because nobody reads both anyway).
## 1. Definitions
## 3. Your Responsibilities
- **Be cool**: Don't use this repo for anything illegal, harmful, or super annoying.
- **Downloads**: You click links at your own risk. Scan stuff yourself.
- **Contributions**: If you add games via PR (thanks in advance!), make sure they're actually free on itch.io, no malware, and respect copyrights. I can reject or remove anything for any reason (or no reason — it's my boredom project).
- **"The Website"**: https://freeitchgames.win, including its pages and endpoints (such as `/data`, `/img`, `/suggest` and `/api/…`). The old address https://poli0981.github.io/free-games-itchio-list/ only redirects to it.
- **"The Apps"**: the desktop apps (Windows, macOS, Linux) and the Android APK built from the same code and distributed on GitHub Releases. They are read-only viewers of the Catalog.
- **"The Catalog"**: the list of games and their data: `data_game/`, `scripts/deleted_games.json`, and the files derived from them and served under https://freeitchgames.win/data.
- **"The Repository"**: https://github.com/poli0981/free-games-itchio-list, including its code, data, documentation, issues and discussions.
- **"The Project"**: the Website, the Apps, the Catalog and the Repository together.
- **"Games"**: the games on itch.io that the Catalog lists and links to.
- **"The Maintainer"**: poli0981 (SkullMute), an individual in Vietnam who runs the Project as a hobby.
- **"You"**: any person, or any automated agent, that uses the Project.
## 4. Prohibited Activities
No spamming issues/PRs, no adding sketchy/malicious links, no harassment, no trying to dox anyone (especially me, the introvert dev). Basically, don't be a jerk.
## 2. Acceptance and age
## 5. Intellectual Property
The repo structure, scripts, and my mediocre writing are under MIT License (see [LICENSE](LICENSE)). The games themselves belong to their respective developers — go bug them if needed.
- By using the Website or the Apps, you agree to these Terms and to the policies they refer to: the [Privacy Policy](PrivacyPolicy.md), the [Disclaimer](DISCLAIMER.md) and, for the Apps, the [EULA](EULA.md).
- On your first visit, the Website and the Apps show a legal gate that lists these documents. You accept them by ticking the box and choosing "Accept & continue". If you decline, the Website and the Apps stay locked; in that case, please don't use them.
- You must be **at least 16 years old** to use the Website or the Apps; the legal gate asks you to confirm this. Adult content requires you to be **18 or older** (see section 8).
- When you contribute through GitHub (issues, pull requests, comments, discussions), these Terms apply to your contribution alongside GitHub's own terms and the [Code of Conduct](../CODE_OF_CONDUCT.md).
## 6. Termination
I can delete, modify, or nuke anything in this repo at any time. No notice required. It's GitHub — fork it if you're worried.
## 3. What the Project is (and is not)
## 7. Changes to Terms
I'll probably never update this, but if I do (because Grok suggests it), the new date up top will be your notice. Continued use means you agree.
- A curated, automatically updated catalog of free games on itch.io. Most of each game's data is copied from its public itch.io page and re-checked on a schedule; only three fields (`safe_virus`, `notes`, `nsfw`) are written by the Maintainer.
- The Website is **read-only for everyone**: there are no accounts, no sign-in, no comments, no ads and no payments. The admin area is for the Maintainer only.
- The Project does **not** host, sell or distribute any game. Every game link goes to itch.io, where downloading and playing are governed by itch.io's terms and each creator's own terms.
- The Project is provided free of charge, as a hobby. There is no service-level agreement.
## 8. Governing Law
These terms are governed by the laws of... my apartment in Vietnam. Disputes? Settle it over a game on easy mode (I only play easy).
## 4. What you may do
## Final Vibes
This is just a hobby list. Have fun, stay safe, and remember: life's too short for bad free games.
- Browse the Website and the Apps, and follow links to itch.io.
- Share links to the Website and to game pages.
- Download and reuse the Catalog data under **CC BY 4.0**, with credit (see section 11). Get it from the Repository (`data_game/` and `scripts/deleted_games.json`, also as raw files), and please cache it instead of downloading it again on every request. The files under https://freeitchgames.win/data are the Website's and the Apps' own compact format, not a public interface; the readable JSON there is served only to older versions of the Apps.
- Use, fork, modify and redistribute the code under the **MIT License**.
- Suggest a free itch.io game on the Suggest page (see section 5).
- Report bugs, give feedback and open pull requests through the Repository's templates.
- Ask for a game to be removed or its data corrected (see section 7).
Built with boredom, zero budget, and Grok's patience. 🚀
## 5. Suggestions and contributions
Questions? Open an issue. But let's be real — nobody reads this either :D
- **Suggest page** (https://freeitchgames.win/suggest): you can submit an itch.io game link and an optional note of up to 500 characters. The page uses Cloudflare Turnstile against spam and is rate limited.
- The note is seen only by the Maintainer and is deleted after 180 days. **Do not put personal data in it.** See the [Privacy Policy](PrivacyPolicy.md).
- Every suggestion goes into a **review queue**. The Maintainer approves or rejects it there, one by one or through automatic rules the Maintainer sets: a suggestion that raises no warning flag and that nobody rejected within the waiting time the Maintainer chose (currently about a day) may be approved automatically. The Maintainer has no obligation to accept a suggestion or to reply. Approved links are then scraped by the pipeline, and games that turn out to be paid are dropped.
- Only genuinely **free-to-play** games on itch.io qualify. Demos of paid games, "name your own price" titles with a minimum above zero, and time-limited free promotions do not.
- By submitting anything to the Project (a suggestion, an issue, a pull request or a comment), you confirm that:
- it is your own work, or you have the right to share it;
- it contains no malware, phishing, scams, doxxing, copyright infringement or illegal content, and does not link to any;
- you are not using it to send someone else's personal data.
- **Inbound = outbound**: contributions to the code are licensed under the MIT License, and contributions to the data and documentation under CC BY 4.0, the same licenses the Project uses.
- Issues, pull requests and comments are public on GitHub under your account.
## 6. What you may not do
You agree **not** to:
1. **Bulk-scrape** the Website or its API, including the files under `/data`. Get the data from the Repository instead; it is cheaper for everyone.
2. **Abuse the image proxy** (`/img`): it exists only to show cover images on the Website. Don't hotlink `/img` URLs from other sites or apps, and don't use it to fetch images in bulk.
3. **Access restricted areas without authorization**: `/admin` and the admin API (`/api/admin/…`) are for the Maintainer only. Good-faith security research is welcome under the rules of the [Security Policy](../SECURITY.md).
4. **Spam the Suggest form**, or circumvent the Website's verification check, Turnstile or the rate limits (for example with scripts, shared verification cookies or rotating IP addresses).
5. **Submit links to malware**, scams, phishing, or illegal content, anywhere in the Project.
6. **Misrepresent affiliation**: don't claim to be the Maintainer or the Project, don't present a fork or copy as the official Project, don't claim that the Project is run or endorsed by itch.io, and don't use the names "poli0981" or "SkullMute" to endorse your own work without prior written permission.
7. **Disrupt the Project**: don't attempt to overload, break or impair the Website (for example by denial-of-service), and don't use the Project to put unreasonable load on itch.io. If you run the pipeline code yourself, you are responsible for complying with itch.io's terms and for keeping its request pacing.
8. **Make false removal or copyright claims**, or claim to be a game's creator or rights holder when you are not.
9. **Harass, threaten, dox or impersonate** anyone through any channel related to the Project (issues, pull requests, discussions, Discord, social media).
10. Use the Project for any purpose that is unlawful where you are or in Vietnam.
## 7. Content removal and copyright
Anyone can ask for a game to be removed from the Catalog or for its data to be corrected. Game creators and rights holders are especially welcome to do so.
**How to ask**
- Email **takedown@poli0981.dev**, or
- open a ["Remove a game" issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=remove_game.yml) in the Repository (it includes a copyright-claim section). GitHub issues are public, so use email for anything you don't want published.
**Include**
- the game's itch.io URL (or its page on the Website);
- who you are: the creator, the rights holder, or someone authorized to act for them;
- the reason (for example: a copyright claim, you don't want the game listed, the data is wrong, or the game is no longer free). For a copyright claim, say which material (for example the description or the cover image) the claim is about.
**What happens**
- The Maintainer removes the record from the Catalog and logs the removal, with a reason, in the public list of removed games (https://freeitchgames.win/removed).
- The resized copies of the cover image stored on Cloudflare R2 are deleted, and cached copies expire from Cloudflare's cache.
- The Git history of the public Repository keeps past versions of the data. The Maintainer cannot rewrite public history, except where there is an exceptional legal necessity. Copies that others have already made (forks, downloaded data) are outside the Maintainer's control.
- Target: within **7 days**; urgent legal requests are handled sooner. If a request is unclear, the Maintainer may ask follow-up questions.
## 8. Adult (NSFW) content
- Games flagged `nsfw: Yes` are **hidden by default**, cover images included.
- You can opt in to 18+ content in Settings (https://freeitchgames.win/settings) after confirming that you are **18 or older**. By opting in, you also confirm that viewing such content is lawful where you are. The choice is stored only in your browser (`webapp.prefs`), and you can switch it off at any time.
- The `nsfw` flag is a best-effort label and may be wrong. Check the itch.io page yourself before downloading if this matters to you.
## 9. Games, safety and third-party services
- The Games belong to their creators and are provided by them through itch.io. The Project has no control over them.
- The Project does **not** scan downloads. The `safe_virus` field is a manual note, not a guarantee. Treat every download as untrusted until you have checked it yourself. See the [Disclaimer](DISCLAIMER.md).
- The Project relies on third-party services such as itch.io, GitHub and Cloudflare, which have their own terms and policies. The [Privacy Policy](PrivacyPolicy.md) explains what each of them processes.
## 10. No affiliation with itch.io
The Project is **not affiliated with, endorsed by, or sponsored by itch.io** or Leaf Corcoran / itch corp. "itch.io", game names, logos and other trademarks belong to their respective owners and are used only to identify the games and the platform. See [NOTICE.md](../NOTICE.md).
## 11. Intellectual property and licenses
- **Code** (everything in the Repository not listed below, such as `scripts/`, `webapp/`, `bash/`, workflows and tests): **MIT License**, Copyright (c) 2025-2026 poli0981 (SkullMute). See [`LICENSE`](../LICENSE).
- **Catalog data** (`data_game/`, `scripts/deleted_games.json`, and the derived files under https://freeitchgames.win/data): **CC BY 4.0** for the Maintainer's contribution, namely the selection and arrangement of the collection, the three Maintainer-written fields (`safe_virus`, `notes`, `nsfw`), the removal records, and the structure and derived statistics. See [`data_game/LICENSE.md`](../data_game/LICENSE.md) and the full legal code in [`LICENSES/CC-BY-4.0.txt`](../LICENSES/CC-BY-4.0.txt).
- Suggested attribution: `Free itch.io games catalog by poli0981 (SkullMute) — https://freeitchgames.win — CC BY 4.0`
- **Not licensed by the Project** (owned by others): game descriptions and any other text written by game creators; cover images, thumbnails and other media; game names, logos and trademarks; and itch.io's trademarks. To reuse these, you need the owner's permission or a legal exception that applies to you. Facts such as URLs, prices and ratings are not protected by copyright anyway.
- The cover images shown on the Website are resized copies served for display only; they remain the property of their creators.
- **Documentation** (the `*.md` files in the repository root and in `docs/`, including the README and these policies): **CC BY 4.0**.
- **Third-party components** keep their own licenses. See the About page (https://freeitchgames.win/about) and [`docs/THIRD_PARTY.md`](THIRD_PARTY.md).
## 12. No warranty and limitation of liability
- The Project is provided **"as is" and "as available"**, without warranties of any kind, including accuracy, completeness, availability, a game's free status, or safety. Details are in the [Disclaimer](DISCLAIMER.md).
- To the extent permitted by law, the Maintainer and contributors are not liable for any damage arising from the use of the Project, from any Game or third-party site reached through it, from downtime, or from errors in the data.
- Nothing in these Terms excludes or limits liability that cannot be excluded or limited under applicable law.
## 13. Changes to the service, moderation and termination
The Maintainer may, at any time and without notice:
- change, suspend or discontinue the Website, the Apps or the published data;
- remove or change any content (game entries, documentation, code);
- reject suggestions, and close, lock or hide issues, pull requests or comments that break these Terms;
- block people who repeatedly break these Terms, and limit or block traffic that abuses the Website.
If you break these Terms, your permission to use the Website and the Apps ends. Any rights you have received under the MIT License or CC BY 4.0 are governed by those licenses. Tagged releases (`vX.Y.Z`) are intended to remain available on GitHub Releases, but this is not guaranteed.
## 14. Changes to these Terms
- The Maintainer may update these Terms. New versions are published in the Repository, with the `Last updated` date at the top, and material changes are noted in [CHANGELOG.md](../CHANGELOG.md).
- When a change requires your acceptance again, the `LEGAL_VERSION` value in the Website and the Apps changes, and the legal gate asks you to accept the updated documents before you continue. If you don't accept them, please stop using the Website and the Apps.
## 15. Governing law and disputes
- These Terms are governed by the laws of the **Socialist Republic of Vietnam**, without regard to conflict-of-law principles.
- Disputes are handled in this order:
1. **Informally first**: email **legal@poli0981.dev**, open an issue, or use a contact channel listed on the About page (https://freeitchgames.win/about) or at https://poli0981.dev/links/. Most disagreements end here.
2. **Mediation**: if informal contact fails, the parties may try mediation by mutual agreement.
3. **Courts**: otherwise, the competent courts of Vietnam have jurisdiction.
- **Consumer rights**: nothing in these Terms limits the mandatory consumer-protection rights you have under the law of your country of residence, including any right that law gives you to bring a claim in your local courts.
## 16. Severability and translations
- If any provision of these Terms is held invalid or unenforceable, the remaining provisions remain in full force.
- Translations (such as the Vietnamese version in [`docs/i18n/vi/`](i18n/vi/ToS.md)) are provided for convenience. If a translation differs from this English version, the English version prevails.
## 17. Contact
These addresses reach the Maintainer's own mailbox (Google Workspace, domain poli0981.dev).
- **legal@poli0981.dev**: these Terms and anything else legal.
- **takedown@poli0981.dev**: content removal and copyright.
- **privacy@poli0981.dev**: privacy questions and requests.
- **security@poli0981.dev**: vulnerabilities (or GitHub's private vulnerability reporting; see the [Security Policy](../SECURITY.md)).
- **contact@poli0981.dev**: general questions that fit none of the above.
The Maintainer's other channels are listed at <https://poli0981.dev/links/>.
## 18. Final vibes
This is still a list of free games plus a website and a few apps, built by a tired dev with zero budget and two AI buddies. Be cool, don't break things, credit the data, and have fun hunting free games.
Questions? Email legal@poli0981.dev, open an issue, or use any channel on the About page. The Maintainer will try not to ghost.
## 19. Not legal advice
These Terms are a hobby-project document drafted by a non-lawyer with AI assistance. They are not a substitute for professional legal advice.
# Only to try the verification gate under `npx wrangler dev` (http://localhost:8787):
# GATE_SECRET=<32+ random characters, e.g. `openssl rand -hex 32`>
```
| Key | Kind | What it does |
|---|---|---|
| `DEV_ADMIN_EMAIL` | local only, optional | Lets you into the admin without Cloudflare Access. Honoured only when the host is `localhost`, `127.0.0.1` or `[::1]`; ignored everywhere else |
| `ADMIN_EMAILS` | secret | Comma-separated admin allow-list, checked behind Access. Not needed locally with `DEV_ADMIN_EMAIL` |
| `TURNSTILE_SECRET` | secret | Suggest form and verification gate, together with the `TURNSTILE_SITEKEY` var |
| `GATE_SECRET` | secret | Signs the verification-gate cookie (32+ characters). Without it the gate stays off. Locally, set `SITE_ORIGIN=http://localhost:8787` and open the site through `wrangler dev`; the cookie is `fig_gate` there (no `Secure`) |
| `GATE_BOT_TOKEN` | secret | The value the zone's Transform Rule sends for verified bots (32+ characters). Required in production, not on localhost |
| `GH_APP_PRIVATE_KEY` | secret | GitHub App private key for admin writes — the PEM as GitHub downloads it (PKCS#1) or PKCS#8, together with the `GH_APP_ID` and `GH_APP_INSTALLATION_ID` vars |
| `SITE_ORIGIN` | var override | The Suggest form and the verification gate only accept POSTs whose `Origin` equals it |
A feature whose settings are missing answers `503`; the public site needs none of them. The two
Turnstile values above are Cloudflare's always-pass test keys
([Turnstile testing](https://developers.cloudflare.com/turnstile/troubleshooting/testing/)); never use
them in production. `npm run cf:types` ignores `.dev.vars` (it reads the empty `types.env`), so local
secrets never reach the committed `worker-configuration.d.ts`.
### Suggest form
With the file above, the local D1 migrated and both servers running,
http://localhost:5173/suggest submits into the local review queue.
### Admin
With `DEV_ADMIN_EMAIL` set, open http://localhost:5173/admin/ (Vite, hot reload) or
http://localhost:8787/admin/ (the built copy, as in production). Without the GitHub App settings the
admin is read-only: actions that write to the repo answer `503`. With `GH_APP_ID`,
`GH_APP_INSTALLATION_ID` and `GH_APP_PRIVATE_KEY` set, approvals and edits become **real commits** to
the `GITHUB_REPO` repository (by default the public one) — point `GITHUB_REPO` at a fork where your
App is installed.
### Cron (RSS discovery)
```sh
npx wrangler dev --test-scheduled
# then open http://localhost:8787/__scheduled
```
This runs `scheduled()` once: it polls **one real itch.io RSS feed** into the local queue, then does
the queue bookkeeping. Use it sparingly.
## Web app checks (same as `webapp-ci.yml`)
```sh
cd webapp
npm run check:tauri # Tauri crates and their npm packages share major.minor
npm run cf:types -- --check # worker-configuration.d.ts matches wrangler.jsonc
npm run lint # ESLint
npm run knip # unused files / exports / dependencies
npm test # Vitest: app + Worker; D1 tests start a local workerd
npx tsc -b # type-check only (npm run build runs it too)
npm run build
npm run cf:check # wrangler deploy --dry-run: validates the Worker config, deploys nothing
```
`npm run test:coverage` runs the tests with v8 coverage and writes `coverage/lcov.info`, as the
SonarQube Cloud workflow (`sonarcloud.yml`) does.
Qodana (JetBrains) also analyses the code in CI (`qodana.yml`: TypeScript / JavaScript, Python and
Rust, each with its own `qodana.yaml`). It needs the project tokens, so it has no local command here;
the same inspections are built into WebStorm, PyCharm and RustRover.
After editing `wrangler.jsonc`, run `npm run cf:types` and commit the regenerated
`worker-configuration.d.ts`.
## Desktop and Android apps (Tauri)
```sh
cd webapp
npm run tauri:dev # native window + HMR
npm run tauri:build # native installers
```
The apps read the live catalog packs from https://freeitchgames.win/data/pack and load covers from
`img.itch.zone`, so they need internet access but not the local Worker (and code that changes the pack
format only works in `tauri:dev` once the site with that format is deployed). Platform prerequisites
(WebView2 on Windows 10, Xcode CLT on macOS, `libwebkit2gtk-4.1-dev` on Debian/Ubuntu) and the
Android build are documented in [`webapp/TAURI.md`](../webapp/TAURI.md).
## Mobile testing
Web UI changes that touch responsive layout, navigation or the data table must be smoke-tested on a
real iOS device before tagging a release; the Android APK is signed off on the Android devices. See
[`pc_spec.md`](pc_spec.md) for the test devices.
## Deploying (Maintainer)
Cloudflare Workers Builds deploys every push to `main` (root directory `webapp`, build
`npm run build`, deploy `npx wrangler deploy`). D1 migrations are applied by hand
(`npx wrangler d1 migrations apply freeitchgames --remote`), secrets are set with
`npx wrangler secret put <NAME>`, and `npx wrangler deploy --env staging` deploys the staging Worker.
Áp dụng từ: khi phát hành phiên bản 4.6.0 (website và các ứng dụng desktop, Android).
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-11-09 (English source revision 2026-11-09). Nếu có khác biệt, bản tiếng Anh được ưu tiên. Bản gốc: [`ACCESSIBILITY.md`](../../../ACCESSIBILITY.md).
Đây là một dự án sở thích do một người vận hành, poli0981 (SkullMute), dưới đây gọi là "Người duy trì": một danh mục game itch.io miễn phí, có trên website https://freeitchgames.win và trong các ứng dụng desktop, Android hiển thị cùng các trang đó. Ai cũng nên dùng được, dù bạn chỉ dùng bàn phím, trình đọc màn hình, phóng to, giao diện tương phản cao, nhập liệu bằng giọng nói hay bất cứ công cụ nào khác. Tuyên bố này cho biết những gì đã hoạt động, cách kiểm tra, những gì chưa ổn, và cách báo cho Người duy trì khi có gì đó cản trở bạn.
> **Tóm tắt (TL;DR)**
>
> - Mục tiêu là [WCAG 2.2](https://www.w3.org/TR/WCAG22/) mức AA cho website và các ứng dụng. Đó là mục tiêu, không phải chứng nhận: chưa có ai ngoài dự án đánh giá.
> - Mọi trang đều dùng được chỉ với bàn phím và với trình đọc màn hình. Người duy trì kiểm tra bằng bàn phím (không dùng chuột), Windows Narrator, và VoiceOver trên iPhone.
> - Màu sắc đạt tỉ lệ tương phản WCAG ở cả giao diện sáng và tối, và một bài test kiểm tra lại sau mỗi thay đổi. Hỗ trợ chế độ tương phản (Contrast themes) của Windows và làm theo thiết lập "giảm chuyển động" của hệ thống.
> - Mỗi biểu đồ đều có bảng dữ liệu đi kèm.
> - Các hạn chế đã biết nằm ở [§6](#6-các-hạn-chế-đã-biết).
> - Có gì cản trở bạn? Hãy mở một [issue trợ năng](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml) hoặc email **contact@poli0981.dev**.
## 1. Phạm vi
Tuyên bố này áp dụng cho:
- **website** https://freeitchgames.win: mọi trang công khai (Trang chủ, Games, trang từng game, Charts, Removed, Suggest, Settings, About, các trang lỗi) và trang xác minh hiện ra trước đó;
- **các ứng dụng desktop** (Windows, macOS, Linux) **và ứng dụng Android**, vốn hiển thị cùng các trang trong web view của hệ thống.
Tuyên bố này không áp dụng cho:
- bản thân các game, trang itch.io của chúng, và những gì người tạo game viết hay làm ra (tên, mô tả, tag, ảnh bìa);
- Cloudflare Turnstile, bước kiểm tra của bên thứ ba trên trang xác minh và trên form Suggest (Cloudflare chịu trách nhiệm về trợ năng của nó);
- trang quản trị của Người duy trì, vốn chỉ có một người dùng;
- các trang web khác được liên kết tới, kể cả GitHub.
## 2. Mục tiêu và ưu tiên
- **Mục tiêu**: [WCAG 2.2](https://www.w3.org/TR/WCAG22/) mức AA, trong khả năng của một dự án sở thích do một người làm.
- **Trước hết**: các việc chính dùng được với bàn phím và trình đọc màn hình: tìm game, đọc thông tin, mở game trên itch.io, đổi cài đặt, gợi ý game.
- **Tiếp theo**: chữ và nút dễ đọc (tương phản, phóng to, dàn lại bố cục), không có chuyển động bạn không yêu cầu, và đúng ngôn ngữ cho trình đọc màn hình (tiếng Anh hoặc tiếng Việt).
- **Luôn luôn**: tính năng mới phải giữ được tất cả những điều trên (xem [§8](#8-dành-cho-người-đóng-góp)).
## 3. Những gì đã hoạt động
### Di chuyển trong trang
- "Chuyển đến nội dung" (Skip to content) là thứ đầu tiên phím Tab chạm tới.
- Mỗi trang có các vùng mốc (landmark) được đặt tên (đầu trang, menu chính, tìm kiếm, nội dung chính, phân trang, chân trang), một tiêu đề cấp 1 và tiêu đề trang riêng.
- Khi bạn bấm một liên kết bên trong site, focus chuyển tới tiêu đề của trang mới, nên trình đọc màn hình đọc tên trang và phím Tab đi tiếp từ đó. Khi quay lại, focus trở về liên kết bạn vừa dùng, ví dụ game bạn mở từ danh sách.
- Thanh đầu trang cố định không bao giờ che phần tử đang có focus bàn phím.
### Bàn phím
- Mọi thứ đều dùng được chỉ với bàn phím: menu, bộ lọc, hộp thoại và biểu đồ.
- Focus luôn nhìn thấy được: một đường viền tím, hoặc màu tô sáng của hệ thống trong chế độ tương phản.
- Hộp thoại giữ focus bên trong khi đang mở và trả focus về chỗ cũ khi đóng.
- Phím "/" đưa bạn tới ô tìm kiếm. Bạn có thể tắt phím tắt này trong **Settings → Trợ năng**, hữu ích khi nhập liệu bằng giọng nói hoặc khi phím này xung đột với trình đọc màn hình hay chức năng tìm nhanh của trình duyệt.
- Khi một nút biến mất sau khi bạn dùng nó (xoá ô tìm kiếm, bỏ một bộ lọc), focus chuyển tới chỗ hợp lý tiếp theo thay vì bị mất.
### Trình đọc màn hình
- Mọi nút điều khiển đều có tên, bằng tiếng Anh hoặc tiếng Việt. Biểu tượng được ẩn khỏi trình đọc màn hình.
- Số kết quả, gợi ý tìm kiếm, trạng thái đang tải và thông báo của form đều được đọc lên.
- Trên màn hình rộng, danh sách game là một bảng có tiêu đề cột; trên điện thoại là một danh sách đơn giản.
- Liên kết mở thẻ mới (trong ứng dụng: mở trình duyệt) đều nói rõ điều đó.
- Chữ thuộc ngôn ngữ kia, như tên các ngôn ngữ và tên tiếng Anh của các văn bản pháp lý, được đánh dấu đúng ngôn ngữ.
### Nhìn nội dung
- Chữ và nút đạt tỉ lệ tương phản WCAG 2.2 AA ở cả hai giao diện: 4.5:1 cho chữ, 3:1 cho viền ô nhập, đường viền focus và màu biểu đồ. Bài test [`webapp/scripts/check-contrast.test.mjs`](../../../webapp/scripts/check-contrast.test.mjs) kiểm tra màu sau mỗi thay đổi.
- Giao diện sáng, tối hoặc theo hệ thống; dòng gọn hoặc thường; ẩn thanh cuộn: tất cả nằm trong Settings.
- Chế độ tương phản của Windows (forced colors): tab đang chọn, nút bật/tắt đang bấm, trang hiện tại và các công tắc dùng màu tô sáng của hệ thống.
- Không bao giờ chặn phóng to. Ở mức phóng 400 % hoặc cửa sổ rộng 320 pixel, bố cục điện thoại được dùng và trang không phải cuộn ngang.
- Liên kết nằm trong câu đều được gạch chân. Không có gì chỉ dựa vào màu sắc: trạng thái luôn kèm thay đổi chữ, viền hoặc gạch chân.
### Chuyển động
- Khi bạn bật "giảm chuyển động" trong hệ thống, hiệu ứng, phần biểu đồ hiện ra và cuộn mượt đều tắt.
- Trên website, ảnh bìa thường được hiển thị dạng ảnh tĩnh (ảnh bìa động được chuyển thành ảnh tĩnh).
- Ngoài các khối giữ chỗ khi đang tải, không có gì tự chuyển động.
### Biểu đồ
- Mỗi biểu đồ được đặt tên theo tiêu đề của nó. Đưa focus vào biểu đồ rồi dùng phím mũi tên trái, phải: giá trị bạn chuyển tới sẽ được đọc lên.
- Dưới mỗi biểu đồ, **Bảng dữ liệu** mở cùng các số liệu dưới dạng bảng, kèm tỉ lệ từng phần với biểu đồ tròn.
### Ngôn ngữ
- Các trang có tiếng Anh và tiếng Việt (Settings), và ngôn ngữ của trang đi theo lựa chọn của bạn, nên trình đọc màn hình chọn đúng giọng đọc. Số và ngày tháng cũng theo ngôn ngữ đó.
## 4. Cách kiểm tra
- **Người duy trì kiểm tra thủ công** (tháng 11/2026): website trên Windows 11 và ứng dụng desktop Windows, chỉ dùng bàn phím (tắt chuột) và Windows Narrator. Không thấy lỗi nào chặn việc sử dụng.
- **Trên điện thoại thật** (tháng 11/2026, phiên bản 4.6.0): website trên iPhone 14 Pro với VoiceOver, trong Safari, Chrome và Brave. Kết quả: đạt.
- **Cho bản 4.6.0**: các trang chính và hộp thoại được đi hết bằng bàn phím, và cây trợ năng (accessibility tree) của chúng được kiểm tra (tên, vai trò, tiêu đề, vùng mốc, thông báo) bằng tiếng Anh và tiếng Việt, trên màn hình máy tính và màn hình cỡ điện thoại.
- **Tự động, sau mỗi thay đổi**: bài test tương phản ở trên và các unit test của ứng dụng (focus đi đâu sau khi đổi trang, bảng dữ liệu biểu đồ).
- **Trước mỗi lần phát hành**: một lượt kiểm tra nhanh. Gồm đi hết các việc chính bằng bàn phím, thử nhanh với trình đọc màn hình, phóng to 200 % và cửa sổ hẹp, giảm chuyển động, và một chế độ tương phản của Windows.
- **Chưa có**: quét tự động trên trình duyệt (như axe hay Lighthouse) trong CI, và việc kiểm tra bởi những người dùng hằng ngày nhiều công cụ hỗ trợ khác nhau. Mọi sự giúp đỡ đều được hoan nghênh.
## 5. Môi trường được hỗ trợ
| | Phiên bản |
|---|---|
| Website | Chrome, Edge, Firefox và Safari hiện hành trên máy tính và điện thoại. Các phiên bản cũ nhất mà site được build cho là Chrome và Edge 111, Firefox 114, Safari và iOS 15.4. |
| Ứng dụng desktop | Windows 10 và 11 (Microsoft Edge WebView2), macOS (WebKit 16.4 trở lên), Linux (WebKitGTK 4.1) |
| Ứng dụng Android | Android 11 trở lên |
Công cụ hỗ trợ (assistive technology):
- **Đã kiểm tra**: Windows Narrator trên Windows 11, VoiceOver trên iOS (iPhone 14 Pro: Safari, Chrome và Brave), và dùng chỉ bàn phím.
- **Dự kiến dùng được, chưa kiểm tra thường xuyên**: NVDA và JAWS trên Windows, VoiceOver trên macOS, TalkBack trên Android, phóng to của trình duyệt, chế độ tương phản của Windows, nhập liệu bằng giọng nói. Chúng dựa trên cùng mã HTML chuẩn.
- **Hạn chế**: Orca trong ứng dụng desktop Linux, vì WebKitGTK hỗ trợ trình đọc màn hình kém hơn các trình duyệt.
## 6. Các hạn chế đã biết
- **Chữ của người tạo game không được đánh dấu ngôn ngữ.** Tên, mô tả và tag của game lấy từ itch.io bằng nhiều ngôn ngữ, và trình đọc màn hình đọc chúng theo ngôn ngữ của trang.
- **Ảnh bìa chỉ có mô tả chung** ("Tên game cover"). Nội dung bức ảnh không được mô tả.
- **Biểu đồ**: phím mũi tên chỉ di chuyển trái và phải. Biểu đồ treemap thể loại không đi từng phần được, nhưng số liệu của nó có trong bảng dữ liệu và trong biểu đồ Genres. Chữ trong biểu đồ có cỡ pixel cố định, nên tăng cỡ chữ mặc định của trình duyệt không làm nó to lên (phóng to trang thì có).
- **Ứng dụng desktop**: không có phím phóng to bên trong ứng dụng, cửa sổ không phóng to toàn màn hình (maximize) được, và không thu nhỏ hơn 900 × 600. Nếu cần chữ lớn hơn, hãy dùng tỉ lệ hiển thị (display scaling) của hệ thống hoặc mở website trong trình duyệt.
- **Ứng dụng Android**: không phóng to bằng hai ngón tay được. Website trong trình duyệt điện thoại thì phóng to được.
- **Ảnh bìa động trong ứng dụng**: ứng dụng tải ảnh bìa trực tiếp từ itch.io, nên ảnh bìa động vẫn chạy ở đó.
- **Bước kiểm tra của Cloudflare**: bước xác minh (chỉ trên website) và bước chống spam của form Suggest là widget Cloudflare Turnstile. Thường chúng tự qua mà bạn không cần làm gì. Nếu có lúc chúng yêu cầu điều bạn không làm được, hãy email Người duy trì.
- **Trang trên GitHub**: các chính sách, tuyên bố này và các form issue nằm trên GitHub, nên trợ năng của chính GitHub áp dụng ở đó.
- **Chưa có đánh giá độc lập**, và chỉ có một người duy trì.
## 7. Báo cáo rào cản trợ năng
Nếu có gì ngăn bạn hoặc làm bạn chậm lại, hãy cho biết. Báo cáo chưa đầy đủ cũng có ích.
- **GitHub**: mở một [issue Accessibility barrier](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml).
- **Email**: **contact@poli0981.dev**. Không cần tài khoản GitHub; viết tiếng Anh hay tiếng Việt đều được.
Những chi tiết có ích, trong chừng mực bạn thấy thoải mái chia sẻ (đừng bao giờ gửi thông tin sức khoẻ):
- bạn đang định làm gì, và điều gì đã xảy ra;
- trang (địa chỉ) hoặc ứng dụng và phiên bản của nó, xem trên trang About;
- thiết bị, hệ điều hành và trình duyệt;
- công cụ hỗ trợ bạn dùng và phiên bản, nếu có;
- ảnh chụp màn hình hoặc video, nếu được.
Mức độ ảnh hưởng:
| Mức độ | Ý nghĩa |
|---|---|
| Critical (nghiêm trọng nhất) | Bạn hoàn toàn không làm được một việc chính, ví dụ mở game hay đọc thông tin của nó. |
| Serious (nghiêm trọng) | Bạn làm được, nhưng rất vất vả hoặc phải đi đường vòng. |
| Moderate (trung bình) | Gây phiền hoặc không nhất quán, nhưng vẫn làm được. |
| Minor (nhỏ) | Một chi tiết nhỏ cần chỉnh. |
Điều gì xảy ra tiếp theo. Đây là mục tiêu, không phải cam kết, vì đây là dự án sở thích của một người:
- **Xác nhận đã nhận** trong vòng 7 ngày, thường sớm hơn.
- **Sửa lỗi hoặc đưa cách khắc phục tạm**: Critical trong 30 ngày, Serious trong 60 ngày, Moderate và Minor ở một bản phát hành sau.
- **Bản sửa cho website** có hiệu lực khi được deploy; **bản sửa cho ứng dụng** đi kèm bản phát hành tiếp theo.
- Bạn sẽ được hỏi bản sửa đã ổn với bạn chưa, và được ghi công trong release notes nếu muốn.
Lỗ hổng bảo mật không nên đưa vào issue công khai: xem [Chính sách bảo mật](SECURITY.md).
## 8. Dành cho người đóng góp
Thay đổi giao diện phải giữ đúng những điều ở [§3](#3-những-gì-đã-hoạt-động):
- **Bàn phím**: mọi nút đều tới được và dùng được, focus luôn nhìn thấy và không bị mất.
- **Tên**: mọi nút có nhãn, với chữ có trong cả `webapp/src/lib/i18n/en.ts` và `vi.ts`.
- **Màu sắc**: dùng các token của theme. `npm test` kiểm tra tương phản (4.5:1 cho chữ, 3:1 cho viền, focus và màu biểu đồ), và màu sắc không bao giờ là tín hiệu duy nhất.
- **Chuyển động**: tôn trọng `prefers-reduced-motion`; quy tắc CSS dùng chung và `SERIES_ANIMATION` đã làm việc đó.
- **Trình đọc màn hình**: kiểm tra thay đổi ít nhất một lần với một trình đọc (Narrator, NVDA, VoiceOver hoặc TalkBack).
- **Mã HTML**: ưu tiên phần tử gốc và các component Radix / shadcn đang dùng, chỉ thêm ARIA khi thật cần.
Tài liệu: tiêu đề theo đúng thứ tự, chữ của liên kết nói rõ nó dẫn tới đâu, ảnh có alt, bảng có ô tiêu đề, và bản tiếng Việt được cập nhật (hoặc ghi rõ trong pull request là chưa).
[Pull request template](../../../.github/pull_request_template.md) có sẵn danh sách kiểm tra.
## 9. Tìm game có hỗ trợ tiếp cận
Danh mục hiển thị các tính năng hỗ trợ tiếp cận mà người tạo game liệt kê trên trang itch.io của họ, như phụ đề, điều khiển tuỳ chỉnh được hay chế độ cho người mù màu:
- trên trang của từng game, ở mục "Hỗ trợ tiếp cận";
- trong bộ lọc Hỗ trợ tiếp cận ở trang Games, ví dụ https://freeitchgames.win/games?access=Subtitles;
- trong biểu đồ "Tính năng hỗ trợ tiếp cận" (Charts → Khám phá).
Người tạo game tự khai báo các tính năng này, và dự án không kiểm chứng. Nếu thông tin của một game sai, hãy báo bằng issue template "Bug Report".
## 10. Tài liệu tham khảo
- [Open Source Guides: Accessibility best practices for your project](https://opensource.guide/accessibility-best-practices-for-your-project/)
- [Open Source Accessibility toolkit](https://github.com/open-source-accessibility/accessibility-toolkit): tuyên bố này theo dàn ý của mẫu ACCESSIBILITY.md trong đó, với lời văn riêng.
- [W3C: Developing an accessibility statement](https://www.w3.org/WAI/planning/statements/)
## 11. Liên hệ
- **Rào cản trợ năng**: [form issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml) hoặc **contact@poli0981.dev**.
- **Mọi việc khác**: xem các địa chỉ trong [README → Pháp lý](../../../README.vi.md#pháp-lý).
## 12. Lời cuối
Một người, một danh mục, và mọi cách duyệt web. Nếu có gì ở đây không hợp với cách bạn dùng web, Người duy trì thật sự muốn được biết — đó là cách danh sách này ngày càng tốt hơn. 🚀
Loaded 100 of 463 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.