@woosh/meep-engine 3.34.0 → 3.35.0

package/src/shade/device/timing/profile/GPUProfileSession.js

@@ -1,474 +1,553 @@
-import { assert } from "../../../../core/assert.js";
-import { Signal } from "../../../../core/events/signal/Signal.js";
-import { GPUFrameRecorder } from "./GPUFrameRecorder.js";
-import { GPUProfileLevel, gpu_profile_level_name } from "./GPUProfileLevel.js";
-import { GPUProfileMeta } from "./GPUProfileMeta.js";
-import { SGPT_RECORD_TYPE } from "./SGPT_RECORD_TYPE.js";
-import { SGPTWriteStream } from "./SGPTWriteStream.js";
-import { sgpt_write_frame } from "./sgpt_frame_codec.js";
-import { sgpt_write_meta } from "./sgpt_meta_codec.js";
-import {
-    sgpt_intern_topology_symbols,
-    sgpt_topology_hash,
-    sgpt_write_topology
-} from "./sgpt_topology_codec.js";
-
-/**
- * @typedef {import("./GPUProfileFrame.js").GPUProfileFrame} GPUProfileFrame
- */
-
-/**
- * Default point at which an uncapped session starts saying how much it has accumulated. Does not
- * stop anything — see {@link GPUProfileSession#byte_budget}.
- *
- * @type {number}
- */
-const DEFAULT_BYTE_BUDGET = 512 * 1024 * 1024;
-
-/**
- * A GPU profile recording, from `start` to `stop`.
- *
- * **The engine never constructs one of these.** The caller builds it and hands it over:
- *
- * ```js
- * const session = new GPUProfileSession({ level: GPUProfileLevel.TIMING });
- *
- * renderer.profile_session = session;
- *
- * await session.start(graphics);
- * // ... frames run, for as long as you like ...
- * const bytes = await session.stop();
- *
- * renderer.profile_session = null;
- * ```
- *
- * That ownership is the point rather than a style choice. **Nothing in the engine imports this file
- * or anything it reaches** — the write stream, the format codecs, the topology extractor — so an
- * application that never mentions the profiler does not carry any of it. The feature ships without
- * a build flag, a strip-plugin interaction, or a dead branch anyone has to keep honest.
- *
- * Nothing under this directory is linked unconditionally. The pass encoders count dispatches into a
- * {@link GPUProfileWork} when handed one, but they hold it as a bag of counters and never name the
- * type; the workgroup size they record comes off {@link ComputePipelineDescriptor}, which reads it
- * as its code is set. What remains in the engine is a nullable field and the null checks around it.
- *
- * Recording is an **open-ended forward stream**: `frame_limit` defaults to `Infinity` and
- * everything captured is kept. There is no ring buffer. Uncapped means a per-frame cost is also a
- * per-second one, so the session reports what it is accumulating rather than letting an
- * application find out when the tab dies.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class GPUProfileSession {
-
-    /**
-     * @type {number}
-     */
-    #level = GPUProfileLevel.TIMING;
-
-    /**
-     * @type {number}
-     */
-    #frame_limit = Infinity;
-
-    /**
-     * @type {string}
-     */
-    #note = "";
-
-    /**
-     * @type {SGPTWriteStream|null}
-     */
-    #stream = null;
-
-    /**
-     * @type {GPUProfileMeta}
-     */
-    #meta = new GPUProfileMeta();
-
-    /**
-     * @type {number}
-     */
-    #frames_recorded = 0;
-
-    /**
-     * @type {boolean}
-     */
-    #running = false;
-
-    /**
-     * @type {boolean}
-     */
-    #stopped = false;
-
-    /**
-     * @type {boolean}
-     */
-    #budget_warned = false;
-
-    /**
-     * Content hash of every topology already written, to the id it was given.
-     *
-     * The whole of the deduplication. A Shade frame graph is nearly identical frame to frame, so
-     * this map stays tiny and hundreds of frames share one entry — the difference between a capture
-     * of tens of megabytes and one of a couple.
-     *
-     * @type {Map<number, number>}
-     */
-    #topology_ids = new Map();
-
-    /**
-     * @type {number}
-     */
-    #topology_count = 0;
-
-    /**
-     * How many distinct frame graph structures this capture has needed.
-     *
-     * Worth watching: if this climbs with the frame count, the graph is changing shape every frame
-     * and the size estimates for a long capture do not hold.
-     *
-     * @returns {number}
-     */
-    get topology_count() {
-        return this.#topology_count;
-    }
-
-    /**
-     * Bytes at which the session warns — once — that it is getting large. It does **not** stop:
-     * full uncapped history is the behaviour that was asked for, and silently truncating a capture
-     * is worse than a large one.
-     *
-     * @type {number}
-     */
-    byte_budget = DEFAULT_BYTE_BUDGET;
-
-    /**
-     * Fires per frame with the running byte total.
-     *
-     * @readonly
-     * @type {Signal<number>}
-     */
-    onBytesWritten = new Signal();
-
-    /**
-     * Fires once, with the finished capture, however the session ended — `stop()` or the frame
-     * limit running out. Both paths land here so a caller can await one thing.
-     *
-     * @readonly
-     * @type {Signal<ArrayBuffer>}
-     */
-    onComplete = new Signal();
-
-    /**
-     * @param {object} [options]
-     * @param {number} [options.level] one of {@link GPUProfileLevel}
-     * @param {number} [options.frame_limit] frames to record before stopping on its own. `Infinity`
-     * by default — a session runs until `stop()`.
-     * @param {string} [options.note] whatever you want the capture to say about itself
-     */
-    constructor({
-                    level = GPUProfileLevel.TIMING,
-                    frame_limit = Infinity,
-                    note = ""
-                } = {}) {
-
-        assert.isInteger(level, 'level');
-        assert.isString(note, 'note');
-        assert.ok(
-            frame_limit === Infinity || (Number.isInteger(frame_limit) && frame_limit > 0),
-            `frame_limit must be a positive integer or Infinity, was ${frame_limit}`
-        );
-
-        this.#level = level;
-        this.#frame_limit = frame_limit;
-        this.#note = note;
-    }
-
-    /**
-     * @returns {number} one of {@link GPUProfileLevel}
-     */
-    get level() {
-        return this.#level;
-    }
-
-    /**
-     * @returns {boolean}
-     */
-    get is_running() {
-        return this.#running;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get frames_recorded() {
-        return this.#frames_recorded;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get bytes_written() {
-        return this.#stream === null ? 0 : this.#stream.bytes_written;
-    }
-
-    /**
-     * The metadata this capture will carry. Populate before {@link start}; it is written into the
-     * stream at that point and not read again.
-     *
-     * @returns {GPUProfileMeta}
-     */
-    get meta() {
-        return this.#meta;
-    }
-
-    /**
-     * Begin recording.
-     *
-     * {@link meta} is written into the stream here and not read again, so populate it first.
-     *
-     * @returns {void}
-     */
-    start() {
-        assert.notOk(this.#running, 'session already started');
-        assert.notOk(this.#stopped, 'a stopped session cannot be restarted; construct a new one');
-
-        const meta = this.#meta;
-
-        meta.level = this.#level;
-        meta.note = this.#note;
-
-        if (meta.wall_clock_start_ms === 0) {
-            meta.wall_clock_start_ms = Date.now();
-        }
-
-        const stream = new SGPTWriteStream();
-
-        stream.write_record(SGPT_RECORD_TYPE.META, sgpt_write_meta, meta);
-
-        this.#stream = stream;
-        this.#running = true;
-    }
-
-    /**
-     * Open a recorder for a frame about to be encoded, or null when nothing should be recorded.
-     *
-     * **This is why the renderer imports nothing from the profiler.** It holds a nullable session
-     * and calls methods on it; the recorder type never appears in its module graph, so the whole
-     * profiler stays unreachable from any engine entry point and drops out of a bundle that does
-     * not ask for it. A `new GPUFrameRecorder(...)` in the renderer would have quietly undone that.
-     *
-     * @param {number} frame_index the renderer's own frame counter
-     * @param {number} cpu_begin_ms
-     * @returns {GPUFrameRecorder|null}
-     */
-    begin_frame(frame_index, cpu_begin_ms) {
-        if (!this.#running) {
-            return null;
-        }
-
-        const recorder = new GPUFrameRecorder(frame_index, cpu_begin_ms);
-
-        if (this.#level >= GPUProfileLevel.STRUCTURE) {
-            recorder.enable_structure_capture();
-        }
-
-        if (this.#level >= GPUProfileLevel.WORKLOAD) {
-            recorder.enable_work_capture();
-        }
-
-        return recorder;
-    }
-
-    /**
-     * Close a recorder opened by {@link begin_frame} and commit what it collected.
-     *
-     * @param {GPUFrameRecorder} recorder
-     * @param {number} cpu_submit_ms
-     * @returns {void}
-     */
-    end_frame(recorder, cpu_submit_ms) {
-        assert.defined(recorder, 'recorder');
-
-        this.record_frame(recorder.close(cpu_submit_ms));
-    }
-
-    /**
-     * Write a topology if this shape has not been seen, and return the id either way.
-     *
-     * @param {GPUProfileTopology} topology
-     * @returns {number}
-     */
-    #write_topology(topology) {
-        const hash = sgpt_topology_hash(topology);
-
-        const existing = this.#topology_ids.get(hash);
-
-        if (existing !== undefined) {
-            return existing;
-        }
-
-        const id = this.#topology_count++;
-
-        topology.id = id;
-
-        this.#topology_ids.set(hash, id);
-
-        const stream = this.#stream;
-
-        // Ahead of the record, for the same reason frame span labels are — a `SYMS` block must
-        // precede whatever references it, or a capture truncated in between resolves no names.
-        sgpt_intern_topology_symbols(topology, value => stream.intern(value));
-
-        stream.write_record(
-            SGPT_RECORD_TYPE.TOPO,
-            (buffer, t) => sgpt_write_topology(buffer, t, value => stream.intern(value)),
-            topology
-        );
-
-        return id;
-    }
-
-    /**
-     * Commit one frame.
-     *
-     * Ignored when the session is not running, so a frame that lands after `stop()` — the readback
-     * for a frame already submitted, which is the ordinary case — is dropped rather than throwing
-     * inside somebody's render loop.
-     *
-     * @param {GPUProfileFrame} frame
-     * @returns {void}
-     */
-    record_frame(frame) {
-        assert.defined(frame, 'frame');
-
-        if (!this.#running) {
-            return;
-        }
-
-        const stream = this.#stream;
-
-        // Reserve before writing, so the buffer's growth — an allocation and a copy — happens here
-        // at the boundary rather than part-way through encoding a frame.
-        stream.reserve_frame();
-
-        if (frame.topology !== null && frame.topology !== undefined) {
-            frame.topology_id = this.#write_topology(frame.topology);
-        }
-
-        /*
-         Intern every name this frame uses *before* the record is opened.
-
-         `write_record` flushes pending symbols ahead of the record it is about to write, and
-         interning from inside the payload writer is too late for that — the symbols would land in
-         the *next* flush, behind the record referencing them. A reader of a capture truncated in
-         between then resolves none of them, which is the failure this format exists to avoid.
-
-         Doing it here rather than inside the stream keeps the stream ignorant of the frame model.
-        */
-        for (const span of frame.spans) {
-            stream.intern(span.label);
-
-            if (span.work !== null && span.work !== undefined) {
-                stream.intern(span.work.pipeline);
-            }
-        }
-
-        stream.write_record(
-            SGPT_RECORD_TYPE.FRAM,
-            (buffer, f) => sgpt_write_frame(buffer, f, value => stream.intern(value)),
-            frame
-        );
-
-        this.#frames_recorded++;
-
-        const bytes = stream.bytes_written;
-
-        if (this.onBytesWritten.hasHandlers()) {
-            this.onBytesWritten.send1(bytes);
-        }
-
-        if (!this.#budget_warned && bytes >= this.byte_budget) {
-            this.#budget_warned = true;
-
-            const per_frame = Math.round(bytes / this.#frames_recorded);
-
-            console.warn(
-                `GPUProfileSession: ${(bytes / (1024 * 1024)).toFixed(0)} MiB after `
-                + `${this.#frames_recorded} frames at level ${gpu_profile_level_name(this.#level)} `
-                + `(~${per_frame} bytes/frame). Recording continues — call stop() when you have enough.`
-            );
-        }
-
-        if (this.#frames_recorded >= this.#frame_limit) {
-            this.stop();
-        }
-    }
-
-    /**
-     * The capture as it stands, without ending the session.
-     *
-     * Reads back as a capture that was cut short — no directory, not marked closed — because that
-     * is precisely what it is. Recording continues afterwards.
-     *
-     * @returns {ArrayBuffer}
-     */
-    snapshot() {
-        assert.ok(this.#running, 'session is not running');
-
-        return this.#stream.snapshot();
-    }
-
-    /**
-     * End the recording and hand back the capture.
-     *
-     * Calling it twice returns the same bytes rather than complaining; a session that hit its
-     * frame limit has already stopped itself, and the caller awaiting `stop()` should still get
-     * the capture.
-     *
-     * @returns {ArrayBuffer}
-     */
-    stop() {
-        if (this.#stopped) {
-            return this.#result;
-        }
-
-        assert.ok(this.#running, 'session was never started');
-
-        this.#running = false;
-        this.#stopped = true;
-
-        this.#result = this.#stream.finish();
-
-        this.onComplete.send1(this.#result);
-
-        return this.#result;
-    }
-
-    /**
-     * @type {ArrayBuffer|null}
-     */
-    #result = null;
-
-    /**
-     * Resolves with the capture when the session ends, whichever way it ends.
-     *
-     * @returns {Promise<ArrayBuffer>}
-     */
-    get done() {
-        if (this.#stopped) {
-            return Promise.resolve(this.#result);
-        }
-
-        return new Promise(resolve => {
-            this.onComplete.addOne(resolve);
-
-            if (this.#stopped) {
-                // guard against the session ending between the check above and the subscription
-                resolve(this.#result);
-            }
-        });
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import { Signal } from "../../../../core/events/signal/Signal.js";
+import { GPUFrameRecorder } from "./GPUFrameRecorder.js";
+import { GPUProfileLevel, gpu_profile_level_name } from "./GPUProfileLevel.js";
+import { GPUProfileMeta } from "./GPUProfileMeta.js";
+import { SGPT_RECORD_TYPE } from "./SGPT_RECORD_TYPE.js";
+import { SGPTWriteStream } from "./SGPTWriteStream.js";
+import { sgpt_write_frame } from "./sgpt_frame_codec.js";
+import { sgpt_write_meta } from "./sgpt_meta_codec.js";
+import {
+    sgpt_intern_topology_symbols,
+    sgpt_topology_hash,
+    sgpt_write_topology
+} from "./sgpt_topology_codec.js";
+
+/**
+ * @typedef {import("./GPUProfileFrame.js").GPUProfileFrame} GPUProfileFrame
+ */
+
+/**
+ * Default point at which an uncapped session starts saying how much it has accumulated. Does not
+ * stop anything — see {@link GPUProfileSession#byte_budget}.
+ *
+ * @type {number}
+ */
+const DEFAULT_BYTE_BUDGET = 512 * 1024 * 1024;
+
+/**
+ * A GPU profile recording, from `start` to `stop`.
+ *
+ * **The engine never constructs one of these.** The caller builds it and hands it over:
+ *
+ * ```js
+ * const session = new GPUProfileSession({ level: GPUProfileLevel.TIMING });
+ *
+ * renderer.profile_session = session;
+ *
+ * await session.start(graphics);
+ * // ... frames run, for as long as you like ...
+ * const bytes = await session.stop();
+ *
+ * renderer.profile_session = null;
+ * ```
+ *
+ * That ownership is the point rather than a style choice. **Nothing in the engine imports this file
+ * or anything it reaches** — the write stream, the format codecs, the topology extractor — so an
+ * application that never mentions the profiler does not carry any of it. The feature ships without
+ * a build flag, a strip-plugin interaction, or a dead branch anyone has to keep honest.
+ *
+ * Nothing under this directory is linked unconditionally. The pass encoders count dispatches into a
+ * {@link GPUProfileWork} when handed one, but they hold it as a bag of counters and never name the
+ * type; the workgroup size they record comes off {@link ComputePipelineDescriptor}, which reads it
+ * as its code is set. What remains in the engine is a nullable field and the null checks around it.
+ *
+ * Recording is an **open-ended forward stream**: `frame_limit` defaults to `Infinity` and
+ * everything captured is kept. There is no ring buffer. Uncapped means a per-frame cost is also a
+ * per-second one, so the session reports what it is accumulating rather than letting an
+ * application find out when the tab dies.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileSession {
+
+    /**
+     * @type {number}
+     */
+    #level = GPUProfileLevel.TIMING;
+
+    /**
+     * @type {number}
+     */
+    #frame_limit = Infinity;
+
+    /**
+     * @type {string}
+     */
+    #note = "";
+
+    /**
+     * @type {SGPTWriteStream|null}
+     */
+    #stream = null;
+
+    /**
+     * @type {GPUProfileMeta}
+     */
+    #meta = new GPUProfileMeta();
+
+    /**
+     * @type {number}
+     */
+    #frames_recorded = 0;
+
+    /**
+     * The frames of recorders {@link begin_frame} has handed out that have not come back through
+     * {@link record_frame} yet — the ones whose timings are still on their way. {@link stop} waits
+     * for this to empty.
+     *
+     * @type {Set<GPUProfileFrame>}
+     */
+    #outstanding = new Set();
+
+    /**
+     * @type {boolean}
+     */
+    #running = false;
+
+    /**
+     * Whether `stop()` has been called, or the frame limit reached. The capture is finished once
+     * this is set and nothing is outstanding.
+     *
+     * @type {boolean}
+     */
+    #stopped = false;
+
+    /**
+     * @type {boolean}
+     */
+    #budget_warned = false;
+
+    /**
+     * Content hash of every topology already written, to the id it was given.
+     *
+     * The whole of the deduplication. A Shade frame graph is nearly identical frame to frame, so
+     * this map stays tiny and hundreds of frames share one entry — the difference between a capture
+     * of tens of megabytes and one of a couple.
+     *
+     * @type {Map<number, number>}
+     */
+    #topology_ids = new Map();
+
+    /**
+     * @type {number}
+     */
+    #topology_count = 0;
+
+    /**
+     * How many distinct frame graph structures this capture has needed.
+     *
+     * Worth watching: if this climbs with the frame count, the graph is changing shape every frame
+     * and the size estimates for a long capture do not hold.
+     *
+     * @returns {number}
+     */
+    get topology_count() {
+        return this.#topology_count;
+    }
+
+    /**
+     * Bytes at which the session warns — once — that it is getting large. It does **not** stop:
+     * full uncapped history is the behaviour that was asked for, and silently truncating a capture
+     * is worse than a large one.
+     *
+     * @type {number}
+     */
+    byte_budget = DEFAULT_BYTE_BUDGET;
+
+    /**
+     * Fires per frame with the running byte total.
+     *
+     * @readonly
+     * @type {Signal<number>}
+     */
+    onBytesWritten = new Signal();
+
+    /**
+     * Fires once, with the finished capture, however the session ended — `stop()` or the frame
+     * limit running out — once the frames begun before that have landed. Both paths land here so a
+     * caller can await one thing.
+     *
+     * @readonly
+     * @type {Signal<ArrayBuffer>}
+     */
+    onComplete = new Signal();
+
+    /**
+     * @param {object} [options]
+     * @param {number} [options.level] one of {@link GPUProfileLevel}
+     * @param {number} [options.frame_limit] frames to record before stopping on its own. `Infinity`
+     * by default — a session runs until `stop()`.
+     * @param {string} [options.note] whatever you want the capture to say about itself
+     */
+    constructor({
+                    level = GPUProfileLevel.TIMING,
+                    frame_limit = Infinity,
+                    note = ""
+                } = {}) {
+
+        assert.isInteger(level, 'level');
+        assert.isString(note, 'note');
+        assert.ok(
+            frame_limit === Infinity || (Number.isInteger(frame_limit) && frame_limit > 0),
+            `frame_limit must be a positive integer or Infinity, was ${frame_limit}`
+        );
+
+        this.#level = level;
+        this.#frame_limit = frame_limit;
+        this.#note = note;
+    }
+
+    /**
+     * @returns {number} one of {@link GPUProfileLevel}
+     */
+    get level() {
+        return this.#level;
+    }
+
+    /**
+     * Whether new frames are being taken: from `start()` until `stop()` or the frame limit. A session
+     * that is no longer running can still be waiting on frames begun before that; {@link done} says
+     * when it has them.
+     *
+     * @returns {boolean}
+     */
+    get is_running() {
+        return this.#running;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get frames_recorded() {
+        return this.#frames_recorded;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get bytes_written() {
+        return this.#stream === null ? 0 : this.#stream.bytes_written;
+    }
+
+    /**
+     * The metadata this capture will carry. Populate before {@link start}; it is written into the
+     * stream at that point and not read again.
+     *
+     * @returns {GPUProfileMeta}
+     */
+    get meta() {
+        return this.#meta;
+    }
+
+    /**
+     * Begin recording.
+     *
+     * {@link meta} is written into the stream here and not read again, so populate it first.
+     *
+     * @returns {void}
+     */
+    start() {
+        assert.notOk(this.#running, 'session already started');
+        assert.notOk(this.#stopped, 'a stopped session cannot be restarted; construct a new one');
+
+        const meta = this.#meta;
+
+        meta.level = this.#level;
+        meta.note = this.#note;
+
+        if (meta.wall_clock_start_ms === 0) {
+            meta.wall_clock_start_ms = Date.now();
+        }
+
+        const stream = new SGPTWriteStream();
+
+        stream.write_record(SGPT_RECORD_TYPE.META, sgpt_write_meta, meta);
+
+        this.#stream = stream;
+        this.#running = true;
+    }
+
+    /**
+     * Open a recorder for a frame about to be encoded, or null when nothing should be recorded.
+     *
+     * **This is why the renderer imports nothing from the profiler.** It holds a nullable session
+     * and calls methods on it; the recorder type never appears in its module graph, so the whole
+     * profiler stays unreachable from any engine entry point and drops out of a bundle that does
+     * not ask for it. A `new GPUFrameRecorder(...)` in the renderer would have quietly undone that.
+     *
+     * @param {number} frame_index the renderer's own frame counter
+     * @param {number} cpu_begin_ms
+     * @returns {GPUFrameRecorder|null}
+     */
+    begin_frame(frame_index, cpu_begin_ms) {
+        if (!this.#running) {
+            return null;
+        }
+
+        const recorder = new GPUFrameRecorder(frame_index, cpu_begin_ms);
+
+        if (this.#level >= GPUProfileLevel.STRUCTURE) {
+            recorder.enable_structure_capture();
+        }
+
+        if (this.#level >= GPUProfileLevel.WORKLOAD) {
+            recorder.enable_work_capture();
+        }
+
+        this.#outstanding.add(recorder.frame);
+
+        return recorder;
+    }
+
+    /**
+     * Close a recorder opened by {@link begin_frame} and commit what it collected — after `stop()`
+     * too, which is waiting for exactly this.
+     *
+     * @param {GPUFrameRecorder} recorder
+     * @param {number} cpu_submit_ms
+     * @returns {void}
+     */
+    end_frame(recorder, cpu_submit_ms) {
+        assert.defined(recorder, 'recorder');
+
+        let frame;
+
+        try {
+            frame = recorder.close(cpu_submit_ms);
+        } catch (error) {
+            // `stop()` is waiting on this frame, and a capture missing it beats a caller hung for good
+            this.#settle(recorder.frame);
+
+            throw error;
+        }
+
+        this.record_frame(frame);
+    }
+
+    /**
+     * A frame is back, whether or not it was written. Finishes the capture if `stop()` was waiting
+     * for it and it was the last.
+     *
+     * @param {GPUProfileFrame} frame
+     * @returns {void}
+     */
+    #settle(frame) {
+        if (
+            this.#outstanding.delete(frame)
+            && this.#stopped
+            && this.#outstanding.size === 0
+            && this.#result === null
+        ) {
+            this.#finish();
+        }
+    }
+
+    /**
+     * Write a topology if this shape has not been seen, and return the id either way.
+     *
+     * @param {GPUProfileTopology} topology
+     * @returns {number}
+     */
+    #write_topology(topology) {
+        const hash = sgpt_topology_hash(topology);
+
+        const existing = this.#topology_ids.get(hash);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const id = this.#topology_count++;
+
+        topology.id = id;
+
+        this.#topology_ids.set(hash, id);
+
+        const stream = this.#stream;
+
+        // Ahead of the record, for the same reason frame span labels are — a `SYMS` block must
+        // precede whatever references it, or a capture truncated in between resolves no names.
+        sgpt_intern_topology_symbols(topology, value => stream.intern(value));
+
+        stream.write_record(
+            SGPT_RECORD_TYPE.TOPO,
+            (buffer, t) => sgpt_write_topology(buffer, t, value => stream.intern(value)),
+            topology
+        );
+
+        return id;
+    }
+
+    /**
+     * Commit one frame.
+     *
+     * Taken for as long as the stream is open: from `start()` until the capture is finished, which
+     * `stop()` holds off until every frame already begun has landed. Ignored before `start()`, once
+     * the capture is finished, and past the frame limit — frames begun before the limit was reached
+     * still land after it — rather than throwing inside somebody's render loop.
+     *
+     * @param {GPUProfileFrame} frame
+     * @returns {void}
+     */
+    record_frame(frame) {
+        assert.defined(frame, 'frame');
+
+        try {
+            this.#write_frame(frame);
+        } finally {
+            // written, refused or thrown, it is no longer on its way
+            this.#settle(frame);
+        }
+    }
+
+    /**
+     * @param {GPUProfileFrame} frame
+     * @returns {void}
+     */
+    #write_frame(frame) {
+        if (this.#stream === null || this.#result !== null || this.#frames_recorded >= this.#frame_limit) {
+            return;
+        }
+
+        const stream = this.#stream;
+
+        // Reserve before writing, so the buffer's growth — an allocation and a copy — happens here
+        // at the boundary rather than part-way through encoding a frame.
+        stream.reserve_frame();
+
+        if (frame.topology !== null && frame.topology !== undefined) {
+            frame.topology_id = this.#write_topology(frame.topology);
+        }
+
+        /*
+         Intern every name this frame uses *before* the record is opened.
+
+         `write_record` flushes pending symbols ahead of the record it is about to write, and
+         interning from inside the payload writer is too late for that — the symbols would land in
+         the *next* flush, behind the record referencing them. A reader of a capture truncated in
+         between then resolves none of them, which is the failure this format exists to avoid.
+
+         Doing it here rather than inside the stream keeps the stream ignorant of the frame model.
+        */
+        for (const span of frame.spans) {
+            stream.intern(span.label);
+
+            if (span.work !== null && span.work !== undefined) {
+                stream.intern(span.work.pipeline);
+            }
+        }
+
+        stream.write_record(
+            SGPT_RECORD_TYPE.FRAM,
+            (buffer, f) => sgpt_write_frame(buffer, f, value => stream.intern(value)),
+            frame
+        );
+
+        this.#frames_recorded++;
+
+        const bytes = stream.bytes_written;
+
+        if (this.onBytesWritten.hasHandlers()) {
+            this.onBytesWritten.send1(bytes);
+        }
+
+        if (!this.#budget_warned && bytes >= this.byte_budget) {
+            this.#budget_warned = true;
+
+            const per_frame = Math.round(bytes / this.#frames_recorded);
+
+            console.warn(
+                `GPUProfileSession: ${(bytes / (1024 * 1024)).toFixed(0)} MiB after `
+                + `${this.#frames_recorded} frames at level ${gpu_profile_level_name(this.#level)} `
+                + `(~${per_frame} bytes/frame). Recording continues — call stop() when you have enough.`
+            );
+        }
+
+        if (this.#frames_recorded >= this.#frame_limit) {
+            this.stop();
+        }
+    }
+
+    /**
+     * The capture as it stands, without ending the session.
+     *
+     * Reads back as a capture that was cut short — no directory, not marked closed — because that
+     * is precisely what it is. Recording continues afterwards.
+     *
+     * @returns {ArrayBuffer}
+     */
+    snapshot() {
+        assert.ok(this.#running, 'session is not running');
+
+        return this.#stream.snapshot();
+    }
+
+    /**
+     * End the recording, and resolve with the capture once every frame already begun has landed.
+     *
+     * No frame is begun after this — {@link begin_frame} hands out nothing — but the ones that were
+     * are kept. A frame is committed when its timestamp readback resolves, a `mapAsync` behind its
+     * submit, so when `stop()` is called the last frame or two are always still on their way; behind
+     * a first-use pipeline compile, which holds the queue for seconds, every frame of a short capture
+     * can be. Finishing the stream on the spot threw all of those away without a word.
+     *
+     * Calling it again resolves with the same capture rather than complaining; a session that hit
+     * its frame limit has already stopped itself, and the caller awaiting `stop()` should still get
+     * the capture.
+     *
+     * @returns {Promise<ArrayBuffer>}
+     */
+    stop() {
+        if (!this.#stopped) {
+            assert.ok(this.#running, 'session was never started');
+
+            this.#running = false;
+            this.#stopped = true;
+
+            if (this.#outstanding.size === 0) {
+                this.#finish();
+            }
+        }
+
+        return this.done;
+    }
+
+    /**
+     * Close the stream and hand the capture to whoever is waiting for it.
+     *
+     * @returns {void}
+     */
+    #finish() {
+        this.#result = this.#stream.finish();
+
+        this.onComplete.send1(this.#result);
+    }
+
+    /**
+     * @type {ArrayBuffer|null}
+     */
+    #result = null;
+
+    /**
+     * Resolves with the capture when the session ends, whichever way it ends — after the frames
+     * begun before the end have landed.
+     *
+     * @returns {Promise<ArrayBuffer>}
+     */
+    get done() {
+        if (this.#result !== null) {
+            return Promise.resolve(this.#result);
+        }
+
+        return new Promise(resolve => {
+            this.onComplete.addOne(resolve);
+
+            if (this.#result !== null) {
+                // guard against the session ending between the check above and the subscription
+                resolve(this.#result);
+            }
+        });
+    }
+}