@woosh/meep-engine 3.14.1 → 3.14.3

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

@@ -0,0 +1,211 @@
+import { jpeg_decode } from "../../../format/image/jpeg/jpeg_decode.js";
+
+/**
+ * Measures the trade `ImageRGBADataLoader`'s codec chain makes for a JPEG.
+ *
+ * Three ways to turn the same bytes into samples:
+ *
+ * 1. **native** — the browser's decoder, as `NativeImageDecoder` uses it: decode, draw to a canvas,
+ *    `getImageData`. The browser decodes on its own thread; the read-back is main-thread work.
+ * 2. **js-main** — the in-tree decoder on the main thread. Never the plan; it is the floor the worker
+ *    number is measured against.
+ * 3. **js-worker** — the in-tree decoder in a module worker, bytes transferred both ways. This is what
+ *    `ImageDecoderWorker` would do if `ThreadedImageDecoder` claimed JPEGs.
+ *
+ * Two numbers per path, because they answer different questions: **wall** is the latency a load
+ * waits for, **main** is the main thread's share of it — the part that stalls a frame. A worker path
+ * that loses on wall and wins on main is a trade, not a result, and which way it goes is what decides
+ * the chain's default order.
+ *
+ * Runs under the dev server (`npm run dev`), which serves `test_assets/`. Results land in the table
+ * and in `window.__bench_results` for a script to read.
+ */
+
+const TEXTURES = [
+    "test_assets/Sponza/glTF/8747919177698443163.jpg",
+    "test_assets/Sponza/glTF/6047387724914829168.jpg",
+    "test_assets/Sponza/glTF/2051777328469649772.jpg",
+];
+
+const RUNS = 5;
+
+const status = document.getElementById("status");
+const table = document.getElementById("results");
+
+/**
+ * @param {number[]} values
+ * @returns {number} the median, which a single GC pause cannot move
+ */
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[sorted.length >> 1];
+}
+
+/**
+ * @param {ArrayBuffer} bytes
+ * @returns {Promise<{wall: number, main: number, width: number, height: number}>}
+ */
+async function native(bytes) {
+    const started = performance.now();
+
+    /*
+     `createImageBitmap` rather than `new Image()` + `decode()`: the same browser decoder behind both,
+     and the former is what `ImageBitmapAssetLoader` uses. `Image.decode()` on a blob URL never
+     resolves in the embedded browser this page is measured in, which is a fact about that browser and
+     not about the decoder — the read-back below is the part `NativeImageDecoder` pays on the main
+     thread either way.
+    */
+    const image = await createImageBitmap(new Blob([bytes], { type: "image/jpeg" }));
+
+    const main_started = performance.now();
+    const canvas = document.createElement("canvas");
+    canvas.width = image.width;
+    canvas.height = image.height;
+    const context = canvas.getContext("2d", { willReadFrequently: true });
+    context.drawImage(image, 0, 0);
+    const pixels = context.getImageData(0, 0, image.width, image.height);
+    const main = performance.now() - main_started;
+
+    image.close();
+
+    return { wall: performance.now() - started, main, width: pixels.width, height: pixels.height };
+}
+
+/**
+ * @param {ArrayBuffer} bytes
+ * @returns {Promise<{wall: number, main: number, width: number, height: number}>}
+ */
+async function js_main(bytes) {
+    const started = performance.now();
+    const image = jpeg_decode(bytes.slice(0));
+    const wall = performance.now() - started;
+
+    return { wall, main: wall, width: image.width, height: image.height };
+}
+
+const worker = new Worker(new URL("./decode_worker.js", import.meta.url), { type: "module" });
+let next_id = 0;
+
+/**
+ * @param {ArrayBuffer} bytes
+ * @returns {Promise<{wall: number, main: number, width: number, height: number, decode: number}>}
+ */
+function js_worker(bytes) {
+    return new Promise((resolve) => {
+        const id = next_id++;
+        const started = performance.now();
+
+        // the copy stands in for what a real caller would transfer rather than keep
+        const copy = bytes.slice(0);
+
+        const on_message = (event) => {
+            if (event.data.id !== id) {
+                return;
+            }
+
+            worker.removeEventListener("message", on_message);
+
+            const receive_started = performance.now();
+            // what the loader does with the answer: wrap the transferred buffer
+            const samples = new Uint8Array(event.data.data);
+            const main_receive = performance.now() - receive_started;
+
+            resolve({
+                wall: performance.now() - started,
+                main: main_post + main_receive,
+                decode: event.data.decode_ms,
+                width: event.data.width,
+                height: event.data.height,
+                samples: samples.length
+            });
+        };
+
+        worker.addEventListener("message", on_message);
+
+        const post_started = performance.now();
+        worker.postMessage({ id, buffer: copy }, [copy]);
+        const main_post = performance.now() - post_started;
+    });
+}
+
+const PATHS = { native, "js-main": js_main, "js-worker": js_worker };
+
+/**
+ * @param {string} path
+ * @param {ArrayBuffer} bytes
+ * @returns {Promise<Object<string, {wall: number, main: number, decode?: number}>>}
+ */
+async function measure(path, bytes) {
+    const result = {};
+
+    for (const [name, run] of Object.entries(PATHS)) {
+        await run(bytes); // warm-up: JIT, decoder tables, the worker's module graph
+
+        const walls = [];
+        const mains = [];
+        const decodes = [];
+
+        for (let i = 0; i < RUNS; i++) {
+            const r = await run(bytes);
+            walls.push(r.wall);
+            mains.push(r.main);
+            if (r.decode !== undefined) decodes.push(r.decode);
+        }
+
+        result[name] = {
+            wall: median(walls),
+            main: median(mains),
+            decode: decodes.length ? median(decodes) : undefined
+        };
+    }
+
+    return result;
+}
+
+function render(rows) {
+    const header = `<tr><th>texture</th><th>size</th><th>native wall</th><th>native main</th>`
+        + `<th>js-main wall</th><th>js-worker wall</th><th>js-worker main</th><th>worker decode</th></tr>`;
+
+    const body = rows.map(row => {
+        const r = row.results;
+        const ms = v => v === undefined ? "—" : `${v.toFixed(1)} ms`;
+        return `<tr><td>${row.name}</td><td>${row.width}×${row.height}, ${(row.bytes / 1024).toFixed(0)} KB</td>`
+            + `<td>${ms(r.native.wall)}</td><td>${ms(r.native.main)}</td>`
+            + `<td>${ms(r["js-main"].wall)}</td>`
+            + `<td>${ms(r["js-worker"].wall)}</td><td>${ms(r["js-worker"].main)}</td><td>${ms(r["js-worker"].decode)}</td></tr>`;
+    }).join("");
+
+    table.innerHTML = header + body;
+}
+
+async function main() {
+    const rows = [];
+
+    for (const path of TEXTURES) {
+        status.textContent = `measuring ${path}…`;
+
+        const response = await fetch(`/${path}`);
+        const bytes = await response.arrayBuffer();
+        const probe = jpeg_decode(bytes.slice(0));
+
+        const results = await measure(path, bytes);
+
+        rows.push({
+            name: path.split("/").pop(),
+            bytes: bytes.byteLength,
+            width: probe.width,
+            height: probe.height,
+            results
+        });
+
+        render(rows);
+    }
+
+    window.__bench_results = rows;
+    status.textContent = `done — ${RUNS} runs per path, medians`;
+}
+
+main().catch(e => {
+    status.textContent = `failed: ${e.message}`;
+    throw e;
+});

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

@@ -44,7 +44,7 @@ It drives frames by hand and compares two **independent** GPU computations of on
 
 - `shader_meshlet_bounds_reduce` merges every deformed vertex into the clone's geometry-metadata
   bounding box. It exists for the rasterizer's culling and knows nothing about trees.
-- `record_blas_refit` takes each leaf triangle's box and climbs the tree, so the root node ends up
+- `GPUBLASRefitBatch` takes each leaf triangle's box and climbs the tree, so the root node ends up
   bounding every triangle.
 
 Same vertices, same frame, no shared code. `min` and `max` are exact in floating point, so the two

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

@@ -79,12 +79,14 @@
         #status.fail { color: var(--fail); }
         #status.warn { color: var(--warn); }
 
-        #stats {
+        #stats, #profile_status {
             margin-top: 6px;
             font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
             color: var(--text);
         }
 
+        #profile_status.recording { color: var(--fail); }
+
         p.note { margin: 8px 0 0; font-size: 11.5px; color: var(--muted); }
     </style>
 </head>
@@ -134,6 +136,18 @@
 
     <hr>
 
+    <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 counts — so the refit is one <code>BLAS/RefitBatch</code> span
+        whatever the dancer count, next to the skinning and the bounds chain. Frames only accumulate
+        while the page is rendering. The browser asks before letting a page save more than one file;
+        if a second capture never appears, that prompt is why, and the filename is on the console.
+    </p>
+
+    <hr>
+
     <div id="status"></div>
     <div id="stats"></div>
 

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

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/main.js"],"names":[],"mappings":"AAyMA;;;;;GAKG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAwSzB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/main.js"],"names":[],"mappings":"AA4QA;;;;;GAKG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAqjBzB"}

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

@@ -1,5 +1,8 @@
+import package_json from "../../../../package.json";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.js";
 import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.js";
 import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
 import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
@@ -50,6 +53,70 @@ const CHARACTER_URL = '/test_assets/Michelle.glb';
  */
 const SPACING = 1.1;
 
+/**
+ * How much each profile capture records. `WORKLOAD` is pass spans, the frame graph, and dispatch
+ * and draw counts — the level at which the refit reads as one pass whatever the dancer count, with
+ * its span next to the skinning and the bounds chain. Light enough that a hand-driven recording
+ * will not notice. `VERBOSE` above it adds bind group contents at several 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`;
+}
+
 /**
  * A frame-time readout, kept as a rolling mean so the number is readable rather than jittering.
  */
@@ -263,11 +330,11 @@ export async function start() {
     // root box against the bounds-refresh chain's box over the same deformed vertices. Useful when
     // the page cannot be looked at — a browser stops calling `requestAnimationFrame` for a page it
     // is not compositing, so a hidden tab renders no frames to look at in the first place.
-    globalThis.verify = async () => {
+    globalThis.verify = async () => paused(async () => {
         const { verify_skinned_blas_refit } = await import('./verify_skinned_blas_refit.js');
 
         return verify_skinned_blas_refit({ renderer, camera, scene, mesh: globalThis.dancers[0] });
-    };
+    });
 
     // The half `verify()` is blind to: whether each leaf's box belongs to the triangle that leaf
     // names. Run against the character's *source* geometry — skinning deforms the clone's vertex
@@ -279,6 +346,15 @@ export async function start() {
         return verify_leaf_correspondence({ renderer, geometry: globalThis.dancers[0].geometry });
     };
 
+    // The same question of the *clone*, live: after the frame's refit, does every leaf of the
+    // dancer's own tree bound the deformed triangle the intersector fetches for it? Reports the
+    // pattern of any that do not — runs of leaves, and the workgroups they fall in.
+    globalThis.verify_clone_leaves = async () => paused(async () => {
+        const { verify_clone_leaves } = await import('./verify_clone_leaves.js');
+
+        return verify_clone_leaves({ renderer, scene, mesh: globalThis.dancers[0] });
+    });
+
     const frame_timer = new FrameTimer();
 
     // Tracing by default — it is the reading of the scene this page exists to check.
@@ -305,6 +381,31 @@ export async function start() {
 
     let animating = true;
 
+    /**
+     * Run a check with the dance held still.
+     *
+     * The checks read the tree and the vertices in separate readbacks, and every await between
+     * those lets the frame loop advance the pose: a box read on one frame and a box read three
+     * frames later disagree by exactly the motion in between, however right the refit is. With the
+     * loop's frames passing a zero time step, only the frames a check drives itself move the pose —
+     * which is what its "did the tree follow the mesh" question needs.
+     *
+     * @template T
+     * @param {() => Promise<T>} check
+     * @returns {Promise<T>}
+     */
+    async function paused(check) {
+        const was_animating = animating;
+
+        animating = false;
+
+        try {
+            return await check();
+        } finally {
+            animating = was_animating;
+        }
+    }
+
     element('animation').addEventListener('click', () => {
         animating = !animating;
 
@@ -365,7 +466,9 @@ export async function start() {
 
     const parameters = new URLSearchParams(location.search);
 
-    const count = Math.min(64, Math.max(1, Number.parseInt(parameters.get('count'), 10) || 1));
+    // Hundreds, not dozens: the refit is one batch whatever the count, and the point of a large cast
+    // is to see that hold.
+    const count = Math.min(512, Math.max(1, Number.parseInt(parameters.get('count'), 10) || 1));
 
     element('character_count').value = String(count);
 
@@ -388,11 +491,26 @@ export async function start() {
     /** @type {SkinnedMesh[]} */
     const dancers = [];
 
+    /**
+     * Where the load's time goes, for the console: one parse per dancer — the glTF decoded, its
+     * meshlets built and compressed, its BLAS built on the CPU, every time — then the first frames
+     * that upload every clone and tree, then one bounds readback per dancer.
+     */
+    const load_timing = { parses: [], first_frames_ms: 0, bounds_ms: 0 };
+
     try {
         const asset_manager = await make_playground_asset_manager();
 
         for (let i = 0; i < count; i++) {
+            // One parse per dancer, in sequence: at a few hundred this is the better part of a
+            // minute, and a status that does not move looks like a page that has stopped.
+            set_status(`loading ${i + 1} / ${count} × ${CHARACTER_URL} …`);
+
+            const started = performance.now();
+
             dancers.push(...await add_dancer(scene, scene_context, asset_manager, i, count));
+
+            load_timing.parses.push(performance.now() - started);
         }
     } catch (error) {
         set_status(
@@ -412,16 +530,26 @@ export async function start() {
     // Frames enough for skinning to run and its bounds-refresh chain to publish a deformed box,
     // which is the only box worth framing on — see `world_bounds_of`. The camera is parked at the
     // origin until then, so nothing is worth looking at yet either.
+    set_status(`first frames — uploading ${count} clones and their trees …`);
+
+    const first_frames_started = performance.now();
+
     for (let i = 0; i < 8; i++) {
         renderer.render(camera, scene, 1 / 60);
 
         await renderer.graphics.device.queue.onSubmittedWorkDone();
     }
 
+    load_timing.first_frames_ms = performance.now() - first_frames_started;
+
     // union over every dancer, so a crowd is framed rather than whoever loaded first
     let low = null;
     let high = null;
 
+    set_status(`framing — reading ${dancers.length} boxes back …`);
+
+    const bounds_started = performance.now();
+
     for (const dancer of dancers) {
         const bounds = await world_bounds_of(scene_context, dancer);
 
@@ -434,6 +562,20 @@ export async function start() {
         );
     }
 
+    load_timing.bounds_ms = performance.now() - bounds_started;
+
+    {
+        const parses = load_timing.parses;
+        const total = parses.reduce((sum, ms) => sum + ms, 0);
+
+        console.log(
+            `load: ${parses.length} parses in ${(total / 1000).toFixed(1)} s `
+            + `(mean ${(total / parses.length).toFixed(0)} ms, max ${Math.max(...parses).toFixed(0)} ms, `
+            + `first ${parses[0].toFixed(0)} ms) · first frames ${(load_timing.first_frames_ms / 1000).toFixed(1)} s `
+            + `· bounds readback ${(load_timing.bounds_ms / 1000).toFixed(1)} s`
+        );
+    }
+
     const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
 
     globalThis.floor = add_floor(scene, Math.max(span.x, span.z) * 6, low.y);
@@ -467,6 +609,200 @@ export async function start() {
 
     renderer.indicate_view_change();
 
+    // ---- 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 = [
+            `${count} dancer${count === 1 ? '' : 's'}`,
+            renderer.feature_path_tracing_enabled ? 'path traced' : 'rasterized',
+            animating ? 'dancing' : 'pose frozen',
+            `${renderer.pixel_ratio.toFixed(2)}x`,
+        ];
+
+        const session = new GPUProfileSession({
+            level: PROFILE_LEVEL,
+            note: `skinned_blas_refit — ${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 = `skinned_blas_refit-${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 fields 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;
+        });
+    });
+
     // ---- frame loop -----------------------------------------------------------------------
 
     const FRAME_RATE_LIMIT = 60;