world-2026-hub/.agents/issues.md

Issues & Optimization Candidates

Tracked optimization proposals and known issues. Analyzed but not yet implemented.

---

Event-Driven Scheduling for Match State Transitions (2026-06-15)

Status: Analyzed, deferred (no implementation yet)

Issue

Latency in the Matches tab when a match transitions to "over" state. Currently, the system uses polling (OCC_TICK_MS = 60s) to check if any match has entered "over" status (either via JSON status==='finished' or clock reaching kickoff + window). This causes up to 60 seconds of delay between the actual state change and the UI update (the "Pendente de resultado" chip appearing on a match card).

Proposed Solution

Implement event-driven scheduling instead of polling:

• Calculate exact timestamps when each match will transition states (kickoff → "live", kickoff + window → "over")
• Use setTimeout to schedule precise callbacks for these moments
• Render the list only when a timeout fires
• Revalidate/reschedule timeouts when getData() updates (daily refresh)

Benefits

• Latency: Reduced from up to 60s to ~0s
• Efficiency: Zero CPU wasted on unnecessary checks between state changes
• Deterministic: Transition moments are calculable with precision

Technical Feasibility

✅ Viable. The matchState() function already computes state based on kickoff and window, so timestamps are known. Logic to manage ~200 timeouts (104 matches × 2 transitions) is straightforward but requires cleanup/reschedule logic on getData() updates.

Why Not Implemented Yet (Cost-Benefit Analysis)

Complexity vs. impact trade-off: The improvement is real but limited:

1. Limited real-world UX impact

   • The "match over but JSON not updated" state is transitory (~minutes), lasting only until the daily manual refresh lands
   • Most users either watch the hero (which updates every 1s and already flips to the next match instantly) or check the Matches tab after a refresh
   • Polling at 60s is already so infrequent (0.017 Hz) that CPU cost is negligible

2. Moderate implementation cost

   • Managing 200+ live timeouts and cleaning up old ones on data refresh adds complexity
   • Must handle race conditions: JSON update and timeout firing simultaneously
   • Adds another system to maintain/debug

3. Narrow use case

   • Would matter if thousands of simultaneous matches existed, or if users commonly left the Matches tab open for hours
   • Current tournament is 72 group matches + 32 knockout matches (104 total); no real-time data updates (daily manual refresh)

When to Implement

Only if:

• Latency in the Matches tab becomes a reported UX complaint
• The tournament adds real-time data feeds (WebSocket/API polling) instead of manual daily refresh
• Similar polling patterns accumulate elsewhere and warrant a systematic refactor

How to Implement (if revisited)

1. Create scheduleMatchStateChanges() in schedule.js
2. For each match, calculate kickoffTime and kickoffTime + matchWindowMs(match)
3. Schedule setTimeout callbacks for both transitions
4. On getData() refetch, cancel old timeouts and reschedule
5. Callback directly fires renderList()
6. Guard against duplicate timers (similar to startHeroClock pattern in app.js)

---

PWA Tier 2 — Service Worker + Offline (2026-06-16)

Status: Analyzed, deferred (Tier 1 shipped 2026-06-16 — see project-memory "PWA — installable app").

Context

The PWA install issue was delivered as Tier 1 (manifest + icons + meta tags), which already meets every acceptance criterion (installable, correct name/icon, standalone launch from the OS shortcut, no app-pipeline risk). Tier 2 — a service worker for offline launch and the strongest cross-browser "app feel" — was intentionally left out. It is not required for the install prompt in modern Chrome/Edge.

Why deferred (the real risk)

A naïve precaching SW would cache data/*.json and silently defeat the 2026-06-16 live-refresh system (the 90s results.json poll with cache:'no-store', plus the ?t=Date.now() cache-buster on every data fetch) — open tabs would stop seeing new scores. It would also make the "stale JS module" gotcha (#5) permanent (cached assets live until the cache name changes).

How to implement (if revisited) — constraints, not optional

1. Never cache data/*.json. Use network-only, or network-first with the cache only as an offline fallback (so an offline launch shows the last-seen results). The 90s poll must stay the owner of freshness.
2. Version the SW cache with a dedicated cache-name constant bumped on each deploy (there is no longer a DATA_VERSION to mirror — data freshness is handled by ?t=Date.now()); clean up old caches on activate — otherwise every code deploy risks serving stale JS forever (gotcha #5).
3. Register at the subpath (worldcup2026/sw.js) so the SW scope matches the deploy (gotcha #7); keep start_url/scope relative as they already are.
4. App-shell strategy: cache-first (versioned) for index.html + assets/css + assets/js + assets/icons; precache on install.
5. Verify the poll still updates an open tab with the SW active (the easy thing to regress).

When to implement

Only if offline launch / a fuller install experience is actually wanted, and only with the data-cache exclusion + cache-versioning above. Otherwise Tier 1 is sufficient.

---

Live Data Refresh — Stale Results Until Page Reload (2026-06-15)

Status: ✅ Implemented 2026-06-16 (Option A⁺ — "Fixed polling done right"). Full implementation (functions, files, the 3 reinforcements, the bracket-config.json piggyback, verification) is documented in project-memory.md → Architecture & Decisions → "Live data refresh — poll results.json without F5".

One-line problem it solved: an open tab loaded data/*.json once and never refetched, so a newly published results.json (daily push) only appeared after F5.

Key decisions worth keeping (rationale):

• Not a live-feed problem. results.json is a manual post-match push, so there is no new server data during a match — a faster "during live" poll buys nothing. A fixed 90s poll is correct; dynamic/state-based polling was rejected (complexity for no gain, double-schedule risk per gotcha #6).
• Cache-busting must use ?t=${Date.now()} + cache:'no-store' — a frozen per-tab constant would never refetch and Hostinger sends no cache headers. (As of 2026-06-18 the initial loadData() fetch also uses ?t=Date.now(); the old ?v=DATA_VERSION constant was removed.)
• Signature = full response text, not a finished-count (a count misses score corrections, stats backfill on an already-finished match, and added penalties).
• thirdPlaceAssignment lives in bracket-config.json, not results.json → on a detected change the poll refetches the config in the same cycle (it ships in the same daily push), avoiding a stale in-memory bracketConfig without per-tick config polling.

---