Merge #139 from dexterlabs1: contain GPU initialization errors and retire failed compositor work

docs/architecture.md

@@ -272,7 +272,21 @@ as NaNs (a kernel that skips pixels fails the oracle) and validation errors pani
 tests, device errors are logged rather than fatal. A viewer frame that runs out of video memory
 (`Gpu::within_memory`) renders on the CPU, the uploaded layers and pooled textures are freed, and
 the RAM preview keeps half as many GPU frames from then on. A frame whose render panics is
-rendered again on the CPU or released, never left in progress. On the web
+rendered again on the CPU or released, never left in progress. Native readbacks and timing waits
+share a finite deadline; failure retires pending readbacks exactly once, and late results are
+discarded. The desktop executable and browser page own their shared device's error/loss handlers and forward
+failures to the compositor through a weak notifier. Libraries borrowing a device preserve its
+host's handlers. A host fault disables shared-device preview acceleration without editing the project or its
+renderer preference; materialized CPU frames remain usable and late GPU textures cannot return
+to the preview cache. Scoped allocation failures retain the adaptive budget/CPU retry behavior.
+
+**Recovery boundary:** the host installs handlers through eframe's CreationContext, after egui's
+presentation pipelines but before EffectCraft's pipelines. This does not cover that earlier egui
+startup window. eframe 0.36.2 supports lost-surface recreation, not replacing its live device and
+all presentation resources. Device loss therefore requires restarting the presentation backend;
+CPU compositing alone cannot restore that display. No automatic restart or persistent safe-mode
+sentinel is implemented here. Browser scope futures are not synchronously awaited; the browser page
+forwards shared-device errors, while owned worker devices install their own handlers. On the web
 (WebGPU) the GPU composites viewer frames; steps that need a readback fall back to the CPU (the
 Info panel's pixel readout reads GPU frames back asynchronously). **GPU particles**
 (`effects::psim`, `gpu::particles`): CC Particle World, CC Particle Systems II and Particle