Skip to content

Fix hidden OpenCode white page after browser refresh#460

Merged
danshapiro merged 9 commits into
mainfrom
fix/opencode-refresh-restore-white-page
Jun 21, 2026
Merged

Fix hidden OpenCode white page after browser refresh#460
danshapiro merged 9 commits into
mainfrom
fix/opencode-refresh-restore-white-page

Conversation

@danshapiro

Copy link
Copy Markdown
Owner

Root Cause

When a hidden OpenCode pane is hydrated after a browser refresh, two race conditions combine to produce a permanent white page:

  1. Unrecoverable viewport hydrate blocked by hidden check: When a replay gap exceeds the viewport window (replay_window_exceeded), the isUnrecoverableOpenCodeViewportHydrate predicate requires !hiddenRef.current. A hidden pane can never satisfy this condition, so it never enters the replacement path — it stays stuck showing nothing.

  2. Attach race before extensions registry loads: The "Create or attach to backend terminal" useEffect fires before the extensions registry is ready (shouldWaitForProviderBehavior is true). This causes a premature attach attempt that races with the OpenCode sidecar initialization, producing a broken terminal state.

Fix (two parts)

Part 1 — Allow hidden OpenCode viewport hydrations to enter replacement path:
Remove !hiddenRef.current from isUnrecoverableOpenCodeViewportHydrate in src/components/TerminalView.tsx. Hidden panes with replay gaps can now trigger beginOpenCodeReplacementAfterExit, which re-creates the terminal session once the pane becomes visible.

Part 2 — Guard create/attach useEffect against provider-behavior wait:
Add if (shouldWaitForProviderBehavior) return to the "Create or attach to backend terminal" useEffect. This prevents the attach race until the extensions registry has loaded, ensuring the OpenCode sidecar is ready before any terminal attach is attempted.

Tests

  • Unit: test/unit/client/components/TerminalView.lifecycle.test.tsx — 126 tests covering the hidden viewport hydration path and the provider-behavior wait guard.
  • E2e: test/e2e-browser/specs/opencode-restart-recovery.spec.ts — 5 Playwright tests covering OpenCode pane recovery across browser refresh, server restart, and hidden-pane association scenarios.

Rebase status

Rebased cleanly onto origin/main (54 commits behind). Only one main commit touched TerminalView.tsx (#444 electron link-clicking, unrelated area). No conflicts.

Kata: y1xn

@danshapiro danshapiro merged commit 1a04ce7 into main Jun 21, 2026
1 check passed
@danshapiro danshapiro deleted the fix/opencode-refresh-restore-white-page branch June 21, 2026 23:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants