Slider latency + WebGPU efficiency plan #

Status: implemented (2026-07-31) — Phases B–E landed in one pass; Phase A (baseline measurement) was skipped per the user's call (they smoke-test by hand). See the diff for details.

1. Diagnosis: why the slider effect "isn't applied correctly" #

The math is fine — the problem is latency and backlog in the render path. Every OnInput slider event fires UpdatedDraftParam/UpdatedLayerParam → renderNow → a RenderChain command. There is no coalescing: a fast drag enqueues one full render per pointermove, and each render costs a full GPU→CPU→GPU round trip:

Per GpuBackend.execute() tick (packages/frontend/src/gpu/backend.ts):

1. copyExternalImageToTexture — re-uploads the entire source image, which never changes during a drag.
2. Fresh allocations: srcTex, dstTex, resolution/frame/params buffers, bind group — destroyed at the end of the same tick.
3. readBack — copyTextureToBuffer + mapAsync (a hard GPU sync point), row unpadding on CPU, new ImageData, createImageBitmap (CPU).
4. RenderedFrame → PaintCanvas → 2D drawImage — re-uploads the full image back to the GPU for display.

Net per tick: 2 full-image GPU transfers, 1 main-thread stall, 2 CPU pixel copies, ~8 GPU allocations, and a second full-image upload for presentation.

Because renders take longer than the event interval, work piles up in the command queue. RenderedFrame's stale-stamp guard (update.ts) drops late results, but the GPU work still ran — so the displayed image trails the slider and the backlog persists after the drag ends. That backlog, not a shader bug, is what reads as "the effect is not applied correctly."

2. Where the wins are #

The WGSL from the SkSL port is mostly fine: single merged compute shader, textureLoad/textureStore, one linear round trip — all correct. The structural inefficiencies above dominate; the shader-text tweaks are the tail.

3. Phases #

All phases below are implemented. The key deliverables: no readback on the display path (compute + blit to a WebGPU canvas), image-scoped persistent resources (one source upload per image), one-render-in-flight coalescing (renderPending + onSubmittedWorkDone), and the WGSL tweaks (vectorized sRGB, integer grain hash, 16×16 workgroups). The engine API changed: render/GpuBackend service are gone — createRenderRequest (pure) + frontend-owned GpuBackend with execute/snapshot replace them.

Phase A — Measure (small, do first) #

• Dev-only timing overlay (or performance.now() logs): per-render execute() time, renders/sec during a drag, main-thread stall time from mapAsync.
• Baseline numbers on a 12MP image; keep them to compare after each phase.

Phase B — Kill the display readback (the big win) #

• The center canvas becomes a WebGPU canvas (getContext('webgpu'), configure({ alphaMode: 'opaque', size: imageSize })). CSS transform pan/zoom keeps working unchanged.
• Backend gains a blit render pipeline: fullscreen triangle (positions from vertex_index, no vertex buffer), fragment does textureSample of the processed texture (free bilinear) → swapchain texture.
• execute() = compute pass into dstTex + blit pass dstTex → canvas texture in one encoder, one submit, no readback, no CPU pixels, no 2D canvas.
• Empty-chain display: stop special-casing it. render() currently fails with EmptyChainError on an empty chain, but generateChainSource([]) already emits a passthrough compute shader. Allow empty chains through the render path; delete PaintInitial, paintBitmap, and the ImageDecoded empty-chain branch.
• Export keeps a readback path (PNG needs CPU pixels), but it runs only on the export button click — one-time cost. Drop renderedBitmap from the model in favor of a hasRendered flag; ExportImage triggers render + readback.

Phase C — Persistent resources #

• Upload srcTex once per image; keep it for the image's lifetime.
• Keep dstTex + blit resources per image size; recreate only on image change.
• Cache params/resolution buffers and the bind group alongside the existing pipeline cache (keyed by shader source; resolution buffer per image).
• A slider tick becomes: writeBuffer(params) + writeBuffer(frame) + 1 compute dispatch + 1 blit dispatch + submit. Zero allocations, no sync.

Phase D — Coalesce renders (fixes the visible lag) #

• Model gains a renderPending flag. renderNow skips dispatch when a render is already in flight and just marks pending (revision still bumps).
• RenderedFrame handler: instead of dropping a stale result outright, if stamp < model.revision and a render is pending, re-dispatch with the latest chain+draft.
• Result: at most one render in flight, always converging on the newest slider value. u_frame = stamp still increments, so grain keeps animating.
• This bounds GPU queue depth to ~1–2 regardless of pointer event rate.

Phase E — WGSL micro-optimizations #

• Vectorize sRGB conversion (colorspace.ts): one select + one pow on vec3<f32> instead of three per-channel branches. Same math, lets the driver vectorize.
• Replace the sin() grain hash (grain.ts) with an integer hash (e.g. pcg/xorshift-derived) — no transcendentals. Keep the density weighting; A/B the noise character (it will change slightly).
• @workgroup_size(16, 16) (256 invocations) instead of (8, 8); make it a named constant, measure on discrete vs integrated GPUs, pick the winner.
• Leave the uniform-alias lets, u_resolution uniform, and the single linear round trip as-is — negligible or inherent.

Phase F — Verify & close #

• Update chain-source.test.ts for the workgroup-size and empty-chain changes.
• Run @lutra/engine and @lutra/frontend test suites.
• Manual pass: drag a slider on a 12MP image; confirm no lag, low CPU during drag, export still correct.
• Update ADR 0001-compute-shader-pipeline.md (display path = compute + blit) and context.md (pipeline, coalescing, persistent resources).

4. Risks / notes #

• WebGPU canvas support tracks the existing device-acquisition gate; no new fallback surface.
• Blit textureSample gives free bilinear downscaling for zoom-out; zoom-in stays CSS-scaled (same as today's 2D canvas).
• bytesPerRow 256-alignment requirement only matters for the export readback now.
• happy-dom tests don't cover the backend; the backend stays unit-test-free, as today.