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/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 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/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-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/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-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", diff --git a/web/src/i18n/locales/en.json b/web/src/i18n/locales/en.json index 49715ff7..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", @@ -64,6 +70,7 @@ "nav": { "dashboard": "Dashboard", "games": "Games", + "random": "Random games", "topOnline": "Top Online", "topOffline": "Top Offline", "charts": "Charts", @@ -197,6 +204,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..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", @@ -64,6 +70,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 +204,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/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; +} 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" },