@woosh/meep-engine 3.30.0 → 3.31.0

package/src/shade/device/mock/texture_copy.js

@@ -1,5 +1,8 @@
 import { array_buffer_copy } from "../../../core/collection/array/typed/array_buffer_copy.js";
 import { gpu_texture_format_physical_size } from "../../descriptor/texture/format/gpu_texture_format_info.js";
+import {
+    gpu_texture_formats_copy_compatible
+} from "../../descriptor/texture/format/gpu_texture_formats_copy_compatible.js";
 import { COPY_BYTES_PER_ROW_ALIGNMENT } from "../COPY_BYTES_PER_ROW_ALIGNMENT.js";
 
 /**
@@ -200,6 +203,25 @@ function buffer_endpoint_refusal(info, role, required_usage, required_usage_name
         return `${role} rowsPerImage ${info.rowsPerImage} is less than the ${rows} rows a layer of ${extent.height} texels takes`;
     }
 
+    // and the copy has to FIT — the last rule of "validating linear texture data", and the one this
+    // was missing while it had every other. Without it a staging buffer sized from the unpadded row
+    // width encoded cleanly and threw `RangeError: Invalid typed array length` out of the copy at
+    // submit, naming neither endpoint. The buffer-to-buffer path was given the same check for the
+    // same reason; see `SoftwareGPUCommandEncoder#copy_buffer_refusal`.
+    const bytes_per_row = info.bytesPerRow ?? tight_row;
+    const rows_per_image = info.rowsPerImage ?? rows;
+
+    // the trailing padding of the LAST row is not part of the copy, so it is measured tight — a
+    // caller sizing the buffer as `bytesPerRow * rows` is right and must not be refused
+    const required = (rows === 0 || extent.depth === 0)
+        ? 0
+        : bytes_per_row * rows_per_image * (extent.depth - 1) + bytes_per_row * (rows - 1) + tight_row;
+
+    if (offset + required > buffer.size) {
+        return `${role} buffer '${buffer.label}' of size ${buffer.size} cannot hold the ${required} bytes`
+            + ` the copy needs at offset ${offset}`;
+    }
+
     return null;
 }
 
@@ -264,8 +286,20 @@ export function texture_copy_refusal({ texture_source, buffer_source, texture_de
     }
 
     if (texture_source !== undefined && texture_destination !== undefined) {
-        if (texture_source.texture.format !== texture_destination.texture.format) {
-            return `source is ${texture_source.texture.format} and destination is ${texture_destination.texture.format}; a texture copy cannot change format`;
+        const source_format = texture_source.texture.format;
+        const destination_format = texture_destination.texture.format;
+
+        /*
+         Copy-compatible rather than equal, which is WebGPU's rule: a copy may add or drop -srgb,
+         because the two halves of such a pair store the same bytes and a copy decodes none of them.
+         The mip generator takes an sRGB texture into its linear twin and its levels back out this
+         way, and while this demanded equal formats, the refused copy dropped the whole submission it
+         was encoded into. A difference beyond the suffix is still refused: `bgra8unorm-srgb` and
+         `rgba8unorm` differ in channel order as well.
+        */
+        if (!gpu_texture_formats_copy_compatible(source_format, destination_format)) {
+            return `source is ${source_format} and destination is ${destination_format}; a texture copy`
+                + ` cannot change format beyond adding or dropping -srgb`;
         }
 
         if (texture_source.texture === texture_destination.texture
@@ -349,7 +383,11 @@ function buffer_plane(info, format, extent) {
 export function texture_copy_execute({ texture_source, buffer_source, texture_destination, buffer_destination, size }) {
     const extent = normalize_extent(size);
 
-    // one side is always a texture, and it is the side that knows the format
+    /*
+     One side is always a texture, and it is the side that knows the format. When both are, the
+     source's serves for both: the refusal lets through only copy-compatible formats, which share one
+     block layout, and the rows move as bytes — an -srgb on either end is not decoded or re-encoded.
+    */
     const format = (texture_source ?? texture_destination).texture.format_info;
 
     const source = texture_source !== undefined

package/src/shade/device/mock/texture_view_resource.d.ts

@@ -0,0 +1,26 @@
+/**
+ * WebGPU takes a texture wherever it takes a texture view — a bind group entry, a render pass
+ * attachment — and reads it as the texture's default view, which the spec calls "get as texture
+ * view". These answer for either, so the places that take one do not each spell out both.
+ */
+/**
+ * The texture a view looks into, or the texture itself when one was given in place of a view.
+ *
+ * @param {SoftwareGPUTextureView|SoftwareGPUTexture} resource
+ * @returns {SoftwareGPUTexture|undefined} `undefined` for anything this device did not hand out
+ */
+export function texture_view_resource_texture(resource: SoftwareGPUTextureView | SoftwareGPUTexture): SoftwareGPUTexture | undefined;
+/**
+ * Why a view — or a texture in place of one — cannot be used as `role`, or `null` when it can.
+ *
+ * Only validity is asked here. What each place further requires of the view — a usage, a format, a
+ * dimension — belongs to that place, and this device does not check it. A destroyed texture is not
+ * refused either, because WebGPU does not refuse it until a submission uses it — see
+ * {@link SoftwareGPUCommandBuffer#destroyed_resource}.
+ *
+ * @param {SoftwareGPUTextureView|SoftwareGPUTexture} resource
+ * @param {string} role how the message should name it
+ * @returns {string|null}
+ */
+export function texture_view_resource_refusal(resource: SoftwareGPUTextureView | SoftwareGPUTexture, role: string): string | null;
+//# sourceMappingURL=texture_view_resource.d.ts.map

package/src/shade/device/mock/texture_view_resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_view_resource.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/texture_view_resource.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,wDAHW,2CAAyC,GACvC,qBAAmB,SAAS,CAYxC;AAED;;;;;;;;;;;GAWG;AACH,wDAJW,2CAAyC,QACzC,MAAM,GACJ,MAAM,GAAC,IAAI,CAYvB"}

package/src/shade/device/mock/texture_view_resource.js

@@ -0,0 +1,47 @@
+/**
+ * WebGPU takes a texture wherever it takes a texture view — a bind group entry, a render pass
+ * attachment — and reads it as the texture's default view, which the spec calls "get as texture
+ * view". These answer for either, so the places that take one do not each spell out both.
+ */
+
+/**
+ * The texture a view looks into, or the texture itself when one was given in place of a view.
+ *
+ * @param {SoftwareGPUTextureView|SoftwareGPUTexture} resource
+ * @returns {SoftwareGPUTexture|undefined} `undefined` for anything this device did not hand out
+ */
+export function texture_view_resource_texture(resource) {
+    if (resource?.isSoftwareGPUTextureView === true) {
+        return resource.texture;
+    }
+
+    if (resource?.isSoftwareGPUTexture === true) {
+        return resource;
+    }
+
+    return undefined;
+}
+
+/**
+ * Why a view — or a texture in place of one — cannot be used as `role`, or `null` when it can.
+ *
+ * Only validity is asked here. What each place further requires of the view — a usage, a format, a
+ * dimension — belongs to that place, and this device does not check it. A destroyed texture is not
+ * refused either, because WebGPU does not refuse it until a submission uses it — see
+ * {@link SoftwareGPUCommandBuffer#destroyed_resource}.
+ *
+ * @param {SoftwareGPUTextureView|SoftwareGPUTexture} resource
+ * @param {string} role how the message should name it
+ * @returns {string|null}
+ */
+export function texture_view_resource_refusal(resource, role) {
+    if (resource?.isSoftwareGPUTextureView === true && !resource.isValid) {
+        return `${role} is view '${resource.label}' of texture '${resource.texture.label}', which is invalid`;
+    }
+
+    if (resource?.isSoftwareGPUTexture === true && !resource.isValid) {
+        return `${role} is texture '${resource.label}', which is invalid`;
+    }
+
+    return null;
+}

package/src/shade/device/timing/GPUTimer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUTimer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/GPUTimer.js"],"names":[],"mappings":"AAMA;IAgFI;;;;OAIG;IACH,sCAFW,MAAM,EAehB;IA1FD;;;OAGG;IACH,mBAEC;IA4BD;;;OAGG;IACH,0BAEC;IAUD;;;OAGG;IACH,eAAyB;IAEzB;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,2BAEC;IAsBD,gBAWC;IAuDD;;;OAGG;IACH,cAFa,QAAQ,YAAY,CAAC,CAiBjC;IAED;;;OAGG;IACH,uBAFa,MAAM,CAQlB;IAED;;;OAGG;IACH,0CA0BC;IAED;;;;OAIG;IACH,gBAHW,0CAAwC,GACtC,IAAI,CAchB;IAED;;OAEG;IACH,kDAUC;IAED;;;OAGG;IACH,gDASC;;CACJ;6BA1R4B,mBAAmB;8BAClB,oBAAoB"}
+{"version":3,"file":"GPUTimer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/GPUTimer.js"],"names":[],"mappings":"AAMA;IA4FI;;;;OAIG;IACH,sCAFW,MAAM,EAehB;IAtGD;;;OAGG;IACH,mBAEC;IAwCD;;;OAGG;IACH,0BAEC;IAUD;;;OAGG;IACH,eAAyB;IAEzB;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,2BAEC;IAsBD,gBAaC;IAsDD;;;OAGG;IACH,cAFa,QAAQ,YAAY,CAAC,CAiBjC;IAED;;;OAGG;IACH,uBAFa,MAAM,CAQlB;IAED;;;OAGG;IACH,0CA2BC;IAED;;;;OAIG;IACH,gBAHW,0CAAwC,GACtC,IAAI,CAchB;IAED;;OAEG;IACH,kDAUC;IAED;;;OAGG;IACH,gDASC;;CACJ;6BAxS4B,mBAAmB;8BAClB,oBAAoB"}

package/src/shade/device/timing/GPUTimer.js

@@ -20,8 +20,6 @@ export class GPUTimer {
         return this.#name;
     }
 
-    #result_version = -1;
-    #resolve_version = 0;
 
 
     /**
@@ -36,9 +34,23 @@ export class GPUTimer {
     #resolve_buffer;
 
     /**
+     * Buffers that hold an encoded but unread measurement, oldest first.
+     *
+     * Separate from {@link #free_buffers}, because one list served as both and nothing
+     * distinguished the two halves: `resolve` took a buffer off the front and encoded a fresh copy
+     * into it, so a second `resolve` before a read overwrote the first frame's timings in place —
+     * one measurement reported with a neighbour's duration, and on hardware a copy into a buffer
+     * that may still be mapped.
+     *
+     * @type {GPUBuffer[]}
+     */
+    #pending_buffers = [];
+
+    /**
+     * Buffers that have been read and can carry the next measurement.
      * @type {GPUBuffer[]}
      */
-    #result_buffers = [];
+    #free_buffers = [];
 
     /**
      * How many measurements have we taken so far?
@@ -109,12 +121,14 @@ export class GPUTimer {
         if (this.#query_set !== undefined) {
             this.#query_set.destroy();
             this.#resolve_buffer.destroy();
-            this.#result_buffers.forEach(b => b.destroy());
+            this.#pending_buffers.forEach(b => b.destroy());
+            this.#free_buffers.forEach(b => b.destroy());
         }
 
         this.#query_set = undefined;
         this.#resolve_buffer = undefined;
-        this.#result_buffers = [];
+        this.#pending_buffers = [];
+        this.#free_buffers = [];
     }
 
     #build() {
@@ -141,14 +155,12 @@ export class GPUTimer {
      */
     async #process_result_buffers(buffers) {
         const count = buffers.length;
-        for (let i = 0; i < count; i++) {
 
-            const result_buffer = buffers.pop();
+        // oldest first, so the statistics are recorded in the order they were measured and
+        // `#result_data` ends holding the most recent one rather than the oldest
+        for (let i = 0; i < count; i++) {
 
-            if (result_buffer === undefined) {
-                // no results yet
-                break;
-            }
+            const result_buffer = buffers[i];
 
             await result_buffer.mapAsync(GPUMapMode.READ)
 
@@ -161,7 +173,8 @@ export class GPUTimer {
 
             this.#stats.record(this.#result_data.duration);
 
-            this.#result_buffers.unshift(result_buffer);
+            // back to the free list only now that it has been read and unmapped
+            this.#free_buffers.push(result_buffer);
 
             this.#event_count++;
 
@@ -176,15 +189,15 @@ export class GPUTimer {
      */
     getResults() {
 
-        const results_to_read = this.#resolve_version - this.#result_version;
-
-        if (results_to_read === 0) {
+        // the pending list IS the count of unread measurements, which is what a pair of version
+        // counters was standing in for — and they started one apart, so the first read computed
+        // one too many and `splice` was handed a negative start index, which JS clamps to 0
+        // instead of failing
+        if (this.#pending_buffers.length === 0) {
             return Promise.resolve(this.#result_data);
         }
 
-        this.#result_version = this.#resolve_version;
-
-        const buffers = this.#result_buffers.splice(this.#result_buffers.length - results_to_read, results_to_read);
+        const buffers = this.#pending_buffers.splice(0, this.#pending_buffers.length);
 
         const resolved = this.#process_result_buffers(buffers);
 
@@ -214,7 +227,9 @@ export class GPUTimer {
             return;
         }
 
-        let result_buffer = this.#result_buffers.shift();
+        // a buffer that has been read, or a new one — never one still holding a measurement
+        // nobody has looked at
+        let result_buffer = this.#free_buffers.pop();
 
         if (result_buffer === undefined) {
             result_buffer = this.#device.createBuffer({
@@ -224,7 +239,7 @@ export class GPUTimer {
             });
         }
 
-        this.#result_buffers.push(result_buffer);
+        this.#pending_buffers.push(result_buffer);
 
         encoder.insertDebugMarker(`GPUTimer[${this.#name}] / Resolve`);
 
@@ -232,7 +247,6 @@ export class GPUTimer {
         encoder.copyBufferToBuffer(this.#resolve_buffer, 0, result_buffer, 0, this.#resolve_buffer.size);
 
         // TODO encoded command doesn't mean that it was already executed, so we have to be careful about potential race conditions
-        this.#resolve_version++;
     }
 
     /**

package/src/shade/playground/caldera/caldera_format.d.ts

@@ -32,7 +32,34 @@ export function caldera_read_geometry_table(bytes: ArrayBuffer): {
  * @param {ArrayBuffer} file
  * @returns {{count: number, geometry: Uint32Array, matrices: Float32Array}}
  */
-export function caldera_read_placements(file: ArrayBuffer): {
+/**
+ * The manifest record a geometry's table row names.
+ *
+ * Refuses with a message naming the ROW rather than answering `undefined`, because the caller's
+ * error path used to build its message out of the record it was reporting: an `undefined` here made
+ * `record.file` throw inside the `try` and `record.file` throw AGAIN in the `catch`, and that
+ * second TypeError escaped the worker, rejected its `Promise.all` and marked the whole district
+ * failed. One geometry a stale rebuild could not resolve took every remaining placement in the
+ * district with it, and the console line was about the wrong thing.
+ *
+ * The two tables are written by separate tools and shipped as separate files, so a table row
+ * indexing past the manifest is exactly the inconsistency the refusal count exists to report.
+ *
+ * @param {ArrayLike<{file: string, bytes: number}>} vgeo_records the manifest's `vgeo` array
+ * @param {{vgeo: Uint32Array}} table
+ * @param {number} id geometry id
+ * @returns {{file: string, bytes: number}}
+ */
+export function caldera_vgeo_record(vgeo_records: ArrayLike<{
+    file: string;
+    bytes: number;
+}>, table: {
+    vgeo: Uint32Array;
+}, id: number): {
+    file: string;
+    bytes: number;
+};
+export function caldera_read_placements(file: any): {
     count: number;
     geometry: Uint32Array;
     matrices: Float32Array;

package/src/shade/playground/caldera/caldera_format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"caldera_format.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/caldera/caldera_format.js"],"names":[],"mappings":"AAsFA;;;;;;;;;;;GAWG;AACH,mDALW,WAAW,GACT;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,WAAW,CAAC;IACvF,SAAsB,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAC9E,KAAkB,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAC,CAiCtD;AAGD;;;;;;;;;;GAUG;AACH,8CAHW,WAAW,GACT;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAC,CA2B1E;AAiBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,6CANW,MAAM,EAAE,GAAC,WAAW,GAAC,SAAS,MAAM,CAAC,SACrC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAC,UAC5D,MAAM,cACN,MAAM,GACJ;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAC,EAAE,CAsCvE;AAhPD;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,sCAFU,MAAM,CAE6C;AAE7D;;;;;;;GAOG;AACH;;;;;;;;;;IAYI,6FAA6F;;IAG7F;;;;;;;OAOG;;IAGH;;;;;OAKG;iBAJQ,UAAU,SAAO,MACjB,MAAM,OACN;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAC5F,IAAe,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC;GAoBrE;AAwFH;;;;;;;;;;GAUG;AACH,sCAFU,MAAM,CAEwC"}
+{"version":3,"file":"caldera_format.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/caldera/caldera_format.js"],"names":[],"mappings":"AAsFA;;;;;;;;;;;GAWG;AACH,mDALW,WAAW,GACT;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,WAAW,CAAC;IACvF,SAAsB,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAC9E,KAAkB,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAC,CAiCtD;AAGD;;;;;;;;;;GAUG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,kDALW,UAAU;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC,SACxC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAC,MACnB,MAAM,GACJ;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAmBzC;AAED;;;;EAyBC;AAiBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,6CANW,MAAM,EAAE,GAAC,WAAW,GAAC,SAAS,MAAM,CAAC,SACrC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAC,UAC5D,MAAM,cACN,MAAM,GACJ;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAC,EAAE,CAsCvE;AArRD;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,sCAFU,MAAM,CAE6C;AAE7D;;;;;;;GAOG;AACH;;;;;;;;;;IAYI,6FAA6F;;IAG7F;;;;;;;OAOG;;IAGH;;;;;OAKG;iBAJQ,UAAU,SAAO,MACjB,MAAM,OACN;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAC5F,IAAe,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC;GAoBrE;AA6HH;;;;;;;;;;GAUG;AACH,sCAFU,MAAM,CAEwC"}

package/src/shade/playground/caldera/caldera_format.js

@@ -141,6 +141,43 @@ export function caldera_read_geometry_table(bytes) {
  * @param {ArrayBuffer} file
  * @returns {{count: number, geometry: Uint32Array, matrices: Float32Array}}
  */
+/**
+ * The manifest record a geometry's table row names.
+ *
+ * Refuses with a message naming the ROW rather than answering `undefined`, because the caller's
+ * error path used to build its message out of the record it was reporting: an `undefined` here made
+ * `record.file` throw inside the `try` and `record.file` throw AGAIN in the `catch`, and that
+ * second TypeError escaped the worker, rejected its `Promise.all` and marked the whole district
+ * failed. One geometry a stale rebuild could not resolve took every remaining placement in the
+ * district with it, and the console line was about the wrong thing.
+ *
+ * The two tables are written by separate tools and shipped as separate files, so a table row
+ * indexing past the manifest is exactly the inconsistency the refusal count exists to report.
+ *
+ * @param {ArrayLike<{file: string, bytes: number}>} vgeo_records the manifest's `vgeo` array
+ * @param {{vgeo: Uint32Array}} table
+ * @param {number} id geometry id
+ * @returns {{file: string, bytes: number}}
+ */
+export function caldera_vgeo_record(vgeo_records, table, id) {
+    const index = table.vgeo[id];
+
+    if (index === CALDERA_TABLE_ROW.NO_VGEO) {
+        throw new Error(`geometry ${id} has no .vgeo`);
+    }
+
+    const record = vgeo_records[index];
+
+    if (record === undefined) {
+        throw new Error(
+            `geometry ${id} names vgeo ${index}, which the manifest does not have`
+            + ` (${vgeo_records.length} entries)`
+        );
+    }
+
+    return record;
+}
+
 export function caldera_read_placements(file) {
     const header = new Uint8Array(file, 0, CALDERA_PLACEMENT_MAGIC.length);
 

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

@@ -38,6 +38,7 @@ import {
     CALDERA_TABLE_ROW,
     caldera_coalesce_ranges,
     caldera_read_geometry_table,
+    caldera_vgeo_record,
     caldera_read_placements,
 } from "./caldera_format.js";
 
@@ -780,9 +781,15 @@ class CalderaPlayground {
             while (next < ids.length && this.fatal === undefined) {
                 const id = ids[next++];
 
-                const record = this.manifest.vgeo[this.table.vgeo[id]];
+                // resolved INSIDE the try: a table row naming a vgeo the manifest does not have is
+                // precisely what `refused` counts, and the handler below used to build its message
+                // out of this record, so an unresolved one threw a second time and took the whole
+                // district down with it
+                let record;
 
                 try {
+                    record = caldera_vgeo_record(this.manifest.vgeo, this.table, id);
+
                     const source = vgeo_byte_source_over_url(
                         new URL(record.file, this.base).href, record.bytes
                     );
@@ -799,7 +806,10 @@ class CalderaPlayground {
                 } catch (error) {
                     this.refused++;
 
-                    console.warn(`${record.file} — ${error.message ?? error}`);
+                    // `id` is always defined; the file only once the record resolved
+                    const where = record === undefined ? `geometry ${id}` : record.file;
+
+                    console.warn(`${where} — ${error.message ?? error}`);
                 }
             }
         };

package/src/shade/playground/frame_rate_meter.d.ts

@@ -0,0 +1,92 @@
+/**
+ * # A frame-rate readout that can see a hitch
+ *
+ * The obvious readout is an exponential mean of `1/dt`, and it is wrong in the
+ * one regime the number is for. A mean of reciprocals is not the reciprocal of
+ * the mean — by Jensen it is biased upward, and the bias grows with the
+ * variance, which is exactly what a stall is. Nine frames at 16.7 ms and one at
+ * 200 ms is 28.6 fps; `fps = fps*0.9 + 0.1/dt` never reads below 53.8 for that
+ * cycle. A page that drops a fifth of a second every ten frames reports itself
+ * as smooth.
+ *
+ * So this averages the frame *time* over a window and takes the reciprocal
+ * once, at the end. Over a window that covers whole cycles of the pattern above
+ * it reads 28.6 fps, which is the answer.
+ *
+ * It also counts **hitches** separately rather than folding them in. A page
+ * that clamps `dt` before stepping its simulation — which is right, a long
+ * stall must not teleport anything — must not hand the clamped value to its
+ * readout as well, or the longest frames enter the average as if they were the
+ * clamp. The meter takes the real interval and keeps the count of frames past
+ * the threshold, so "it is running at 60 and hitching four times a second" is
+ * sayable.
+ *
+ * (The three pages that carry an inline `FrameTimer` predate this and are the
+ * duplication pass's business, not this module's.)
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Frames averaged by default — a second at 60 fps, which is long enough to
+ * cover several repeats of a periodic stall and short enough to follow a real
+ * change in cost.
+ * @type {number}
+ */
+export const FRAME_RATE_WINDOW: number;
+/**
+ * A frame longer than this counts as a hitch, by default. The same 50 ms the
+ * particle pages clamp their simulation step at: three frames' worth at 60 fps,
+ * and the point past which a stall is visible rather than felt.
+ * @type {number}
+ */
+export const FRAME_HITCH_SECONDS: number;
+export class FrameRateMeter {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.window] frames to average over
+     * @param {number} [options.hitch_seconds] a frame at least this long is a hitch
+     */
+    constructor({ window, hitch_seconds }?: {
+        window?: number;
+        hitch_seconds?: number;
+    });
+    /**
+     * Record one frame's REAL length — not a clamped one, and not the
+     * limiter's scheduled interval (see `create_frame_loop`'s second argument).
+     *
+     * A non-positive or non-finite interval is ignored rather than averaged:
+     * two callbacks in the same millisecond is a property of the clock, not of
+     * the frame.
+     *
+     * @param {number} seconds
+     * @returns {void}
+     */
+    add(seconds: number): void;
+    /**
+     * Forget the window and the hitch count. For a page resuming after a pause,
+     * where the gap is not a frame anybody waited through.
+     * @returns {void}
+     */
+    reset(): void;
+    /**
+     * Mean frame time over the window, milliseconds. `0` before the first frame.
+     * @returns {number}
+     */
+    get mean_ms(): number;
+    /**
+     * Frames per second: the reciprocal of the mean frame time, taken once.
+     * `0` before the first frame.
+     * @returns {number}
+     */
+    get fps(): number;
+    /**
+     * Frames at or past the hitch threshold since the last {@link reset}. Not
+     * windowed — it is a count of events, and a page that hitched is a page
+     * that hitched.
+     * @returns {number}
+     */
+    get hitches(): number;
+    #private;
+}
+//# sourceMappingURL=frame_rate_meter.d.ts.map

package/src/shade/playground/frame_rate_meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame_rate_meter.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/frame_rate_meter.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;GAKG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;;GAKG;AACH,kCAFU,MAAM,CAEwB;AAExC;IAgBI;;;;OAIG;IACH;QAH4B,MAAM,GAAvB,MAAM;QACW,aAAa,GAA9B,MAAM;OAKhB;IAED;;;;;;;;;;OAUG;IACH,aAHW,MAAM,GACJ,IAAI,CAchB;IAED;;;;OAIG;IACH,SAFa,IAAI,CAMhB;IAED;;;OAGG;IACH,sBAYC;IAED;;;;OAIG;IACH,kBAIC;IAED;;;;;OAKG;IACH,sBAEC;;CACJ"}

package/src/shade/playground/frame_rate_meter.js

@@ -0,0 +1,147 @@
+/**
+ * # A frame-rate readout that can see a hitch
+ *
+ * The obvious readout is an exponential mean of `1/dt`, and it is wrong in the
+ * one regime the number is for. A mean of reciprocals is not the reciprocal of
+ * the mean — by Jensen it is biased upward, and the bias grows with the
+ * variance, which is exactly what a stall is. Nine frames at 16.7 ms and one at
+ * 200 ms is 28.6 fps; `fps = fps*0.9 + 0.1/dt` never reads below 53.8 for that
+ * cycle. A page that drops a fifth of a second every ten frames reports itself
+ * as smooth.
+ *
+ * So this averages the frame *time* over a window and takes the reciprocal
+ * once, at the end. Over a window that covers whole cycles of the pattern above
+ * it reads 28.6 fps, which is the answer.
+ *
+ * It also counts **hitches** separately rather than folding them in. A page
+ * that clamps `dt` before stepping its simulation — which is right, a long
+ * stall must not teleport anything — must not hand the clamped value to its
+ * readout as well, or the longest frames enter the average as if they were the
+ * clamp. The meter takes the real interval and keeps the count of frames past
+ * the threshold, so "it is running at 60 and hitching four times a second" is
+ * sayable.
+ *
+ * (The three pages that carry an inline `FrameTimer` predate this and are the
+ * duplication pass's business, not this module's.)
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Frames averaged by default — a second at 60 fps, which is long enough to
+ * cover several repeats of a periodic stall and short enough to follow a real
+ * change in cost.
+ * @type {number}
+ */
+export const FRAME_RATE_WINDOW = 60;
+
+/**
+ * A frame longer than this counts as a hitch, by default. The same 50 ms the
+ * particle pages clamp their simulation step at: three frames' worth at 60 fps,
+ * and the point past which a stall is visible rather than felt.
+ * @type {number}
+ */
+export const FRAME_HITCH_SECONDS = 0.05;
+
+export class FrameRateMeter {
+    /** @type {Float64Array} @private */
+    #samples;
+
+    /** @type {number} @private */
+    #count = 0;
+
+    /** @type {number} @private */
+    #cursor = 0;
+
+    /** @type {number} @private */
+    #hitches = 0;
+
+    /** @type {number} @private */
+    #hitch_seconds;
+
+    /**
+     * @param {object} [options]
+     * @param {number} [options.window] frames to average over
+     * @param {number} [options.hitch_seconds] a frame at least this long is a hitch
+     */
+    constructor({ window = FRAME_RATE_WINDOW, hitch_seconds = FRAME_HITCH_SECONDS } = {}) {
+        this.#samples = new Float64Array(window);
+        this.#hitch_seconds = hitch_seconds;
+    }
+
+    /**
+     * Record one frame's REAL length — not a clamped one, and not the
+     * limiter's scheduled interval (see `create_frame_loop`'s second argument).
+     *
+     * A non-positive or non-finite interval is ignored rather than averaged:
+     * two callbacks in the same millisecond is a property of the clock, not of
+     * the frame.
+     *
+     * @param {number} seconds
+     * @returns {void}
+     */
+    add(seconds) {
+        if (!(seconds > 0) || !Number.isFinite(seconds)) {
+            return;
+        }
+
+        this.#samples[this.#cursor] = seconds;
+        this.#cursor = (this.#cursor + 1) % this.#samples.length;
+        this.#count = Math.min(this.#count + 1, this.#samples.length);
+
+        if (seconds >= this.#hitch_seconds) {
+            this.#hitches++;
+        }
+    }
+
+    /**
+     * Forget the window and the hitch count. For a page resuming after a pause,
+     * where the gap is not a frame anybody waited through.
+     * @returns {void}
+     */
+    reset() {
+        this.#count = 0;
+        this.#cursor = 0;
+        this.#hitches = 0;
+    }
+
+    /**
+     * Mean frame time over the window, milliseconds. `0` before the first frame.
+     * @returns {number}
+     */
+    get mean_ms() {
+        if (this.#count === 0) {
+            return 0;
+        }
+
+        let total = 0;
+
+        for (let i = 0; i < this.#count; i++) {
+            total += this.#samples[i];
+        }
+
+        return (total / this.#count) * 1e3;
+    }
+
+    /**
+     * Frames per second: the reciprocal of the mean frame time, taken once.
+     * `0` before the first frame.
+     * @returns {number}
+     */
+    get fps() {
+        const mean = this.mean_ms;
+
+        return mean > 0 ? 1000 / mean : 0;
+    }
+
+    /**
+     * Frames at or past the hitch threshold since the last {@link reset}. Not
+     * windowed — it is a count of events, and a page that hitched is a page
+     * that hitched.
+     * @returns {number}
+     */
+    get hitches() {
+        return this.#hitches;
+    }
+}