@woosh/meep-engine 3.10.0 → 3.11.1

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

@@ -0,0 +1,88 @@
+/**
+ * One recorded frame.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileFrame {
+    /**
+     * The renderer's own frame counter, not this frame's position in the capture. A capture started
+     * mid-session does not begin at zero, and a frame that dropped its records leaves a gap — both
+     * of which are worth seeing.
+     * @type {number}
+     */
+    frame_index = 0;
+
+    /**
+     * `performance.now()` when the frame began encoding.
+     * @type {number}
+     */
+    cpu_begin_ms = 0;
+
+    /**
+     * `performance.now()` when the command buffer was submitted.
+     * @type {number}
+     */
+    cpu_submit_ms = 0;
+
+    /**
+     * The GPU timestamp all of this frame's spans are relative to — the earliest of them.
+     *
+     * There is no calibration between this clock and `performance.now()`; WebGPU exposes none. The
+     * CPU and GPU tracks are anchored per frame at submission and that anchoring is nominal, which
+     * is a thing to say out loud rather than paper over.
+     *
+     * @type {bigint}
+     */
+    gpu_epoch_ns = 0n;
+
+    /**
+     * Index into the capture's topology list, or -1 when the capture was recorded below
+     * {@link GPUProfileLevel.STRUCTURE} and has no structure to point at.
+     *
+     * Many frames share one: the graph is nearly identical frame to frame, so the structure is
+     * stored once and referenced.
+     *
+     * @type {number}
+     */
+    topology_id = -1;
+
+    /**
+     * The structure this frame ran, before the session has deduplicated it.
+     *
+     * Transient: the session hashes it, writes it if the shape is new, sets {@link topology_id},
+     * and never looks at this again. A frame decoded from a capture has `null` here and the id
+     * instead — the structure lives once, in the capture, rather than once per frame.
+     *
+     * @type {GPUProfileTopology|null}
+     */
+    topology = null;
+
+    /**
+     * @type {GPUProfileSpan[]}
+     */
+    spans = [];
+
+    /**
+     * Passes that went untimed because the frame had more of them than the timer array had slots.
+     * @see GPUTimerArray#dropped_count
+     * @type {number}
+     */
+    dropped_pass_count = 0;
+
+    /**
+     * Total GPU time across this frame's spans. Spans can overlap on some hardware, so this is a
+     * sum of durations rather than a wall-clock span, and the two are not the same number.
+     *
+     * @returns {number} nanoseconds
+     */
+    get gpu_duration_ns() {
+        let total = 0;
+
+        for (const span of this.spans) {
+            total += span.duration_ns;
+        }
+
+        return total;
+    }
+}

package/src/shade/device/timing/profile/GPUProfileLevel.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @param {number} level one of {@link GPUProfileLevel}
+ * @returns {string}
+ */
+export function gpu_profile_level_name(level: number): string;
+/**
+ * How much a capture records, and therefore what it costs per frame.
+ *
+ * The levels are cumulative: each includes everything below it. A capture is uncapped by default,
+ * so a per-frame figure is also a per-second one — see the rate table in the profiler proposal
+ * before reaching for {@link VERBOSE }.
+ */
+export type GPUProfileLevel = number;
+export namespace GPUProfileLevel {
+    let TIMING: number;
+    let STRUCTURE: number;
+    let WORKLOAD: number;
+    let VERBOSE: number;
+}
+//# sourceMappingURL=GPUProfileLevel.d.ts.map

package/src/shade/device/timing/profile/GPUProfileLevel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileLevel.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileLevel.js"],"names":[],"mappings":"AAqCA;;;GAGG;AACH,8CAHW,MAAM,GACJ,MAAM,CAUlB;;;;;;;;8BA1CS,MAAM"}

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

@@ -0,0 +1,50 @@
+/**
+ * How much a capture records, and therefore what it costs per frame.
+ *
+ * The levels are cumulative: each includes everything below it. A capture is uncapped by default,
+ * so a per-frame figure is also a per-second one — see the rate table in the profiler proposal
+ * before reaching for {@link VERBOSE}.
+ *
+ * @enum {number}
+ */
+export const GPUProfileLevel = {
+    /**
+     * GPU pass spans and frame boundaries. A few kilobytes a frame; runs for many minutes without
+     * anyone noticing.
+     */
+    TIMING: 0,
+
+    /**
+     * Adds the frame graph: passes, resource nodes, edges, scopes, cull decisions, and the declared
+     * size of every resource. Nearly free on top of {@link TIMING}, because the topology repeats
+     * frame to frame and is stored once.
+     */
+    STRUCTURE: 1,
+
+    /**
+     * Adds workload: dispatch and draw counts, pipeline identities, workgroup sizes, attachment
+     * state. This is the level at which "is this dispatch the right size" becomes answerable.
+     */
+    WORKLOAD: 2,
+
+    /**
+     * Adds bind group contents, resolved indirect counts, and per-pass CPU timing. Roughly an order
+     * of magnitude more data than {@link WORKLOAD}. Meant for a specific repro with a frame limit
+     * set, not for leaving running.
+     */
+    VERBOSE: 3
+};
+
+/**
+ * @param {number} level one of {@link GPUProfileLevel}
+ * @returns {string}
+ */
+export function gpu_profile_level_name(level) {
+    for (const name in GPUProfileLevel) {
+        if (GPUProfileLevel[name] === level) {
+            return name;
+        }
+    }
+
+    return `UNKNOWN(${level})`;
+}

package/src/shade/device/timing/profile/GPUProfileMeta.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Everything a reader needs in order for the numbers to mean anything.
+ *
+ * Without this a shared capture is unreadable: a pass taking 0.4 ms says nothing until you know
+ * which GPU, at what resolution, and with which features on.
+ *
+ * **On timestamp quantization.** Browsers quantize WebGPU timestamps as a timing-attack
+ * mitigation — Chrome to 100 µs unless `chrome://flags/#enable-webgpu-developer-features` is set —
+ * and the median Shade pass runs well under that. Nothing here measures or compensates for it, by
+ * deliberate choice: recovering the quantum is recovering exactly what the browser removed on
+ * purpose, and a correction that is slightly wrong skews every number it touches. The capture
+ * records what the device reported and says nothing more. Reading a coarse capture is a matter of
+ * aggregating across many frames rather than trusting any single one, and that is the reader's
+ * judgement to make, not something to bake into the data.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileMeta {
+    /**
+     * One of {@link GPUProfileLevel}.
+     * @type {number}
+     */
+    level: number;
+    /**
+     * `Date.now()` when the session started. Wall clock, for ordering captures against each other
+     * and against a bug report — not for timing anything.
+     * @type {number}
+     */
+    wall_clock_start_ms: number;
+    /**
+     * Whatever the person capturing wanted to say about it.
+     * @type {string}
+     */
+    note: string;
+    /**
+     * @type {string}
+     */
+    engine_version: string;
+    /**
+     * From `GPUAdapterInfo`. Empty where the browser withheld it, which several do.
+     * @type {string}
+     */
+    adapter_vendor: string;
+    /**
+     * @type {string}
+     */
+    adapter_architecture: string;
+    /**
+     * @type {string}
+     */
+    adapter_device: string;
+    /**
+     * @type {string}
+     */
+    adapter_description: string;
+    /**
+     * `GPUFeatureName`s the device was created with.
+     * @type {string[]}
+     */
+    features: string[];
+}
+//# sourceMappingURL=GPUProfileMeta.d.ts.map

package/src/shade/device/timing/profile/GPUProfileMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileMeta.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileMeta.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEe;IAE/B;;;;OAIG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;OAEG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,gBAFU,MAAM,CAEI;IAEpB;;OAEG;IACH,sBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,gBAFU,MAAM,CAEI;IAEpB;;OAEG;IACH,qBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,UAFU,MAAM,EAAE,CAEJ;CAEjB"}

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

@@ -0,0 +1,73 @@
+import { GPUProfileLevel } from "./GPUProfileLevel.js";
+
+/**
+ * Everything a reader needs in order for the numbers to mean anything.
+ *
+ * Without this a shared capture is unreadable: a pass taking 0.4 ms says nothing until you know
+ * which GPU, at what resolution, and with which features on.
+ *
+ * **On timestamp quantization.** Browsers quantize WebGPU timestamps as a timing-attack
+ * mitigation — Chrome to 100 µs unless `chrome://flags/#enable-webgpu-developer-features` is set —
+ * and the median Shade pass runs well under that. Nothing here measures or compensates for it, by
+ * deliberate choice: recovering the quantum is recovering exactly what the browser removed on
+ * purpose, and a correction that is slightly wrong skews every number it touches. The capture
+ * records what the device reported and says nothing more. Reading a coarse capture is a matter of
+ * aggregating across many frames rather than trusting any single one, and that is the reader's
+ * judgement to make, not something to bake into the data.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileMeta {
+    /**
+     * One of {@link GPUProfileLevel}.
+     * @type {number}
+     */
+    level = GPUProfileLevel.TIMING;
+
+    /**
+     * `Date.now()` when the session started. Wall clock, for ordering captures against each other
+     * and against a bug report — not for timing anything.
+     * @type {number}
+     */
+    wall_clock_start_ms = 0;
+
+    /**
+     * Whatever the person capturing wanted to say about it.
+     * @type {string}
+     */
+    note = "";
+
+    /**
+     * @type {string}
+     */
+    engine_version = "";
+
+    /**
+     * From `GPUAdapterInfo`. Empty where the browser withheld it, which several do.
+     * @type {string}
+     */
+    adapter_vendor = "";
+
+    /**
+     * @type {string}
+     */
+    adapter_architecture = "";
+
+    /**
+     * @type {string}
+     */
+    adapter_device = "";
+
+    /**
+     * @type {string}
+     */
+    adapter_description = "";
+
+    /**
+     * `GPUFeatureName`s the device was created with.
+     * @type {string[]}
+     */
+    features = [];
+
+}

package/src/shade/device/timing/profile/GPUProfileSession.d.ts

@@ -0,0 +1,173 @@
+/**
+ * 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.
+ *
+ * Two leaf helpers under this directory *are* linked unconditionally, because
+ * {@link ShadeGPUCommandContext} needs them while encoding: `make_profiling_pass_encoder` and
+ * `parse_workgroup_size`. They import `assert` and nothing else, and neither knows what a capture
+ * is. What remains in the engine beyond those 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 {
+    /**
+     * @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, frame_limit, note }?: {
+        level?: number;
+        frame_limit?: number;
+        note?: string;
+    });
+    /**
+     * 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(): number;
+    /**
+     * 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: number;
+    /**
+     * Fires per frame with the running byte total.
+     *
+     * @readonly
+     * @type {Signal<number>}
+     */
+    readonly onBytesWritten: any;
+    /**
+     * 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>}
+     */
+    readonly onComplete: any;
+    /**
+     * @returns {number} one of {@link GPUProfileLevel}
+     */
+    get level(): number;
+    /**
+     * @returns {boolean}
+     */
+    get is_running(): boolean;
+    /**
+     * @returns {number}
+     */
+    get frames_recorded(): number;
+    /**
+     * @returns {number}
+     */
+    get bytes_written(): number;
+    /**
+     * 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(): GPUProfileMeta;
+    /**
+     * Begin recording.
+     *
+     * {@link meta} is written into the stream here and not read again, so populate it first.
+     *
+     * @returns {void}
+     */
+    start(): void;
+    /**
+     * 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: number, cpu_begin_ms: number): GPUFrameRecorder | null;
+    /**
+     * 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: GPUFrameRecorder, cpu_submit_ms: number): void;
+    /**
+     * 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: GPUProfileFrame): void;
+    /**
+     * 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(): ArrayBuffer;
+    /**
+     * 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(): ArrayBuffer;
+    /**
+     * Resolves with the capture when the session ends, whichever way it ends.
+     *
+     * @returns {Promise<ArrayBuffer>}
+     */
+    get done(): Promise<ArrayBuffer>;
+    #private;
+}
+import { GPUProfileMeta } from "./GPUProfileMeta.js";
+import { GPUFrameRecorder } from "./GPUFrameRecorder.js";
+//# sourceMappingURL=GPUProfileSession.d.ts.map

package/src/shade/device/timing/profile/GPUProfileSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileSession.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileSession.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IAqGI;;;;;;OAMG;IACH;QAL4B,KAAK,GAAtB,MAAM;QACW,WAAW,GAA5B,MAAM;QAEW,IAAI,GAArB,MAAM;OAkBhB;IA7DD;;;;;;;OAOG;IACH,6BAEC;IAED;;;;;;OAMG;IACH,aAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,6BAA8B;IAE9B;;;;;;OAMG;IACH,yBAA0B;IA2B1B;;OAEG;IACH,oBAEC;IAED;;OAEG;IACH,0BAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;;;;;OAMG;IACH,SAFa,IAAI,CAqBhB;IAED;;;;;;;;;;;OAWG;IACH,yBAJW,MAAM,gBACN,MAAM,GACJ,gBAAgB,GAAC,IAAI,CAkBjC;IAED;;;;;;OAMG;IACH,oBAJW,gBAAgB,iBAChB,MAAM,GACJ,IAAI,CAMhB;IAsCD;;;;;;;;;OASG;IACH,sCAFa,IAAI,CAkEhB;IAED;;;;;;;OAOG;IACH,YAFa,WAAW,CAMvB;IAED;;;;;;;;OAQG;IACH,QAFa,WAAW,CAiBvB;IAOD;;;;OAIG;IACH,iCAaC;;CACJ;+BAjd8B,qBAAqB;iCAFnB,uBAAuB"}