Merge branch 'main' into worktree-agent-a9fea98fe9839069d

docs/architecture.md

@@ -127,7 +127,17 @@ preview frame are written (LZ4, atomic rename, checksummed) under 128-bit conten
 comp's content hash (the comp, what it uses, footage file size and time) plus frame, scale and
 view for frames; the layer key salted with the footage fingerprint for layers — so entries
 survive restarts and never go stale. LRU eviction keeps it under the size limit; Edit ▸ Purge
-empties it, `cache.diskStats` reports it, and the timeline draws disk-only frames in blue.
+empties it, `cache.diskStats` reports it, and the timeline draws disk-only frames in blue. In the
+browser the frames live in the Origin Private File System: frame workers write them, the page
+keeps the index (`DiskIndex`) and reads hits ([web.md](web.md#disk-cache)).
+
+**Deferred readbacks** (`effectcraft-gpu` `deferred`): where a readback can't be waited for (WebGPU
+in a browser worker) a frame renders in passes. `Accelerator::frame_begin` / `pass_begin` /
+`pass_missed` / `miss_gate`: a readback not there yet starts asynchronously and the step returns a
+placeholder; the pass is missed, the layer cache's gate drops inserts until the pass ends, and the
+caller (`remote::FrameServer::resume`) renders again once the device delivered. Readbacks are keyed
+by content (a chain's input pixels and parameters; the frame's comp, time and options), so later
+passes are served from them; a pass without a miss is the frame.
 
 **Time effects** (Echo, Posterize Time, Timewarp…) read the layer at other times through
 `EffectHost::self_at`: the renderer renders the layer's source and masks (plus, optionally, the
@@ -190,21 +200,35 @@ runs render on the GPU end to end (`gpu::adv3d`, `Renderer::prepare_adv_run` /
 then compute kernels (`adv3d.wgsl`) resolve the 2×2 supersampling, average the sub-samples
 (nearest depth), apply the depth-based iris depth of field with the Classic 3D bokeh spans
 (`three_d::bokeh::kernel_spans`, highlight boost, progressive blur levels) and composite over the
-GPU canvas; only the depth of field reads back its 8-byte radius range. Advanced 3D layers with
-blend modes, track mattes or Preserve Transparency and environment backgrounds take the CPU's
-2D compositing path (their scenes still render through `render_3d`). Wireframe outlines draw on
-the GPU from the CPU's pixel list (`Renderer::wireframe_pixels`). GPU
-effects (`effects::GPU_EFFECTS`, 166 of them: blurs, colour correction, keying incl. Key Light,
-mattes, channel, stylize, distortion and warps (Warp, Bezier Warp, Smear, Reshape, CC Bend It, CC
-Page Turn), Cartoon, bevels, shapes, transitions, generators, noise, grain and time; see
+GPU canvas; only the depth of field reads back its 8-byte radius range. Runs whose layers need
+the 2D compositing path (blend modes, track mattes, Preserve Transparency) come to the GPU as a
+`three_d::adv::SplitRun` (`Renderer::split_adv_run`, `draw_run`'s steps as data): the plain
+layers render as one scene over the canvas, then each special layer, farthest first, renders on
+its own, is hidden where the main scene is nearer (`occlude`), and goes through the 2D matte /
+Preserve Transparency / blend kernels (a 3D track matte renders solo through the camera).
+Environment Light Background layers draw their sky in a kernel (`adv_sky`, from
+`Renderer::sky_draw`) before the rest of the run, in Classic and Advanced 3D comps. Wireframe
+outlines draw on the GPU from the CPU's pixel list (`Renderer::wireframe_pixels`). GPU effects
+(`effects::GPU_EFFECTS`, 196 of them: blurs, colour correction, keying incl. Key Light, mattes,
+channel, stylize, distortion and warps (Warp, Bezier Warp, Smear, Reshape, CC Bend It, CC Page
+Turn, CC Bender, CC Blobbylize), Cartoon, bevels, shapes, the transitions (CC light family, CC
+transitions, Block Dissolve), perspective (Radial Shadow, CC Cylinder / Sphere / Spotlight /
+Environment, 3D Glasses), generators, noise, grain, text (Numbers, Timecode) and time; see
 [effects.md](effects.md)) repeat the CPU effect's steps (padding, box radii, parameters, hashes)
 as kernels, in one module per family (`gpu::fx_*` with `shaders/fx_*.wgsl`); consecutive GPU
 effects run as one chain with one upload and one readback. Statistics that need the whole frame
 (Auto Levels / Contrast / Color, Equalize, Shadow/Highlight, Color Stabilizer, Remove Grain's
 noise level) are measured on the CPU from one readback and applied on the GPU; effects reading
-other frames (Echo, Posterize Time) upload the frames the host renders. Settings a kernel cannot
-match render on the CPU (`effects::catalog::gpu_supported`; e.g. Warp's Fisheye and Twist past
-50 % or with a distortion, whose Newton inverse wanders chaotically near the crease). Tests render
+other frames (Echo, Posterize Time, Time Difference, Time Displacement, CC Force Motion Blur, CC
+Wide Time, Pixel Motion Blur, Timewarp) upload the frames the host renders (`time_frames`) and
+combine them on the GPU; Time Displacement's per-pixel times and Timewarp's motion vectors
+(`time_fx::timewarp_plan`) are computed on the CPU. Numbers and Timecode rasterise their glyph
+coverage on the CPU (`textfx::text_layer`) and composite it on the GPU. Other layers an effect
+reads (gradients, reveals, environments) are fitted on the CPU (`util::fit_layer`) and uploaded.
+Settings a kernel cannot match render on the CPU (`effects::catalog::gpu_supported`; e.g. Warp's
+Fisheye and Twist past 50 % or with a distortion, whose Newton inverse wanders chaotically near
+the crease, and Timewarp with a Matte Layer); Card Wipe (the 3D card renderer of Card Dance and
+Shatter) stays on the CPU. Tests render
 scenes on both paths and compare them (≤ 1/255 at 8 bpc, ≤ 1e-3 at 32 bpc); they skip without an
 adapter. Working textures (premultiplied RGBA f32) come from a pool: a released texture is reused
 once every encoder that could still read it has been submitted, transparent inputs share one