🐛 fix(crash): unclean-exit marker honours visibility, sampling and reports once per session

[nitinstp23]

Summary

Fixes B14-2079, B14-2080 and B14-2081 (snabbit app-webview-rum, Preact page inside the Expert Android app's WebView).

• Heartbeat no longer re-arms a hidden page. visibilitychange: hidden cleared the marker but the 10 s heartbeat wrote it back as active. An embedded WebView keeps running timers after the host pauses it and is then destroyed without pagehide, so every routine close was reported as app_unclean_exit on the next open (~8× the app_startup rate on snabbit). The heartbeat writes the current visibility; freeze / resume clear and re-arm. The native marker's heartbeat writes the current AppState.
• Reports follow the dead session's sampling decision. The marker records sampled; an unsampled session's exit is not filed (it exported nothing else, and the lone span escaped sessionSampleRate for 100 % of sessions).
• One report per terminated session. The marker remembers reportedSessionId, so a session resumed within sessionTimeoutMinutes is not reported once per reopen.
• enableUncleanExitDetection config flag: default true, on web default false inside an embedded WebView (Android wv UA token, iOS WKWebView UA without Safari/). Explicit values override the heuristic. Reported in the scout.config log.

Evidence

40/40 live app_crash spans on snabbit (scout-react 0.1.16): crash.reason=tab_terminated_without_pagehide, no exception, 6 with a lifecycle: paused last breadcrumb; 39/40 session.sampled=false; one crash.previous_session_id duplicated inside a 53 s sample. Details on the tickets.

Tests

• crash.test.ts: hidden heartbeat stays inactive, freeze/resume, page created hidden, sampled recorded and honoured, reportedSessionId recorded and honoured, a different session still reports.
• platform.test.ts: isEmbeddedWebView UA matrix.
• unclean-exit-gate.test.ts: Scout.initialize arms the marker in a browser, not in a WebView, and both explicit overrides.
• make ci green locally (316 tests).

Docs

CHANGELOG [Unreleased], docs/configuration.md (new row, alwaysCaptureErrors note), docs/ARCHITECTURE.md and README.md no longer describe the web marker as app_crash.

Rollout

snabbit runs 0.1.16, where the marker is still emitted as app_crash. They need this release plus, until they wire setWebViewBridge session adoption, the WebView default (or enableUncleanExitDetection: false) in the app-webview build.

[nitinstp23]

Verification against scout-rum-example-apps/webview-react-web

Integration build = #9 + #10 + #11 merged locally (make ci green, 345 tests), packed and installed into the harness.

Headless Chrome 153 via Playwright, 29/29 (sessionSampleRate: 100, OTLP exports intercepted and parsed):

• Marker: written on load with sampled; visibilitychange:hidden clears it and the heartbeat keeps it cleared for 12.5 s; visible/freeze/resume re-arm; a seeded dead sampled session exports exactly one app_unclean_exit attributed to it (session.id = crash.previous_session_id), never app_crash; marker records reportedSessionId; an already-reported session and an unsampled session export nothing.
• Android WebView UA: no marker written, a pending marker is not filed, other spans still export.
• Array.prototype.at deleted before init: no TypeError, no error span, CLS/INP absent while TTFB/FCP/LCP report; an app error carries error.origin=app; an error whose top frame is the SDK module carries error.origin=sdk + sdk_internal, is exported once for three throws, and error.count stays at the one app error.
• 1 s stall → one long_task (LoAF only) + one frozen_frame (1.0 s); a stall overlapping a hidden interval is dropped; an 11 s stall reports 10 s with frozen_frame.capped=true.

Real Android System WebView (emulator API 34, Chrome 113, webview-bridge-flutter mode=off, DevTools over adb), 7/7: UA has wv; Scout.instance.config.enableUncleanExitDetection === false; no marker key in localStorage; 1 s stall → one long_task + one frozen_frame; HOME → visibilityState=hidden + app_paused; return → app_resumed; no app_unclean_exit/app_crash.

Kill cycle with the marker forced on (VITE_SCOUT_UNCLEAN_EXIT=true), 6/6: first launch reports nothing; HOME → 16 s → am force-stop → relaunch: no app_unclean_exit; foreground force-stop → relaunch: exactly one; a second foreground kill of the same (resumed) session: none; never app_crash.