@woosh/meep-engine 3.8.0 → 3.10.0

package/src/shade/device/timing/GPU_PROFILER_PROPOSAL_2026_08_28.md

@@ -0,0 +1,625 @@
+# A graphical GPU profiler for Shade — recorder, format, inspector
+
+Proposal, 2026-08-28. Alex Goldring / Company Named Limited.
+
+Scope: a **recording** side that ships with the engine, a **binary container** that carries a
+capture, and an **inspector** web application under `packages/gpu-inspector-tool/` that reads the
+container and nothing else.
+
+> The request spelled the directory `gpu-inespector-tool`. Reading that as a typo and using
+> `packages/gpu-inspector-tool/` throughout. Say the word if the misspelling was deliberate.
+
+---
+
+## 0. Verdict
+
+**Worth building, and the engine is further along than it looks — but not in the place you would
+expect.**
+
+The timing half is the *small* half. `GPUTimerArray` already lands begin/end timestamps per GPU
+pass, and `SoftwareGPUDevice` already emulates timestamp queries well enough to test the recorder in
+node without a GPU. What is genuinely missing is **attribution**: the timestamps are keyed by
+`GPUComputePassDescriptor.label`, the dependency structure lives in `FrameGraph`, and *nothing
+connects the two*. One frame-graph pass can open several GPU passes with unrelated labels
+(`graph_build_hzb` → `hzb.build()` → its own `constructComputePass` labels), so a label is not a key.
+Closing that gap is the central piece of engineering in this proposal, and it is about thirty lines
+in `FrameGraph.execute` plus a field on the command context.
+
+The dependency half is nearly free. `FrameGraph.exportToJson()`
+([FrameGraph.js:644](src/engine/graphics/render/frame_graph/FrameGraph.js:644)) already emits passes,
+resource nodes, versions, readers, writers, producers and cull state, keyed consistently. Resource
+*sizes* fall out of the descriptors that graph already holds. Nesting for a flame-graph view falls
+out of `FrameGraphScope`.
+
+The work-size half needs a wrapper that does not exist: `beginComputePass` hands back the raw
+`GPUComputePassEncoder`, so `dispatchWorkgroups(x, y, z)` is invisible to us. A recording-only proxy
+around the pass encoder buys every dispatch and draw count for one class and no call-site churn.
+
+**The single biggest risk is not ours.** Chrome quantizes WebGPU timestamps to **100 µs** unless the
+user sets `chrome://flags/#enable-webgpu-developer-features`. Most Shade passes run well under that,
+so on a default browser almost every pass measures as exactly 0 or exactly 100 µs. A profiler that
+does not say this out loud, in the recording *and* in the inspector, is a profiler that lies. §2.1.
+
+---
+
+## 1. What exists today
+
+### 1.1 The timing path, end to end
+
+| Piece | Where | What it does |
+|---|---|---|
+| `GPUTimerArray` | [GPUTimerArray.js](src/shade/device/timing/GPUTimerArray.js) | One `GPUQuerySet` of `size * 2` timestamps. `getComputeWrites(label)` / `getRenderWrites(label)` claim a slot from an `IdPool` and return the `timestampWrites` struct. Resolve + copy to a `MAP_READ` buffer, `download_results()` maps it, `results_to_console_table()` turns slots into `{label, type, duration_ms, start, end}`. |
+| `ShadeGPUCommandContext.enable_debug_timers(cb)` | [ShadeGPUCommandContext.js:89](src/shade/device/ShadeGPUCommandContext.js:89) | Constructs a `GPUTimerArray` for this context. `beginComputePass` / `beginRenderPass` then inject `timestampWrites` into every descriptor. |
+| `finish()` | [ShadeGPUCommandContext.js:699](src/shade/device/ShadeGPUCommandContext.js:699) | Resolves the query set into the command buffer before `encoder.finish()`, then after submit downloads results and calls the callback, then destroys the timer array. |
+| `Renderer.add_debug_frame(count)` | [Renderer.js:626](src/shade/renderer/Renderer.js:626) | Arms N future frames. |
+| `Renderer.onFrameDebug` | [Renderer.js:408](src/shade/renderer/Renderer.js:408) | `send2(frame_index, table)`. **Currently has no subscribers anywhere in the tree.** |
+| `GPUTimerStats`, `format_nanosecond_time` | `src/shade/device/timing/` | Ring-buffer averaging and human formatting. Reusable in the inspector. |
+
+Degradation is already correct: with `timestamp-query` withheld, the query set is never created and
+`resolve` / `download_results` / `destroy` all no-op rather than throwing. Keep that property.
+
+### 1.2 Four defects the recorder must fix, not inherit
+
+1. **No slot bound check.** `GPUTimerArray.#bind_slot` takes an id from the `IdPool` and never
+   compares it to `#size`. Pass 1025 in a frame (default `size = 1024`) writes a query index past
+   `querySet.count` and takes a WebGPU validation error, at the `beginRenderPass` rather than at the
+   place that overflowed. A recording session runs *more* passes instrumented than a debug frame
+   does, so this is on the path. Clamp and count drops; report the drop count in the recording.
+2. **Per-context GPU allocation.** `enable_debug_timers` builds a query set and two buffers per
+   context and destroys them after the download. Fine for one frame; recording 600 frames means 600
+   query-set create/destroy pairs and 600 `mapAsync` round trips. Wants a small pool of timer arrays
+   cycled N-deep against frames in flight.
+3. **Descriptor mutation.** `beginComputePass` does `let _descriptor = descriptor;` and then writes
+   `_descriptor.timestampWrites`, mutating the caller's object. Several call sites reuse descriptor
+   objects. Copy, or document the mutation.
+4. **`beginComputePass()` with no descriptor throws** once timers are on, at
+   `timers.getComputeWrites(descriptor.label)`. Currently latent because every call site passes one.
+
+### 1.3 The structure half
+
+`FrameGraph.exportToJson()` is most of the dependency model already:
+
+```js
+{
+  passes:    [{ id, name, culled, reads: [node_id], writes: [node_id] }],
+  resources: [{ id, name, transient, version?, description?, createdBy?, readers?, writers? }]
+}
+```
+
+Keyed by **resource node** (per version), not by registry entry — deliberately, so
+`passes[].reads/writes` stay resolvable across versions. The recording format must preserve that
+choice; a registry-keyed export dangles every reference past version 0.
+
+What it does *not* carry, and we want:
+
+- `FrameGraphNode.scope` — the `FrameGraphScope` chain, which is the hierarchy a flame graph needs.
+- `ref_count` and `has_side_effects` — why a pass survived culling.
+- Typed descriptors. `description` is `resource_descriptor.toString()`, a human string
+  (`"Buffer{ size = 1,048,576, usage = STORAGE | COPY_DST }"`). We want the fields.
+
+### 1.4 The gap: labels are not keys
+
+```js
+// graph_build_hzb.js
+const builder = graph.add("hzb/ build", data, (data, resources, context) => {
+    hzb.build(context.encoder, source, viewport);   // opens N compute passes, its own labels
+});
+```
+
+`GPUTimerArray` records the labels `hzb.build` chose. `FrameGraph` records `"hzb/ build"`. Nothing
+relates them, and the relation is not derivable after the fact — labels are not unique, not stable,
+and one graph pass legitimately produces many GPU passes.
+
+**Fix:** bracket `node.execute(...)` inside `FrameGraph.execute`
+([FrameGraph.js:604](src/engine/graphics/render/frame_graph/FrameGraph.js:604)) so the context knows
+which graph pass is open. Every GPU pass begun while that bracket is open is attributed to it. The
+same bracket should emit `pushDebugGroup(node.name)` / `popDebugGroup()`, which costs nothing and
+immediately improves what RenderDoc, PIX and webgpu-inspector show — worth doing on its own merits.
+
+### 1.5 Work sizes are not observable today
+
+`beginComputePass` / `constructComputePass` return the **raw** `GPUComputePassEncoder`. All 11
+production `dispatchWorkgroups` call sites talk to it directly, as does every draw call across the
+31 render-pass construction sites. Editing every one of them to report its own counts is the wrong
+trade. A proxy encoder, installed only while recording, is one class.
+
+`SoftwareGPUComputePassEncoder` already models exactly this: it records
+`{pipeline, bind_groups, dynamic_offsets, group_counts}` per dispatch. The recording proxy is the
+same shape with a real encoder behind it.
+
+---
+
+## 2. What the platform will give us
+
+### 2.1 Timestamp quantization — the headline constraint
+
+Chrome quantizes `timestamp-query` results to **100 µs** as a timing-attack mitigation. It is
+disabled by `chrome://flags/#enable-webgpu-developer-features`; that flag does not itself enable the
+feature, which additionally needs the device to expose `timestamp-query`.
+
+100 µs is 0.1 ms. A Shade frame at 60 Hz has ~16.6 ms of budget spread over a couple of hundred
+passes. **The median pass is below the quantum.** Unmitigated, the tool reports a histogram of zeros
+with occasional 100 µs spikes, and every conclusion drawn from it is noise.
+
+Three consequences, all of which belong in the design rather than in a README:
+
+- **Measure the quantum, do not assume it.** At session start, run a calibration: submit a known
+  workload repeatedly, collect raw timestamp values, take the GCD of the deltas. Store the result as
+  `timestamp_period_ns` in the recording header.
+- **Stamp it into the container** so the inspector knows what it is looking at without being told.
+- **The inspector refuses to draw a precise-looking picture from imprecise data.** If
+  `timestamp_period_ns > 1000`, the timeline renders spans with explicit uncertainty bars and a
+  persistent banner naming the flag. Not a footnote in a tooltip.
+
+There is a real mitigation beyond the flag: **aggregate across frames.** 600 frames of a 40 µs pass
+quantized to 100 µs still average toward ~40 µs, because the quantization is in practice a floor
+applied to a free-running counter rather than a deterministic snap of the duration. The inspector's
+statistical view is therefore not a nicety — on a default browser it is the *only* trustworthy view.
+This shapes the format: keep every frame's raw values, never pre-aggregate on the recorder side.
+
+### 2.2 Pass granularity is the floor
+
+WebGPU writes timestamps at pass boundaries only. Per-draw timing needs
+`chromium-experimental-timestamp-query-inside-passes`, which is Chromium-only and experimental.
+
+**Design for pass granularity.** Treat inside-passes as an optional capability the recorder probes
+for and, if present, uses to add sub-pass markers — recorded as a distinct span kind so the format
+does not pretend the two are the same measurement.
+
+### 2.3 No CPU↔GPU clock sync
+
+WebGPU exposes no calibration between `performance.now()` and the GPU timestamp domain. Anything
+claiming to place CPU and GPU events on one axis is guessing.
+
+**Be honest in the format.** Record two clocks explicitly: a CPU track from `performance.now()`
+(encode time, submit time, callback time) and a GPU track from timestamps. The inspector shows two
+tracks anchored per frame at submit, and says the alignment is nominal. Perfetto solves this problem
+with explicit `ClockSnapshot` packets and a clock graph; we do not have the snapshots, so we do not
+get to claim the sync.
+
+### 2.4 Cross-query-set comparability
+
+Timestamps from two different `GPUQuerySet`s are not specified to share a domain. In Dawn they do in
+practice. Since each `ShadeGPUCommandContext` currently gets its own `GPUTimerArray`, and a frame has
+several contexts, **every frame already spans several query sets.**
+
+Record a `query_set_id` per span. Then the inspector can, if a capture ever looks wrong, colour
+spans by origin and let the reader see whether the anomaly follows a set boundary. Cheap; makes an
+otherwise unfalsifiable class of bug visible.
+
+### 2.5 Indirect work is unknowable at encode time
+
+`dispatchWorkgroupsIndirect` and `drawIndirect` take their counts from a GPU buffer. At encode time
+we know only *that* it was indirect. Two options, both worth having:
+
+- **v1:** record the indirect flag plus the source buffer's id and offset. The inspector shows
+  "indirect (unknown)" and links to the buffer.
+- **v2 (opt-in, costly):** the recorder copies indirect argument buffers into a readback staging
+  buffer at encode time and resolves the actual counts after submit. This is the only way to see the
+  real post-cull draw count, which for a GPU-driven renderer is one of the numbers most worth seeing.
+  It changes memory traffic, so it must be a flag, and the format must mark such counts as
+  *resolved* rather than *encoded* so nobody compares the two carelessly.
+
+### 2.6 Prior art
+
+| Tool | What to take | What to leave |
+|---|---|---|
+| [webgpu_inspector](https://github.com/brendan-duncan/webgpu_inspector) (Brendan Duncan) | The reference point for WebGPU frame capture in a browser. Object inspection with creation stacktraces; frame-time plotting; buffer content view. Its recorder emits a standalone replayable HTML file. | It is a *generic API* interceptor, extension-hosted. We want *engine-semantic* data — frame graph passes, resource lifetimes, cull decisions — which a generic interceptor cannot see. Complementary, not competing. |
+| [Perfetto](https://perfetto.dev/docs/getting-started/other-formats) | Track/slice model; nested slices; counter tracks; explicit clock domains. Its JSON importer is a free escape hatch — see §5.6. | The protobuf format and the full trace-processor stack are far more than we need, and its UI knows nothing about resource dependency. |
+| RenderDoc / PIX / Radeon GPU Profiler | The three-pane idiom: event list, timeline, per-event detail; a resource view keyed by lifetime; "why is this bound" attribution. | Native capture, replay, driver counters. Out of reach on WebGPU. |
+| Chrome Trace Event Format | Trivially writable, universally readable. | Text JSON at our event rates is 5–10× our binary size. Export target, not storage. |
+| [webgpufundamentals timing](https://webgpufundamentals.org/webgpu/lessons/webgpu-timing.html) | The canonical treatment of the query-set/resolve/map dance and its pitfalls. | — |
+
+The gap in that table is the whole reason to build this: **no existing tool knows what a Shade frame
+graph is.** Timings without the dependency structure tell you a pass is slow; timings *with* it tell
+you a pass is slow because it waits on a resource that a culled branch still produced.
+
+---
+
+## 3. What a recording must contain
+
+Three axes were asked for. A fourth is needed to make the first three legible.
+
+### 3.1 Timings
+
+| Datum | Source | Cost |
+|---|---|---|
+| GPU pass begin/end, ns | `GPUTimerArray` | free, already there |
+| Which query set a span came from | recorder | 1 byte |
+| CPU encode time per graph pass | `performance.now()` around `node.execute` | ~2 × 200 calls/frame |
+| CPU submit timestamp | `ShadeGPUCommandContext.finish` | free |
+| Callback/readback latency | recorder | free |
+| Sub-pass markers | `chromium-experimental-timestamp-query-inside-passes` if present | optional |
+
+### 3.2 Dependencies
+
+Straight from `FrameGraph`, enriched:
+
+- Passes: id, name, scope chain, culled, `ref_count`, `has_side_effects`, reads/writes/creates.
+- Resource nodes: id, name, version, transient/imported, producer, readers, writers.
+- Per graph pass: the GPU passes it opened, in order — the join from §1.4.
+- Resource lifetime: first write → last read, derivable from `ResourceEntry.last`, which `compile()`
+  already computes.
+
+### 3.3 Data sizes
+
+Descriptors carry everything:
+
+| Resource | Fields | Footprint |
+|---|---|---|
+| Buffer | `size` bytes, `usage` bitmask, `ensure_cleared` range | `size` directly |
+| Texture | `resolution[3]`, `format`, `dimension`, `mipLevelCount`, `sampleCount`, `usage` | computed from `gpu_texture_format_info` — `bytes_per_block`, `block_width`, `block_height` — summed over the mip chain, × `sampleCount` |
+
+These are **declared** sizes, not allocated ones; a pooled allocator may serve a larger block.
+`GraphicsContext.gpu_memory_usage` gives the real total per frame — record it as a counter track and
+let the inspector show declared-vs-actual as the aliasing metric it is.
+
+### 3.4 Work sizes
+
+| Datum | Needs |
+|---|---|
+| `dispatchWorkgroups(x, y, z)` | proxy encoder |
+| Workgroup size from the shader (`@workgroup_size`) | pipeline descriptor, recorded once per pipeline |
+| Total invocations = groups × workgroup size | derived in the inspector |
+| `draw` / `drawIndexed` vertex, index, instance counts | proxy encoder |
+| Indirect flag + argument buffer id/offset | proxy encoder |
+| Resolved indirect counts | §2.5 v2, opt-in |
+| Bind group contents per dispatch | proxy encoder; **large** — gate behind a verbosity level |
+| Render pass attachment formats and load/store ops | pass descriptor |
+
+### 3.5 The fourth axis — context, so any of it means anything
+
+Without this a shared recording is unreadable:
+
+- Adapter info (`vendor`, `architecture`, `device`, `description`), features, the limits that matter.
+- Engine version, git revision, build flags, `ENV_PRODUCTION`.
+- Renderer settings: internal vs output resolution, upscaler, which features are on.
+- `timestamp_period_ns` (§2.1) and whether the developer-features flag was detected.
+- Wall-clock start, session id, user-supplied note.
+- Scene scale: mesh/instance/light counts, resident material and geometry bytes.
+
+---
+
+## 4. Architecture
+
+```
+  ENGINE (ships)                      CONTAINER                 INSPECTOR (published separately)
+  ─────────────────────               ─────────                 ───────────────────────────────
+  GPUTimerArray ────┐
+  FrameGraph ───────┤                                            ┌── timeline / flame graph
+  proxy encoders ───┼──> GPUProfileRecorder ──> .sgpt ──drop──>  ├── dependency graph
+  GraphicsContext ──┘         │                  bytes           ├── resource table
+                              │                                  ├── pass detail
+                       sgpt_write_*                              └── frame comparison
+                              │                                          │
+                        BinaryBuffer  <───────────────────────────  sgpt_read_*
+```
+
+**Three rules that keep this from rotting.**
+
+1. **The container is the only interface.** The inspector imports the format readers and
+   `BinaryBuffer`. It never imports Shade, `FrameGraph`, or anything under `src/shade/renderer/`.
+   This is a licensing constraint as much as an architectural one — meep is proprietary and
+   source-available, and a separately published inspector must not carry renderer internals.
+2. **The recorder never blocks the frame.** Every buffer it touches is written at encode time or
+   read after submit. Serialization runs off the frame — accumulate into per-frame plain records,
+   encode to bytes when the session stops or when a chunk fills.
+3. **Reader and writer live together, in the engine tree.** Under
+   `src/shade/device/timing/profile/`, one file per concern, matching the `vgeo_*` convention. The
+   inspector package imports them by path. One definition of the format; no drift.
+
+### 4.1 Verbosity levels
+
+A capture is a trade between fidelity and cost. Four levels, recorded in the header:
+
+| Level | Adds | Bytes/frame, ~200 passes |
+|---|---|---|
+| 0 `TIMING` | GPU pass spans, frame boundaries | ~2 KB |
+| 1 `STRUCTURE` | + frame graph topology, resource descriptors, cull state | ~2 KB amortised (§5.4) |
+| 2 `WORKLOAD` | + dispatch/draw counts, pipeline identities, attachment state | ~6 KB |
+| 3 `VERBOSE` | + bind group contents, indirect readback, CPU per-pass timing | ~40 KB |
+
+Levels 0–2 are the product. Level 3 is for us, on a repro, and the inspector should say so when it
+opens one.
+
+---
+
+## 5. The `.sgpt` container
+
+**S**hade **G**PU **P**rofile **T**race. Magic `0x54505347` — the ASCII bytes `S G P T` read as a
+little-endian u32 at offset 0, matching the `VGEO_MAGIC` convention in
+[VGEO_MAGIC.js](src/shade/renderer/geometry/virtual/format/header/VGEO_MAGIC.js).
+
+### 5.1 Why binary, concretely
+
+A 600-frame capture at level 2, ~200 passes/frame, in Chrome Trace Event JSON: each span is roughly
+`{"ph":"X","name":"...","cat":"gpu","ts":123456.7,"dur":234.5,"pid":1,"tid":3,"args":{...}}` — call
+it 140 bytes minified, times 120,000 spans, **~17 MB**, before pass arguments. The same content in
+the layout below is **~1.5 MB**, and gzip (already a dependency via `pako`, and available natively
+via `CompressionStream`) takes it under 400 KB. That is the difference between a capture you attach
+to a bug report and one you do not.
+
+### 5.2 Layout
+
+Chunked, directory at the tail — so a writer streams forward and only seeks back once, and a reader
+can pull the header and the frame index without reading the payload.
+
+```
+  offset  size   field
+  ──────────────────────────────────────────────────────────────────
+       0     4   magic                        u32   0x54505347
+       4     2   format_version               u16
+       6     2   min_reader_version           u16
+       8     4   flags                        u32   bit0 = payload deflated
+      12     4   header_checksum              u32   over bytes [0, 12)
+      16     8   directory_offset             u64
+      24     8   directory_byte_length        u64
+      32   ...   chunks, in write order
+     ...   ...   directory
+```
+
+Chunk framing, uniform:
+
+```
+       0     4   chunk_type                   u32   FourCC
+       4     8   payload_byte_length          u64
+      12   ...   payload
+```
+
+### 5.3 Chunks
+
+| FourCC | Purpose | Cardinality |
+|---|---|---|
+| `META` | §3.5 context. Adapter, engine version, settings, `timestamp_period_ns`, verbosity level, session note. | 1 |
+| `STRS` | String table. Every name, label, format, scope name — written once, referenced by u32 index. | 1 |
+| `PIPE` | Pipeline table: id, label, kind, shader module name, `@workgroup_size`, entry point, vertex layout digest. | 1 |
+| `TOPO` | Frame-graph **topologies**: pass list, resource node list, edges, scopes, descriptors. Content-hashed and deduplicated across frames (§5.4). | 0..n |
+| `FRAM` | One per frame: topology id, CPU timestamps, span array, dispatch/draw array, counters. | 0..n |
+| `CNTR` | Counter tracks sampled per frame: `gpu_memory_usage`, mesh/instance/light counts, resolution. | 0..1 |
+| `NOTE` | Free-form user annotations with a frame index — "this is where it hitches". | 0..n |
+| `DIRE` | Directory: `{chunk_type, offset, byte_length}` plus a frame index of `{frame_number, chunk_offset, gpu_duration_ns}` so the inspector can draw the frame-time strip before parsing anything else. | 1 |
+
+Unknown chunk types are skipped by length. That is what makes level-3 payloads addable without a
+version bump, and what lets an old inspector open a new capture and say honestly which parts it
+cannot show.
+
+### 5.4 The compression that matters: topology deduplication
+
+**A Shade frame graph is nearly identical frame to frame.** Same passes, same resources, same edges;
+what changes is the timings, the cull decisions, and the occasional resolution change. Recording the
+full topology 600 times is the difference between a 20 MB file and a 1.5 MB one.
+
+So: hash the recorded topology (pass names, edges, descriptors, scope chain). If the hash matches a
+`TOPO` already written, the frame stores only the topology id. Cull state and per-pass timings stay
+in `FRAM`, because they are exactly what varies.
+
+Expected behaviour on a real capture: a handful of distinct topologies over 600 frames — steady
+state, plus the shadow-refresh variants, plus resolution changes. §4.1's "~2 KB amortised" for level
+1 is that claim.
+
+This must be **measured, not assumed**. If topologies turn out to churn every frame, the design
+still works (it degrades to storing each), but the size estimates in §5.1 do not. First milestone
+work item, §8.
+
+### 5.5 Per-frame span encoding
+
+Per span, level 0:
+
+| Field | Type | Note |
+|---|---|---|
+| `pass_ref` | `uintVar` | index into the topology's GPU-pass list |
+| `t_begin` | `u32` | ns offset from the frame's `gpu_epoch_ns` |
+| `t_end_delta` | `uintVar` | ns from `t_begin` |
+| `query_set_id` | `u8` | §2.4 |
+
+`u32` for the frame-relative begin holds 4.29 s — three orders of magnitude of headroom over a
+frame, and it survives a stall without overflowing. `BinaryBuffer.writeUintVar` / `readUintVar`
+already exist and handle the two variable-length fields.
+
+That is ~10 bytes per span against 26 for a naive absolute-u64 encoding, and the frame's absolute
+epoch is stored once as a `u64`.
+
+### 5.6 Chrome Trace Event export
+
+The inspector exports the loaded capture as Chrome Trace Event JSON, for opening in
+[ui.perfetto.dev](https://perfetto.dev/docs/getting-started/other-formats). Costs an afternoon and
+buys: a second opinion when the inspector looks wrong, a viewer for anyone unwilling to run ours, and
+a sanity check on our own timeline maths. Passes become `X` slices on a GPU track, scopes become
+nesting, counters become `C` events. Lossy — the dependency graph has no representation there — which
+is precisely why it is an export and not the storage format.
+
+### 5.7 String encoding
+
+Use an explicit `STRS` table with u32 indices rather than `EncodingBinaryBuffer`. The latter
+deduplicates by writing back-references to **absolute buffer positions**
+([EncodingBinaryBuffer.js:21](src/core/binary/EncodingBinaryBuffer.js:21)), which is correct for a
+single flat buffer and wrong the moment chunks are written out of order, compressed independently, or
+skipped by a reader that does not understand them. An index table costs one indirection and is
+robust against all three.
+
+---
+
+## 6. The recorder
+
+### 6.1 Surface
+
+```js
+const session = new GPUProfileSession({
+    graphics,
+    level: GPUProfileLevel.WORKLOAD,
+    max_frames: 600,
+    note: "hitch on shadow refresh, RTX 3070"
+});
+
+session.start();
+// ... frames run ...
+const bytes = await session.stop();     // ArrayBuffer, ready to save
+```
+
+`Renderer` gets `begin_profile(options)` / `end_profile()` wrapping it, so the common case is two
+calls and no wiring. `add_debug_frame` and `onFrameDebug` stay as they are — cheap, synchronous,
+console-shaped, and a different tool for a different question.
+
+### 6.2 The five hooks
+
+1. **`FrameGraph.execute`** — bracket `node.execute(...)`. Notify the context which graph pass is
+   open; take CPU timestamps either side; push/pop a debug group. The only edit outside `src/shade/`.
+   Guarded so a graph with no listener does nothing.
+2. **`ShadeGPUCommandContext`** — a `#profile_sink` field. When set, `beginComputePass` /
+   `beginRenderPass` report `{label, kind, graph_pass_id, query_slot, query_set_id}` and wrap the
+   returned encoder in the recording proxy.
+3. **The proxy encoders** — `ProfilingComputePassEncoder`, `ProfilingRenderPassEncoder`. Forward
+   everything; record `dispatchWorkgroups*`, `draw*`, `setPipeline`, `setBindGroup`. Modelled on
+   `SoftwareGPUComputePassEncoder`, which already records exactly this shape.
+4. **`GPUTimerArray`** — pooling (§1.2.2), bound checking (§1.2.1), and expose raw slot data rather
+   than only the console table.
+5. **`GraphicsContext`** — sample `gpu_memory_usage` and the collection counters once per frame into
+   the counter track.
+
+### 6.3 Cost when off
+
+Every hook is a null check against a field that is `undefined` in normal operation. No allocation and
+no proxy construction; the frame-graph bracket is two comparisons per pass. This must stay true — a
+profiler that costs something when disabled will be disabled at the build level and then rot.
+
+### 6.4 Cost when on
+
+Level 0–2 add: one `performance.now()` pair per graph pass, one small record per GPU pass, one per
+dispatch/draw, and a `push`/`popDebugGroup` pair per graph pass. The existing per-context query set
+churn (§1.2.2) is the largest cost and the pool removes it. Expect single-digit percent frame-time
+overhead at level 2; measure it and record the measurement in `META`, so a reader can see how much of
+what they are looking at is the observer.
+
+---
+
+## 7. The inspector
+
+`packages/gpu-inspector-tool/`. A static site: drop a `.sgpt` on it, or pass `?file=` for a
+bookmarkable view — the affordance `prototypeVGEOFormatViewer` already established in this codebase.
+
+### 7.1 Technology
+
+**Plain ES modules, Canvas 2D for the timeline, DOM for panels, no runtime dependencies, built with
+Vite.** Reasons: the repo has no UI framework and adding one for this is unjustified; the timeline is
+a custom-drawn virtualised widget that a framework would only get in the way of; zero dependencies
+keeps a separately published proprietary artifact simple to reason about; and Vite is already the dev
+server here.
+
+The only imports from the engine tree are `src/core/binary/BinaryBuffer.js` and the `sgpt_*` readers.
+That boundary is a build-time assertion, not a convention — a lint rule that fails the build on any
+other engine import.
+
+### 7.2 Views
+
+| View | Answers |
+|---|---|
+| **Frame strip** | Which frame is interesting. Frame time over the session, GPU and CPU overlaid, hitches marked, brush to select a range. Drawn from the directory index alone, so it appears before the payload finishes parsing. |
+| **Timeline / flame graph** | Where the time went in *this* frame. Spans on a GPU track, nested by `FrameGraphScope`; a CPU track above with encode time; hover for exact ns; click to select. Uncertainty rendering when `timestamp_period_ns` is coarse (§2.1). |
+| **Statistics** | Where the time goes *in general*. Per-pass min/median/p95/max/total across the selected frame range, sorted by total contribution. **On a default-quantization capture this is the only honest view**, and the inspector should open on it in that case rather than on the timeline. |
+| **Dependency graph** | Why this pass runs, and what it waits on. Passes and resource nodes, culled ones greyed, edges directed. Select a pass → highlight its transitive inputs. Select a resource → its version chain and every reader. |
+| **Resource table** | What memory costs. Every resource node with declared bytes, format, usage, transient/imported, lifetime span, peak concurrent footprint. Sorted by size. Declared total vs `gpu_memory_usage` side by side. |
+| **Pass detail** | Everything about one pass. Timings across frames as a sparkline, dispatch/draw counts, derived total invocations, pipeline and workgroup size, attachments, bindings at level 3. |
+| **Frame comparison** | What changed. Two frames or two ranges side by side, per-pass deltas sorted by regression. This is the view that makes the tool useful for optimisation work rather than only for diagnosis. |
+
+### 7.3 What it must refuse to do
+
+- **Never interpolate across the quantum.** If the data is 100 µs-granular, no view draws a 12 µs
+  span. Draw the quantum.
+- **Never present the CPU and GPU tracks as one clock** (§2.3). Two tracks, anchored per frame,
+  labelled as nominal.
+- **Never hide dropped spans.** If the recorder dropped passes on slot exhaustion (§1.2.1), say how
+  many, on the frame that dropped them.
+
+---
+
+## 8. Phasing
+
+Each milestone is independently useful and independently shippable.
+
+### M0 — Measure the assumptions (½ day)
+
+Before any of the below. Instrument one Sponza capture and answer three questions, because three
+size estimates and one whole design decision rest on them:
+
+1. How many distinct frame-graph topologies over 600 frames? (§5.4)
+2. What is the observed `timestamp_period_ns` on our dev machines, flag on and flag off? (§2.1)
+3. How many GPU passes per frame, actually? (`GPUTimerArray` default is 1024 slots; §1.2.1)
+
+Write the answers into this document.
+
+### M1 — Timing spine (2–3 days)
+
+`GPUTimerArray` pooling and bound checks; the `FrameGraph.execute` bracket and debug groups;
+`GPUProfileSession` at level 0; `META`/`STRS`/`FRAM`/`DIRE` chunks; round-trip test on
+`SoftwareGPUDevice`. Deliverable: a `.sgpt` with real spans and no viewer.
+
+### M2 — Inspector skeleton (2–3 days)
+
+Package scaffold, format readers, drop target, frame strip, timeline, pass detail. Deliverable: a
+capture you can look at.
+
+### M3 — Structure (2–3 days)
+
+`TOPO` chunk with deduplication; resource descriptors; scopes; cull state. Dependency graph and
+resource table in the inspector. Deliverable: the "why is this pass here" question becomes
+answerable.
+
+### M4 — Workload (2–3 days)
+
+Proxy encoders; `PIPE` chunk; dispatch/draw counts; derived invocation counts. Deliverable: the "is
+this dispatch the right size" question becomes answerable.
+
+### M5 — Analysis (2–3 days)
+
+Statistics view, frame comparison, counter tracks, Chrome Trace Event export.
+
+### M6 — Publish (1–2 days)
+
+Build target, static hosting, a format specification document written for someone outside the
+company, and the sharing story: what a user sends us and what we can read from it.
+
+**Not in scope, listed so it stays that way:** buffer/texture content capture, shader source in the
+container, replay, live attach to a running session, anything requiring a browser extension.
+
+---
+
+## 9. Testing
+
+Per the established tiers:
+
+| Tier | Covers |
+|---|---|
+| **Unit, node** | Format round-trip: build a synthetic session, encode, decode, assert structural equality. Every chunk. Forward compatibility: a reader skipping an unknown chunk. Truncation and corruption: a bad checksum, a short chunk, a directory pointing past EOF — all must fail with a named error, not a stack trace out of `BinaryBuffer`. |
+| **`SoftwareGPUDevice`** | The recorder end to end without a GPU. The device already emulates `timestamp-query`, query sets and `write_pass_timestamp`, and already refuses a query set over 4096. Encode a frame graph, run a session, decode the output, assert the topology matches what was recorded. This is where the §1.4 attribution logic gets its coverage. |
+| **Playground page** | `src/shade/playground/` gets a capture harness against Sponza, which is also how M0 gets answered. |
+| **Inspector** | Golden captures checked into the package as fixtures. Parse-and-render smoke tests. A capture recorded before a format change must still open — that is what `min_reader_version` is for and it needs a test that proves it. |
+
+---
+
+## 10. Risks and open questions
+
+| Risk | Severity | Handling |
+|---|---|---|
+| **Timestamp quantization makes captures useless on default browsers** (§2.1) | **High** | Measure and record the period; make the statistics view the default when it is coarse; document the flag prominently. Accept that shared user captures will mostly be coarse. |
+| Topology dedup does not pay off | Medium | M0 measures it. Design degrades gracefully; the size claims do not. |
+| Proxy encoder overhead distorts what it measures | Medium | Level-gate it; record measured overhead in `META`; forward-only methods, no allocation per call. |
+| One `GPUTimerArray` per context means several query sets per frame (§2.4) | Low–Medium | Record `query_set_id`. Consider a per-frame shared array as a follow-up, which would also simplify pooling. |
+| Format churn during development invalidates captures | Low | `min_reader_version` from day one; the inspector reads every version it ever supported; fixtures in the test suite. |
+| Publishing a proprietary-engine tool separately | Low, but real | The §4 rule-1 boundary is what makes this tractable. Enforce it in the build. Confirm the licensing intent for the published inspector before M6. |
+
+**Open questions for you:**
+
+1. **Monorepo or not.** `packages/` does not exist and this repo has no workspaces. Options: (a) npm
+   workspaces with `packages/gpu-inspector-tool` as a real workspace — cleanest, touches the root
+   `package.json` and CI; (b) an unreferenced directory with its own `package.json`, built manually —
+   zero risk to the engine build, worse ergonomics. **Recommendation: (a)**, but it is your call
+   whether you want workspaces in this repo at all.
+2. **Does the recorder ship in production builds?** Rollup runs `@rollup/plugin-strip`. Shipping it
+   means users can send us captures, which is the stated goal; it also means the hooks survive
+   stripping and the null-check cost must genuinely be zero.
+3. **How much does the frame-graph bracket in `FrameGraph.execute` bother you?** It is the one edit
+   outside `src/shade/` and outside the profiler's own files. The alternative — inferring attribution
+   from labels — does not work (§1.4).
+4. **Recording length policy.** Ring buffer of the last N frames (good for "capture the hitch that
+   just happened") or explicit start/stop (good for reproducible benchmarks)? Both are cheap; the
+   ring buffer is more useful in the field. **Recommendation: both, ring by default.**

package/src/shade/renderer/postprocess/nss/NSS.d.ts

@@ -49,7 +49,7 @@ export class NSS {
      * @returns {number}
      */
     static recommended_jitter_sequence_size(upscale_ratio: number): number;
-    static "__#126@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
+    static "__#131@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
     /**
      * @param {GraphicsContext} graphics
      */

package/src/shade/renderer/rasterize/native/oit/shader_oit_blend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_oit_blend.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/oit/shader_oit_blend.js"],"names":[],"mappings":"AAwDA,2CAkBE;4BAxE0B,gCAAgC"}
+{"version":3,"file":"shader_oit_blend.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/oit/shader_oit_blend.js"],"names":[],"mappings":"AAyDA,2CAkBE;4BAzE0B,gCAAgC"}

package/src/shade/renderer/rasterize/native/oit/shader_oit_blend.js

@@ -29,10 +29,11 @@ fn main(
     let accum_alpha = accum_transparent.a;
     
     if(is_nan(accum_transparent.r)){
-        // not sure why we get invalid results, but we do
-        // this removes the pixel from the final image
-        // the final image ends up looking correct as far as I can tell
-        // TODO investigate
+        // Backstop: one NaN fragment in the resolve pass poisons the whole pixel of the
+        // additive accumulator, so dropping the pixel beats smearing NaN into the frame.
+        // The known source — the c[2] -> 0 division in
+        // compute_transmittance_from_4_power_moments, visible as a camera-locked stripe —
+        // is guarded at the source now; this remains for any future NaN in forward shading.
         discard;
     }