Serve /api/city stale-while-revalidate, instrument the intro drop-off, stop the 404 noise

[wachen]

Three fixes that came straight out of the Cloudflare numbers for Jul 12 - Aug 10.

1. /api/city never blocks a visitor on the sheet again

/api/city averaged 2.7s and twice died at 8.3s with a 502 in the Aug 3-10 window. Cause: past the 5-minute freshness window, handleCity discarded the cached tally and made the visitor wait on the Apps Script round-trip. A perfectly usable cached entry was sitting there both times.

It now serves that entry immediately and refreshes in the background. Only a cold cache (first hit per colo per day) blocks.

One subtlety worth flagging for review: naively returning { ...cached, stale: true } on this path would have made /city/ show its "Live tally unavailable right now" banner (src/boot-city.jsx) on every request more than 5 minutes old. That banner means "upstream is down", not "a few minutes behind". So stale now needs CITY_STALE_MS (30 min) of failed refreshes, which is unreachable while background refreshes are working.

2. Two funnel events on the screen where the funnel actually leaks

The 7-day funnel was 74 game_started → 15 mode_chosen → 9 submit_attempted → 9 submit_succeeded. Submissions never fail once attempted, but four out of five people who pick a mode never reach the board, and nothing recorded said whether they bounced off the five-field intro gate on sight or gave up partway through it.

• intro_engaged fires once on the first keystroke in any field. Splits bounced-on-sight from gave-up-partway.
• intro_blocked fires when Start was pressed but validation refused, carrying which required fields were missing. This is the actionable one: it names the field that costs the conversion.

Field names only, never values. The Worker re-derives the list from INTRO_FIELDS rather than echoing it, so a forged beacon can only ever produce a subset in a fixed order.

I did not rename game_started/mode_chosen, even though they fire in the opposite order to what the names suggest (game_started = picked a mode, mode_chosen = cleared the intro gate). Renaming mid-event-week would orphan the existing baseline. Worth doing after the burn.

3. The 404 noise

45% of all requests and 82% of Worker invocations are scanner traffic. Some of it was self-inflicted: favicon.ico and apple-touch-icon-precomposed.png were 404ing because clients request those exact paths whether or not the HTML points at them, and sitemap.xml was missing. Adds those three plus llms.txt, with day-long cache headers.

favicon.ico is a real multi-size ICO (16/32/48, PNG-embedded) generated from apple-touch-icon.png. No robots.txt here on purpose: Cloudflare currently serves a synthetic one, and shadowing it could drop AI Crawl Control's directives.

The remaining scanner traffic is a WAF rule, which is dashboard config rather than a code change, so it is not in this PR.

Verification

• bun test — 132 pass, 0 fail. The 4 new /api/city tests fail by timeout against the pre-fix handler, and that timeout is precisely the blocked visitor the 502s came from.
• bun run scripts/build.js && git status --porcelain -- dist — clean.
• test/boot-smoke.mjs — all four pages pass.
• Both new beacons confirmed end to end in Chromium, for board and form mode, including that a second field edit does not re-emit intro_engaged.

Note for reviewers: this rebased onto #108, which unified the two Intro render branches and moved trackEvent into beacon.js as window.sendEvent. The auto-merge silently put mode="form" on both paths; it is now mode={board ? 'board' : 'form'}, which is what the two-mode browser check above pins.

🤖 Generated with Claude Code

https://claude.ai/code/session_01B94AdnTqEvYxFjRLXQUMBb

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	green-radius-game	73e4ec5	Commit Preview URL Branch Preview URL	Aug 10 2026, 11:20 PM

[wachen]

Review pass (high effort) — 5 findings, 3 fixed

The review turned up a live production bug on main that this PR did not introduce but would have widened.

Fixed: blocked beacon.js makes the game unplayable

#108 moved the funnel transport into beacon.js as window.sendEvent and called it directly from nine places. beacon.js is not guaranteed to load — a network blip, or an ad blocker matching its filename, which is a common filter-list target. The direct call then throws from a click handler, so the mode picker's first click dies and the game cannot be started at all. Confirmed in headless Chromium:

sendEvent defined? undefined
reached intro screen? inputs = 0
JS errors: ["pageerror: window.sendEvent is not a function"]

It reports nothing, because the client-error beacon lives in that same blocked file. That is why no telemetry ever surfaced it, and it is live right now.

This branch would have made it worse: intro_engaged put the same unguarded call in the keystroke path of every intro field, where the throw happens before set(v) and would have swallowed each typed character.

Fixed at the root — all ten call sites now route through trackEvent (src/core.jsx, first script on all four pages), which no-ops when the transport is absent. test/boot-smoke.mjs gains a beacon.js-blocked case, verified to fail against the unguarded form:

[FAIL] / (beacon.js blocked)
    - uncaught page error: window.sendEvent is not a function

One trap worth recording: the helper must not be named sendEvent. Top-level bindings in these classic scripts land on window, so that name would overwrite window.sendEvent with the wrapper and recurse forever. Both gotchas are now in CLAUDE.md.

Fixed: intro_engaged double-counted players

engagedRef was per-mount, and Intro unmounts on Back — so a player who stepped back and returned counted as two engaged players in the very funnel this PR adds. Now once per page load; verified one beacon across a Back-and-return.

Fixed: unsourced claim in llms.txt

"takes about 10 to 20 minutes" was supported by nothing in the repo. Removed rather than published as fact on the live domain.

Accepted, not fixed

• favicon.ico is an opaque square (generated from apple-touch-icon.png, which has no alpha) while favicon.svg is a transparent circle. Only affects clients that ignore the SVG link. A brand-colored square is a normal favicon treatment.
• sitemap.xml lastmod is hardcoded to 2026-08-10 and will rot. It is an advisory hint; automating it means adding build machinery for no real gain.

Verification

bun test 132 pass / 0 fail · compile gate clean · boot-smoke passes all five cases including the new one. Docs updated: docs/architecture.md (funnel section rewritten around trackEvent; /api/city SWR flow and the CITY_STALE_MS rationale) and CLAUDE.md.

🤖 Generated with Claude Code