Browser back-button breaks cellblock state: mobile stuck on CELLMATE FOUND, desktop jumps to Scanning

bosun commented

2026-06-22 21:10:19 +02:00

Owner

Behavior (operator iPhone+desktop multiplayer playtest 2026-06-22, deployed round-18)

Browser back/forward navigation interacts badly with cellblock state:

Reproduction sequence (two-client versus session):

Connect mobile + desktop clients into multiplayer session
Both reach CELLMATE FOUND screen
On mobile: press browser backward button
On mobile: press browser forward button (returns to CELLMATE FOUND)
On mobile: press browser backward button again

Observed result:

Desktop client: jumps to "Scanning the yard for a cellmate..." (as if matchmaking re-started)
Mobile client: stays at "CELLMATE FOUND" screen regardless of further desktop navigation
Mobile screen "sticks" — no matter what navigation happens on desktop, mobile doesn't update

Side observation:

There are TWO browser navigation buttons visible (backward + forward — Safari toolbar)
Forward button seems to work as intended (returns to expected screen)
Backward button breaks navigation / causes state desync

Severity: substantive

Substrate-state desync between server-state and client-displayed-state. Mobile gets "stuck" with no apparent recovery without page reload. Affects multiplayer playability when either player accidentally uses browser back-button.

Likely root cause (NEEDS PROBE)

Cellblock client probably doesn't handle browser history API events (popstate). Browser back-button moves through history entries without notifying the app's state-machine; the app doesn't realize the user "navigated back" and doesn't update its UI accordingly.

Distinct from cellblock#93 (ws.onclose latent gap) — though related family. #93 is socket-drop-handler-missing; this is browser-history-event-handler-missing. Both produce "stuck" client state but via different mechanisms.

Fix-direction (Shipwright lane, probe-first)

Probe: does cellblock use any history.pushState / replaceState / popstate handling currently?
If no: add popstate listener that maps browser-history-changes to app-state transitions (or replaces history entries with current state to suppress browser-navigation entirely)
Consider: replace approach (replaceState every screen transition → browser-history never accumulates entries → back-button does nothing in-app) is simpler than handling popstate

Acceptance criteria

Probe identifies current history-API usage in cellblock client
Browser back/forward buttons either (a) do nothing in-app (replaceState approach) OR (b) trigger correct app-state transitions (popstate approach)
No client-state desync between server-state and displayed-state regardless of browser navigation
Versus playability preserved (other player doesn't get stuck if one navigates back)
Harness #81 extended (likely depends on #92 WS-mock for full versus coverage)

Cross-refs

cellblock#93 (ws.onclose; related but distinct mechanism — ws-drop vs browser-history)
cellblock#99 (mobile MP layout; same playtest session)
Operator playtest 2026-06-22 (post round-18, multi-client versus)

Anchor

2026-06-22 operator iPhone+desktop versus playtest. Empirically reproduced + side-observation distinguishing forward (works) vs backward (breaks).

## Behavior (operator iPhone+desktop multiplayer playtest 2026-06-22, deployed round-18) Browser back/forward navigation interacts badly with cellblock state: **Reproduction sequence** (two-client versus session): 1. Connect mobile + desktop clients into multiplayer session 2. Both reach CELLMATE FOUND screen 3. On mobile: press browser **backward** button 4. On mobile: press browser **forward** button (returns to CELLMATE FOUND) 5. On mobile: press browser **backward** button again **Observed result**: - Desktop client: jumps to "Scanning the yard for a cellmate..." (as if matchmaking re-started) - Mobile client: stays at "CELLMATE FOUND" screen regardless of further desktop navigation - Mobile screen "sticks" — no matter what navigation happens on desktop, mobile doesn't update **Side observation**: - There are TWO browser navigation buttons visible (backward + forward — Safari toolbar) - **Forward** button seems to work as intended (returns to expected screen) - **Backward** button breaks navigation / causes state desync ## Severity: substantive Substrate-state desync between server-state and client-displayed-state. Mobile gets "stuck" with no apparent recovery without page reload. Affects multiplayer playability when either player accidentally uses browser back-button. ## Likely root cause (NEEDS PROBE) Cellblock client probably doesn't handle browser history API events (popstate). Browser back-button moves through history entries without notifying the app's state-machine; the app doesn't realize the user "navigated back" and doesn't update its UI accordingly. Distinct from cellblock#93 (ws.onclose latent gap) — though related family. #93 is socket-drop-handler-missing; this is browser-history-event-handler-missing. Both produce "stuck" client state but via different mechanisms. ## Fix-direction (Shipwright lane, probe-first) 1. **Probe**: does cellblock use any history.pushState / replaceState / popstate handling currently? 2. If no: add popstate listener that maps browser-history-changes to app-state transitions (or replaces history entries with current state to suppress browser-navigation entirely) 3. Consider: replace approach (replaceState every screen transition → browser-history never accumulates entries → back-button does nothing in-app) is simpler than handling popstate ## Acceptance criteria 1. **Probe** identifies current history-API usage in cellblock client 2. Browser back/forward buttons either (a) do nothing in-app (replaceState approach) OR (b) trigger correct app-state transitions (popstate approach) 3. No client-state desync between server-state and displayed-state regardless of browser navigation 4. Versus playability preserved (other player doesn't get stuck if one navigates back) 5. Harness #81 extended (likely depends on #92 WS-mock for full versus coverage) ## Cross-refs - cellblock#93 (ws.onclose; related but distinct mechanism — ws-drop vs browser-history) - cellblock#99 (mobile MP layout; same playtest session) - Operator playtest 2026-06-22 (post round-18, multi-client versus) ## Anchor 2026-06-22 operator iPhone+desktop versus playtest. Empirically reproduced + side-observation distinguishing forward (works) vs backward (breaks).

bosun referenced this issue from a commit

2026-06-22 22:32:39 +02:00

feat(test): WS-mock harness substrate-foundation (#92)

shipwright referenced this issue

2026-06-22 22:44:00 +02:00

Client robustness gap: no ws.onclose / ws.onerror handler — accidental drops freeze the client #93

bosun referenced this issue from a commit

2026-06-22 23:24:48 +02:00

fix(client): ws.onclose/onerror disconnect recovery — Option A (#93)

shipwright self-assigned this

2026-06-22 23:35:04 +02:00

shipwright referenced this issue from a commit

2026-06-22 23:37:13 +02:00

fix(client): trap browser Back to suppress SPA unload + state desync (#109)

shipwright referenced this issue from a pull request that will close it,

2026-06-22 23:37:49 +02:00

fix(client): trap browser Back to suppress SPA unload + state desync (#109) #117

shipwright commented

2026-06-22 23:38:42 +02:00

Owner

AC-tick (pre-merge) — addressed in PR #117 (head bcaa4af):

✅ Probe — grep for pushState|replaceState|popstate|hashchange|history.|location.hash in client/src/ → empty. Zero history-API usage confirmed at source.
✅ Back/Forward do nothing in-app — suppression via a boot pushState sentinel + popstate re-push (AC2 option (a)). Note: pure replaceState (the tracker's lean) does not achieve this — with zero accumulated in-app entries there's nothing to replace away, so Back still unloads the page; the pushState-sentinel trap is what actually makes Back a same-document no-op. Full reasoning in the PR decision tree.
✅ No state desync — the document never unloads, so server-state ↔ displayed-state stay consistent. Test asserts screen/phase unchanged across two Back presses (the operator's back→fwd→back sequence).
✅ Versus playability preserved — Back no longer drops our socket, so the opponent is never re-queued by an accidental Back (the desktop "Scanning the yard" jump the operator saw was a consequence of the mobile socket dropping).
✅ Harness #81 extended — #109 versus.spec test drives history.back() against the #92 WS-mock; mutation-proven (remove the popstate listener → reds). 55/55 green, tsc clean.

Mechanism: pushState sentinel + popstate re-trap (NOT pure replaceState). No-op suppression (NOT Back→leave) per the operator's ratified direction. Awaiting Surveyor review + CI green before merge.

**AC-tick (pre-merge)** — addressed in PR #117 (head `bcaa4af`): 1. ✅ **Probe** — `grep` for `pushState|replaceState|popstate|hashchange|history.|location.hash` in `client/src/` → **empty**. Zero history-API usage confirmed at source. 2. ✅ Back/Forward **do nothing in-app** — suppression via a boot `pushState` sentinel + `popstate` re-push (AC2 option (a)). Note: pure `replaceState` (the tracker's lean) does *not* achieve this — with zero accumulated in-app entries there's nothing to replace away, so Back still unloads the page; the `pushState`-sentinel trap is what actually makes Back a same-document no-op. Full reasoning in the PR decision tree. 3. ✅ **No state desync** — the document never unloads, so server-state ↔ displayed-state stay consistent. Test asserts screen/phase unchanged across two Back presses (the operator's back→fwd→back sequence). 4. ✅ **Versus playability preserved** — Back no longer drops our socket, so the opponent is never re-queued by an accidental Back (the desktop "Scanning the yard" jump the operator saw was a *consequence* of the mobile socket dropping). 5. ✅ **Harness #81 extended** — `#109` `versus.spec` test drives `history.back()` against the #92 WS-mock; mutation-proven (remove the `popstate` listener → reds). 55/55 green, `tsc` clean. Mechanism: `pushState` sentinel + `popstate` re-trap (NOT pure `replaceState`). No-op suppression (NOT Back→leave) per the operator's ratified direction. Awaiting Surveyor review + CI green before merge.

bosun closed this issue

2026-06-23 09:44:50 +02:00

bosun referenced this issue from a commit

2026-06-23 09:44:51 +02:00

fix(client): browser Back-button trap via pushState-sentinel (#109)

bosun referenced this issue from a commit

2026-06-23 11:30:15 +02:00

feat(client): mobile-versus portrait layout — player-primary + opponent-compact (#99)

bosun referenced this issue

2026-06-24 00:55:46 +02:00

Desktop Back rapid double-click defeats pushState-sentinel trap (#109 regression) #144

bosun referenced this issue