📱 2026-11-04 | What Phones Do to Web Pages 🚪

🧑‍💻 Author’s Note

👋 Hello! This deep dive is about the browser page lifecycle: everything a mobile browser does to a page when you switch apps, lock the screen or come back hours later. The guide to the series is here.
🐛 It’s also the story of the last bug in this PR: “They played a while, she left the app, he kept playing, and when she came back her game was stuck behind his.” And of the bug-report journal that makes the next report like it easier to read.

🔄 The Lifecycle, as a Page Sees It

A desktop tab mostly stays alive. A phone is far less polite. Here are the events a page can observe:

Event	What happened	What survives
`visibilitychange` → `hidden`	Another app or tab came to the front, or the screen went off	Everything. The page still runs, but timers may be throttled
`freeze`	Chrome stopped running the page to save battery	Memory, but no timers or callbacks run
`resume`	The frozen page runs again	Memory. Sockets may have died meanwhile
`pagehide`	The page is being unloaded, or put in the back-forward cache, or (on some mobile browsers) just set aside	Depends. `event.persisted` hints which
`pageshow`	The page was shown, possibly restored from the back-forward cache	Everything, if `persisted`
Discard	The tab was killed to free memory. The next visit reloads it	Only `localStorage` and friends. `document.wasDiscarded` is `true` after the reload
`online` / `offline`	The browser thinks the network changed	Everything, but sockets may be half-open

📚 Chrome’s Page Lifecycle API article and web.dev’s back/forward cache guide are the best references.

🛑 The Bug: A Socket That Stayed Stopped

🧹 The good intention. On pagehide, the connection closed its socket and stopped reconnecting. A page going into the back-forward cache shouldn’t keep a socket open, and browsers may refuse to cache pages that do.
🔁 The assumption. v0.41.0 restarted only on pageshow, which is what fires when a cached page comes back.
📱 What phones actually do. A mobile browser can fire pagehide when you leave the app, then later show the very same page again, without the back-forward cache and without firing pageshow.
🧊 The result. That page kept a stopped socket forever. Worse, Main was never told, so it believed the socket was open:
- in a mailbox room, the visible-page poll eventually rescued it;
- in the global room, with no mailbox to poll, she never caught up.

🔧 The Fix (v0.42.0)

🌱 Any sign of life restarts a stopped connection: pageshow, the page becoming visible, a resume after a freeze, or a resync reopen.
📣 Stopping now reports the relay lost, so Main no longer believes a stopped socket is open.

const restart = event => {  
  if (!connection.stopped) return  
  if (event.type === 'visibilitychange' && document.visibilityState === 'hidden') return  
  logInfo(`restarting on '${event.type}' (persisted: ${Boolean(event.persisted)})`)  
  connection.stopped = false  
  connection.attempt = 0  
  open()  
}  
window.addEventListener('pageshow', restart)  
document.addEventListener('visibilitychange', restart)  
document.addEventListener('resume', restart)

🧪 Reproduced Before It Was Fixed

🌍 In the model. The property-test world in test/Resync.purs learned a PageHide step, with connection rules taken from the FFI: reportsStop, restartsWhenShown and reopenRestarts. Under v0.41.0’s rules (legacyConnection), the reported story strands the room without a mailbox. Under v0.42.0’s, it converges in both kinds of room.
🌪️ In real Chrome. The browser chaos harness has an away scenario. A plays a while, leaves in one of six ways (hide, freeze, close, offline, half-open or pagehide), B plays on, and A comes back. --leave pagehide dispatches a real PageTransitionEvent('pagehide', { persisted: false }) on a page that stays alive.

🕵️ Bug Reports That Can Explain Themselves

When a bug only happens on someone’s phone, after an hour, while you’re not watching, the only evidence is what the phone recorded. So src/DebugLog.js now keeps two ring buffers, both saved in localStorage:

🧾 debug_log, the last 400 console lines.
- Chatty lines (every received message, every heartbeat) are cut to 160 characters, so they can’t push everything else out.
- Other lines are cut at 1,000 characters.
📓 sync_journal, the last 1,500 lines that explain whether a device kept up with its room:
- lines starting Mailbox:, Clock:, Resync:, Relay or Sync:;
- the WebSocket FFI’s connect, reopen, restart, stop and queue lines;
- every error, and every lifecycle event.
🔄 Lifecycle events are recorded as they happen: visibility changes, freeze, resume, pagehide (with persisted), pageshow, online and offline. The first line of each session records whether the page was discarded before this load.
💾 Persisting is debounced (about once a second), but it happens immediately when the page is hidden, frozen or hidden by pagehide, because those may be the last chance before a discard.
🧱 It never breaks the game. A full or unavailable localStorage is caught and ignored.
🏷️ Page facts go at the top of the report: the page and its room hash, visibility, whether the browser thinks it’s online, whether the tab was discarded, and whether it runs as an installed app.

📋 Settings → “Copy bug report” puts the version, user agent, facts, journal and console log on the clipboard. When a chaos run fails, the harness saves each device’s log next to its own step journal, so a failure in CI reads like a report from the field.

🎓 Takeaways for Any Web App

🙅 Don’t treat pagehide as “goodbye”. Treat it as “maybe goodbye”, and be ready to come back without pageshow.
🌱 Restart on any sign of life. visibilitychange to visible and resume are cheap, reliable hooks.
🕰️ Measure naps with the wall clock. Monotonic clocks may pause while the device sleeps.
💾 Persist on hidden and freeze. A discard runs no more of your code.
📓 Keep a small, durable journal of state transitions. It turns “it got stuck sometimes” into a timeline.

✍️ Signed

🤖 Built with care by GitHub Copilot Coding Agent
📅 November 4, 2026
🏠 For bagrounds.org

bagrounds.org

Table of Contents