@woosh/meep-engine 3.18.0 → 3.20.0

package/src/shade/playground/particle_ecs/moonlit_environment.js

@@ -0,0 +1,144 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { sampler2d_to_f16 } from "../../../engine/graphics/texture/sampler/sampler2d_to_f16.js";
+import { octahedral_uv_to_direction } from "../../renderer/light/environment/octahedral_uv_to_direction.js";
+import { ColorSpace } from "../../renderer/texture/ColorSpace.js";
+import { ShadeImage } from "../../renderer/texture/source/ShadeImage.js";
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+
+/**
+ * A moonlit night sky, generated: what the bonfire is lit by when it is not lighting itself.
+ *
+ * Built rather than loaded for the same reason the sprites are — `test_assets/` is gitignored, so a
+ * fresh checkout has no environment map, and a page that needs one to look right would look wrong
+ * for everybody who has not fetched the asset repository. This is small, it is in linear radiance,
+ * and it is the same octahedral projection `scene.lights.environment` samples.
+ *
+ * **The sky is the reason the fire reads as a fire.** Shade assumes global illumination, so a scene
+ * with no environment renders unlit; give it a bright day and the flame washes out to a pale smear,
+ * because the fire's own light is then a small fraction of what is already there. A night sky about
+ * three orders of magnitude below daylight is what leaves the fire room to be the brightest thing
+ * in the frame, and what makes the smoke read as blue where the firelight has stopped reaching it.
+ */
+
+/**
+ * Resolution per octahedral face grid.
+ *
+ * Small on purpose: this is an ambient source, convolved into irradiance and a handful of roughness
+ * mips before anything samples it. What it has to be is smooth and correctly oriented.
+ *
+ * @type {number}
+ */
+const RESOLUTION = 128;
+
+/**
+ * Where the moon is. Unit, +Y up — the direction light arrives *from*, so the shadows fall the
+ * other way.
+ *
+ * @type {Vector3}
+ */
+export const MOON_DIRECTION = new Vector3(-0.42, 0.62, -0.66).normalize();
+
+/**
+ * Angular radius of the moon's disc, in radians. Far larger than the real one (about 0.0045): the
+ * map is 128 texels across a hemisphere, so a true disc would be a fraction of a texel and would
+ * disappear into the first mip. This is a moon to look at, not an ephemeris.
+ *
+ * @type {number}
+ */
+const MOON_RADIUS = 0.075;
+
+/**
+ * @type {Vector3}
+ */
+const SCRATCH_DIRECTION = new Vector3();
+
+/**
+ * Radiance arriving from a direction, in linear space.
+ *
+ * @param {number[]} out rgb
+ * @param {number} x
+ * @param {number} y +Y is up
+ * @param {number} z
+ */
+function moonlit_radiance(out, x, y, z) {
+    // How close this direction is to the moon, as the cosine of the angle between them.
+    const alignment = x * MOON_DIRECTION.x + y * MOON_DIRECTION.y + z * MOON_DIRECTION.z;
+    const angle = Math.acos(Math.min(1, Math.max(-1, alignment)));
+
+    if (y >= 0) {
+        // Night sky: deepest at the zenith, lifting toward the horizon where the atmosphere is
+        // thicker and there is more of it to scatter what little light there is.
+        const horizon = Math.pow(1 - y, 4);
+
+        out[0] = 0.0035 + horizon * 0.011;
+        out[1] = 0.0052 + horizon * 0.014;
+        out[2] = 0.0115 + horizon * 0.020;
+    } else {
+        // Below the horizon: ground bounce, dimmer and less blue than the sky. This is what lights
+        // the underside of the smoke, so it is not zero however dark the night is.
+        const t = Math.pow(1 + y, 2);
+
+        out[0] = 0.0016 + t * 0.0042;
+        out[1] = 0.0017 + t * 0.0044;
+        out[2] = 0.0022 + t * 0.0055;
+    }
+
+    // A broad halo, then the disc itself. The halo is what makes the sky around the moon read as
+    // sky with a moon in it rather than as a sticker on a gradient.
+    const halo = Math.exp(-angle * 5.5) * 0.05;
+
+    out[0] += halo * 0.75;
+    out[1] += halo * 0.82;
+    out[2] += halo;
+
+    if (angle < MOON_RADIUS) {
+        // Soft-edged, so the disc survives the convolution into the roughness mips with a shape
+        // rather than as ringing.
+        const disc = 1 - Math.pow(angle / MOON_RADIUS, 3);
+
+        out[0] += disc * 5.2;
+        out[1] += disc * 5.6;
+        out[2] += disc * 6.4;
+    }
+}
+
+/**
+ * The environment map. Assign it to `scene.lights.environment`.
+ *
+ * @returns {ShadeTexture}
+ */
+export function moonlit_environment() {
+    const sampler = Sampler2D.float32(4, RESOLUTION, RESOLUTION);
+
+    const data = sampler.data;
+    const rgb = [0, 0, 0];
+
+    for (let v = 0; v < RESOLUTION; v++) {
+        for (let u = 0; u < RESOLUTION; u++) {
+            // texel centres, so the mapping is symmetric across the octahedron's folds
+            octahedral_uv_to_direction(
+                SCRATCH_DIRECTION,
+                (u + 0.5) / RESOLUTION,
+                (v + 0.5) / RESOLUTION
+            );
+
+            moonlit_radiance(rgb, SCRATCH_DIRECTION.x, SCRATCH_DIRECTION.y, SCRATCH_DIRECTION.z);
+
+            const offset = (v * RESOLUTION + u) * 4;
+
+            data[offset] = rgb[0];
+            data[offset + 1] = rgb[1];
+            data[offset + 2] = rgb[2];
+            data[offset + 3] = 1;
+        }
+    }
+
+    const image = ShadeImage.fromSampler2D(sampler2d_to_f16(sampler));
+
+    // radiance, not colour: the values above are light arriving, and treating them as sRGB would
+    // put a transfer curve through numbers that never had one
+    image.color_space = ColorSpace.LinearSRGB;
+
+    return ShadeTexture.from(image);
+}

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

@@ -78,10 +78,11 @@ edits it at both altitudes.
 - Two of them are **ramps**, edited as a picture. An **RGBA Gradient** (and an RGB one) is a strip of
   the colour it produces with its stops underneath: drag a stop, click the lane to add one — in the
   colour the gradient already is there, so adding never changes anything — and middle-click to remove.
-  A **Curve** is the unit square with its keys in it, and the picker under it decides the selected
-  key's tangents. Neither is sampled from a table at runtime: both are written out into the program as
-  arithmetic, which is what the **Code** tab shows. `Curve Table`, which *is* the table, is the other
-  node — it takes a row handle rather than a curve.
+  A **Curve** plots normalized time against unrestricted values, with a Y axis that fits the whole
+  curve, including peaks between keys. Its fields edit the selected key's time, value and tangents.
+  The scale stays fixed during a drag and refits on release. Neither ramp is sampled from a table
+  at runtime: both are written out into the program as arithmetic, which is what the **Code** tab
+  shows.
 - The strip along the bottom lists every problem with the effect, from **both** phases, loudest
   first. Click one to jump to the phase it is in and select the node; the node is outlined in the
   graph too.

package/src/shade/playground/particle_system/particle_prototype.d.ts

@@ -1,31 +1,29 @@
 /**
  * Worked examples of authoring particle effects with the node graph + placing them in a scene for a
  * {@link GPUParticleSystem} to run. Demonstrates: distinct per-particle lifecycle (no built-in age — the
- * effect declares it), AnimationCurve sampling over life, flipbook frames, random emission,
+ * effect declares it), authored curves over life, flipbook frames, random emission,
  * additive vs alpha blending, projection modes, soft depth and lighting toggles.
  *
  * These are examples, not engine code, which is why they sit here rather than under
  * `renderer/particles/`: the only thing that opens them is this playground's page, and keeping them
  * on this side of the line means the dependency runs playground -> renderer and never back.
  *
- * `curves` is a `GPUAnimationManager` (or anything with `register_curve(AnimationCurve) -> handle`);
- * `size_curve` / `alpha_curve` are meep `AnimationCurve`s. Both are optional — passing `undefined`
- * yields effects that use constant size/alpha instead (curve handle 0, evaluated as 0 by the
- * disabled provider), which is handy for the headless tests.
+ * `size_curve` / `alpha_curve` are authored curve parameters compiled into arithmetic. Both are
+ * optional; omitted curves leave the initial size/colour unchanged.
  */
 /**
  * A fire effect: buoyant, turbulent, additive-blended camera-facing sprites whose size and opacity
  * follow curves over their lifetime and whose flipbook advances with age.
  *
  * @param {object} [options]
- * @param {number} [options.size_curve] curve handle for size(normalizedAge)
- * @param {number} [options.alpha_curve] curve handle for alpha(normalizedAge)
+ * @param {import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter} [options.size_curve] size(normalizedAge)
+ * @param {import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter} [options.alpha_curve] alpha(normalizedAge)
  * @param {number} [options.flipbook_frames]
  * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
  */
 export function fire_effect({ size_curve, alpha_curve, flipbook_frames }?: {
-    size_curve?: number;
-    alpha_curve?: number;
+    size_curve?: import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter;
+    alpha_curve?: import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter;
     flipbook_frames?: number;
 }): {
     layout: ParticleLayout;

package/src/shade/playground/particle_system/particle_prototype.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_prototype.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_prototype.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH;IAL4B,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,eAAe,GAAhC,MAAM;;YACK,cAAc;YAAU,MAAM;aAAW,MAAM;EA+GpE;AAED;;;;GAIG;AACH;YAFsB,cAAc;YAAU,MAAM;aAAW,MAAM;EAYpE;AAED;;;;;;;;;;;;;GAaG;AACH,yCANW,OAAO,+BAA+B,EAAE,KAAK;IAEa,IAAI,GAA9D,OAAO,gCAAgC,EAAE,MAAM;;UAEtC,eAAe;WAAS,eAAe;EAe1D;+BAzL8B,mDAAmD;gCAElD,qDAAqD"}
+{"version":3,"file":"particle_prototype.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_prototype.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;GASG;AACH;IALsG,UAAU,GAArG,OAAO,iDAAiD,EAAE,sBAAsB;IACW,WAAW,GAAtG,OAAO,iDAAiD,EAAE,sBAAsB;IAC/D,eAAe,GAAhC,MAAM;;YACK,cAAc;YAAU,MAAM;aAAW,MAAM;EA+GpE;AAED;;;;GAIG;AACH;YAFsB,cAAc;YAAU,MAAM;aAAW,MAAM;EAYpE;AAED;;;;;;;;;;;;;GAaG;AACH,yCANW,OAAO,+BAA+B,EAAE,KAAK;IAEa,IAAI,GAA9D,OAAO,gCAAgC,EAAE,MAAM;;UAEtC,eAAe;WAAS,eAAe;EAe1D;+BAvL8B,mDAAmD;gCAElD,qDAAqD"}

package/src/shade/playground/particle_system/particle_prototype.js

@@ -13,17 +13,15 @@ import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitte
 /**
  * Worked examples of authoring particle effects with the node graph + placing them in a scene for a
  * {@link GPUParticleSystem} to run. Demonstrates: distinct per-particle lifecycle (no built-in age — the
- * effect declares it), AnimationCurve sampling over life, flipbook frames, random emission,
+ * effect declares it), authored curves over life, flipbook frames, random emission,
  * additive vs alpha blending, projection modes, soft depth and lighting toggles.
  *
  * These are examples, not engine code, which is why they sit here rather than under
  * `renderer/particles/`: the only thing that opens them is this playground's page, and keeping them
  * on this side of the line means the dependency runs playground -> renderer and never back.
  *
- * `curves` is a `GPUAnimationManager` (or anything with `register_curve(AnimationCurve) -> handle`);
- * `size_curve` / `alpha_curve` are meep `AnimationCurve`s. Both are optional — passing `undefined`
- * yields effects that use constant size/alpha instead (curve handle 0, evaluated as 0 by the
- * disabled provider), which is handy for the headless tests.
+ * `size_curve` / `alpha_curve` are authored curve parameters compiled into arithmetic. Both are
+ * optional; omitted curves leave the initial size/colour unchanged.
  */
 
 /**
@@ -31,8 +29,8 @@ import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitte
  * follow curves over their lifetime and whose flipbook advances with age.
  *
  * @param {object} [options]
- * @param {number} [options.size_curve] curve handle for size(normalizedAge)
- * @param {number} [options.alpha_curve] curve handle for alpha(normalizedAge)
+ * @param {import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter} [options.size_curve] size(normalizedAge)
+ * @param {import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter} [options.alpha_curve] alpha(normalizedAge)
  * @param {number} [options.flipbook_frames]
  * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
  */
@@ -111,12 +109,12 @@ export function fire_effect({ size_curve, alpha_curve, flipbook_frames = 16 } =
 
         // size + alpha from curves over life (or constants if no curve provided)
         if (size_curve !== undefined) {
-            const sc = particle_node(update, "curve", { handle: size_curve }); particle_wire(update, sc, "t", nAge);
+            const sc = particle_node(update, "curveLiteral", { curve: size_curve }); particle_wire(update, sc, "t", nAge);
             particle_wire(update, particle_node(update, "setAttribute", { name: "size" }), "value", sc);
         }
         const color = particle_node(update, "attribute", { name: "color" });
         if (alpha_curve !== undefined) {
-            const ac = particle_node(update, "curve", { handle: alpha_curve }); particle_wire(update, ac, "t", nAge);
+            const ac = particle_node(update, "curveLiteral", { curve: alpha_curve }); particle_wire(update, ac, "t", nAge);
             // color.rgb unchanged, color.a = ac : rebuild via select on a swizzle mask is overkill;
             // simplest: multiply color by (1,1,1,ac_normalized) — approximate by scaling alpha only.
             const alphaVec = particle_node(update, "mul");

package/src/shade/playground/profile_hotkey.d.ts

@@ -0,0 +1,58 @@
+/**
+ * One key that records a GPU profile capture and downloads it.
+ *
+ * `T` starts a recording, `T` again stops it and saves an `.sgpt` next to the browser's other
+ * downloads. That is the whole interaction, and it is what every playground page wants: a capture is
+ * something you take *while looking at* the thing you are suspicious of, so reaching for a panel is
+ * already too slow.
+ *
+ * **The engine never constructs a `GPUProfileSession`.** `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. Importing this module is the opt-in.
+ *
+ * `volumetrics_froxel/main.js` has its own copy of this, written first; it is the page this was
+ * lifted from and it can adopt this when somebody has the assets to verify it against.
+ */
+/**
+ * @typedef {object} ProfileHotkeyHandle
+ * @property {function(): boolean} is_recording
+ * @property {function(): Promise<void>} toggle start a recording, or stop and save the one running
+ * @property {function(): void} dispose remove the key listener
+ */
+/**
+ * Wire the key up.
+ *
+ * @param {object} params
+ * @param {import("../renderer/Renderer.js").Renderer} params.renderer initialized — this reads its
+ *        device for the capture's metadata
+ * @param {string} params.name goes in the filename and in the capture's note
+ * @param {HTMLElement|null} [params.status] written with what the recording is doing; the element
+ *        gets the class `recording` while one is running, and nothing otherwise
+ * @param {function(): string[]} [params.settings] what the page was set to when the capture was
+ *        taken. A pass timing says nothing until you know that
+ * @param {number} [params.level] see {@link GPUProfileLevel}; `WORKLOAD` is the most detailed
+ * @param {string} [params.key] the letter to bind, lowercase
+ * @param {EventTarget} [params.target] where the listener goes
+ * @returns {ProfileHotkeyHandle}
+ */
+export function install_profile_hotkey({ renderer, name, status, settings, level, key, target, }: {
+    renderer: import("../renderer/Renderer.js").Renderer;
+    name: string;
+    status?: HTMLElement | null;
+    settings?: () => string[];
+    level?: number;
+    key?: string;
+    target?: EventTarget;
+}): ProfileHotkeyHandle;
+export type ProfileHotkeyHandle = {
+    is_recording: () => boolean;
+    /**
+     * start a recording, or stop and save the one running
+     */
+    toggle: () => Promise<void>;
+    /**
+     * remove the key listener
+     */
+    dispose: () => void;
+};
+//# sourceMappingURL=profile_hotkey.d.ts.map

package/src/shade/playground/profile_hotkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile_hotkey.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/profile_hotkey.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IAZ8D,QAAQ,EAA3D,OAAO,yBAAyB,EAAE,QAAQ;IAE3B,IAAI,EAAnB,MAAM;IACoB,MAAM,GAAhC,WAAW,GAAC,IAAI;IAEc,QAAQ,SAA1B,MAAM,EAAE;IAEJ,KAAK,GAArB,MAAM;IACU,GAAG,GAAnB,MAAM;IACe,MAAM,GAA3B,WAAW;IACT,mBAAmB,CAwO/B;;wBA3PyB,OAAO;;;;kBACP,QAAQ,IAAI,CAAC;;;;mBACb,IAAI"}

package/src/shade/playground/profile_hotkey.js

@@ -0,0 +1,325 @@
+import package_json from "../../../package.json";
+import { GPUProfileLevel } from "../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../device/timing/profile/GPUProfileSession.js";
+
+/**
+ * One key that records a GPU profile capture and downloads it.
+ *
+ * `T` starts a recording, `T` again stops it and saves an `.sgpt` next to the browser's other
+ * downloads. That is the whole interaction, and it is what every playground page wants: a capture is
+ * something you take *while looking at* the thing you are suspicious of, so reaching for a panel is
+ * already too slow.
+ *
+ * **The engine never constructs a `GPUProfileSession`.** `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. Importing this module is the opt-in.
+ *
+ * `volumetrics_froxel/main.js` has its own copy of this, written first; it is the page this was
+ * lifted from and it can adopt this when somebody has the assets to verify it against.
+ */
+
+/**
+ * @typedef {object} ProfileHotkeyHandle
+ * @property {function(): boolean} is_recording
+ * @property {function(): Promise<void>} toggle start a recording, or stop and save the one running
+ * @property {function(): void} dispose remove the key listener
+ */
+
+/**
+ * Wire the key up.
+ *
+ * @param {object} params
+ * @param {import("../renderer/Renderer.js").Renderer} params.renderer initialized — this reads its
+ *        device for the capture's metadata
+ * @param {string} params.name goes in the filename and in the capture's note
+ * @param {HTMLElement|null} [params.status] written with what the recording is doing; the element
+ *        gets the class `recording` while one is running, and nothing otherwise
+ * @param {function(): string[]} [params.settings] what the page was set to when the capture was
+ *        taken. A pass timing says nothing until you know that
+ * @param {number} [params.level] see {@link GPUProfileLevel}; `WORKLOAD` is the most detailed
+ * @param {string} [params.key] the letter to bind, lowercase
+ * @param {EventTarget} [params.target] where the listener goes
+ * @returns {ProfileHotkeyHandle}
+ */
+export function install_profile_hotkey({
+    renderer,
+    name,
+    status = null,
+    settings = () => [],
+    level = GPUProfileLevel.WORKLOAD,
+    key = "t",
+    target = window,
+}) {
+    /**
+     * The recording in progress, or null.
+     * @type {GPUProfileSession|null}
+     */
+    let session = null;
+
+    /** Guards against the key being leaned on while a stop is still draining. */
+    let busy = false;
+
+    /**
+     * @param {string} text
+     * @param {boolean} [recording]
+     */
+    function set_status(text, recording = false) {
+        if (status === null) {
+            return;
+        }
+
+        status.textContent = text;
+        status.className = recording ? "recording" : "";
+    }
+
+    function start() {
+        const device = renderer.device;
+
+        const recording = new GPUProfileSession({
+            level,
+            note: `${name} — ${[...settings(), `${renderer.pixel_ratio.toFixed(2)}x`].join(" · ")}`,
+        });
+
+        /*
+         Populated 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 = recording.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;
+
+        recording.onBytesWritten.add(bytes => {
+            /*
+             Only while this is still the live recording. Frames keep landing all through the drain
+             in `stop`, which is the whole point of draining — and without this check each one would
+             overwrite "stopping…" with "● recording · T to stop", so a capture that is on its way to
+             disk reads as one that is still running.
+            */
+            if (session !== recording) {
+                return;
+            }
+
+            set_status(
+                `● recording — ${recording.frames_recorded} frames, ${format_bytes(bytes)}`
+                + `  ·  ${key.toUpperCase()} to stop`,
+                true
+            );
+        });
+
+        renderer.profile_session = recording;
+        recording.start();
+
+        session = recording;
+
+        // 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_status(
+            timed
+                ? `● recording — 0 frames  ·  ${key.toUpperCase()} to stop`
+                : "● recording without timestamp-query — structure only, no durations"
+                + `  ·  ${key.toUpperCase()} 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} recording
+     * @returns {Promise<void>}
+     */
+    async function drain(recording) {
+        const DEADLINE_MS = 1000;
+        const QUIET_MS = 60;
+
+        await renderer.device.queue.onSubmittedWorkDone();
+
+        const deadline = performance.now() + DEADLINE_MS;
+
+        let previous = recording.frames_recorded;
+
+        while (performance.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, QUIET_MS));
+
+            if (recording.frames_recorded === previous) {
+                return;
+            }
+
+            previous = recording.frames_recorded;
+        }
+    }
+
+    async function stop() {
+        const recording = session;
+
+        session = null;
+
+        // Detached 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_status("stopping — draining in-flight frames…");
+
+        await drain(recording);
+
+        const bytes = recording.stop();
+        const filename = `${name}-${file_timestamp()}.sgpt`;
+
+        download_bytes(bytes, filename);
+
+        const topologies = `${recording.topology_count} topolog${recording.topology_count === 1 ? "y" : "ies"}`;
+
+        // 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: ${recording.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, `
+            + `${topologies} -> ${filename}`
+        );
+
+        set_status(
+            `${recording.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, ${topologies}`
+            + `  ·  ${filename}`
+        );
+    }
+
+    /**
+     * @returns {Promise<void>}
+     */
+    function toggle() {
+        if (busy) {
+            return Promise.resolve();
+        }
+
+        busy = true;
+
+        const done = session === null ? Promise.resolve(start()) : stop();
+
+        return done.catch(error => {
+            set_status(`profiling failed: ${error?.message ?? error}`);
+            console.error(error);
+
+            session = null;
+            renderer.profile_session = null;
+        }).finally(() => {
+            busy = false;
+        });
+    }
+
+    /**
+     * @param {KeyboardEvent} event
+     */
+    function on_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() !== key && event.code !== `Key${key.toUpperCase()}`) {
+            return;
+        }
+
+        // a panel's fields and buttons are focusable; do not steal a key from one
+        const focused = event.target;
+
+        if (
+            focused instanceof HTMLInputElement
+            || focused instanceof HTMLTextAreaElement
+            || focused instanceof HTMLSelectElement
+        ) {
+            return;
+        }
+
+        event.preventDefault();
+
+        toggle();
+    }
+
+    target.addEventListener("keydown", on_keydown);
+
+    return {
+        is_recording: () => session !== null,
+        toggle,
+        dispose: () => target.removeEventListener("keydown", on_keydown),
+    };
+}
+
+/**
+ * @param {Uint8Array} 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 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`;
+}

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

@@ -0,0 +1,22 @@
+# SSR cross camera playground
+
+Open `/src/shade/playground/ssr_motion/` on the engine's Vite development server.
+It shares the exact scene, camera lens, resolution and fixed exposure of
+`ssr_variance`: one metallic floor and an emissive cross card with two colored
+markers. Final-image TAA and raster jitter default off independently.
+
+Drag to orbit, right-drag to pan, wheel to zoom, or focus the canvas and use WASD.
+Floor roughness changes live from 0.01 to 1.00. Material changes clear history;
+ordinary camera movement does not. The lateral path uses the same motion-speed
+scale as `ssr_reprojection` (x = 2 sin(phase), phase rate = 0.7 × speed).
+Choose speed 2.0 to reproduce the faster lateral movement.
+
+Pause motion continues sampling at the current pose. Pause rendering freezes the
+image. Step frame submits one 1/60-second frame. SSR parallax, surface-only and
+no-history modes, spatial denoising, final TAA and jitter can be compared separately.
+
+Query controls: `?motion=lateral&speed=2&roughness=0.3`, `taa=on`, `jitter=on`,
+`spatial=off`, and `temporal=0|1|2`. `manual` starts at frame zero with rendering
+paused. `await ssr_motion_ready` exposes the renderer, camera, scene, `pose`,
+`frame`, and `step(n, advance=true)` for controlled experiments. `advance=false`
+keeps the current pose while sampling. Exact stepping requires rendering paused.