fix(observatory): stop health probe racing WebGL startup into demo mode

[Omriaru]

Summary

On a host without GPU acceleration, the Observatory reports a perfectly healthy sensing server as absent and silently switches to DemoDataGenerator — so the HUD shows fabricated vitals that look real. The server is never at fault; the client's own startup sequence aborts its detection probe.

Root cause

_autoDetectLive() is called synchronously from the Observatory constructor (main.js:134), and its probe uses a wall-clock deadline:

fetch(`${base}/health`, { signal: AbortSignal.timeout(1500) })

The code immediately after that call builds the three.js scene and compiles shaders, blocking the main thread. Where WebGL is software-rendered — a VM, or any host without GPU acceleration — that block lasts for seconds, so the 1500 ms deadline expires before the response can ever be handled.

Wrapping window.fetch on such a host shows what actually happens:

http://127.0.0.1:3000/health   resolved 200   after 5612 ms
main-thread jank:              blockedMs: 6931

The response headers arrive fine — but r.json() is aborted mid-body-read by the already-fired signal. The .catch advances to the next candidate, :8765 is refused, and the app concludes:

[Observatory] No sensing server detected, using demo mode

dataSource latches to 'demo', the badge reads DEMO, and HR/BR sit at -- while the demo generator drives the scene.

Fix

• Defer the probe with a double requestAnimationFrame so it is issued once the main thread is idle, instead of racing scene construction.
• Raise the timeout to 10 s, because each frame can still stall ~600 ms under software rendering.

The deferral is the substantive fix; the timeout increase is defence-in-depth.

Verification

Against a live ESP32-S3 CSI node (--source esp32), same build, only this patch changed:

	badge	HR	BR
before	DEMO	--	--
after	LIVE	56	10

After the fix, a clean load auto-detects with no manual intervention:

[Observatory] Sensing server detected at http://127.0.0.1:3000 → ws://127.0.0.1:3000/ws/sensing
[Observatory] WebSocket connected

Vitals track /api/v1/vital-signs. On a GPU-accelerated host the behaviour is unchanged — startup is fast enough that the original deadline was never hit, which is why this only bites some users.

Reproducing

Needs a host where WebGL falls back to software rendering (e.g. a VM). Note that headless Chrome's --virtual-time-budget fakes this bug: it fires the 1500 ms abort prematurely and will make an otherwise-healthy host look affected. I used real-time CDP with Page.addScriptToEvaluateOnNewDocument instead.

Related

• Has anyone got this project to work? #1125 — users reporting they cannot get the project working; this failure mode presents exactly that way, since the UI looks alive while showing synthetic data.
• fix(#1125, #1004): Remove all simulated-data fallback mechanisms #1431 removes simulated-data fallbacks generally. This PR is complementary and much narrower: it fixes the faulty detection that triggers the fallback, and does not change fallback policy.

🤖 Generated with Claude Code