@3driseai/3drise-viewer 0.1.28 → 0.1.29

package/dist/operations/catalogue/swirl.js

@@ -22,7 +22,7 @@ function pose(target, st, p) {
     const q = new Quaternion().setFromAxisAngle(UP, dir * turns * 2 * Math.PI * 1.6 * t * t);
     const k = 1 - smoothstep(0.3, 1, t);
     const s = new Vector3(1, 1, 1).multiplyScalar(Math.max(k, 1e-4));
-    poseAbout(target, r, r.centerLocal, q, s, off);
+    poseAbout(target, r, r.centerLocal, q, s, off, KEY);
 }
 const smoothstep = (a, b, x) => { const v = Math.min(1, Math.max(0, (x - a) / (b - a))); return v * v * (3 - 2 * v); };
 export default defineOperation({
@@ -32,7 +32,8 @@ export default defineOperation({
     channel: 'transform',
     multi: true,
     toggles: true,
-    usableIn: ['interaction', 'action'],
+    usableIn: ['interaction', 'action', 'object'],
+    presence: 'vanish',
     params: {
         turns: { type: 'number', label: 'Turns', default: 1.5, min: 0.5, max: 6, step: 0.25 },
         radius: { type: 'number', label: 'Radius', default: 0.6, min: 0, max: 3, step: 0.05, hint: 'A fraction of the object’s width' },
@@ -43,7 +44,7 @@ export default defineOperation({
     apply(target, p) {
         let st = target.userData[KEY];
         if (!st) {
-            st = { rest: acquireRest(target), proxy: { t: 0 }, visible: target.visible };
+            st = { rest: acquireRest(target, KEY), proxy: { t: 0 }, visible: target.visible };
             target.userData[KEY] = st;
         }
         const s = st;
@@ -58,12 +59,12 @@ export default defineOperation({
         const s = target.userData[KEY];
         if (!s)
             return;
-        target.visible = s.visible;
+        target.visible = true; // it comes back shown (it may have been made while the object was hidden)
         gsap.killTweensOf(s.proxy);
         gsap.to(s.proxy, {
             t: 0, duration: Number(p.duration), ease: 'power2.out',
             onUpdate: () => pose(target, s, p),
-            onComplete: () => { delete target.userData[KEY]; releaseRest(target); },
+            onComplete: () => { delete target.userData[KEY]; releaseRest(target, KEY); },
         });
     },
 });

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

@@ -0,0 +1,89 @@
+import { Color, Group, Matrix4, Quaternion, Vector3 } from 'three';
+import type { Object3D } from 'three';
+export declare const CAP = 480;
+export interface Sample {
+    t: number;
+    p: Vector3;
+    q: Quaternion;
+    s: Vector3;
+}
+export interface TrailParams {
+    style: string;
+    length: number;
+    amount: number;
+    size: number;
+    opacity: number;
+    /** The style's colours (linear), from its own settings — see each style for what they colour. */
+    color: Color;
+    color2: Color;
+    color3: Color;
+}
+export interface TrailCtx {
+    target: Object3D;
+    group: Group;
+    env: {
+        v: number;
+    };
+    p: TrailParams;
+    /** Bounding diameter of the object (world), and the floor under it (world y of its base). */
+    span: number;
+    floor: number;
+    hist: Sample[];
+    head: number;
+    count: number;
+    now: number;
+    dt: number;
+    vel: Vector3;
+    acc: Vector3;
+    speed: number;
+    world: Matrix4;
+    cam: Vector3 | null;
+    /** Called by the core when the history restarts (a teleport): simulations reset too. */
+    onReset?: () => void;
+}
+export interface TrailStyle {
+    /** Build meshes into ctx.group (compiled before shown by the caller). */
+    build(ctx: TrailCtx): void;
+    /** Every frame, after the history has the new sample. */
+    update(ctx: TrailCtx): void;
+    /** Particles still in flight — switching off waits for them to finish (never cut mid-air). */
+    alive?(ctx: TrailCtx): boolean;
+    /** Free what build made (geometries, materials) — the group itself is removed by the caller. */
+    dispose?(ctx: TrailCtx): void;
+}
+export declare const smooth: (a: number, b: number, x: number) => number;
+export declare const clamp01: (x: number) => number;
+export declare function newHistory(): Sample[];
+/** Sample the object now; a jump of more than two sizes in one frame restarts the history. */
+export declare function record(ctx: TrailCtx, now: number): void;
+/** The pose `ago` seconds back (interpolated); false when the history does not reach that far. */
+export declare function poseAgo(ctx: TrailCtx, ago: number, out: Sample): boolean;
+/** How far a past pose is from the pose now, in object sizes (position + turn + scale). */
+export declare function awayFromNow(ctx: TrailCtx, s: Sample): number;
+export declare function cameraPos(out: Vector3): Vector3 | null;
+export interface SurfacePts {
+    pos: Float32Array;
+    nrm: Float32Array;
+    col: Float32Array;
+    n: number;
+}
+export declare function surfaceOf(target: Object3D, count: number, seed: number): SurfacePts;
+/** `k` points spread over the surface (farthest-point picks), root-local. */
+export declare function spreadPoints(target: Object3D, k: number, seed?: number): Vector3[];
+/** Bounding diameter (world) and the world y of the object's base. */
+export declare function measure(target: Object3D): {
+    span: number;
+    floor: number;
+};
+/** Smooth value noise in [−1, 1]. */
+export declare function vnoise(x: number, y: number, z: number): number;
+/** Divergence-free (curl) flow at a point — swirls without sinks or sources. */
+export declare function curl(x: number, y: number, z: number, out: Vector3): Vector3;
+/**
+ * Blackbody-like ramp for a cooling spark, linear RGB: 1 = white-hot, 0.6 yellow,
+ * 0.35 orange, 0.15 deep red, 0 = gone.
+ */
+export declare function blackbody(t: number, out: Color): Color;
+/** GLSL: anti-aliased edge — 1 inside, 0 outside, a one-pixel ramp (fragment only). */
+export declare const GLSL_AA = "\nfloat trlAA(float d) { float w = fwidth(d); return clamp(0.5 - d / max(w, 1e-5), 0.0, 1.0); }";
+//# sourceMappingURL=trailCore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trailCore.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/trailCore.ts"],"names":[],"mappings":"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"}

package/dist/operations/catalogue/trailCore.js

@@ -0,0 +1,190 @@
+// Motion trail — the shared core every trail style is built on (see motionTrail.ts).
+//
+//   history   the object's world pose, sampled every frame on gsap's clock, with
+//             interpolated look-ups back in time (poseAgo)
+//   motion    smoothed velocity and acceleration of the object (world units / s)
+//   surface   surface samples of the object (root-local position, normal, colour)
+//   camera    where the camera is (for camera-facing ribbons and lines)
+//   helpers   curl noise, blackbody ramp, farthest-point picks, smoothstep
+//
+// A style gets a TrailCtx: it builds its meshes into ctx.group (which lives in the
+// SCENE, not under the object — the trail outlives an exit that hides the object)
+// and updates them every frame. ctx.env (0…1) is the effect's on / off envelope.
+import { Quaternion, Vector3 } from 'three';
+import { sampleSurfaceCached } from './surfaceSample.js';
+import cameraManager from '../../utils/CameraSingleton.js';
+export const CAP = 480; // history samples kept (~8 s at 60 fps)
+export const smooth = (a, b, x) => { const v = Math.min(1, Math.max(0, (x - a) / (b - a))); return v * v * (3 - 2 * v); };
+export const clamp01 = (x) => Math.min(1, Math.max(0, x));
+// ---------------------------------------------------------------- history & motion
+const _p = new Vector3(), _q = new Quaternion(), _s = new Vector3(), _v = new Vector3(), _dv = new Vector3();
+export function newHistory() {
+    return Array.from({ length: CAP }, () => ({ t: 0, p: new Vector3(), q: new Quaternion(), s: new Vector3() }));
+}
+/** Sample the object now; a jump of more than two sizes in one frame restarts the history. */
+export function record(ctx, now) {
+    const t = ctx.target;
+    t.updateWorldMatrix(true, false);
+    ctx.world.copy(t.matrixWorld);
+    ctx.world.decompose(_p, _q, _s);
+    const last = ctx.count ? ctx.hist[ctx.head] : null;
+    ctx.dt = last ? Math.max(0, now - last.t) : 0;
+    ctx.now = now;
+    if (last && last.p.distanceTo(_p) > 2 * ctx.span && ctx.dt < 0.12) {
+        ctx.count = 0;
+        ctx.vel.set(0, 0, 0);
+        ctx.acc.set(0, 0, 0);
+        ctx.speed = 0;
+        ctx.onReset?.();
+    }
+    else if (last && ctx.dt > 1e-5) {
+        // velocity and acceleration, smoothed over ~50 ms (frame-rate independent)
+        _v.subVectors(_p, last.p).divideScalar(ctx.dt);
+        const k = 1 - Math.exp(-ctx.dt / 0.05);
+        _dv.copy(ctx.vel);
+        ctx.vel.lerp(_v, k);
+        _dv.subVectors(ctx.vel, _dv).divideScalar(ctx.dt);
+        ctx.acc.lerp(_dv, 1 - Math.exp(-ctx.dt / 0.06));
+        ctx.speed = ctx.vel.length() / ctx.span;
+    }
+    if (last && ctx.dt <= 1e-5 && ctx.count)
+        return; // same instant (composed twice): keep one sample
+    ctx.head = (ctx.head + 1) % CAP;
+    const e = ctx.hist[ctx.head];
+    e.t = now;
+    e.p.copy(_p);
+    e.q.copy(_q);
+    e.s.copy(_s);
+    ctx.count = Math.min(CAP, ctx.count + 1);
+}
+/** The pose `ago` seconds back (interpolated); false when the history does not reach that far. */
+export function poseAgo(ctx, ago, out) {
+    if (!ctx.count)
+        return false;
+    const now = ctx.hist[ctx.head].t, want = now - ago;
+    let i = ctx.head;
+    for (let k = 0; k < ctx.count - 1; k++) {
+        const prev = (i - 1 + CAP) % CAP;
+        const a = ctx.hist[prev], b = ctx.hist[i];
+        if (a.t <= want) {
+            const f = b.t > a.t ? (want - a.t) / (b.t - a.t) : 0;
+            out.p.lerpVectors(a.p, b.p, f);
+            out.q.slerpQuaternions(a.q, b.q, f);
+            out.s.lerpVectors(a.s, b.s, f);
+            out.t = want;
+            return true;
+        }
+        i = prev;
+    }
+    const o = ctx.hist[i];
+    out.p.copy(o.p);
+    out.q.copy(o.q);
+    out.s.copy(o.s);
+    out.t = o.t;
+    return ago <= 0;
+}
+/** How far a past pose is from the pose now, in object sizes (position + turn + scale). */
+export function awayFromNow(ctx, s) {
+    const now = ctx.hist[ctx.head];
+    return s.p.distanceTo(now.p) / ctx.span + 1.4 * (1 - Math.abs(s.q.dot(now.q))) + Math.abs(s.s.x - now.s.x);
+}
+export function cameraPos(out) {
+    const cam = cameraManager.getCamera?.();
+    if (!cam)
+        return null;
+    cam.updateMatrixWorld();
+    return cam.getWorldPosition(out);
+}
+export function surfaceOf(target, count, seed) {
+    const s = sampleSurfaceCached(target, count, seed);
+    return { pos: s.position, nrm: s.normal, col: s.color, n: s.position.length / 3 };
+}
+/** `k` points spread over the surface (farthest-point picks), root-local. */
+export function spreadPoints(target, k, seed = 11) {
+    const s = surfaceOf(target, 500, seed);
+    const pts = [];
+    if (!s.n)
+        return pts;
+    const at = (i) => new Vector3(s.pos[i * 3], s.pos[i * 3 + 1], s.pos[i * 3 + 2]);
+    pts.push(at(0));
+    const d = new Float32Array(s.n).fill(Infinity);
+    while (pts.length < Math.min(k, s.n)) {
+        const last = pts[pts.length - 1];
+        let best = -1, bi = 0;
+        for (let i = 0; i < s.n; i++) {
+            const v = at(i);
+            d[i] = Math.min(d[i], v.distanceToSquared(last));
+            if (d[i] > best) {
+                best = d[i];
+                bi = i;
+            }
+        }
+        pts.push(at(bi));
+    }
+    return pts;
+}
+/** Bounding diameter (world) and the world y of the object's base. */
+export function measure(target) {
+    target.updateWorldMatrix(true, true);
+    let r = 0, floor = Infinity;
+    const v = new Vector3();
+    target.traverse((c) => {
+        if (!c.isMesh || !c.geometry || c.userData?.__opFxHelper)
+            return;
+        const g = c.geometry;
+        if (!g.boundingSphere)
+            g.computeBoundingSphere();
+        if (!g.boundingBox)
+            g.computeBoundingBox();
+        const ws = new Vector3();
+        c.getWorldScale(ws);
+        r = Math.max(r, g.boundingSphere.radius * Math.max(ws.x, ws.y, ws.z));
+        const b = g.boundingBox;
+        for (let i = 0; i < 8; i++) {
+            v.set(i & 1 ? b.max.x : b.min.x, i & 2 ? b.max.y : b.min.y, i & 4 ? b.max.z : b.min.z).applyMatrix4(c.matrixWorld);
+            floor = Math.min(floor, v.y);
+        }
+    });
+    return { span: Math.max(2 * r, 1e-3), floor: Number.isFinite(floor) ? floor : 0 };
+}
+// ---------------------------------------------------------------- noise
+function hash3(x, y, z) {
+    let h = (x * 374761393 + y * 668265263 + z * 2147483647) | 0;
+    h = (h ^ (h >>> 13)) * 1274126177;
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967295;
+}
+/** Smooth value noise in [−1, 1]. */
+export function vnoise(x, y, z) {
+    const xi = Math.floor(x), yi = Math.floor(y), zi = Math.floor(z);
+    const xf = x - xi, yf = y - yi, zf = z - zi;
+    const u = xf * xf * (3 - 2 * xf), v = yf * yf * (3 - 2 * yf), w = zf * zf * (3 - 2 * zf);
+    const l = (a, b, t) => a + (b - a) * t;
+    const c = (dx, dy, dz) => hash3(xi + dx, yi + dy, zi + dz);
+    return 2 * l(l(l(c(0, 0, 0), c(1, 0, 0), u), l(c(0, 1, 0), c(1, 1, 0), u), v), l(l(c(0, 0, 1), c(1, 0, 1), u), l(c(0, 1, 1), c(1, 1, 1), u), v), w) - 1;
+}
+/** Divergence-free (curl) flow at a point — swirls without sinks or sources. */
+export function curl(x, y, z, out) {
+    const e = 0.1;
+    const A = (px, py, pz) => vnoise(px, py, pz);
+    const B = (px, py, pz) => vnoise(px + 31.4, py + 17.2, pz + 5.9);
+    const C = (px, py, pz) => vnoise(px + 9.1, py + 43.7, pz + 23.3);
+    const dCdy = (C(x, y + e, z) - C(x, y - e, z)) / (2 * e), dBdz = (B(x, y, z + e) - B(x, y, z - e)) / (2 * e);
+    const dAdz = (A(x, y, z + e) - A(x, y, z - e)) / (2 * e), dCdx = (C(x + e, y, z) - C(x - e, y, z)) / (2 * e);
+    const dBdx = (B(x + e, y, z) - B(x - e, y, z)) / (2 * e), dAdy = (A(x, y + e, z) - A(x, y - e, z)) / (2 * e);
+    return out.set(dCdy - dBdz, dAdz - dCdx, dBdx - dAdy);
+}
+// ---------------------------------------------------------------- colour
+/**
+ * Blackbody-like ramp for a cooling spark, linear RGB: 1 = white-hot, 0.6 yellow,
+ * 0.35 orange, 0.15 deep red, 0 = gone.
+ */
+export function blackbody(t, out) {
+    const x = clamp01(t);
+    const r = smooth(0.02, 0.3, x);
+    const g = Math.pow(smooth(0.18, 0.75, x), 1.6);
+    const b = Math.pow(smooth(0.55, 1, x), 2);
+    return out.setRGB(r * 1.0, g * 0.82, b * 0.75);
+}
+/** GLSL: anti-aliased edge — 1 inside, 0 outside, a one-pixel ramp (fragment only). */
+export const GLSL_AA = /* glsl */ `
+float trlAA(float d) { float w = fwidth(d); return clamp(0.5 - d / max(w, 1e-5), 0.0, 1.0); }`;

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

@@ -0,0 +1,5 @@
+import { type TrailStyle } from './trailCore';
+export declare const afterimage: TrailStyle;
+export declare const longExposure: TrailStyle;
+export declare const chromaticEcho: TrailStyle;
+//# sourceMappingURL=trailGhosts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trailGhosts.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/trailGhosts.ts"],"names":[],"mappings":"AAmBA,OAAO,EAA8E,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AA6I1H,eAAO,MAAM,UAAU,YAOrB,CAAC;AAEH,eAAO,MAAM,YAAY,YASvB,CAAC;AAEH,eAAO,MAAM,aAAa,YAQxB,CAAC"}

package/dist/operations/catalogue/trailGhosts.js

@@ -0,0 +1,179 @@
+// Ghost trails — copies of the object's own geometry placed at its poses back in time
+// (instanced per mesh, sharing the mesh's attributes), drawn as additive Fresnel shells.
+// One machine, three looks:
+//
+//   afterimage      a handful of distinct copies fading along the path, colour →
+//                   tail colour                                              (length × 1)
+//   longExposure    many faint copies, so close they read as one continuous
+//                   smear — a long-exposure photograph of the move           (length × 1.25)
+//   chromaticEcho   three copies a beat apart in three colours (red, green, blue by
+//                   default): they split into a fringe when it moves fast and add
+//                   back up to white as they close in                         (length × 0.5)
+//
+// A copy that sits on the object draws nothing (alpha ∝ how far its pose is from now),
+// so a still object has no trail.
+import { AdditiveBlending, BufferGeometry, Color, DoubleSide, InstancedBufferAttribute, InstancedMesh, Matrix4, Quaternion, ShaderMaterial, Vector3, } from 'three';
+import { awayFromNow, poseAgo, smooth } from './trailCore.js';
+const MAX_MESHES = 24;
+const VERT = /* glsl */ `
+attribute float aTrlAlpha;
+attribute vec3 aTrlTint;
+varying float vTrlA;
+varying vec3 vTrlTint;
+varying vec3 vTrlN;
+varying vec3 vTrlV;
+void main() {
+    vTrlA = aTrlAlpha;
+    vTrlTint = aTrlTint;
+    mat4 m = modelMatrix * instanceMatrix;
+    vec4 wp = m * vec4(position, 1.0);
+    vTrlN = normalize(mat3(m) * normal);
+    vTrlV = normalize(cameraPosition - wp.xyz);
+    gl_Position = projectionMatrix * viewMatrix * wp;
+}`;
+const FRAG = /* glsl */ `
+uniform vec3 uTrlColor;
+uniform float uTrlOpacity;
+uniform float uTrlBody;
+varying float vTrlA;
+varying vec3 vTrlTint;
+varying vec3 vTrlN;
+varying vec3 vTrlV;
+void main() {
+    if (vTrlA < 0.001) discard;
+    float fres = pow(1.0 - abs(dot(normalize(vTrlN), normalize(vTrlV))), 2.2);
+    float a = vTrlA * uTrlOpacity * (uTrlBody + (1.0 - uTrlBody) * fres);
+    vec3 col = uTrlColor * vTrlTint * (0.55 + 0.9 * fres);
+    gl_FragColor = vec4(col * a, a);
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>
+}`;
+const state = new WeakMap();
+const _a = { t: 0, p: new Vector3(), q: new Quaternion(), s: new Vector3() };
+const _poses = Array.from({ length: 64 }, () => new Matrix4());
+const _alphas = new Float32Array(64);
+const _rootInv = new Matrix4(), _rel = new Matrix4(), _w = new Matrix4(), _prevP = new Vector3();
+const _tints = new Float32Array(64 * 3), _tc = new Color();
+/** Colour → second colour along the copies (newest → oldest). */
+const gradient = (i, n, p, out) => out.copy(p.color).lerp(p.color2, n > 1 ? i / (n - 1) : 0);
+function ghostStyle(cfg) {
+    return {
+        build(ctx) {
+            const meshes = [];
+            ctx.target.traverse((c) => {
+                if (c.isMesh && !c.isInstancedMesh && !c.userData?.__opFxHelper && c.geometry?.attributes?.position && meshes.length < MAX_MESHES)
+                    meshes.push(c);
+            });
+            const tris = meshes.reduce((n, m) => n + (m.geometry.index ? m.geometry.index.count : m.geometry.attributes.position.count) / 3, 0);
+            // keep the copies' total triangle count sane on heavy models
+            const n = Math.max(1, Math.min(64, cfg.copies(ctx.p.amount), Math.floor(4e6 / Math.max(1, tris))));
+            const g = { list: [], n };
+            for (const m of meshes) {
+                // its own geometry object that SHARES the mesh's attributes (no copy), plus the per-copy attributes
+                const geo = new BufferGeometry();
+                for (const [name, attr] of Object.entries(m.geometry.attributes))
+                    geo.setAttribute(name, attr);
+                geo.setIndex(m.geometry.index);
+                const alpha = new InstancedBufferAttribute(new Float32Array(n), 1);
+                geo.setAttribute('aTrlAlpha', alpha);
+                const tint = new InstancedBufferAttribute(new Float32Array(n * 3), 3);
+                geo.setAttribute('aTrlTint', tint);
+                const mat = new ShaderMaterial({
+                    vertexShader: VERT, fragmentShader: FRAG,
+                    uniforms: { uTrlColor: { value: new Color(1, 1, 1) }, uTrlOpacity: { value: ctx.p.opacity }, uTrlBody: { value: cfg.body } },
+                    transparent: true, depthWrite: false, blending: AdditiveBlending, side: DoubleSide,
+                });
+                const inst = new InstancedMesh(geo, mat, n);
+                inst.frustumCulled = false;
+                inst.raycast = () => undefined;
+                inst.renderOrder = 2;
+                inst.matrixAutoUpdate = false;
+                ctx.group.add(inst);
+                g.list.push({ mesh: m, inst, alpha, tint });
+            }
+            state.set(ctx, g);
+        },
+        update(ctx) {
+            const g = state.get(ctx);
+            if (!g)
+                return;
+            const len = ctx.p.length * cfg.lengthScale;
+            _prevP.copy(ctx.hist[ctx.head].p);
+            for (let i = 0; i < g.n; i++) {
+                let a = 0;
+                if (poseAgo(ctx, len * cfg.when(i, g.n), _a)) {
+                    const gap = _a.p.distanceTo(_prevP) / ctx.span;
+                    a = ctx.env.v * cfg.alpha(i, g.n, ctx.p.amount, gap) * smooth(0.04, 0.3, awayFromNow(ctx, _a));
+                }
+                _prevP.copy(_a.p);
+                _poses[i].compose(_a.p, _a.q, _a.s);
+                _alphas[i] = a;
+            }
+            // colours are live settings: per copy, every frame (a handful of numbers)
+            for (let i = 0; i < g.n; i++) {
+                cfg.tint(i, g.n, ctx.p, _tc);
+                _tints[i * 3] = _tc.r;
+                _tints[i * 3 + 1] = _tc.g;
+                _tints[i * 3 + 2] = _tc.b;
+            }
+            _rootInv.copy(ctx.world).invert();
+            for (const c of g.list) {
+                c.tint.array.set(_tints.subarray(0, g.n * 3));
+                c.tint.needsUpdate = true;
+                c.inst.material.uniforms.uTrlOpacity.value = ctx.p.opacity;
+                c.mesh.updateWorldMatrix(true, false);
+                _rel.multiplyMatrices(_rootInv, c.mesh.matrixWorld); // the mesh inside the object, as it is now
+                for (let i = 0; i < g.n; i++) {
+                    c.inst.setMatrixAt(i, _w.multiplyMatrices(_poses[i], _rel));
+                    c.alpha.array[i] = _alphas[i];
+                }
+                c.inst.instanceMatrix.needsUpdate = true;
+                c.alpha.needsUpdate = true;
+            }
+        },
+        dispose(ctx) {
+            const g = state.get(ctx);
+            if (!g)
+                return;
+            for (const c of g.list) {
+                // the copies share the object's own attributes: drop those first, so disposing frees only ours
+                const geo = c.inst.geometry;
+                for (const name of Object.keys(geo.attributes))
+                    if (name !== 'aTrlAlpha' && name !== 'aTrlTint')
+                        geo.deleteAttribute(name);
+                geo.setIndex(null);
+                geo.dispose();
+                c.inst.material.dispose();
+                c.inst.dispose();
+            }
+            state.delete(ctx);
+        },
+    };
+}
+export const afterimage = ghostStyle({
+    copies: a => Math.round(4 + a * 20),
+    lengthScale: 1,
+    when: (i, n) => (i + 1) / n,
+    alpha: (i, n) => Math.pow(1 - i / n, 1.35),
+    tint: gradient,
+    body: 0.12,
+});
+export const longExposure = ghostStyle({
+    copies: a => Math.round(18 + a * 40),
+    lengthScale: 1.25,
+    when: (i, n) => (i + 1) / n,
+    // many faint copies that read as ONE smear: a copy's strength follows how far it is from
+    // the next one — packed tight they share the light, spread out each carries more
+    alpha: (i, n, _a, gap) => 0.34 * Math.min(1, Math.max(0.06, gap / 0.12)) * Math.pow(1 - i / n, 0.7),
+    tint: gradient,
+    body: 0.45,
+});
+export const chromaticEcho = ghostStyle({
+    copies: () => 3,
+    lengthScale: 0.5,
+    when: (i, n) => (i + 1) / n,
+    alpha: (_i, _n, a) => 0.55 + 0.45 * a,
+    // its three colours (red, green, blue by default): apart they fringe, together they add up to white
+    tint: (i, _n, p, out) => out.copy(i === 0 ? p.color : i === 1 ? p.color2 : p.color3),
+    body: 0.42,
+});

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

@@ -0,0 +1,11 @@
+export declare const smoke: import("./trailCore").TrailStyle;
+export declare const ash: import("./trailCore").TrailStyle;
+export declare const hologram: import("./trailCore").TrailStyle;
+export declare const ink: import("./trailCore").TrailStyle;
+export declare const frost: import("./trailCore").TrailStyle;
+export declare const sand: import("./trailCore").TrailStyle;
+export declare const voxel: import("./trailCore").TrailStyle;
+export declare const shatter: import("./trailCore").TrailStyle;
+export declare const wireframe: import("./trailCore").TrailStyle;
+export declare const bubbles: import("./trailCore").TrailStyle;
+//# sourceMappingURL=trailStampStyles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trailStampStyles.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/trailStampStyles.ts"],"names":[],"mappings":"AA6CA,eAAO,MAAM,KAAK,kCAgBhB,CAAC;AAIH,eAAO,MAAM,GAAG,kCAqBd,CAAC;AAIH,eAAO,MAAM,QAAQ,kCA2BnB,CAAC;AAIH,eAAO,MAAM,GAAG,kCAsBd,CAAC;AAIH,eAAO,MAAM,KAAK,kCAmBhB,CAAC;AAIH,eAAO,MAAM,IAAI,kCA8Cf,CAAC;AAIH,eAAO,MAAM,KAAK,kCAuDhB,CAAC;AAIH,eAAO,MAAM,OAAO,kCA4ElB,CAAC;AAIH,eAAO,MAAM,SAAS,kCA2CpB,CAAC;AASH,eAAO,MAAM,OAAO,kCAmDlB,CAAC"}