diff --git a/AGENTS.md b/AGENTS.md index c409145..1b33ed3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ src/client/ React app, service worker, manifest lens.ts — who sees which rows (focus, outstanding, next-to-expire); pure scripts/ build-feed.ts, build-static.ts, parse-fixture.ts (offline), refresh-sources.ts (fetches) serve.ts static server + /api/health -test/ 466 tests +test/ 480 tests fixtures// raw HTML + .expected.json per source — pinned, kept forever snapshots/ current page per source, rewritten by refresh — see its README ``` @@ -405,3 +405,12 @@ to an open page). Four things hold it up: `src/client/state/lens.ts`). Being pointed at a job you already finished is the bug either way. For the same reason "next to expire" reads the minimum end date rather than the head of the list, which under "doing first" is a different event entirely. +- **The page states its own age unprompted, and reads it off the data.** The footer says when event + data last refreshed on every load, not only past the two-day threshold — a page silent about its age + reads as current, and "how old is this?" has to be answerable before a countdown is worth trusting + (PRD F7). `freshness()` in `src/shared/feed.ts` is the one definition: it takes the newest + `lastSuccessAt` and **never `generatedAt`**, which is a build stamp that would call a + fixture-backed calendar minutes old, and it treats a game as only as fresh as its *oldest* source, + so one live wiki cannot vouch for a stalled sibling. Given that eight sources cannot be fetched + from CI at all (§ Scraping conduct), this disclosure is the only thing standing between a reader and + a confidently stale calendar — do not let a future change source it from the build clock. diff --git a/docs/FEEDBACK.md b/docs/FEEDBACK.md index 1ec6668..5b4defa 100644 --- a/docs/FEEDBACK.md +++ b/docs/FEEDBACK.md @@ -92,10 +92,14 @@ first thing to find out. making a request. 3. If Game8 is being refused, that is a scraping-conduct question before it is a code question — re-read `AGENTS.md` § Scraping conduct and decide, rather than working around it. -4. Regardless of cause: surface it in the UI. `Colophon.tsx` already receives `staleCount`, and - `App.tsx` computes `staleSources` at a two-day threshold. Verify a reader actually sees that - banner today, because if five of six games are on four-day-old fixtures, the app is currently - claiming more freshness than it has. +4. ~~Regardless of cause: surface it in the UI.~~ **Done.** The footer now states the data's age on + every load rather than only when something is wrong — `freshness()` in `src/shared/feed.ts`, read + by `Colophon.tsx`. Two things it settles, both of which were the "claiming more freshness than it + has" worry in concrete form: the age comes from the newest `lastSuccessAt` and never from + `generatedAt`, which is a build stamp that would call a fixture-backed calendar minutes old; and a + game is only as fresh as its *oldest* source, so Endfield's live wiki cannot vouch for its stalled + Game8 page. Lagging games are named rather than counted, because a count tells a reader nothing + they can act on — except when every game is behind, which collapses to one sentence. 5. Add a CI assertion that fails the build when a source has neither a snapshot nor a fixture newer than N days. A silent fallback to stale bytes should not be able to deploy. diff --git a/src/client/App.tsx b/src/client/App.tsx index 6901827..88e7631 100644 --- a/src/client/App.tsx +++ b/src/client/App.tsx @@ -27,7 +27,7 @@ import { outstanding, resolveFocus, } from "./state/lens.ts"; -import { clockFor, DAY, formatRemaining } from "../shared/time.ts"; +import { clockFor, formatRemaining } from "../shared/time.ts"; import { dailySummary, isDaily, resolveDaily } from "../shared/daily.ts"; import { GameMetaProvider, type MetaResolver } from "./state/gameMeta.tsx"; import { @@ -295,10 +295,6 @@ export function App() { ); } - const staleSources = state.feed.sources.filter( - (s) => s.lastSuccessAt === null || now - Date.parse(s.lastSuccessAt) > 2 * DAY, - ); - return ( @@ -503,7 +499,7 @@ export function App() {

)} - + {lastIgnored !== null && ( @@ -46,13 +56,14 @@ function siteFor(url: string): { name: string; url: string } { */ export function Colophon({ sources, - staleCount, + now, }: { sources: SourceHealth[]; - staleCount: number; + now: number; }) { const games = [...new Set(sources.map((s) => s.game))].map(gameMeta); const studios = [...new Set(games.map((g) => g.studio))]; + const { refreshedAt, stale } = freshness(sources, now); const sites = [...new Map(sources.map((s) => { const site = siteFor(s.url); @@ -68,10 +79,60 @@ export function Colophon({ from — check there before the last hours.

- {staleCount > 0 && ( + {/* + Stated on every load, not only when something is wrong. A page that says + nothing about its own age reads as current, and "how old is this?" is the + question a reader has to be able to answer before trusting a countdown + (PRD F7). The date is absolute *and* relative on purpose: the relative + half is what gets read, the absolute half is what can be checked. + */} +

+ Event data last refreshed{" "} + {refreshedAt === null ? ( + "— no source has been fetched yet." + ) : ( + <> + + {` — ${formatRemaining(now - Date.parse(refreshedAt))} ago.`} + + )} +

+ + {stale.length > 0 && ( + // Named per game rather than counted, because a count is not something a + // reader can act on: knowing *which* lane is behind tells them which + // source page to go and check, which is the whole remedy on offer. + // + // Except when the answer is "all of them", which is what a refresh that + // stopped running looks like. Ten names each repeating the same age is + // less readable than the count this replaced, and the headline above + // already gives the date — so that case gets a sentence, not a list.

- {staleCount} source{staleCount > 1 ? "s have" : " has"} not refreshed in - over two days. Some end dates may have moved. + {stale.length === games.length ? ( + `Nothing has refreshed in over two days, so any end date here may have moved.` + ) : ( + <> + {stale.length === 1 ? "This game has" : "These games have"} not + refreshed in over two days, so some of their end dates may have + moved:{" "} + {stale.slice(0, STALE_NAMES).map((s, i, shown) => ( + + {i > 0 && (i === shown.length - 1 && stale.length <= STALE_NAMES ? " and " : ", ")} + {gameMeta(s.game).name} + {s.lastSuccessAt === null + ? " (never)" + : ` (${formatRemaining(now - Date.parse(s.lastSuccessAt))} ago)`} + + ))} + {stale.length > STALE_NAMES && + ` and ${stale.length - STALE_NAMES} other game${ + stale.length - STALE_NAMES > 1 ? "s" : "" + }`} + {"."} + + )}

)} diff --git a/src/shared/feed.ts b/src/shared/feed.ts index e466680..ccf7b04 100644 --- a/src/shared/feed.ts +++ b/src/shared/feed.ts @@ -27,3 +27,64 @@ export const EventFeed = z.object({ export type SourceHealth = z.infer; export type EventFeed = z.infer; + +/** A game's data is stale past this age (PRD F7). */ +export const STALE_AFTER_MS = 48 * 60 * 60 * 1000; + +export interface Freshness { + /** + * When any source last had its bytes confirmed — the newest `lastSuccessAt`. + * + * Deliberately not `generatedAt`. The feed is rebuilt on every deploy whether + * or not a page was refetched, so a build stamp would report a calendar as + * minutes old while its events came from a fixture captured months ago. This + * reports the age of the *data*, which is the only thing a reader is trusting + * (PRD F7: never present stale data as current). + * + * Null only when no source has ever succeeded, which is a fresh checkout with + * no fixtures — not a state a reader reaches. + */ + refreshedAt: string | null; + /** Per game, oldest first: what has not refreshed inside `STALE_AFTER_MS`. */ + stale: Array<{ game: GameId; lastSuccessAt: string | null }>; +} + +/** + * How current this feed's data is, per game. + * + * Pure and clock-injected like everything else that a test needs to pin. One + * game can have several sources, and a game is only as fresh as its *oldest* + * one: if Endfield's wiki refreshed an hour ago but its Game8 page has been + * down for a week, some of that lane's rows are a week old and saying "fresh" + * would be the confident wrong answer this product exists to avoid. + */ +export function freshness( + sources: readonly SourceHealth[], + now: number, +): Freshness { + const oldestPerGame = new Map(); + let refreshedAt: string | null = null; + + for (const source of sources) { + const at = source.lastSuccessAt; + if (at !== null && (refreshedAt === null || at > refreshedAt)) { + refreshedAt = at; + } + + // `null` beats any date: a source that has never succeeded is the oldest + // thing a game can have, and must not be outvoted by a sibling that has. + // `undefined` is the separate case of no entry yet, which is why this reads + // the map once rather than asking `has` and then `get`. + const known = oldestPerGame.get(source.game); + if (known === undefined || (known !== null && (at === null || at < known))) { + oldestPerGame.set(source.game, at); + } + } + + const stale = [...oldestPerGame.entries()] + .filter(([, at]) => at === null || now - Date.parse(at) > STALE_AFTER_MS) + .map(([game, lastSuccessAt]) => ({ game, lastSuccessAt })) + .sort((a, b) => (a.lastSuccessAt ?? "").localeCompare(b.lastSuccessAt ?? "")); + + return { refreshedAt, stale }; +} diff --git a/test/custom-ui.test.tsx b/test/custom-ui.test.tsx index ecc0bcd..b941955 100644 --- a/test/custom-ui.test.tsx +++ b/test/custom-ui.test.tsx @@ -3,6 +3,7 @@ import { renderToStaticMarkup } from "react-dom/server"; import { EventForm } from "../src/client/components/CustomForms.tsx"; import { YourOwn } from "../src/client/components/YourOwn.tsx"; import { EventRow } from "../src/client/components/EventRow.tsx"; +import { Colophon } from "../src/client/components/Colophon.tsx"; import { GameMetaProvider } from "../src/client/state/gameMeta.tsx"; import { asDisplayEvent, @@ -177,3 +178,106 @@ describe("EventRow provenance", () => { expect(html).not.toContain(">yours<"); }); }); + +describe("Colophon freshness notice (PRD F7)", () => { + const NOW = Date.parse("2026-08-17T12:00:00.000Z"); + const HOUR = 60 * 60 * 1000; + + const fresh = { + sourceId: "genshin-game8-events", + game: "genshin" as const, + url: "https://game8.co/games/Genshin-Impact/archives/301601", + lastSuccessAt: new Date(NOW - 3 * HOUR).toISOString(), + eventCount: 9, + }; + + test("states when the data was refreshed, unprompted", () => { + // Always rendered, not only on a problem: a footer that says nothing about + // its own age reads as current. + const html = renderToStaticMarkup(); + expect(html).toContain("Event data last refreshed"); + expect(html).toContain("3h 0m ago"); + // The machine-readable instant is there for anyone checking the claim. + // Matched case-insensitively: React emits the JSX spelling verbatim, and + // HTML attribute names are case-insensitive, so either is correct. + expect(html).toMatch( + new RegExp(`