Omniscio

Blank-screen recovery button (survives a full React unmount)

The Reload Omniscio button that appears in the middle of the screen when the app's interface has vanished, so you can recover without closing the window and losing the forensic trail. Covers when it appears, what it does when you click it, why it survives a React unmount, and how to switch it off.

On this page

What it is

A visible "Reload Omniscio" button that appears in the centre of your screen when the Omniscio chat UI has vanished. It exists for the case where the React app silently unmounts and #root goes empty — the window stays open, the Minimise / Maximise / X controls still draw because Windows owns them natively, but the entire app surface (sidebar, chat, toolbar) is gone. Without this button your only recovery is closing the window and relaunching, which loses the forensic trail of what just happened.

The button is not a hotkey — that was a deliberate choice after a prior round where hotkey-based recovery couldn't reach the user. It's a literal DOM element you can click with the mouse. Same idea as the OS-drawn titlebar: a small chrome surface that survives whatever broke the rest of the window.

What you see

When the React app blanks for at least 1.5 seconds, a small dark card slides into view, centred on the screen:

┌─────────────────────────────────────┐
│  The window went blank. Click to    │
│  reload.                            │
│                                     │
│        ┌─────────────────┐          │
│        │   Reload Omniscio    │          │
│        └─────────────────┘          │
└─────────────────────────────────────┘

The card sits on top of everything else (z-index 2147483647 — the max signed-32-bit integer, used so no app stylesheet can accidentally cover it). The button is a rounded indigo pill, 44 px tall (the standard tap-target minimum), with a hover shade that darkens it slightly. Clicking it disables the button, changes its label to "Reloading…", and kicks off the recovery flow.

If React recovers on its own (the unmount turned out to be transient — e.g. a hot-reload re-mount succeeded), the card disappears the moment #root regains a child element. The card never stays up after the app has healed itself.

Where to find it

Nothing to open. The recovery card is not in any menu and has no Settings row of its own — it appears by itself, centred on the screen, once the app surface has been blank long enough. There is nothing to enable first. Switching it off is a per-window developer action rather than a setting; see Kill switches below.

How it behaves

When it appears

Two trigger conditions, both monitored every second by a MutationObserver + interval backstop:

  1. #root is empty. No child elements at all. This is what a React.lazy() chunk failure looks like after the suspense boundary gives up — the whole tree is detached. Grace period before the card appears: 1500 ms, so a normal cold mount (where React paints in a few hundred ms) never trips it.
  2. A chunk-load error fired AND the inline #app-loader is still visible inside #root. This is the "stuck on the loading dots forever" failure: a Vite content-hashed chunk 404'd, React never mounted past the inline pre-paint loader, and you'd otherwise sit there indefinitely. Grace period in this mode: 250 ms — once we've seen the chunk error, there's no point waiting.

Chunk-load errors are recognised from two sources: the capture-phase error listener (catches <script>-element load failures) and the unhandledrejection listener (catches dynamic-import promise rejections — ChunkLoadError, "Loading chunk N failed", "Failed to fetch dynamically imported module", "Importing a module script failed", "Unable to preload CSS for …"). That last one is not a JS chunk: Vite's preload helper fetches a lazy chunk's stylesheet through the same call, so a pruned content hash on assets/<chunk>.css rejects the import exactly like a missing module.

What it does on click

When you press the button, the in-renderer IIFE invokes the app:recover-blank-screen IPC with a small structured payload (trigger, blankMs, hadChunkError, rootChildCount, attempts, supportId). The main process handler then:

  1. Records [MANUAL-RECOVERY] into heartbeat.log with the current lastOp slot and the payload fields. This is the forensic marker that pairs with the existing [RENDER-GONE] / [STALL-CAUGHT] / [POST-MORTEM] family — see main-heartbeat.md for the full vocabulary.
  2. Dumps the heartbeat ring buffer to heartbeat-snapshot.log with the reason manual-recovery-blank-screen. That snapshots the last 10 ticks (≈ 50 seconds of pre-blank main-process state — lag P50/P99, RSS, IPC names) for the next-launch investigator. (It goes to the snapshot file, not heartbeat-final.log, because the app survived — a blank screen never killed the main process.)
  3. Clears the WebContents HTTP cache so a stale Vite chunk that caused the blank can't be served again from cache.
  4. Reloads the WebContents with reloadIgnoringCache(). The renderer process tears down and restarts; the guardian IIFE re-runs against the fresh page and the card disappears once React mounts.

If for any reason the IPC channel itself fails (the preload bridge missing, the main process unresponsive, a desktop-vs-mobile build mismatch), the guardian falls back to window.location.reload(). The user still gets a reload; the forensic trail is the only thing that's lost on that path.

When reloading does not help

Each click on Reload Omniscio adds one to a reload count that lives in the window's sessionStorage (and in memory, so a window that blocks storage still counts within one page life). The count survives the reload itself and is cleared the moment React has replaced the inline #app-loader — a slow boot that is still showing the loading dots keeps it. After the third reload that did not bring the app back, the fourth click does not reload. The card changes instead:

  • the message becomes "The window keeps going blank after reloading. Copy these details and send them to support.";
  • a details block appears with the support id (BS-<time>-<random>, minted once and kept in localStorage), support@omniscio.com, the reload count, whether a chunk-load error fired, how many elements #root holds, the page's protocol and host (never its path, query or #fragment — the fragment can carry a pairing token), and the browser string;
  • Copy details copies that block and says "Copied" only after the clipboard write succeeded;
  • the main button becomes Reload anyway, which reloads exactly as before and sends the count and support id.

The same attempts and supportId are written into the [MANUAL-RECOVERY] line in heartbeat.log (attempts=4 supportId="BS-…"), so a support id quoted in a report finds the matching heartbeat entry. A stored support id that is not in the BS-… shape is replaced rather than sent, and the main-process schema accepts only that shape, so nothing free-form reaches the log line. When the app heals and later blanks again, the card is rebuilt from the current count and shows the plain version.

Kill switches

  • Per-window opt-out: set window.__amcDisableBlankScreenGuardian = true in DevTools before the IIFE runs, or remove the <script> tag from index.html. The IIFE early-returns if the flag is set at install time. There is no runtime "turn it off after it's installed" — the install path is the gate.
  • No config flag. The guardian is unconditional in production builds. The cost is negligible (a MutationObserver on one element + one 1 s setInterval + two passive event listeners), and the failure mode it protects against — invisible app, no recovery affordance — is severe enough that opt-out from the user's perspective is not appropriate.

What it does NOT do

  • It does not restart the main process. A WebContents.reloadIgnoringCache() only reloads the renderer. If the underlying problem is a main-process hang (a [STALL-CAUGHT] in heartbeat.log with inFlightCount > 0), the reload may complete but the same hang can recur. The fix in that case is to close the Omniscio window entirely and relaunch — at which point the next-launch [POST-MORTEM] analyser surfaces the prior [MANUAL-RECOVERY] line so you know what triggered the close.
  • It does not preserve unsent draft messages, scroll position, or any volatile renderer state. The reload is a hard reset of the renderer; everything that wasn't already in SQLite (drafts auto-save every few seconds, so most of the time you lose at most a few words) is gone.
  • It does not appear on a slow cold-mount where React paints in 1500 ms+ but is still working. The 1500 ms grace is calibrated so a normal launch — even one slowed by parallel-worktree contention — never trips it. The chunk-error grace (250 ms) only fires AFTER a chunk-load error was actually observed.

This DOM guardian is the LAST line of defence — it only fires once the whole React tree has detached (#root empty) or React never mounted past the inline loader. A subtree chunk failure — e.g. the inbox approval pane (React.lazy) failing to load after a npm run dev rebuild while the rest of the app is fine — is caught one layer earlier by the app's React ErrorBoundary: when the thrown error matches isStaleChunkError, the boundary renders a friendly "A new version loaded — Reload" card in place of the failed subtree, and the rest of the app stays interactive. That includes the dev-window case where the renderer runs with live reload off, master updates a file the window already loaded, and a screen opened for the first time afterwards asks the old copy for a function it never had (The requested module '…' does not provide an export named '…'): only a reload brings the window's files back in step, so it gets the Reload card, never the generic crash card whose Try Again cannot recover. So the two recovery surfaces layer cleanly:

  • Subtree fails, app still mounted → the in-React ErrorBoundary card (no full reload needed unless you click Reload).
  • Whole app blanks / never mounts → this DOM guardian's "Reload Omniscio" card.

The boundary card's Reload first calls resetReloadGuardForManualReload() so a user-initiated reload isn't suppressed by the automatic crash-loop cap (the same preload-reload-guard caps the guardian respects). Critically, retry-import itself no longer does its own once-per-session location.reload() — that redundant third reload used to stick (suppressed-by-session-flag) and leave later staleness with NO recovery (the "regularly black/blank" reports on the desktop dev app + mobile). Recovery is now owned by preload-reload-guard (reload + cap + intent-restore) and these two cards.

A development-only hot-reload crash gets the same card. The boundary shows a card for a class of crash whose only recovery is a full reload, not only for a stale chunk. The dev-only React artifacts — a Fast-Refresh null store, a commit-phase DOM desync, a hook-count hot-swap, a stale lazy-component mount, and a Vite dep-reoptimize leaving two React generations live (isDevReactDepReoptimizeError: Cannot read properties of null (reading 'useMemo') thrown from a .vite/deps hook while renderWithHooks is on the stack) — self-heal on the next clean load and cannot occur in a production build. They used to show the generic "Something went wrong" crash card with a reference id and a "Report this" button, which invited a support ticket for something a reload fixes (Mark, 2026-11-14: tickets #2147/#2148, refs 45c3f1a9/ad3c3489). The boundary keeps them classified and reported (boundary-benign, with the crash id in the log), but renders the Reload card, whose button reloads the module graph. A genuine crash keeps the crash card, and nothing outside a dev build changes. Rule: ErrorBoundary.render shows the reload card when isStaleChunkError matches or componentDidCatch classified the crash as a development artifact.

What makes an error count as stale. A lazy view's module namespace arriving without the named export it was asked for is the shape to know about: lazyNamedView (src/renderer/src/lib/lazy-with-preload.ts, the shared factory behind every lazy() view in app/lazy-views.tsx) throws Stale chunk: <Name> export missing from module namespace for it, which is what isStaleChunkError reads. Until 2026-10-16 that shape threw a raw Cannot read properties of undefined (reading '<Export>') instead — the helper read the export with no guard — so the boundary could not recognise it: the user got the generic "Something went wrong" crash card rather than the reload card (seen on mobile web, after an update).

A chunk's stylesheet is part of the same class. Vite's preload helper fetches a lazy chunk's CSS with the module, and a stylesheet the server no longer has rejects the import with Unable to preload CSS for <url> — the identical stale-build situation, one asset over. It is in isStaleChunkError's list for that reason: left out, it showed the generic crash card and logged an ERROR-level crash report for a stylesheet 404 (seen on mobile web after a rebuild). A stylesheet failure that genuinely is a transient network blip is not treated differently — the lazy load has already spent its retries by the time the boundary sees it, and Reload is the same recovery the JS-module case gets.

A lazy read of the session store goes through one guarded loader. Fourteen places in the renderer load the session store on demand (boot prefetch, inbox prefetch, the channels bridge, the tasks and supermail launch paths, the KMS mention list, and the three boot intent restores). They all call loadSessionStoreModule() (src/renderer/src/lib/load-session-store.ts), which retries a torn load through retryDynamicImport and requires both the module namespace and its useSessionStore export, so the two failure shapes that used to reach the boundary as an opaque crash are now the tagged Stale chunk: error it already renders as a reload card. Reading the namespace directly is what Sentry issue 7850068227 reported: a dynamic import that resolved to undefined made the call site throw Cannot read properties of undefined (reading 'useSessionStore'). A test scans the renderer so a new bare read cannot come back.

A stale chunk is also a NON-crash where it is reported. The boundary tags a boundary-caught error that isStaleChunkError recognises as boundary-benign, so the main process writes a WARN line and skips the crash sinks — no Sentry event — exactly as it does for the ResizeObserver / monaco-Canceled / Firestore assertion classes. Before that same change the report kept the plain boundary tag, so a stale chunk still ran log.error + captureException and opened a fresh error-level Sentry issue under the chunk's name: naming the cause is not the same as stopping the report. A genuine render crash is untouched and still reports at ERROR with a Sentry event. Covered by tests/unit/lib/stale-chunk-boundary-report.test.tsx (card, WARN classification, and that positive control) and tests/unit/lib/lazy-with-preload.test.ts (the guard itself, including a discarded preload rejection staying handled so it cannot become a second, unhandledrejection-sourced report).

Reading order after a blank-screen incident

  1. Open heartbeat.log (Settings → Diagnostics → Main-Process Heartbeat → Reveal). Search for the most recent [MANUAL-RECOVERY] line. That marks the click that triggered recovery, including the blankMs (how long the screen was blank before you clicked) and hadChunkError (whether a chunk-load failure preceded the blank).
  2. Open heartbeat-snapshot.log next to it. If the ring dump reason is manual-recovery-blank-screen, the file holds the last ≈ 50 seconds of main-process ticks leading up to the blank — useful for spotting a [STALL] or rising lastOp repeats just before the click.
  3. Open startup.log for the launch that came AFTER the click. If the chunk-error grace fired (hadChunkError=true in the marker line), the next launch's startup trace is where you'll see whether the rebuild fixed it or whether the same chunk is still 404'ing.
  4. If the renderer reload didn't help and you closed the window manually, the next launch's [POST-MORTEM] block will reference the manual-recovery ring dump.

The whole point of the marker is that an LLM (Claude Code, or an outside AI you paste the logs into) can correlate a user report — "the window went blank and I clicked the button" — with a specific tick window and a specific lastOp, without having to guess at timestamps.

The recovery card is one of a small family of self-healing surfaces. main-heartbeat.md explains the heartbeat log and the marker vocabulary the button writes into it; crash-recovery.md covers how sessions themselves come back after a crash or a restart; and app-already-running-or-frozen.md is the neighbouring problem of a copy that is running but has stopped responding.

Last verified 2026-11-16