@3driseai/3drise-viewer 0.1.28 → 0.1.30

package/dist/operations/catalogue/trailStampStyles.js

@@ -0,0 +1,479 @@
+// The stamp trail styles (see trailStamps.ts): what each copy of the object turns into,
+// and how it goes. All of them are the object's own geometry or derived from it.
+//
+//   smoke      billows, rises, eaten by drifting density — smoke in its shape
+//   ash        burns from within along a glowing ember front; behind it, gone
+//   hologram   its hologram: object-space grid, Fresnel rim, scan bands; it glitches out
+//              band by band (each band jitters, then drops)
+//   ink        ink in water in its shape: swells and swirls, tears into ridged filaments
+//   frost      ice crystals grow over it, cracks open along cell borders, it melts away
+//   sand       its surface as grains (surface samples): released from the top down, they
+//              pour under gravity onto the floor and lie there in a little heap
+//   voxel      its shape as cubes (surface samples quantised to a grid): they drop from the
+//              top down, tumbling, and shrink away; crisp lit edges
+//   shatter    its own triangles cut into Voronoi shards (nearest surface seed): each shard
+//              turns and drifts outwards, glassy, and is gone
+//   wireframe  its real mesh edges as fine lines; each edge retracts into its middle
+import { BoxGeometry, BufferAttribute, BufferGeometry, EdgesGeometry, Matrix3, Matrix4, Vector3 } from 'three';
+import { surfaceOf } from './trailCore.js';
+import { defaultTiming, meshStamp, slotStamp } from './trailStamps.js';
+// ---------------------------------------------------------------- object → root-space helpers
+/** The object's meshes with the matrix that takes each into the object's root space. */
+function meshesInRoot(ctx) {
+    const out = [];
+    ctx.target.updateWorldMatrix(true, true);
+    const inv = new Matrix4().copy(ctx.target.matrixWorld).invert();
+    ctx.target.traverse((c) => {
+        if (!c.isMesh || c.isInstancedMesh || c.userData?.__opFxHelper || !c.geometry?.attributes?.position)
+            return;
+        const m = new Matrix4().multiplyMatrices(inv, c.matrixWorld);
+        out.push({ mesh: c, m, nm: new Matrix3().getNormalMatrix(m) });
+    });
+    return out;
+}
+/** Bounds of root-space points (y range for "from the top down"). */
+function yRange(pos) {
+    let lo = Infinity, hi = -Infinity;
+    for (let i = 1; i < pos.length; i += 3) {
+        lo = Math.min(lo, pos[i]);
+        hi = Math.max(hi, pos[i]);
+    }
+    return { lo, h: Math.max(1e-6, hi - lo) };
+}
+// ---------------------------------------------------------------- smoke
+export const smoke = meshStamp({
+    ...defaultTiming(6),
+    opacity: 0.8,
+    vertex: /* glsl */ `
+    float b = stpN(wp.xyz * 1.6 / uStpSpan + aStpSeed * 11.0);
+    wp.xyz += n * uStpSpan * (0.04 + uStpSize * 0.3) * (0.25 + 0.75 * b) * aStpAge;
+    wp.y += uStpSpan * 0.32 * aStpAge * aStpAge;`,
+    fragment: /* glsl */ `
+    vec3 q = vStpW * 2.6 / uStpSpan + vec3(0.0, -uStpTime * 0.35, 0.0) + vStpSeed * 5.0;
+    float d = stpFbm(q);
+    float edge = 0.12 + age * 0.85;
+    float keep = smoothstep(edge - 0.06, edge + 0.14, d);
+    float body = 0.25 + 0.75 * abs(dot(n, v));
+    float a = keep * body * uStpOpacity * smoothstep(0.0, 0.06, age) * pow(1.0 - age, 0.9);
+    float lit = 0.5 + 0.5 * n.y;
+    stpOut = vec4(mix(uStpC2, uStpC1, lit * (0.7 + 0.3 * d)), a);`,
+});
+// ---------------------------------------------------------------- ash
+export const ash = meshStamp({
+    ...defaultTiming(6),
+    opacity: 1,
+    vertex: /* glsl */ `
+    // what has burnt sags a touch and drifts up as it goes (the ash lifts off)
+    float f = stpFbm(L * 3.0 + aStpSeed * 7.0);
+    float burnt = smoothstep(f - 0.05, f + 0.25, aStpAge * 1.2 - 0.1);
+    wp.y += uStpSpan * 0.18 * burnt * burnt;
+    wp.xyz += n * uStpSpan * 0.02 * burnt;`,
+    fragment: /* glsl */ `
+    // the burn front: a field over the object's own space, its threshold climbing with age
+    float f = stpFbm(vStpL * 3.0 + vStpSeed * 7.0);
+    float t = age * 1.2 - 0.1;
+    float w = 0.04 + uStpSize * 0.09;
+    if (f < t - w) discard;                                        // burnt away
+    float ember = 1.0 - smoothstep(t - w, t + w * 0.6, f);       // 1 at the front, fading into the char
+    float shade = 0.5 + 0.5 * max(0.0, dot(n, normalize(vec3(0.35, 0.85, 0.3))));
+    vec3 ashCol = uStpC1 * shade * (0.75 + 0.25 * stpN(vStpL * 18.0));
+    vec3 col = mix(ashCol, uStpC2 * 2.6, ember * ember);          // the ember glows (over 1: it blooms)
+    float a = uStpOpacity * smoothstep(0.0, 0.05, age) * (0.88 + 0.12 * ember);
+    stpOut = vec4(col, a);`,
+});
+// ---------------------------------------------------------------- hologram
+export const hologram = meshStamp({
+    ...defaultTiming(5),
+    additive: true,
+    opacity: 0.38,
+    vertexPars: /* glsl */ `
+float holoBand(vec3 L, float seed) { return floor(L.y * 14.0 + seed * 3.0); }`,
+    vertex: /* glsl */ `
+    // a band about to drop jitters sideways
+    float band = holoBand(L, aStpSeed);
+    float death = 0.15 + 0.8 * stpH(vec3(band, aStpSeed * 13.0, 1.7));
+    float near = smoothstep(death - 0.12, death, aStpAge) * step(aStpAge, death);
+    wp.x += uStpSpan * 0.03 * near * sin(uStpTime * 47.0 + band * 3.1);`,
+    fragmentPars: /* glsl */ `
+float holoBand(vec3 L, float seed) { return floor(L.y * 14.0 + seed * 3.0); }
+float holoLine(float x, float k) { float g = abs(fract(x * k) - 0.5); return 1.0 - smoothstep(0.0, fwidth(x * k) * 1.2, g - 0.47); }`,
+    fragment: /* glsl */ `
+    float band = holoBand(vStpL, vStpSeed);
+    float death = 0.15 + 0.8 * stpH(vec3(band, vStpSeed * 13.0, 1.7));
+    if (age > death) discard;                                      // this band has dropped out
+    float flick = 1.0 - 0.7 * step(0.5, stpH(vec3(floor(uStpTime * 24.0), band, vStpSeed))) * smoothstep(death - 0.1, death, age);
+    float fres = pow(1.0 - abs(dot(n, v)), 2.0);
+    float grid = max(holoLine(vStpL.x, 9.0), max(holoLine(vStpL.y, 9.0), holoLine(vStpL.z, 9.0)));
+    float scan = 0.5 + 0.5 * sin((vStpL.y * 40.0 - uStpTime * 6.0));
+    // faint body, a clear rim, crisp grid lines — copies overlap, so each one is light
+    float a = uStpOpacity * flick * (0.02 + 0.22 * fres + 0.4 * grid) * (0.8 + 0.2 * scan) * smoothstep(0.0, 0.05, age) * (1.0 - 0.6 * age);
+    vec3 col = mix(uStpC1, uStpC2, grid * 0.7);
+    stpOut = vec4(col, a);`,
+});
+// ---------------------------------------------------------------- ink
+export const ink = meshStamp({
+    ...defaultTiming(7),
+    opacity: 0.85,
+    vertex: /* glsl */ `
+    // it swells and swirls like ink let go in water
+    vec3 q = wp.xyz * 0.9 / uStpSpan + vec3(0.0, uStpTime * 0.15, aStpSeed * 9.0);
+    vec3 drift = vec3(stpN(q) - 0.5, stpN(q + 17.3) - 0.5, stpN(q + 31.7) - 0.5);
+    float g = pow(aStpAge, 0.7);
+    wp.xyz += n * uStpSpan * (0.05 + uStpSize * 0.4) * g * (0.4 + stpN(q * 2.3));
+    wp.xyz += drift * uStpSpan * 0.9 * g;
+    wp.y -= uStpSpan * 0.12 * aStpAge * aStpAge;                    // ink is heavier than water`,
+    fragment: /* glsl */ `
+    // ridged filaments: it tears into threads as it thins
+    vec3 q = vStpW * 3.4 / uStpSpan + vec3(0.0, uStpTime * 0.1, vStpSeed * 4.0);
+    float r = 1.0 - abs(2.0 * stpFbm(q) - 1.0);
+    r = r * r;                                                     // narrower ridges: threads, not clouds
+    float th = 0.12 + age * 0.62;
+    float dens = smoothstep(th, th + 0.07, r);
+    float body = 0.3 + 0.7 * abs(dot(n, v));
+    vec3 col = mix(uStpC2, uStpC1, dens * body);                  // thick ink deep, thin edges bleed lighter
+    float a = uStpOpacity * dens * body * smoothstep(0.0, 0.08, age) * pow(1.0 - age, 0.8);
+    stpOut = vec4(col, a);`,
+});
+// ---------------------------------------------------------------- frost
+export const frost = meshStamp({
+    ...defaultTiming(7),
+    opacity: 0.9,
+    vertex: /* glsl */ `
+    // melting: it slumps as it goes
+    float melt = smoothstep(0.55, 1.0, aStpAge);
+    wp.y -= uStpSpan * 0.08 * melt * (0.5 + stpN(L * 4.0 + aStpSeed));`,
+    fragment: /* glsl */ `
+    vec3 cell = stpWorley(vStpL * (5.0 + uStpSize * 8.0) + vStpSeed * 3.0);
+    // crystals grow over it (a front through its own space), cracks open along cell borders, it melts from below
+    float grow = smoothstep(0.0, 0.22, age - 0.25 * stpN(vStpL * 2.0 + vStpSeed));
+    float crack = smoothstep(0.42, 0.7, age) * (1.0 - smoothstep(0.0, 0.035, cell.y - cell.x));
+    float meltT = smoothstep(0.55, 1.0, age);
+    if (stpFbm(vStpL * 4.0 + vec3(0.0, uStpTime * 0.05, vStpSeed)) + vStpL.y * 0.35 < meltT * 1.25 - 0.1) discard;
+    float fres = pow(1.0 - abs(dot(n, v)), 2.5);
+    float facet = 0.75 + 0.25 * cell.z;                            // each crystal catches the light differently
+    vec3 col = uStpC1 * facet * (0.6 + 0.4 * max(0.0, n.y)) + uStpC2 * (0.7 * fres + 1.4 * crack);
+    float a = uStpOpacity * grow * (0.35 + 0.45 * fres + 0.6 * crack) * (1.0 - meltT * 0.4);
+    stpOut = vec4(col, a);`,
+});
+// ---------------------------------------------------------------- sand (surface grains)
+export const sand = slotStamp({
+    ...defaultTiming(6),
+    kind: 'points',
+    opacity: 1,
+    derive(ctx) {
+        const s = surfaceOf(ctx.target, 7000, 59);
+        const { lo, h } = yRange(s.pos);
+        const rnd = new Float32Array(s.n * 4);
+        for (let i = 0; i < s.n; i++) {
+            rnd[i * 4] = Math.random();
+            rnd[i * 4 + 1] = Math.random();
+            rnd[i * 4 + 2] = Math.random();
+            rnd[i * 4 + 3] = (s.pos[i * 3 + 1] - lo) / h; // 0 at its base, 1 at its top
+        }
+        const g = new BufferGeometry();
+        g.setAttribute('position', new BufferAttribute(s.pos.slice(), 3));
+        g.setAttribute('normal', new BufferAttribute(s.nrm.slice(), 3));
+        g.setAttribute('aGrain', new BufferAttribute(rnd, 4));
+        return { geometry: g };
+    },
+    vertexPars: /* glsl */ `
+attribute vec4 aGrain;
+varying float vGrainMix;
+varying float vGrainFree;`,
+    vertexLocal: /* glsl */ `
+    vGrainMix = aGrain.y;`,
+    vertexWorld: /* glsl */ `
+    // released from the top down, then gravity; it lands and lies in a heap
+    float rel = (1.0 - aGrain.w) * 0.42 + aGrain.x * 0.14;
+    float tau = max(0.0, age - rel);
+    vGrainFree = smoothstep(0.0, 0.02, tau);
+    wp.y -= uStpSpan * 7.0 * tau * tau;
+    vec2 spread = (aGrain.zy - 0.5) * 2.0;
+    float landed = step(wp.y, uStpFloor + 0.004 * uStpSpan);
+    wp.xz += spread * uStpSpan * (0.05 * tau + 0.25 * landed * min(1.0, tau * 2.0));
+    wp.y = max(wp.y, uStpFloor + aGrain.x * 0.02 * uStpSpan);
+    stpSize = uStpPx * (0.75 + 0.5 * aGrain.z);`,
+    fragmentPars: /* glsl */ `
+varying float vGrainMix;
+varying float vGrainFree;`,
+    // a crisp round grain: a one-pixel anti-aliased edge, no soft sprite
+    fragment: /* glsl */ `
+    float d = length(pc);
+    float edge = clamp((1.0 - d) / max(fwidth(d), 1e-4), 0.0, 1.0);
+    float shade = 0.65 + 0.35 * max(0.0, n.y);
+    vec3 col = mix(uStpC1, uStpC2, vGrainMix * 0.8) * shade;
+    float a = edge * uStpOpacity * smoothstep(0.0, 0.03, age) * (1.0 - smoothstep(0.8, 1.0, age));
+    stpOut = vec4(col, a);`,
+});
+// ---------------------------------------------------------------- voxels
+export const voxel = slotStamp({
+    ...defaultTiming(5.5),
+    kind: 'mesh',
+    opacity: 1,
+    derive(ctx) {
+        const s = surfaceOf(ctx.target, 30000, 37);
+        let min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+        for (let i = 0; i < s.n; i++)
+            for (let a = 0; a < 3; a++) {
+                min[a] = Math.min(min[a], s.pos[i * 3 + a]);
+                max[a] = Math.max(max[a], s.pos[i * 3 + a]);
+            }
+        const res = Math.round(10 + ctx.p.amount * 16);
+        const cell = Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2], 1e-3) / res;
+        const cells = new Map();
+        for (let i = 0; i < s.n; i++) {
+            const ix = Math.floor((s.pos[i * 3] - min[0]) / cell), iy = Math.floor((s.pos[i * 3 + 1] - min[1]) / cell), iz = Math.floor((s.pos[i * 3 + 2] - min[2]) / cell);
+            const k = `${ix},${iy},${iz}`;
+            if (!cells.has(k))
+                cells.set(k, [min[0] + (ix + 0.5) * cell, min[1] + (iy + 0.5) * cell, min[2] + (iz + 0.5) * cell]);
+        }
+        const n = cells.size, h = Math.max(1e-6, max[1] - min[1]);
+        const vox = new Float32Array(n * 4), rnd = new Float32Array(n * 4);
+        let i = 0;
+        for (const c of cells.values()) {
+            vox.set([c[0], c[1], c[2], cell], i * 4);
+            rnd.set([Math.random(), Math.random(), Math.random(), (c[1] - min[1]) / h], i * 4);
+            i++;
+        }
+        return { geometry: new BoxGeometry(1, 1, 1), elements: { count: n, attrs: { aVox: { itemSize: 4, array: vox }, aVoxR: { itemSize: 4, array: rnd } } } };
+    },
+    vertexPars: /* glsl */ `
+attribute vec4 aVox;
+attribute vec4 aVoxR;
+varying vec3 vVoxBox;`,
+    vertexLocal: /* glsl */ `
+    // released from the top down; it tumbles as it drops and shrinks away
+    float rel = (1.0 - aVoxR.w) * 0.5 + aVoxR.x * 0.18;
+    float tau = max(0.0, age - rel);
+    float sc = 0.94 * (1.0 - smoothstep(0.22, 0.42, tau)) * smoothstep(0.0, 0.03, age);
+    mat3 R = stpRot(normalize(aVoxR.xyz - 0.5 + 1e-3), tau * (6.0 + 8.0 * aVoxR.y));
+    vVoxBox = position;
+    lp = aVox.xyz + R * (position * aVox.w * sc);
+    ln = R * normal;
+    L = aVox.xyz / uStpSpan;`,
+    vertexWorld: /* glsl */ `
+    float tau2 = max(0.0, age - ((1.0 - aVoxR.w) * 0.5 + aVoxR.x * 0.18));
+    wp.y -= uStpSpan * 4.0 * tau2 * tau2;`,
+    fragmentPars: /* glsl */ `
+varying vec3 vVoxBox;`,
+    // lit faces with a crisp edge line on every cube
+    fragment: /* glsl */ `
+    vec3 b = abs(vVoxBox) * 2.0;                                   // 0 centre … 1 face
+    float e2 = b.x + b.y + b.z - max(b.x, max(b.y, b.z));          // the two largest: near an edge → ~2
+    float w = fwidth(e2) * 1.5;
+    float edge = smoothstep(1.86 - w, 1.86 + w, e2);
+    float lit = 0.45 + 0.55 * max(0.0, dot(n, normalize(vec3(0.35, 0.85, 0.4))));
+    vec3 col = mix(uStpC1 * lit, uStpC2, edge * 0.85);
+    float a = uStpOpacity * (0.9 + 0.1 * edge) * (1.0 - smoothstep(0.85, 1.0, age));
+    stpOut = vec4(col, a);`,
+});
+// ---------------------------------------------------------------- shatter (its own triangles as Voronoi shards)
+export const shatter = slotStamp({
+    ...defaultTiming(5),
+    kind: 'mesh',
+    opacity: 0.9,
+    derive(ctx) {
+        const seedsS = surfaceOf(ctx.target, 2000, 71);
+        const nSeeds = Math.round(30 + ctx.p.amount * 90);
+        const seeds = new Float32Array(nSeeds * 3);
+        for (let k = 0; k < nSeeds; k++) {
+            const i = (Math.random() * seedsS.n) | 0;
+            seeds.set(seedsS.pos.subarray(i * 3, i * 3 + 3), k * 3);
+        }
+        const cellRnd = Array.from({ length: nSeeds }, () => [Math.random(), Math.random(), Math.random(), Math.random()]);
+        // the object's triangles in root space, non-indexed
+        const P = [], N = [];
+        const v = new Vector3(), nn = new Vector3();
+        for (const { mesh, m, nm } of meshesInRoot(ctx)) {
+            const g = mesh.geometry.index ? mesh.geometry.toNonIndexed() : mesh.geometry;
+            const pos = g.attributes.position, nor = g.attributes.normal;
+            if (pos.count > 300000)
+                continue;
+            for (let i = 0; i < pos.count; i++) {
+                v.fromBufferAttribute(pos, i).applyMatrix4(m);
+                P.push(v.x, v.y, v.z);
+                if (nor) {
+                    nn.fromBufferAttribute(nor, i).applyMatrix3(nm).normalize();
+                    N.push(nn.x, nn.y, nn.z);
+                }
+                else
+                    N.push(0, 1, 0);
+            }
+            if (g !== mesh.geometry)
+                g.dispose();
+        }
+        const n = P.length / 3;
+        // each triangle → its nearest seed's cell; a cell moves as one shard about its centroid
+        const cellOf = new Int32Array(n / 3);
+        const sum = new Float64Array(nSeeds * 3), cnt = new Uint32Array(nSeeds);
+        let cx = 0, cy = 0, cz = 0;
+        for (let t = 0, f = 0; t < n; t += 3, f++) {
+            const x = (P[t * 3] + P[t * 3 + 3] + P[t * 3 + 6]) / 3, y = (P[t * 3 + 1] + P[t * 3 + 4] + P[t * 3 + 7]) / 3, z = (P[t * 3 + 2] + P[t * 3 + 5] + P[t * 3 + 8]) / 3;
+            let best = 0, bd = Infinity;
+            for (let k = 0; k < nSeeds; k++) {
+                const dx = x - seeds[k * 3], dy = y - seeds[k * 3 + 1], dz = z - seeds[k * 3 + 2], d = dx * dx + dy * dy + dz * dz;
+                if (d < bd) {
+                    bd = d;
+                    best = k;
+                }
+            }
+            cellOf[f] = best;
+            sum[best * 3] += x;
+            sum[best * 3 + 1] += y;
+            sum[best * 3 + 2] += z;
+            cnt[best]++;
+            cx += x;
+            cy += y;
+            cz += z;
+        }
+        const tris = Math.max(1, n / 3);
+        cx /= tris;
+        cy /= tris;
+        cz /= tris;
+        const cen = new Float32Array(n * 3), dir = new Float32Array(n * 3), rnd = new Float32Array(n * 4);
+        for (let t = 0, f = 0; t < n; t += 3, f++) {
+            const k = cellOf[f], inv = 1 / Math.max(1, cnt[k]);
+            const c = [sum[k * 3] * inv, sum[k * 3 + 1] * inv, sum[k * 3 + 2] * inv];
+            const d = new Vector3(c[0] - cx, c[1] - cy, c[2] - cz).normalize();
+            for (let vtx = t; vtx < t + 3; vtx++) {
+                cen.set(c, vtx * 3);
+                dir.set([d.x, d.y, d.z], vtx * 3);
+                rnd.set(cellRnd[k], vtx * 4);
+            }
+        }
+        const g = new BufferGeometry();
+        g.setAttribute('position', new BufferAttribute(new Float32Array(P), 3));
+        g.setAttribute('normal', new BufferAttribute(new Float32Array(N), 3));
+        g.setAttribute('aShCen', new BufferAttribute(cen, 3));
+        g.setAttribute('aShDir', new BufferAttribute(dir, 3));
+        g.setAttribute('aShRnd', new BufferAttribute(rnd, 4));
+        return { geometry: g };
+    },
+    vertexPars: /* glsl */ `
+attribute vec3 aShCen;
+attribute vec3 aShDir;
+attribute vec4 aShRnd;`,
+    vertexLocal: /* glsl */ `
+    // each shard lets go at its own moment, turns about its centre and drifts outwards
+    float tau = max(0.0, age - aShRnd.x * 0.3);
+    mat3 R = stpRot(normalize(aShRnd.yzw - 0.5 + 1e-3), tau * (3.0 + 5.0 * aShRnd.y));
+    float sc = 1.0 - smoothstep(0.45, 0.7, tau);
+    lp = aShCen + R * (position - aShCen) * sc + aShDir * uStpSpan * (0.05 + 0.35 * uStpSize) * tau;
+    ln = R * normal;`,
+    vertexWorld: /* glsl */ `
+    float tau2 = max(0.0, age - aShRnd.x * 0.3);
+    wp.y -= uStpSpan * 1.6 * tau2 * tau2;`,
+    // glassy: a faint body, a bright Fresnel rim
+    fragment: /* glsl */ `
+    float fres = pow(1.0 - abs(dot(n, v)), 2.2);
+    float lit = 0.5 + 0.5 * max(0.0, dot(n, normalize(vec3(0.35, 0.85, 0.4))));
+    vec3 col = uStpC1 * lit + uStpC2 * fres * 0.9;
+    float a = uStpOpacity * (0.32 + 0.6 * fres) * smoothstep(0.0, 0.04, age) * (1.0 - smoothstep(0.75, 1.0, age));
+    stpOut = vec4(col, a);`,
+});
+// ---------------------------------------------------------------- wireframe (its real edges)
+export const wireframe = slotStamp({
+    ...defaultTiming(5),
+    kind: 'lines',
+    additive: true,
+    opacity: 1,
+    derive(ctx) {
+        const P = [], M = [], R = [];
+        const a = new Vector3(), b = new Vector3();
+        for (const { mesh, m } of meshesInRoot(ctx)) {
+            if (mesh.geometry.attributes.position.count > 200000)
+                continue;
+            const e = new EdgesGeometry(mesh.geometry, 18);
+            const pos = e.attributes.position;
+            for (let i = 0; i < pos.count; i += 2) {
+                a.fromBufferAttribute(pos, i).applyMatrix4(m);
+                b.fromBufferAttribute(pos, i + 1).applyMatrix4(m);
+                const mx = (a.x + b.x) / 2, my = (a.y + b.y) / 2, mz = (a.z + b.z) / 2, r = Math.random();
+                P.push(a.x, a.y, a.z, b.x, b.y, b.z);
+                M.push(mx, my, mz, mx, my, mz);
+                R.push(r, r);
+            }
+            e.dispose();
+        }
+        const g = new BufferGeometry();
+        g.setAttribute('position', new BufferAttribute(new Float32Array(P), 3));
+        g.setAttribute('aWireMid', new BufferAttribute(new Float32Array(M), 3));
+        g.setAttribute('aWireR', new BufferAttribute(new Float32Array(R), 1));
+        return { geometry: g };
+    },
+    vertexPars: /* glsl */ `
+attribute vec3 aWireMid;
+attribute float aWireR;
+varying float vWireF;`,
+    vertexLocal: /* glsl */ `
+    // each edge retracts into its middle, at its own moment
+    float rel = aWireR * 0.45;
+    float f = smoothstep(rel, rel + 0.45, age);
+    vWireF = f;
+    lp = mix(position, aWireMid, f);`,
+    fragmentPars: /* glsl */ `
+varying float vWireF;`,
+    fragment: /* glsl */ `
+    vec3 col = mix(uStpC1, uStpC2, smoothstep(0.0, 0.8, age));
+    float a = uStpOpacity * (1.0 - vWireF) * smoothstep(0.0, 0.03, age);
+    stpOut = vec4(col, a);`,
+});
+// ---------------------------------------------------------------- bubbles (from its surface)
+// Soap bubbles form all over the copy's surface (surface samples), let go one by one,
+// rise with a little buoyant acceleration, wobble, and pop — each a crisp sphere drawn in
+// a point: an anti-aliased edge, a thin-film sheen sliding between its two colours with the
+// viewing angle, a bright rim and a small window highlight. Sized in world units (they
+// shrink with distance like real bubbles).
+export const bubbles = slotStamp({
+    ...defaultTiming(6),
+    kind: 'points',
+    opacity: 1,
+    derive(ctx) {
+        const s = surfaceOf(ctx.target, 240, 83);
+        const rnd = new Float32Array(s.n * 4);
+        for (let i = 0; i < s.n; i++)
+            rnd.set([Math.random(), Math.random(), Math.random(), Math.random()], i * 4);
+        const g = new BufferGeometry();
+        g.setAttribute('position', new BufferAttribute(s.pos.slice(), 3));
+        g.setAttribute('normal', new BufferAttribute(s.nrm.slice(), 3));
+        g.setAttribute('aBub', new BufferAttribute(rnd, 4));
+        return { geometry: g };
+    },
+    vertexPars: /* glsl */ `
+attribute vec4 aBub;
+varying float vBubA;
+varying float vBubSeed;`,
+    vertexLocal: /* glsl */ `
+    vBubSeed = aBub.w;`,
+    vertexWorld: /* glsl */ `
+    float rel = aBub.x * 0.35;                                     // when it lets go of the surface
+    float tau = max(0.0, age - rel);
+    float popAt = 0.35 + 0.55 * aBub.y;                            // how long it lives once free
+    // forms on the surface, then rises (accelerating a little) and wobbles
+    wp.xyz += n * uStpSpan * 0.015 * smoothstep(0.0, 0.05, age);
+    wp.y += uStpSpan * (0.6 + 0.8 * aBub.z) * pow(tau, 1.35);
+    wp.x += uStpSpan * 0.05 * sin(tau * 13.0 + aBub.w * 6.28) * smoothstep(0.0, 0.1, tau);
+    wp.z += uStpSpan * 0.05 * cos(tau * 11.0 + aBub.z * 6.28) * smoothstep(0.0, 0.1, tau);
+    float r = uStpSpan * (0.02 + uStpSize * 0.07) * (0.3 + 0.9 * aBub.z * aBub.z) * smoothstep(0.0, 0.08, age);
+    // the pop: it swells a touch and is gone in a blink
+    float pop = smoothstep(popAt - 0.02, popAt, tau);
+    r *= 1.0 + 0.25 * pop;
+    vBubA = 1.0 - step(popAt, tau);
+    vec4 cp = projectionMatrix * viewMatrix * wp;
+    stpSize = max(1.0, 2.0 * r * projectionMatrix[1][1] * uStpRes.y * 0.5 / max(cp.w, 1e-4));`,
+    fragmentPars: /* glsl */ `
+varying float vBubA;
+varying float vBubSeed;`,
+    fragment: /* glsl */ `
+    if (vBubA < 0.5) discard;                                      // popped
+    float d = length(pc);
+    float edge = clamp((1.0 - d) / max(fwidth(d), 1e-4), 0.0, 1.0);
+    float nz = sqrt(max(0.0, 1.0 - d * d));                        // the sphere's normal, facing us
+    float fres = pow(1.0 - nz, 2.2);
+    // thin film: the colour slides with the viewing angle and drifts slowly
+    float film = 0.5 + 0.5 * cos(6.2832 * (fres * 1.4 + vBubSeed + uStpTime * 0.08));
+    vec3 col = mix(uStpC1, uStpC2, film);
+    float window = smoothstep(0.26, 0.0, length(pc - vec2(-0.34, 0.36)));   // a small bright reflection
+    float a = edge * uStpOpacity * (0.06 + 0.9 * fres + 0.95 * window) * (1.0 - smoothstep(0.85, 1.0, age));
+    stpOut = vec4(col + window * 0.8, a);`,
+});

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

@@ -0,0 +1,57 @@
+import { BufferGeometry, Matrix4 } from 'three';
+import type { TrailCtx, TrailStyle } from './trailCore';
+export declare const MAX_STAMPS = 24;
+export interface Stamp {
+    m: Matrix4;
+    t: number;
+    seed: number;
+}
+export interface StampTiming {
+    /** Life of a stamp in seconds, from the settings. */
+    life: (ctx: TrailCtx) => number;
+    /** Distance between stamps in object sizes, from the settings. */
+    spacing: (ctx: TrailCtx) => number;
+}
+export declare const defaultTiming: (lifeScale: number) => StampTiming;
+export declare const STP_NOISE = "\nfloat stpH(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 stpN(vec3 x) {\n    vec3 i = floor(x), f = fract(x); f = f * f * (3.0 - 2.0 * f);\n    return mix(mix(mix(stpH(i), stpH(i + vec3(1, 0, 0)), f.x), mix(stpH(i + vec3(0, 1, 0)), stpH(i + vec3(1, 1, 0)), f.x), f.y),\n               mix(mix(stpH(i + vec3(0, 0, 1)), stpH(i + vec3(1, 0, 1)), f.x), mix(stpH(i + vec3(0, 1, 1)), stpH(i + vec3(1, 1, 1)), f.x), f.y), f.z);\n}\nfloat stpFbm(vec3 p) { return 0.55 * stpN(p) + 0.3 * stpN(p * 2.07 + 3.1) + 0.15 * stpN(p * 4.13 + 7.7); }\nvec3 stpHash3(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}\n// cellular: (F1, F2, cell id)\nvec3 stpWorley(vec3 p) {\n    vec3 i = floor(p), f = fract(p);\n    float f1 = 8.0, f2 = 8.0, 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 = stpHash3(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}\nmat3 stpRot(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}";
+export interface MeshStampConfig extends StampTiming {
+    /** GLSL before main (vertex), may use STP_NOISE. */
+    vertexPars?: string;
+    /** Vertex body: change `wp` (vec4, world) / `n` (vec3, world) from `L`, `aStpAge`, `aStpSeed`. */
+    vertex: string;
+    fragmentPars?: string;
+    /** Fragment body: set `stpOut`. */
+    fragment: string;
+    additive?: boolean;
+    /** Strength multiplier on Strength. */
+    opacity?: number;
+}
+export declare function meshStamp(cfg: MeshStampConfig): TrailStyle;
+/** Geometry derived from the object, in its ROOT space, plus optional per-element instance data. */
+export interface Derived {
+    geometry: BufferGeometry;
+    /** Per element (repeated for every stamp slot); omit for one element (the geometry itself). */
+    elements?: {
+        count: number;
+        attrs: Record<string, {
+            itemSize: number;
+            array: Float32Array;
+        }>;
+    };
+}
+export interface SlotStampConfig extends StampTiming {
+    kind: 'points' | 'lines' | 'mesh';
+    /** Build the derived geometry (cached by the style as it likes). */
+    derive: (ctx: TrailCtx) => Derived;
+    vertexPars?: string;
+    /** Object-local stage: move `lp` (vec3, root-local) / `ln` (normal) from `age`, `seed`, element attributes. */
+    vertexLocal?: string;
+    /** World stage: move `wp` / `n` (after the stamp's matrix). Set `stpSize` (px) for points. */
+    vertexWorld?: string;
+    fragmentPars?: string;
+    fragment: string;
+    additive?: boolean;
+    opacity?: number;
+}
+export declare function slotStamp(cfg: SlotStampConfig): TrailStyle;
+//# sourceMappingURL=trailStamps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trailStamps.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/trailStamps.ts"],"names":[],"mappings":"AAwBA,OAAO,EACgC,cAAc,EACK,OAAO,EAChE,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAExD,eAAO,MAAM,UAAU,KAAK,CAAC;AAK7B,MAAM,WAAW,KAAK;IAAG,CAAC,EAAE,OAAO,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAE9D,MAAM,WAAW,WAAW;IACxB,qDAAqD;IACrD,IAAI,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAC;IAChC,kEAAkE;IAClE,OAAO,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAC;CACtC;AAED,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,KAAG,WAGhD,CAAC;AAwBH,eAAO,MAAM,SAAS,smDA8BpB,CAAC;AA8DH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAChD,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CAyF1D;AAID,oGAAoG;AACpG,MAAM,WAAW,OAAO;IACpB,QAAQ,EAAE,cAAc,CAAC;IACzB,+FAA+F;IAC/F,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,YAAY,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CAClG;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAChD,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAClC,oEAAoE;IACpE,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+GAA+G;IAC/G,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CA4F1D"}