From 69c89648422b843ae9b5152ce4f8548384e75d77 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 3 Nov 2026 19:27:31 +0700 Subject: [PATCH 1/4] feat(web): random games page /random rolls one to five games from the catalogue (five to start with): any type, online or offline, dead games only when asked, never one marked unsafe. Roll again avoids the games on screen while enough others remain; a smaller count keeps the first picks, a larger one adds to them. - lib/random-pick.ts: crypto.getRandomValues with rejection sampling and a sparse Fisher-Yates, never Math.random (SonarCloud S2245), plus the pool rules, read off appidIndex so each game appears once. - lib/random.svelte.ts: the picks as appids, module-level and memory only, so Back from a game keeps them and no f2p:* key is needed (a new key means a privacy-policy edit, which reopens the consent gate). Only the reader rolls; a revalidation only drops a pick that left the catalogue or stopped qualifying. - The page, an entry in the sidebar, drawer and palette (nav.ts) and a dashboard button. Top-level on purpose: the header search, isActive and the PWA's globIgnores all treat /games/* specially. The empty state joins verify-dist's BAKED_EMPTY_STATES; the sitemap ranks the page low. Co-Authored-By: Claude Opus 5.5 --- web/scripts/verify-dist.mjs | 2 +- web/src/i18n/locales/en.json | 15 ++ web/src/i18n/locales/vi.json | 15 ++ web/src/lib/nav.test.ts | 11 ++ web/src/lib/nav.ts | 2 + web/src/lib/random-pick.test.ts | 198 ++++++++++++++++++++++ web/src/lib/random-pick.ts | 143 ++++++++++++++++ web/src/lib/random-store.test.ts | 131 +++++++++++++++ web/src/lib/random.svelte.ts | 109 ++++++++++++ web/src/routes/+page.svelte | 11 +- web/src/routes/random/+page.svelte | 229 ++++++++++++++++++++++++++ web/src/routes/sitemap.xml/+server.ts | 2 + 12 files changed, 866 insertions(+), 2 deletions(-) create mode 100644 web/src/lib/random-pick.test.ts create mode 100644 web/src/lib/random-pick.ts create mode 100644 web/src/lib/random-store.test.ts create mode 100644 web/src/lib/random.svelte.ts create mode 100644 web/src/routes/random/+page.svelte diff --git a/web/scripts/verify-dist.mjs b/web/scripts/verify-dist.mjs index fe2a8f05..bd2cdbaf 100644 --- a/web/scripts/verify-dist.mjs +++ b/web/scripts/verify-dist.mjs @@ -150,7 +150,7 @@ const TURNSTILE_HOST = "https://challenges.cloudflare.com"; const MEDIA_HOST = "https://media.free-steam-games.win"; // Strings that must never be baked into a page before data exists. -const BAKED_EMPTY_STATES = [en.games.noResults, en.health.allClear, en.studios.notFound]; +const BAKED_EMPTY_STATES = [en.games.noResults, en.health.allClear, en.studios.notFound, en.random.noMatch]; const CONSENT_TITLE = en.consent.title; const HUMAN_CHECK_TITLE = en.humanCheck.title; diff --git a/web/src/i18n/locales/en.json b/web/src/i18n/locales/en.json index 49715ff7..0e0a9907 100644 --- a/web/src/i18n/locales/en.json +++ b/web/src/i18n/locales/en.json @@ -64,6 +64,7 @@ "nav": { "dashboard": "Dashboard", "games": "Games", + "random": "Random games", "topOnline": "Top Online", "topOffline": "Top Offline", "charts": "Charts", @@ -197,6 +198,20 @@ "topOffline": { "subtitle": "Top 100 single-player or non-online F2P titles by concurrent players." }, + "random": { + "subtitle": "Can't decide what to play? Roll up to five free games from the catalogue.", + "seoDescription": "Free-to-play Steam games picked at random - online or offline, with or without the ones nobody plays any more.", + "roll": "Roll the dice", + "rollAgain": "Roll again", + "countLabel": "How many", + "includeDead": "Include dead games", + "pool": "Picked from {{total}} games", + "pool_one": "Picked from {{total}} game", + "announce": "{{count}} games picked: {{names}}", + "announce_one": "1 game picked: {{names}}", + "noMatch": "No game matches these settings.", + "openOnSteam": "Open on Steam" + }, "settings": { "title": "Settings", "subtitle": "Language, theme, and preferences.", diff --git a/web/src/i18n/locales/vi.json b/web/src/i18n/locales/vi.json index 28172bc2..4b220435 100644 --- a/web/src/i18n/locales/vi.json +++ b/web/src/i18n/locales/vi.json @@ -64,6 +64,7 @@ "nav": { "dashboard": "Tổng quan", "games": "Trò chơi", + "random": "Game ngẫu nhiên", "topOnline": "Top Online", "topOffline": "Top Offline", "charts": "Biểu đồ", @@ -197,6 +198,20 @@ "topOffline": { "subtitle": "Top 100 game F2P single-player / không-online theo số người chơi đồng thời." }, + "random": { + "subtitle": "Chưa biết chơi gì? Gieo xúc xắc để chọn tối đa năm game miễn phí trong danh sách.", + "seoDescription": "Game miễn phí trên Steam được chọn ngẫu nhiên - online hay offline, có hoặc không tính những game không còn ai chơi.", + "roll": "Gieo xúc xắc", + "rollAgain": "Gieo lại", + "countLabel": "Số lượng", + "includeDead": "Tính cả game đã chết", + "pool": "Chọn từ {{total}} game", + "pool_one": "Chọn từ {{total}} game", + "announce": "Đã chọn {{count}} game: {{names}}", + "announce_one": "Đã chọn 1 game: {{names}}", + "noMatch": "Không có game nào khớp với các lựa chọn này.", + "openOnSteam": "Mở trên Steam" + }, "settings": { "title": "Cài đặt", "subtitle": "Ngôn ngữ, giao diện và tuỳ chọn.", diff --git a/web/src/lib/nav.test.ts b/web/src/lib/nav.test.ts index 92611481..071e59a0 100644 --- a/web/src/lib/nav.test.ts +++ b/web/src/lib/nav.test.ts @@ -26,4 +26,15 @@ describe("navigation lists", () => { it("publishers is reachable from the sidebar", () => { expect(PRIMARY.some((r) => r.to === "/publishers")).toBe(true); }); + + it("random games are reachable from the sidebar", () => { + expect(PRIMARY.some((r) => r.to === "/random")).toBe(true); + }); + + it("the sidebar's icons are all distinct", () => { + // An icon shared by two rows is useless for finding either (nav.ts). EXTRA + // is left out: it is palette-only, and /welcome shares About's icon. + const icons = [...PRIMARY, ...SECONDARY].map((r) => r.icon); + expect(new Set(icons).size).toBe(icons.length); + }); }); diff --git a/web/src/lib/nav.ts b/web/src/lib/nav.ts index 8667d139..0589626b 100644 --- a/web/src/lib/nav.ts +++ b/web/src/lib/nav.ts @@ -12,6 +12,7 @@ */ import type { Component } from "svelte"; import BarChart3 from "@lucide/svelte/icons/chart-column"; +import Dices from "@lucide/svelte/icons/dices"; import Gamepad2 from "@lucide/svelte/icons/gamepad-2"; import Heart from "@lucide/svelte/icons/heart"; import HeartPulse from "@lucide/svelte/icons/heart-pulse"; @@ -42,6 +43,7 @@ export interface NavItem { export const PRIMARY: NavItem[] = [ { to: "/", i18n: "nav.dashboard", icon: LayoutDashboard, exact: true }, { to: "/games", i18n: "nav.games", icon: Gamepad2 }, + { to: "/random", i18n: "nav.random", icon: Dices }, { to: "/top-online", i18n: "nav.topOnline", icon: Users }, { to: "/top-offline", i18n: "nav.topOffline", icon: Trophy }, { to: "/charts", i18n: "nav.charts", icon: BarChart3 }, diff --git a/web/src/lib/random-pick.test.ts b/web/src/lib/random-pick.test.ts new file mode 100644 index 00000000..bcae1dee --- /dev/null +++ b/web/src/lib/random-pick.test.ts @@ -0,0 +1,198 @@ +import { describe, expect, it } from "vitest"; +import { buildIndex } from "./data-store"; +import { + MAX_PICKS, + PICK_COUNTS, + buildPool, + clampCount, + isEligible, + randomBelow, + samplePicks, + type RandomSource, +} from "./random-pick"; +import { SKELETON_TEMPLATE, type GameRecord } from "./schema"; + +/** Fixed words in order, then a loud failure: a test that draws more than it + * planned is a wrong test. */ +function replay(...values: number[]): RandomSource { + let i = 0; + return () => { + if (i >= values.length) throw new Error("replay: out of values"); + return values[i++]; + }; +} + +/** xorshift32: deterministic, even enough to compare frequencies, and no + * Math.random even in a test. */ +function xorshift(seed: number): RandomSource { + let x = seed | 0 || 1; + return () => { + x ^= x << 13; + x ^= x >>> 17; + x ^= x << 5; + return x >>> 0; + }; +} + +function game(appid: number, overrides: Partial = {}): GameRecord { + return { + ...SKELETON_TEMPLATE, + link: `https://store.steampowered.com/app/${appid}/`, + name: `Game ${appid}`, + type_game: "online", + ...overrides, + }; +} + +function catalogue(records: GameRecord[]) { + return { records, appidIndex: buildIndex(records) }; +} + +/** `safe` is typed y/n/?/"", but it is typed in by hand, and the data carries + * spellings outside that (safety.ts normalises them). */ +function handTyped(safe: string): GameRecord["safe"] { + return safe as GameRecord["safe"]; +} + +const ANY = { type: "any", includeDead: false } as const; + +describe("randomBelow", () => { + it("throws away the words that would favour low results", () => { + // 2^32 % 3 === 1: 0xFFFFFFFF is the one word that would make 0 likelier. + const next = replay(0xffffffff, 0xfffffffe); + expect(randomBelow(3, next)).toBe(2); + expect(() => next()).toThrow(/out of values/); + // The worst case: just under half of all words are rejected. + expect(randomBelow(2 ** 31 + 1, replay(2 ** 31 + 1, 5))).toBe(5); + }); + + it("rejects nothing when n divides 2^32", () => { + expect(randomBelow(4, replay(0xffffffff))).toBe(3); + expect(randomBelow(2 ** 32, replay(0xffffffff))).toBe(0xffffffff); + expect(randomBelow(1, replay(123_456))).toBe(0); + }); + + it("fails loudly on a source that never produces a usable word", () => { + expect(() => randomBelow(3, () => 0xffffffff)).toThrow(/never produced/); + }); + + it("refuses an n it cannot draw from", () => { + for (const n of [0, -1, 1.5, Number.NaN, 2 ** 32 + 1]) { + expect(() => randomBelow(n, replay(1))).toThrow(RangeError); + } + }); + + it("draws from crypto by default, and evenly", () => { + const bins = new Array(7).fill(0); + for (let i = 0; i < 70_000; i++) bins[randomBelow(7)]++; + // 10,000 expected per bin; one standard deviation is about 93. + for (const count of bins) expect(Math.abs(count - 10_000)).toBeLessThan(600); + }); +}); + +describe("samplePicks", () => { + const POOL = Array.from({ length: 100 }, (_, i) => `g${i}`); + + it("never returns the same entry twice, even from a pool that repeats one", () => { + const picks = samplePicks(["a", "a", "b"], 3, { next: xorshift(1) }); + expect([...picks].sort()).toEqual(["a", "b"]); + }); + + it("returns at most the count, and at most the pool", () => { + for (const count of [0, -3, Number.NaN]) expect(samplePicks(POOL, count)).toEqual([]); + expect(samplePicks(POOL, 2.7)).toHaveLength(2); + expect(samplePicks([], 5)).toEqual([]); + expect([...samplePicks(["x", "y", "z"], 5)].sort()).toEqual(["x", "y", "z"]); + for (const id of samplePicks(POOL, 5)) expect(POOL).toContain(id); + }); + + it("avoids the games on screen while enough others remain", () => { + const avoid = new Set(POOL.slice(0, 5)); + const next = xorshift(2); + for (let i = 0; i < 1000; i++) { + const picks = samplePicks(POOL, 5, { avoid, next }); + expect(picks).toHaveLength(5); + expect(picks.some((id) => avoid.has(id))).toBe(false); + } + }); + + it("falls back on the games on screen when the pool is too small", () => { + const pool = ["a", "b", "c", "d", "e", "f", "g"]; + const avoid = new Set(["a", "b", "c", "d", "e"]); + const picks = samplePicks(pool, 5, { avoid, next: xorshift(3) }); + expect(picks).toHaveLength(5); + expect(new Set(picks).size).toBe(5); + // The two fresh ones first, then the shown ones to make up the number. + expect([...picks.slice(0, 2)].sort()).toEqual(["f", "g"]); + for (const id of picks.slice(2)) expect(avoid.has(id)).toBe(true); + }); + + it("never picks an excluded entry, even when that leaves fewer", () => { + const pool = ["a", "b", "c", "d", "e", "f", "g"]; + const exclude = new Set(["a", "b", "c", "d", "e"]); + expect([...samplePicks(pool, 5, { exclude, next: xorshift(4) })].sort()).toEqual(["f", "g"]); + }); + + it("puts every order equally often", () => { + const counts = new Map(); + const next = xorshift(5); + for (let i = 0; i < 60_000; i++) { + const key = samplePicks(["a", "b", "c"], 3, { next }).join(""); + counts.set(key, (counts.get(key) ?? 0) + 1); + } + expect([...counts.keys()].sort()).toEqual(["abc", "acb", "bac", "bca", "cab", "cba"]); + // 10,000 expected per order; one standard deviation is about 91. + for (const count of counts.values()) expect(Math.abs(count - 10_000)).toBeLessThan(500); + }); +}); + +describe("the pool", () => { + it("leaves out what must never come up", () => { + const data = catalogue([ + game(1), + game(2, { status: "delisted" }), + game(3, { safe: "n" }), + game(4, { safe: handTyped("no") }), + game(5, { is_dead: true }), + game(6, { safe: "y" }), + game(7, { safe: "" }), + game(0, { link: "" }), + ]); + expect(buildPool(data, ANY)).toEqual(["1", "6", "7"]); + expect(buildPool(data, { ...ANY, includeDead: true })).toEqual(["1", "5", "6", "7"]); + }); + + it("narrows to one type", () => { + const data = catalogue([game(1), game(2, { type_game: "offline" }), game(3, { type_game: "" })]); + expect(buildPool(data, ANY)).toEqual(["1", "2", "3"]); + expect(buildPool(data, { ...ANY, type: "online" })).toEqual(["1"]); + expect(buildPool(data, { ...ANY, type: "offline" })).toEqual(["2"]); + }); + + it("lists an appid once, however many records carry it", () => { + const data = catalogue([game(1), game(2), game(1, { name: "Again" })]); + expect(buildPool(data, ANY)).toEqual(["1", "2"]); + }); + + it("judges a single record the same way", () => { + expect(isEligible(game(1), ANY)).toBe(true); + expect(isEligible(game(1, { safe: handTyped(" N ") }), ANY)).toBe(false); + expect(isEligible(game(1, { is_dead: true }), { ...ANY, includeDead: true })).toBe(true); + expect(isEligible(game(1, { type_game: "offline" }), { ...ANY, type: "online" })).toBe(false); + }); +}); + +describe("clampCount", () => { + it("keeps the count between one and the maximum", () => { + expect(clampCount(0)).toBe(1); + expect(clampCount(-2)).toBe(1); + expect(clampCount(3.9)).toBe(3); + expect(clampCount(7)).toBe(MAX_PICKS); + expect(clampCount(Number.NaN)).toBe(MAX_PICKS); + }); + + it("matches what the control offers", () => { + expect(Math.max(...PICK_COUNTS)).toBe(MAX_PICKS); + expect(PICK_COUNTS.map(clampCount)).toEqual([...PICK_COUNTS]); + }); +}); diff --git a/web/src/lib/random-pick.ts b/web/src/lib/random-pick.ts new file mode 100644 index 00000000..0745bbe8 --- /dev/null +++ b/web/src/lib/random-pick.ts @@ -0,0 +1,143 @@ +/** + * Picking games at random, for /random. + * + * Pure: no runes and no catalogue import, so the rules are tested without + * Svelte, and nothing here pulls in the search index (games/filtering.ts brings + * Fuse with it - the reason safety.ts is a module of its own). + * + * The randomness comes from crypto.getRandomValues, never Math.random. Nothing + * about a game pick is secret, but SonarCloud reports every Math.random as a + * security hotspot (S2245), and an unreviewed hotspot fails the quality gate. + */ +import { safeClass } from "./safety"; +import type { GameRecord } from "./schema"; + +/** The most games one roll shows. */ +export const MAX_PICKS = 5; +/** What the count control offers. */ +export const PICK_COUNTS = [1, 2, 3, 4, 5] as const; + +export type TypeChoice = "any" | "online" | "offline"; + +export interface PoolOptions { + type: TypeChoice; + includeDead: boolean; +} + +/** What a roll reads of the catalogue. GamesData satisfies it as it is. */ +export interface Catalogue { + readonly records: readonly GameRecord[]; + readonly appidIndex: ReadonlyMap; +} + +/** A uniformly random integer in [0, 2^32). Injectable, so tests are exact. */ +export type RandomSource = () => number; + +const word = new Uint32Array(1); +const cryptoRandom: RandomSource = () => crypto.getRandomValues(word)[0]; + +const RANGE = 2 ** 32; +// The worst case, n = 2^31 + 1, rejects just under half of all words, so 64 +// tries in a row fail with probability ~2^-64: only a broken source gets there. +const MAX_TRIES = 64; + +/** + * A uniformly random integer in [0, n). + * + * `x % n` on its own favours the low remainders whenever n does not divide + * 2^32, so the top `2^32 % n` words are thrown away and drawn again. + */ +export function randomBelow(n: number, next: RandomSource = cryptoRandom): number { + if (!Number.isInteger(n) || n < 1 || n > RANGE) { + throw new RangeError(`randomBelow(${n}): n must be an integer from 1 to 2^32`); + } + const limit = RANGE - (RANGE % n); + for (let tries = 0; tries < MAX_TRIES; tries++) { + const x = next(); + if (x < limit) return x % n; + } + throw new Error("randomBelow: the random source never produced a usable value"); +} + +/** + * 0..n-1 in uniformly random order, produced lazily. + * + * A Fisher-Yates shuffle that stores only the slots it has swapped: a roll + * reads five positions out of ~15,000, and shuffling a full copy of the pool + * for that would be 15,000 writes for five reads. + */ +function* shuffledPositions(n: number, next: RandomSource): Generator { + const moved = new Map(); + for (let i = 0; i < n; i++) { + const j = i + randomBelow(n - i, next); + const value = moved.get(j) ?? j; + moved.set(j, moved.get(i) ?? i); + // Slot i is never read again. Dropping it keeps the map as small as the + // number of draws, and is also right when j === i. + moved.delete(i); + yield value; + } +} + +export interface SampleOptions { + /** Never picked: the picks being KEPT when the count grows. */ + exclude?: ReadonlySet; + /** Picked only when too few others remain: the picks a re-roll replaces. */ + avoid?: ReadonlySet; + next?: RandomSource; +} + +/** + * Up to `count` DISTINCT entries of `pool`, uniformly, in random order. + * + * Distinct even when the pool repeats one: the page keys its list on the + * appid, and a duplicate key in a keyed each throws in a production build. + */ +export function samplePicks(pool: readonly string[], count: number, opts: SampleOptions = {}): string[] { + const { exclude, avoid, next = cryptoRandom } = opts; + const want = Math.min(Math.max(Math.trunc(count) || 0, 0), pool.length); + const fresh: string[] = []; + if (want === 0) return fresh; + + const held: string[] = []; + const seen = new Set(); + for (const at of shuffledPositions(pool.length, next)) { + const id = pool[at]; + if (seen.has(id) || exclude?.has(id)) continue; + seen.add(id); + if (avoid?.has(id)) held.push(id); + else fresh.push(id); + if (fresh.length === want) return fresh; + } + // Too few games besides the ones on screen: make up the number with those, + // in the order they came up. + return [...fresh, ...held.slice(0, want - fresh.length)]; +} + +/** Whether a record may come up at all. */ +export function isEligible(r: GameRecord, { type, includeDead }: PoolOptions): boolean { + if (r.status !== "active") return false; + // Reviewed and found unsafe: never suggested, whatever the settings. + if (safeClass(r.safe) === "n") return false; + if (r.is_dead && !includeDead) return false; + return type === "any" || r.type_game === type; +} + +/** + * The appids a roll draws from. Read off appidIndex rather than the records: + * it holds exactly one entry per appid and none for a record without one, + * which is what a /games/ link needs. + */ +export function buildPool(data: Catalogue, opts: PoolOptions): string[] { + const out: string[] = []; + for (const [appid, i] of data.appidIndex) { + const r = data.records[i]; + if (r && isEligible(r, opts)) out.push(appid); + } + return out; +} + +/** The count control's value, kept to 1..MAX_PICKS. */ +export function clampCount(n: number): number { + return Number.isFinite(n) ? Math.min(MAX_PICKS, Math.max(1, Math.trunc(n))) : MAX_PICKS; +} diff --git a/web/src/lib/random-store.test.ts b/web/src/lib/random-store.test.ts new file mode 100644 index 00000000..38f84cc6 --- /dev/null +++ b/web/src/lib/random-store.test.ts @@ -0,0 +1,131 @@ +import { describe, expect, it } from "vitest"; +import { buildIndex } from "./data-store"; +import { RandomPicks } from "./random.svelte"; +import type { RandomSource } from "./random-pick"; +import { SKELETON_TEMPLATE, type GameRecord } from "./schema"; + +function xorshift(seed: number): RandomSource { + let x = seed | 0 || 1; + return () => { + x ^= x << 13; + x ^= x >>> 17; + x ^= x << 5; + return x >>> 0; + }; +} + +function game(appid: number, overrides: Partial = {}): GameRecord { + return { + ...SKELETON_TEMPLATE, + link: `https://store.steampowered.com/app/${appid}/`, + name: `Game ${appid}`, + type_game: appid % 2 ? "offline" : "online", + ...overrides, + }; +} + +function catalogue(records: GameRecord[]) { + return { records, appidIndex: buildIndex(records) }; +} + +const GAMES = Array.from({ length: 40 }, (_, i) => game(i + 1)); + +describe("the /random picks", () => { + it("rolls once when the catalogue arrives, and never again by itself", () => { + const picks = new RandomPicks(xorshift(1)); + picks.rollOnce(catalogue(GAMES)); + const first = picks.appids; + expect(first).toHaveLength(5); + // A revalidation hands over a new catalogue object; the picks stay. + picks.rollOnce(catalogue([...GAMES])); + expect(picks.appids).toBe(first); + }); + + it("rolls a set that avoids the games on screen", () => { + const picks = new RandomPicks(xorshift(2)); + const data = catalogue(GAMES); + picks.roll(data); + for (let i = 0; i < 50; i++) { + const before = new Set(picks.appids); + picks.roll(data); + expect(picks.appids).toHaveLength(5); + expect(picks.appids.some((appid) => before.has(appid))).toBe(false); + } + }); + + it("keeps the first picks for a smaller count, and adds to them for a larger one", () => { + const picks = new RandomPicks(xorshift(3)); + const data = catalogue(GAMES); + picks.roll(data); + const five = [...picks.appids]; + picks.setCount(3, data); + expect(picks.appids).toEqual(five.slice(0, 3)); + picks.setCount(5, data); + expect(picks.appids.slice(0, 3)).toEqual(five.slice(0, 3)); + expect(new Set(picks.appids).size).toBe(5); + picks.setCount(9, data); + expect(picks.count).toBe(5); + }); + + it("rolls again within a new type", () => { + const picks = new RandomPicks(xorshift(4)); + const data = catalogue(GAMES); + picks.roll(data); + picks.setType("offline", data); + const shown = picks.resolve(data); + expect(shown).toHaveLength(5); + for (const { record } of shown) expect(record.type_game).toBe("offline"); + }); + + it("brings dead games in only when asked", () => { + const data = catalogue(GAMES.map((g, i) => (i < 30 ? { ...g, is_dead: true } : g))); + const picks = new RandomPicks(xorshift(5)); + for (let i = 0; i < 20; i++) { + picks.roll(data); + for (const { record } of picks.resolve(data)) expect(record.is_dead).toBe(false); + } + picks.setIncludeDead(true, data); + let sawDead = false; + for (let i = 0; i < 20 && !sawDead; i++) { + picks.roll(data); + sawDead = picks.resolve(data).some(({ record }) => record.is_dead); + } + expect(sawDead).toBe(true); + }); + + it("uses settings chosen before the catalogue arrived for the first roll", () => { + const picks = new RandomPicks(xorshift(6)); + picks.setCount(2); + picks.setType("online"); + expect(picks.appids).toEqual([]); + const data = catalogue(GAMES); + picks.rollOnce(data); + const shown = picks.resolve(data); + expect(shown).toHaveLength(2); + for (const { record } of shown) expect(record.type_game).toBe("online"); + }); + + it("drops a pick that left the catalogue or turned unsafe, without rolling", () => { + const picks = new RandomPicks(xorshift(7)); + picks.roll(catalogue(GAMES)); + const [a, b, c, d, e] = picks.appids; + const next = catalogue( + GAMES.filter((g) => !g.link.includes(`/app/${a}/`)).map((g) => + g.link.includes(`/app/${c}/`) ? { ...g, safe: "n" as const } : g, + ), + ); + expect(picks.resolve(next).map((p) => p.appid)).toEqual([b, d, e]); + expect(picks.appids).toEqual([a, b, c, d, e]); + }); + + it("shows what a small pool has, and nothing from an empty one", () => { + const picks = new RandomPicks(xorshift(8)); + const three = catalogue(GAMES.slice(0, 3)); + picks.roll(three); + expect(picks.appids).toHaveLength(3); + picks.roll(three); + expect(new Set(picks.appids).size).toBe(3); + picks.roll(catalogue(GAMES.map((g) => ({ ...g, is_dead: true })))); + expect(picks.appids).toEqual([]); + }); +}); diff --git a/web/src/lib/random.svelte.ts b/web/src/lib/random.svelte.ts new file mode 100644 index 00000000..0df71cc0 --- /dev/null +++ b/web/src/lib/random.svelte.ts @@ -0,0 +1,109 @@ +/** + * The picks /random shows, kept for the session. + * + * Module-level, like filters.svelte.ts, so opening a game and coming Back + * shows the same games rather than a new roll. Memory only, on purpose: the + * Privacy Policy lists every key the app stores, and editing it changes the + * document's hash, which asks every reader to accept the terms again. A reload + * rolls anew, which is what reloading a random page should do anyway. + * + * The picks are appids, resolved against whichever catalogue is current, so a + * revalidation that brings new data never re-rolls: it only drops a pick that + * left the catalogue or no longer qualifies. Nothing tops a dropped pick back + * up - that would be a roll the reader did not ask for. + */ +import { + MAX_PICKS, + buildPool, + clampCount, + isEligible, + samplePicks, + type Catalogue, + type PoolOptions, + type RandomSource, + type TypeChoice, +} from "./random-pick"; +import type { GameRecord } from "./schema"; + +export interface ShownPick { + appid: string; + record: GameRecord; +} + +export class RandomPicks { + count = $state(MAX_PICKS); + type = $state("any"); + includeDead = $state(false); + /** In display order. Replaced whole, never mutated. */ + appids = $state.raw([]); + + #rolled = false; + readonly #next: RandomSource | undefined; + + /** `next` replaces the crypto source, for tests only. */ + constructor(next?: RandomSource) { + this.#next = next; + } + + get options(): PoolOptions { + return { type: this.type, includeDead: this.includeDead }; + } + + /** The picks still in `data` that still qualify, in order. Deterministic, + * so it is safe inside a $derived. */ + resolve(data: Catalogue): ShownPick[] { + const opts = this.options; + const out: ShownPick[] = []; + const seen = new Set(); + for (const appid of this.appids) { + const i = data.appidIndex.get(appid); + const record = i === undefined ? undefined : data.records[i]; + if (!record || seen.has(appid) || !isEligible(record, opts)) continue; + seen.add(appid); + out.push({ appid, record }); + } + return out; + } + + /** The first roll, once the catalogue is here; a no-op ever after. */ + rollOnce(data: Catalogue): void { + if (!this.#rolled) this.roll(data); + } + + /** A new set, avoiding the games on screen while enough others remain. */ + roll(data: Catalogue): void { + const shown = new Set(this.resolve(data).map((p) => p.appid)); + this.appids = samplePicks(buildPool(data, this.options), this.count, { avoid: shown, next: this.#next }); + this.#rolled = true; + } + + /** Fewer keeps the first ones; more adds new games beside the ones shown. + * Without a catalogue yet it only records the choice for the first roll. */ + setCount(n: number, data?: Catalogue): void { + this.count = clampCount(n); + if (!data) return; + const kept = this.resolve(data) + .slice(0, this.count) + .map((p) => p.appid); + const missing = this.count - kept.length; + this.appids = + missing > 0 + ? [...kept, ...samplePicks(buildPool(data, this.options), missing, { exclude: new Set(kept), next: this.#next })] + : kept; + this.#rolled = true; + } + + /** A different type changes which games qualify, so it rolls again. */ + setType(type: TypeChoice, data?: Catalogue): void { + this.type = type; + if (data) this.roll(data); + } + + /** As setType: the pool changes, so the picks do too. */ + setIncludeDead(on: boolean, data?: Catalogue): void { + this.includeDead = on; + if (data) this.roll(data); + } +} + +export const randomPicks = new RandomPicks(); diff --git a/web/src/routes/+page.svelte b/web/src/routes/+page.svelte index 639522c8..f9c2a1ae 100644 --- a/web/src/routes/+page.svelte +++ b/web/src/routes/+page.svelte @@ -7,6 +7,7 @@ import Trash2 from "@lucide/svelte/icons/trash-2"; import TrendingUp from "@lucide/svelte/icons/trending-up"; import ArrowRight from "@lucide/svelte/icons/arrow-right"; + import Dices from "@lucide/svelte/icons/dices"; import { games, removedGames } from "#lib/games.svelte.js"; import { computeKpis, countBy, topByPlayers } from "#lib/stats.js"; import { i18n } from "#lib/i18n.svelte.js"; @@ -20,6 +21,7 @@ import EChart from "#lib/charts/EChart.svelte"; import { chartTheme, gridBox } from "#lib/chart-theme.js"; import Seo from "#lib/common/Seo.svelte"; + import Button from "#lib/ui/Button.svelte"; const t = i18n.t; @@ -73,7 +75,14 @@ subtitle={games.data ? t("dashboard.subtitle", { count: formatNumber(kpis.total) }) : t("dashboard.seoDescription")} -/> +> + {#snippet actions()} + + {/snippet} + games.refetch()}>
diff --git a/web/src/routes/random/+page.svelte b/web/src/routes/random/+page.svelte new file mode 100644 index 00000000..f5a8cab3 --- /dev/null +++ b/web/src/routes/random/+page.svelte @@ -0,0 +1,229 @@ + + + + + + {#snippet actions()} + + + {/snippet} + + + +
+
+

{t("random.countLabel")}

+
+ {#each PICK_COUNTS as n (n)} + + {/each} +
+
+ +
+

{t("detail.labelType")}

+
+ {#each TYPES as option (option.value)} + + {/each} +
+
+ + +
+ +

{announcement}

+ + games.refetch()}> + {#if pool.length === 0} +
+

{t("random.noMatch")}

+
+ {:else} +

+ {t("random.pool", { count: pool.length, total: formatNumber(pool.length) })} +

+ + {/if} +
diff --git a/web/src/routes/sitemap.xml/+server.ts b/web/src/routes/sitemap.xml/+server.ts index 249cc86a..87edcc75 100644 --- a/web/src/routes/sitemap.xml/+server.ts +++ b/web/src/routes/sitemap.xml/+server.ts @@ -33,6 +33,8 @@ export const prerender = true; const HINTS: Record = { "/": { freq: "daily", priority: "1.0" }, "/games": { freq: "daily", priority: "0.9" }, + // Mostly controls until the catalogue has loaded; a different roll every visit. + "/random": { freq: "monthly", priority: "0.4" }, "/top-online": { freq: "daily", priority: "0.8" }, "/top-offline": { freq: "daily", priority: "0.8" }, "/stats": { freq: "weekly", priority: "0.8" }, From 5981c24bcdb90ef75fd9f60246141c0d17dc9c5d Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 3 Nov 2026 19:27:44 +0700 Subject: [PATCH 2/4] feat(consent): Leave site on the terms screen; Decline quits the apps Web: a "Leave site" button on the terms card and on the declined notice. No page may open the browser's own start page (chrome://newtab, about:home), so lib/leave-site.ts goes back to the page before the site: history.go(-(navigation.currentEntry.index + 1)) steps over every entry of the site's contiguous same-origin run at once. history.go() is silent when there is nowhere to go, so a 1.5 s watchdog (cancelled by beforeunload, pagehide and popstate) shows "Nothing to go back to"; when every entry is the site's that shows at once, and closing the tab is a second, explicit click, because closing the last tab closes the browser window. Apps: Decline called getCurrentWindow().close(), which on Android resolves without closing anything (tao reports a destroyed window only from the Activity's onDestroy), so Decline did nothing there. It now calls exit() from @tauri-apps/api/app, which finishes the activity on Android and ends the process on the desktop; the declined notice appears if the app is still alive 2 s later. default.json trades core:window:allow-close, which nothing else used, for core:app:allow-exit. The Leave button is web only. Co-Authored-By: Claude Opus 5.5 --- web/src-tauri/capabilities/default.json | 4 +- web/src/i18n/locales/en.json | 8 +- web/src/i18n/locales/vi.json | 8 +- web/src/lib/common/ConsentGate.svelte | 81 +++++++++++-- web/src/lib/consent-gate.test.ts | 35 ++++++ web/src/lib/leave-site.test.ts | 146 ++++++++++++++++++++++++ web/src/lib/leave-site.ts | 102 +++++++++++++++++ 7 files changed, 371 insertions(+), 13 deletions(-) create mode 100644 web/src/lib/consent-gate.test.ts create mode 100644 web/src/lib/leave-site.test.ts create mode 100644 web/src/lib/leave-site.ts diff --git a/web/src-tauri/capabilities/default.json b/web/src-tauri/capabilities/default.json index a0708b8e..70ad1cf4 100644 --- a/web/src-tauri/capabilities/default.json +++ b/web/src-tauri/capabilities/default.json @@ -1,13 +1,13 @@ { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "default", - "description": "Cross-platform capabilities for the main window. The frontend is a static SvelteKit app that fetches its data from free-steam-games.win over plain HTTP, so shell:open is the only native bridge it needs - it opens external links, which the webview otherwise blocks. The desktop-only updater lives in updater.json so the Android/iOS build, which does not compile that plugin, does not fail ACL resolution.", + "description": "Cross-platform capabilities for the main window. The frontend is a static SvelteKit app that fetches its data from free-steam-games.win over plain HTTP, so it needs two native bridges: shell:open, which opens external links the webview otherwise blocks, and app exit, which quits the app when the reader declines the terms (core:default does not include it, and the window's close() does nothing on Android). The desktop-only updater lives in updater.json so the Android/iOS build, which does not compile that plugin, does not fail ACL resolution.", "windows": [ "main" ], "permissions": [ "core:default", - "core:window:allow-close", + "core:app:allow-exit", "shell:allow-open" ] } diff --git a/web/src/i18n/locales/en.json b/web/src/i18n/locales/en.json index 0e0a9907..a0e2e700 100644 --- a/web/src/i18n/locales/en.json +++ b/web/src/i18n/locales/en.json @@ -17,7 +17,13 @@ "decline": "Decline", "declinedTitle": "You need to accept the terms", "declinedBody": "You must accept the licences, EULA, Privacy Policy, Disclaimer, and Terms of Use to use F2P Tracker.", - "back": "Back" + "back": "Back", + "leave": "Leave site", + "leaveNowhereTitle": "Nothing to go back to", + "leaveNowhereBody": "This site is the first page in this tab or window, so there is no earlier page to return to. Close it to leave.", + "leaveCloseTab": "Close this tab", + "leaveCloseWindow": "Close this window", + "leaveRefused": "The browser does not let a page close a tab that has a history. Close the tab or window yourself to leave." }, "humanCheck": { "title": "Checking you are human", diff --git a/web/src/i18n/locales/vi.json b/web/src/i18n/locales/vi.json index 4b220435..7180f706 100644 --- a/web/src/i18n/locales/vi.json +++ b/web/src/i18n/locales/vi.json @@ -17,7 +17,13 @@ "decline": "Từ chối", "declinedTitle": "Bạn cần chấp nhận điều khoản", "declinedBody": "Bạn phải chấp nhận các giấy phép, EULA, Chính sách quyền riêng tư, Tuyên bố miễn trừ và Điều khoản sử dụng để dùng F2P Tracker.", - "back": "Quay lại" + "back": "Quay lại", + "leave": "Rời trang", + "leaveNowhereTitle": "Không có trang nào để quay về", + "leaveNowhereBody": "Trang này là trang đầu tiên trong thẻ hoặc cửa sổ này, nên không có trang nào trước đó để quay về. Hãy đóng nó để rời đi.", + "leaveCloseTab": "Đóng thẻ này", + "leaveCloseWindow": "Đóng cửa sổ này", + "leaveRefused": "Trình duyệt không cho trang tự đóng một thẻ đã có lịch sử duyệt. Hãy tự đóng thẻ hoặc cửa sổ để rời đi." }, "humanCheck": { "title": "Đang xác minh bạn là người thật", diff --git a/web/src/lib/common/ConsentGate.svelte b/web/src/lib/common/ConsentGate.svelte index 9b77ec1c..eef1d3a9 100644 --- a/web/src/lib/common/ConsentGate.svelte +++ b/web/src/lib/common/ConsentGate.svelte @@ -3,6 +3,7 @@ import ShieldCheck from "@lucide/svelte/icons/shield-check"; import ChevronRight from "@lucide/svelte/icons/chevron-right"; import FileDiff from "@lucide/svelte/icons/file-diff"; + import House from "@lucide/svelte/icons/house"; import { page } from "$app/state"; import { consent } from "../consent.svelte"; import { CONSENT_DOCS, legalDocSlug } from "../legal"; @@ -10,6 +11,8 @@ import { i18n } from "../i18n.svelte"; import { isTauri } from "../external-open"; import { isUngatedPath } from "../gates"; + import { closeTab, leaveSite } from "../leave-site"; + import { pwa } from "../pwa-state.svelte"; import Button from "../ui/Button.svelte"; const t = i18n.t; @@ -17,6 +20,15 @@ let checked = $state(false); let declined = $state(false); + // The apps have no browser to go back in, and Decline already quits them. + // Settled when the component is created in the page; the server render that + // reads it never shows the gate (`open` waits for consent.hydrated). + const canLeave = !isTauri(); + + /** "nowhere": the site is the first page in this tab, so the only way out is + * closing it. "refused": the browser would not let the page do that either. */ + let leaving = $state<"idle" | "nowhere" | "refused">("idle"); + // /error/* and /legal/* stay readable before consent; lib/gates.ts says why, // and HumanCheck.svelte exempts exactly the same routes. const exempt = $derived(isUngatedPath(page.url.pathname)); @@ -89,36 +101,81 @@ // overflow-auto, so wheel events over it never reach the page beneath. async function decline() { - // Desktop: declining means you do not get the app, so quit it. On the web - // there is nothing to quit, so show a blocking notice with a way back. + // Apps: declining means you do not get the app, so quit it - with exit() + // from the app module (capability core:app:allow-exit), not the window's + // close(). On Android close() does nothing at all: tao reports a destroyed + // window only from the Activity's onDestroy, so Decline sat there dead. + // exit() finishes the activity there (back to the home screen) and ends + // the process on the desktop. On the web there is nothing to quit, so show + // a blocking notice with a way back. if (isTauri()) { try { - const { getCurrentWindow } = await import("@tauri-apps/api/window"); - await getCurrentWindow().close(); + const { exit } = await import("@tauri-apps/api/app"); + await exit(0); + // exit() can resolve before Android's closing transition has run. + // Still here a while later means it did not happen: say so. + setTimeout(() => (declined = true), 2000); return; } catch (err) { - console.error("ConsentGate: failed to close window", err); + console.error("ConsentGate: failed to quit the app", err); } } declined = true; } + + // Web only (canLeave): back to the page before the site; lib/leave-site.ts + // has why that is the nearest a page can get to the browser's start page. + function leave() { + leaveSite(window, () => (leaving = "nowhere")); + } + + function closeThisTab() { + if (!closeTab(window)) leaving = "refused"; + } - {#if !open} +{:else if leaving !== "idle"} +
+
+ +

{t("consent.leaveNowhereTitle")}

+

+ {leaving === "refused" ? t("consent.leaveRefused") : t("consent.leaveNowhereBody")} +

+
+ {#if leaving === "nowhere"} + + {/if} + + +
+
+
{:else if declined}

{t("consent.declinedTitle")}

{t("consent.declinedBody")}

- +
+ + {#if canLeave} + + {/if} +
{:else} @@ -206,6 +263,12 @@ {reviewing ? t("consent.acceptChanges") : t("consent.continue")} + {#if canLeave} + + {/if}
diff --git a/web/src/lib/consent-gate.test.ts b/web/src/lib/consent-gate.test.ts new file mode 100644 index 00000000..13abf47c --- /dev/null +++ b/web/src/lib/consent-gate.test.ts @@ -0,0 +1,35 @@ +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; +import { withoutBlockComments } from "./testing/source"; + +const gate = withoutBlockComments( + readFileSync(join(process.cwd(), "src", "lib", "common", "ConsentGate.svelte"), "utf-8"), +); +const capability = JSON.parse( + readFileSync(join(process.cwd(), "src-tauri", "capabilities", "default.json"), "utf-8"), +) as { permissions: string[] }; + +describe("declining the terms in the apps", () => { + it("quits through the app module, not the window", () => { + // getCurrentWindow().close() does nothing on Android, where Decline sat + // there dead. exit() finishes the activity. + expect(gate).toContain('import("@tauri-apps/api/app")'); + expect(gate).not.toContain('import("@tauri-apps/api/window")'); + }); + + it("is allowed to quit, and to do nothing more", () => { + // Without the permission exit() throws, and Decline only shows a notice. + expect(capability.permissions).toContain("core:app:allow-exit"); + // Closing a window from script was Decline's alone; nothing needs it now. + expect(capability.permissions).not.toContain("core:window:allow-close"); + }); +}); + +describe("leaving the site from the terms", () => { + it("offers Leave on the terms card and on the declined notice, on the web only", () => { + expect(gate.match(/onclick=\{leave\}/g)).toHaveLength(2); + expect(gate.match(/\{#if canLeave\}/g)).toHaveLength(2); + expect(gate).toContain("const canLeave = !isTauri();"); + }); +}); diff --git a/web/src/lib/leave-site.test.ts b/web/src/lib/leave-site.test.ts new file mode 100644 index 00000000..aef8548d --- /dev/null +++ b/web/src/lib/leave-site.test.ts @@ -0,0 +1,146 @@ +import { describe, expect, it, vi } from "vitest"; +import { LEAVE_TIMEOUT_MS, closeTab, leaveSite, type LeaveWindow } from "./leave-site"; + +interface FakeOptions { + /** history.length: every entry in the tab. */ + length: number; + /** navigation.entries().length; leave out for a browser without the API. */ + ours?: number; + /** navigation.currentEntry.index, null for no current entry. */ + index?: number | null; + /** Whether close() is accepted. */ + closes?: boolean; +} + +/** A window whose history, timers and events the test drives by hand. */ +function fakeWindow({ length, ours, index, closes = false }: FakeOptions) { + const listeners = new Map void>>(); + const timers = new Map void; timeout: number }>(); + let nextId = 1; + const go = vi.fn<(delta: number) => void>(); + const win = { + history: { length, go }, + navigation: + ours === undefined + ? undefined + : { + currentEntry: index === null ? null : { index: index ?? ours - 1 }, + entries: () => new Array(ours), + }, + closed: false as boolean, + close() { + if (closes) win.closed = true; + }, + setTimeout(handler: () => void, timeout: number) { + const id = nextId++; + timers.set(id, { handler, timeout }); + return id; + }, + clearTimeout(id: number) { + timers.delete(id); + }, + addEventListener(type: string, listener: () => void) { + if (!listeners.has(type)) listeners.set(type, new Set()); + listeners.get(type)!.add(listener); + }, + removeEventListener(type: string, listener: () => void) { + listeners.get(type)?.delete(listener); + }, + } satisfies LeaveWindow; + return { + win, + go, + fire(type: string) { + for (const listener of [...(listeners.get(type) ?? [])]) listener(); + }, + runTimers() { + for (const [id, timer] of [...timers]) { + timers.delete(id); + timer.handler(); + } + }, + timeouts: () => [...timers.values()].map((t) => t.timeout), + listening: () => [...listeners.values()].reduce((n, set) => n + set.size, 0), + }; +} + +describe("leaving the site", () => { + it("steps back past every page of the site, to the one before it", () => { + // New-tab page, then three entries of ours (a legal document among them). + const tab = fakeWindow({ length: 4, ours: 3, index: 2 }); + const nowhere = vi.fn(); + expect(leaveSite(tab.win, nowhere)).toBe("traversing"); + expect(tab.go).toHaveBeenCalledExactlyOnceWith(-3); + expect(tab.timeouts()).toEqual([LEAVE_TIMEOUT_MS]); + expect(nowhere).not.toHaveBeenCalled(); + }); + + it("says at once when every entry in the tab is the site's", () => { + const tab = fakeWindow({ length: 2, ours: 2 }); + const nowhere = vi.fn(); + expect(leaveSite(tab.win, nowhere)).toBe("nowhere"); + expect(nowhere).toHaveBeenCalledOnce(); + expect(tab.go).not.toHaveBeenCalled(); + expect(tab.timeouts()).toEqual([]); + }); + + it("says so later when the only other entries are forward ones", () => { + // The reader went on to another site and came Back: go(-1) is out of + // range, and the browser answers that with silence. + const tab = fakeWindow({ length: 2, ours: 1, index: 0 }); + const nowhere = vi.fn(); + leaveSite(tab.win, nowhere); + expect(tab.go).toHaveBeenCalledWith(-1); + expect(nowhere).not.toHaveBeenCalled(); + tab.runTimers(); + expect(nowhere).toHaveBeenCalledOnce(); + expect(tab.listening()).toBe(0); + }); + + it.each(["beforeunload", "pagehide", "popstate"])("stands the watchdog down on %s", (event) => { + const tab = fakeWindow({ length: 3, ours: 1, index: 0 }); + const nowhere = vi.fn(); + leaveSite(tab.win, nowhere); + tab.fire(event); + expect(tab.timeouts()).toEqual([]); + expect(tab.listening()).toBe(0); + tab.runTimers(); + expect(nowhere).not.toHaveBeenCalled(); + }); + + it("ignores a second click while the first is under way", () => { + const tab = fakeWindow({ length: 3, ours: 1, index: 0 }); + leaveSite(tab.win, vi.fn()); + expect(leaveSite(tab.win, vi.fn())).toBe("traversing"); + expect(tab.go).toHaveBeenCalledOnce(); + // Brought back from the back/forward cache: a new click works again. + tab.fire("pagehide"); + leaveSite(tab.win, vi.fn()); + expect(tab.go).toHaveBeenCalledTimes(2); + }); + + it("takes one step back without the Navigation API", () => { + const tab = fakeWindow({ length: 3 }); + leaveSite(tab.win, vi.fn()); + expect(tab.go).toHaveBeenCalledWith(-1); + + const fresh = fakeWindow({ length: 1 }); + const nowhere = vi.fn(); + expect(leaveSite(fresh.win, nowhere)).toBe("nowhere"); + expect(nowhere).toHaveBeenCalledOnce(); + expect(fresh.go).not.toHaveBeenCalled(); + }); + + it("takes one step back when the API has no current entry", () => { + const tab = fakeWindow({ length: 3, ours: 2, index: null }); + leaveSite(tab.win, vi.fn()); + expect(tab.go).toHaveBeenCalledWith(-1); + }); +}); + +describe("closing the tab", () => { + it("reports whether the browser agreed", () => { + expect(closeTab(fakeWindow({ length: 1, closes: true }).win)).toBe(true); + expect(closeTab(fakeWindow({ length: 2 }).win)).toBe(false); + }); +}); diff --git a/web/src/lib/leave-site.ts b/web/src/lib/leave-site.ts new file mode 100644 index 00000000..f0e61f83 --- /dev/null +++ b/web/src/lib/leave-site.ts @@ -0,0 +1,102 @@ +/** + * "Leave site" on the first-run terms screen. + * + * A page cannot open the browser's own start page: chrome://newtab, about:home + * and edge://newtab are all refused to websites. The closest thing is the page + * this tab showed before the site - the new-tab page when the address was typed + * there, the search results when the reader came from a search - so that is + * where this goes. + * + * The Navigation API (Baseline since 2026-01) knows this site's run of entries + * in the tab: entries() is the contiguous same-origin stretch around the + * current entry, other documents of this origin and SvelteKit's own pushState + * entries included, and currentEntry.index is the position in it. So + * history.go(-(index + 1)) lands on the entry just before the site, in one + * step, however many of the site's own pages (a legal document, say) came in + * between. Without the API it is one step back, which may land on one of the + * site's pages; the reader clicks again. + * + * history.go() says nothing when there is nowhere to go - the foreign entries + * may all be FORWARD ones (the reader went on to another site and came back) - + * so a watchdog calls onNowhere if the page is still here LEAVE_TIMEOUT_MS + * later. beforeunload (a traversal leaving the document has started), pagehide + * (the page is going, into the back/forward cache too) and popstate (a landing + * inside the document, the legacy path) cancel it. Timers freeze in the + * back/forward cache and resume on restore, so pagehide clears it whether or + * not the page is kept: a page brought back by Forward must not then claim it + * had nowhere to go. + * + * When every entry is the site's (the tab, or the installed app's window, was + * opened on it) there is nothing to go back to, and onNowhere runs at once. + * Closing is then a separate, deliberate click (closeTab): closing the last tab + * closes the window, and the browser with it, which "leave this site" never + * asked for. + */ +export const LEAVE_TIMEOUT_MS = 1500; + +type LeaveEvent = "beforeunload" | "pagehide" | "popstate"; +const SETTLED: readonly LeaveEvent[] = ["beforeunload", "pagehide", "popstate"]; + +/** The parts of `window` this needs; the real window satisfies it as it is. */ +export interface LeaveWindow { + readonly history: { readonly length: number; go(delta: number): void }; + readonly navigation?: { + readonly currentEntry: { readonly index: number } | null; + entries(): readonly unknown[]; + }; + readonly closed: boolean; + close(): void; + setTimeout(handler: () => void, timeout: number): number; + clearTimeout(id: number): void; + addEventListener(type: LeaveEvent, listener: () => void): void; + removeEventListener(type: LeaveEvent, listener: () => void): void; +} + +export type LeaveStart = "traversing" | "nowhere"; + +// A second click while the first traversal is starting must neither arm a +// second watchdog nor step back twice. +const watching = new WeakSet(); + +/** Back to the page before this site. `onNowhere` runs now when there is none, + * or later when the traversal never started. */ +export function leaveSite(win: LeaveWindow, onNowhere: () => void): LeaveStart { + if (watching.has(win)) return "traversing"; + + const nav = win.navigation; + const current = nav?.currentEntry; + let delta = -1; + if (nav && current) { + if (win.history.length <= nav.entries().length) { + onNowhere(); + return "nowhere"; + } + delta = -(current.index + 1); + } else if (win.history.length <= 1) { + onNowhere(); + return "nowhere"; + } + + let timer = 0; + const settle = () => { + win.clearTimeout(timer); + for (const type of SETTLED) win.removeEventListener(type, settle); + watching.delete(win); + }; + watching.add(win); + for (const type of SETTLED) win.addEventListener(type, settle); + timer = win.setTimeout(() => { + settle(); + onNowhere(); + }, LEAVE_TIMEOUT_MS); + win.history.go(delta); + return "traversing"; +} + +/** Close the tab; true when the browser agreed. A script may close only a tab + * whose history holds this one page (or one a script opened), and `closed` + * turns true at once when the browser accepts. */ +export function closeTab(win: Pick): boolean { + win.close(); + return win.closed; +} From 4c987036e2a7bbd4a88385b3dbb8bb3fff928e3e Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 3 Nov 2026 19:27:56 +0700 Subject: [PATCH 3/4] docs: random games and Leave site CLAUDE.md: why /random keeps its picks in memory and only the reader rolls, the crypto sampling (not Math.random), why the route is top-level, and the base key a plural needs; how Leave site finds the page before the site, the watchdog and its three cancel events, the deliberate second click to close, and why Decline quits through exit(). Both READMEs list the random page and its modules. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 41 +++++++++++++++++++++++++++++++++++++++++ README.md | 1 + web/README.md | 4 +++- 3 files changed, 45 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 68e8e95a..9a292ae7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1118,6 +1118,28 @@ scraping pipeline (`scripts/`) driven by GitHub Actions. The gate renders only after `consent.hydrated`: rendered before storage was read, it was baked into every prerendered page and flashed for returning visitors. +- **Declining or leaving at the gate.** In the apps Decline calls `exit()` from + `@tauri-apps/api/app` (capability `core:app:allow-exit` in + `capabilities/default.json`), never `getCurrentWindow().close()`: on Android + that resolves without closing anything (tao reports a destroyed window only + from the Activity's `onDestroy`), so Decline did nothing there before 2.5.0. + `exit()` finishes the activity on Android and ends the process on the + desktop; the declined notice appears if the app is still alive 2 s later. On + the web, "Leave site" (`lib/leave-site.ts`, hidden under Tauri) goes back to + the page before the site, because no page may open the browser's own start + page (`chrome://newtab`, `about:home`). Rules: + - It steps over ALL of the site's entries at once, + `history.go(-(navigation.currentEntry.index + 1))`: `entries()` is the + contiguous same-origin run, other documents and SvelteKit's pushState + entries included. Without the Navigation API it is one step back. + - `history.go()` is silent when there is nowhere to go (the foreign entries + can all be forward ones), so a 1.5 s watchdog shows "Nothing to go back + to"; `beforeunload`, `pagehide` and `popstate` cancel it. `pagehide` + matters: timers freeze in the back/forward cache and resume on restore. + - When every entry is the site's, closing the tab is a SECOND, explicit click + (`closeTab()`): closing the last tab closes the browser window with it. + - `consent-gate.test.ts` holds the exit import, the capability and the two + guarded Leave buttons; `leave-site.test.ts` holds the algorithm. - **`/welcome` is shown once, by the layout, and only to a visit that STARTED on `/`** (not a deep link, not `/#/…`, not mid-session), after consent and the human check. It @@ -1135,6 +1157,25 @@ scraping pipeline (`scripts/`) driven by GitHub Actions. from a game keeps the page and a changed filter starts again at page 1. The language filter (`?lang=`) offers the names stored in `languages`, Steam's English ones: data, never i18n keys. +- **`/random` keeps its picks in memory, and only the reader rolls.** + `lib/random.svelte.ts` holds appids, module-level so Back from a game shows + the same games, and NO `f2p:*` key: the Privacy Policy lists every stored + key, and editing it reopens the consent gate for everyone. Rules: + - A roll happens in a handler, or once in an `untrack`ed effect when the + catalogue first arrives - never in `$derived` or markup, which would roll + again on every revalidation or language switch. `resolve()` is the + deterministic part: it drops a pick that left the catalogue or stopped + qualifying, and nothing tops it back up. + - Randomness is `crypto.getRandomValues` with rejection sampling and a sparse + Fisher-Yates (`lib/random-pick.ts`). Never `Math.random`: SonarCloud + reports it as hotspot S2245, and an unreviewed hotspot fails the gate. + - Never a game marked unsafe or without an appid; dead games only on + request. The route is top-level on purpose: under `/games/` the header + search would stop jumping to /games, `isActive` would light Games too, and + the PWA's `globIgnores` would leave it out of the precache. + - A plural key needs its base key (`random.pool` beside `random.pool_one`): + `t()` falls back from `_other` to the base, and the i18n test requires + every literal key to exist. - **Search folds; storage never does.** `lib/search-fold.ts` `fold()` is NFKC plus hiragana to katakana, applied to BOTH sides of every search box (`/games`' Fuse index, the palette, /developers, /publishers, the anti-cheat diff --git a/README.md b/README.md index 888d58f4..fcd62917 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ A SvelteKit 2 / Svelte 5 app, prerendered and served by a Cloudflare Worker that - **Browse** — virtualised table (TanStack Virtual), filters for genre, type, platform, status, anti-cheat and safety, Fuse.js fuzzy search, sortable columns, 50/100/200/500/all pages. Filters live in the URL, so a filtered view can be shared. - **Charts** — Apache ECharts: dashboard KPIs, genres, platforms, languages, tags, anti-cheat (chart and a searchable index), reviews, player tiers, release years and catalogue growth, DRM/DLC, delisted games, plus a stats page (Metacritic, retention, games that went quiet). - **A page per game** — `/games/:appid` is prerendered for search engines and filled with live player counts and reviews in the browser. +- **Random games** — `/random` rolls one to five games when you cannot decide: online, offline or either, dead games only if you ask, never one marked unsafe. Roll again for a new set; opening a game and coming back keeps the picks. - **Fresh data, verified** — `data/index.json` carries a SHA-256 per shard; the app only caches a generation it could verify, keeps the last good one offline, and re-checks when you come back to the tab. - **Installable** — a web app you can install, with an offline mode and an update prompt. - **i18n** vi / en — auto-detected, switchable from the welcome page or Settings. diff --git a/web/README.md b/web/README.md index 76c6dd6a..99d35ec2 100644 --- a/web/README.md +++ b/web/README.md @@ -94,13 +94,15 @@ web/ │ ├── routes/ # pages; +layout, +error, sitemap.xml │ ├── params/ # route param matchers (legal document slugs) │ ├── lib/ -│ │ ├── *.svelte.ts # rune state: games, filters, prefs, i18n, pwa +│ │ ├── *.svelte.ts # rune state: games, filters, random picks, prefs, i18n, pwa │ │ ├── schema.ts # mirrors scripts/core/constants.py │ │ ├── games-loader.ts # verified shard generations, offline fallback │ │ ├── cache.ts # IndexedDB read/write │ │ ├── fallback-route.ts # re-renders routes served the SPA shell │ │ ├── consent.svelte.ts # legal consent, hashed per document │ │ ├── diff.ts # the line diff the consent gate shows +│ │ ├── leave-site.ts # the consent gate's "Leave site": back to the page before +│ │ ├── random-pick.ts # /random: crypto sampling and who may come up │ │ ├── analytics.ts # the beacon, appended only after consent │ │ ├── human-check.ts # the Turnstile check's rules (+ -state.svelte.ts, turnstile.ts) │ │ ├── gates.ts # the routes no first-run gate covers From b6e45d86ef2a0721e1eba75c16cb86485fa621ee Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 3 Nov 2026 19:27:56 +0700 Subject: [PATCH 4/4] release: v4.7.0 "Lucky Dip" / apps 2.5.0 Desktop and Android 2.4.1 -> 2.5.0 (package.json and its lock, tauri.conf.json, Cargo.toml, the f2p-tracker entry of Cargo.lock); repo public-facing version 4.6.1 -> 4.7.0. CHANGELOG: the random games page, Leave site, Decline quitting the Android app, and the 2026-11-03 dependency pass that waited in [Unreleased]. No legal document changed. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 42 +++++++++++++++++++++++++++++++++++ web/package-lock.json | 4 ++-- web/package.json | 2 +- web/src-tauri/Cargo.lock | 2 +- web/src-tauri/Cargo.toml | 2 +- web/src-tauri/tauri.conf.json | 2 +- 6 files changed, 48 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ceefcc75..17daa60f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,42 @@ All notable changes to this awesome noob repo will be documented here. ## [Unreleased] +## [v4.7.0] – 2026-11-03 (The "Lucky Dip" Edition) + +Two small additions. A Random games page picks up to five games from the +catalogue when you cannot decide what to play, and the first-run terms screen +gets a way out: on the website, "Leave site" takes you back to the page you +came from; in the apps, Decline now quits, which on Android it never did. No +legal document changed, so nobody is asked to accept the terms again. Desktop +and Android bumped `2.4.1` → `2.5.0`; repo public-facing version `4.6.1` → +`4.7.0`. The desktop app offers 2.5.0 through its updater once the release is +published; on Android, install the new APK over the old one. + +### ✨ Added + +- **Random games.** `/random`, in the sidebar, the menu and the command + palette, with a dice button on the dashboard, rolls one to five games (five + to start with): online, offline or either, dead games only when you ask for + them, and never one marked unsafe. Roll again for a set that avoids the + games on screen; a smaller count keeps the first ones, a larger one adds to + them. Opening a game and coming back keeps the picks, and nothing is + stored: a reload rolls anew. +- **Leave site**, on the first-run terms screen and on the notice after + Decline (website only). A page may not open the browser's own start page, + so it goes back to the page before the site - the new-tab page when you + typed the address there, the search results when you came from a search - + past every page of the site you opened in between. When the site is the + first page in its tab, it says so and offers to close the tab; that takes a + second click, because closing the last tab closes the browser window too. + +### 🐛 Fixed + +- Declining the terms quits the Android app. It did nothing at all: the app + asked its window to close, which does nothing on Android. Both apps now quit + through Tauri's own exit, and the declined notice appears if an app is ever + still open afterwards. The apps also drop a permission nothing uses any more + (closing a window from script) for the one quitting needs. + ### 🧰 Tooling & misc - Dependencies: SvelteKit 3.1.1 and adapter-static 4.0.1, Svelte 5.57.3, @@ -16,6 +52,12 @@ All notable changes to this awesome noob repo will be documented here. - The undici override is gone: wrangler 4.156.0's local simulator pins the patched undici 7.30.1 itself. +### 📚 Docs + +- `CLAUDE.md`: how `/random` rolls and why it stores nothing; how Leave site + finds the page before the site, and why Decline quits through `exit()`. +- Both READMEs list the random page and its modules. + ## [v4.6.1] – 2026-10-31 (The "Zip Tie" Edition) A security pass. The desktop app's updater takes the patched zip reader diff --git a/web/package-lock.json b/web/package-lock.json index f548d1fe..6219caf6 100644 --- a/web/package-lock.json +++ b/web/package-lock.json @@ -1,12 +1,12 @@ { "name": "free-steam-games-web", - "version": "2.4.1", + "version": "2.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "free-steam-games-web", - "version": "2.4.1", + "version": "2.5.0", "dependencies": { "@fontsource-variable/bricolage-grotesque": "^5.3.0", "@fontsource-variable/ibm-plex-sans": "^5.3.0", diff --git a/web/package.json b/web/package.json index 1059cd3d..08ed5884 100644 --- a/web/package.json +++ b/web/package.json @@ -1,7 +1,7 @@ { "name": "free-steam-games-web", "private": true, - "version": "2.4.1", + "version": "2.5.0", "type": "module", "imports": { "#lib/*": "./src/lib/*" diff --git a/web/src-tauri/Cargo.lock b/web/src-tauri/Cargo.lock index 83892da2..21bd019b 100644 --- a/web/src-tauri/Cargo.lock +++ b/web/src-tauri/Cargo.lock @@ -938,7 +938,7 @@ dependencies = [ [[package]] name = "f2p-tracker" -version = "2.4.1" +version = "2.5.0" dependencies = [ "serde", "serde_json", diff --git a/web/src-tauri/Cargo.toml b/web/src-tauri/Cargo.toml index b08d66b3..302e1ed3 100644 --- a/web/src-tauri/Cargo.toml +++ b/web/src-tauri/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "f2p-tracker" -version = "2.4.1" +version = "2.5.0" description = "Desktop wrapper around the Steam F2P Tracker web app" authors = ["poli0981"] license = "MIT" diff --git a/web/src-tauri/tauri.conf.json b/web/src-tauri/tauri.conf.json index fae6a1bf..a9433818 100644 --- a/web/src-tauri/tauri.conf.json +++ b/web/src-tauri/tauri.conf.json @@ -1,7 +1,7 @@ { "$schema": "https://schema.tauri.app/config/2", "productName": "F2P Tracker", - "version": "2.4.1", + "version": "2.5.0", "identifier": "io.github.poli0981.f2p-tracker", "build": { "beforeBuildCommand": "npm run build:desktop",