@3driseai/3drise-viewer 0.1.26 → 0.1.28

package/dist/operations/catalogue/rainBeads.js

@@ -0,0 +1,223 @@
+// Rain beads — the object gets wet. Water beads land on the surface (a 3D
+// lattice of drops in the object's own space, each a dome whose normal bends
+// the scene's lighting: glossy highlight, dark refraction rim, a caustic on the
+// side away from the light), and the surface darkens and turns glossy where it
+// is wet. On the steep sides some drops break loose and slide down with gravity
+// (world down, whatever the object's rotation), wiping a wet trail behind them
+// that leaves a few tiny beads. They keep sliding while it holds.
+// A state, not an exit: reverting dries it — the beads shrink away and the wet
+// sheen fades.
+import { Color } from 'three';
+import { defineOperation } from '../types.js';
+import { GLSL_WORLEY, addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, runProgress, setFieldParams } from './transitionField.js';
+const P = 'Rain';
+const KEY = 'rainBeads';
+const STATE = '__opRainBeads';
+/** Computed once per fragment in the first anchor it reaches, then shared. */
+const COMPUTE = /* glsl */ `
+float rainB = 0.0;        // bead coverage (anti-aliased edge)
+float rainT = 2.0;        // position inside the bead: 0 centre, 1 rim
+vec3 rainDelta = vec3(0.0); // root-space normal bend of the bead
+float rainWet = 0.0, rainTrail = 0.0, rainRim = 0.0, rainCaus = 0.0;
+bool rainDone = false;
+void rainCompute() {
+  rainDone = true;
+  vec3 n = normalize(vRainN);
+  vec3 p = vRainR / uRainExtent * uRainDensity;                       // lattice units
+  vec3 g = normalize(mat3(uRainRootInv) * vec3(0.0, -1.0, 0.0));      // world down, in root space
+  vec3 gt = g - n * dot(g, n);
+  float vert = length(gt);
+  vec3 gd = vert > 1e-3 ? gt / vert : vec3(0.0);
+  float prog = clamp(uRainProgress, 0.0, 1.0);
+  float fq = RainField(vRainQ);
+  rainWet = smoothstep(fq * 0.5, fq * 0.5 + 0.35, prog) * uRainWetness;
+  // ---- sliding drops (steep sides only): one lane per column of a lattice across gravity
+  float slideT = 2.0; vec3 slideOff = vec3(0.0); float trail = 0.0;
+  float steep = smoothstep(0.3, 0.6, vert);
+  if (uRainSlide > 0.0 && steep > 0.0) {
+    vec3 a1 = normalize(abs(g.y) < 0.9 ? cross(g, vec3(0.0, 1.0, 0.0)) : cross(g, vec3(1.0, 0.0, 0.0)));
+    vec3 a2 = cross(g, a1);
+    vec2 uv = vec2(dot(p, a1), dot(p, a2)) * 0.6;
+    vec2 id = floor(uv);
+    vec3 hh = fxHash3(vec3(id, 7.0));
+    if (hh.x < uRainSlide * smoothstep(0.55, 1.0, prog)) {
+      float s = dot(p, g);
+      float period = 2.5 + 3.0 * hh.y;
+      float y = fract(s / period - uRainTime * (0.1 + 0.16 * hh.z) + hh.y);
+      float along = (y - 0.5) * period;                                // > 0 below the drop, < 0 behind it
+      // across the lane, measured along the surface's own horizontal
+      vec3 t1 = normalize(cross(n, g) + vec3(1e-5));
+      vec2 off2 = (fract(uv) - 0.5 - (hh.yz - 0.5) * 0.35) / 0.6;
+      float lateral = dot(off2, vec2(dot(t1, a1), dot(t1, a2))) - 0.12 * sin(s * 1.7 + hh.z * 6.28);
+      float rd = 0.2 * uRainBead;
+      float m = length(vec2(lateral / rd, along / (rd * (along < 0.0 ? 1.7 : 1.15))));
+      slideT = m;
+      slideOff = t1 * (lateral / rd) + gd * (along / (rd * 1.3));
+      // the wet trail it wipes, tapering behind it
+      float back = -along;
+      float tw = rd * 0.45 * (1.0 - smoothstep(0.0, period * 0.45, back));
+      trail = (1.0 - smoothstep(tw * 0.7, tw, abs(lateral))) * step(0.0, back) * (1.0 - smoothstep(period * 0.3, period * 0.48, back)) * steep;
+      // a few tiny beads left behind in the trail
+      float k = fract(back / (0.28 * uRainBead) + hh.x * 5.0);
+      float tb = length(vec2(lateral, (k - 0.5) * 0.28 * uRainBead)) / (0.045 * uRainBead * (0.6 + hh.y));
+      if (trail > 0.5 && tb < 1.0 && fxHash3(vec3(id, floor(back / (0.28 * uRainBead)))).x < 0.45) {
+        slideT = min(slideT, tb);
+        if (tb <= m) slideOff = t1 * (lateral / (0.045 * uRainBead)) + gd * ((k - 0.5) * 6.0);
+      }
+      slideT = mix(2.0, slideT, steep);
+    }
+  }
+  rainTrail = trail * uRainWetness;
+  // ---- static beads: one candidate drop per lattice cell
+  float bt = 2.0; vec3 bOff = vec3(0.0);
+  if (trail < 0.5) {
+    vec3 ic = floor(p);
+    for (int z = -1; z <= 1; z++) for (int y = -1; y <= 1; y++) for (int x = -1; x <= 1; x++) {
+      vec3 cell = ic + vec3(float(x), float(y), float(z));
+      vec3 h = fxHash3(cell);
+      vec3 h2 = fxHash3(cell + 31.7);
+      float birth = 0.62 * h2.x + 0.3 * fq;
+      float grow = smoothstep(birth, birth + 0.07, prog);
+      float rad = uRainBead * (0.13 + 0.3 * h2.y * h2.y) * grow;
+      if (rad < 1e-3) continue;
+      vec3 dv = p - (cell + h);
+      float dn = dot(dv, n);
+      if (abs(dn) >= rad) continue;
+      vec3 tv = dv - n * dn;
+      tv -= gd * dot(tv, gd) * 0.18;                                    // a slight sag with gravity
+      float sr = sqrt(rad * rad - dn * dn);
+      float t = length(tv) / sr;
+      if (t < bt) { bt = t; bOff = tv / sr; }
+    }
+  }
+  if (slideT < bt) { bt = slideT; bOff = slideOff; }
+  rainT = bt;
+  float aa = fwidth(bt) * 1.5 + 1e-3;
+  rainB = 1.0 - smoothstep(1.0 - aa, 1.0, bt);
+  float dome = sqrt(clamp(1.0 - bt * bt, 0.0, 1.0));
+  // a flat-ish drop: the bend grows towards the rim
+  vec3 nb = normalize(n * (0.35 + dome) + bOff * 0.9);
+  rainDelta = nb - n;
+  rainRim = smoothstep(0.72, 0.97, bt) * rainB;
+  rainCaus = smoothstep(0.1, 0.55, dot(bOff, gd)) * (1.0 - smoothstep(0.55, 0.85, bt)) * rainB;
+}
+`;
+function layerFor(st) {
+    return {
+        uniforms: {
+            ...fieldUniforms(P, st.field), uRainDensity: st.density, uRainBead: st.bead, uRainSlide: st.slide,
+            uRainWetness: st.wetness, uRainTint: st.tint,
+        },
+        common: `varying vec3 vRainQ;\nvarying vec3 vRainR;\nvarying vec3 vRainN;\nvarying vec3 vRainView;\nvarying vec3 vRainX;\nvarying vec3 vRainY;\nvarying vec3 vRainZ;\n${fieldGlsl(P)}\n${GLSL_WORLEY}`,
+        fragmentPars: COMPUTE,
+        vertex: /* glsl */ `
+        vRainR = (uRainRootInv * modelMatrix * vec4(transformed, 1.0)).xyz;
+        vRainQ = RainNorm(vRainR);
+        vRainN = (uRainRootInv * modelMatrix * vec4(normal, 0.0)).xyz;
+        vRainView = (modelViewMatrix * vec4(transformed, 1.0)).xyz;
+        {
+          // root axes in view space, to bend the lighting normal
+          mat3 rv = mat3(viewMatrix) * inverse(mat3(uRainRootInv));
+          vRainX = rv[0]; vRainY = rv[1]; vRainZ = rv[2];
+        }`,
+        diffuse: /* glsl */ `
+        {
+          if (!rainDone) rainCompute();
+          float wet = max(rainWet, rainTrail);
+          diffuseColor.rgb *= 1.0 - 0.42 * wet;
+          diffuseColor.rgb *= 1.0 - 0.18 * rainTrail;                     // a trail is wetter still
+          diffuseColor.rgb *= 1.0 - rainB * (0.18 + 0.45 * rainRim);
+        }`,
+        material: /* glsl */ `
+        {
+          if (!rainDone) rainCompute();
+          float wet = max(rainWet, rainTrail);
+          roughnessFactor = mix(roughnessFactor, roughnessFactor * 0.3, wet);
+          roughnessFactor = mix(roughnessFactor, 0.07, rainTrail);
+          roughnessFactor = mix(roughnessFactor, 0.03, rainB);
+          metalnessFactor = mix(metalnessFactor, 0.0, rainB);
+        }`,
+        emissive: /* glsl */ `
+        {
+          if (!rainDone) rainCompute();
+          vec3 dv = rainDelta.x * vRainX + rainDelta.y * vRainY + rainDelta.z * vRainZ;
+          normal = normalize(normal + dv * rainB);
+        }`,
+        fragment: /* glsl */ `
+        {
+          if (!rainDone) rainCompute();
+          if (rainB > 0.001) {
+            vec3 pos = vRainView;
+            vec3 gn = normalize(cross(dFdx(pos), dFdy(pos)));
+            vec3 dv = rainDelta.x * vRainX + rainDelta.y * vRainY + rainDelta.z * vRainZ;
+            vec3 n = normalize(gn + dv);
+            vec3 v = normalize(pos);
+            vec3 rw = normalize((vec4(reflect(v, n), 0.0) * viewMatrix).xyz);
+            float up = rw.y;
+            vec3 env = mix(vec3(0.03), vec3(0.75, 0.82, 0.9), smoothstep(-0.2, 0.7, up));
+            env += vec3(1.6) * exp(-abs(up - 0.03) * 40.0);
+            env += vec3(6.0) * pow(max(dot(rw, normalize(vec3(0.6, 0.55, 0.6))), 0.0), 240.0);
+            env += vec3(2.5) * pow(max(dot(rw, normalize(vec3(-0.7, 0.35, -0.3))), 0.0), 120.0);
+            float ndv = abs(dot(n, v));
+            float fres = 0.03 + 0.97 * pow(1.0 - ndv, 5.0);
+            outgoingLight += uRainTint * env * fres * rainB * 1.4;
+            outgoingLight += uRainTint * rainCaus * 0.35;
+          }
+        }`,
+    };
+}
+export default defineOperation({
+    value: 'rainBeads',
+    label: 'Rain beads',
+    description: 'Bead the targets with water drops that catch the light, some sliding down in wet trails — reverting dries them',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action', 'object'],
+    params: {
+        direction: { type: 'select', label: 'Rain arrives', default: 'down', options: DIRECTION_OPTIONS },
+        density: { type: 'number', label: 'Drops', default: 22, min: 5, max: 80, step: 1, hint: 'Drops across the object' },
+        size: { type: 'number', label: 'Drop size', default: 1, min: 0.3, max: 2.2, step: 0.05, unit: '×' },
+        slide: { type: 'number', label: 'Sliding drops', default: 0.45, min: 0, max: 1, step: 0.01 },
+        wetness: { type: 'number', label: 'Wetness', default: 0.7, min: 0, max: 1, step: 0.01, hint: 'How much the surface darkens and shines' },
+        tint: { type: 'color', label: 'Water', default: '#e6f2ff' },
+        duration: { type: 'number', label: 'Duration', default: 3, min: 0.3, max: 12, step: 0.1, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        let st = target.userData[STATE];
+        if (!st) {
+            const field = createFieldState(target);
+            st = {
+                field, density: { value: 22 }, bead: { value: 1 }, slide: { value: 0.45 }, wetness: { value: 0.7 }, tint: { value: new Color() },
+                mats: new Set(),
+            };
+            const own = st;
+            const layer = layerFor(own);
+            forEachMeshMaterial(target, (mat, mesh) => {
+                if (mesh.userData?.__opFxHelper)
+                    return;
+                if (addLayer(mat, KEY, layer))
+                    own.mats.add(mat);
+            });
+            target.userData[STATE] = st;
+        }
+        const s = st;
+        setFieldParams(s.field, p, target, ctx);
+        s.density.value = Number(p.density);
+        s.bead.value = Number(p.size);
+        s.slide.value = Number(p.slide);
+        s.wetness.value = Number(p.wetness);
+        s.tint.value.set(String(p.tint));
+        return runProgress(target, s.field, 1, { duration: Number(p.duration), ease: 'power1.out', hold: true });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        return runProgress(target, s.field, 0, {
+            duration: Number(p.duration), ease: 'power1.in',
+            onComplete: () => { s.mats.forEach(m => removeLayer(m, KEY)); delete target.userData[STATE]; },
+        });
+    },
+});

package/dist/operations/catalogue/restPose.d.ts

@@ -0,0 +1,21 @@
+import { Quaternion, Vector3 } from 'three';
+import type { Object3D } from 'three';
+export interface RestPose {
+    position: Vector3;
+    quaternion: Quaternion;
+    scale: Vector3;
+    /** Bounds centre and bottom in the object's own local space (unscaled). */
+    centerLocal: Vector3;
+    bottomLocal: Vector3;
+    /** World-space size at rest. */
+    size: Vector3;
+    users: number;
+}
+export declare function acquireRest(target: Object3D): RestPose;
+export declare function releaseRest(target: Object3D): void;
+/**
+ * Pose the object as rest ∘ (rotation `q` and non-uniform scale `s` about the local
+ * `pivot`), then offset by `worldOffset`. The pivot stays where it is at rest.
+ */
+export declare function poseAbout(target: Object3D, r: RestPose, pivot: Vector3, q: Quaternion, s: Vector3, worldOffset?: Vector3): void;
+//# sourceMappingURL=restPose.d.ts.map

package/dist/operations/catalogue/restPose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restPose.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/restPose.ts"],"names":[],"mappings":"AAGA,OAAO,EAAQ,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,MAAM,WAAW,QAAQ;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAgBtD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,QAQ3C;AAGD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,QAaxH"}

package/dist/operations/catalogue/restPose.js

@@ -0,0 +1,55 @@
+// Rest pose for transform operations: captured once when the first transform
+// effect starts on an object, released when the last one ends, so effects that
+// overlap (a jelly during a flip) always return to the authored pose.
+import { Box3, Vector3 } from 'three';
+const KEY = '__opRestPose';
+export function acquireRest(target) {
+    let r = target.userData[KEY];
+    if (!r) {
+        target.updateWorldMatrix(true, true);
+        const box = new Box3().setFromObject(target);
+        const c = box.getCenter(new Vector3());
+        const bottom = new Vector3(c.x, box.min.y, c.z);
+        r = {
+            position: target.position.clone(), quaternion: target.quaternion.clone(), scale: target.scale.clone(),
+            centerLocal: target.worldToLocal(c.clone()), bottomLocal: target.worldToLocal(bottom),
+            size: box.getSize(new Vector3()), users: 0,
+        };
+        target.userData[KEY] = r;
+    }
+    r.users++;
+    return r;
+}
+export function releaseRest(target) {
+    const r = target.userData[KEY];
+    if (!r)
+        return;
+    r.users--;
+    if (r.users <= 0) {
+        target.position.copy(r.position);
+        target.quaternion.copy(r.quaternion);
+        target.scale.copy(r.scale);
+        delete target.userData[KEY];
+    }
+}
+const _v = new Vector3();
+/**
+ * Pose the object as rest ∘ (rotation `q` and non-uniform scale `s` about the local
+ * `pivot`), then offset by `worldOffset`. The pivot stays where it is at rest.
+ */
+export function poseAbout(target, r, pivot, q, s, worldOffset) {
+    // local pivot → parent space at rest, and under the new rotation/scale
+    const restP = _v.copy(pivot).multiply(r.scale).applyQuaternion(r.quaternion);
+    const newQ = r.quaternion.clone().multiply(q);
+    const newS = r.scale.clone().multiply(s);
+    const nowP = pivot.clone().multiply(newS).applyQuaternion(newQ);
+    target.quaternion.copy(newQ);
+    target.scale.copy(newS);
+    target.position.copy(r.position).add(restP).sub(nowP);
+    if (worldOffset && target.parent) {
+        const w = target.parent.localToWorld(target.position.clone()).add(worldOffset);
+        target.position.copy(target.parent.worldToLocal(w));
+    }
+    else if (worldOffset)
+        target.position.add(worldOffset);
+}

package/dist/operations/catalogue/rimLight.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("..").OperationDefinition;
+export default _default;
+//# sourceMappingURL=rimLight.d.ts.map

package/dist/operations/catalogue/rimLight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rimLight.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/rimLight.ts"],"names":[],"mappings":";AAgBA,wBAwDG"}

package/dist/operations/catalogue/rimLight.js

@@ -0,0 +1,72 @@
+// Rim light — a Fresnel edge light over the object's own material: the
+// silhouette catches light, faces turned to the camera stay as they are. It
+// sweeps on along the chosen direction (a soft front in the object's own space)
+// and sweeps off the same way when reverted. Lit materials only.
+import { Color } from 'three';
+import { defineOperation } from '../types.js';
+import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, runProgress, setFieldParams } from './transitionField.js';
+const P = 'Rim';
+const KEY = 'rimLight';
+const STATE = '__opRim';
+const LIT = (m) => m.isMeshStandardMaterial || m.isMeshPhongMaterial || m.isMeshLambertMaterial || m.isMeshToonMaterial;
+export default defineOperation({
+    value: 'rimLight',
+    label: 'Rim light',
+    description: 'Light the edges of the targets, like a backlight catching the silhouette — sweeping on in a direction',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action', 'object'],
+    params: {
+        direction: { type: 'select', label: 'Direction', default: 'up', options: DIRECTION_OPTIONS },
+        color: { type: 'color', label: 'Colour', default: '#8fd8ff' },
+        intensity: { type: 'number', label: 'Intensity', default: 2.5, min: 0, max: 10, step: 0.1 },
+        sharpness: { type: 'number', label: 'Sharpness', default: 3, min: 1, max: 8, step: 0.1, hint: 'Higher = a thinner edge' },
+        softness: { type: 'number', label: 'Front softness', default: 0.25, min: 0.02, max: 0.6, step: 0.01, hint: 'How soft the sweeping front is' },
+        duration: { type: 'number', label: 'Duration', default: 0.8, min: 0, max: 10, step: 0.05, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        let st = target.userData[STATE];
+        if (!st) {
+            const field = createFieldState(target);
+            st = { field, color: { value: new Color() }, intensity: { value: 0 }, power: { value: 3 }, mats: new Set() };
+            const own = st;
+            const layer = {
+                uniforms: { ...fieldUniforms(P, field), uRimColor: own.color, uRimIntensity: own.intensity, uRimPower: own.power },
+                common: `varying vec3 vRimQ;\n${fieldGlsl(P)}`,
+                vertex: `vRimQ = RimNorm((uRimRootInv * modelMatrix * vec4(transformed, 1.0)).xyz);`,
+                fragment: /* glsl */ `
+                {
+                  // on behind the front, a soft ramp across it
+                  float on = smoothstep(0.0, uRimEdgeWidth, RimThreshold() - RimField(vRimQ));
+                  float facing = clamp(abs(dot(normalize(normal), normalize(vViewPosition))), 0.0, 1.0);
+                  outgoingLight += uRimColor * (uRimIntensity * on * pow(1.0 - facing, uRimPower));
+                }`,
+            };
+            forEachMeshMaterial(target, (mat, mesh) => {
+                if (mesh.userData?.__opFxHelper || !LIT(mat))
+                    return;
+                if (addLayer(mat, KEY, layer))
+                    own.mats.add(mat);
+            });
+            target.userData[STATE] = st;
+        }
+        const s = st;
+        setFieldParams(s.field, p, target, ctx);
+        s.field.edgeWidth.value = Number(p.softness);
+        s.color.value.set(String(p.color));
+        s.intensity.value = Number(p.intensity);
+        s.power.value = Number(p.sharpness);
+        return runProgress(target, s.field, 1, { duration: Number(p.duration), ease: 'power1.out', hold: true });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        return runProgress(target, s.field, 0, {
+            duration: Number(p.duration), ease: 'power1.in',
+            onComplete: () => { s.mats.forEach(m => removeLayer(m, KEY)); delete target.userData[STATE]; },
+        });
+    },
+});

package/dist/operations/catalogue/sandErosion.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("..").OperationDefinition;
+export default _default;
+//# sourceMappingURL=sandErosion.d.ts.map

package/dist/operations/catalogue/sandErosion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandErosion.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/sandErosion.ts"],"names":[],"mappings":";AAyEA,wBAkGG"}

package/dist/operations/catalogue/sandErosion.js

@@ -0,0 +1,167 @@
+// Sand erosion — first the surface turns to sand (a warm, grainy, matte crust
+// that keeps a trace of the object's colour), then it crumbles grain by grain
+// along a granular edge — no glow, just a darker, damp-looking lip where it is
+// breaking. Each grain slides off, then drops under gravity (accelerating) onto
+// a cone-shaped mound around the base; grains that fell earlier lie lower, so the pile
+// really builds up. The pile stays while the effect is on; reverting sends every
+// grain back up to its exact spot and the surface closes.
+import { Color } from 'three';
+import { defineOperation } from '../types.js';
+import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, hideMeshes, runProgress, setFieldParams, } from './transitionField.js';
+import { sampleSurfaceCached } from './surfaceSample.js';
+import { GLSL_POINT_SIZE, createFxPoints, disposeFxPoints } from './fxPoints.js';
+const P = 'Snd';
+const KEY = 'sandErosion';
+const STATE = '__opSand';
+/** The crumble trails the sand crust by LAG; grains fall for LIFE (progress units). */
+const LAG = 0.25;
+const LIFE = 0.55;
+const END = 1 + LAG + LIFE;
+/** Grains across the object's extent, for the granular crumble edge. */
+const GRAIN_CELLS = 140.0;
+const HASH1 = /* glsl */ `
+#ifndef FX_HASH1
+#define FX_HASH1
+float fxHash1(vec3 p) { return fract(sin(dot(p, vec3(127.1, 311.7, 74.7))) * 43758.5453); }
+#endif
+`;
+/**
+ * The surface: a sand crust spreads with the front (colour, grain, matte), then
+ * the crumble front eats it away with a per-grain jitter, so the edge breaks
+ * up into grains instead of a smooth line — darker right at the breaking lip.
+ */
+function sandLayer(field, sand, tint) {
+    const crust = /* glsl */ `
+      float f = SndField(vSndQ);
+      float crust = smoothstep(0.0, 0.1, SndThreshold() - f);
+      float pc = clamp(uSndProgress - ${LAG}, 0.0, 1.0);
+      float tc = pc * (1.0 + 2.0 * uSndEdgeWidth) - uSndEdgeWidth;
+      float jit = (fxHash1(floor(vSndR / uSndExtent * ${GRAIN_CELLS.toFixed(1)})) - 0.5) * 0.06;
+      float d = f + jit - tc;`;
+    return {
+        uniforms: { ...fieldUniforms(P, field), uSndSand: sand, uSndTint: tint },
+        common: `varying vec3 vSndQ;\nvarying vec3 vSndR;\n${fieldGlsl(P)}\n${HASH1}`,
+        vertex: /* glsl */ `
+        vSndR = (uSndRootInv * modelMatrix * vec4(transformed, 1.0)).xyz;
+        vSndQ = SndNorm(vSndR);`,
+        diffuse: /* glsl */ `
+        {
+          ${crust}
+          if (d < 0.0) discard;
+          float g = fxHash1(floor(vSndR / uSndExtent * ${GRAIN_CELLS.toFixed(1)} * 2.3));
+          vec3 sandC = mix(uSndSand, diffuseColor.rgb, uSndTint) * (0.8 + 0.3 * g);
+          diffuseColor.rgb = mix(diffuseColor.rgb, sandC, crust);
+          // the breaking lip is darker, like damp sand under the fall
+          diffuseColor.rgb *= 1.0 - 0.45 * (1.0 - smoothstep(0.0, 0.05, d)) * step(0.0001, pc);
+        }`,
+        material: /* glsl */ `
+        {
+          ${crust}
+          roughnessFactor = mix(roughnessFactor, 0.97, crust);
+          metalnessFactor = mix(metalnessFactor, 0.0, crust);
+        }`,
+    };
+}
+export default defineOperation({
+    value: 'sandErosion',
+    label: 'Sand erosion',
+    description: 'Crumble the targets into grains that pour down into a mound — reverting pours them back up',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    params: {
+        direction: { type: 'select', label: 'Direction', default: 'down', options: DIRECTION_OPTIONS },
+        grains: { type: 'number', label: 'Grains', default: 45000, min: 5000, max: 150000, step: 1000 },
+        grainSize: { type: 'number', label: 'Grain size', default: 1, min: 0.3, max: 4, step: 0.1, unit: '×' },
+        pile: { type: 'number', label: 'Mound height', default: 1, min: 0, max: 3, step: 0.05, unit: '×' },
+        spread: { type: 'number', label: 'Mound width', default: 1, min: 0.3, max: 3, step: 0.05, unit: '×' },
+        sand: { type: 'color', label: 'Sand', default: '#d8b98a' },
+        tint: { type: 'number', label: 'Object colour', default: 0.35, min: 0, max: 1, step: 0.05, hint: 'How much of the object’s own colour the sand keeps' },
+        scale: { type: 'number', label: 'Grain pattern', default: 3, min: 0.5, max: 12, step: 0.1 },
+        duration: { type: 'number', label: 'Duration', default: 3.2, min: 0.3, max: 12, step: 0.1, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        let st = target.userData[STATE];
+        if (!st) {
+            const field = createFieldState(target);
+            field.edgeWidth.value = 0.05;
+            const life = { value: LIFE }, pile = { value: 1 }, spread = { value: 1 }, grain = { value: 1 }, sand = { value: new Color() }, tint = { value: 0.35 };
+            const sample = sampleSurfaceCached(target, Math.round(Number(p.grains)), 21);
+            const points = createFxPoints(target, sample, {
+                additive: false,
+                uniforms: { ...fieldUniforms(P, field), uSndLife: life, uSndPile: pile, uSndSpread: spread, uSndGrain: grain, uSndSand: sand, uSndTint: tint },
+                vertexPars: fieldGlsl(P) + GLSL_POINT_SIZE + HASH1,
+                vertexMain: /* glsl */ `
+                  float f = ${P}Field(${P}Norm(aP));
+                  // grains leave when the crumble reaches them (same granular jitter as the edge)
+                  float jit = (fxHash1(floor(aP / uSndExtent * ${GRAIN_CELLS.toFixed(1)})) - 0.5) * 0.06;
+                  float birth = ${LAG} + ${P}BirthOf(f + jit);
+                  float a = (uSndProgress - birth) / uSndLife;
+                  if (a <= 0.0) { gl_Position = vec4(2.0, 2.0, 2.0, 1.0); gl_PointSize = 0.0; vColor = vec3(0.0); vAlpha = 0.0; return; }
+                  a = min(a, 1.0);
+                  float E = uSndExtent;
+                  vec3 C = u${P}Min + u${P}Size * 0.5;
+                  float ground = u${P}Min.y;
+                  // resting spot on a cone around the base; early grains lie low, late ones on top
+                  float R = 0.42 * max(u${P}Size.x, u${P}Size.z) * uSndSpread + 0.08 * E;
+                  float rr = R * sqrt(aR.x);
+                  float th = aR.y * 6.2832;
+                  float H = u${P}Size.y * 0.34 * uSndPile;
+                  float layer = mix(0.12, 1.0, clamp(birth, 0.0, 1.0));
+                  // a slightly rounded cone, with a little noise so the mound isn't a perfect solid of revolution
+                  float cone = pow(1.0 - rr / R, 1.25) * (0.9 + 0.2 * fxNoise(vec3(cos(th), sin(th), 0.0) * 3.0));
+                  vec3 rest = vec3(C.x + cos(th) * rr, ground + H * cone * layer * (0.8 + 0.4 * aR.z) + 0.002 * E, C.z + sin(th) * rr);
+                  // slide off the surface, then fall: horizontal glide, vertical t² (gravity)
+                  float glide = smoothstep(0.0, 1.0, a);
+                  vec3 kick = aN * (0.035 * E) * sin(3.14159 * min(a * 2.5, 1.0));
+                  vec3 local = vec3(mix(aP.x, rest.x, glide), mix(aP.y, rest.y, a * a), mix(aP.z, rest.z, glide)) + kick;
+                  vec4 mv = modelViewMatrix * vec4(local, 1.0);
+                  gl_Position = projectionMatrix * mv;
+                  // the colour of the spot it left; grains deeper in the mound a little darker
+                  float depthShade = 0.72 + 0.28 * clamp((local.y - ground) / max(H, 1e-3), 0.0, 1.0);
+                  vec3 grainC = mix(uSndSand, aC, uSndTint) * (0.72 + 0.36 * aR.w);
+                  vColor = grainC * mix(1.0, depthShade, a);
+                  vAlpha = 1.0;
+                  gl_PointSize = clamp(fxPointPx(E * 0.0032 * uSndGrain * (0.7 + 0.6 * aR.w), mv), 1.0, 10.0);`,
+            });
+            st = { field, life, pile, spread, grain, sand, points, mats: new Set() };
+            st.tint = tint;
+            const own = st;
+            const layer = sandLayer(field, sand, tint);
+            forEachMeshMaterial(target, (mat, mesh) => {
+                if (mesh.userData?.__opFxHelper)
+                    return;
+                if (addLayer(mat, KEY, layer))
+                    own.mats.add(mat);
+            });
+            target.userData[STATE] = st;
+        }
+        const s = st;
+        setFieldParams(s.field, p, target, ctx);
+        s.pile.value = Number(p.pile);
+        s.spread.value = Number(p.spread);
+        s.grain.value = Number(p.grainSize);
+        s.sand.value.set(String(p.sand));
+        s.tint.value = Number(p.tint);
+        return runProgress(target, s.field, END, {
+            duration: Number(p.duration), ease: 'none',
+            onComplete: () => hideMeshes(target, KEY, true),
+        });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        hideMeshes(target, KEY, false);
+        return runProgress(target, s.field, 0, {
+            duration: Number(p.duration), ease: 'none',
+            onComplete: () => {
+                s.mats.forEach(m => removeLayer(m, KEY));
+                disposeFxPoints(s.points);
+                delete target.userData[STATE];
+            },
+        });
+    },
+});

package/dist/operations/catalogue/shaderLayers.d.ts

@@ -0,0 +1,74 @@
+import type { Material, Object3D } from 'three';
+export interface ShaderLayer {
+    /** Uniform objects — keep the references and write `.value` to animate. */
+    uniforms: Record<string, {
+        value: unknown;
+    }>;
+    /** Declarations, both stages (varyings go here). */
+    common?: string;
+    vertexPars?: string;
+    /**
+     * After beginnormal_vertex: `objectNormal` (vec3, local) can be rewritten.
+     * Only reached where the material computes normals (lit materials; basic ones
+     * with an env map or skinning).
+     */
+    normal?: string;
+    /** After begin_vertex: `transformed` (vec3, local) is in scope. */
+    vertex?: string;
+    fragmentPars?: string;
+    /**
+     * After color_fragment, BEFORE lighting: rewrite `diffuseColor` (rgba) so the new
+     * base colour is lit by the scene. `discard` is fine here too.
+     */
+    diffuse?: string;
+    /**
+     * After metalnessmap_fragment (MeshStandard / MeshPhysical only — skipped
+     * elsewhere): rewrite `roughnessFactor` / `metalnessFactor`.
+     */
+    material?: string;
+    /** After emissivemap_fragment: add to `totalEmissiveRadiance` (lit materials with emission). */
+    emissive?: string;
+    /** Before opaque_fragment: `outgoingLight` and `diffuseColor` are in scope; `discard` is fine. */
+    fragment?: string;
+}
+/** Can this material take a layer? Built-in shaders only (checked by type, before compile). */
+export declare const canLayer: (mat: Material) => boolean;
+/**
+ * Add a layer to a material. On a live scene the layer is STAGED: nothing changes
+ * on screen until commitPendingLayers() has compiled the new program in the
+ * background (runProgress does that before an effect starts). Pass
+ * `{ immediate: true }` for materials that are not on screen yet (an effect's own
+ * helpers), or when there is no renderer.
+ */
+export declare function addLayer(mat: Material, key: string, layer: ShaderLayer, opts?: {
+    immediate?: boolean;
+}): boolean;
+/**
+ * Compile, in the background, the programs that the staged layers of `root`'s
+ * materials will need, then commit the layers. three keys programs by their
+ * cache key, so when the live material switches to the layered code it finds the
+ * finished program and uses it straight away — no compile, no freeze.
+ */
+export declare function commitPendingLayers(root: Object3D): Promise<void>;
+/** The material's own shader hooks, before any layer (for cloning a layered material). */
+export declare function ownHooks(mat: Material): Pick<Material, 'onBeforeCompile' | 'customProgramCacheKey'>;
+/**
+ * Take a layer off. The wrapper hooks stay installed (with no layers they add no
+ * GLSL and return the material's own cache key): any later recompile — new
+ * lights, a new effect — must still register every proxy, see "Uniform binding".
+ */
+export declare function removeLayer(mat: Material, key: string): void;
+/** Does the material carry any layer right now? */
+export declare const hasLayers: (mat: Material) => boolean;
+export declare const hasLayer: (mat: Material, key: string) => boolean;
+/** Every mesh material under a root (points, lines and sprites have no surface to layer). */
+export declare function forEachMeshMaterial(root: Object3D, fn: (mat: Material, mesh: any) => void): void;
+/** `uniform <type> <name>;` from a uniform's current value. */
+export declare function uniformDecl(name: string, v: any): string;
+/** Calm 3D value noise + 3-octave fBm (GLSL). */
+export declare const GLSL_NOISE = "\n#ifndef FX_NOISE\n#define FX_NOISE\nfloat fxHash(vec3 p) { p = fract(p * 0.3183099 + 0.1); p *= 17.0; return fract(p.x * p.y * p.z * (p.x + p.y + p.z)); }\nfloat fxNoise(vec3 x) {\n  vec3 i = floor(x); vec3 f = fract(x); f = f * f * (3.0 - 2.0 * f);\n  return mix(mix(mix(fxHash(i), fxHash(i + vec3(1,0,0)), f.x), mix(fxHash(i + vec3(0,1,0)), fxHash(i + vec3(1,1,0)), f.x), f.y),\n             mix(mix(fxHash(i + vec3(0,0,1)), fxHash(i + vec3(1,0,1)), f.x), mix(fxHash(i + vec3(0,1,1)), fxHash(i + vec3(1,1,1)), f.x), f.y), f.z);\n}\nfloat fxFbm(vec3 p) { float a = 0.5, s = 0.0; for (int i = 0; i < 3; i++) { s += a * fxNoise(p); p = p * 2.03 + 11.7; a *= 0.5; } return s / 0.875; }\n#endif\n";
+/** Rotation about a unit axis (GLSL), include-guarded. */
+export declare const GLSL_ROT = "\n#ifndef FX_ROT\n#define FX_ROT\nmat3 fxRot(vec3 ax, float an) {\n  float s = sin(an), c = cos(an), oc = 1.0 - c;\n  return mat3(oc*ax.x*ax.x + c,      oc*ax.x*ax.y + ax.z*s, oc*ax.z*ax.x - ax.y*s,\n              oc*ax.x*ax.y - ax.z*s, oc*ax.y*ax.y + c,      oc*ax.y*ax.z + ax.x*s,\n              oc*ax.z*ax.x + ax.y*s, oc*ax.y*ax.z - ax.x*s, oc*ax.z*ax.z + c);\n}\n#endif\n";
+/** 3D cellular noise (GLSL): returns vec3(F1, F2, cell hash) for p, include-guarded. */
+export declare const GLSL_WORLEY = "\n#ifndef FX_WORLEY\n#define FX_WORLEY\nvec3 fxHash3(vec3 p) {\n  p = vec3(dot(p, vec3(127.1, 311.7, 74.7)), dot(p, vec3(269.5, 183.3, 246.1)), dot(p, vec3(113.5, 271.9, 124.6)));\n  return fract(sin(p) * 43758.5453123);\n}\nvec3 fxWorley(vec3 p) {\n  vec3 i = floor(p); vec3 f = fract(p);\n  float f1 = 8.0, f2 = 8.0; float id = 0.0;\n  for (int z = -1; z <= 1; z++) for (int y = -1; y <= 1; y++) for (int x = -1; x <= 1; x++) {\n    vec3 g = vec3(float(x), float(y), float(z));\n    vec3 h = fxHash3(i + g);\n    vec3 r = g + h - f;\n    float d = dot(r, r);\n    if (d < f1) { f2 = f1; f1 = d; id = h.x; } else if (d < f2) { f2 = d; }\n  }\n  return vec3(sqrt(f1), sqrt(f2), id);\n}\n#endif\n";
+//# sourceMappingURL=shaderLayers.d.ts.map

package/dist/operations/catalogue/shaderLayers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shaderLayers.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/shaderLayers.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEhD,MAAM,WAAW,WAAW;IACxB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7C,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAmCD,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,KAAK,QAAQ,KAAG,OAEmE,CAAC;AAO7G;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAOhH;AA6BD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCvE;AA8CD,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,uBAAuB,CAAC,CAKnG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAM5D;AAED,mDAAmD;AACnD,eAAO,MAAM,SAAS,GAAI,KAAK,QAAQ,KAAG,OACiC,CAAC;AAE5E,eAAO,MAAM,QAAQ,GAAI,KAAK,QAAQ,EAAE,KAAK,MAAM,KAAG,OACgB,CAAC;AAEvE,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,QAMzF;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAUxD;AAED,iDAAiD;AACjD,eAAO,MAAM,UAAU,4rBAWtB,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,QAAQ,4XAUpB,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,WAAW,4rBAoBvB,CAAC"}