@woosh/meep-engine 2.138.20 → 2.140.0

package/src/core/graph/metis/native/refine/project_kway.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Project the partition assignment from `graph.coarser_graph` down to `graph`,
+ * then compute the k-way refinement bookkeeping at the fine level.
+ *
+ * Each fine vertex inherits the partition of its coarse parent
+ * (`coarse_vertex_map[v]` maps fine→coarse). After projection,
+ * `vertex_partition`, `partition_weights`, the `internal_degree` /
+ * `external_degree` / `neighbor_partition_*` arrays, the boundary list, and
+ * `current_cut` are all rebuilt from scratch.
+ *
+ * METIS's `ProjectKWayPartition` folds the projection into the parameter-compute
+ * pass and uses the coarse graph's `external_degree[]` as a hint to skip vertices
+ * that are guaranteed interior. That's a measurable speedup at scale, but the
+ * state coupling isn't worth it in v1 — we just project then call the standard
+ * compute routine.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph the fine graph (must have
+ *   `.coarser_graph` set and that coarser graph's `vertex_partition` populated)
+ * @param {number} partition_count
+ */
+export function project_kway(graph: import('../MetisGraph.js').MetisGraph, partition_count: number): void;
+//# sourceMappingURL=project_kway.d.ts.map

package/src/core/graph/metis/native/refine/project_kway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project_kway.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/refine/project_kway.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oCAJW,OAAO,kBAAkB,EAAE,UAAU,mBAErC,MAAM,QAqBhB"}

package/src/core/graph/metis/native/refine/project_kway.js

@@ -0,0 +1,43 @@
+import { assert } from "../../../../assert.js";
+import { compute_kway_params } from "./compute_kway_params.js";
+
+/**
+ * Project the partition assignment from `graph.coarser_graph` down to `graph`,
+ * then compute the k-way refinement bookkeeping at the fine level.
+ *
+ * Each fine vertex inherits the partition of its coarse parent
+ * (`coarse_vertex_map[v]` maps fine→coarse). After projection,
+ * `vertex_partition`, `partition_weights`, the `internal_degree` /
+ * `external_degree` / `neighbor_partition_*` arrays, the boundary list, and
+ * `current_cut` are all rebuilt from scratch.
+ *
+ * METIS's `ProjectKWayPartition` folds the projection into the parameter-compute
+ * pass and uses the coarse graph's `external_degree[]` as a hint to skip vertices
+ * that are guaranteed interior. That's a measurable speedup at scale, but the
+ * state coupling isn't worth it in v1 — we just project then call the standard
+ * compute routine.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph the fine graph (must have
+ *   `.coarser_graph` set and that coarser graph's `vertex_partition` populated)
+ * @param {number} partition_count
+ */
+export function project_kway(graph, partition_count) {
+    const coarser_graph = graph.coarser_graph;
+    const coarse_vertex_map = graph.coarse_vertex_map;
+
+    assert.equal(coarser_graph !== null, true, 'graph.coarser_graph must be set before projection');
+    assert.equal(coarse_vertex_map !== null, true, 'graph.coarse_vertex_map must be set before projection');
+    assert.equal(coarser_graph.vertex_partition !== null, true, 'coarser_graph.vertex_partition must be populated before projection');
+
+    graph.allocate_partition_state(partition_count);
+
+    const fine_partition = graph.vertex_partition;
+    const coarse_partition = coarser_graph.vertex_partition;
+    const vertex_count = graph.vertex_count;
+
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        fine_partition[vertex] = coarse_partition[coarse_vertex_map[vertex]];
+    }
+
+    compute_kway_params(graph, partition_count);
+}

package/src/core/graph/metis/native/refine/refine_kway.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Uncoarsen the multilevel graph hierarchy, running FM refinement at every level.
+ *
+ * On entry, `coarsest_graph` has a valid initial partition in
+ * `coarsest_graph.vertex_partition[]` and its refinement bookkeeping fully
+ * populated (via `compute_kway_params`). On exit, `original_graph.vertex_partition[]`
+ * holds the refined partition of the original finest graph.
+ *
+ * Mirrors `RefineKWay` from libmetis/kwayrefine.c, simplified:
+ *   - no minconn / contig handling
+ *   - no separate balance passes (we run REFINE-only at each level; the
+ *     adaptive ub_factor in fm_kway recovers most of what an explicit BALANCE
+ *     pass would have done)
+ *   - no separator/volume code
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} original_graph the finest graph
+ * @param {import('../MetisGraph.js').MetisGraph} coarsest_graph the coarsest graph
+ * @param {number} partition_count
+ * @param {{
+ *   random: function():number,
+ *   pass_count?: number,
+ *   ub_factor?: number,
+ *   fudge_factor?: number,
+ * }} opts forwarded to `fm_kway`
+ * @param {import('./RefinementScratch.js').RefinementScratch} scratch shared scratch
+ *   sized to `original_graph.vertex_count`
+ */
+export function refine_kway(original_graph: import('../MetisGraph.js').MetisGraph, coarsest_graph: import('../MetisGraph.js').MetisGraph, partition_count: number, opts: {
+    random: () => number;
+    pass_count?: number;
+    ub_factor?: number;
+    fudge_factor?: number;
+}, scratch: import('./RefinementScratch.js').RefinementScratch): void;
+//# sourceMappingURL=refine_kway.d.ts.map

package/src/core/graph/metis/native/refine/refine_kway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine_kway.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/refine/refine_kway.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,4CAZW,OAAO,kBAAkB,EAAE,UAAU,kBACrC,OAAO,kBAAkB,EAAE,UAAU,mBACrC,MAAM,QACN;IACV,MAAU,QAAa,MAAM,CAAC;IAC9B,UAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAgB,CAAC,EAAE,MAAM,CAAC;CACvB,WACO,OAAO,wBAAwB,EAAE,iBAAiB,QAe5D"}

package/src/core/graph/metis/native/refine/refine_kway.js

@@ -0,0 +1,43 @@
+import { fm_kway } from "./fm_kway.js";
+import { project_kway } from "./project_kway.js";
+
+/**
+ * Uncoarsen the multilevel graph hierarchy, running FM refinement at every level.
+ *
+ * On entry, `coarsest_graph` has a valid initial partition in
+ * `coarsest_graph.vertex_partition[]` and its refinement bookkeeping fully
+ * populated (via `compute_kway_params`). On exit, `original_graph.vertex_partition[]`
+ * holds the refined partition of the original finest graph.
+ *
+ * Mirrors `RefineKWay` from libmetis/kwayrefine.c, simplified:
+ *   - no minconn / contig handling
+ *   - no separate balance passes (we run REFINE-only at each level; the
+ *     adaptive ub_factor in fm_kway recovers most of what an explicit BALANCE
+ *     pass would have done)
+ *   - no separator/volume code
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} original_graph the finest graph
+ * @param {import('../MetisGraph.js').MetisGraph} coarsest_graph the coarsest graph
+ * @param {number} partition_count
+ * @param {{
+ *   random: function():number,
+ *   pass_count?: number,
+ *   ub_factor?: number,
+ *   fudge_factor?: number,
+ * }} opts forwarded to `fm_kway`
+ * @param {import('./RefinementScratch.js').RefinementScratch} scratch shared scratch
+ *   sized to `original_graph.vertex_count`
+ */
+export function refine_kway(original_graph, coarsest_graph, partition_count, opts, scratch) {
+    let current_level = coarsest_graph;
+
+    // First refine the freshly-initialised coarsest partition before projection.
+    fm_kway(current_level, partition_count, opts, scratch);
+
+    while (current_level !== original_graph) {
+        const finer_level = current_level.finer_graph;
+        project_kway(finer_level, partition_count);
+        current_level = finer_level;
+        fm_kway(current_level, partition_count, opts, scratch);
+    }
+}

package/src/core/math/linalg/eigen/matrix_householder_in_place.d.ts

@@ -1,7 +1,7 @@
 /**
  * NxN matrix Householder reduction to upper Hessenberg form via similarity
  * transformations. After this routine, `a[c*n + r] == 0` for every `r > c+1`
- * — i.e. only the main diagonal and the first sub-diagonal carry nonzeros
+ * — i.e. only the main diagonal and the first sub-diagonal carry non-zeros
  * below the diagonal.
  *
  * Inner loops are arranged so the hot accesses stream one column at a time
@@ -9,7 +9,7 @@
  *
  * @see http://www-in.aut.ac.jp/~minemura/pub/Csimu/C/QRmethod.html
  * @param {number[]|Float64Array} a Square matrix, column-major flat layout (a[j*n + i] = row i, col j); modified in place
- * @param {number} n
+ * @param {number} n matrix size (e.g. 4 for 4x4 matrix)
  */
 export function matrix_householder_in_place(a: number[] | Float64Array, n: number): void;
 //# sourceMappingURL=matrix_householder_in_place.d.ts.map

package/src/core/math/linalg/eigen/matrix_householder_in_place.js

@@ -3,7 +3,7 @@ const EPSILON = 1e-10;
 /**
  * NxN matrix Householder reduction to upper Hessenberg form via similarity
  * transformations. After this routine, `a[c*n + r] == 0` for every `r > c+1`
- * — i.e. only the main diagonal and the first sub-diagonal carry nonzeros
+ * — i.e. only the main diagonal and the first sub-diagonal carry non-zeros
  * below the diagonal.
  *
  * Inner loops are arranged so the hot accesses stream one column at a time
@@ -11,7 +11,7 @@ const EPSILON = 1e-10;
  *
  * @see http://www-in.aut.ac.jp/~minemura/pub/Csimu/C/QRmethod.html
  * @param {number[]|Float64Array} a Square matrix, column-major flat layout (a[j*n + i] = row i, col j); modified in place
- * @param {number} n
+ * @param {number} n matrix size (e.g. 4 for 4x4 matrix)
  */
 export function matrix_householder_in_place(a, n) {
     const u = new Float64Array(n);

package/src/core/math/linalg/eigen/matrix_qr_in_place.d.ts

@@ -2,10 +2,12 @@
  * Perform QR factorization in-place.
  * Subfunction that analyzes eigenvalues by QR decomposition.
  *
- * Single-shift Wilkinson iteration: deflates the trailing subdiagonal one row
- * at a time as it converges. A complex eigenvalue pair leaves a 2×2 trailing
- * block whose inner subdiagonal does not vanish, and this routine will spin
- * on it indefinitely — only safe today for matrices with all-real eigenvalues.
+ * Single-shift Wilkinson iteration with LAPACK-style exceptional shifts:
+ * deflates the trailing subdiagonal one row at a time as it converges. A
+ * complex eigenvalue pair leaves a 2×2 trailing block whose inner subdiagonal
+ * does not vanish — only safe today for matrices with all-real eigenvalues.
+ * If convergence fails within 30·n sweeps (LAPACK convention), the routine
+ * throws rather than spinning.
  *
  * @see http://www-in.aut.ac.jp/~minemura/pub/Csimu/C/QRmethod.html
  * @param {number[]|Float64Array} a Square matrix, column-major flat layout (a[j*n + i] = row i, col j); modified in place (R is left on the upper triangle)

package/src/core/math/linalg/eigen/matrix_qr_in_place.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matrix_qr_in_place.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_qr_in_place.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,sCAHW,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,QAkIhB"}
+{"version":3,"file":"matrix_qr_in_place.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_qr_in_place.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,sCAHW,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,QA8KhB"}

package/src/core/math/linalg/eigen/matrix_qr_in_place.js

@@ -4,10 +4,12 @@ const EPSILON = 1e-10;
  * Perform QR factorization in-place.
  * Subfunction that analyzes eigenvalues by QR decomposition.
  *
- * Single-shift Wilkinson iteration: deflates the trailing subdiagonal one row
- * at a time as it converges. A complex eigenvalue pair leaves a 2×2 trailing
- * block whose inner subdiagonal does not vanish, and this routine will spin
- * on it indefinitely — only safe today for matrices with all-real eigenvalues.
+ * Single-shift Wilkinson iteration with LAPACK-style exceptional shifts:
+ * deflates the trailing subdiagonal one row at a time as it converges. A
+ * complex eigenvalue pair leaves a 2×2 trailing block whose inner subdiagonal
+ * does not vanish — only safe today for matrices with all-real eigenvalues.
+ * If convergence fails within 30·n sweeps (LAPACK convention), the routine
+ * throws rather than spinning.
  *
  * @see http://www-in.aut.ac.jp/~minemura/pub/Csimu/C/QRmethod.html
  * @param {number[]|Float64Array} a Square matrix, column-major flat layout (a[j*n + i] = row i, col j); modified in place (R is left on the upper triangle)
@@ -22,40 +24,81 @@ export function matrix_qr_in_place(a, n) {
 
     let i, j, k;
 
+    // LAPACK convention: ~30 QR sweeps per eigenvalue. Hitting this means
+    // we're stuck (typically a complex eigenvalue pair the single-shift can't
+    // deflate) — fail loudly rather than spin forever.
+    const MAX_SWEEPS = 30 * n;
+    let sweeps = 0;
+    // Sweeps since the last deflation. Drives exceptional-shift fallbacks
+    // when the standard Wilkinson shift stalls (typical pathology: a trailing
+    // block with near-symmetric ±λ eigenvalues — the shift oscillates and
+    // single-shift QR converges only linearly without a perturbation).
+    let sweeps_since_deflation = 0;
+
     while (m > 1) {
         // a[m-1, m-2] in column-major: (m-2)*n + (m-1)
         const a10_index = (m - 2) * n + (m - 1);
 
         const a10 = a[a10_index];
 
-        //   Convergence test
-        if (Math.abs(a10) < EPSILON) {
+        // Relative convergence test (LAPACK xLAHQR convention): subdiagonal
+        // is "small" when it falls below EPSILON × the magnitude of the
+        // surrounding 2×2 diagonal. Scales correctly with matrix magnitude.
+        // Falls back to the absolute EPSILON when both diagonal entries
+        // collapse to zero, so we don't refuse to deflate a zero block.
+        const a00_abs = Math.abs(a[(m - 2) * n + (m - 2)]);
+        const a11_abs = Math.abs(a[(m - 1) * n + (m - 1)]);
+        const diagScale = a00_abs + a11_abs;
+        const convTol = diagScale > 0 ? EPSILON * diagScale : EPSILON;
+
+        if (Math.abs(a10) <= convTol) {
             m = m - 1;
+            sweeps_since_deflation = 0;
             continue;
         }
 
-        //   Origin movement mu (compute Wilkinson's shift)
+        if (++sweeps > MAX_SWEEPS) {
+            throw new Error(`matrix_qr_in_place: failed to converge after ${MAX_SWEEPS} sweeps (likely complex eigenvalue pair; single-shift QR only handles real spectra)`);
+        }
+        sweeps_since_deflation++;
+
         const a00 = a[(m - 2) * n + (m - 2)];
         const a01 = a[(m - 1) * n + (m - 2)];
         const a11 = a[(m - 1) * n + (m - 1)];
 
-        sum1 = a00 + a11;
-        sum2 = a00 * a11 - a01 * a10;
-
-        wa = sum1 * sum1 - 4.0 * sum2;
-        if (wa < 0.0) {
-            wa = 0.0;
+        if (sweeps_since_deflation === 10 || sweeps_since_deflation === 20) {
+            // Exceptional Rayleigh-quotient shift. The standard Wilkinson
+            // shift can stall on a trailing 2×2 with near-symmetric (±λ)
+            // eigenvalues: it keeps picking whichever root happens to be
+            // closer to a11 that sweep, and the QR step doesn't make
+            // progress. Falling back to mu = a11 alone breaks the symmetry
+            // and gets convergence moving again (LAPACK xLAHQR does an
+            // analogous fallback for the double-shift case at iter 10/20).
+            mu = a11;
         } else {
-            wa = Math.sqrt(wa);
-        }
+            // Standard Wilkinson shift from the trailing 2×2 block.
+            sum1 = a00 + a11;
+            sum2 = a00 * a11 - a01 * a10;
 
-        const lam1 = 0.5 * (sum1 + wa);
-        const lam2 = sum2 / lam1;
+            wa = sum1 * sum1 - 4.0 * sum2;
+            if (wa < 0.0) {
+                wa = 0.0;
+            } else {
+                wa = Math.sqrt(wa);
+            }
 
-        if (Math.abs(a11 - lam1) < Math.abs(a11 - lam2)) {
-            mu = a11 - lam1;
-        } else {
-            mu = a11 - lam2;
+            // Match the sign of wa to sum1 so we form the root with the
+            // larger magnitude first; otherwise sum1 < 0, sum2 ≈ 0 makes
+            // lam1 cancel to zero and lam2 = 0/0 = NaN poisons mu. Guard
+            // the divide too for the degenerate sum1=0, sum2=0 case.
+            const lam1 = 0.5 * (sum1 + (sum1 >= 0 ? wa : -wa));
+            const lam2 = lam1 !== 0 ? sum2 / lam1 : 0;
+
+            if (Math.abs(a11 - lam1) < Math.abs(a11 - lam2)) {
+                mu = a11 - lam1;
+            } else {
+                mu = a11 - lam2;
+            }
         }
 
         // Subtract mu from diagonal
@@ -78,9 +121,12 @@ export function matrix_qr_in_place(a, n) {
 
             sum1 = Math.sqrt(diag * diag + subdiag * subdiag);
 
-            if (Math.abs(sum1) < EPSILON) {
+            if (sum1 < EPSILON) {
+                // Both diag and subdiag ≈ 0 — column already zero in these
+                // two rows. Rotation is the identity (NOT the zero matrix,
+                // which would annihilate rows i and i+1 across all j > i).
                 sinx = 0.0;
-                cosx = 0.0;
+                cosx = 1.0;
             } else {
                 sinx = subdiag / sum1;
                 cosx = diag / sum1;

package/src/engine/EngineHarness.d.ts

@@ -97,8 +97,9 @@ export class EngineHarness {
      * @param {Vector3} [param.sunDirection]
      * @param {Color} [param.ambient]
      * @param {number} [param.ambientIntensity]
+     * @param {number} [param.sunShadowDistance] Maximum draw distance for sun's shadow. Allows better use of shadowmap resolution.
      */
-    static buildLights({ engine, ecd, shadowmapResolution, castShadow, sun, sunIntensity, sunDirection, ambient, ambientIntensity }: {
+    static buildLights({ engine, ecd, shadowmapResolution, castShadow, sun, sunIntensity, sunDirection, sunShadowDistance, ambient, ambientIntensity }: {
         engine: Engine;
         ecd?: EntityComponentDataset;
         shadowmapResolution?: number;
@@ -108,6 +109,7 @@ export class EngineHarness {
         sunDirection?: Vector3;
         ambient?: Color;
         ambientIntensity?: number;
+        sunShadowDistance?: number;
     }): Promise<void>;
     /**
      * @param {Object} param

package/src/engine/EngineHarness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EngineHarness.d.ts","sourceRoot":"","sources":["../../../src/engine/EngineHarness.js"],"names":[],"mappings":"AA6DA;IAmBI;;;;OAIG;IACH,8CAHmB,mBAAmB,UAAQ,MAAM,WACxC,QAAQ,MAAM,CAAC,CAM1B;IAED;;;OAGG;IACH,6BAFW,MAAM,QAYhB;IAkED;;;;;;;;;;;;;OAaG;IACH;QAZyB,MAAM,EAApB,MAAM;QACyB,GAAG;QAClB,MAAM,GAAtB,OAAO;QACQ,QAAQ,GAAvB,MAAM;QACS,KAAK,GAApB,MAAM;QACS,GAAG,GAAlB,MAAM;QACU,QAAQ,GAAxB,OAAO;QACQ,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACJ,MAAM,CA+DlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QApB0B,MAAM,EAArB,MAAM;QACgC,KAAK,GAA3C;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC;QACrB,SAAS;QACT,WAAW;QACF,KAAK,GAArB,MAAM;QACU,GAAG,GAAnB,MAAM;QACU,QAAQ,GAAxB,MAAM;QACwB,WAAW,GAAzC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAC,CAAC,EAAC,MAAM,CAAA;SAAC;QACJ,iBAAiB,GAAjC,MAAM;QACW,WAAW,GAA5B,OAAO;QACU,aAAa,GAA9B,OAAO;QACU,YAAY,GAA7B,OAAO;QACU,aAAa,GAA9B,OAAO;QACS,iBAAiB,GAAjC,MAAM;QACU,iBAAiB,GAAjC,MAAM;QACW,gBAAgB,GAAjC,OAAO;QACU,cAAc,GAA/B,OAAO;QACS,mBAAmB,GAAnC,MAAM;QACW,OAAO,GAAxB,OAAO;sBA0EjB;IAGD;;;;;;;;;;;OAWG;IACH;QAVyB,MAAM,EAApB,MAAM;QACyB,GAAG;QACnB,mBAAmB,GAAlC,MAAM;QACU,UAAU,GAA1B,OAAO;QACO,GAAG,GAAjB,KAAK;QACU,YAAY,GAA3B,MAAM;QACU,YAAY,GAA5B,OAAO;QACO,OAAO,GAArB,KAAK;QACU,gBAAgB,GAA/B,MAAM;sBAqDhB;IAED;;;;;;;OAOG;IACH;QAN0B,YAAY,GAA3B,MAAM;QACQ,MAAM,EAApB,MAAM;QACS,WAAW,GAA1B,MAAM;QACyB,GAAG;QAChC,QAAQ,MAAM,CAAC,CA2C3B;IAGD;;;;;;;;;;OAUG;IACH,sFATW,MAAM,GAOJ,OAAO,CAsDnB;IA9cG;;;OAGG;IACH,QAFU,MAAM,CAEiC;IAMjD;;;OAGG;IACH,YAFU,eAAQ,IAAI,CAET;IA8BjB;;;;;OAKG;IACH;iCAJmB,mBAAmB,UAAQ,MAAM;8BACzC,OAAO;QACL,QAAQ,MAAM,CAAC,CA0D3B;CAqWJ;;IAID;;;OAGG;IACH,uCAMC;;mBA7gBkB,aAAa;oCACI,0BAA0B;oBAX1C,yBAAyB;mBAK1B,iBAAiB;sBATd,wBAAwB;oBAW1B,8BAA8B"}
+{"version":3,"file":"EngineHarness.d.ts","sourceRoot":"","sources":["../../../src/engine/EngineHarness.js"],"names":[],"mappings":"AA6DA;IAmBI;;;;OAIG;IACH,8CAHmB,mBAAmB,UAAQ,MAAM,WACxC,QAAQ,MAAM,CAAC,CAM1B;IAED;;;OAGG;IACH,6BAFW,MAAM,QAYhB;IAkED;;;;;;;;;;;;;OAaG;IACH;QAZyB,MAAM,EAApB,MAAM;QACyB,GAAG;QAClB,MAAM,GAAtB,OAAO;QACQ,QAAQ,GAAvB,MAAM;QACS,KAAK,GAApB,MAAM;QACS,GAAG,GAAlB,MAAM;QACU,QAAQ,GAAxB,OAAO;QACQ,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACJ,MAAM,CA+DlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QApB0B,MAAM,EAArB,MAAM;QACgC,KAAK,GAA3C;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC;QACrB,SAAS;QACT,WAAW;QACF,KAAK,GAArB,MAAM;QACU,GAAG,GAAnB,MAAM;QACU,QAAQ,GAAxB,MAAM;QACwB,WAAW,GAAzC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAC,CAAC,EAAC,MAAM,CAAA;SAAC;QACJ,iBAAiB,GAAjC,MAAM;QACW,WAAW,GAA5B,OAAO;QACU,aAAa,GAA9B,OAAO;QACU,YAAY,GAA7B,OAAO;QACU,aAAa,GAA9B,OAAO;QACS,iBAAiB,GAAjC,MAAM;QACU,iBAAiB,GAAjC,MAAM;QACW,gBAAgB,GAAjC,OAAO;QACU,cAAc,GAA/B,OAAO;QACS,mBAAmB,GAAnC,MAAM;QACW,OAAO,GAAxB,OAAO;sBA0EjB;IAGD;;;;;;;;;;;;OAYG;IACH;QAXyB,MAAM,EAApB,MAAM;QACyB,GAAG;QACnB,mBAAmB,GAAlC,MAAM;QACU,UAAU,GAA1B,OAAO;QACO,GAAG,GAAjB,KAAK;QACU,YAAY,GAA3B,MAAM;QACU,YAAY,GAA5B,OAAO;QACO,OAAO,GAArB,KAAK;QACU,gBAAgB,GAA/B,MAAM;QACS,iBAAiB,GAAhC,MAAM;sBAuDhB;IAED;;;;;;;OAOG;IACH;QAN0B,YAAY,GAA3B,MAAM;QACQ,MAAM,EAApB,MAAM;QACS,WAAW,GAA1B,MAAM;QACyB,GAAG;QAChC,QAAQ,MAAM,CAAC,CA2C3B;IAGD;;;;;;;;;;OAUG;IACH,sFATW,MAAM,GAOJ,OAAO,CAsDnB;IAjdG;;;OAGG;IACH,QAFU,MAAM,CAEiC;IAMjD;;;OAGG;IACH,YAFU,eAAQ,IAAI,CAET;IA8BjB;;;;;OAKG;IACH;iCAJmB,mBAAmB,UAAQ,MAAM;8BACzC,OAAO;QACL,QAAQ,MAAM,CAAC,CA0D3B;CAwWJ;;IAID;;;OAGG;IACH,uCAMC;;mBAhhBkB,aAAa;oCACI,0BAA0B;oBAX1C,yBAAyB;mBAK1B,iBAAiB;sBATd,wBAAwB;oBAW1B,8BAA8B"}

package/src/engine/EngineHarness.js

@@ -354,6 +354,7 @@ export class EngineHarness {
      * @param {Vector3} [param.sunDirection]
      * @param {Color} [param.ambient]
      * @param {number} [param.ambientIntensity]
+     * @param {number} [param.sunShadowDistance] Maximum draw distance for sun's shadow. Allows better use of shadowmap resolution.
      */
     static async buildLights({
                                  engine,
@@ -363,6 +364,7 @@ export class EngineHarness {
                                  sun = DEFAULT_SUNLIGHT_COLOR,
                                  sunIntensity = 0.9,
                                  sunDirection = new Vector3(0.17, -1, 0.17),
+                                 sunShadowDistance = 1000,
                                  ambient = Color.white,
                                  ambientIntensity = 0.1
                              }) {
@@ -381,6 +383,7 @@ export class EngineHarness {
         const key = new Light();
         key.type.set(Light.Type.DIRECTION);
         key.color.copy(sun);
+        key.maxShadowDistance.set(sunShadowDistance);
         key.intensity.set(sunIntensity);
         key.castShadow.set(castShadow);
 

package/src/engine/control/first-person/DESIGN.md

@@ -470,14 +470,38 @@ f = config.bob.stepFreqAtWalk
 ```
 At rest `f → 0` and bob amplitude clamps to 0, so the player stops bobbing when they stop.
 
-**Bob shape** (vertical uses `|sin|` so each footfall is a trough; horizontal uses half-rate sine so left/right alternate):
+**Bob shape**:
+
+`stridePhase ∈ [0, 1)` wraps once per stride (= 2 footsteps).
+
+Lateral and roll alternate ONCE per stride (head shifts right during right-foot midstance, left during left-foot midstance):
+```
+phase    = stridePhase * 2π                       // one full cycle per stride (= 2 steps)
+lateral  =  A_l * sin(phase) * intensity          // 1 full L↔R cycle per stride
+roll     =  A_r * sin(phase) * intensity          // in phase with lateral
+```
+
+Vertical is modeled as an **impulse-driven under-damped spring** rather than a sinusoid — the smooth `|sin|` curve we initially specified didn't match real gait dynamics (head is *highest* at midstance, *dips* at footfall under loading response, then is *pushed back up* by the standing leg). At each footfall event:
+```
+verticalImpactSpring.velocity -= A_v * impactKickMultiplier * intensity
 ```
-phase    = stridePhase * 2π                                  // one full cycle per 2 steps
-vert     = -A_v * |sin(phase)|        * speedNormalized
-lateral  =  A_l * sin(phase / 2)      * speedNormalized      // half-rate
-roll     =  A_r * sin(phase / 2)      * speedNormalized      // in phase with lateral
+Then each fixed step the spring damps toward zero with `halfLife ≈ 0.14 s`, `ζ ≈ 0.5`:
 ```
-Sign on `vert` is negative so the eye dips on footfall — this is what reads as "weight".
+verticalOffset = verticalImpactSpring.value     // negative during impact dip,
+                                                // positive during overshoot/push
+```
+
+The under-damped response produces the four-phase curve:
+1. **Impact** — sharp dip below neutral as the foot arrests the head's fall
+2. **Recovery** — value rises back through neutral
+3. **Push** — overshoot above neutral, modeling energy injection from the standing leg
+4. **Settle** — back toward neutral until the next footfall kicks it again
+
+At fast cadence (sprint) the spring barely settles between footfalls and the head oscillates continuously. At slow cadence (back-pedal) each impact is more punctuated, with visible settling between steps. This emerges from the dynamics — no separate handling needed.
+
+**Intensity envelope.** The `intensity` factor used by the lateral/roll/kick amplitudes is itself a critically damped spring around `max(speedNormalized, backwardness)` (or zero when airborne), with `halfLife ≈ 0.22 s`. This is what prevents the "whiplash" of stopping motion — bob amplitudes fade smoothly to zero instead of being cut off when speed drops below the stride threshold.
+
+> An even earlier draft of this doc used `sin(phase / 2)` for lateral and roll, intending a "half-rate" oscillation. That formula actually produces only the first *half* of a sine wave per stridePhase cycle (range [0, π) of sin → all non-negative), which manifested as a one-sided sustained offset for the duration of one stride. The current `sin(phase)` formulation alternates correctly.
 
 **Footstep detection**: emit `onFootStep` when `stridePhase` crosses `0` (right foot) or `0.5` (left foot), but only if `state.grounded && speed > minStepSpeed`. The boundary check uses the *previous* phase so it fires exactly once even at huge dt.