Render continuously and optimize the glTF viewer

Remove vsync and dirty-flag frame gating, optimize PBR sampling and lighting, add a direct-to-canvas loadout, and preserve camera state on viewer resize.

Add regression coverage and update rendering documentation.

Amp-Thread-ID: https://ampcode.com/threads/T-01a0b382-1e79-712b-abd1-d29201c9bb5e
Co-authored-by: Heaust Azure <heaust.azure@gmail.com>

coredocs/guide/shared-memory.md

@@ -48,26 +48,20 @@ Capacity does not shrink. Deletion makes descriptors/views invalid for applicati
 | 2 | `elapsedTime` | Accumulated seconds |
 | 3 | `targetFps` | Configured cap; 0 means uncapped |
 | 4 | `skipRender` | Nonzero suppresses rendering |
-| 5 | `sabDirty` | Nonzero requests a frame; consumed (set to 0) at frame start |
+| 5 | `reserved` | Legacy `sabDirty` lane; ignored by the renderer |
 | 6 | `bundleDirty` | Nonzero suppresses stale bundles until a successful loadout switch |
 | 7 | `reserved` | No current contract; leave unchanged/zero |
 
-The core updates lanes 0–3 while playing. A render starts only when lanes 4 and 6 are zero and lane 5 is nonzero. Finish the row writes first, then set the dirty signal:
+The core updates lanes 0–3 while playing and renders continuously when lanes 4 and 6 are zero. No dirty signal is needed. The worker yields to control messages and waits for GPU completion between submissions, rather than waiting for `requestAnimationFrame` or main-thread vsync. An explicit FPS cap still applies; the browser controls display presentation.
 
 ```js
 const signalsF32 = rowFor(buffer, signalDescriptor, 0);
 
-function publishRows(write) {
-  write();           // finish every row write
-  signalsF32[5] = 1; // request the frame last
-}
-
 async function replaceBundle(mutate, compileAndSwitch) {
   signalsF32[6] = 1; // suppress the old bundle first
   mutate();
-  signalsF32[5] = 1;
   try {
-    await compileAndSwitch(); // successful switch clears lane 6 and requests a frame
+    await compileAndSwitch(); // successful switch clears lane 6 and resumes rendering
   } catch (error) {
     // Keep lane 6 set: rendering stale bindings would be unsafe. Repair/retry or stop.
     throw error;
@@ -75,12 +69,12 @@ async function replaceBundle(mutate, compileAndSwitch) {
 }
 ```
 
-The signals are invalidation state, not a lock or transaction boundary. If multiple threads can write one logical update, coordinate those writers so core cannot observe a partially updated value. Core marks lane 5 after object deletion, texture upload, and a successful switch, but direct SAB writes do not. Always publish lane 5 after direct data writes.
+The signals are control state, not a lock or transaction boundary. Shared row writes can overlap worker reads; callers needing an atomic multi-field update should await `pause`, write the rows, then `play`.
 
 ## Frame-sync versus manual-sync
 
-A graph buffer's `sync` defaults to `"frame"`. Before each actual render, the full named row array is copied SAB → GPU, so ordinary value edits only require `sabDirty`. Use it for small, frequently changing arrays (transforms, lights, draw commands).
+A graph buffer's `sync` defaults to `"frame"`. Before each actual render, the full named row array is copied SAB → GPU, so ordinary value edits need no notification. Use it for small, frequently changing arrays (transforms, lights, draw commands).
 
-`sync: "manual"` is copied in full only when its GPU buffer is created: on the first `switch-loadout` that declares it, and whenever the source array grows/relocates or the declaration's usage changes. Later SAB edits reach the GPU only through `sync-rows { name, first, count }`, which uploads that row range into every active buffer bound to the array and marks the frame dirty. Use it for large, mostly static arrays such as vertex and index data: write the rows, then `sync-rows` exactly that span.
+`sync: "manual"` is copied in full only when its GPU buffer is created: on the first `switch-loadout` that declares it, and whenever the source array grows/relocates or the declaration's usage changes. Later SAB edits reach the GPU only through `sync-rows { name, first, count }`, which uploads that row range into every active buffer bound to the array. Use it for large, mostly static arrays such as vertex and index data: write the rows, then `sync-rows` exactly that span.
 
 GPU resources survive graph switches when nothing about them changed: a buffer is reused when its declaration ID keeps the same source array, byte size, and usage; a render or compute pipeline is reused when a previous declaration had identical code and state (IDs may differ); non-transient textures with the same descriptor are kept. Bind groups and render bundles are always rebuilt. Structural changes affecting bindings, offsets, draw ranges, passes, pipelines, or attachment/resource declarations require bundle invalidation and a graph/loadout switch because render commands are precompiled into render bundles.

coredocs/index.md

@@ -15,7 +15,7 @@ features:
   - title: Raw transport
     details: Start core/worker.js, correlate replies, and handle profiler events.
   - title: Shared rows
-    details: Build typed views, allocate slots, and follow the dirty-lane protocol.
+    details: Build typed views, allocate slots, and control continuous rendering.
   - title: Graph wire format
     details: Encode, compile, and activate complete WebGPU render and compute graphs.
 ---
@@ -27,7 +27,7 @@ The browser main thread owns the HTML canvas and starts the module worker. The w
 The application is responsible for three important contracts:
 
 1. Correlate each reply by its `request` value; profiler messages are unsolicited.
-2. Finish shared-memory writes before setting `signals[5]` (`sabDirty`).
+2. Shared-memory value edits are rendered continuously; no `sabDirty` notification is needed. Pause before updates that must not overlap rendering.
 3. Before a mutation that invalidates compiled render bundles, set `signals[6]` (`bundleDirty`), make the mutation, compile and switch a replacement graph, then let successful `switch-loadout` clear lane 6.
 
 This site describes the current wire API, not the higher-level wrapper API.

coredocs/reference/errors.md

@@ -60,16 +60,16 @@ On row growth, consume the returned descriptor before the next access and commit
 | `GRAPH_BLEND`, `GRAPH_WRITE_MASK` | Invalid fragment blend or write-mask bits. |
 | `GRAPH_SAMPLER` | Invalid sampler enum/compare value. |
 | `GRAPH_LOAD_OP`, `GRAPH_STORE_OP` | Attachment operation is not allowed. |
-| `SURFACE` | Surface acquisition/recovery failed; core marks the SAB dirty to retry later. |
+| `SURFACE` | Surface acquisition/recovery failed; the continuous render loop retries later. |
 
 Shader compilation, bind-layout mismatch, device limits, invalid upload extents/mips, and WebGPU validation are not all normalized to these codes. Validate graph inputs before switching and retain the previous graph source for recovery.
 
 ## Safe state transitions
 
 1. Initialize once and cache descriptors.
-2. Create rows, allocate IDs, and initialize complete rows before publishing `sabDirty`.
+2. Create rows, allocate IDs, and initialize complete rows. Pause first if an update must not overlap rendering.
 3. Compile graphs before switching. Compilation stores a graph but does not validate every GPU-dependent property; activation can still fail.
 4. For bundle-invalidating mutation, set `bundleDirty` first. Leave it set after compile/switch failure, because that intentionally suppresses stale rendering. Repair and switch successfully; never clear it merely to hide an error.
 5. Upload textures with transfer ownership. Delete cached sources when no future loadout needs them.
-6. Pause when editor state should stop timing/render-loop progress. `pause` does not cancel requests or clear dirty lanes.
+6. Pause when editor state should stop timing/render-loop progress. `pause` does not cancel requests or clear control lanes.
 7. On worker failure, reject all pending requests and rebuild the entire worker/canvas/core state. Requests are not generally safe to replay because create, allocate, delete, switch, and texture operations may already have committed.

coredocs/reference/worker.md

@@ -7,18 +7,18 @@ All fields below are top-level beside `type` and `request`. Except for `init` an
 | `init` | `canvas: OffscreenCanvas`, `arenaBytes: number` | `[canvas]` | `{ buffer: SharedArrayBuffer, rows: Descriptor[], features: string[] }` | Once only; initializes WASM/WebGPU. `features` lists optional device features that were available (`timestamp-query`, `indirect-first-instance`). |
 | `create-rows` | `name`, `rows`, `stride`, `format` | — | `{ rows: descriptor, commit: boolean }` | Nonempty name; rows > 0; stride ≥16 and multiple of 16; format f32/u32/i32. Existing name may only retain format/stride and grow. `commit: true` means the rows moved: copy the old bytes into the descriptor and send `commit-rows`. |
 | `create-rows-batch` | `rows: Array<{name,rows,stride,format}>` | — | `{ rows: descriptor[] (input order), commit: string[] }` | Nonempty. Sequential; in-place creations/growths survive a later failure, staged relocations are discarded. `commit` lists the arrays that moved. Active GPU resources refresh once for in-place growth. |
-| `commit-rows` | `names: string[]` | — | `undefined` | Publishes staged relocations after the caller copied them. Must name every staged array. Frees the old rows, refreshes bound GPU buffers once, sets `sabDirty`. While a relocation is staged the worker queues every other request until this arrives. |
+| `commit-rows` | `names: string[]` | — | `undefined` | Publishes staged relocations after the caller copied them. Must name every staged array. Frees the old rows and refreshes bound GPU buffers once. While a relocation is staged the worker queues every other request until this arrives. |
 | `delete-rows` | `name` | — | `undefined` | Not `signals`, not active slots, not referenced by active graph. |
 | `allocate-object` | `name`, `count: u32 = 1` | — | `{ id, rows: descriptor, commit: boolean }` | Not `signals`; `count` > 0; reserves `count` contiguous rows starting at `id`; may grow. `commit` as in `create-rows`. |
 | `delete-object` | `name`, `id: u32` | — | `undefined` | ID must be the first row of an active span; the whole span is zeroed. |
-| `sync-rows` | `name`, `first: u32 = 0`, `count: u32` | — | `undefined` | Uploads rows `first .. first + count` of the array into every active GPU buffer bound to it (any `sync`) and sets `sabDirty`. `ROW_RANGE` when the span exceeds the array. No-op without an active loadout. |
+| `sync-rows` | `name`, `first: u32 = 0`, `count: u32` | — | `undefined` | Uploads rows `first .. first + count` of the array into every active GPU buffer bound to it (any `sync`). `ROW_RANGE` when the span exceeds the array. No-op without an active loadout. |
 | `compile-graph` | `serialized: string` | — | graph ID string | Parses and stores; same ID replaces previously stored graph. Does not activate it. |
-| `switch-loadout` | `id` | — | `undefined` | Builds GPU resources and activates stored graph. Clears `bundleDirty`, sets `sabDirty`. |
-| `upload-texture` | `name`, `mipLevel: u32`, `image: ImageBitmap` | `[image]` | `undefined` | Uploads immediately if active graph has the texture and caches source for future switches. Source extent must fit destination/mip. Sets dirty. |
-| `delete-texture` | `name` | — | `undefined` | Deletes/closes cached mip sources; does not remove graph texture or mark dirty. |
+| `switch-loadout` | `id` | — | `undefined` | Builds GPU resources and activates stored graph. Clears `bundleDirty`. |
+| `upload-texture` | `name`, `mipLevel: u32`, `image: ImageBitmap` | `[image]` | `undefined` | Uploads immediately if active graph has the texture and caches source for future switches. Source extent must fit destination/mip. |
+| `delete-texture` | `name` | — | `undefined` | Deletes/closes cached mip sources; does not remove graph texture. |
 | `play` | — | — | `undefined` | Enables render-loop ticks; resets last-time baseline. |
 | `pause` | — | — | `undefined` | Stops loop updates/renders. |
-| `set-fps` | `fps: u32` | — | `undefined` | 0 uncapped; maximum 1000. Does not itself dirty a frame. |
+| `set-fps` | `fps: u32` | — | `undefined` | 0 uncapped; maximum 1000. |
 | `set-profiler` | `enabled` (boolean-coerced) | — | boolean | Result says timestamp queries are supported. Enables only when requested and supported. |
 
 Rust/WASM numeric conversion applies to `u32` fields; callers should send finite nonnegative integers in range rather than rely on coercion.
@@ -41,6 +41,8 @@ When enabled and supported, the worker polls every 250 ms and may send an unsoli
 }
 ```
 
+`milliseconds` is the sum of GPU timestamp durations across passes, not CPU frame time or the interval between frames. It excludes scheduling waits and readback latency; `readbackMilliseconds` reports the time from starting that frame to receiving its timestamp results.
+
 One pass timing corresponds to a compiled execution; compatible adjacent render passes are merged into one execution labelled `first … last (N draws)`. Samples are throttled and asynchronous, so they are diagnostics, not one event per frame. Disabling clears pending published statistics and the worker polling interval.
 
 ## Texture lifecycle