@3driseai/3drise-core 1.0.3 → 1.0.4

package/dist/presets/coronaPresets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coronaPresets.d.ts","sourceRoot":"","sources":["../../src/presets/coronaPresets.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAED,eAAO,MAAM,aAAa,EAAE,YAAY,EAkJvC,CAAC"}
+{"version":3,"file":"coronaPresets.d.ts","sourceRoot":"","sources":["../../src/presets/coronaPresets.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAED,eAAO,MAAM,aAAa,EAAE,YAAY,EAyJvC,CAAC"}

package/dist/presets/coronaPresets.js

@@ -34,7 +34,8 @@ export const coronaPresets = [
             u_pulseAmount: 0.45,
             u_shellScale: 1.30,
             u_innerColor: [1.0, 0.18, 0.02],
-            u_outerColor: [1.0, 0.85, 0.40]
+            u_outerColor: [1.0, 0.85, 0.40],
+            side: BackSide
         }
     },
     {
@@ -52,7 +53,8 @@ export const coronaPresets = [
             u_pulseAmount: 0.15,
             u_shellScale: 1.35,
             u_innerColor: [0.95, 0.85, 0.65],
-            u_outerColor: [1.0, 0.95, 0.80]
+            u_outerColor: [1.0, 0.95, 0.80],
+            side: BackSide
         }
     },
     {
@@ -70,7 +72,8 @@ export const coronaPresets = [
             u_pulseAmount: 0.2,
             u_shellScale: 1.28,
             u_innerColor: [0.10, 0.30, 0.85],
-            u_outerColor: [0.75, 0.92, 1.0]
+            u_outerColor: [0.75, 0.92, 1.0],
+            side: BackSide
         }
     },
     {
@@ -88,7 +91,8 @@ export const coronaPresets = [
             u_pulseAmount: 0.40,
             u_shellScale: 1.22,
             u_innerColor: [0.55, 0.02, 0.0],
-            u_outerColor: [1.0, 0.22, 0.08]
+            u_outerColor: [1.0, 0.22, 0.08],
+            side: BackSide
         }
     },
     {
@@ -106,7 +110,8 @@ export const coronaPresets = [
             u_pulseAmount: 0.50,
             u_shellScale: 1.30,
             u_innerColor: [0.40, 0.08, 0.80],
-            u_outerColor: [1.0, 0.35, 0.95]
+            u_outerColor: [1.0, 0.35, 0.95],
+            side: BackSide
         }
     },
     {
@@ -124,7 +129,8 @@ export const coronaPresets = [
             u_pulseAmount: 0.30,
             u_shellScale: 1.35,
             u_innerColor: [0.10, 0.55, 0.40],
-            u_outerColor: [0.65, 1.0, 0.75]
+            u_outerColor: [0.65, 1.0, 0.75],
+            side: BackSide
         }
     },
     {
@@ -142,7 +148,8 @@ export const coronaPresets = [
             u_pulseAmount: 0.15,
             u_shellScale: 1.25,
             u_innerColor: [0.20, 0.45, 0.85],
-            u_outerColor: [0.92, 0.97, 1.0]
+            u_outerColor: [0.92, 0.97, 1.0],
+            side: BackSide
         }
     }
 ];

package/dist/shaders/effects/index.d.ts

@@ -1,5 +1,7 @@
 export * from './presets';
 export * from './types';
+export * from './noiseLib';
+export * from './vertexEffectsCpu';
 export * from './EffectsFragmentFunctions.glsl';
 export * from './EffectsVertexFunctions.glsl';
 export * from './buildShaderEffectsMaterial';

package/dist/shaders/effects/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shaders/effects/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shaders/effects/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC"}

package/dist/shaders/effects/index.js

@@ -1,5 +1,7 @@
 export * from './presets.js';
 export * from './types.js';
+export * from './noiseLib.js';
+export * from './vertexEffectsCpu.js';
 export * from './EffectsFragmentFunctions.glsl.js';
 export * from './EffectsVertexFunctions.glsl.js';
 export * from './buildShaderEffectsMaterial.js';

package/dist/shaders/effects/noiseLib.d.ts

@@ -0,0 +1,12 @@
+export declare function whiteNoise2D(x: number, y: number): number;
+export declare function valueNoise2D(x: number, y: number): number;
+export declare function perlinNoise2D(px: number, py: number): number;
+export declare function simplexNoise2D(vx: number, vy: number): number;
+export declare function worleyNoise2D(px: number, py: number): number;
+export declare function fractalNoise2D(px: number, py: number): number;
+export declare function turbulenceNoise2D(px: number, py: number): number;
+export declare function ridgedNoise2D(px: number, py: number): number;
+export declare function domainWarpedNoise2D(px: number, py: number): number;
+/** Mirrors the GLSL `sampleNoise(float type, vec2 p)` dispatch, ranges included. */
+export declare function sampleNoise(type: number, px: number, py: number): number;
+//# sourceMappingURL=noiseLib.d.ts.map

package/dist/shaders/effects/noiseLib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noiseLib.d.ts","sourceRoot":"","sources":["../../../src/shaders/effects/noiseLib.ts"],"names":[],"mappings":"AAmCA,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAUzD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CA6C5D;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAyC7D;AAID,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAOhE;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAIlE;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAUxE"}

package/dist/shaders/effects/noiseLib.js

@@ -0,0 +1,215 @@
+// =============================================================================
+// noiseLib.ts — CPU port of noiseLib.glsl
+// =============================================================================
+//
+// A faithful scalar transcription of the GLSL noise library, so a position
+// effect evaluated on the CPU produces the same shape as the shader did. Keep
+// the two in step: if a function changes in `noiseLib.glsl.ts`, change it here.
+//
+// Type dispatch matches `sampleNoise` exactly:
+//   0=perlin 1=simplex 2=worley 3=value 4=white
+//   5=fractal 6=ridged 7=turbulence 8=domainWarped
+//
+const fract = (x) => x - Math.floor(x);
+/** GLSL mod(), which differs from JS % for negative operands. */
+const glslMod = (x, y) => x - y * Math.floor(x / y);
+const mix = (a, b, t) => a + (b - a) * t;
+const mod289 = (x) => x - Math.floor(x * (1.0 / 289.0)) * 289.0;
+const permute = (x) => mod289(((x * 34.0) + 1.0) * x);
+const hash21 = (x, y) => fract(Math.sin(x * 127.1 + y * 311.7) * 43758.5453123);
+/** nl_hash22 — returns a 2-vector in roughly [-1, 1]. */
+function hash22(x, y, out) {
+    const dx = x * 127.1 + y * 311.7;
+    const dy = x * 269.5 + y * 183.3;
+    out[0] = -1.0 + 2.0 * fract(Math.sin(dx) * 43758.5453123);
+    out[1] = -1.0 + 2.0 * fract(Math.sin(dy) * 43758.5453123);
+    return out;
+}
+const fade = (t) => t * t * t * (t * (t * 6.0 - 15.0) + 10.0);
+export function whiteNoise2D(x, y) {
+    return hash21(x, y);
+}
+export function valueNoise2D(x, y) {
+    const ix = Math.floor(x), iy = Math.floor(y);
+    const fx = fract(x), fy = fract(y);
+    const a = hash21(ix, iy);
+    const b = hash21(ix + 1.0, iy);
+    const c = hash21(ix, iy + 1.0);
+    const d = hash21(ix + 1.0, iy + 1.0);
+    const ux = fx * fx * (3.0 - 2.0 * fx);
+    const uy = fy * fy * (3.0 - 2.0 * fy);
+    return mix(a, b, ux) + (c - a) * uy * (1.0 - ux) + (d - b) * ux * uy;
+}
+export function perlinNoise2D(px, py) {
+    // Pi = floor(P.xyxy) + (0,0,1,1); Pf = fract(P.xyxy) - (0,0,1,1)
+    let pi0 = Math.floor(px), pi1 = Math.floor(py);
+    let pi2 = pi0 + 1.0, pi3 = pi1 + 1.0;
+    const pf0 = fract(px), pf1 = fract(py);
+    const pf2 = pf0 - 1.0, pf3 = pf1 - 1.0;
+    pi0 = glslMod(pi0, 289.0);
+    pi1 = glslMod(pi1, 289.0);
+    pi2 = glslMod(pi2, 289.0);
+    pi3 = glslMod(pi3, 289.0);
+    // ix = Pi.xzxz, iy = Pi.yyww, fx = Pf.xzxz, fy = Pf.yyww
+    const ix = [pi0, pi2, pi0, pi2];
+    const iy = [pi1, pi1, pi3, pi3];
+    const fx = [pf0, pf2, pf0, pf2];
+    const fy = [pf1, pf1, pf3, pf3];
+    const gxv = [0, 0, 0, 0];
+    const gyv = [0, 0, 0, 0];
+    for (let k = 0; k < 4; k++) {
+        const i = permute(permute(ix[k]) + iy[k]);
+        let gx = 2.0 * fract(i * 0.0243902439) - 1.0;
+        const gy = Math.abs(gx) - 0.5;
+        gx = gx - Math.floor(gx + 0.5);
+        gxv[k] = gx;
+        gyv[k] = gy;
+    }
+    // g00=(gx.x,gy.x) g10=(gx.y,gy.y) g01=(gx.z,gy.z) g11=(gx.w,gy.w)
+    let g00x = gxv[0], g00y = gyv[0];
+    let g10x = gxv[1], g10y = gyv[1];
+    let g01x = gxv[2], g01y = gyv[2];
+    let g11x = gxv[3], g11y = gyv[3];
+    const N = 1.79284291400159, M = 0.85373472095314;
+    const n00norm = N - M * (g00x * g00x + g00y * g00y);
+    const n01norm = N - M * (g01x * g01x + g01y * g01y);
+    const n10norm = N - M * (g10x * g10x + g10y * g10y);
+    const n11norm = N - M * (g11x * g11x + g11y * g11y);
+    g00x *= n00norm;
+    g00y *= n00norm;
+    g01x *= n01norm;
+    g01y *= n01norm;
+    g10x *= n10norm;
+    g10y *= n10norm;
+    g11x *= n11norm;
+    g11y *= n11norm;
+    const n00 = g00x * fx[0] + g00y * fy[0];
+    const n10 = g10x * fx[1] + g10y * fy[1];
+    const n01 = g01x * fx[2] + g01y * fy[2];
+    const n11 = g11x * fx[3] + g11y * fy[3];
+    const fadeX = fade(pf0), fadeY = fade(pf1);
+    const nx0 = mix(n00, n10, fadeX);
+    const nx1 = mix(n01, n11, fadeX);
+    return 2.3 * mix(nx0, nx1, fadeY);
+}
+export function simplexNoise2D(vx, vy) {
+    const C0 = 0.211324865405187, C1 = 0.366025403784439;
+    const C2 = -0.577350269189626, C3 = 0.024390243902439;
+    const dotVC = vx * C1 + vy * C1;
+    let ix = Math.floor(vx + dotVC);
+    let iy = Math.floor(vy + dotVC);
+    const dotIC = ix * C0 + iy * C0;
+    const x0x = vx - ix + dotIC;
+    const x0y = vy - iy + dotIC;
+    const i1x = x0x > x0y ? 1.0 : 0.0;
+    const i1y = x0x > x0y ? 0.0 : 1.0;
+    // x12 = x0.xyxy + C.xxzz; x12.xy -= i1
+    const x12x = x0x + C0 - i1x;
+    const x12y = x0y + C0 - i1y;
+    const x12z = x0x + C2;
+    const x12w = x0y + C2;
+    ix = mod289(ix);
+    iy = mod289(iy);
+    const p0 = permute(permute(iy + 0.0) + ix + 0.0);
+    const p1 = permute(permute(iy + i1y) + ix + i1x);
+    const p2 = permute(permute(iy + 1.0) + ix + 1.0);
+    let m0 = Math.max(0.5 - (x0x * x0x + x0y * x0y), 0.0);
+    let m1 = Math.max(0.5 - (x12x * x12x + x12y * x12y), 0.0);
+    let m2 = Math.max(0.5 - (x12z * x12z + x12w * x12w), 0.0);
+    m0 = m0 * m0;
+    m0 = m0 * m0;
+    m1 = m1 * m1;
+    m1 = m1 * m1;
+    m2 = m2 * m2;
+    m2 = m2 * m2;
+    const xa = 2.0 * fract(p0 * C3) - 1.0;
+    const xb = 2.0 * fract(p1 * C3) - 1.0;
+    const xc = 2.0 * fract(p2 * C3) - 1.0;
+    const ha = Math.abs(xa) - 0.5, hb = Math.abs(xb) - 0.5, hc = Math.abs(xc) - 0.5;
+    const a0a = xa - Math.floor(xa + 0.5);
+    const a0b = xb - Math.floor(xb + 0.5);
+    const a0c = xc - Math.floor(xc + 0.5);
+    const N = 1.79284291400159, M = 0.85373472095314;
+    m0 *= N - M * (a0a * a0a + ha * ha);
+    m1 *= N - M * (a0b * a0b + hb * hb);
+    m2 *= N - M * (a0c * a0c + hc * hc);
+    const gx = a0a * x0x + ha * x0y;
+    const gy = a0b * x12x + hb * x12y;
+    const gz = a0c * x12z + hc * x12w;
+    return 130.0 * (m0 * gx + m1 * gy + m2 * gz);
+}
+const worleyScratch = [0, 0];
+export function worleyNoise2D(px, py) {
+    const ix = Math.floor(px), iy = Math.floor(py);
+    const fx = fract(px), fy = fract(py);
+    let minDist = 1.5;
+    for (let y = -1; y <= 1; y++) {
+        for (let x = -1; x <= 1; x++) {
+            const h = hash22(ix + x, iy + y, worleyScratch);
+            const pointX = 0.5 + 0.5 * h[0];
+            const pointY = 0.5 + 0.5 * h[1];
+            const dx = x + pointX - fx;
+            const dy = y + pointY - fy;
+            const d = Math.sqrt(dx * dx + dy * dy);
+            if (d < minDist)
+                minDist = d;
+        }
+    }
+    return minDist;
+}
+export function fractalNoise2D(px, py) {
+    let v = 0.0, amp = 0.5, qx = px, qy = py;
+    for (let i = 0; i < 4; i++) {
+        v += amp * perlinNoise2D(qx, qy);
+        qx *= 2.0;
+        qy *= 2.0;
+        amp *= 0.5;
+    }
+    return v;
+}
+export function turbulenceNoise2D(px, py) {
+    let v = 0.0, amp = 0.5, qx = px, qy = py;
+    for (let i = 0; i < 4; i++) {
+        v += amp * Math.abs(perlinNoise2D(qx, qy));
+        qx *= 2.0;
+        qy *= 2.0;
+        amp *= 0.5;
+    }
+    return v;
+}
+export function ridgedNoise2D(px, py) {
+    let v = 0.0, amp = 0.5, qx = px, qy = py;
+    for (let i = 0; i < 4; i++) {
+        const n = 1.0 - Math.abs(perlinNoise2D(qx, qy));
+        v += amp * n * n;
+        qx *= 2.0;
+        qy *= 2.0;
+        amp *= 0.5;
+    }
+    return v;
+}
+export function domainWarpedNoise2D(px, py) {
+    const wx = perlinNoise2D(px, py);
+    const wy = perlinNoise2D(px + 5.2, py + 1.3);
+    return perlinNoise2D(px + wx * 0.5, py + wy * 0.5);
+}
+/** Mirrors the GLSL `sampleNoise(float type, vec2 p)` dispatch, ranges included. */
+export function sampleNoise(type, px, py) {
+    if (type < 0.5)
+        return perlinNoise2D(px, py);
+    if (type < 1.5)
+        return simplexNoise2D(px, py);
+    if (type < 2.5)
+        return worleyNoise2D(px, py) * 2.0 - 1.0;
+    if (type < 3.5)
+        return valueNoise2D(px, py) * 2.0 - 1.0;
+    if (type < 4.5)
+        return whiteNoise2D(px, py) * 2.0 - 1.0;
+    if (type < 5.5)
+        return fractalNoise2D(px, py);
+    if (type < 6.5)
+        return ridgedNoise2D(px, py);
+    if (type < 7.5)
+        return turbulenceNoise2D(px, py);
+    return domainWarpedNoise2D(px, py);
+}

package/dist/shaders/effects/vertexEffectsCpu.d.ts

@@ -0,0 +1,52 @@
+import type { ShaderEffect } from './types';
+/**
+ * The shader approximated a local-space pointer as `u_pointer * 5.0` — a legacy
+ * constant, but the one the effects were tuned against. The CPU path reuses it
+ * so pointer-scoped effects keep the reach they had.
+ */
+export declare const LOCAL_POINTER_SCALE = 5;
+export interface VertexEffectContext {
+    /** Seconds, matching the shader's `u_time`. */
+    time: number;
+    /**
+     * Pointer position in the same space as the positions being displaced.
+     * The shader computed pointer falloff in screen NDC per vertex; doing that
+     * on the CPU would mean projecting every point every frame, so this uses
+     * object-local distance instead. Pointer-scoped effects therefore have a
+     * slightly different falloff shape than they did in the shader.
+     */
+    pointerX: number;
+    pointerY: number;
+    /** Falloff radius for `pointer`-scoped effects, in local units. */
+    pointerRadius: number;
+}
+/** Working position, reused across points so the loop allocates nothing. */
+interface Pos {
+    x: number;
+    y: number;
+    z: number;
+}
+type VertexEffectImpl = (p: Pos, values: Record<string, number>, time: number, scope: number, baseX: number, baseY: number, baseZ: number) => void;
+/**
+ * Position effects that run on the CPU. Anything vertex-stage but absent here
+ * still needs the shader shell — `scale` writes gl_PointSize, which has no
+ * per-point CPU equivalent.
+ */
+export declare const CPU_VERTEX_EFFECTS: Record<string, VertexEffectImpl>;
+/** True when this effect type displaces positions on the CPU. */
+export declare function hasCpuVertexEffect(type: string): boolean;
+/** Split a mixed list into the CPU-displaced ones and everything else. */
+export declare function partitionShaderEffects(effects: ShaderEffect[] | null | undefined): {
+    position: ShaderEffect[];
+    shell: ShaderEffect[];
+};
+/**
+ * Displace `base` into `out` by every enabled position effect.
+ *
+ * `base` is never modified, so effects always compose from the authored
+ * positions rather than accumulating frame over frame. Returns false when
+ * nothing was applied, so the caller can skip the attribute upload.
+ */
+export declare function applyVertexEffects(base: Float32Array, out: Float32Array, effects: ShaderEffect[] | null | undefined, ctx: VertexEffectContext): boolean;
+export {};
+//# sourceMappingURL=vertexEffectsCpu.d.ts.map

package/dist/shaders/effects/vertexEffectsCpu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertexEffectsCpu.d.ts","sourceRoot":"","sources":["../../../src/shaders/effects/vertexEffectsCpu.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAM,CAAC;AAEvC,MAAM,WAAW,mBAAmB;IAChC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,4EAA4E;AAC5E,UAAU,GAAG;IACT,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAED,KAAK,gBAAgB,GAAG,CACpB,CAAC,EAAE,GAAG,EACN,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,KACZ,IAAI,CAAC;AA+HV;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAE/D,CAAC;AAEF,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG;IAChF,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,EAAE,YAAY,EAAE,CAAC;CACzB,CAOA;AAoBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI,GAAG,SAAS,EAC1C,GAAG,EAAE,mBAAmB,GACzB,OAAO,CAsCT"}

package/dist/shaders/effects/vertexEffectsCpu.js

@@ -0,0 +1,240 @@
+// =============================================================================
+// vertexEffectsCpu — position effects, evaluated on the CPU
+// =============================================================================
+//
+// Why this exists: the GLSL versions of these effects only run inside
+// `buildShaderEffectsMaterial`'s standalone shell, and that shell *replaces*
+// whatever material the object was given. Evaluating position effects here
+// instead means they displace the geometry and leave `.material` alone, so they
+// compose with any material — the registry's, a custom ShaderMaterial, anything.
+//
+// Colour effects cannot move: there is no per-pixel hook on the CPU. They stay
+// in the shell until they are injected into the chosen material (onBeforeCompile).
+//
+// Each implementation is a transcription of the matching `vertexBody` in
+// `registry/*.ts`. Keep them in step. The GLSL bodies remain the reference for
+// anything still rendered through the shell.
+//
+// Deliberately allocation-free in the hot loop: positions are read from a base
+// array and written to an output array, no vectors constructed per point.
+//
+import { getDescriptor } from './registry/index.js';
+import { sampleNoise } from './noiseLib.js';
+/**
+ * The shader approximated a local-space pointer as `u_pointer * 5.0` — a legacy
+ * constant, but the one the effects were tuned against. The CPU path reuses it
+ * so pointer-scoped effects keep the reach they had.
+ */
+export const LOCAL_POINTER_SCALE = 5.0;
+const smoothstep = (edge0, edge1, x) => {
+    const t = Math.min(Math.max((x - edge0) / (edge1 - edge0), 0), 1);
+    return t * t * (3 - 2 * t);
+};
+const fract = (x) => x - Math.floor(x);
+// ─── Implementations ─────────────────────────────────────────────────────────
+const wave = (p, v, t, s) => {
+    const input = v.direction < 0.5 ? p.x : v.direction < 1.5 ? p.y : p.x + p.y;
+    p.z += Math.sin(input * v.frequency + t * v.speed) * v.intensity * s;
+};
+const ripple = (p, v, t, s) => {
+    const dx = p.x - v.centerX;
+    const dy = p.y - v.centerY;
+    const dist = Math.sqrt(dx * dx + dy * dy);
+    p.z += Math.sin(dist * v.frequency - t * v.speed) * v.intensity * s;
+};
+const vortex = (p, v, t, s) => {
+    const toX = p.x - v.centerX;
+    const toY = p.y - v.centerY;
+    const angle = v.intensity * t * v.speed * s;
+    const c = Math.cos(angle), sn = Math.sin(angle);
+    p.x = v.centerX + (c * toX - sn * toY);
+    p.y = v.centerY + (sn * toX + c * toY);
+};
+const spiral = (p, v, t, s) => {
+    const toX = p.x - v.centerX;
+    const toY = p.y - v.centerY;
+    let r = Math.sqrt(toX * toX + toY * toY);
+    let a = Math.atan2(toY, toX);
+    a += t * v.speed * v.intensity * s;
+    r = Math.max(0, r + t * v.radialSpeed * s);
+    p.x = v.centerX + r * Math.cos(a);
+    p.y = v.centerY + r * Math.sin(a);
+};
+const twist = (p, v, t, s) => {
+    const coord = v.axis < 0.5 ? p.x : v.axis < 1.5 ? p.y : p.z;
+    const angle = (coord * v.intensity + t * v.speed) * s;
+    const sn = Math.sin(angle), c = Math.cos(angle);
+    if (v.axis < 0.5) {
+        const y = c * p.y - sn * p.z;
+        const z = sn * p.y + c * p.z;
+        p.y = y;
+        p.z = z;
+    }
+    else if (v.axis < 1.5) {
+        const x = c * p.x + sn * p.z;
+        const z = -sn * p.x + c * p.z;
+        p.x = x;
+        p.z = z;
+    }
+    else {
+        const x = c * p.x - sn * p.y;
+        const y = sn * p.x + c * p.y;
+        p.x = x;
+        p.y = y;
+    }
+};
+const explode = (p, v, t, s) => {
+    const fx = p.x - v.centerX;
+    const fy = p.y - v.centerY;
+    const fz = p.z - v.centerZ;
+    const dist = Math.sqrt(fx * fx + fy * fy + fz * fz);
+    let dx = 0, dy = 1, dz = 0;
+    if (dist > 0.0001) {
+        dx = fx / dist;
+        dy = fy / dist;
+        dz = fz / dist;
+    }
+    const wave01 = Math.sin(t * v.speed) * 0.5 + 0.5;
+    const push = v.intensity * wave01 * s;
+    p.x += dx * push;
+    p.y += dy * push;
+    p.z += dz * push;
+};
+const magnet = (p, v, t, s) => {
+    const toX = v.centerX - p.x;
+    const toY = v.centerY - p.y;
+    const toZ = v.centerZ - p.z;
+    const dist = Math.max(Math.sqrt(toX * toX + toY * toY + toZ * toZ), 0.001);
+    const strength = Math.min(v.intensity * s / Math.pow(dist, v.falloffPower), dist);
+    p.x += (toX / dist) * strength;
+    p.y += (toY / dist) * strength;
+    p.z += (toZ / dist) * strength;
+};
+const jitter = (p, v, t, s, bx, by, bz) => {
+    // Seeded from the untouched base position, exactly as the shader seeds from
+    // the `position` attribute, so each point keeps its own stable direction.
+    const step = Math.floor(t * v.speed) * 0.137;
+    const sx = bx + step, sy = by + step, sz = bz + step;
+    const ox = fract(Math.sin(sx * 12.9898 + sy * 78.233 + sz * 37.719) * 43758.5453) - 0.5;
+    const oy = fract(Math.sin(sx * 93.9898 + sy * 47.233 + sz * 12.719) * 43758.5453) - 0.5;
+    const oz = fract(Math.sin(sx * 54.9898 + sy * 31.233 + sz * 89.719) * 43758.5453) - 0.5;
+    const k = v.intensity * 2.0 * s;
+    p.x += ox * k;
+    p.y += oy * k;
+    p.z += oz * k;
+};
+const noise = (p, v, t, s) => {
+    const nx = p.x * v.frequency + t * v.speed;
+    const ny = p.y * v.frequency + t * v.speed;
+    const k = v.intensity * s;
+    if (v.axis < 2.5) {
+        const push = sampleNoise(v.noiseType, nx, ny) * k;
+        if (v.axis < 0.5)
+            p.x += push;
+        else if (v.axis < 1.5)
+            p.y += push;
+        else
+            p.z += push;
+        return;
+    }
+    p.x += sampleNoise(v.noiseType, nx, ny) * k;
+    p.y += sampleNoise(v.noiseType, nx + 31.7, ny + 5.2) * k;
+    p.z += sampleNoise(v.noiseType, nx + 11.3, ny + 27.1) * k;
+};
+const displacement = (p, v, t, s, _bx, _by, _bz) => {
+    // Pushed away from the pointer. `ctx` supplies the pointer in local space;
+    // it is folded into `values` by applyVertexEffects before the loop.
+    const dx = p.x - v.__pointerX;
+    const dy = p.y - v.__pointerY;
+    const len = Math.sqrt(dx * dx + dy * dy);
+    if (len < 1e-6)
+        return;
+    const k = v.intensity * s * 2.0;
+    p.x += (dx / len) * k;
+    p.y += (dy / len) * k;
+};
+/**
+ * Position effects that run on the CPU. Anything vertex-stage but absent here
+ * still needs the shader shell — `scale` writes gl_PointSize, which has no
+ * per-point CPU equivalent.
+ */
+export const CPU_VERTEX_EFFECTS = {
+    wave, ripple, vortex, spiral, twist, explode, magnet, jitter, noise, displacement,
+};
+/** True when this effect type displaces positions on the CPU. */
+export function hasCpuVertexEffect(type) {
+    return Object.prototype.hasOwnProperty.call(CPU_VERTEX_EFFECTS, type);
+}
+/** Split a mixed list into the CPU-displaced ones and everything else. */
+export function partitionShaderEffects(effects) {
+    const position = [];
+    const shell = [];
+    for (const effect of effects ?? []) {
+        (hasCpuVertexEffect(effect.type) ? position : shell).push(effect);
+    }
+    return { position, shell };
+}
+/** Resolve an effect's values against its descriptor defaults, once per frame. */
+function resolveValues(effect, ctx) {
+    const descriptor = getDescriptor(effect.type);
+    if (!descriptor)
+        return null;
+    const values = {};
+    for (const [key, def] of Object.entries(descriptor.uniforms)) {
+        const raw = effect.values?.[key];
+        const value = raw === undefined ? def.default : raw;
+        values[key] = typeof value === 'number' ? value : Number(value) || 0;
+    }
+    values.__pointerX = ctx.pointerX;
+    values.__pointerY = ctx.pointerY;
+    return values;
+}
+const scratch = { x: 0, y: 0, z: 0 };
+/**
+ * Displace `base` into `out` by every enabled position effect.
+ *
+ * `base` is never modified, so effects always compose from the authored
+ * positions rather than accumulating frame over frame. Returns false when
+ * nothing was applied, so the caller can skip the attribute upload.
+ */
+export function applyVertexEffects(base, out, effects, ctx) {
+    const active = (effects ?? []).filter(e => e?.enabled && hasCpuVertexEffect(e.type));
+    if (active.length === 0)
+        return false;
+    const resolved = [];
+    for (const effect of active) {
+        const values = resolveValues(effect, ctx);
+        if (!values)
+            continue;
+        resolved.push({
+            impl: CPU_VERTEX_EFFECTS[effect.type],
+            values,
+            pointerScoped: effect.scope === 'pointer',
+        });
+    }
+    if (resolved.length === 0)
+        return false;
+    const radius = ctx.pointerRadius > 0 ? ctx.pointerRadius : 1;
+    const count = Math.min(base.length, out.length);
+    for (let i = 0; i < count; i += 3) {
+        const bx = base[i], by = base[i + 1], bz = base[i + 2];
+        scratch.x = bx;
+        scratch.y = by;
+        scratch.z = bz;
+        // Falloff is measured from the untouched position so that one effect
+        // moving a point cannot change how strongly the next one grips it.
+        const dx = bx - ctx.pointerX;
+        const dy = by - ctx.pointerY;
+        const pointerFalloff = smoothstep(radius, 0, Math.sqrt(dx * dx + dy * dy));
+        for (const { impl, values, pointerScoped } of resolved) {
+            const scope = pointerScoped ? pointerFalloff : 1;
+            if (scope <= 0)
+                continue;
+            impl(scratch, values, ctx.time, scope, bx, by, bz);
+        }
+        out[i] = scratch.x;
+        out[i + 1] = scratch.y;
+        out[i + 2] = scratch.z;
+    }
+    return true;
+}

package/dist/utils/edgeUtils.d.ts

@@ -1,4 +1,4 @@
-import { BufferGeometry, Matrix4, Mesh, Vector3 } from "three";
+import { BufferAttribute, BufferGeometry, Matrix4, Mesh, Vector3 } from "three";
 import type { Object3D } from 'three';
 export interface MeshEntry {
     mesh: Mesh;
@@ -34,4 +34,5 @@ export declare function sampleEdgePoints(segments: EdgeSegment[], countPerEdge:
  * Indices form connected pairs so LineSegments renders them as solid continuous lines per edge.
  */
 export declare function buildSubdividedEdgeGeometry(object: Object3D, subdivisions?: number, parentMatrix?: Matrix4): BufferGeometry;
+export declare function buildSegmentQuadGeometry(source: BufferAttribute | ArrayLike<[number, number, number]>, thickness?: number): BufferGeometry;
 //# sourceMappingURL=edgeUtils.d.ts.map

package/dist/utils/edgeUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edgeUtils.d.ts","sourceRoot":"","sources":["../../src/utils/edgeUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,cAAc,EAAiB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC/F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,4CAA4C;IAC5C,oBAAoB,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;CAChB;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,YAAY,GAAE,OAAuB,GAAG,SAAS,EAAE,CAY/F;AACD,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAQjE;AACD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,GAAG,WAAW,EAAE,CAiBnE;AACD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG;IACzE,SAAS,EAAE,YAAY,CAAC;IACxB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,YAAY,CAAC;CAC3B,CAsBJ;AACD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAE,MAAW,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,cAAc,CA8C/H"}
+{"version":3,"file":"edgeUtils.d.ts","sourceRoot":"","sources":["../../src/utils/edgeUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAyC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACvH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,4CAA4C;IAC5C,oBAAoB,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;CAChB;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,YAAY,GAAE,OAAuB,GAAG,SAAS,EAAE,CAY/F;AACD,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAQjE;AACD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,GAAG,WAAW,EAAE,CAiBnE;AACD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG;IACzE,SAAS,EAAE,YAAY,CAAC;IACxB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,YAAY,CAAC;CAC3B,CAsBJ;AACD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAE,MAAW,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,cAAc,CA8C/H;AAmBD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,SAAS,GAAE,MAAc,GAAG,cAAc,CAmDjJ"}

package/dist/utils/edgeUtils.js

@@ -1,4 +1,4 @@
-import { BufferAttribute, BufferGeometry, EdgesGeometry, Matrix4, Mesh, Vector3 } from "three";
+import { BufferAttribute, BufferGeometry, EdgesGeometry, Float32BufferAttribute, Matrix4, Mesh, Vector3 } from "three";
 import { EDGES_GROUP_KEY } from "./materialApplicationUtils.js";
 /** Recursively collect all meshes with geometries, accumulating local matrices. */
 export function collectMeshes(obj, parentMatrix = new Matrix4()) {
@@ -126,3 +126,72 @@ export function buildSubdividedEdgeGeometry(object, subdivisions = 60, parentMat
     geo.setIndex(indices);
     return geo;
 }
+// =============================================================================
+// SEGMENT QUADS
+// =============================================================================
+//
+// Turn a list of line segments into a ribbon of camera-agnostic quads — two
+// triangles per segment, with UVs running (0,0)-(1,1) along and across it.
+//
+// This is what makes edges materialisable: the result is an ordinary Mesh with
+// real UVs, so every registry material (the `line` shader family included)
+// applies to it exactly as it would to any other mesh. Line primitives cannot
+// do that — Line2 needs its own LineMaterial and carries no UVs — which is why
+// both the edges builder and the `lines` display modes go through here instead.
+//
+// `source` is a flat sequence of vertex positions, two consecutive vertices per
+// segment: either a BufferAttribute (e.g. EdgesGeometry.attributes.position) or
+// an array of [x, y, z] triples.
+//
+export function buildSegmentQuadGeometry(source, thickness = 0.008) {
+    const isAttribute = typeof source.getX === 'function';
+    const attr = source;
+    const list = source;
+    const vertexCount = isAttribute ? attr.count : list.length;
+    const segCount = Math.floor(vertexCount / 2);
+    const readVertex = (i, out) => (isAttribute
+        ? out.fromBufferAttribute(attr, i)
+        : out.set(list[i][0], list[i][1], list[i][2]));
+    const positions = [];
+    const uvs = [];
+    const indices = [];
+    const start = new Vector3();
+    const end = new Vector3();
+    const dir = new Vector3();
+    const up = new Vector3(0, 1, 0);
+    const right = new Vector3();
+    for (let i = 0; i < segCount; i++) {
+        readVertex(i * 2, start);
+        readVertex(i * 2 + 1, end);
+        dir.subVectors(end, start).normalize();
+        // Perpendicular axis — fallback to X if the segment is vertical
+        right.crossVectors(dir, up).normalize();
+        if (right.lengthSq() < 0.0001) {
+            right.set(1, 0, 0);
+        }
+        const rx = right.x * thickness;
+        const ry = right.y * thickness;
+        const rz = right.z * thickness;
+        const base = i * 4;
+        // v0  start-bottom   uv(0,0)
+        positions.push(start.x - rx, start.y - ry, start.z - rz);
+        uvs.push(0, 0);
+        // v1  end-bottom     uv(1,0)
+        positions.push(end.x - rx, end.y - ry, end.z - rz);
+        uvs.push(1, 0);
+        // v2  start-top      uv(0,1)
+        positions.push(start.x + rx, start.y + ry, start.z + rz);
+        uvs.push(0, 1);
+        // v3  end-top        uv(1,1)
+        positions.push(end.x + rx, end.y + ry, end.z + rz);
+        uvs.push(1, 1);
+        indices.push(base, base + 1, base + 2);
+        indices.push(base + 1, base + 3, base + 2);
+    }
+    const geo = new BufferGeometry();
+    geo.setAttribute('position', new Float32BufferAttribute(positions, 3));
+    geo.setAttribute('uv', new Float32BufferAttribute(uvs, 2));
+    geo.setIndex(indices);
+    geo.computeVertexNormals();
+    return geo;
+}

package/dist/utils/index.d.ts

@@ -16,6 +16,7 @@ export * from './positionsCreatorUtils';
 export * from './sunUtils';
 export * from './utils';
 export * from './edgeUtils';
+export * from './surfaceUtils';
 export * from './objectTreeUtils';
 export * from './handleTransformEffects';
 export * from './handleEdgesAnimations';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/utils/index.js

@@ -16,6 +16,7 @@ export * from './positionsCreatorUtils.js';
 export * from './sunUtils.js';
 export * from './utils.js';
 export * from './edgeUtils.js';
+export * from './surfaceUtils.js';
 export * from './objectTreeUtils.js';
 export * from './handleTransformEffects.js';
 export * from './handleEdgesAnimations.js';

package/dist/utils/materialApplicationUtils.d.ts

@@ -3,10 +3,19 @@ import { MaterialInstance } from '../services/MaterialRegistry';
 export declare const MATERIAL_INSTANCE_KEY = "_3driseMaterialInstance";
 export declare const EDGES_GROUP_KEY = "__isEdgesGroup";
 export declare const GEREATIVE_EFFECTS_KEY = "__isGenerativeEffectsGroup";
+/**
+ * Set by a renderer that builds and owns its object's material itself — today the
+ * points renderers, while shader effects are active. Two writers on one
+ * `.material` is the bug this prevents: whichever loses keeps animating a
+ * material that is no longer on the mesh, and the object renders as whatever the
+ * winner left behind.
+ */
+export declare const SELF_OWNED_MATERIAL_KEY = "__ownsItsMaterial";
 /**
  * Traverses obj and its descendants, skipping subtrees whose root is marked
- * with EDGES_GROUP_KEY or GEREATIVE_EFFECTS_KEY — unless obj itself carries that mark (so an edges group
- * or generative effects group can still apply its own material via useMaterialApplication).
+ * with EDGES_GROUP_KEY, GEREATIVE_EFFECTS_KEY or SELF_OWNED_MATERIAL_KEY — unless obj itself
+ * carries that mark (so an edges group or generative effects group can still
+ * apply its own material via useMaterialApplication).
  */
 export declare function traverseSkippingEdgesAndEffects(obj: Object3D, isRoot: boolean, callback: (node: Object3D) => void): void;
 /**

package/dist/utils/materialApplicationUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"materialApplicationUtils.d.ts","sourceRoot":"","sources":["../../src/utils/materialApplicationUtils.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAChD,OAA4B,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrF,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAClE;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAOxH;AAKD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,gBAAgB,CAI/G;AACD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAQlH;AACD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAsCrF;AACD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE1F;AACD;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGtD;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAElE;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAElE;AACD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,GAAG,CAAC,MAAM,CAGtC,CAAC;AACH;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;IAC3D,OAAO,EAAE,KAAK,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACV,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;CACN,CA6BJ"}
+{"version":3,"file":"materialApplicationUtils.d.ts","sourceRoot":"","sources":["../../src/utils/materialApplicationUtils.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAChD,OAA4B,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrF,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAClE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAC3D;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAOxH;AAKD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,gBAAgB,CAI/G;AACD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAQlH;AACD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAsCrF;AACD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE1F;AACD;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGtD;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAElE;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAElE;AACD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,GAAG,CAAC,MAAM,CAGtC,CAAC;AACH;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;IAC3D,OAAO,EAAE,KAAK,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACV,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;CACN,CA6BJ"}

package/dist/utils/materialApplicationUtils.js

@@ -18,13 +18,22 @@ export const MATERIAL_INSTANCE_KEY = '_3driseMaterialInstance';
 // Key placed on edges group userData to prevent material bleed-through
 export const EDGES_GROUP_KEY = '__isEdgesGroup';
 export const GEREATIVE_EFFECTS_KEY = '__isGenerativeEffectsGroup';
+/**
+ * Set by a renderer that builds and owns its object's material itself — today the
+ * points renderers, while shader effects are active. Two writers on one
+ * `.material` is the bug this prevents: whichever loses keeps animating a
+ * material that is no longer on the mesh, and the object renders as whatever the
+ * winner left behind.
+ */
+export const SELF_OWNED_MATERIAL_KEY = '__ownsItsMaterial';
 /**
  * Traverses obj and its descendants, skipping subtrees whose root is marked
- * with EDGES_GROUP_KEY or GEREATIVE_EFFECTS_KEY — unless obj itself carries that mark (so an edges group
- * or generative effects group can still apply its own material via useMaterialApplication).
+ * with EDGES_GROUP_KEY, GEREATIVE_EFFECTS_KEY or SELF_OWNED_MATERIAL_KEY — unless obj itself
+ * carries that mark (so an edges group or generative effects group can still
+ * apply its own material via useMaterialApplication).
  */
 export function traverseSkippingEdgesAndEffects(obj, isRoot, callback) {
-    if (!isRoot && (obj.userData[EDGES_GROUP_KEY] || obj.userData[GEREATIVE_EFFECTS_KEY]))
+    if (!isRoot && (obj.userData[EDGES_GROUP_KEY] || obj.userData[GEREATIVE_EFFECTS_KEY] || obj.userData[SELF_OWNED_MATERIAL_KEY]))
         return;
     callback(obj);
     for (const child of obj.children) {

package/dist/utils/surfaceUtils.d.ts

@@ -0,0 +1,21 @@
+import type { CreatedObjectSettings, DisplayMode, EdgesType, ModeGroup } from '../types/scene3d';
+/** Display mode → the kind of object it draws. */
+export declare const DISPLAY_MODE_GROUPS: Record<DisplayMode, ModeGroup>;
+export declare function modeGroupOf(mode?: DisplayMode | null): ModeGroup;
+/**
+ * Edge decorations follow the same rule: `particles` edges are a Points object,
+ * every other edge type is built from meshes.
+ */
+export declare function edgesTypeGroupOf(type?: EdgesType | null): ModeGroup;
+/** The surface a created object draws, for material-compatibility purposes. */
+export declare function surfaceOf(settings?: Pick<CreatedObjectSettings, 'type' | 'modeConfig'> | null): ModeGroup;
+/**
+ * The one hard constraint: a Points object can only take the `particles`
+ * family, and that family only renders on a Points object. Everything else is
+ * an ordinary mesh material — the `line` family included, which is a material
+ * with line-like effects rather than a material for line primitives.
+ */
+export declare function materialTypeFitsSurface(materialType: string, surface: ModeGroup): boolean;
+/** The family to fall back to when the current one cannot draw on a surface. */
+export declare function defaultMaterialTypeForSurface(surface: ModeGroup): string;
+//# sourceMappingURL=surfaceUtils.d.ts.map

package/dist/utils/surfaceUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceUtils.d.ts","sourceRoot":"","sources":["../../src/utils/surfaceUtils.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEjG,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,WAAW,EAAE,SAAS,CAa9D,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAEhE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,CAEnE;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,GAAG,YAAY,CAAC,GAAG,IAAI,GAAG,SAAS,CAQzG;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAIzF;AAED,gFAAgF;AAChF,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAExE"}

package/dist/utils/surfaceUtils.js

@@ -0,0 +1,50 @@
+/** Display mode → the kind of object it draws. */
+export const DISPLAY_MODE_GROUPS = {
+    solid: 'mesh',
+    volume: 'points',
+    surface: 'points',
+    symmetric: 'points',
+    evenScatter: 'points',
+    vertices: 'points',
+    // plexus draws a point cloud plus connecting ribbons; the points dominate.
+    plexus: 'points',
+    edges3d: 'lines',
+    profile2d: 'lines',
+    wireframe: 'lines',
+    contourSlices: 'lines',
+};
+export function modeGroupOf(mode) {
+    return (mode && DISPLAY_MODE_GROUPS[mode]) || 'mesh';
+}
+/**
+ * Edge decorations follow the same rule: `particles` edges are a Points object,
+ * every other edge type is built from meshes.
+ */
+export function edgesTypeGroupOf(type) {
+    return type === 'particles' ? 'points' : 'lines';
+}
+/** The surface a created object draws, for material-compatibility purposes. */
+export function surfaceOf(settings) {
+    if (!settings)
+        return 'mesh';
+    if (settings.type === 'particles')
+        return 'points';
+    if (settings.type === 'mesh')
+        return modeGroupOf(settings.modeConfig?.mode);
+    return 'mesh';
+}
+/**
+ * The one hard constraint: a Points object can only take the `particles`
+ * family, and that family only renders on a Points object. Everything else is
+ * an ordinary mesh material — the `line` family included, which is a material
+ * with line-like effects rather than a material for line primitives.
+ */
+export function materialTypeFitsSurface(materialType, surface) {
+    return surface === 'points'
+        ? materialType === 'particles'
+        : materialType !== 'particles';
+}
+/** The family to fall back to when the current one cannot draw on a surface. */
+export function defaultMaterialTypeForSurface(surface) {
+    return surface === 'points' ? 'particles' : 'basic';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3driseai/3drise-core",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",