@woosh/meep-engine 3.11.1 → 3.11.3

package/src/shade/device/mock/SoftwareGPURenderPassEncoder.js

@@ -1,4 +1,6 @@
 import { normalize_dynamic_offsets } from "./normalize_dynamic_offsets.js";
+import { pipeline_immediate_size } from "./pipeline_immediate_size.js";
+import { SoftwareGPUImmediateData } from "./SoftwareGPUImmediateData.js";
 import { SoftwareGPUObjectBase } from "./SoftwareGPUObjectBase.js";
 import { write_pass_timestamp } from "./write_pass_timestamp.js";
 
@@ -79,6 +81,14 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     #scissor = null;
 
+    /**
+     * Immediate data for this pass. Per-encoder state in WebGPU, and a new pass starts over — which
+     * is why it is constructed here rather than carried in from the command encoder.
+     *
+     * @type {SoftwareGPUImmediateData}
+     */
+    #immediates;
+
     #ended = false;
 
     /**
@@ -99,6 +109,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
 
         this.#encoder = encoder;
         this.descriptor = descriptor;
+        this.#immediates = new SoftwareGPUImmediateData(encoder.device.limits.maxImmediateSize);
 
         write_pass_timestamp(descriptor, 'beginningOfPassWriteIndex');
     }
@@ -138,6 +149,22 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
         );
     }
 
+    /**
+     * @param {number} range_offset byte offset into the immediate data range
+     * @param {ArrayBuffer|ArrayBufferView} data
+     * @param {number} [data_offset] in elements if `data` is a TypedArray, bytes otherwise
+     * @param {number} [data_size] in elements if `data` is a TypedArray, bytes otherwise
+     */
+    setImmediates(range_offset, data, data_offset = 0, data_size) {
+        this.#assert_encoding();
+
+        const message = this.#immediates.write(range_offset, data, data_offset, data_size);
+
+        if (message !== null) {
+            this.#encoder.notify_pass_validation_error(message);
+        }
+    }
+
     /**
      * @param {number} slot
      * @param {GPUBuffer} buffer
@@ -206,6 +233,24 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
         this.stencil_reference = reference;
     }
 
+    /**
+     * WebGPU's *Validate immediate data*: every slot the pipeline's immediate range covers must have
+     * been written before a command reads it. The bytes default to zero but the slots do not default
+     * to set, so a forgotten `setImmediates` is a refused draw on a real device rather than a shader
+     * quietly reading zeroes. Catching it here is the whole reason the slot bookkeeping exists.
+     *
+     * @returns {void}
+     */
+    #validate_immediates() {
+        const size = pipeline_immediate_size(this.#pipeline);
+
+        if (size > 0 && !this.#immediates.isRangeSet(0, size)) {
+            this.#encoder.notify_pass_validation_error(
+                `draw: pipeline declares ${size} bytes of immediate data, and not all of it was set by setImmediates`
+            );
+        }
+    }
+
     /**
      * The state a draw would run under, copied so later state changes do not rewrite a draw already
      * recorded.
@@ -221,6 +266,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
             index_buffer: this.#index_buffer,
             viewport: this.#viewport,
             scissor: this.#scissor,
+            immediates: this.#immediates.snapshot(),
         };
     }
 
@@ -230,6 +276,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     draw(vertex_count, instance_count = 1) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.draws.push({
             ...this.#snapshot(),
@@ -246,6 +293,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     drawIndexed(index_count, instance_count = 1) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.draws.push({
             ...this.#snapshot(),
@@ -262,6 +310,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     drawIndirect(indirect_buffer, indirect_offset) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.draws.push({
             ...this.#snapshot(),
@@ -281,6 +330,7 @@ export class SoftwareGPURenderPassEncoder extends SoftwareGPUObjectBase {
      */
     drawIndexedIndirect(indirect_buffer, indirect_offset) {
         this.#assert_encoding();
+        this.#validate_immediates();
 
         this.draws.push({
             ...this.#snapshot(),

package/src/shade/device/mock/pipeline_immediate_size.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bytes of immediate data a pipeline's layout declares, or 0 when it declares none.
+ *
+ * A pipeline built with `layout: "auto"` reports 0 rather than deriving a size: deriving one would
+ * mean reading the WGSL, and nothing in this folder compiles WGSL.
+ *
+ * @param {GPUPipelineBase|null} pipeline
+ * @returns {number}
+ */
+export function pipeline_immediate_size(pipeline: GPUPipelineBase | null): number;
+//# sourceMappingURL=pipeline_immediate_size.d.ts.map

package/src/shade/device/mock/pipeline_immediate_size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline_immediate_size.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/pipeline_immediate_size.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,kDAHW,kBAAgB,IAAI,GAClB,MAAM,CAUlB"}

package/src/shade/device/mock/pipeline_immediate_size.js

@@ -0,0 +1,18 @@
+/**
+ * Bytes of immediate data a pipeline's layout declares, or 0 when it declares none.
+ *
+ * A pipeline built with `layout: "auto"` reports 0 rather than deriving a size: deriving one would
+ * mean reading the WGSL, and nothing in this folder compiles WGSL.
+ *
+ * @param {GPUPipelineBase|null} pipeline
+ * @returns {number}
+ */
+export function pipeline_immediate_size(pipeline) {
+    const layout = pipeline?.descriptor?.layout;
+
+    if (layout === undefined || layout === null || layout === "auto") {
+        return 0;
+    }
+
+    return layout.immediateSize ?? 0;
+}

package/src/shade/device/pipeline/PipelineLayoutManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PipelineLayoutManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/PipelineLayoutManager.js"],"names":[],"mappings":"AAGA;IAMI;;;OAGG;IACH,+BAEC;IAoBD;;;;OAIG;IACH,2DAFa,4BAA0B,SAAS,CAI/C;IAgBD;;;;OAIG;IACH,iFAKC;IAED;;;;OAIG;IACH,8EAEC;;CAkBJ"}
+{"version":3,"file":"PipelineLayoutManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/PipelineLayoutManager.js"],"names":[],"mappings":"AAGA;IAMI;;;OAGG;IACH,+BAEC;IAoBD;;;;OAIG;IACH,2DAFa,4BAA0B,SAAS,CAI/C;IAgBD;;;;OAIG;IACH,iFAKC;IAED;;;;OAIG;IACH,8EAEC;;CAmBJ"}

package/src/shade/device/pipeline/PipelineLayoutManager.js

@@ -89,6 +89,7 @@ export class PipelineLayoutManager {
         return this.#device.createPipelineLayout({
             label: descriptor.label,
             bindGroupLayouts,
+            immediateSize: descriptor.immediateSize,
         });
 
     }

package/src/shade/playground/volumetrics_froxel/README.md

@@ -30,6 +30,36 @@ Those fixes are in the permanent path now and there is nothing left to A/B. What
 the *next* change here — the performance findings especially, since every one of them trades image
 quality for time and none can be judged from a screenshot.
 
+Q-01 was judged here and now ships unconditionally: every clustered point and spot light is occluded
+by geometry, sampled with one nearest tap out of the shadow atlas. The two checkboxes that switched
+that off, or swapped the tap for the deferred pass's filter kernels, are gone along with the metadata
+word behind them — `volumetrics/NOTES.md` keeps the measurements that closed the question. The
+torches are the local lights here: 130 point lights, every one of them a shadow caster, and **zero
+spot lights**, so the spot half has no on-screen coverage on this page and is covered by
+`shader_volumetrics_build_lighting_local_shadow.spec.js` instead. Adding a `SpotLight` from the
+console is the way to look at it.
+
+Q-04 went the same way and its switch is gone too. The sun's media self-shadowing is one fetch into
+a ladder of three cascaded volumes built once a frame with their third axis on the sun, and that is
+now the only path for it: the `__VOL_SUN_SHADOW` global and the checkbox over it are removed along
+with the `sun_shadow_mode` word they drove, so nothing on this page reproduces the march/cascade
+comparison any more. Restoring it means re-adding that word and the branch in
+`shader_volumetrics_build_lighting` that reads it.
+
+Worth knowing what it was, because it is the size of what the page can no longer show. Against a
+march at `STEP_COUNT = 512` the cascades read within 1.2 mean luminance at every viewpoint here and
+across 40 to 110 degrees of field of view, while sixteen steps read **+58** and **+70** at the two
+poses beside the small fog boxes — the step there is eight units, the box is three thick, and the
+march goes straight over it. They are also cheaper: 0.37 ms against 0.53 at 1080p, 0.81 against 1.52
+at 2160p, per pass. `volumetrics/NOTES.md` has the whole measurement, including the one that says a
+*single* world-uniform box could not have been sized correctly at any resolution — every shape
+measured has a field of view at which it is 28 to 50 luminance from the truth, and which one that is
+moves with the resolution.
+
+The march itself is still in the tree and still runs: every point and spot light uses it, and so
+would a second directional light. Only the first one is amortized, because there is one ladder of
+boxes and it is aligned to one direction.
+
 ## Measuring, rather than eyeballing
 
 This pass is stochastic and temporally filtered, so most changes to it move the image by less than
@@ -50,6 +80,14 @@ confident wrong answer during the work above:
   *change → settle ~45 frames → average*, and take the floor by making an identical no-op change so
   both paths cost the same.
 
+- **Frame time here is presentation-throttled, not GPU-bound.** At 1920×1080 every setting reads
+  ~16.5 ms, including settings that do obviously different amounts of work — `ms_octaves` at 1 and at
+  8 come back within noise of each other, which is the tell. The swap chain is pacing the
+  measurement. Raise `renderer.pixel_ratio` until the GPU is the bottleneck (3 gives 3840×2160 and
+  ~10 ms of real work here), interleave the settings round-robin so drift hits all of them equally,
+  and take medians. Remember the froxel grid scales with resolution, so a per-froxel cost measured at
+  4× the pixels is 4× the one you will pay.
+
 Prefer the **signed mean** when the change has a direction; it discriminates far better than the
 mean-absolute, which is dominated by noise. C-01b read −0.148 at 60° FOV against a floor of ±0.05,
 and −1.071 at 110°: same fix, and that 7× is the `1/cos θ` scaling it predicts.
@@ -57,6 +95,68 @@ and −1.071 at 110°: same fix, and that 7× is the `1/cos θ` scaling it predi
 Also: mutating `light.intensity` does not mark the light buffer dirty, so a sweep of it renders
 identically. Remove and re-add the light instead.
 
+### measure.js
+
+`measure.js` is that protocol as code, loaded from the console rather than by the page:
+
+```js
+const m = await (await import('./measure.js')).attach();
+const r = await m.ab(v => globalThis.__VOL_TAA_ENABLED = v, false, true);
+```
+
+`attach` pauses the page's loop — which matters for a reason beyond frame counting: that loop
+assigns `renderer.pixel_ratio = window.devicePixelRatio` on every tick, ahead of its own pause check,
+so a raised pixel ratio is undone before the next frame unless the loop is stopped. `set_pixel_ratio`
+replaces the property for the same reason.
+
+Everything renders into a texture the module owns, through `Renderer.render_to_target`, which shares
+the view context and therefore all the temporal history with the canvas path. That is not a
+refinement: a canvas texture is configured by the presentation path, cannot carry `COPY_SRC`, and is
+rotated away the moment the frame is presented, so a `drawImage` off it a task later returns an empty
+bitmap — and a comparison of two blanks reports perfect agreement. Driving the frames from here also
+takes the swap chain out of the timing entirely, which is the presentation-throttling trap above.
+
+`ab` runs the two settings interleaved and takes its own floor from a repeat of each. `fly`,
+`converge_at` and `series_stats` are the camera-path half: a structure fitted to the camera can be
+perfectly correct standing still and swim under motion, and neither swimming nor the ghosting the
+0.95-blend TAA turns it into is visible in a still. `time` and `profile` answer different questions and
+`profile` is the one to believe — at 1080p, whole-frame timing of Q-04 came back with the wrong sign
+three runs in a row while the per-pass capture read it cleanly.
+
+`profile` records a `WORKLOAD` session and decodes it in the page, so a cost number does not need a
+downloaded `.sgpt` and a second tool. It returns the median duration per pass label over the frames
+it recorded. Interleave the settings and take medians across rounds even so — the run-to-run spread
+on this machine moves a pass by more than most changes to it do:
+
+```js
+const p = await m.profile({ frames: 24 });
+p['Volumetrics / build sun shadow volume 0'];
+```
+
+## Recording a GPU profile
+
+**T** starts a recording, **T** again stops it and downloads a `.sgpt` capture. The engine side is
+already there — `Renderer.profile_session` is a nullable field and the null checks around it are the
+whole integration — so this page is only the two imports, the key handler, and the metadata a capture
+needs in order to mean anything later: adapter, engine version, device features, and a note carrying
+the viewpoint, FOV, pixel ratio and volumetric TAA setting that were in force when you pressed the
+key.
+
+Level is `WORKLOAD`: pass spans, the frame graph, and dispatch/draw counts. Measured on this page it
+runs about 11 KB a frame — roughly 660 KB/s at 60 Hz, and around 393 spans per frame — with the frame
+graph topology stored once and shared by every frame. `VERBOSE` above it adds bind group contents at
+about seven times the rate and wants a frame limit set; `PROFILE_LEVEL` in `main.js` is the one line
+to change.
+
+Two things to know. Stopping does not end the recording immediately: a frame is committed when its
+timestamp readback lands, a `mapAsync` a frame or two behind submit, so the handler drains the queue
+and waits for the frame count to settle before it writes the file — otherwise the last frames, the
+ones you were probably looking at, are the ones missing. And the browser asks before letting a page
+save more than one file, so a second capture may never appear; the filename goes to the console
+either way.
+
+Frames only accumulate while the page is rendering, so a recording taken while paused stays at zero.
+
 ## Scene
 
 `flying_world_-_battle_of_the_trash_god/v2`, six participating-media volumes, a low sun, and the
@@ -80,7 +180,10 @@ accepts version 2 only, deliberately and with no backward compatibility.
 ## Notes
 
 Two viewpoints from the sibling repo (`v_volumetrics_light_extinction_0` and `_1`) sit inside
-geometry here and were replaced with placements verified against this build. *Log camera* writes the
+geometry here and were replaced with placements verified against this build. Two more —
+*Beside the fog box* and *Beside the fog box, deeper* — were added for Q-04: they are the only
+placements in the scene where the sun's path through the medium is short enough for the 16-step
+march to miss it, which makes them the ones any change to that path has to be judged at. *Log camera* writes the
 current placement to the console in the form the `VIEWS` table takes, which is how to add more.
 
 Frame time settles around 28 ms at 1920×1080 on a 4070-class part. That is the whole frame, not the

package/src/shade/playground/volumetrics_froxel/index.html

@@ -117,12 +117,14 @@
         #status.fail { color: var(--fail); }
         #status.warn { color: var(--warn); }
 
-        #stats {
+        #stats, #profile_status {
             margin-top: 4px;
             font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
             color: var(--text);
         }
 
+        #profile_status.recording { color: var(--fail); }
+
         p.note { margin: 6px 0 0; font-size: 11.5px; color: var(--muted); }
     </style>
 </head>
@@ -220,6 +222,23 @@
 
     <hr>
 
+    <h2>Profiling</h2>
+
+    <div id="profile_status">idle</div>
+    <p class="note">
+        <strong>T</strong> starts a GPU profile recording; <strong>T</strong> again stops it and
+        downloads the <code>.sgpt</code> capture. Level is <code>WORKLOAD</code> — pass spans, the
+        frame graph, and dispatch/draw counts, which measures around 11 KB a frame on this page.
+        Frames only accumulate while the page is rendering, so a recording taken while paused stays
+        at zero.
+    </p>
+    <p class="note">
+        The browser asks before letting a page save more than one file. If a second capture never
+        appears, that prompt is why — allow it, and the filename is on the console either way.
+    </p>
+
+    <hr>
+
     <div class="row">
         <button id="pause">Pause</button>
         <button id="log_camera">Log camera</button>

package/src/shade/playground/volumetrics_froxel/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/volumetrics_froxel/main.js"],"names":[],"mappings":"AA+TA,uCA2SC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/volumetrics_froxel/main.js"],"names":[],"mappings":"AA8ZA,uCAsfC"}

package/src/shade/playground/volumetrics_froxel/main.js

@@ -1,7 +1,10 @@
+import package_json from "../../../../package.json";
 import Quaternion from "../../../core/geom/Quaternion.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
 import { MIE_PARTICLES_STANDARD_PRECOMPUTED } from "../../../core/math/physics/mie/MIE_PARTICLES_STANDARD_PRECOMPUTED.js";
+import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.js";
 import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
 import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
 import { create_frame_loop } from "../../renderer/create_frame_loop.js";
@@ -143,6 +146,32 @@ const VIEWS = [
         position: { x: -36.56903863396318, y: 19.1017887067011, z: 13.881382214134083 },
         rotation: { x: -0.0961072760435774, y: 0.9036695806244697, z: -0.3054532939528032, w: -0.28432897453277794 }
     },
+    {
+        id: 'fog_box_0',
+        label: 'Beside the fog box',
+        c: 'Q-04',
+        hint: 'the sun crosses three units of medium here — where sixteen march steps read +58',
+        position: { x: -49.64917207609583, y: 3.9195318273572317, z: -4.211048766762115 },
+        rotation: {
+            x: -0.037898077937503966,
+            y: 0.6176094542736352,
+            z: 0.029816629610983452,
+            w: 0.7850052651282708
+        }
+    },
+    {
+        id: 'fog_box_1',
+        label: 'Beside the fog box, deeper',
+        c: 'Q-04',
+        hint: 'the same medium a little further in; +70 for the march, and where the volume strobed',
+        position: { x: -50.28590468756837, y: 4.239170044321892, z: -3.9966900541348767 },
+        rotation: {
+            x: -0.03789807793750395,
+            y: 0.6176094542736352,
+            z: 0.02981662961098345,
+            w: 0.7850052651282708
+        }
+    },
     {
         id: 'inside_out',
         label: 'Under the island',
@@ -317,6 +346,72 @@ function aim_light(light, azimuth_degrees, elevation_degrees) {
     light.updateMatrices();
 }
 
+/**
+ * How much each profile capture records. `WORKLOAD` is the highest of the three levels the proposal
+ * calls shippable: pass spans, the frame graph, and dispatch/draw counts.
+ *
+ * Measured on this page it runs ~11 KB a frame over ~393 spans, so ~660 KB/s at 60 Hz — the
+ * proposal's estimate of 6 KB assumed ~200 passes and this graph is about twice that. Still small
+ * enough that a hand-driven recording will not notice. `VERBOSE` above it adds bind group contents
+ * at roughly seven times the rate and wants a frame limit set, not a key you can lean on.
+ *
+ * @type {number}
+ */
+const PROFILE_LEVEL = GPUProfileLevel.WORKLOAD;
+
+/**
+ * Hand an ArrayBuffer to the browser as a file.
+ *
+ * @param {ArrayBuffer} bytes
+ * @param {string} filename
+ */
+function download_bytes(bytes, filename) {
+    const url = URL.createObjectURL(new Blob([bytes], { type: 'application/octet-stream' }));
+
+    const anchor = document.createElement('a');
+
+    anchor.href = url;
+    anchor.download = filename;
+
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+
+    // Revoking in the same task cancels the download in some browsers — the click only schedules it.
+    setTimeout(() => URL.revokeObjectURL(url), 60000);
+}
+
+/**
+ * `YYYYMMDD-HHMMSS` in local time, matching the naming the other `.sgpt` captures on this machine
+ * already use — same sort order, and it reads as the clock you took it by rather than as UTC.
+ *
+ * @returns {string}
+ */
+function file_timestamp() {
+    const now = new Date();
+
+    const pad = value => String(value).padStart(2, '0');
+
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+        + `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function format_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    }
+
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+
 export async function start() {
 
     const element = id => document.getElementById(id);
@@ -407,8 +502,17 @@ export async function start() {
 
     const views_element = element('views');
 
+    /**
+     * Which placement the camera was last sent to, for the profile capture's note — a capture that
+     * cannot say where it was taken is much less use a week later.
+     * @type {object|null}
+     */
+    let current_view = null;
+
     /** @param {object} view */
     function go_to(view) {
+        current_view = view;
+
         camera.transform.fromJSON({ position: view.position, rotation: view.rotation });
 
         // the controller holds its own spherical state and would otherwise snap the camera back on
@@ -559,6 +663,200 @@ export async function start() {
         repaint();
     });
 
+    // -- profiling: T starts a recording, T again stops it and downloads the capture
+
+    const profile_status = element('profile_status');
+
+    /**
+     * The recording in progress, or null.
+     *
+     * The engine never constructs one of these — `Renderer.profile_session` is a nullable field and
+     * the null checks around it are the entire integration, which is what keeps the profiler out of
+     * a bundle that does not ask for it. The two imports at the top of this file are the whole
+     * opt-in.
+     *
+     * @type {GPUProfileSession|null}
+     */
+    let profile_session = null;
+
+    /** Guards against T being leaned on while a stop is still draining. */
+    let profile_busy = false;
+
+    function set_profile_status(text, recording = false) {
+        profile_status.textContent = text;
+        profile_status.className = recording ? 'recording' : '';
+    }
+
+    function start_profile() {
+        const device = renderer.device;
+
+        const settings = [
+            current_view === null ? 'free camera' : current_view.label,
+            `fov ${Math.round(camera.fov / DEG_TO_RAD)}°`,
+            `volumetric TAA ${(globalThis.__VOL_TAA_ENABLED ?? true) ? 'on' : 'off'}`,
+            `${renderer.pixel_ratio.toFixed(2)}x`,
+        ];
+
+        const session = new GPUProfileSession({
+            level: PROFILE_LEVEL,
+            note: `volumetrics_froxel — ${settings.join(' · ')}`,
+        });
+
+        // Populate before start(): the meta record is written into the stream there and not read
+        // again. Without it the capture is unreadable in the sense that matters — a pass taking
+        // 0.4 ms says nothing until you know which GPU and at what resolution.
+        const meta = session.meta;
+
+        // `GPUDevice.adapterInfo` is recent enough that a browser running this page may not have it,
+        // and several browsers withhold the fields even when they do. Empty is what the format
+        // expects in that case.
+        const info = device.adapterInfo;
+
+        if (info !== undefined && info !== null) {
+            meta.adapter_vendor = info.vendor ?? "";
+            meta.adapter_architecture = info.architecture ?? "";
+            meta.adapter_device = info.device ?? "";
+            meta.adapter_description = info.description ?? "";
+        }
+
+        meta.features = [...device.features];
+        meta.engine_version = package_json.version;
+
+        session.onBytesWritten.add(bytes => {
+            set_profile_status(
+                `● recording — ${session.frames_recorded} frames, ${format_bytes(bytes)}  ·  T to stop`,
+                true
+            );
+        });
+
+        renderer.profile_session = session;
+        session.start();
+
+        profile_session = session;
+
+        // The timers go quiet without this rather than failing, so the capture still carries the
+        // frame graph and the workload — it just has no durations in it. Worth knowing before you
+        // record for a minute and then look.
+        const timed = device.features.has('timestamp-query');
+
+        set_profile_status(
+            timed
+                ? '● recording — 0 frames  ·  T to stop'
+                : '● recording without timestamp-query — structure only, no durations  ·  T to stop',
+            true
+        );
+    }
+
+    /**
+     * Wait for frames already submitted to finish landing in the session.
+     *
+     * A frame is committed when its timestamp readback resolves — a `mapAsync` a frame or two behind
+     * submit, see `ShadeGPUCommandContext.profiling_absorbed` — and `record_frame` silently ignores
+     * anything arriving after `stop()`. Stopping the instant the key goes down therefore discards
+     * the last few frames, which are the ones you were most likely looking at.
+     *
+     * Drains the queue, then waits for the frame count to stop moving. Capped, because a recording
+     * taken while the page is paused never moves at all.
+     *
+     * @param {GPUProfileSession} session
+     */
+    async function drain_profile(session) {
+        const DEADLINE_MS = 1000;
+        const QUIET_MS = 60;
+
+        await renderer.device.queue.onSubmittedWorkDone();
+
+        const deadline = performance.now() + DEADLINE_MS;
+
+        let previous = session.frames_recorded;
+
+        while (performance.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, QUIET_MS));
+
+            if (session.frames_recorded === previous) {
+                return;
+            }
+
+            previous = session.frames_recorded;
+        }
+    }
+
+    async function stop_profile() {
+        const session = profile_session;
+
+        profile_session = null;
+
+        // Detach first, so nothing encoded during the drain below joins the recording. Frames
+        // already encoded are unaffected: Renderer captures the session into a local before it
+        // subscribes to the readback.
+        renderer.profile_session = null;
+
+        set_profile_status('stopping — draining in-flight frames…');
+
+        await drain_profile(session);
+
+        const bytes = session.stop();
+
+        const filename = `volumetrics_froxel-${file_timestamp()}.sgpt`;
+
+        download_bytes(bytes, filename);
+
+        // Also to the console, because the status line is the only other place the name appears and
+        // a browser that declines the save says nothing about which capture it declined.
+        console.log(
+            `profile: ${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, `
+            + `${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'} -> ${filename}`
+        );
+
+        set_profile_status(
+            `${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}`
+            + `, ${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'}`
+            + `  ·  ${filename}`
+        );
+    }
+
+    window.addEventListener('keydown', event => {
+        if (event.ctrlKey || event.metaKey || event.altKey || event.repeat) {
+            return;
+        }
+
+        // `key` first, because it is the letter actually printed on the key the user pressed —
+        // `code` is physical position, so on AZERTY it names the key where T sits on QWERTY. `code`
+        // is the fallback for layouts whose `key` is not Latin at all (Cyrillic gives "е" here).
+        if (event.key.toLowerCase() !== 't' && event.code !== 'KeyT') {
+            return;
+        }
+
+        // the panel's sliders and buttons are focusable; do not steal a key from a field
+        const target = event.target;
+
+        if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) {
+            return;
+        }
+
+        if (profile_busy) {
+            return;
+        }
+
+        event.preventDefault();
+
+        profile_busy = true;
+
+        const done = profile_session === null
+            ? Promise.resolve(start_profile())
+            : stop_profile();
+
+        done.catch(error => {
+            set_profile_status(`profiling failed: ${error?.message ?? error}`);
+            console.error(error);
+
+            profile_session = null;
+            renderer.profile_session = null;
+        }).finally(() => {
+            profile_busy = false;
+        });
+    });
+
     element('pause').addEventListener('click', () => {
         paused = !paused;
         element('pause').textContent = paused ? 'Resume' : 'Pause';