@woosh/meep-engine 3.22.0 → 3.23.0

package/src/engine/physics/cloth/solver/constraint/cloth_self_row.js

@@ -0,0 +1,202 @@
+import {
+    CVA_F_X,
+    CVA_F_Y,
+    CVA_F_Z,
+    CVA_H_XX,
+    CVA_H_XY,
+    CVA_H_XZ,
+    CVA_H_YY,
+    CVA_H_YZ,
+    CVA_H_ZZ
+} from "../cloth_vertex_accumulator.js";
+
+/**
+ * # Self-collision — the row that keeps cloth off itself
+ *
+ *     C(x) = ‖x_i − x_j‖ − (r_i + r_j)
+ *     ∂C/∂x_i = (x_i − x_j)/‖x_i − x_j‖ = n
+ *     ∂C/∂x_j = −n
+ *     clamp (−∞, 0]
+ *
+ * **That clamp is right and it is the one place in §6's table where the negative
+ * half is the live one.** The rule is that `[0, +∞)` admits only forces that
+ * *reduce* `C` and `(−∞, 0]` only forces that *increase* it; this row is violated
+ * when the two particles are closer than their radii, which is `C < 0`, so what
+ * it needs is `C` increased. Under the solver's `f -= fc·g`, a negative `fc`
+ * pushes `i` along `+n` and `j` along `−n` — apart. Every distance row above it
+ * in the table bounds a distance from *above* and therefore takes the other
+ * half; this one bounds from below.
+ *
+ * ## It is applied Jacobi-style, and this is where §5.4 was right
+ *
+ * A collider contact is unary and needs none of §5.4's machinery (`MEASUREMENTS.md`
+ * §18). A self-collision row is a **pair**, and pairs are exactly what the
+ * colouring cannot pre-partition: two particles of the same colour can be
+ * neighbours in space and would then both move against each other inside one
+ * sweep, in an order that depends on how the sweep was split. So the pairs are
+ * accumulated once per iteration into a per-particle `(f, H)` scratch, from the
+ * positions at the start of that iteration, and every vertex update adds its own
+ * entry. The result is a step that is the same whatever order the colours were
+ * swept in, which is what §12's bit-parity gate is going to be held to.
+ *
+ * ## The row is soft, which the collision row could not be
+ *
+ * `MEASUREMENTS.md` §18 measured that a collider contact cannot be a soft
+ * penalty: the force it has to produce is an *arrested impact*, 376 N for a
+ * sheet arriving at 8 m/s, against the 4.6 N a soft row inside M0's dissipative
+ * band can deliver at one thickness of penetration.
+ *
+ * A self-collision row carries nothing of the kind. What it holds apart is cloth
+ * against cloth — grams, moving at the speed cloth moves relative to itself — and
+ * a penalty at the top of the band produces newtons per millimetre against a
+ * load of fractions of a newton. So it is a plain penalty with no multiplier, no
+ * warm start and no identity across steps, which is also what makes a pair list
+ * that is rebuilt from scratch every step affordable: there is nothing on a pair
+ * worth carrying. `MEASUREMENTS.md` §33.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Below this a separation is treated as zero and the row is skipped: `‖·‖` is
+ * not differentiable there, and two particles at exactly the same place have no
+ * direction to be pushed apart along.
+ * @type {number}
+ */
+export const CLOTH_SELF_EPSILON = 1e-9;
+
+/**
+ * Rebuild the per-particle Jacobi scratch from the pair list.
+ *
+ * Called once per iteration, before the colour sweep, from the positions the
+ * previous iteration left. Every pair contributes to both of its particles.
+ *
+ * @param {ClothState} state
+ * @param {number} stiffness penalty, N/m — the same for every pair, because
+ *   every pair has the same two free ends and therefore the same inertial scale
+ * @returns {number} how many pairs were in contact
+ */
+export function cloth_self_accumulate_scratch(state, stiffness) {
+    const force = state.self_force;
+    const hessian = state.self_hessian;
+
+    force.fill(0);
+    hessian.fill(0);
+
+    const count = state.self_count;
+
+    if (count === 0) {
+        return 0;
+    }
+
+    const pair = state.self_pair;
+    const position = state.position;
+
+    const radius = state.self_radius * 2;
+
+    let active = 0;
+
+    for (let p = 0; p < count; p++) {
+        const i = pair[p * 2];
+        const j = pair[p * 2 + 1];
+
+        const a = i * 3;
+        const b = j * 3;
+
+        const dx = position[a] - position[b];
+        const dy = position[a + 1] - position[b + 1];
+        const dz = position[a + 2] - position[b + 2];
+
+        const length_squared = dx * dx + dy * dy + dz * dz;
+
+        if (length_squared >= radius * radius || length_squared < CLOTH_SELF_EPSILON * CLOTH_SELF_EPSILON) {
+            continue;
+        }
+
+        active++;
+
+        const length = Math.sqrt(length_squared);
+
+        const inverse = 1 / length;
+
+        const nx = dx * inverse;
+        const ny = dy * inverse;
+        const nz = dz * inverse;
+
+        // `C < 0` and the clamp admits only negative force, so `fc = k·C` needs
+        // no clamping at all — it is already on the admitted side, which is what
+        // a one-sided row with no multiplier reduces to.
+        const magnitude = stiffness * (radius - length);
+
+        force[a] += magnitude * nx;
+        force[a + 1] += magnitude * ny;
+        force[a + 2] += magnitude * nz;
+
+        force[b] -= magnitude * nx;
+        force[b + 1] -= magnitude * ny;
+        force[b + 2] -= magnitude * nz;
+
+        // `k·n nᵀ`, the penalty curvature, into both particles' blocks. The
+        // geometric term `(fc/L)·(I − n nᵀ)` is dropped: `fc` is negative here —
+        // the row is in *compression*, pushing apart — so that term is negative
+        // semidefinite, and §5.3 keeps only the positive half.
+        const hxx = stiffness * nx * nx;
+        const hyy = stiffness * ny * ny;
+        const hzz = stiffness * nz * nz;
+        const hxy = stiffness * nx * ny;
+        const hxz = stiffness * nx * nz;
+        const hyz = stiffness * ny * nz;
+
+        const ha = i * 6;
+        const hb = j * 6;
+
+        hessian[ha] += hxx;
+        hessian[ha + 1] += hyy;
+        hessian[ha + 2] += hzz;
+        hessian[ha + 3] += hxy;
+        hessian[ha + 4] += hxz;
+        hessian[ha + 5] += hyz;
+
+        hessian[hb] += hxx;
+        hessian[hb + 1] += hyy;
+        hessian[hb + 2] += hzz;
+        hessian[hb + 3] += hxy;
+        hessian[hb + 4] += hxz;
+        hessian[hb + 5] += hyz;
+    }
+
+    return active;
+}
+
+/**
+ * Add one particle's share of the Jacobi scratch into its vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_self_accumulate(accumulator, state, particle) {
+    const hessian = state.self_hessian;
+
+    const h = particle * 6;
+
+    if (hessian[h] === 0 && hessian[h + 1] === 0 && hessian[h + 2] === 0) {
+        return;
+    }
+
+    const force = state.self_force;
+
+    const f = particle * 3;
+
+    accumulator[CVA_F_X] += force[f];
+    accumulator[CVA_F_Y] += force[f + 1];
+    accumulator[CVA_F_Z] += force[f + 2];
+
+    accumulator[CVA_H_XX] += hessian[h];
+    accumulator[CVA_H_YY] += hessian[h + 1];
+    accumulator[CVA_H_ZZ] += hessian[h + 2];
+    accumulator[CVA_H_XY] += hessian[h + 3];
+    accumulator[CVA_H_XZ] += hessian[h + 4];
+    accumulator[CVA_H_YZ] += hessian[h + 5];
+}

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#386@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#383@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#386@#clear_field"(fluid: FluidComponent): void;
+    static "__#383@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#386@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#383@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#386@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#383@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/shade/playground/vgeo_viewer/README.md

@@ -65,6 +65,18 @@ them. Coarse-first layout is what makes the second worth doing: a prefix that ov
 frame has overshot into the pages the traversal is about to want. Watch `read so far` and `requests`
 move against each other. `?head=<bytes>` sets it on load.
 
+**head prefix** on the streaming panel is what is still *held*, and it says `released` for most of a
+session: the reader drops the prefix the first time a read falls outside it, because after the pages
+inside it have installed it is bytes nothing will read — and at a thousand open assets a retained
+256 KiB apiece was a quarter of a gigabyte that neither `resident` nor eviction could see. The
+always-resident set is about 2.4 KB, so the prefix is speculation about the next band and 64 KiB is
+enough of it; the dial is there to watch the trade rather than to tune it.
+
+**quarantined** is the other new row, and it is the difference between an asset that is coarse
+because the camera just moved and one that is coarse because a page will never arrive — which look
+identical on screen. A page that fails its retries is quarantined with its reason and is not asked
+for again; the clamped cut keeps its surface correct with a coarser ancestor, indefinitely.
+
 `read so far` is cumulative and is allowed past 100%: evicting and re-streaming really does fetch
 those pages again, and the audit really does read every byte.
 
@@ -76,6 +88,12 @@ incremental reader exists to avoid, and it answers a question about whoever *wro
 than about the view being put on screen. Press **validate the whole file** when that is the
 question, or pass `?validate`.
 
+It is not a method on the reader, either. `vgeo_audit_container` and `vgeo_install_all_pages` live in
+`format/read/tool/`, and this viewer calls them as the tool it is — a renderer holding a thousand
+containers must not have either within reach of one of them. The audit takes the file as a single
+`ArrayBuffer`, because every build invariant is a cross-check between two places in it, so it refuses
+above 1 GiB naming the size rather than failing in the allocator.
+
 What is *not* optional, because it is the difference between refusing a file and misreading one:
 magic, minimum reader version, payload encoding, hash algorithm, unknown required feature bits,
 unknown codecs, a `decoded_size` outside what the stored bytes could physically produce, and a root

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

@@ -25,6 +25,12 @@ import {
 import {
     VGeoReadOptions
 } from "../../renderer/geometry/virtual/format/read/VGeoReadOptions.js";
+import {
+    vgeo_audit_container
+} from "../../renderer/geometry/virtual/format/read/tool/vgeo_audit_container.js";
+import {
+    vgeo_install_all_pages
+} from "../../renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.js";
 import { make_sunlight } from "../../renderer/light/make_sunlight.js";
 import { Renderer } from "../../renderer/Renderer.js";
 import { DynamicMesh } from "../../renderer/scene/DynamicMesh.js";
@@ -93,8 +99,8 @@ const STREAM_BATCH = 8;
 const HEAD_PREFIXES = [
     ['256 B — header only', 256],
     ['16 KB', 16 * 1024],
-    ['64 KB', 64 * 1024],
-    ['256 KB — the default', 256 * 1024],
+    ['64 KB — the default', 64 * 1024],
+    ['256 KB', 256 * 1024],
     ['1 MB', 1024 * 1024],
 ];
 
@@ -145,35 +151,76 @@ function escape_html(text) {
 }
 
 /**
- * What the resident pages cost stored against what they cost decoded, and under which codec.
+ * What a reader's quarantine amounts to, for the panel.
  *
- * Stored is the number that gets fetched and the number that sits on disk; decoded is the number a
- * resident page costs in RAM. The codec is per frame, so a file can genuinely be a mixture — the
- * encoder stores a page raw whenever compressing it would not have shrunk it — and naming all of
- * them is more honest than naming whichever one happened to come first.
+ * A page that has failed its retries is not an error the viewer can act on — the clamped cut keeps
+ * that surface correct with a coarser ancestor — but it is the difference between an asset that is
+ * coarse because the camera just moved and one that is coarse because a page will never arrive, and
+ * those look identical on screen. So the count goes on the panel, with the first reason.
  *
- * @param {VGeoPage[]} pages
+ * @param {VGeoContainerReader} reader
  * @returns {string}
  */
-function page_storage(pages) {
-    if (pages.length === 0) {
-        return '—';
+function quarantine_summary(reader) {
+    const count = reader.quarantined_page_count;
+
+    if (count === 0) {
+        return 'none';
     }
 
+    const [page, reason] = reader.quarantine().next().value;
+
+    return `${thousands(count)} page(s) · page ${page}: ${escape_html(reason)}`;
+}
+
+/**
+ * Everything the panel says about the resident set, in one pass over it.
+ *
+ * One pass, and over `resident_pages()` rather than `pages`, because the panel refreshes on every
+ * streaming round and `VGeoContainerReader.pages` is a snapshot that allocates an array and sorts
+ * it — 0.29 ms at 20,000 resident pages, and this used to ask for two of them.
+ *
+ * Storage: stored is what gets fetched and what sits on disk, decoded is what a resident page costs
+ * in RAM. The codec is per frame, so a file can genuinely be a mixture — the encoder stores a page
+ * raw whenever compressing it would not have shrunk it — and naming all of them is more honest than
+ * naming whichever one came first.
+ *
+ * Normals: worth saying outright because the alternative reads as a broken viewer. A source that
+ * carried no normals encodes the engine default everywhere, every cluster compresses to one constant
+ * word, and `colour by stored normal` comes out one flat colour across the whole model.
+ *
+ * @param {VGeoContainerReader} reader
+ * @returns {{storage: string, normals: string}}
+ */
+function page_summary(reader) {
     let stored = 0;
     let decoded = 0;
+    let per_vertex = 0;
+    let clusters = 0;
+    let pages = 0;
+
+    const codecs = new Set();
 
-    for (const page of pages) {
+    for (const page of reader.resident_pages()) {
         stored += page.stored_size;
         decoded += page.decoded_size;
+        per_vertex += page.per_vertex_normal_cluster_count;
+        clusters += page.cluster_count;
+
+        codecs.add(page.codec);
+
+        pages++;
     }
 
-    const codec = Array.from(new Set(pages.map((page) => page.codec)))
-        .map(vgeo_codec_name)
-        .join(' + ');
+    const codec = Array.from(codecs).map(vgeo_codec_name).join(' + ');
 
-    return `${human_bytes(stored)} stored · ${human_bytes(decoded)} decoded`
-        + ` · ${codec} ${(decoded / Math.max(stored, 1)).toFixed(2)}x`;
+    return {
+        storage: pages === 0
+            ? '—'
+            : `${human_bytes(stored)} stored · ${human_bytes(decoded)} decoded`
+                + ` · ${codec} ${(decoded / Math.max(stored, 1)).toFixed(2)}x`,
+        normals: `${thousands(per_vertex)} / ${thousands(clusters)} clusters`,
+    };
 }
 
 /**
@@ -802,10 +849,10 @@ class VGeoViewer {
         const sample = vgeo_sample_source();
 
         /*
-         The default prefix is one nominal page plus the head, and a *default* build has 256 KB
-         pages. The sample's are 8 KB, so the same prefix would swallow most of it and there would be
-         nothing left to stream — a demonstration of the head prefix rather than of the reader. Sized
-         to the sample's own pages instead, unless the address bar has already made the choice.
+         The default prefix is 64 KB, sized against a *default* build's pages of hundreds of KB. The
+         sample's are 8 KB, so even that prefix would swallow much of it and there would be little
+         left to stream — a demonstration of the head prefix rather than of the reader. Sized to the
+         sample's own pages instead, unless the address bar has already made the choice.
         */
         if (!this.#head_pinned) {
             this.#read_options.head_prefix_bytes = 16 * 1024;
@@ -867,7 +914,7 @@ class VGeoViewer {
         const started = performance.now();
 
         try {
-            this.#defects = await this.#reader.validate();
+            this.#defects = await vgeo_audit_container(this.#reader);
         } catch (e) {
             this.#defects = undefined;
             this.#validation_status = String(e.message ?? e);
@@ -896,11 +943,18 @@ class VGeoViewer {
         this.#status = 'installing every page';
         this.#refresh_panel();
 
-        await this.#reader.install_all_pages((done, total) => {
-            this.#status = `installing every page — ${done} / ${total}`;
-        });
+        try {
+            await vgeo_install_all_pages(this.#reader, (done, total) => {
+                this.#status = `installing every page — ${done} / ${total}`;
+            });
 
-        this.#status = '';
+            this.#status = '';
+        } catch (e) {
+            // A page that could not be read is quarantined rather than fatal now, and the tool
+            // reports at the end rather than stopping at the first one — so every page that *could*
+            // be installed is here, and the message says how many could not.
+            this.#status = String(e.message ?? e);
+        }
 
         this.adapt();
         this.#refresh_panel();
@@ -1023,7 +1077,7 @@ class VGeoViewer {
         const header = reader.header;
         const source = reader.source;
 
-        const pages = reader.pages;
+        const summary = page_summary(reader);
 
         /*
          Cumulative for the session, and deliberately allowed past the file's own size: evicting and
@@ -1050,32 +1104,13 @@ class VGeoViewer {
                 ['requests', thousands(source.request_count)],
                 ['cold start', `${human_bytes(this.#open_bytes)} · ${this.#open_ms.toFixed(1)} ms`],
                 ['resident', `${thousands(reader.resident_page_count)} / ${thousands(header.total_pages)} pages · ${human_bytes(reader.resident_bytes)}`],
-                ['page storage', page_storage(pages)],
-                ['per-vertex normals', this.#normal_share(pages)],
+                ['page storage', summary.storage],
+                ['per-vertex normals', summary.normals],
+                ['head prefix', reader.head_bytes === 0 ? 'released' : human_bytes(reader.head_bytes)],
+                ['quarantined', quarantine_summary(reader)],
             ]);
     }
 
-    /**
-     * How many resident clusters store a normal per vertex, against how many are resident at all.
-     *
-     * Worth saying outright because the alternative reads as a broken viewer: a source that carried
-     * no normals encodes the engine default everywhere, every cluster compresses to one constant
-     * word, and `colour by stored normal` comes out one flat colour across the whole model.
-     *
-     * @param {VGeoPage[]} pages
-     * @returns {string}
-     */
-    #normal_share(pages) {
-        let per_vertex = 0;
-        let total = 0;
-
-        for (const page of pages) {
-            per_vertex += page.per_vertex_normal_cluster_count;
-            total += page.cluster_count;
-        }
-
-        return `${thousands(per_vertex)} / ${thousands(total)} clusters`;
-    }
 
     /**
      * @returns {string}
@@ -1282,6 +1317,8 @@ function __state() {
         total_clusters: reader?.header.total_clusters,
         resident_pages: reader?.resident_page_count ?? 0,
         resident_bytes: reader?.resident_bytes ?? 0,
+        head_bytes: reader?.head_bytes ?? 0,
+        quarantined_pages: reader?.quarantined_page_count ?? 0,
         file_bytes: reader?.source.byte_length ?? 0,
         bytes_read: reader?.source.bytes_read ?? 0,
         requests: reader?.source.request_count ?? 0,

package/src/shade/renderer/buffer/table/GPUDatabase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AAwCA;;;;;;;;;GASG;AACH;IA0EI;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAuEhB;IApJD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAyCP;;OAEG;IACH,8BAEC;IAgFD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;OAKG;IACH,gCAEC;IAoPD;;;OAGG;IACH,gBAFW,sBAAsB,QAoIhC;IA2DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBAIC;;CACJ;qCA/1BY,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BANzC,oBAAoB"}
+{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA0CA;;;;;;;;;GASG;AACH;IA0EI;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAuEhB;IApJD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAyCP;;OAEG;IACH,8BAEC;IAgFD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;OAKG;IACH,gCAEC;IAoPD;;;OAGG;IACH,gBAFW,sBAAsB,QA+EhC;IA+OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBAIC;;CACJ;qCA99BY,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BANzC,oBAAoB"}