@woosh/meep-engine 3.14.5 → 3.14.6

package/src/shade/renderer/particles/shaders/shader_particle_simulate.js

@@ -7,6 +7,8 @@ import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourc
 import {
     PARTICLE_RECORD_HEADER_EMITTER,
     PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    PARTICLE_SIM_PAD_SLOT,
     PARTICLE_VM_INSTRUCTION_WORDS,
 } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
@@ -15,18 +17,37 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
 /**
  * The particle simulate pass — Destiny-style single execution shader.
  *
- * One dispatch processes the entire alive list across every emitter. Per particle: read its owning
+ * One dispatch processes every live particle across every emitter. Per particle: read its owning
  * emitter, set up the VM context + RNG, run that emitter's compiled UPDATE program over the record,
  * then compact — killed particles are pushed back to the dead (free) list, survivors are appended to
  * the new alive list. There is exactly one pipeline regardless of how many distinct effects exist,
  * because behaviour is data (the bytecode program), not code.
  *
- * The input length is read from `counters[ALIVE_IN]` — the previous frame's final alive count,
- * snapshotted on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count
- * is inevitably stale (readback latency) and corrupts the pool: under-counting orphans the tail of
- * the alive list (slots leak into limbo), over-counting re-simulates stale entries and double-frees
- * their slots. Dispatch this shader with `dispatchWorkgroupsIndirect` using the args the
- * build-indirect pass wrote last frame, so thread count and bound agree by construction.
+ * ## The input list
+ *
+ * `sim_list` is NOT the raw alive list. It is the program-coherent indirection list the coherence
+ * pass (`../coherence/`) built at the end of last frame: the same pool slots, reordered so that
+ * particles running one VM program sit together, each run padded out to a whole workgroup. That is
+ * what keeps a wave from spanning two programs, which would make the interpreter's opcode `switch`
+ * diverge and multiply the register file's `v_movrels` waterfall by the number of distinct register
+ * indices in the wave.
+ *
+ * Padding entries carry {@link PARTICLE_SIM_PAD_SLOT} and are dropped BEFORE the compaction
+ * atomics, so a padding lane never appends to the alive list and never pushes a slot onto the free
+ * list — pushing the sentinel would put `0xffffffff` on the free list for a later emit to hand out
+ * as a record base. Returning early is safe for the lanes that remain: padding only ever appears in
+ * the tail of a bucket, and every real lane in that wave belongs to that one bucket, so the `switch`
+ * the survivors execute is uniform regardless.
+ *
+ * ## Sizing
+ *
+ * The input length is read from `counters[ALIVE_IN]` — the padded length of that list, snapshotted
+ * on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count is inevitably
+ * stale (readback latency) and corrupts the pool: under-counting orphans the tail of the list (slots
+ * leak into limbo), over-counting re-simulates stale entries and double-frees their slots. Dispatch
+ * this shader with `dispatchWorkgroupsIndirect` using the args the build-indirect pass wrote last
+ * frame from that same value, so thread count and bound agree by construction — and, because the
+ * padded length is a whole number of workgroups, agree exactly.
  *
  * All structured reads go through `array<u32>` for emulator-testability. Curve sampling uses the
  * pluggable `particle_vm_sample_curve` — here the no-op provider; the feature swaps in the
@@ -35,7 +56,7 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
  * @type {ComputeShader}
  */
 
-export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE };
 
 /**
  * Per-dispatch, 12 bytes, read-only — see shader_particle_emit for why the three travel
@@ -58,7 +79,7 @@ resources.createGroup()
     .addStorageBuffer("program", WebGPUArray.u32, false)
     .addStorageBuffer("vm_constants", WebGPUArray.u32, false)
     .addStorageBuffer("pool", WebGPUArray.u32, true)
-    .addStorageBuffer("alive_in", WebGPUArray.u32, false)
+    .addStorageBuffer("sim_list", WebGPUArray.u32, false)
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
     .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
@@ -71,14 +92,22 @@ const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
 const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
 const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
 const COUNTER_ALIVE_IN : u32 = ${PARTICLE_COUNTER.ALIVE_IN}u;
+const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
 
 @compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
-    // The exact alive-list length, snapshotted on-GPU last frame — never a stale CPU value.
+    // The exact input length, snapshotted on-GPU last frame — never a stale CPU value.
     if (i >= atomicLoad(&counters[COUNTER_ALIVE_IN])) { return; }
 
-    let slot = alive_in[i];
+    let slot = sim_list[i];
+
+    // A lane the coherence pass padded the bucket out with. Leave BEFORE the compaction atomics
+    // below: appending here would put the sentinel on the alive or the free list, and the free list
+    // would then hand 0xffffffff to an emit as a record base. The lanes that stay all belong to the
+    // one bucket this wave covers, so their program — and the interpreter's switch — is uniform.
+    if (slot == PARTICLE_SIM_PAD_SLOT) { return; }
+
     let record_base = slot * PARTICLE_RECORD_WORDS;
     let emitter_index = pool[record_base + PARTICLE_HEADER_EMITTER];
 

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts

@@ -1,23 +1,12 @@
+export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
 /**
- * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
- *
- * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
- *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
- *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
- *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
- * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
- *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
- *    `keys`, and atomically bump the per-bucket `histogram`.
- * 2. graph_prefix_scan_csdldf turns the histogram into inclusive prefix sums.
- * 3. {@link shader_particle_sort_scatter} — per particle, read its bucket, take the exclusive
- *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
- *    into `sorted` at that position.
+ * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count)` threads, not over
+ * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
+ * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
+ * and the scan adds them in.
  *
- * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
- * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
- * algorithm.
+ * @type {ComputeShader}
  */
-export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
 export const shader_particle_sort_reset: ComputeShader;
 export const shader_particle_sort_histogram: ComputeShader;
 export const shader_particle_sort_scatter: ComputeShader;

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8CAA+C;AAkC/C,uDAIG;AAyEH,2DAIG;AAqCH,yDAIG;8BAvL2B,+BAA+B"}
+{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAsDA,8CAA+C;AAgD/C;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;AA0EH,2DAIG;AAyCH,yDAIG;8BA1O2B,+BAA+B"}

package/src/shade/renderer/particles/sort/shader_particle_sort.js

@@ -4,6 +4,7 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
 import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
 import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_LAYOUT.js";
 import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
@@ -11,10 +12,11 @@ import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
 /**
  * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
  *
- * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
- *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
- *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
- *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
+ * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count, elements}`
+ *    header (the bucket count the csdldf scan sizes itself from), clear the header padding and the
+ *    bins, and zero the scatter cursor. Without this the scan consumes garbage counts and the
+ *    scatter compounds last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not
+ *    per frame.
  * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
  *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
  *    `keys`, and atomically bump the per-bucket `histogram`.
@@ -23,11 +25,33 @@ import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
  *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
  *    into `sorted` at that position.
  *
+ * ## The buffer the four passes share
+ *
+ * The histogram IS the scan's `{count: u32, elements: array<vec4u>}`, bound flat here as
+ * `array<atomic<u32>>` because these passes need atomics on it. `elements` is `@align(16)`, so bin
+ * `b` is word {@link PREFIX_SCAN_CSDLDF_HEADER_WORDS}` + b` and words 1..3 are padding the scan
+ * never reads. Every pass below steps over that header by hand; the reset clears whole vec4s of
+ * bins, because whole vec4s is what the scan loads.
+ *
+ * ## This is the render order
+ *
+ * The camera-dependent back-to-front list the billboard draw consumes. `../coherence/` produces the
+ * simulation order from the same three-phase shape — different buffers, different passes, different
+ * counter slots (`PARTICLE_COUNTER.SORTED` against `PARTICLE_COUNTER.SIM_PADDED`), on purpose.
+ *
  * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
  * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
  * algorithm.
  */
 
+/** @type {number} words of `{count, elements}` header in front of the scan's bins */
+const HEADER = PREFIX_SCAN_CSDLDF_HEADER_WORDS;
+
+/** The header stride every pass in this file interpolates. */
+const COMMON = /* wgsl */ `
+const SORT_HEADER_WORDS : u32 = ${HEADER}u;
+`;
+
 export const PARTICLE_SORT_WORKGROUP_SIZE = 64;
 
 // --- reset pass ---
@@ -48,20 +72,42 @@ reset_resources.createGroup()
     .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
     .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true);
 const reset_body = CodeChunk.from(/* wgsl */ `
+${COMMON}
+
 @compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
+
     if (i == 0u) {
         // The {count, elements} header the csdldf scan sizes itself from.
         atomicStore(&histogram[0], settings.u_bucket_count);
     }
+
+    // Header padding: never read by the scan, but it shares the buffer and the pool may have left
+    // something in it.
+    if (i > 0u && i < SORT_HEADER_WORDS) {
+        atomicStore(&histogram[i], 0u);
+    }
+
+    // The scan reads whole vec4s, so the bins are cleared up to the vec4 the last one lands in.
+    if (i < ((settings.u_bucket_count + 3u) & 0xfffffffcu)) {
+        atomicStore(&histogram[SORT_HEADER_WORDS + i], 0u);
+    }
+
     if (i < settings.u_bucket_count) {
-        atomicStore(&histogram[1u + i], 0u);
         atomicStore(&cursor[i], 0u);
     }
 }
 `);
 
+/**
+ * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count)` threads, not over
+ * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
+ * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
+ * and the scan adds them in.
+ *
+ * @type {ComputeShader}
+ */
 export const shader_particle_sort_reset = ComputeShader.from({
     label: "Particle Sort Reset",
     resources: reset_resources,
@@ -105,6 +151,7 @@ histogram_resources.createGroup()
     .addStorageBuffer("keys", WebGPUArray.u32, true)
     .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true);
 const histogram_body = CodeChunk.from(/* wgsl */ `
+${COMMON}
 const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
 const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
 const PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
@@ -135,7 +182,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let bucket = min(u32(clamped * f32(settings.u_bucket_count)), settings.u_bucket_count - 1u);
 
     keys[i] = bucket;
-    atomicAdd(&histogram[1u + bucket], 1u);
+    atomicAdd(&histogram[SORT_HEADER_WORDS + bucket], 1u);
 }
 `, [chunk_particle_emitter]);
 
@@ -166,15 +213,19 @@ scatter_resources.createGroup()
     .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
     .addStorageBuffer("sorted", WebGPUArray.u32, true);
 const scatter_body = CodeChunk.from(/* wgsl */ `
+${COMMON}
+
 @compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
     if (i >= settings.u_count) { return; }
 
     let bucket = keys[i];
-    // Exclusive offset = inclusive prefix sum up to bucket-1. With the count field at index 0 the
-    // scanned inclusive value for bucket b lives at index (1+b), so bucket b-1 is at index b.
-    let exclusive = select(0u, scanned[bucket], bucket > 0u);
+
+    // The scan is inclusive, so bucket b's exclusive offset is bucket b-1's inclusive value, one
+    // word earlier. For bucket 0 the index lands on the last header word — in bounds, and unused,
+    // because select() takes the 0 branch there.
+    let exclusive = select(0u, scanned[SORT_HEADER_WORDS + bucket - 1u], bucket > 0u);
     let rank = atomicAdd(&cursor[bucket], 1u);
     sorted[exclusive + rank] = alive[i];
 }

package/src/shade/wgsl/emulator/CPUBitmapData.d.ts

@@ -139,7 +139,7 @@ export class CPUBitmapData {
      * to decide what `textureDimensions` should return.
      * @returns {1 | 2 | 3}
      */
-    get dimensionality(): 2 | 1 | 3;
+    get dimensionality(): 1 | 2 | 3;
     /**
      * Linear element index of the first channel of pixel `(x, y, z)`.
      * Caller is responsible for bounds checking.

package/src/view/DOM.d.ts

@@ -0,0 +1,69 @@
+export default domify;
+export function DOM(argument: any, namespace: any): this;
+export class DOM {
+    constructor(argument: any, namespace: any);
+    /**
+     *
+     * @type {Element}
+     */
+    el: Element;
+    /**
+     *
+     * @param {string} [elName=div]
+     * @returns {DOM}
+     */
+    createChild(elName?: string): DOM;
+    append(child: any): this;
+    remove(child: any): this;
+    text(text: any): this;
+    /**
+     *
+     * @param {string} querySelector
+     * @returns {DOM|null}
+     */
+    select(querySelector: string): DOM | null;
+    /**
+     *
+     * @param {string} name
+     * @returns {DOM}
+     */
+    addClass(name: string): DOM;
+    removeClass(name: any): this;
+    /**
+     *
+     * @param {string} name
+     * @param {boolean} flag
+     * @returns {DOM}
+     */
+    setClass(name: string, flag: boolean): DOM;
+    css(hash: any): this;
+    attr(hash: any): this;
+    clone(): DOM;
+    /**
+     * removes all children
+     * @returns {DOM}
+     */
+    clear(): DOM;
+    /**
+     *
+     * @param eventName
+     * @param handler
+     * @returns {DOM}
+     */
+    on(eventName: any, handler: any): DOM;
+    /**
+     *
+     * @param eventName
+     * @param handler
+     * @returns {DOM}
+     */
+    off(eventName: any, handler: any): DOM;
+}
+/**
+ *
+ * @param {String|Element} [x=div]
+ * @param {String} [namespace]
+ * @returns {DOM}
+ */
+declare function domify(x?: string | Element, namespace?: string): DOM;
+//# sourceMappingURL=DOM.d.ts.map

package/src/view/DOM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DOM.d.ts","sourceRoot":"","sources":["../../../src/view/DOM.js"],"names":[],"mappings":";AACA,yDAoBC;;IApBD,2CAoBC;IANG;;;OAGG;IACH,IAFU,OAAO,CAEL;IAIhB;;;;OAIG;IACH,qBAHW,MAAM,GACJ,GAAG,CAMf;IAaD,yBAIC;IACD,yBAIC;IAED,sBAGC;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,GAAG,GAAC,IAAI,CAUpB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,GAAG,CAKf;IAED,6BAGC;IAED;;;;;OAKG;IACH,eAJW,MAAM,QACN,OAAO,GACL,GAAG,CAMf;IAED,qBAOC;IAED,sBAQC;IAED,aAEC;IAED;;;OAGG;IACH,SAFa,GAAG,CAQf;IAED;;;;;OAKG;IACH,kCAFa,GAAG,CAMf;IACD;;;;;OAKG;IACH,mCAFa,GAAG,CAMf;;AAED;;;;;GAKG;AACH,4BAJW,SAAO,OAAO,uBAEZ,GAAG,CAIf"}

package/src/view/DOM.js

@@ -1,5 +1,5 @@
 
-const DOM = function (argument, namespace) {
+function DOM(argument, namespace) {
     let el;
     if (typeof argument === "string") {
         if (namespace === undefined) {
@@ -169,4 +169,5 @@ function domify(x, namespace) {
     return new DOM(x, namespace);
 }
 
+export { DOM };
 export default domify;

package/src/view/common/LocalizedLabelView.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @extends View
+ */
+export class LocalizedLabelView extends View {
+    /**
+     *
+     * @param {string} id
+     * @param {object} [seed]
+     * @param {Localization} [localization]
+     * @param {string[]} [classList]
+     * @param {GMLEngine} [gml] if supplied, string will be compiled first
+     * @param {string} [tag=div] HTML element tag
+     */
+    constructor({ id, seed, localization, classList, gml, tag }: string);
+    /**
+     * @private
+     * @type {Localization}
+     */
+    private localization;
+    /**
+     *
+     * @type {GMLEngine}
+     */
+    gml: GMLEngine;
+    /**
+     *
+     * @type {Object}
+     */
+    seed: any;
+    /**
+     *
+     * @type {string}
+     */
+    key: string;
+    $el: import("../DOM.js").DOM;
+    el: Element;
+    needsUpdate: boolean;
+    /**
+     * Cached locale key
+     * @type {String}
+     * @private
+     */
+    private __localeKey;
+    updateLocale(): void;
+    setLocalization(localization: any): void;
+    setKey(key: any): void;
+    update(): void;
+}
+import View from "../View.js";
+//# sourceMappingURL=LocalizedLabelView.d.ts.map

package/src/view/common/LocalizedLabelView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalizedLabelView.d.ts","sourceRoot":"","sources":["../../../../src/view/common/LocalizedLabelView.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IACI;;;;;;;;OAQG;IACH,6DAPW,MAAM,EAoEhB;IAxDG;;;OAGG;IACH,qBAAwB;IAExB;;;OAGG;IACH,eAAc;IAEd;;;OAGG;IACH,UAAgB;IAEhB;;;OAGG;IACH,KAFU,MAAM,CAEH;IAKb,6BAAc;IAEd,YAAgB;IAKhB,qBAAuB;IAavB;;;;OAIG;IACH,oBAAuB;IAM3B,qBAOC;IAED,yCAeC;IAED,uBAaC;IAED,eAgCC;CACJ;iBAxJgB,YAAY"}

package/src/view/controller/controls/GuiControl.d.ts

@@ -0,0 +1,19 @@
+export default GuiControl;
+declare class GuiControl extends View {
+    dRoot: import("../../DOM.js").DOM;
+    el: Element;
+    model: ObservedValue;
+    /**
+     * @template {T}
+     * @param {string} text
+     * @param {T} control
+     * @returns {T}
+     */
+    addLabeledControlVertical(text: string, control: T): T;
+}
+declare namespace GuiControl {
+    let CSS_CLASS_NAME: string;
+}
+import View from '../../View.js';
+import ObservedValue from '../../../core/model/ObservedValue.js';
+//# sourceMappingURL=GuiControl.d.ts.map

package/src/view/controller/controls/GuiControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuiControl.d.ts","sourceRoot":"","sources":["../../../../../src/view/controller/controls/GuiControl.js"],"names":[],"mappings":";AAKA;IAOQ,kCAAkB;IAClB,YAAkB;IAElB,qBAAoC;IAGxC;;;;;OAKG;IACH,gCAJW,MAAM,iBAahB;CACJ;;;;iBA/BgB,eAAe;0BAHN,sCAAsC"}

package/src/view/elements/FrameRateView.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A frame-rate readout: one number, updated twice a second.
+ *
+ * This replaces `stats.js`, which the engine used to pull in for the same job.
+ * That package was declared `optional` in `peerDependenciesMeta` and imported
+ * unconditionally at the top of {@link EngineHarness}, so *evaluating* the
+ * module that is in practice this engine's entry point required an optional
+ * dependency whether or not a counter was ever asked for. Under Vite — where a
+ * consumer must exclude a ~6000-module package from dependency pre-bundling,
+ * which also stops the scanner discovering that package's own CommonJS
+ * dependencies — the result was a module-evaluation failure naming a package
+ * the application had never referenced, and a blank page. Reported from a port
+ * as GAP-003.
+ *
+ * A graph was never the point. The number is.
+ *
+ * The counter binds itself: pass the signal that fires once per rendered frame
+ * and the binding is linked and unlinked with the view, so removing it from the
+ * view stack stops the work.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FrameRateView extends EmptyView {
+    /**
+     * @param {Object} [options]
+     * @param {Signal} [options.frame_signal] fires once per rendered frame;
+     * typically `engine.graphics.on.postRender`. Bound for the lifetime of the
+     * view's link, so it stops counting when the view leaves the stack.
+     */
+    constructor({ frame_signal }?: {
+        frame_signal?: Signal;
+    });
+    /**
+     * Count one frame, and refresh the readout if the window has closed.
+     *
+     * Safe to call directly — a caller driving its own loop can use this
+     * instead of handing a signal to the constructor.
+     */
+    sample(): void;
+    #private;
+}
+export type Signal = import("../../core/events/signal/Signal.js").default;
+import EmptyView from "./EmptyView.js";
+//# sourceMappingURL=FrameRateView.d.ts.map

package/src/view/elements/FrameRateView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FrameRateView.d.ts","sourceRoot":"","sources":["../../../../src/view/elements/FrameRateView.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAiCI;;;;;OAKG;IACH;QAJ4B,YAAY,GAA7B,MAAM;OAuBhB;IAED;;;;;OAKG;IACH,eA0BC;;CACJ;qBA/HY,OAAO,oCAAoC,EAAE,OAAO;sBAH3C,gBAAgB"}

package/src/view/elements/FrameRateView.js

@@ -0,0 +1,131 @@
+import EmptyView from "./EmptyView.js";
+
+/**
+ * @typedef {import("../../core/events/signal/Signal.js").default} Signal
+ */
+
+/**
+ * How long a sample window is. Short enough to react to a stall, long enough
+ * that the number is readable rather than a blur — a per-frame readout is a
+ * counter nobody can actually read.
+ * @type {number}
+ */
+const WINDOW_MILLISECONDS = 500;
+
+/**
+ * A frame-rate readout: one number, updated twice a second.
+ *
+ * This replaces `stats.js`, which the engine used to pull in for the same job.
+ * That package was declared `optional` in `peerDependenciesMeta` and imported
+ * unconditionally at the top of {@link EngineHarness}, so *evaluating* the
+ * module that is in practice this engine's entry point required an optional
+ * dependency whether or not a counter was ever asked for. Under Vite — where a
+ * consumer must exclude a ~6000-module package from dependency pre-bundling,
+ * which also stops the scanner discovering that package's own CommonJS
+ * dependencies — the result was a module-evaluation failure naming a package
+ * the application had never referenced, and a blank page. Reported from a port
+ * as GAP-003.
+ *
+ * A graph was never the point. The number is.
+ *
+ * The counter binds itself: pass the signal that fires once per rendered frame
+ * and the binding is linked and unlinked with the view, so removing it from the
+ * view stack stops the work.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FrameRateView extends EmptyView {
+    /**
+     * Frames counted since the window opened.
+     * @private
+     * @type {number}
+     */
+    #frames = 0;
+
+    /**
+     * When the current window opened, on the same clock the samples are taken
+     * against.
+     * @private
+     * @type {number}
+     */
+    #window_opened = 0;
+
+    /**
+     * Whether a window is open at all. A separate flag rather than a sentinel
+     * value in {@link #window_opened}, because `performance.now()` legitimately
+     * returns 0 on the first call in a fresh context and a zero sentinel would
+     * then re-open the window instead of counting the frame.
+     * @private
+     * @type {boolean}
+     */
+    #counting = false;
+
+    /**
+     * Last value written to the DOM, so an unchanged rate costs no write.
+     * @private
+     * @type {number}
+     */
+    #displayed = -1;
+
+    /**
+     * @param {Object} [options]
+     * @param {Signal} [options.frame_signal] fires once per rendered frame;
+     * typically `engine.graphics.on.postRender`. Bound for the lifetime of the
+     * view's link, so it stops counting when the view leaves the stack.
+     */
+    constructor({ frame_signal } = {}) {
+        super({ classList: ["frame-rate-view"] });
+
+        this.css({
+            position: "absolute",
+            left: 0,
+            top: 0,
+            padding: "2px 6px",
+            font: "12px monospace",
+            color: "#fff",
+            background: "rgba(0,0,0,0.5)",
+            pointerEvents: "none"
+        });
+
+        this.el.textContent = "--";
+
+        if (frame_signal !== undefined) {
+            this.bindSignal(frame_signal, this.sample, this);
+        }
+    }
+
+    /**
+     * Count one frame, and refresh the readout if the window has closed.
+     *
+     * Safe to call directly — a caller driving its own loop can use this
+     * instead of handing a signal to the constructor.
+     */
+    sample() {
+        const now = performance.now();
+
+        if (!this.#counting) {
+            this.#counting = true;
+            this.#window_opened = now;
+            return;
+        }
+
+        this.#frames++;
+
+        const elapsed = now - this.#window_opened;
+
+        if (elapsed < WINDOW_MILLISECONDS) {
+            return;
+        }
+
+        const rate = Math.round((this.#frames * 1000) / elapsed);
+
+        if (rate !== this.#displayed) {
+            this.el.textContent = `${rate} FPS`;
+            this.#displayed = rate;
+        }
+
+        this.#frames = 0;
+        this.#window_opened = now;
+    }
+}