@3driseai/3drise-viewer 0.1.28 → 0.1.30

package/dist/operations/catalogue/teleport.js

@@ -5,10 +5,13 @@
 // column of light: a soft core that is brightest face-on, fine streaks flowing
 // upward, and thin rings of light climbing it. Reverting materialises the
 // object back down the beam.
+// With Disappear off (an object effect's default) the object stays "charged": hot
+// white at the top fading to its own colour below, the beam standing over it with
+// particles cycling up it, nothing leaving.
 import { AdditiveBlending, Color, CylinderGeometry, Mesh, ShaderMaterial } from 'three';
 import { defineOperation } from '../types.js';
 import { GLSL_ROT, addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
-import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, hideMeshes, runProgress, setFieldParams, } from './transitionField.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, hideMeshes, runProgress, setFieldParams, setReveal, } from './transitionField.js';
 import { sampleSurfaceCached } from './surfaceSample.js';
 import { GLSL_POINT_SIZE, createFxPoints, disposeFxPoints } from './fxPoints.js';
 import { hideUntilWarm } from './warmup.js';
@@ -21,14 +24,14 @@ const END = 1 + LIFE * 1.6;
 const SING = `(u${P}Min + u${P}Size * vec3(0.5, 1.0, 0.5) + vec3(0.0, 0.18 * u${P}Extent, 0.0))`;
 function surface(st) {
     return {
-        uniforms: { ...fieldUniforms(P, st.field), uTelLife: st.life, uTelGlow: st.glow },
+        uniforms: { ...fieldUniforms(P, st.field), uTelLife: st.life, uTelGlow: st.glow, uTelKeep: st.keep },
         common: `varying float vTelK;\nvarying vec3 vTelQ;\n${fieldGlsl(P)}\n${GLSL_ROT}`,
         vertex: /* glsl */ `
         {
           mat4 toRoot = uTelRootInv * modelMatrix;
           vec3 rl = (toRoot * vec4(transformed, 1.0)).xyz;
           float birth = TelBirthOf(TelField(TelNorm(rl)));
-          float k = clamp((uTelProgress - birth) / uTelLife, 0.0, 1.0);
+          float k = clamp((uTelProgress - birth) / uTelLife, 0.0, 1.0) * (1.0 - uTelKeep);
           k = k * k * (3.0 - 2.0 * k);
           vTelK = k;
           vTelQ = TelNorm(rl);
@@ -41,10 +44,21 @@ function surface(st) {
         }`,
         fragment: /* glsl */ `
         {
-          float cut = 0.1 + 0.35 * fxFbm(vTelQ * 7.0);
-          if (vTelK > cut) discard;
-          float h = smoothstep(0.0, cut, vTelK);
-          outgoingLight = mix(outgoingLight, uTelGlow * (1.5 + 3.5 * h), h);
+          if (uTelKeep > 0.5) {
+            // charged: heat climbs the object — white-hot at the top, its own colour below — and flickers
+            float TelD = TelField(vTelQ) - TelThreshold();
+            float charged = smoothstep(0.0, uTelEdgeWidth, -TelD);
+            // painting the object in: nothing ahead of the front, fully charged right behind it
+            if (uTelReveal > 0.5) { if (TelD > 0.0) discard; charged = 1.0; }
+            float heat = pow(clamp(vTelQ.y, 0.0, 1.0), 2.6) * (0.85 + 0.15 * sin(uTelTime * 5.0 + fxFbm(vTelQ * 6.0 + uTelTime * 0.4) * 12.0));
+            vec3 hot = mix(uTelGlow * 0.9, vec3(2.0), heat) * (0.5 + 1.5 * heat);
+            outgoingLight = mix(outgoingLight, hot, charged * (0.12 + 0.88 * heat));
+          } else {
+            float cut = 0.1 + 0.35 * fxFbm(vTelQ * 7.0);
+            if (vTelK > cut) discard;
+            float h = smoothstep(0.0, cut, vTelK);
+            outgoingLight = mix(outgoingLight, uTelGlow * (1.5 + 3.5 * h), h);
+          }
         }`,
     };
 }
@@ -114,13 +128,16 @@ function updateColumn(s) {
 export default defineOperation({
     value: 'teleport',
     label: 'Teleport',
-    description: 'Draw the targets into a point of light and send them up a beam — reverting brings them back down',
+    description: 'Draw the targets into a point of light and send them up a beam (or, Disappear off, keep them charged under the beam) — reverting brings them back down',
     channel: 'visual',
     multi: true,
     toggles: true,
-    usableIn: ['interaction', 'action'],
+    usableIn: ['interaction', 'action', 'object'],
+    objectParams: { disappear: false },
+    presence: 'paint',
     params: {
         direction: { type: 'select', label: 'Direction', default: 'down', options: DIRECTION_OPTIONS },
+        disappear: { type: 'boolean', label: 'Disappear', default: true, hint: 'Off: the object stays charged under the beam' },
         color: { type: 'color', label: 'Light', default: '#a8ecff' },
         sparks: { type: 'number', label: 'Particles', default: 9000, min: 1000, max: 60000, step: 1000 },
         beam: { type: 'number', label: 'Beam height', default: 3, min: 0.5, max: 10, step: 0.1, unit: '×' },
@@ -133,15 +150,17 @@ export default defineOperation({
         if (!st) {
             const field = createFieldState(target);
             field.edgeWidth.value = 0.1;
-            const own = { field, life: { value: LIFE }, glow: { value: new Color() }, beam: { value: 3 }, width: { value: 1 }, mats: new Set() };
+            const own = { field, life: { value: LIFE }, glow: { value: new Color() }, beam: { value: 3 }, width: { value: 1 }, keep: { value: 0 }, mats: new Set() };
             const sample = sampleSurfaceCached(target, Math.round(Number(p.sparks)), 23);
             own.points = createFxPoints(target, sample, {
                 additive: true,
-                uniforms: { ...fieldUniforms(P, field), uTelLife: own.life, uTelGlow: own.glow, uTelBeam: own.beam, uTelWidth: own.width },
+                uniforms: { ...fieldUniforms(P, field), uTelLife: own.life, uTelGlow: own.glow, uTelBeam: own.beam, uTelWidth: own.width, uTelKeep: own.keep },
                 vertexPars: fieldGlsl(P) + GLSL_POINT_SIZE + GLSL_ROT,
                 vertexMain: /* glsl */ `
                   float birth = TelBirthOf(TelField(TelNorm(aP)));
                   float a = (uTelProgress - birth) / (uTelLife * 1.6);
+                  // keep: once charged, a particle cycles up the beam over and over
+                  if (uTelKeep > 0.5) a = uTelProgress > birth ? 0.5 + 0.5 * fract(u${P}Time * 0.2 + aR.w) : 0.0;
                   if (a <= 0.0 || a >= 1.0) { gl_Position = vec4(2.0, 2.0, 2.0, 1.0); gl_PointSize = 0.0; vColor = vec3(0.0); vAlpha = 0.0; return; }
                   float E = uTelExtent;
                   vec3 S = ${SING};
@@ -184,7 +203,17 @@ export default defineOperation({
         s.beam.value = Number(p.beam);
         s.width.value = Number(p.width);
         s.points.visible = true;
+        s.keep.value = p.disappear === false ? 1 : 0;
+        hideMeshes(target, KEY, false);
         updateColumn(s);
+        if (s.keep.value) {
+            // keep: the charge climbs the object (0 → 1), the beam stands, and it holds
+            return runProgress(target, s.field, 1, {
+                duration: Number(p.duration) / END, ease: 'none', hold: true,
+                onUpdate: () => updateColumn(s),
+                onComplete: () => updateColumn(s),
+            });
+        }
         return runProgress(target, s.field, END, {
             duration: Number(p.duration), ease: 'power1.in',
             onUpdate: () => updateColumn(s),
@@ -196,9 +225,11 @@ export default defineOperation({
         if (!s)
             return;
         hideMeshes(target, KEY, false);
+        setReveal(s.field, p);
         s.points.visible = true;
+        // from a hold it only has part of the way to go: keep the same speed
         return runProgress(target, s.field, 0, {
-            duration: Number(p.duration), ease: 'power1.out',
+            duration: Number(p.duration) * Math.min(1, Math.max(0.1, s.field.progress.value / END)), ease: s.keep.value ? 'none' : 'power1.out',
             onUpdate: () => updateColumn(s),
             onComplete: () => {
                 s.mats.forEach(m => removeLayer(m, 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"}