@3driseai/3drise-viewer 0.1.27 → 0.1.29

package/dist/operations/catalogue/trailStamps.js

@@ -0,0 +1,349 @@
+// Stamp trails — the object leaves copies of ITSELF where it was, and each copy turns
+// into something and goes away in place (smoke, ash, sand, a hologram, voxels, shards,
+// ink, frost, its wireframe). The shared machine for all of them:
+//
+//   stamps      while the object moves, a stamp is laid each time it has travelled
+//               `spacing`: its world matrix and the time. A stamp ages 0 → 1 over the
+//               style's life and is dropped at 1. Standing still lays nothing.
+//
+//   meshStamp   draws the object's OWN meshes at each stamp — instanced per mesh,
+//               sharing the mesh's attributes (no copy of the geometry). The style
+//               writes a vertex body (move wp / n by age) and a fragment body (stpOut).
+//
+//   slotStamp   draws geometry DERIVED from the object (surface grains, voxels, Voronoi
+//               shards, mesh edges) built once in the object's root space, repeated per
+//               stamp in one draw: each instance is (element × stamp slot), and the stamp
+//               matrices / ages / seeds are uniform arrays indexed by slot.
+//
+// Shader inputs common to both (prefix Stp):
+//   vertex   aStpAge, aStpSeed (per stamp), L (object-local position, in object sizes),
+//            wp (world position), n (world normal), uStpSpan, uStpTime, uStpSize,
+//            uStpAmount, uStpFloor (world y of the floor under the object)
+//   fragment age, n, v (to camera), vStpW (world), vStpL (object-local, sizes),
+//            vStpSeed, uStpC1 / C2 / C3 (the style's colours, linear), uStpOpacity;
+//            write stpOut = vec4(colour, alpha) — straight alpha for both blend modes.
+import { AdditiveBlending, BufferGeometry, Color, DoubleSide, InstancedBufferAttribute, InstancedBufferGeometry, InstancedMesh, LineSegments, Matrix4, Mesh, NormalBlending, Points, ShaderMaterial, Vector2, } from 'three';
+import { SceneStore } from '@3driseai/3drise-core';
+export const MAX_STAMPS = 24;
+const MAX_MESHES = 24;
+export const defaultTiming = (lifeScale) => ({
+    life: ctx => Math.max(0.5, ctx.p.length * lifeScale),
+    spacing: ctx => 0.34 - 0.26 * ctx.p.amount,
+});
+class Stamps {
+    list = [];
+    lastP = null;
+    update(ctx, timing) {
+        const e = ctx.world.elements;
+        const p = [e[12], e[13], e[14]];
+        const moved = this.lastP ? Math.hypot(p[0] - this.lastP[0], p[1] - this.lastP[1], p[2] - this.lastP[2]) : Infinity;
+        if (ctx.env.v > 0.01 && ctx.speed > 0.15 && moved > timing.spacing(ctx) * ctx.span) {
+            this.list.push({ m: ctx.world.clone(), t: ctx.now, seed: Math.random() });
+            if (this.list.length > MAX_STAMPS)
+                this.list.shift();
+            this.lastP = p;
+        }
+        else if (ctx.speed <= 0.15)
+            this.lastP = p; // standing still: the next move starts fresh
+        const life = timing.life(ctx);
+        while (this.list.length && ctx.now - this.list[0].t > life)
+            this.list.shift();
+    }
+    age(ctx, s, timing) { return Math.min(0.999, Math.max(0.0005, (ctx.now - s.t) / timing.life(ctx))); }
+    reset() { this.list.length = 0; this.lastP = null; }
+    alive(ctx, timing) { return this.list.length > 0 && ctx.now - this.list[this.list.length - 1].t < timing.life(ctx); }
+}
+// ---------------------------------------------------------------- GLSL
+export const STP_NOISE = /* glsl */ `
+float 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)); }
+float stpN(vec3 x) {
+    vec3 i = floor(x), f = fract(x); f = f * f * (3.0 - 2.0 * f);
+    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),
+               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);
+}
+float stpFbm(vec3 p) { return 0.55 * stpN(p) + 0.3 * stpN(p * 2.07 + 3.1) + 0.15 * stpN(p * 4.13 + 7.7); }
+vec3 stpHash3(vec3 p) {
+    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)));
+    return fract(sin(p) * 43758.5453123);
+}
+// cellular: (F1, F2, cell id)
+vec3 stpWorley(vec3 p) {
+    vec3 i = floor(p), f = fract(p);
+    float f1 = 8.0, f2 = 8.0, id = 0.0;
+    for (int z = -1; z <= 1; z++) for (int y = -1; y <= 1; y++) for (int x = -1; x <= 1; x++) {
+        vec3 g = vec3(float(x), float(y), float(z));
+        vec3 h = stpHash3(i + g);
+        vec3 r = g + h - f;
+        float d = dot(r, r);
+        if (d < f1) { f2 = f1; f1 = d; id = h.x; } else if (d < f2) f2 = d;
+    }
+    return vec3(sqrt(f1), sqrt(f2), id);
+}
+mat3 stpRot(vec3 ax, float an) {
+    float s = sin(an), c = cos(an), oc = 1.0 - c;
+    return mat3(oc*ax.x*ax.x + c, oc*ax.x*ax.y + ax.z*s, oc*ax.z*ax.x - ax.y*s,
+                oc*ax.x*ax.y - ax.z*s, oc*ax.y*ax.y + c, oc*ax.y*ax.z + ax.x*s,
+                oc*ax.z*ax.x + ax.y*s, oc*ax.y*ax.z - ax.x*s, oc*ax.z*ax.z + c);
+}`;
+const COMMON_UNIFORMS = `
+uniform float uStpSpan;
+uniform float uStpTime;
+uniform float uStpSize;
+uniform float uStpAmount;
+uniform float uStpFloor;
+uniform float uStpOpacity;
+uniform vec3 uStpC1;
+uniform vec3 uStpC2;
+uniform vec3 uStpC3;
+uniform vec2 uStpRes;
+varying float vStpAge;
+varying float vStpSeed;
+varying vec3 vStpW;
+varying vec3 vStpN;
+varying vec3 vStpV;
+varying vec3 vStpL;`;
+function fragment(pars, body, points = false) {
+    return /* glsl */ `
+${COMMON_UNIFORMS}
+${STP_NOISE}
+${pars}
+void main() {
+    float age = vStpAge;
+    if (age <= 0.0 || age >= 1.0) discard;
+    vec3 n = normalize(vStpN);
+    vec3 v = normalize(vStpV);
+    ${points ? 'vec2 pc = gl_PointCoord * 2.0 - 1.0;' : ''}
+    vec4 stpOut = vec4(0.0);
+    ${body}
+    if (stpOut.a < 0.004) discard;
+    gl_FragColor = stpOut;
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>
+}`;
+}
+function makeUniforms(ctx, extra = {}) {
+    return {
+        uStpSpan: { value: ctx.span }, uStpTime: { value: 0 }, uStpSize: { value: 0 }, uStpAmount: { value: 0 },
+        uStpFloor: { value: ctx.floor }, uStpOpacity: { value: 0 },
+        uStpC1: { value: new Color() }, uStpC2: { value: new Color() }, uStpC3: { value: new Color() },
+        uStpRes: { value: new Vector2(1280, 720) },
+        ...extra,
+    };
+}
+function syncUniforms(u, ctx, opacityScale) {
+    u.uStpTime.value = ctx.now;
+    u.uStpSize.value = ctx.p.size;
+    u.uStpAmount.value = ctx.p.amount;
+    u.uStpOpacity.value = Math.min(1.5, ctx.p.opacity * opacityScale) * ctx.env.v;
+    u.uStpC1.value.copy(ctx.p.color);
+    u.uStpC2.value.copy(ctx.p.color2);
+    u.uStpC3.value.copy(ctx.p.color3);
+    const gl = SceneStore.gl;
+    if (gl?.getDrawingBufferSize)
+        gl.getDrawingBufferSize(u.uStpRes.value);
+}
+export function meshStamp(cfg) {
+    const VERT = /* glsl */ `
+attribute float aStpAge;
+attribute float aStpSeed;
+uniform mat4 uStpRel;
+${COMMON_UNIFORMS}
+${STP_NOISE}
+${cfg.vertexPars ?? ''}
+void main() {
+    vStpAge = aStpAge; vStpSeed = aStpSeed;
+    mat4 m = modelMatrix * instanceMatrix;
+    vec3 L = (uStpRel * vec4(position, 1.0)).xyz / uStpSpan;      // object-local, in object sizes
+    vec4 wp = m * vec4(position, 1.0);
+    vec3 n = normalize(mat3(m) * normal);
+    ${cfg.vertex}
+    vStpW = wp.xyz; vStpN = n; vStpL = L; vStpV = normalize(cameraPosition - wp.xyz);
+    gl_Position = projectionMatrix * viewMatrix * wp;
+}`;
+    const FRAG = fragment(cfg.fragmentPars ?? '', cfg.fragment);
+    const state = new WeakMap();
+    const _rel = new Matrix4(), _rootInv = new Matrix4(), _w = new Matrix4();
+    return {
+        build(ctx) {
+            const meshes = [];
+            ctx.target.traverse((c) => {
+                if (c.isMesh && !c.isInstancedMesh && !c.userData?.__opFxHelper && c.geometry?.attributes?.position && c.geometry.attributes.normal && meshes.length < MAX_MESHES)
+                    meshes.push(c);
+            });
+            const parts = [];
+            for (const m of meshes) {
+                const geo = new BufferGeometry();
+                for (const [name, attr] of Object.entries(m.geometry.attributes))
+                    geo.setAttribute(name, attr);
+                geo.setIndex(m.geometry.index);
+                const age = new InstancedBufferAttribute(new Float32Array(MAX_STAMPS), 1);
+                const seed = new InstancedBufferAttribute(new Float32Array(MAX_STAMPS), 1);
+                geo.setAttribute('aStpAge', age);
+                geo.setAttribute('aStpSeed', seed);
+                const mat = new ShaderMaterial({
+                    vertexShader: VERT, fragmentShader: FRAG,
+                    uniforms: makeUniforms(ctx, { uStpRel: { value: new Matrix4() } }),
+                    transparent: true, depthWrite: false, side: DoubleSide,
+                    blending: cfg.additive ? AdditiveBlending : NormalBlending,
+                });
+                const inst = new InstancedMesh(geo, mat, MAX_STAMPS);
+                inst.count = 0;
+                inst.frustumCulled = false;
+                inst.raycast = () => undefined;
+                inst.renderOrder = 1;
+                inst.matrixAutoUpdate = false;
+                ctx.group.add(inst);
+                parts.push({ mesh: m, inst, age, seed, mat });
+            }
+            const stamps = new Stamps();
+            state.set(ctx, { parts, stamps });
+            ctx.onReset = () => stamps.reset();
+        },
+        update(ctx) {
+            const st = state.get(ctx);
+            if (!st)
+                return;
+            st.stamps.update(ctx, cfg);
+            const list = st.stamps.list, n = list.length;
+            _rootInv.copy(ctx.world).invert();
+            for (const c of st.parts) {
+                const u = c.mat.uniforms;
+                syncUniforms(u, ctx, cfg.opacity ?? 1);
+                c.mesh.updateWorldMatrix(true, false);
+                _rel.multiplyMatrices(_rootInv, c.mesh.matrixWorld); // the mesh inside the object, as it is now
+                u.uStpRel.value.copy(_rel);
+                for (let i = 0; i < n; i++) {
+                    c.inst.setMatrixAt(i, _w.multiplyMatrices(list[i].m, _rel));
+                    c.age.array[i] = st.stamps.age(ctx, list[i], cfg);
+                    c.seed.array[i] = list[i].seed;
+                }
+                c.inst.count = n;
+                c.inst.instanceMatrix.needsUpdate = true;
+                c.age.needsUpdate = true;
+                c.seed.needsUpdate = true;
+            }
+        },
+        alive(ctx) { const st = state.get(ctx); return !!st && st.stamps.alive(ctx, cfg); },
+        dispose(ctx) {
+            const st = state.get(ctx);
+            if (!st)
+                return;
+            for (const c of st.parts) {
+                // the stamps 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 !== 'aStpAge' && name !== 'aStpSeed')
+                        geo.deleteAttribute(name);
+                geo.setIndex(null);
+                geo.dispose();
+                c.mat.dispose();
+                c.inst.dispose();
+            }
+            state.delete(ctx);
+        },
+    };
+}
+export function slotStamp(cfg) {
+    const points = cfg.kind === 'points';
+    const VERT = /* glsl */ `
+attribute float aStpSlot;
+uniform mat4 uStpMat[${MAX_STAMPS}];
+uniform float uStpAgeA[${MAX_STAMPS}];
+uniform float uStpSeedA[${MAX_STAMPS}];
+uniform float uStpPx;
+${COMMON_UNIFORMS}
+${STP_NOISE}
+${cfg.vertexPars ?? ''}
+void main() {
+    int s = int(aStpSlot + 0.5);
+    float age = uStpAgeA[s];
+    float seed = uStpSeedA[s];
+    vStpAge = age; vStpSeed = seed;
+    vec3 lp = position;
+    ${cfg.kind === 'lines' ? 'vec3 ln = vec3(0.0, 1.0, 0.0);' : 'vec3 ln = normal;'}
+    vec3 L = position / uStpSpan;
+    float stpSize = uStpPx;
+    ${cfg.vertexLocal ?? ''}
+    mat4 m = uStpMat[s];
+    vec4 wp = m * vec4(lp, 1.0);
+    vec3 n = normalize(mat3(m) * ln);
+    ${cfg.vertexWorld ?? ''}
+    vStpW = wp.xyz; vStpN = n; vStpL = L; vStpV = normalize(cameraPosition - wp.xyz);
+    gl_Position = projectionMatrix * viewMatrix * wp;
+    if (age <= 0.0 || age >= 1.0) gl_Position = vec4(2.0, 2.0, 2.0, 1.0);   // an unused slot: off screen
+    ${points ? 'gl_PointSize = stpSize;' : ''}
+}`;
+    const FRAG = fragment(cfg.fragmentPars ?? '', cfg.fragment, points);
+    const state = new WeakMap();
+    return {
+        build(ctx) {
+            const d = cfg.derive(ctx);
+            const geo = new InstancedBufferGeometry();
+            for (const [name, attr] of Object.entries(d.geometry.attributes))
+                geo.setAttribute(name, attr);
+            if (d.geometry.index)
+                geo.setIndex(d.geometry.index);
+            const per = d.elements?.count ?? 1;
+            const total = per * MAX_STAMPS;
+            const slot = new Float32Array(total);
+            for (let s = 0; s < MAX_STAMPS; s++)
+                slot.fill(s, s * per, (s + 1) * per);
+            geo.setAttribute('aStpSlot', new InstancedBufferAttribute(slot, 1));
+            for (const [name, a] of Object.entries(d.elements?.attrs ?? {})) {
+                const arr = new Float32Array(total * a.itemSize);
+                for (let s = 0; s < MAX_STAMPS; s++)
+                    arr.set(a.array, s * per * a.itemSize);
+                geo.setAttribute(name, new InstancedBufferAttribute(arr, a.itemSize));
+            }
+            geo.instanceCount = total;
+            const mat = new ShaderMaterial({
+                vertexShader: VERT, fragmentShader: FRAG,
+                uniforms: makeUniforms(ctx, {
+                    uStpMat: { value: Array.from({ length: MAX_STAMPS }, () => new Matrix4()) },
+                    uStpAgeA: { value: new Array(MAX_STAMPS).fill(0) },
+                    uStpSeedA: { value: new Array(MAX_STAMPS).fill(0) },
+                    uStpPx: { value: 2 },
+                }),
+                transparent: true, depthWrite: false, side: DoubleSide,
+                blending: cfg.additive ? AdditiveBlending : NormalBlending,
+            });
+            const obj = points ? new Points(geo, mat) : cfg.kind === 'lines' ? new LineSegments(geo, mat) : new Mesh(geo, mat);
+            obj.frustumCulled = false;
+            obj.raycast = () => undefined;
+            obj.renderOrder = 1;
+            obj.matrixAutoUpdate = false;
+            ctx.group.add(obj);
+            const stamps = new Stamps();
+            state.set(ctx, { obj, mat, stamps });
+            ctx.onReset = () => stamps.reset();
+            d.geometry.dispose?.();
+        },
+        update(ctx) {
+            const st = state.get(ctx);
+            if (!st)
+                return;
+            st.stamps.update(ctx, cfg);
+            const u = st.mat.uniforms;
+            syncUniforms(u, ctx, cfg.opacity ?? 1);
+            const gl = SceneStore.gl;
+            u.uStpPx.value = (1.6 + ctx.p.size * 3.2) * (gl?.getPixelRatio?.() || 1);
+            const list = st.stamps.list;
+            for (let s = 0; s < MAX_STAMPS; s++) {
+                const stamp = list[s];
+                u.uStpAgeA.value[s] = stamp ? st.stamps.age(ctx, stamp, cfg) : 0;
+                u.uStpSeedA.value[s] = stamp ? stamp.seed : 0;
+                if (stamp)
+                    u.uStpMat.value[s].copy(stamp.m);
+            }
+        },
+        alive(ctx) { const st = state.get(ctx); return !!st && st.stamps.alive(ctx, cfg); },
+        dispose(ctx) {
+            const st = state.get(ctx);
+            if (!st)
+                return;
+            st.obj.geometry.dispose();
+            st.mat.dispose();
+            state.delete(ctx);
+        },
+    };
+}

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

@@ -0,0 +1,3 @@
+import { type TrailStyle } from './trailCore';
+export declare const streaks: TrailStyle;
+//# sourceMappingURL=trailStreaks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trailStreaks.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/trailStreaks.ts"],"names":[],"mappings":"AAOA,OAAO,EAAsE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AA0ClH,eAAO,MAAM,OAAO,EAAE,UA6ErB,CAAC"}

package/dist/operations/catalogue/trailStreaks.js

@@ -0,0 +1,147 @@
+// Streaks — thin camera-facing light ribbons pulled from points spread over the
+// object's surface (farthest-point picks), each point carried back through the
+// object's recent poses. They taper and fade along their length; a segment that
+// does not move draws nothing. Ribbon edges are anti-aliased in the shader; colour
+// runs from Colour at the head to Tail colour.
+// Length × 1 (seconds of history); amount = how many ribbons; size = width.
+import { AdditiveBlending, BufferAttribute, BufferGeometry, Color, DoubleSide, Matrix4, Mesh, Quaternion, ShaderMaterial, Vector3 } from 'three';
+import { GLSL_AA, poseAgo, smooth, spreadPoints } from './trailCore.js';
+const PTS = 40;
+const VERT = /* glsl */ `
+attribute float aTrlAlpha;
+attribute float aTrlSide;
+attribute float aTrlT;
+varying float vTrlA;
+varying float vTrlS;
+varying float vTrlT;
+void main() {
+    vTrlA = aTrlAlpha;
+    vTrlS = aTrlSide;
+    vTrlT = aTrlT;
+    gl_Position = projectionMatrix * viewMatrix * vec4(position, 1.0);
+}`;
+const FRAG = /* glsl */ `
+uniform vec3 uTrlColor;
+uniform vec3 uTrlColor2;
+uniform float uTrlOpacity;
+varying float vTrlA;
+varying float vTrlS;
+varying float vTrlT;
+${GLSL_AA}
+void main() {
+    // a crisp ribbon: a bright core and an anti-aliased edge (no blur)
+    float edge = trlAA(abs(vTrlS) - 0.82);
+    float core = 1.0 - smoothstep(0.0, 0.7, abs(vTrlS));
+    float a = vTrlA * uTrlOpacity * edge * (0.55 + 0.45 * core);
+    if (a < 0.002) discard;
+    vec3 col = mix(uTrlColor, uTrlColor2, vTrlT);            // colour at the head → tail colour
+    gl_FragColor = vec4(col * (0.8 + 0.7 * core) * 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 _w = new Matrix4(), _prev = new Vector3(), _next = new Vector3(), _dir = new Vector3(), _side = new Vector3(), _view = new Vector3();
+export const streaks = {
+    build(ctx) {
+        const anchors = spreadPoints(ctx.target, Math.round(4 + ctx.p.amount * 14));
+        const K = anchors.length, M = PTS;
+        const geo = new BufferGeometry();
+        const pos = new BufferAttribute(new Float32Array(K * M * 2 * 3), 3);
+        const alpha = new BufferAttribute(new Float32Array(K * M * 2), 1);
+        const side = new BufferAttribute(new Float32Array(K * M * 2), 1);
+        const tAt = new BufferAttribute(new Float32Array(K * M * 2), 1);
+        for (let i = 0; i < K * M; i++) {
+            side.array[i * 2] = -1;
+            side.array[i * 2 + 1] = 1;
+            tAt.array[i * 2] = tAt.array[i * 2 + 1] = (i % M) / (M - 1);
+        }
+        const idx = [];
+        for (let k = 0; k < K; k++)
+            for (let j = 0; j < M - 1; j++) {
+                const a = (k * M + j) * 2;
+                idx.push(a, a + 1, a + 2, a + 1, a + 3, a + 2);
+            }
+        geo.setIndex(idx);
+        geo.setAttribute('position', pos);
+        geo.setAttribute('aTrlAlpha', alpha);
+        geo.setAttribute('aTrlSide', side);
+        geo.setAttribute('aTrlT', tAt);
+        pos.setUsage(35048);
+        alpha.setUsage(35048);
+        const mesh = new Mesh(geo, new ShaderMaterial({
+            vertexShader: VERT, fragmentShader: FRAG,
+            uniforms: { uTrlColor: { value: new Color() }, uTrlColor2: { value: new Color() }, uTrlOpacity: { value: ctx.p.opacity } },
+            transparent: true, depthWrite: false, blending: AdditiveBlending, side: DoubleSide,
+        }));
+        mesh.frustumCulled = false;
+        mesh.raycast = () => undefined;
+        mesh.renderOrder = 2;
+        ctx.group.add(mesh);
+        state.set(ctx, {
+            mesh, pos, alpha, anchors,
+            pts: Array.from({ length: K }, () => Array.from({ length: M }, () => new Vector3())),
+            ok: new Array(M).fill(false),
+        });
+    },
+    update(ctx) {
+        const st = state.get(ctx);
+        if (!st)
+            return;
+        const u = st.mesh.material.uniforms;
+        u.uTrlOpacity.value = ctx.p.opacity * 1.6;
+        u.uTrlColor.value.copy(ctx.p.color);
+        u.uTrlColor2.value.copy(ctx.p.color2);
+        const K = st.anchors.length, M = PTS;
+        const len = ctx.p.length;
+        const width = (0.006 + ctx.p.size * 0.05) * ctx.span;
+        const P = st.pos.array, A = st.alpha.array;
+        for (let j = 0; j < M; j++) {
+            st.ok[j] = poseAgo(ctx, (len * j) / (M - 1), _a);
+            _w.compose(_a.p, _a.q, _a.s);
+            for (let k = 0; k < K; k++)
+                st.pts[k][j].copy(st.anchors[k]).applyMatrix4(_w);
+        }
+        for (let k = 0; k < K; k++) {
+            for (let j = 0; j < M; j++) {
+                const cur = st.pts[k][j];
+                _prev.copy(st.pts[k][Math.max(0, j - 1)]);
+                _next.copy(st.pts[k][Math.min(M - 1, j + 1)]);
+                _dir.subVectors(_prev, _next);
+                const seg = _dir.length();
+                if (ctx.cam)
+                    _view.subVectors(ctx.cam, cur).normalize();
+                else
+                    _view.set(0, 0, 1);
+                _side.crossVectors(_dir, _view);
+                if (_side.lengthSq() < 1e-12)
+                    _side.set(0, 1, 0);
+                else
+                    _side.normalize();
+                const t = j / (M - 1);
+                const w = width * (1 - 0.8 * t);
+                const i = (k * M + j) * 2;
+                P[i * 3] = cur.x - _side.x * w;
+                P[i * 3 + 1] = cur.y - _side.y * w;
+                P[i * 3 + 2] = cur.z - _side.z * w;
+                P[i * 3 + 3] = cur.x + _side.x * w;
+                P[i * 3 + 4] = cur.y + _side.y * w;
+                P[i * 3 + 5] = cur.z + _side.z * w;
+                const moving = smooth(0.002, 0.03, (seg * (M - 1)) / (2 * ctx.span));
+                const a = st.ok[j] ? ctx.env.v * Math.pow(1 - t, 1.6) * moving : 0;
+                A[i] = a;
+                A[i + 1] = a;
+            }
+        }
+        st.pos.needsUpdate = true;
+        st.alpha.needsUpdate = true;
+    },
+    dispose(ctx) {
+        const st = state.get(ctx);
+        if (!st)
+            return;
+        st.mesh.geometry.dispose();
+        st.mesh.material.dispose();
+        state.delete(ctx);
+    },
+};

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

@@ -50,6 +50,26 @@ export interface FieldState {
     sweep: {
         value: Vector3;
     };
+    /**
+     * 1 = the object is drawn only where the effect has painted it (`__reveal`: the effect
+     * follows the object's visibility — see `presence` in types.ts). Each effect's own
+     * shader decides what "painted" means.
+     */
+    reveal: {
+        value: number;
+    };
+    /**
+     * Direct handover: 0..1, the progress of the look that is replacing this one. Where its
+     * front has passed (a little behind it, `clearEdge`), this look is gone — see goneGlsl.
+     * The controller copies the incoming look's direction / scale / sweep into this state
+     * while it wipes, so the two fronts are the same front.
+     */
+    clear: {
+        value: number;
+    };
+    clearEdge: {
+        value: number;
+    };
 }
 /** Bounds of `root` in its own (root-local) space. */
 export declare function localBounds(root: Object3D): Box3;
@@ -68,6 +88,8 @@ export declare function screenRight(root: Object3D, ctx?: {
  * left → right / right → left directions can be taken from the screen at trigger.
  */
 export declare function setFieldParams(st: FieldState, p: Record<string, unknown>, root?: Object3D, ctx?: any): void;
+/** `__reveal` on: only what the effect has painted is drawn. Set on every apply and revert. */
+export declare const setReveal: (st: FieldState, p: Record<string, unknown>) => void;
 export declare const syncRoot: (root: Object3D, st: FieldState) => void;
 /** The field's uniforms under a prefix: `u<P>Progress`, `u<P>RootInv`, … */
 export declare function fieldUniforms(P: string, st: FieldState): Record<string, {
@@ -81,6 +103,14 @@ export declare function fieldUniforms(P: string, st: FieldState): Record<string,
  * Calm, low-frequency fBm — stretched so the front moves evenly over the whole run.
  */
 export declare const fieldGlsl: (P: string) => string;
+/**
+ * GLSL for take-overs that can be wiped (after fieldGlsl):
+ *   <P>Gone(vec3 q) → 1 where the look that replaces this one has fully arrived
+ * The wipe front is the incoming look's own front (same field, its progress in u<P>Clear),
+ * trailing by the incoming edge width — so the old look goes exactly where the new one is
+ * complete, and the object underneath never shows.
+ */
+export declare const goneGlsl: (P: string) => string;
 /** Whether a field state is holding (tests / debugging). */
 export declare const isHolding: (st: FieldState) => boolean;
 /**

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

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

package/dist/operations/catalogue/transitionField.js

@@ -61,6 +61,7 @@ export function createFieldState(root) {
         boundsMin: { value: b.min.clone() }, boundsSize: { value: size }, extent: { value: Math.max(size.length(), 1e-3) },
         scale: { value: 3 }, direction: { value: 0 }, edgeWidth: { value: 0.08 }, edgeColor: { value: new Color('#ff7a2e') },
         sweep: { value: new Vector3(1, 0, 0) },
+        reveal: { value: 0 }, clear: { value: 0 }, clearEdge: { value: 0.05 },
     };
 }
 /** The camera's screen-right, in `root`'s local space (world X when there is no camera). */
@@ -82,6 +83,8 @@ export function screenRight(root, ctx) {
  * left → right / right → left directions can be taken from the screen at trigger.
  */
 export function setFieldParams(st, p, root, ctx) {
+    setReveal(st, p);
+    st.clear.value = 0; // applied again: whatever was wiping it is over
     if (p.direction !== undefined) {
         const d = String(p.direction);
         st.direction.value = Math.max(0, DIRECTIONS.indexOf(d));
@@ -97,6 +100,8 @@ export function setFieldParams(st, p, root, ctx) {
     if (p.edgeColor !== undefined)
         st.edgeColor.value.set(String(p.edgeColor));
 }
+/** `__reveal` on: only what the effect has painted is drawn. Set on every apply and revert. */
+export const setReveal = (st, p) => { st.reveal.value = p.__reveal === true ? 1 : 0; };
 export const syncRoot = (root, st) => {
     root.updateWorldMatrix(true, false);
     st.rootInv.value.copy(root.matrixWorld).invert();
@@ -108,6 +113,7 @@ export function fieldUniforms(P, st) {
         [`u${P}Min`]: st.boundsMin, [`u${P}Size`]: st.boundsSize, [`u${P}Extent`]: st.extent,
         [`u${P}Scale`]: st.scale, [`u${P}Direction`]: st.direction,
         [`u${P}EdgeWidth`]: st.edgeWidth, [`u${P}EdgeColor`]: st.edgeColor, [`u${P}Sweep`]: st.sweep,
+        [`u${P}Reveal`]: st.reveal, [`u${P}Clear`]: st.clear, [`u${P}ClearEdge`]: st.clearEdge,
     };
 }
 /**
@@ -138,6 +144,20 @@ float ${P}Threshold() { return clamp(u${P}Progress, 0.0, 1.0) * (1.0 + 2.0 * u${
 // progress at which the front reaches field value f (inverse of Threshold)
 float ${P}BirthOf(float f) { return (f + u${P}EdgeWidth) / (1.0 + 2.0 * u${P}EdgeWidth); }
 `;
+/**
+ * GLSL for take-overs that can be wiped (after fieldGlsl):
+ *   <P>Gone(vec3 q) → 1 where the look that replaces this one has fully arrived
+ * The wipe front is the incoming look's own front (same field, its progress in u<P>Clear),
+ * trailing by the incoming edge width — so the old look goes exactly where the new one is
+ * complete, and the object underneath never shows.
+ */
+export const goneGlsl = (P) => /* glsl */ `
+float ${P}Gone(vec3 q) {
+  if (u${P}Clear <= 0.0) return 0.0;
+  float t = clamp(u${P}Clear, 0.0, 1.0) * (1.0 + 2.0 * u${P}ClearEdge) - u${P}ClearEdge;
+  return step(u${P}ClearEdge, t - ${P}Field(q));
+}
+`;
 // ---------------------------------------------------------------- hold clock
 /** Field states holding their finished state → their root. One ticker drives them all. */
 const holds = new Map();
@@ -238,6 +258,7 @@ export function surfaceLayer(P, st, edge = 'ember') {
         v${P}Q = ${P}Norm((u${P}RootInv * modelMatrix * vec4(transformed, 1.0)).xyz);`,
         fragment: /* glsl */ `
         {
+          if (u${P}Reveal > 0.5) discard;                    // revealed by its particles alone
           float ${P}D = ${P}Field(v${P}Q) - ${P}Threshold();
           if (${P}D < 0.0) discard;
           float ${P}E = 1.0 - smoothstep(0.0, u${P}EdgeWidth, ${P}D);

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

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

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

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