@ifc-lite/renderer 1.49.1 → 2.0.0

package/dist/frame-timing-cpu.js

@@ -0,0 +1,25 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * Creates a `CpuFrameTicker`. The clock read (`performance.now()` in a real
+ * caller) happens OUTSIDE this module — `tick(nowMs)` takes the timestamp as
+ * a parameter rather than reading a clock itself, so this module has no
+ * dependency on real elapsed time and its own tests (see
+ * `frame-timing-cpu.test.ts`) can feed synthetic values deterministically.
+ */
+export function createCpuFrameTicker() {
+    let lastMs = null;
+    const deltas = [];
+    return {
+        tick(nowMs) {
+            if (lastMs !== null)
+                deltas.push(nowMs - lastMs);
+            lastMs = nowMs;
+        },
+        deltasMs() {
+            return deltas.slice();
+        },
+    };
+}
+//# sourceMappingURL=frame-timing-cpu.js.map

package/dist/frame-timing-cpu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-timing-cpu.js","sourceRoot":"","sources":["../src/frame-timing-cpu.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AA0B/D;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,OAAO;QACL,IAAI,CAAC,KAAa;YAChB,IAAI,MAAM,KAAK,IAAI;gBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;YACjD,MAAM,GAAG,KAAK,CAAC;QACjB,CAAC;QACD,QAAQ;YACN,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/frame-timing-gpu.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Thin GPU-facing half of frame/pass timing (issue #2670 perf-verdict gate).
+ * Everything with judgement — statistics, unit conversion, mode selection —
+ * lives in `frame-timing.ts` / `frame-timing-stats.ts`, which are pure and
+ * fully covered by synthetic-value tests. This file is deliberately as small
+ * as it can be: it only creates the `GPUQuerySet`, writes `timestampWrites`
+ * into pass descriptors, resolves the query set into a readback buffer, and
+ * hands the raw nanosecond pairs to the pure aggregator. None of it runs in
+ * this environment (`navigator.gpu` is absent here, so there is no test file
+ * for this module — a mock `GPUDevice` would only prove the mock is
+ * internally consistent, not that the real WebGPU calls are correct) and
+ * none of it should be trusted without exercising it on a real
+ * `'timestamp-query'`-capable adapter.
+ *
+ * OPT-IN, NOT WIRED BY DEFAULT: nothing in this codebase constructs a
+ * `GpuFrameTimingRecorder` today. A caller enables it explicitly:
+ *
+ * ```ts
+ * const recorder = GpuFrameTimingRecorder.create(device); // null if unsupported
+ * if (recorder) {
+ *   const pass = encoder.beginRenderPass({
+ *     ...descriptor,
+ *     timestampWrites: recorder.beginPass('main'),
+ *   });
+ *   // ...draw calls...
+ *   pass.end();
+ *   recorder.endFrame(encoder);
+ *   device.queue.submit([encoder.finish()]);
+ *   const samples = await recorder.readback(); // PassTimingSample[] | null
+ * }
+ * ```
+ *
+ * Measuring every frame changes what you're measuring (query resolution and
+ * the readback `mapAsync` are not free), so a caller should sample
+ * intermittently (e.g. every Nth frame) rather than every frame in a
+ * shipped build — this module does not impose that policy, it only makes
+ * one frame's measurement cheap and correct.
+ */
+import type { PassTimingSample } from './frame-timing.js';
+/** Feature-detects `'timestamp-query'` on an already-created `GPUDevice`'s adapter features, without touching mode-decision logic (see `decideTimingMode` in `frame-timing.ts`, which consumes this boolean). */
+export declare function hasTimestampQueryFeature(features: {
+    has(name: string): boolean;
+} | null | undefined): boolean;
+/**
+ * Byte size of the resolve/readback buffers needed for `passCount` passes —
+ * 2 timestamp queries (begin + end) per pass, `BYTES_PER_TIMESTAMP` each.
+ * Pure arithmetic, decidable without a device: extracted out of `create()`
+ * so the sizing formula itself is unit-tested rather than only ever
+ * exercised as a side effect of a real `device.createBuffer` call.
+ */
+export declare function queryBufferSizeBytes(passCount: number): number;
+/**
+ * Allocates the next pair of query-set write indices for one pass, or
+ * `null` if `maxPasses` passes have already been begun this frame. Pure:
+ * given the current cursor and the frame's pass budget, the next
+ * (begin, end, cursor) triple — or exhaustion — is fully determined; no
+ * `GPUQuerySet` is touched to decide it. Extracted out of
+ * `GpuFrameTimingRecorder.beginPass` so this index bookkeeping (the part
+ * most likely to hide an off-by-one — see the exhaustion boundary test) is
+ * checked with synthetic cursor/maxPasses values instead of only ever
+ * running inside a live recording session.
+ */
+export declare function allocatePassQueryIndices(nextQueryIndex: number, maxPasses: number): {
+    beginningOfPassWriteIndex: number;
+    endOfPassWriteIndex: number;
+    nextQueryIndex: number;
+} | null;
+/**
+ * Pairs each recorded pass `label` (in recording order) with its
+ * (start, end) nanosecond timestamps at `timestamps[i*2]` /
+ * `timestamps[i*2+1]` — the layout `GpuFrameTimingRecorder` writes via
+ * `timestampWrites`. Pure: given a labels array and a `BigInt64Array`, the
+ * resulting `PassTimingSample[]` is fully determined; no `GPUBuffer`
+ * mapping is involved. Extracted out of `readback()` so this pairing
+ * arithmetic — the part that would silently mis-attribute a duration to
+ * the wrong label on an off-by-one — is checked directly.
+ *
+ * `GpuFrameTimingRecorder.readback()` always calls this with
+ * `timestamps.length === labels.length * 2` (it sizes the readback slice
+ * from the same `nextQueryIndex` cursor that `beginPass` pushed each label
+ * against — see `readback()`'s call site), so a short buffer cannot occur
+ * on that path today. But this function is exported precisely so it can be
+ * exercised standalone, and a caller passing a corrupted or hand-built
+ * buffer must not get back a sample whose `startNs`/`endNs` is `undefined`
+ * where the type says `bigint`: that silently propagates into
+ * `frameTotalMs`/`passDurationsMs` (`frame-timing.ts`), which throws a
+ * `TypeError` mixing `BigInt` and `undefined` for a one-short buffer, or
+ * silently computes `NaN` for a two-short buffer — two different failure
+ * shapes for what is really the same input error, and neither is the
+ * "never throws, never fabricates" contract the rest of this module's
+ * siblings hold themselves to. A label whose (start, end) pair does not
+ * fully fit in `timestamps` is dropped rather than pushed with a missing
+ * field.
+ */
+export declare function pairTimestampsWithLabels(labels: readonly string[], timestamps: BigInt64Array): PassTimingSample[];
+/**
+ * Records GPU timestamp queries for the passes of one frame and resolves
+ * them into `PassTimingSample[]` (nanosecond pairs; see `frame-timing.ts`
+ * for what happens to them next). One instance is good for one frame's
+ * worth of passes up to `maxPasses`, then must be recreated (or reset via
+ * `beginFrame()`) for the next — this keeps the query-set/readback-buffer
+ * lifetime unambiguous rather than trying to make it silently reusable
+ * across frames while a previous frame's readback might still be pending.
+ */
+export declare class GpuFrameTimingRecorder {
+    private readonly maxPasses;
+    private readonly querySet;
+    private readonly resolveBuffer;
+    private readonly readbackBuffer;
+    private labels;
+    private nextQueryIndex;
+    private resolved;
+    private constructor();
+    /**
+     * Returns a recorder, or `null` if the device's adapter did not advertise
+     * `'timestamp-query'` — callers must treat `null` as "cannot measure this
+     * way" and either fall back to CPU-side timing (`decideTimingMode` in
+     * `frame-timing.ts`) or skip measurement, never throw.
+     */
+    static create(device: GPUDevice, maxPasses?: number): GpuFrameTimingRecorder | null;
+    /**
+     * Returns the `timestampWrites` object for the next pass, labelled
+     * `label`. Pass it straight into `beginRenderPass`'s descriptor. Returns
+     * `null` once `maxPasses` passes have been begun this frame — a caller
+     * that hits this should raise `maxPasses` at construction, not retry.
+     */
+    beginPass(label: string): GPURenderPassTimestampWrites | null;
+    /** Resolves every query written this frame into the readback buffer. Call once, after every pass has been `.end()`-ed, before `queue.submit`. */
+    endFrame(encoder: GPUCommandEncoder): void;
+    /**
+     * Maps the readback buffer and returns this frame's `PassTimingSample[]`,
+     * or `null` if `endFrame` was never called (nothing was recorded, or the
+     * caller forgot). Async because `mapAsync` is: the caller's queue submit
+     * must have completed first for the buffer to contain real data — WebGPU
+     * enforces this by making `mapAsync` wait for pending GPU work that
+     * touches the buffer.
+     */
+    readback(): Promise<PassTimingSample[] | null>;
+    /** Resets for the next frame's recording. Does not reallocate the query set or buffers — they are sized once at `create()` and reused. */
+    beginFrame(): void;
+    /** Releases the GPU query set and buffers. Call when timing is turned off. */
+    destroy(): void;
+}
+//# sourceMappingURL=frame-timing-gpu.d.ts.map

package/dist/frame-timing-gpu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-timing-gpu.d.ts","sourceRoot":"","sources":["../src/frame-timing-gpu.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,iNAAiN;AACjN,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE7G;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,GAChB;IAAE,yBAAyB,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOnG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,aAAa,GAAG,gBAAgB,EAAE,CAOjH;AAED;;;;;;;;GAQG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAY;IAC3C,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO;IAOP;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,SAAI,GAAG,sBAAsB,GAAG,IAAI;IAiB9E;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,4BAA4B,GAAG,IAAI;IAY7D,iJAAiJ;IACjJ,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAO1C;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,EAAE,GAAG,IAAI,CAAC;IAUpD,0IAA0I;IAC1I,UAAU,IAAI,IAAI;IAMlB,8EAA8E;IAC9E,OAAO,IAAI,IAAI;CAKhB"}

package/dist/frame-timing-gpu.js

@@ -0,0 +1,176 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/** Feature-detects `'timestamp-query'` on an already-created `GPUDevice`'s adapter features, without touching mode-decision logic (see `decideTimingMode` in `frame-timing.ts`, which consumes this boolean). */
+export function hasTimestampQueryFeature(features) {
+    return features?.has('timestamp-query') ?? false;
+}
+const BYTES_PER_TIMESTAMP = 8; // GPUQuerySet resolves each timestamp query to one 64-bit (BigInt64) value.
+/**
+ * Byte size of the resolve/readback buffers needed for `passCount` passes —
+ * 2 timestamp queries (begin + end) per pass, `BYTES_PER_TIMESTAMP` each.
+ * Pure arithmetic, decidable without a device: extracted out of `create()`
+ * so the sizing formula itself is unit-tested rather than only ever
+ * exercised as a side effect of a real `device.createBuffer` call.
+ */
+export function queryBufferSizeBytes(passCount) {
+    return passCount * 2 * BYTES_PER_TIMESTAMP;
+}
+/**
+ * Allocates the next pair of query-set write indices for one pass, or
+ * `null` if `maxPasses` passes have already been begun this frame. Pure:
+ * given the current cursor and the frame's pass budget, the next
+ * (begin, end, cursor) triple — or exhaustion — is fully determined; no
+ * `GPUQuerySet` is touched to decide it. Extracted out of
+ * `GpuFrameTimingRecorder.beginPass` so this index bookkeeping (the part
+ * most likely to hide an off-by-one — see the exhaustion boundary test) is
+ * checked with synthetic cursor/maxPasses values instead of only ever
+ * running inside a live recording session.
+ */
+export function allocatePassQueryIndices(nextQueryIndex, maxPasses) {
+    if (nextQueryIndex + 1 >= maxPasses * 2)
+        return null;
+    return {
+        beginningOfPassWriteIndex: nextQueryIndex,
+        endOfPassWriteIndex: nextQueryIndex + 1,
+        nextQueryIndex: nextQueryIndex + 2,
+    };
+}
+/**
+ * Pairs each recorded pass `label` (in recording order) with its
+ * (start, end) nanosecond timestamps at `timestamps[i*2]` /
+ * `timestamps[i*2+1]` — the layout `GpuFrameTimingRecorder` writes via
+ * `timestampWrites`. Pure: given a labels array and a `BigInt64Array`, the
+ * resulting `PassTimingSample[]` is fully determined; no `GPUBuffer`
+ * mapping is involved. Extracted out of `readback()` so this pairing
+ * arithmetic — the part that would silently mis-attribute a duration to
+ * the wrong label on an off-by-one — is checked directly.
+ *
+ * `GpuFrameTimingRecorder.readback()` always calls this with
+ * `timestamps.length === labels.length * 2` (it sizes the readback slice
+ * from the same `nextQueryIndex` cursor that `beginPass` pushed each label
+ * against — see `readback()`'s call site), so a short buffer cannot occur
+ * on that path today. But this function is exported precisely so it can be
+ * exercised standalone, and a caller passing a corrupted or hand-built
+ * buffer must not get back a sample whose `startNs`/`endNs` is `undefined`
+ * where the type says `bigint`: that silently propagates into
+ * `frameTotalMs`/`passDurationsMs` (`frame-timing.ts`), which throws a
+ * `TypeError` mixing `BigInt` and `undefined` for a one-short buffer, or
+ * silently computes `NaN` for a two-short buffer — two different failure
+ * shapes for what is really the same input error, and neither is the
+ * "never throws, never fabricates" contract the rest of this module's
+ * siblings hold themselves to. A label whose (start, end) pair does not
+ * fully fit in `timestamps` is dropped rather than pushed with a missing
+ * field.
+ */
+export function pairTimestampsWithLabels(labels, timestamps) {
+    const samples = [];
+    for (let i = 0; i < labels.length; i++) {
+        if (i * 2 + 1 >= timestamps.length)
+            break; // buffer shorter than this (and every later) label needs — stop rather than fabricate a partial pair.
+        samples.push({ label: labels[i], startNs: timestamps[i * 2], endNs: timestamps[i * 2 + 1] });
+    }
+    return samples;
+}
+/**
+ * Records GPU timestamp queries for the passes of one frame and resolves
+ * them into `PassTimingSample[]` (nanosecond pairs; see `frame-timing.ts`
+ * for what happens to them next). One instance is good for one frame's
+ * worth of passes up to `maxPasses`, then must be recreated (or reset via
+ * `beginFrame()`) for the next — this keeps the query-set/readback-buffer
+ * lifetime unambiguous rather than trying to make it silently reusable
+ * across frames while a previous frame's readback might still be pending.
+ */
+export class GpuFrameTimingRecorder {
+    maxPasses;
+    querySet;
+    resolveBuffer;
+    readbackBuffer;
+    labels = [];
+    nextQueryIndex = 0;
+    resolved = false;
+    constructor(maxPasses, querySet, resolveBuffer, readbackBuffer) {
+        this.maxPasses = maxPasses;
+        this.querySet = querySet;
+        this.resolveBuffer = resolveBuffer;
+        this.readbackBuffer = readbackBuffer;
+    }
+    /**
+     * Returns a recorder, or `null` if the device's adapter did not advertise
+     * `'timestamp-query'` — callers must treat `null` as "cannot measure this
+     * way" and either fall back to CPU-side timing (`decideTimingMode` in
+     * `frame-timing.ts`) or skip measurement, never throw.
+     */
+    static create(device, maxPasses = 8) {
+        if (!hasTimestampQueryFeature(device.features))
+            return null;
+        const querySet = device.createQuerySet({ type: 'timestamp', count: maxPasses * 2, label: 'frame-timing-queries' });
+        const resolveBuffer = device.createBuffer({
+            size: queryBufferSizeBytes(maxPasses),
+            usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
+            label: 'frame-timing-resolve',
+        });
+        const readbackBuffer = device.createBuffer({
+            size: queryBufferSizeBytes(maxPasses),
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+            label: 'frame-timing-readback',
+        });
+        return new GpuFrameTimingRecorder(maxPasses, querySet, resolveBuffer, readbackBuffer);
+    }
+    /**
+     * Returns the `timestampWrites` object for the next pass, labelled
+     * `label`. Pass it straight into `beginRenderPass`'s descriptor. Returns
+     * `null` once `maxPasses` passes have been begun this frame — a caller
+     * that hits this should raise `maxPasses` at construction, not retry.
+     */
+    beginPass(label) {
+        const allocation = allocatePassQueryIndices(this.nextQueryIndex, this.maxPasses);
+        if (allocation === null)
+            return null;
+        this.nextQueryIndex = allocation.nextQueryIndex;
+        this.labels.push(label);
+        return {
+            querySet: this.querySet,
+            beginningOfPassWriteIndex: allocation.beginningOfPassWriteIndex,
+            endOfPassWriteIndex: allocation.endOfPassWriteIndex,
+        };
+    }
+    /** Resolves every query written this frame into the readback buffer. Call once, after every pass has been `.end()`-ed, before `queue.submit`. */
+    endFrame(encoder) {
+        if (this.nextQueryIndex === 0)
+            return; // no passes recorded — nothing to resolve
+        encoder.resolveQuerySet(this.querySet, 0, this.nextQueryIndex, this.resolveBuffer, 0);
+        encoder.copyBufferToBuffer(this.resolveBuffer, 0, this.readbackBuffer, 0, this.nextQueryIndex * BYTES_PER_TIMESTAMP);
+        this.resolved = true;
+    }
+    /**
+     * Maps the readback buffer and returns this frame's `PassTimingSample[]`,
+     * or `null` if `endFrame` was never called (nothing was recorded, or the
+     * caller forgot). Async because `mapAsync` is: the caller's queue submit
+     * must have completed first for the buffer to contain real data — WebGPU
+     * enforces this by making `mapAsync` wait for pending GPU work that
+     * touches the buffer.
+     */
+    async readback() {
+        if (!this.resolved)
+            return null;
+        await this.readbackBuffer.mapAsync(GPUMapMode.READ);
+        const raw = this.readbackBuffer.getMappedRange(0, this.nextQueryIndex * BYTES_PER_TIMESTAMP);
+        const timestamps = new BigInt64Array(raw.slice(0)); // copy out before unmap invalidates the ArrayBuffer
+        this.readbackBuffer.unmap();
+        return pairTimestampsWithLabels(this.labels, timestamps);
+    }
+    /** Resets for the next frame's recording. Does not reallocate the query set or buffers — they are sized once at `create()` and reused. */
+    beginFrame() {
+        this.labels = [];
+        this.nextQueryIndex = 0;
+        this.resolved = false;
+    }
+    /** Releases the GPU query set and buffers. Call when timing is turned off. */
+    destroy() {
+        this.querySet.destroy();
+        this.resolveBuffer.destroy();
+        this.readbackBuffer.destroy();
+    }
+}
+//# sourceMappingURL=frame-timing-gpu.js.map

package/dist/frame-timing-gpu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-timing-gpu.js","sourceRoot":"","sources":["../src/frame-timing-gpu.ts"],"names":[],"mappings":"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"}

package/dist/frame-timing-stats.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Pure statistics for frame/pass GPU timing (issue #2670 perf-verdict gate).
+ *
+ * Everything in this file is arithmetic over plain numbers/bigints — no
+ * `GPUQuerySet`, no `performance.now()`, nothing that touches a clock or a
+ * device. That split is deliberate: the thin GPU-facing code in
+ * `frame-timing-gpu.ts` cannot be exercised without a WebGPU adapter with the
+ * `timestamp-query` feature (which this environment's Chromium does not
+ * expose — `navigator.gpu` itself is absent), so every number it produces is
+ * pushed through here, where it CAN be tested with synthetic values.
+ */
+/**
+ * Summary statistics over a sample of frame or pass durations, in
+ * milliseconds.
+ *
+ * A mean hides exactly the stutter a perf verdict cares about — one frame
+ * that spikes to 40 ms among fifty at 8 ms barely moves a mean, but it is
+ * the one a user notices. `p95` (and `max`, its worst case) are the
+ * statistics this module treats as the headline; `mean` and `median` are
+ * kept for context, not as the number to gate on.
+ *
+ * `count === 0` is the explicit empty-sample marker: every other field is
+ * `null` rather than `0`, because a real all-zero sample and "nothing was
+ * measured" must never be indistinguishable to a caller reading this object.
+ */
+export interface DurationStats {
+    /** Number of samples the statistics below were computed over. */
+    count: number;
+    min: number | null;
+    /** 50th percentile (nearest-rank on the sorted sample). */
+    median: number | null;
+    /** 95th percentile (nearest-rank on the sorted sample) — see class doc. */
+    p95: number | null;
+    max: number | null;
+    /** Arithmetic mean. Context only — do not gate a perf verdict on this. */
+    mean: number | null;
+}
+/**
+ * WebGPU timestamp queries resolve to nanoseconds (`BigInt64Array` values
+ * read back from the resolve buffer). The renderer's budgets and every other
+ * timing surface in this codebase (`FrameStats.timestamp` via
+ * `performance.now()`) are in milliseconds, so every raw pair gets converted
+ * through this one function.
+ *
+ * Takes `bigint` (the actual readback type) so a caller cannot accidentally
+ * pass an already-lossy `Number(timestamp)` of a value that may exceed
+ * `Number.MAX_SAFE_INTEGER` (a query set can hold timestamps for a
+ * long-running session; ~104 days of nanoseconds overflows a JS number).
+ * The subtraction happens in `bigint` space and only the final, small
+ * (sub-second, in practice sub-100ms) millisecond duration is converted to
+ * `number`.
+ *
+ * Clamps a negative delta (`endNs < startNs`) to `0` rather than returning
+ * a physically impossible negative duration. This is reachable: GPU
+ * timestamps are not guaranteed monotonic across a device reset (see this
+ * module's own doc above). `0` is the honest floor — a duration cannot be
+ * negative, and unlike a raw negative number it cannot silently drag a
+ * `min`/`mean` computed downstream into nonsense. This is the guard's one
+ * choke point: `frameTotalMs`/`passDurationsMs` (`frame-timing.ts`) sum
+ * this function's output directly, without ever routing it through
+ * `computeDurationStats`, so a guard placed only in `computeDurationStats`
+ * would miss that summation entirely. Use `isNegativeDelta` alongside this
+ * function where the caller wants to know a clamp happened.
+ */
+export declare function nsToMs(startNs: bigint, endNs: bigint): number;
+/**
+ * Reports whether `(startNs, endNs)` is a monotonicity violation (`endNs <
+ * startNs`) — the only case the module's own doc calls out as reachable:
+ * GPU timestamps "are not guaranteed monotonic across a device reset".
+ *
+ * This is the guard's true origin point: `nsToMs` alone cannot both return a
+ * single honest millisecond number for every downstream summation (see
+ * `frameTotalMs`/`passDurationsMs` in `frame-timing.ts`, which add its
+ * output directly into a running total and never pass through
+ * `computeDurationStats`) AND separately expose "this one was bad" — a
+ * plain `number` return has no second channel for that. Callers that want
+ * to surface an invalid-sample count (rather than let a clamped-to-0 value
+ * pass as an unremarkable real zero) call this predicate on the same raw
+ * pair alongside `nsToMs`. `computeDurationStats` is deliberately NOT where
+ * this lives: by the time a caller has an array of plain millisecond
+ * numbers, it has no way to tell a clamped GPU-reset zero apart from a
+ * genuine fast pass or a CPU-fallback delta (which is never negative — it
+ * comes from `performance.now()`, spec-guaranteed non-decreasing) — see
+ * that function's doc.
+ */
+export declare function isNegativeDelta(startNs: bigint, endNs: bigint): boolean;
+/**
+ * Reduces a sample of durations (milliseconds) to summary statistics. Pure:
+ * no side effects, no clock reads — the durations are supplied by the
+ * caller, whether they came from GPU timestamp queries or the CPU
+ * frame-delta fallback (see `frame-timing.ts`).
+ *
+ * `durationsMs.length === 0` returns `EMPTY_STATS` (`count: 0`, every other
+ * field `null`) rather than computing `0`s — a percentile or a mean over an
+ * empty array is either `NaN` (misreported as a real "instant" frame) or a
+ * divide-by-zero, and either would read as "this was fast" instead of "this
+ * was never measured".
+ */
+export declare function computeDurationStats(durationsMs: readonly number[]): DurationStats;
+//# sourceMappingURL=frame-timing-stats.d.ts.map

package/dist/frame-timing-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-timing-stats.d.ts","sourceRoot":"","sources":["../src/frame-timing-stats.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvE;AAeD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAclF"}

package/dist/frame-timing-stats.js

@@ -0,0 +1,116 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * The one empty-sample result, handed back BY REFERENCE to every caller of
+ * `computeDurationStats([])`. Frozen for exactly that reason: an unfrozen
+ * shared constant lets one caller's in-place edit (e.g. patching the nulls to
+ * zeros for its own display code) rewrite what every LATER empty result
+ * reports, turning an honest "nothing was measured" into a fabricated number
+ * process-wide. Frozen, such a write is a no-op — a `TypeError` under the
+ * strict mode every ES module runs in — and the constant stays honest.
+ */
+const EMPTY_STATS = Object.freeze({
+    count: 0,
+    min: null,
+    median: null,
+    p95: null,
+    max: null,
+    mean: null,
+});
+/**
+ * WebGPU timestamp queries resolve to nanoseconds (`BigInt64Array` values
+ * read back from the resolve buffer). The renderer's budgets and every other
+ * timing surface in this codebase (`FrameStats.timestamp` via
+ * `performance.now()`) are in milliseconds, so every raw pair gets converted
+ * through this one function.
+ *
+ * Takes `bigint` (the actual readback type) so a caller cannot accidentally
+ * pass an already-lossy `Number(timestamp)` of a value that may exceed
+ * `Number.MAX_SAFE_INTEGER` (a query set can hold timestamps for a
+ * long-running session; ~104 days of nanoseconds overflows a JS number).
+ * The subtraction happens in `bigint` space and only the final, small
+ * (sub-second, in practice sub-100ms) millisecond duration is converted to
+ * `number`.
+ *
+ * Clamps a negative delta (`endNs < startNs`) to `0` rather than returning
+ * a physically impossible negative duration. This is reachable: GPU
+ * timestamps are not guaranteed monotonic across a device reset (see this
+ * module's own doc above). `0` is the honest floor — a duration cannot be
+ * negative, and unlike a raw negative number it cannot silently drag a
+ * `min`/`mean` computed downstream into nonsense. This is the guard's one
+ * choke point: `frameTotalMs`/`passDurationsMs` (`frame-timing.ts`) sum
+ * this function's output directly, without ever routing it through
+ * `computeDurationStats`, so a guard placed only in `computeDurationStats`
+ * would miss that summation entirely. Use `isNegativeDelta` alongside this
+ * function where the caller wants to know a clamp happened.
+ */
+export function nsToMs(startNs, endNs) {
+    const deltaNs = endNs - startNs;
+    if (deltaNs < 0n)
+        return 0;
+    return Number(deltaNs) / 1_000_000;
+}
+/**
+ * Reports whether `(startNs, endNs)` is a monotonicity violation (`endNs <
+ * startNs`) — the only case the module's own doc calls out as reachable:
+ * GPU timestamps "are not guaranteed monotonic across a device reset".
+ *
+ * This is the guard's true origin point: `nsToMs` alone cannot both return a
+ * single honest millisecond number for every downstream summation (see
+ * `frameTotalMs`/`passDurationsMs` in `frame-timing.ts`, which add its
+ * output directly into a running total and never pass through
+ * `computeDurationStats`) AND separately expose "this one was bad" — a
+ * plain `number` return has no second channel for that. Callers that want
+ * to surface an invalid-sample count (rather than let a clamped-to-0 value
+ * pass as an unremarkable real zero) call this predicate on the same raw
+ * pair alongside `nsToMs`. `computeDurationStats` is deliberately NOT where
+ * this lives: by the time a caller has an array of plain millisecond
+ * numbers, it has no way to tell a clamped GPU-reset zero apart from a
+ * genuine fast pass or a CPU-fallback delta (which is never negative — it
+ * comes from `performance.now()`, spec-guaranteed non-decreasing) — see
+ * that function's doc.
+ */
+export function isNegativeDelta(startNs, endNs) {
+    return endNs - startNs < 0n;
+}
+/**
+ * Nearest-rank percentile over `sorted` (must already be sorted ascending).
+ * `p` is a fraction in `[0, 1]`. Rounds the rank rather than interpolating —
+ * cheap, deterministic, and matches how `p95`/`median` are colloquially read
+ * off a sorted sample in perf work.
+ */
+function percentile(sorted, p) {
+    if (sorted.length === 1)
+        return sorted[0];
+    const rank = Math.ceil(p * sorted.length) - 1;
+    const clamped = Math.min(Math.max(rank, 0), sorted.length - 1);
+    return sorted[clamped];
+}
+/**
+ * Reduces a sample of durations (milliseconds) to summary statistics. Pure:
+ * no side effects, no clock reads — the durations are supplied by the
+ * caller, whether they came from GPU timestamp queries or the CPU
+ * frame-delta fallback (see `frame-timing.ts`).
+ *
+ * `durationsMs.length === 0` returns `EMPTY_STATS` (`count: 0`, every other
+ * field `null`) rather than computing `0`s — a percentile or a mean over an
+ * empty array is either `NaN` (misreported as a real "instant" frame) or a
+ * divide-by-zero, and either would read as "this was fast" instead of "this
+ * was never measured".
+ */
+export function computeDurationStats(durationsMs) {
+    if (durationsMs.length === 0)
+        return EMPTY_STATS;
+    const sorted = [...durationsMs].sort((a, b) => a - b);
+    const sum = sorted.reduce((acc, v) => acc + v, 0);
+    return {
+        count: sorted.length,
+        min: sorted[0],
+        median: percentile(sorted, 0.5),
+        p95: percentile(sorted, 0.95),
+        max: sorted[sorted.length - 1],
+        mean: sum / sorted.length,
+    };
+}
+//# sourceMappingURL=frame-timing-stats.js.map

package/dist/frame-timing-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-timing-stats.js","sourceRoot":"","sources":["../src/frame-timing-stats.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAyC/D;;;;;;;;GAQG;AACH,MAAM,WAAW,GAAkB,MAAM,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC;IACR,GAAG,EAAE,IAAI;IACT,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,IAAI,EAAE,IAAI;CACX,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,MAAM,CAAC,OAAe,EAAE,KAAa;IACnD,MAAM,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAChC,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,KAAa;IAC5D,OAAO,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,MAAyB,EAAE,CAAS;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAA8B;IACjE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,WAAW,CAAC;IAEjD,MAAM,MAAM,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAElD,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,MAAM;QACpB,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QACd,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC;QAC/B,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC;QAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QAC9B,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM;KAC1B,CAAC;AACJ,CAAC"}