@wave3d/core 0.6.0 → 0.8.0

package/dist/renderer/WaveGeometry.d.ts

@@ -4,8 +4,8 @@ import * as THREE from "three";
  * Base wave geometry — `folded()`: a flat PlaneGeometry folded into a hairpin
  * (sideways-U) cross-section, then stood up so the fold runs along the wave's length.
  *
- *   - Each vertex gets a half-thickness `r` (per-vertex math below): tight along the
- *     width centreline, flaring toward the long edges.
+ *   - Each vertex gets a half-thickness `r` (per-vertex math below): tight at the middle
+ *     of the wave's length, flaring toward both ends.
  *   - The strip |x| < FOLD_X becomes a semicircular hinge; the plane's two halves bend
  *     around it into parallel arms offset to +r and -r.
  *   - Two −90° rotations (about X then Y) orient the U upright and down its length.
@@ -16,7 +16,26 @@ import * as THREE from "three";
  * faces only, no vertex positions move.
  *
  * All further deformation (displacement, twist, transform) happens in the vertex shader
- * on top of this base. UVs: u along the fold/length, v across the width.
+ * on top of this base.
+ *
+ * UV AXES — the canonical statement, because this is easy to get backwards and the rest of
+ * the codebase reasons in uv. The plane is folded along its local x, which is the COLUMN
+ * direction (uv.x), and the two −90° rotations land world = (plane.y, plane.z, plane.x):
+ *
+ *   uv.y → the ribbon's 400-unit LENGTH (world X — the axis `displaceFrequency.x` drives)
+ *   uv.x → the folded ~188-unit WIDTH, wrapping the hairpin cross-section (world Z)
+ *
+ * So u runs ACROSS the fold and v runs ALONG it. The welding below corroborates it twice:
+ * the end-caps fan across columns at rows v=0 / v=subX, and the seam joins col 0 to col
+ * subX down every row — a join that necessarily runs the full length. Measured on a built
+ * mesh, the correlation of uv.y with world X is exactly 1.0, and of uv.x with world X, 0.
+ * (uv.x vs world Z also reads 0 — the fold's own signature: a monotone mapping would give
+ * ±1, but the hairpin runs out along one arm and back along the other.)
+ *
+ * Consequences that read backwards if you assume otherwise: a `NoiseBand`'s startX/endX
+ * are the SHORT axis; `edgeFeather` softens the two ends, not the long edges; the palette
+ * texture's "edge tint" lands on the ends; `parabolaPower` bunches streaks toward the long
+ * edges; and the twist X/Z falloffs run lengthwise while Y runs across the width.
  */
 declare class WaveGeometry {
   readonly geometry: THREE.BufferGeometry;

package/dist/renderer/WaveGeometry.js

@@ -11,8 +11,8 @@ const Y_AXIS = new THREE.Vector3(0, 1, 0);
 * Base wave geometry — `folded()`: a flat PlaneGeometry folded into a hairpin
 * (sideways-U) cross-section, then stood up so the fold runs along the wave's length.
 *
-*   - Each vertex gets a half-thickness `r` (per-vertex math below): tight along the
-*     width centreline, flaring toward the long edges.
+*   - Each vertex gets a half-thickness `r` (per-vertex math below): tight at the middle
+*     of the wave's length, flaring toward both ends.
 *   - The strip |x| < FOLD_X becomes a semicircular hinge; the plane's two halves bend
 *     around it into parallel arms offset to +r and -r.
 *   - Two −90° rotations (about X then Y) orient the U upright and down its length.
@@ -23,7 +23,26 @@ const Y_AXIS = new THREE.Vector3(0, 1, 0);
 * faces only, no vertex positions move.
 *
 * All further deformation (displacement, twist, transform) happens in the vertex shader
-* on top of this base. UVs: u along the fold/length, v across the width.
+* on top of this base.
+*
+* UV AXES — the canonical statement, because this is easy to get backwards and the rest of
+* the codebase reasons in uv. The plane is folded along its local x, which is the COLUMN
+* direction (uv.x), and the two −90° rotations land world = (plane.y, plane.z, plane.x):
+*
+*   uv.y → the ribbon's 400-unit LENGTH (world X — the axis `displaceFrequency.x` drives)
+*   uv.x → the folded ~188-unit WIDTH, wrapping the hairpin cross-section (world Z)
+*
+* So u runs ACROSS the fold and v runs ALONG it. The welding below corroborates it twice:
+* the end-caps fan across columns at rows v=0 / v=subX, and the seam joins col 0 to col
+* subX down every row — a join that necessarily runs the full length. Measured on a built
+* mesh, the correlation of uv.y with world X is exactly 1.0, and of uv.x with world X, 0.
+* (uv.x vs world Z also reads 0 — the fold's own signature: a monotone mapping would give
+* ±1, but the hairpin runs out along one arm and back along the other.)
+*
+* Consequences that read backwards if you assume otherwise: a `NoiseBand`'s startX/endX
+* are the SHORT axis; `edgeFeather` softens the two ends, not the long edges; the palette
+* texture's "edge tint" lands on the ends; `parabolaPower` bunches streaks toward the long
+* edges; and the twist X/Z falloffs run lengthwise while Y runs across the width.
 */
 var WaveGeometry = class {
 	geometry;

package/dist/renderer/WaveGeometry.js.map

@@ -1 +1 @@
-{"version":3,"file":"WaveGeometry.js","names":[],"sources":["../../src/renderer/WaveGeometry.ts"],"sourcesContent":["import * as THREE from \"three\";\n\n/** Native plane size for folded() — keep this exact (400) so the vertex\n *  shader's displace/twist frequencies (calibrated to this scale) stay faithful. */\nconst NATIVE = 400;\nconst FOLD_X = 16; // |x| < 16 is the semicircular hinge; outside it the two flat arms\nconst SHIFT = NATIVE / 4; // recentre the folded cross-section along x\n\nconst X_AXIS = new THREE.Vector3(1, 0, 0);\nconst Y_AXIS = new THREE.Vector3(0, 1, 0);\n\n/**\n * Local-Z centre of the folded ribbon's width. The fold collapses x ∈ [-NATIVE/2, NATIVE/2] onto a\n * single arm and SHIFT recentres it, which lands the width at [-100, 84] rather than symmetric\n * about 0 — so a rotation about local X through the ORIGIN would swing the ribbon's two long edges\n * to radii 100 and 84 (a visibly lopsided helix). The vertex shader's helix roll rotates about this\n * line instead, so both edges come out at equal radius.\n */\nexport const RIBBON_Z_CENTER = (SHIFT - NATIVE / 2 + (SHIFT - FOLD_X)) / 2;\n\n/**\n * Base wave geometry — `folded()`: a flat PlaneGeometry folded into a hairpin\n * (sideways-U) cross-section, then stood up so the fold runs along the wave's length.\n *\n *   - Each vertex gets a half-thickness `r` (per-vertex math below): tight along the\n *     width centreline, flaring toward the long edges.\n *   - The strip |x| < FOLD_X becomes a semicircular hinge; the plane's two halves bend\n *     around it into parallel arms offset to +r and -r.\n *   - Two −90° rotations (about X then Y) orient the U upright and down its length.\n *\n * folded() leaves the U open along one side and hollow at both ends, so at oblique\n * camera angles you could see straight through it. We weld the open side and cap both\n * ends with extra triangles so the mesh is a watertight solid — welding/capping adds\n * faces only, no vertex positions move.\n *\n * All further deformation (displacement, twist, transform) happens in the vertex shader\n * on top of this base. UVs: u along the fold/length, v across the width.\n */\nexport class WaveGeometry {\n  readonly geometry: THREE.BufferGeometry;\n  private segments = -1;\n\n  constructor(segments: number) {\n    this.geometry = new THREE.BufferGeometry();\n    this.resize(segments);\n  }\n\n  resize(segments: number): void {\n    if (segments === this.segments) return;\n    this.segments = segments;\n\n    // subX along the fold, subY across the width (twice as dense).\n    const subX = THREE.MathUtils.clamp(Math.round(segments), 48, 200);\n    const subY = subX * 2;\n\n    const plane = new THREE.PlaneGeometry(NATIVE, NATIVE, subX, subY);\n    const pos = plane.attributes.position as THREE.BufferAttribute;\n    const uv = plane.attributes.uv as THREE.BufferAttribute;\n    const v = new THREE.Vector3();\n\n    for (let i = 0; i < pos.count; i++) {\n      v.fromBufferAttribute(pos, i);\n      const uy = uv.getY(i);\n      // r: cross-section half-thickness — tight (2) along the width centreline, flaring (4)\n      // toward the long edges. The pow() term is a sharp parabolic bump peaking at uv.y = 0.5.\n      const r = 4 - 2 * Math.pow(4 * uy * (1 - uy), 9.5);\n\n      if (v.x < -FOLD_X) {\n        v.z += r; // long arm, at +r\n      } else if (v.x < FOLD_X) {\n        // semicircular hinge: z sweeps +r → -r, x collapses to the bend\n        v.z = Math.cos(THREE.MathUtils.mapLinear(v.x, -FOLD_X, FOLD_X, 0, Math.PI)) * r;\n        v.x =\n          Math.cos(THREE.MathUtils.mapLinear(v.x, -FOLD_X, FOLD_X, -Math.PI / 2, Math.PI / 2)) * r -\n          FOLD_X;\n      } else {\n        v.z -= r; // folded-over arm, mirrored back at -r\n        v.x = -v.x;\n      }\n\n      v.x += SHIFT;\n      v.applyAxisAngle(X_AXIS, -Math.PI / 2);\n      v.applyAxisAngle(Y_AXIS, -Math.PI / 2);\n      pos.setXYZ(i, v.x, v.y, v.z);\n    }\n    pos.needsUpdate = true;\n\n    // Seal the hairpin's OPEN side. folded() leaves the two arm tips unconnected — the\n    // plane's u=0 and u=subX edges, which fold to adjacent tips at +r and -r — so at oblique\n    // camera angles you can see through the U to the background. Weld those two edges with a\n    // strip of triangles, closing the tube. No vertex positions move; this only adds faces\n    // over the previously-open seam.\n    const cols = subX + 1;\n    const srcIdx = plane.getIndex();\n    const merged = srcIdx ? Array.from(srcIdx.array as ArrayLike<number>) : [];\n    // (a) Weld the U's side opening: the u=0 and u=subX edges fold to adjacent tips at ±r.\n    for (let iy = 0; iy < subY; iy++) {\n      const a = iy * cols; // (row iy, col 0)  — arm-A tip\n      const b = (iy + 1) * cols; // (row iy+1, col 0)\n      const c = a + subX; // (row iy, col subX) — arm-B tip\n      const d = b + subX; // (row iy+1, col subX)\n      merged.push(a, c, b, b, c, d);\n    }\n    // (b) Cap the two length-ends (v=0 and v=subX rows): the folded sheet is a hollow channel\n    // open at both ends, so an edge-on camera sees straight through it. Fan-triangulate each\n    // end's U cross-section (apex = the col-0 tip) to close it — making the wave a closed solid.\n    for (const row of [0, subY]) {\n      const apex = row * cols;\n      for (let ix = 1; ix < subX; ix++) merged.push(apex, row * cols + ix, row * cols + ix + 1);\n    }\n    plane.setIndex(merged);\n\n    plane.computeVertexNormals();\n\n    // Move the baked attributes onto our reusable geometry, then drop the temp.\n    this.geometry.setIndex(plane.getIndex());\n    this.geometry.setAttribute(\"position\", plane.getAttribute(\"position\"));\n    this.geometry.setAttribute(\"uv\", plane.getAttribute(\"uv\"));\n    this.geometry.setAttribute(\"normal\", plane.getAttribute(\"normal\"));\n    this.geometry.computeBoundingSphere();\n    plane.dispose();\n  }\n\n  dispose(): void {\n    this.geometry.dispose();\n  }\n}\n"],"mappings":";;;;AAIA,MAAM,SAAS;AACf,MAAM,SAAS;AACf,MAAM,QAAQ,SAAS;AAEvB,MAAM,SAAS,IAAI,MAAM,QAAQ,GAAG,GAAG,CAAC;AACxC,MAAM,SAAS,IAAI,MAAM,QAAQ,GAAG,GAAG,CAAC;;;;;;;;;;;;;;;;;;;AA6BxC,IAAa,eAAb,MAA0B;CACxB;CACA,WAAmB;CAEnB,YAAY,UAAkB;EAC5B,KAAK,WAAW,IAAI,MAAM,eAAe;EACzC,KAAK,OAAO,QAAQ;CACtB;CAEA,OAAO,UAAwB;EAC7B,IAAI,aAAa,KAAK,UAAU;EAChC,KAAK,WAAW;EAGhB,MAAM,OAAO,MAAM,UAAU,MAAM,KAAK,MAAM,QAAQ,GAAG,IAAI,GAAG;EAChE,MAAM,OAAO,OAAO;EAEpB,MAAM,QAAQ,IAAI,MAAM,cAAc,QAAQ,QAAQ,MAAM,IAAI;EAChE,MAAM,MAAM,MAAM,WAAW;EAC7B,MAAM,KAAK,MAAM,WAAW;EAC5B,MAAM,IAAI,IAAI,MAAM,QAAQ;EAE5B,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,OAAO,KAAK;GAClC,EAAE,oBAAoB,KAAK,CAAC;GAC5B,MAAM,KAAK,GAAG,KAAK,CAAC;GAGpB,MAAM,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,GAAG;GAEjD,IAAI,EAAE,IAAI,KACR,EAAE,KAAK;QACF,IAAI,EAAE,IAAI,QAAQ;IAEvB,EAAE,IAAI,KAAK,IAAI,MAAM,UAAU,UAAU,EAAE,GAAG,KAAS,QAAQ,GAAG,KAAK,EAAE,CAAC,IAAI;IAC9E,EAAE,IACA,KAAK,IAAI,MAAM,UAAU,UAAU,EAAE,GAAG,KAAS,QAAQ,CAAC,KAAK,KAAK,GAAG,KAAK,KAAK,CAAC,CAAC,IAAI,IACvF;GACJ,OAAO;IACL,EAAE,KAAK;IACP,EAAE,IAAI,CAAC,EAAE;GACX;GAEA,EAAE,KAAK;GACP,EAAE,eAAe,QAAQ,CAAC,KAAK,KAAK,CAAC;GACrC,EAAE,eAAe,QAAQ,CAAC,KAAK,KAAK,CAAC;GACrC,IAAI,OAAO,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;EAC7B;EACA,IAAI,cAAc;EAOlB,MAAM,OAAO,OAAO;EACpB,MAAM,SAAS,MAAM,SAAS;EAC9B,MAAM,SAAS,SAAS,MAAM,KAAK,OAAO,KAA0B,IAAI,CAAC;EAEzE,KAAK,IAAI,KAAK,GAAG,KAAK,MAAM,MAAM;GAChC,MAAM,IAAI,KAAK;GACf,MAAM,KAAK,KAAK,KAAK;GACrB,MAAM,IAAI,IAAI;GACd,MAAM,IAAI,IAAI;GACd,OAAO,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;EAC9B;EAIA,KAAK,MAAM,OAAO,CAAC,GAAG,IAAI,GAAG;GAC3B,MAAM,OAAO,MAAM;GACnB,KAAK,IAAI,KAAK,GAAG,KAAK,MAAM,MAAM,OAAO,KAAK,MAAM,MAAM,OAAO,IAAI,MAAM,OAAO,KAAK,CAAC;EAC1F;EACA,MAAM,SAAS,MAAM;EAErB,MAAM,qBAAqB;EAG3B,KAAK,SAAS,SAAS,MAAM,SAAS,CAAC;EACvC,KAAK,SAAS,aAAa,YAAY,MAAM,aAAa,UAAU,CAAC;EACrE,KAAK,SAAS,aAAa,MAAM,MAAM,aAAa,IAAI,CAAC;EACzD,KAAK,SAAS,aAAa,UAAU,MAAM,aAAa,QAAQ,CAAC;EACjE,KAAK,SAAS,sBAAsB;EACpC,MAAM,QAAQ;CAChB;CAEA,UAAgB;EACd,KAAK,SAAS,QAAQ;CACxB;AACF"}
+{"version":3,"file":"WaveGeometry.js","names":[],"sources":["../../src/renderer/WaveGeometry.ts"],"sourcesContent":["import * as THREE from \"three\";\n\n/** Native plane size for folded() — keep this exact (400) so the vertex\n *  shader's displace/twist frequencies (calibrated to this scale) stay faithful. */\nconst NATIVE = 400;\nconst FOLD_X = 16; // |x| < 16 is the semicircular hinge; outside it the two flat arms\nconst SHIFT = NATIVE / 4; // recentre the folded cross-section along x\n\nconst X_AXIS = new THREE.Vector3(1, 0, 0);\nconst Y_AXIS = new THREE.Vector3(0, 1, 0);\n\n/**\n * Local-Z centre of the folded ribbon's width. The fold collapses x ∈ [-NATIVE/2, NATIVE/2] onto a\n * single arm and SHIFT recentres it, which lands the width at [-100, 84] rather than symmetric\n * about 0 — so a rotation about local X through the ORIGIN would swing the ribbon's two long edges\n * to radii 100 and 84 (a visibly lopsided helix). The vertex shader's helix roll rotates about this\n * line instead, so both edges come out at equal radius.\n */\nexport const RIBBON_Z_CENTER = (SHIFT - NATIVE / 2 + (SHIFT - FOLD_X)) / 2;\n\n/**\n * Base wave geometry — `folded()`: a flat PlaneGeometry folded into a hairpin\n * (sideways-U) cross-section, then stood up so the fold runs along the wave's length.\n *\n *   - Each vertex gets a half-thickness `r` (per-vertex math below): tight at the middle\n *     of the wave's length, flaring toward both ends.\n *   - The strip |x| < FOLD_X becomes a semicircular hinge; the plane's two halves bend\n *     around it into parallel arms offset to +r and -r.\n *   - Two −90° rotations (about X then Y) orient the U upright and down its length.\n *\n * folded() leaves the U open along one side and hollow at both ends, so at oblique\n * camera angles you could see straight through it. We weld the open side and cap both\n * ends with extra triangles so the mesh is a watertight solid — welding/capping adds\n * faces only, no vertex positions move.\n *\n * All further deformation (displacement, twist, transform) happens in the vertex shader\n * on top of this base.\n *\n * UV AXES — the canonical statement, because this is easy to get backwards and the rest of\n * the codebase reasons in uv. The plane is folded along its local x, which is the COLUMN\n * direction (uv.x), and the two −90° rotations land world = (plane.y, plane.z, plane.x):\n *\n *   uv.y → the ribbon's 400-unit LENGTH (world X — the axis `displaceFrequency.x` drives)\n *   uv.x → the folded ~188-unit WIDTH, wrapping the hairpin cross-section (world Z)\n *\n * So u runs ACROSS the fold and v runs ALONG it. The welding below corroborates it twice:\n * the end-caps fan across columns at rows v=0 / v=subX, and the seam joins col 0 to col\n * subX down every row — a join that necessarily runs the full length. Measured on a built\n * mesh, the correlation of uv.y with world X is exactly 1.0, and of uv.x with world X, 0.\n * (uv.x vs world Z also reads 0 — the fold's own signature: a monotone mapping would give\n * ±1, but the hairpin runs out along one arm and back along the other.)\n *\n * Consequences that read backwards if you assume otherwise: a `NoiseBand`'s startX/endX\n * are the SHORT axis; `edgeFeather` softens the two ends, not the long edges; the palette\n * texture's \"edge tint\" lands on the ends; `parabolaPower` bunches streaks toward the long\n * edges; and the twist X/Z falloffs run lengthwise while Y runs across the width.\n */\nexport class WaveGeometry {\n  readonly geometry: THREE.BufferGeometry;\n  private segments = -1;\n\n  constructor(segments: number) {\n    this.geometry = new THREE.BufferGeometry();\n    this.resize(segments);\n  }\n\n  resize(segments: number): void {\n    if (segments === this.segments) return;\n    this.segments = segments;\n\n    // subX across the fold (the cross-section), subY along the length (twice as dense).\n    const subX = THREE.MathUtils.clamp(Math.round(segments), 48, 200);\n    const subY = subX * 2;\n\n    const plane = new THREE.PlaneGeometry(NATIVE, NATIVE, subX, subY);\n    const pos = plane.attributes.position as THREE.BufferAttribute;\n    const uv = plane.attributes.uv as THREE.BufferAttribute;\n    const v = new THREE.Vector3();\n\n    for (let i = 0; i < pos.count; i++) {\n      v.fromBufferAttribute(pos, i);\n      const uy = uv.getY(i);\n      // r: cross-section half-thickness — tight (2) at the middle of the length, flaring (4)\n      // toward both ends. The pow() term is a sharp parabolic bump peaking at uv.y = 0.5.\n      const r = 4 - 2 * Math.pow(4 * uy * (1 - uy), 9.5);\n\n      if (v.x < -FOLD_X) {\n        v.z += r; // long arm, at +r\n      } else if (v.x < FOLD_X) {\n        // semicircular hinge: z sweeps +r → -r, x collapses to the bend\n        v.z = Math.cos(THREE.MathUtils.mapLinear(v.x, -FOLD_X, FOLD_X, 0, Math.PI)) * r;\n        v.x =\n          Math.cos(THREE.MathUtils.mapLinear(v.x, -FOLD_X, FOLD_X, -Math.PI / 2, Math.PI / 2)) * r -\n          FOLD_X;\n      } else {\n        v.z -= r; // folded-over arm, mirrored back at -r\n        v.x = -v.x;\n      }\n\n      v.x += SHIFT;\n      v.applyAxisAngle(X_AXIS, -Math.PI / 2);\n      v.applyAxisAngle(Y_AXIS, -Math.PI / 2);\n      pos.setXYZ(i, v.x, v.y, v.z);\n    }\n    pos.needsUpdate = true;\n\n    // Seal the hairpin's OPEN side. folded() leaves the two arm tips unconnected — the\n    // plane's u=0 and u=subX edges, which fold to adjacent tips at +r and -r — so at oblique\n    // camera angles you can see through the U to the background. Weld those two edges with a\n    // strip of triangles, closing the tube. No vertex positions move; this only adds faces\n    // over the previously-open seam.\n    const cols = subX + 1;\n    const srcIdx = plane.getIndex();\n    const merged = srcIdx ? Array.from(srcIdx.array as ArrayLike<number>) : [];\n    // (a) Weld the U's side opening: the u=0 and u=subX edges fold to adjacent tips at ±r.\n    for (let iy = 0; iy < subY; iy++) {\n      const a = iy * cols; // (row iy, col 0)  — arm-A tip\n      const b = (iy + 1) * cols; // (row iy+1, col 0)\n      const c = a + subX; // (row iy, col subX) — arm-B tip\n      const d = b + subX; // (row iy+1, col subX)\n      merged.push(a, c, b, b, c, d);\n    }\n    // (b) Cap the two length-ends (v=0 and v=subX rows): the folded sheet is a hollow channel\n    // open at both ends, so an edge-on camera sees straight through it. Fan-triangulate each\n    // end's U cross-section (apex = the col-0 tip) to close it — making the wave a closed solid.\n    for (const row of [0, subY]) {\n      const apex = row * cols;\n      for (let ix = 1; ix < subX; ix++) merged.push(apex, row * cols + ix, row * cols + ix + 1);\n    }\n    plane.setIndex(merged);\n\n    plane.computeVertexNormals();\n\n    // Move the baked attributes onto our reusable geometry, then drop the temp.\n    this.geometry.setIndex(plane.getIndex());\n    this.geometry.setAttribute(\"position\", plane.getAttribute(\"position\"));\n    this.geometry.setAttribute(\"uv\", plane.getAttribute(\"uv\"));\n    this.geometry.setAttribute(\"normal\", plane.getAttribute(\"normal\"));\n    this.geometry.computeBoundingSphere();\n    plane.dispose();\n  }\n\n  dispose(): void {\n    this.geometry.dispose();\n  }\n}\n"],"mappings":";;;;AAIA,MAAM,SAAS;AACf,MAAM,SAAS;AACf,MAAM,QAAQ,SAAS;AAEvB,MAAM,SAAS,IAAI,MAAM,QAAQ,GAAG,GAAG,CAAC;AACxC,MAAM,SAAS,IAAI,MAAM,QAAQ,GAAG,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDxC,IAAa,eAAb,MAA0B;CACxB;CACA,WAAmB;CAEnB,YAAY,UAAkB;EAC5B,KAAK,WAAW,IAAI,MAAM,eAAe;EACzC,KAAK,OAAO,QAAQ;CACtB;CAEA,OAAO,UAAwB;EAC7B,IAAI,aAAa,KAAK,UAAU;EAChC,KAAK,WAAW;EAGhB,MAAM,OAAO,MAAM,UAAU,MAAM,KAAK,MAAM,QAAQ,GAAG,IAAI,GAAG;EAChE,MAAM,OAAO,OAAO;EAEpB,MAAM,QAAQ,IAAI,MAAM,cAAc,QAAQ,QAAQ,MAAM,IAAI;EAChE,MAAM,MAAM,MAAM,WAAW;EAC7B,MAAM,KAAK,MAAM,WAAW;EAC5B,MAAM,IAAI,IAAI,MAAM,QAAQ;EAE5B,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,OAAO,KAAK;GAClC,EAAE,oBAAoB,KAAK,CAAC;GAC5B,MAAM,KAAK,GAAG,KAAK,CAAC;GAGpB,MAAM,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,GAAG;GAEjD,IAAI,EAAE,IAAI,KACR,EAAE,KAAK;QACF,IAAI,EAAE,IAAI,QAAQ;IAEvB,EAAE,IAAI,KAAK,IAAI,MAAM,UAAU,UAAU,EAAE,GAAG,KAAS,QAAQ,GAAG,KAAK,EAAE,CAAC,IAAI;IAC9E,EAAE,IACA,KAAK,IAAI,MAAM,UAAU,UAAU,EAAE,GAAG,KAAS,QAAQ,CAAC,KAAK,KAAK,GAAG,KAAK,KAAK,CAAC,CAAC,IAAI,IACvF;GACJ,OAAO;IACL,EAAE,KAAK;IACP,EAAE,IAAI,CAAC,EAAE;GACX;GAEA,EAAE,KAAK;GACP,EAAE,eAAe,QAAQ,CAAC,KAAK,KAAK,CAAC;GACrC,EAAE,eAAe,QAAQ,CAAC,KAAK,KAAK,CAAC;GACrC,IAAI,OAAO,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;EAC7B;EACA,IAAI,cAAc;EAOlB,MAAM,OAAO,OAAO;EACpB,MAAM,SAAS,MAAM,SAAS;EAC9B,MAAM,SAAS,SAAS,MAAM,KAAK,OAAO,KAA0B,IAAI,CAAC;EAEzE,KAAK,IAAI,KAAK,GAAG,KAAK,MAAM,MAAM;GAChC,MAAM,IAAI,KAAK;GACf,MAAM,KAAK,KAAK,KAAK;GACrB,MAAM,IAAI,IAAI;GACd,MAAM,IAAI,IAAI;GACd,OAAO,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;EAC9B;EAIA,KAAK,MAAM,OAAO,CAAC,GAAG,IAAI,GAAG;GAC3B,MAAM,OAAO,MAAM;GACnB,KAAK,IAAI,KAAK,GAAG,KAAK,MAAM,MAAM,OAAO,KAAK,MAAM,MAAM,OAAO,IAAI,MAAM,OAAO,KAAK,CAAC;EAC1F;EACA,MAAM,SAAS,MAAM;EAErB,MAAM,qBAAqB;EAG3B,KAAK,SAAS,SAAS,MAAM,SAAS,CAAC;EACvC,KAAK,SAAS,aAAa,YAAY,MAAM,aAAa,UAAU,CAAC;EACrE,KAAK,SAAS,aAAa,MAAM,MAAM,aAAa,IAAI,CAAC;EACzD,KAAK,SAAS,aAAa,UAAU,MAAM,aAAa,QAAQ,CAAC;EACjE,KAAK,SAAS,sBAAsB;EACpC,MAAM,QAAQ;CAChB;CAEA,UAAgB;EACd,KAAK,SAAS,QAAQ;CACxB;AACF"}

package/dist/renderer/WaveRenderer.d.ts

@@ -1,5 +1,6 @@
 import { CameraFit, StudioConfig, WaveConfig } from "../config/model.js";
 import { WaveGeometry } from "./WaveGeometry.js";
+import { ParticleField } from "./particleField.js";
 import { InteractionController } from "./interaction.js";
 import * as THREE from "three";
 //#region src/renderer/WaveRenderer.d.ts
@@ -66,6 +67,9 @@ type Wave = {
   geometry: WaveGeometry;
   /** This wave's own 2D palette texture + optional video. */
   palette: WavePalette;
+  /** This wave's own particle / dust field — created when its `particles.count` first goes >0,
+   *  disposed at 0 / absent (the WavePalette lifecycle pattern). Undefined = no dust for this wave. */
+  particleField?: ParticleField;
 };
 /** Convert an sRGB hex string to a linear-space RGB vector (three's ColorManagement does the
  *  sRGB→linear conversion on parse). Exported for the studio subclass's live light-uniform push. */
@@ -90,6 +94,9 @@ declare class WaveRenderer {
   private heatmapPass?;
   private paperTexturePass?;
   private halftoneCmykPass?;
+  private readonly fxCenter;
+  private readonly fxRight;
+  private readonly fxUp;
   protected readonly container: HTMLElement;
   private readonly respectReducedMotion;
   private readonly skipIntroRamp;
@@ -260,6 +267,21 @@ declare class WaveRenderer {
   private updateTime;
   /** Render exactly one frame at the current time. */
   renderOnce(): void;
+  /** Insert / sync / remove EACH wave's particle field — mirrors applyBloom's lazy lifecycle, per wave.
+   *  An absent block or count 0 means no THREE.Points for that wave (byte-identical). The seeded buffers
+   *  rebuild only when the (count, seed, edgeBias, bias) signature changes; the rest are live uniforms.
+   *  configure() (the wave-shape binding) runs later in updateSceneFx, once transforms are current. */
+  private applyParticles;
+  /** Per-frame placement for every wave's particle field: derive the camera's screen basis + each
+   *  wave's world centre (drift radiates from there) and bind that wave's live shape (#defines +
+   *  uniforms + matrixWorld) so the dust rides the SAME deform as the ribbon. Runs after refresh()'s
+   *  per-wave loop so the wave transforms/uniforms are current. No allocation; a no-op when off. */
+  private updateSceneFx;
+  /** The subset of waveDefines() the particle program shares: the shape gates (what waveShape reads,
+   *  so the dust matches its wave's deform) plus the pointer gates (what pointerField reads, so the
+   *  dust reacts to the same cursor). Every one of these is derived from CONFIG alone — live input
+   *  must never reach here, or each frame would flip the define set and recompile the point program. */
+  private shapeDefines;
   /** Create/dispose the interaction controller as config toggles interaction on/off. Called from
    *  refresh(); the compiled define set (POINTER_FX etc.) is handled separately by waveDefines(). */
   private syncInteraction;

package/dist/renderer/WaveRenderer.js

@@ -2,6 +2,7 @@ import { ensureStudioConfig } from "../config/model.js";
 import { WaveGeometry } from "./WaveGeometry.js";
 import { ditherFragmentShader, fragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, postFragmentShader, postVertexShader, vertexShader } from "./shaders.js";
 import { InteractionController, SCENE_APPLIERS, WAVE_APPLIERS, anyPointerFxActive, interactionActive, wavePointerFxActive, waveRipplesActive } from "./interaction.js";
+import { ParticleField } from "./particleField.js";
 import { PALETTE_MAPS, buildBackgroundGradientCanvas, buildBackgroundImageCanvas, buildBackgroundMeshCanvas, buildPaletteTexture, canvasToTexture, configurePaletteTexture, drawBackgroundMediaFrame, loadPaletteImage, paletteMapCanvas, paletteSignature } from "./palette.js";
 import { buildHeroPaletteCanvas, buildHeroPaletteTexture } from "./heroPalette.js";
 import * as THREE from "three";
@@ -186,6 +187,9 @@ var WaveRenderer = class {
 	heatmapPass;
 	paperTexturePass;
 	halftoneCmykPass;
+	fxCenter = new THREE.Vector3();
+	fxRight = new THREE.Vector3();
+	fxUp = new THREE.Vector3();
 	container;
 	respectReducedMotion;
 	skipIntroRamp;
@@ -411,6 +415,11 @@ var WaveRenderer = class {
 			uHelixRadius: { value: 0 },
 			uHelixRoll: { value: 0 },
 			uHelixPhase: { value: 0 },
+			uRadialAmount: { value: 0 },
+			uRadialArc: { value: 160 },
+			uRadialSpread: { value: 1 },
+			uRadialRadius: { value: 40 },
+			uRadialCenter: { value: 0 },
 			uRungAmount: { value: 0 },
 			uRungThickness: { value: 1 },
 			uPointer: { value: new THREE.Vector2(0, 0) },
@@ -444,6 +453,7 @@ var WaveRenderer = class {
 		if ((sc?.edgeFeather ?? .1) !== .1) defines.EDGE_FEATHER = "";
 		const bindsHelix = sc?.interaction?.bindings?.some((b) => b.target.startsWith("helix")) ?? false;
 		if ((sc?.helixRadius ?? 0) !== 0 || (sc?.helixRoll ?? 0) !== 0 || bindsHelix) defines.HELIX = "";
+		if ((sc?.radialAmount ?? 0) !== 0) defines.RADIAL = "";
 		if (sc?.theme === "wireframe" && (sc.rungAmount ?? 0) > 0) defines.RUNGS = "";
 		if (sc && wavePointerFxActive(this.config, sc)) {
 			defines.POINTER_FX = "";
@@ -505,6 +515,10 @@ var WaveRenderer = class {
 			s.material.dispose();
 			s.geometry.dispose();
 			s.palette.dispose();
+			if (s.particleField) {
+				this.scene.remove(s.particleField.points);
+				s.particleField.dispose();
+			}
 		}
 		this.waves = [];
 	}
@@ -523,6 +537,10 @@ var WaveRenderer = class {
 			s.material.dispose();
 			s.geometry.dispose();
 			s.palette.dispose();
+			if (s.particleField) {
+				this.scene.remove(s.particleField.points);
+				s.particleField.dispose();
+			}
 		}
 		while (this.waves.length < target) this.addWave();
 		const segments = this.segments;
@@ -536,6 +554,7 @@ var WaveRenderer = class {
 	refresh() {
 		this.applyBackground();
 		this.applyPost();
+		this.applyParticles();
 		this.syncInteraction();
 		if (!this.isCameraExternallyDriven()) {
 			const p = this.config.cameraPosition;
@@ -658,6 +677,11 @@ var WaveRenderer = class {
 			u.uHelixRadius.value = sc.helixRadius ?? 0;
 			u.uHelixRoll.value = sc.helixRoll ?? 0;
 			u.uHelixPhase.value = sc.helixPhase ?? 0;
+			u.uRadialAmount.value = sc.radialAmount ?? 0;
+			u.uRadialArc.value = sc.radialArc ?? 160;
+			u.uRadialSpread.value = sc.radialSpread ?? 1;
+			u.uRadialRadius.value = sc.radialRadius ?? 40;
+			u.uRadialCenter.value = sc.radialCenter ?? 0;
 			wave.mesh.scale.set(sc.scale.x, sc.scale.y, sc.scale.z);
 			wave.mesh.rotation.set(THREE.MathUtils.degToRad(sc.rotation.x), THREE.MathUtils.degToRad(sc.rotation.y), THREE.MathUtils.degToRad(sc.rotation.z));
 			wave.mesh.position.set(sc.position.x, sc.position.y, sc.position.z);
@@ -1308,16 +1332,95 @@ var WaveRenderer = class {
 			}
 		}
 		this.postPass.uniforms.uTime.value = t;
+		for (const w of this.waves) w.particleField?.setTime(t);
 	}
 	/** Render exactly one frame at the current time. */
 	renderOnce() {
 		this.updateBackgroundVideoFrame();
 		this.updateTime();
 		this.applyInteraction();
+		this.updateSceneFx();
 		this.updateClipPlanes();
 		this.composer.render();
 		this.onAfterRenderFrame();
 	}
+	/** Insert / sync / remove EACH wave's particle field — mirrors applyBloom's lazy lifecycle, per wave.
+	*  An absent block or count 0 means no THREE.Points for that wave (byte-identical). The seeded buffers
+	*  rebuild only when the (count, seed, edgeBias, bias) signature changes; the rest are live uniforms.
+	*  configure() (the wave-shape binding) runs later in updateSceneFx, once transforms are current. */
+	applyParticles() {
+		const loop = this.config.loopSeconds ?? 0;
+		this.waves.forEach((wave, i) => {
+			const cfg = (this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1])?.particles;
+			if (cfg && cfg.count > 0) {
+				if (!wave.particleField) {
+					wave.particleField = new ParticleField(() => {
+						if (!this.running) this.renderOnce();
+					});
+					this.scene.add(wave.particleField.points);
+				}
+				wave.particleField.sync(cfg, loop);
+			} else if (wave.particleField) {
+				this.scene.remove(wave.particleField.points);
+				wave.particleField.dispose();
+				wave.particleField = void 0;
+			}
+		});
+	}
+	/** Per-frame placement for every wave's particle field: derive the camera's screen basis + each
+	*  wave's world centre (drift radiates from there) and bind that wave's live shape (#defines +
+	*  uniforms + matrixWorld) so the dust rides the SAME deform as the ribbon. Runs after refresh()'s
+	*  per-wave loop so the wave transforms/uniforms are current. No allocation; a no-op when off. */
+	updateSceneFx() {
+		let anyField = false;
+		for (const w of this.waves) if (w.particleField) {
+			anyField = true;
+			break;
+		}
+		if (!anyField) return;
+		this.camera.updateMatrixWorld();
+		this.fxRight.setFromMatrixColumn(this.camera.matrixWorld, 0).normalize();
+		this.fxUp.setFromMatrixColumn(this.camera.matrixWorld, 1).normalize();
+		const pr = this.renderer.getPixelRatio();
+		this.waves.forEach((wave, i) => {
+			const field = wave.particleField;
+			if (!field) return;
+			const sc = this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1];
+			wave.mesh.updateWorldMatrix(true, false);
+			wave.mesh.getWorldPosition(this.fxCenter);
+			const frame = {
+				center: this.fxCenter,
+				right: this.fxRight,
+				up: this.fxUp
+			};
+			field.frame(frame, pr);
+			field.configure({
+				defines: this.shapeDefines(sc),
+				uniforms: wave.material.uniforms,
+				matrixWorld: wave.mesh.matrixWorld,
+				speed: sc.speed,
+				seed: sc.seed
+			});
+		});
+	}
+	/** The subset of waveDefines() the particle program shares: the shape gates (what waveShape reads,
+	*  so the dust matches its wave's deform) plus the pointer gates (what pointerField reads, so the
+	*  dust reacts to the same cursor). Every one of these is derived from CONFIG alone — live input
+	*  must never reach here, or each frame would flip the define set and recompile the point program. */
+	shapeDefines(sc) {
+		const all = this.waveDefines(sc);
+		const out = {};
+		for (const k of [
+			"LOOP_MOTION",
+			"DETAIL_OCTAVE",
+			"HELIX",
+			"TWIST_MOTION",
+			"RADIAL",
+			"POINTER_FX",
+			"POINTER_RIPPLES"
+		]) if (k in all) out[k] = "";
+		return out;
+	}
 	/** Create/dispose the interaction controller as config toggles interaction on/off. Called from
 	*  refresh(); the compiled define set (POINTER_FX etc.) is handled separately by waveDefines(). */
 	syncInteraction() {
@@ -1535,7 +1638,9 @@ var WaveRenderer = class {
 				const h = sc.interaction?.hover;
 				pointerDisp = (h?.agitate ?? 0) + Math.abs(h?.push ?? 0) + (h?.wake ?? 0) + (sc.interaction?.press?.ripple ?? 0);
 			}
-			const radius = (bs.center.length() + bs.radius + disp + pointerDisp) * mesh.matrixWorld.getMaxScaleOnAxis() * 1.2;
+			const localRadius = bs.center.length() + bs.radius + disp + pointerDisp;
+			const drift = wave.particleField ? Math.abs(sc.particles?.drift ?? 0) : 0;
+			const radius = localRadius * mesh.matrixWorld.getMaxScaleOnAxis() * 1.2 + drift;
 			this.clipBox.expandByPoint(this.clipTmpB.copy(center).addScalar(radius));
 			this.clipBox.expandByPoint(this.clipTmpB.copy(center).addScalar(-radius));
 		}
@@ -1633,6 +1738,7 @@ var WaveRenderer = class {
 			s.material.dispose();
 			s.geometry.dispose();
 			s.palette.dispose();
+			s.particleField?.dispose();
 		}
 		this.bloomPass?.dispose();
 		this.ditherPass?.dispose();