@3driseai/3drise-viewer 0.1.27 → 0.1.29

package/dist/components/text/engine/looks/lightPainting.js

@@ -0,0 +1,567 @@
+import * as THREE from 'three';
+import { buildCapsules, setReveal, REVEAL_UNIFORMS, uniformsBase, frag } from '../ribbon.js';
+import { prepare, applyAnim, extentOf, DRAW_METHODS, ERASE_METHODS } from '../methods.js';
+// =========================================================================================
+// lightPainting - a long-exposure photograph of someone writing in the dark with a small light.
+//
+// THE MATHS
+//  * The pen tip is a moving point source. A camera shutter that stays open integrates its light: the exposure a trail
+//    point receives is  H = L * dwell  with  dwell = ds / speed  (time the tip spent over that bit of path), so
+//    brightness ~ 1/speed. Speed comes from the same 2/3 power-law pen timing the pen draw method uses (slow in tight
+//    curves) and is further slowed at stroke starts / ends (the hand dwells there), so those become bright blobs.
+//    The CPU rewrites the pen clock from that speed (s.pt / s.ptime), so what you see the tip do and what the trail
+//    recorded are the same quantity: exposure e = (1/speed) / median(1/speed).
+//  * Film does not add linearly forever: it saturates per channel  out_c = peak * (1 - exp(-K * H * tint_c)).
+//    Heavy exposure therefore clips towards WHITE in the core while the thin halo keeps its hue - the typical
+//    blown-out centre / coloured fringe of light painting - with no hand-made colour tricks. peak < 1 keeps every
+//    sustained pixel below 1.0; only the tip bloom may exceed it.
+//  * Colour from temperature: tint = ramp(colour2 -> colour, h) * blackbody(Tk) / blackbody(6500K), with the source
+//    temperature Tk = T * (1 + 0.85 h) and  h = exp(-age/tau)  (age = seconds since the tip passed). A fresh trail
+//    is hot (near white), then cools to the resting colour of the 'photo'. Brightness decays gently with the same age
+//    and settles on a held level.
+//  * Sparkler: closed-form ballistic sparks. Spark i of slot s is born at progress g_e = (e + jitter)/R at the pen
+//    position P(g_e) (a CPU path lookup built from the strokes' schedule seg / t, baked into a float texture, one row
+//    per concurrently active pen), and then  p(a) = o + (v0 - vinf)(1 - e^(-k a))/k + vinf a  (linear drag k, gravity
+//    giving terminal velocity vinf), a = age. Drawn as a short additive streak along v(a), cooling white -> orange ->
+//    red by blackbody. No state: everything is a function of (head progress, seconds since).
+// =========================================================================================
+const hex = (h) => new THREE.Color(h);
+const clamp = (x, a, b) => Math.max(a, Math.min(b, x));
+const MAX_ROWS = 10, TIP_BINS = 4096, MAX_SPARKS = 2000;
+// ---- exposure: rewrite pen timing with dwell at stroke ends, derive e = 1/speed -----------------
+function shapeExposure(strokes) {
+    const all = [];
+    for (const s of strokes) {
+        const n = s.pts.length / 2;
+        const sp = new Float32Array(n);
+        const vv = new Float32Array(n);
+        const P = s.ptime || 1;
+        for (let i = 0; i < n - 1; i++) {
+            const dt = Math.max(1e-7, (s.pt[i + 1] - s.pt[i]) * P);
+            sp[i] = (s.cum[i + 1] - s.cum[i]) / dt;
+        }
+        for (let i = 0; i < n; i++)
+            vv[i] = n > 1 ? 0.5 * (sp[Math.max(0, i - 1)] + sp[Math.min(n - 2, i)]) : 1;
+        let vmean = 0;
+        for (let i = 0; i < n; i++)
+            vmean += vv[i];
+        vmean = vmean / n || 1;
+        const t = new Float32Array(n);
+        const e = new Float32Array(n);
+        for (let i = 0; i < n; i++) {
+            const x = Math.min(s.cum[i], s.len - s.cum[i]) / 0.05;
+            const q = clamp(x, 0, 1);
+            const k = 0.4 + 0.6 * q * q * (3 - 2 * q); // hand dwells at stroke ends
+            vv[i] = Math.max(1e-4, (vv[i] / vmean) * k);
+        }
+        for (let i = 1; i < n; i++)
+            t[i] = t[i - 1] + (s.cum[i] - s.cum[i - 1]) / Math.max(1e-6, 0.5 * (vv[i] + vv[i - 1]));
+        const T = Math.max(1e-6, t[n - 1]);
+        for (let i = 0; i < n; i++) {
+            s.pt[i] = t[i] / T;
+            e[i] = 1 / vv[i];
+        }
+        s.pt = Float32Array.from(s.pt);
+        s.ptime = T;
+        s._e = e;
+        for (let i = 0; i < n; i++)
+            all.push(e[i]);
+    }
+    all.sort((a, b) => a - b);
+    const med = all[Math.floor(all.length / 2)] || 1;
+    for (const s of strokes) {
+        const n = s._e.length;
+        let a = s._e;
+        for (let i = 0; i < n; i++)
+            a[i] = clamp(Math.pow(a[i] / med, 2.0), 0.25, 2.8);
+        for (let pass = 0; pass < 2; pass++) {
+            const q = new Float32Array(n);
+            for (let i = 0; i < n; i++) {
+                let m = 0, c = 0;
+                for (let j = Math.max(0, i - 3); j <= Math.min(n - 1, i + 3); j++) {
+                    m += a[j];
+                    c++;
+                }
+                q[i] = m / c;
+            }
+            a = q;
+        }
+        s.pressure = a;
+        delete s._e;
+    }
+    // total pen time is rescaled so the sum of all strokes keeps the schedule proportions (pen method uses s.ptime)
+}
+// ---- pen clock (same proportions as the 'pen' draw method, independent of the chosen method) ------
+// gives every point a time in seconds (tsec, for tremor) and a strobe phase in pulse cycles (cyc)
+function penClock(strokes, dur) {
+    const avg = strokes.reduce((a, s) => a + s.ptime, 0) / Math.max(1, strokes.length), gap = 0.2 * avg;
+    const total = strokes.reduce((a, s) => a + s.ptime + gap, 0) || 1;
+    const len = strokes.reduce((a, s) => a + s.len, 0);
+    const ksec = Math.max(0.5, dur) / total, kcyc = (len / 0.06) / total;
+    let c = 0;
+    for (const s of strokes) {
+        const n = s.pts.length / 2;
+        s.tsec = new Float32Array(n);
+        s.cyc = new Float32Array(n);
+        for (let i = 0; i < n; i++) {
+            const tp = c + s.pt[i] * s.ptime;
+            s.tsec[i] = tp * ksec;
+            s.cyc[i] = tp * kcyc;
+        }
+        c += s.ptime + gap;
+    }
+}
+// physiological hand tremor: band-limited (8-12 Hz) noise in pen time, smaller where the pen is slow. Local deviation of the
+// trail path only (baked, deterministic) - never a transform of the text.
+function applyTremor(strokes, amount) {
+    if (amount <= 0)
+        return;
+    const A = 0.008 * amount;
+    strokes.forEach((s, si) => {
+        const n = s.pts.length / 2;
+        const P = s.pts;
+        const out = new Float32Array(P.length);
+        const hs = (a, b) => { const x = Math.sin((si * 97 + a) * 127.1 + b * 311.7) * 43758.5453; return x - Math.floor(x); };
+        const F = [], PH = [], PT = [];
+        for (let j = 0; j < 5; j++) {
+            F.push(8 + 4 * hs(j, 1));
+            PH.push(6.2831 * hs(j, 2));
+            PT.push(6.2831 * hs(j, 3));
+        }
+        const env0 = 6.2831 * hs(9, 4);
+        for (let i = 0; i < n; i++) {
+            const a = Math.max(0, i - 1), b = Math.min(n - 1, i + 1);
+            let tx = P[2 * b] - P[2 * a], ty = P[2 * b + 1] - P[2 * a + 1];
+            const tl = Math.hypot(tx, ty) || 1;
+            tx /= tl;
+            ty /= tl;
+            const dt = Math.max(1e-4, (s.tsec[b] - s.tsec[a]));
+            const v = tl / dt; // em / s
+            const q = clamp((v - 0.1) / 0.9, 0, 1);
+            const w = 0.12 + 0.88 * q * q * (3 - 2 * q);
+            const t = s.tsec[i];
+            let dn = 0, dtn = 0;
+            for (let j = 0; j < 5; j++) {
+                dn += Math.sin(6.2831 * F[j] * t + PH[j]);
+                dtn += Math.sin(6.2831 * F[j] * t + PT[j]);
+            }
+            const env = 0.65 + 0.35 * Math.sin(6.2831 * 0.8 * t + env0);
+            const k = A * w * env / Math.sqrt(5);
+            out[2 * i] = P[2 * i] + (-ty * dn + tx * dtn * 0.3) * k;
+            out[2 * i + 1] = P[2 * i + 1] + (tx * dn + ty * dtn * 0.3) * k;
+        }
+        s.pts = out;
+    });
+}
+// ---- CPU path-position lookup from the schedule (seg window + per-point t) ------------------------
+function packRows(strokes) {
+    const order = strokes.slice().sort((a, b) => a.seg[0] - b.seg[0]);
+    const rows = [];
+    for (const s of order) {
+        let r = rows.find((row) => row[row.length - 1].seg[1] <= s.seg[0] + 1e-9);
+        if (!r) {
+            if (rows.length >= MAX_ROWS)
+                continue;
+            r = [];
+            rows.push(r);
+        }
+        r.push(s);
+    }
+    return rows;
+}
+// tip of pen row `r` at global progress g -> out = [x, y, fade, exposure]; returns false when the pen is not down
+function tipAt(rows, r, g, out) {
+    const row = rows[r];
+    let lo = 0, hi = row.length - 1;
+    while (lo < hi) {
+        const m = (lo + hi + 1) >> 1;
+        if (row[m].seg[0] <= g)
+            lo = m;
+        else
+            hi = m - 1;
+    }
+    const s = row[lo];
+    if (g < s.seg[0] || g > s.seg[1])
+        return false;
+    const span = Math.max(1e-6, s.seg[1] - s.seg[0]);
+    const u = (g - s.seg[0]) / span;
+    const n = s.pts.length / 2;
+    const T = s.t;
+    let a = 0, b = n - 1;
+    while (b - a > 1) {
+        const m = (a + b) >> 1;
+        if (T[m] <= u)
+            a = m;
+        else
+            b = m;
+    }
+    const f = clamp((u - T[a]) / Math.max(1e-9, T[b] - T[a]), 0, 1);
+    out[0] = s.pts[2 * a] + (s.pts[2 * b] - s.pts[2 * a]) * f;
+    out[1] = s.pts[2 * a + 1] + (s.pts[2 * b + 1] - s.pts[2 * a + 1]) * f;
+    out[2] = Math.min(1, u / 0.04, (1 - u) / 0.04);
+    out[3] = s.pressure[a] + (s.pressure[b] - s.pressure[a]) * f;
+    return true;
+}
+// ---- shared GLSL ------------------------------------------------------------------------------
+const GLSL_BB = /* glsl */ `
+// blackbody colour (Tanner Helland fit, sRGB) -> linear
+vec3 bbLin(float T){
+  float t = clamp(T, 1000.0, 12000.0)/100.0; vec3 c;
+  c.r = t <= 66.0 ? 1.0 : 1.29293*pow(max(t - 60.0, 1e-3), -0.1332);
+  c.g = t <= 66.0 ? 0.390083*log(t) - 0.631841 : 1.129891*pow(max(t - 60.0, 1e-3), -0.0755);
+  c.b = t >= 66.0 ? 1.0 : (t <= 19.0 ? 0.0 : 0.543205*log(max(t - 10.0, 1e-3)) - 1.196254);
+  return pow(clamp(c, 0.0, 1.0), vec3(2.2));
+}
+vec3 bbRel(float T){ return bbLin(T)/bbLin(6500.0); }
+`;
+const VARYINGS = /* glsl */ `
+varying float vSide; varying vec2 vUU; varying vec4 vTT; varying vec2 vLL; varying vec2 vSI; varying float vVar; varying float vGlyph; varying float vSeed; varying vec2 vPos;
+`;
+// ---- trail: capsule field (MAX blended = exact function of the distance to the polyline) -----------
+const TRAIL_VERT = /* glsl */ `
+attribute vec2 aq; attribute vec2 iA; attribute vec2 iB; attribute vec2 iT; attribute vec2 iTO; attribute vec2 iArc; attribute float iLen;
+attribute vec2 iSeg; attribute vec2 iSegO; attribute vec2 iVar; attribute vec2 iPC;
+${REVEAL_UNIFORMS}${VARYINGS}
+varying vec2 vXY; varying float vHL; varying float vLen; varying vec2 vPC; varying float vSpacing;
+void main(){
+  vec2 d = iB - iA; float l = max(length(d), 1e-6); vec2 dir = d / l; vec2 perp = vec2(-dir.y, dir.x);
+  float hl = 0.5*l; float R = uHalf;
+  vec2 loc = vec2(aq.x*(hl + R), aq.y*R);
+  vec2 w = 0.5*(iA + iB) + dir*loc.x + perp*loc.y;
+  gl_Position = projectionMatrix*modelViewMatrix*vec4(w, 0.0, 1.0);
+  float sp = max(iSeg.y - iSeg.x, 1e-4), so = max(iSegO.y - iSegO.x, 1e-4);
+  vXY = loc; vHL = hl; vLen = iLen; vPC = iPC; vSpacing = min(l/max(iPC.y - iPC.x, 1e-6), 0.6); vSide = 0.0; vVar = iVar.x; vGlyph = iVar.y; vPos = w;
+  vTT = vec4(iT, iTO); vUU = iArc / iLen; vSI = vec2(iSeg.x, sp);
+  vLL = vec2((uHead - iSeg.x)/sp, (uErase - iSegO.x)/so);
+  vSeed = iSeg.x*91.7 + iVar.y*13.1;
+}`;
+const TRAIL_FRAG = /* glsl */ `
+uniform vec3 uColor; uniform vec3 uColor2; uniform float uOpacity; uniform float uExposure; uniform float uTemp; uniform float uWidth; uniform float uStrobe; uniform float uHalation;
+varying vec2 vXY; varying float vHL; varying float vLen; varying vec2 vPC; varying float vSpacing;
+${GLSL_BB}
+float vn(vec2 p){ vec2 i = floor(p); vec2 f = fract(p); f = f*f*(3.0 - 2.0*f);
+  return mix(mix(h21(i), h21(i + vec2(1.0, 0.0)), f.x), mix(h21(i + vec2(0.0, 1.0)), h21(i + vec2(1.0, 1.0)), f.x), f.y); }
+void main(){
+  float dd = length(vec2(max(abs(vXY.x) - vHL, 0.0), vXY.y));
+  float fwd = max(fwidth(dd), 1e-5);                       // derivatives before any discard
+  float lat = vXY.y;
+  float f = clamp((vXY.x + vHL)/(2.0*max(vHL, 1e-6)), 0.0, 1.0);
+  float sAbs = mix(vUU.x, vUU.y, f)*vLen; float uArc = mix(vUU.x, vUU.y, f);
+  float fwl = fwidth(lat);
+  float inR = revealIn(f);
+  float age = ageAt(f);
+  float e = clamp(vVar, 0.3, 3.5);
+
+  // --- erase: the trail cools and dims ahead of the erase front (oldest end first)
+  float tO = mix(vTT.z, vTT.w, f); float rem = tO - vLL.y;
+  float lead = uFadeOut > 0.5 ? 1.0 : smoothstep(0.0, uSoftOut + 0.2, rem);
+  float dimF = mix(1.0, lead, smoothstep(0.0, 0.05, uE))*revealOut(f);
+
+  // --- exposure profile: tight source image + soft scattering tail + faint wide airglow (all sized by the pen dwell)
+  float sig = max(uWidth*(0.8 + 0.2*min(e, 1.8)), 0.8*fwd);
+  float x = dd/sig;
+  float P = 0.92*exp(-0.5*x*x) + 0.05*exp(-0.5*x*x/5.0) + 0.008*sqrt(e)*exp(-0.5*x*x/40.0);
+  float edgeF = 1.0 - smoothstep(0.6*uHalf, uHalf, dd);
+  P *= edgeF;
+
+  // --- strobe: the LED pulses at constant pen-clock intervals, so dot spacing = pen speed; slow stretches merge into continuous light
+  float ph = fract(mix(vPC.x, vPC.y, f)); float dsd = (ph - 0.5)*vSpacing;
+  float mrg = 1.0 - smoothstep(3.0*sig, 6.5*sig, vSpacing);
+  float dotA = mix(0.04 + 0.96*exp(-0.5*dsd*dsd/(1.21*sig*sig)), 1.0, mrg);
+  float along = mix(1.0, dotA, uStrobe); float boost = mix(1.0, 1.0 + 0.6*(1.0 - mrg), uStrobe);
+
+  // --- fibre grain of the exposure (film), elongated along the trail; shimmer is slow real time
+  float aa = 1.0 - smoothstep(0.35, 0.9, fwl*95.0);
+  vec2 gc = vec2(sAbs*22.0, lat*85.0 + vGlyph*17.0);
+  float fib = vn(gc)*0.65 + vn(vec2(sAbs*61.0, lat*210.0 + vGlyph*5.0))*0.35*(1.0 - smoothstep(0.3, 0.8, fwl*210.0));
+  float tw = 0.5 + 0.5*sin(uTime*0.55*uIdleSpeed + 6.2831*h21(floor(gc)));
+  float capK = 1.0 - smoothstep(0.0, 0.012, max(abs(vXY.x) - vHL, 0.0));
+  float grain = 1.0 + 0.2*(fib - 0.5)*2.0*(0.55 + 0.45*tw)*aa*capK;
+
+  // --- a few slow glints drifting along the finished strokes
+  float sd = vSeed; float on = step(0.38, h21(vec2(sd, 3.0)));
+  float gp = fract(uTime*0.03*uIdleSpeed*(0.6 + 0.8*h21(vec2(sd, 1.0))) + h21(vec2(sd, 2.0)));
+  float du = abs(fract(uArc - gp + 0.5) - 0.5)*vLen;
+  float env = pow(0.5 + 0.5*sin(uTime*0.11*uIdleSpeed + 6.2831*h21(vec2(sd, 4.0))), 3.0);
+  float glint = on*env*exp(-du*du/0.0225 - 0.5*dd*dd/(2.0*sig*sig))*smoothstep(0.8, 2.0, age)*uIdle;
+
+  // --- film response
+  float h = exp(-age/1.0) * dimF;
+  h = clamp(h + 0.25*glint, 0.0, 1.0);
+  float lvl = 0.62 + 0.38*exp(-age/1.7);
+  float H = uExposure*e*lvl*P*grain*(1.0 + 0.5*glint)*dimF*dimF*along*boost;
+  // film halation: light scattered in the film base bleeds a wide dim red-orange glow around the strongest exposure
+  float Hh = uHalation*0.011*pow(uExposure*lvl, 1.4)*sqrt(e)*exp(-0.5*dd*dd/(18.0*sig*sig))*edgeF*dimF*dimF*mix(1.0, 0.35 + 0.65*along, uStrobe);
+  float Tk = uTemp*(1.0 + 0.85*h)*mix(0.6, 1.0, dimF);
+  vec3 tint = mix(uColor, uColor2, h)*bbRel(Tk);
+  tint /= max(max(tint.r, tint.g), max(tint.b, 1e-3));
+  vec3 col = 0.94*(1.0 - exp(-(3.0*H*tint + 3.0*Hh*vec3(1.0, 0.30, 0.08))))*inR*uOpacity;
+  if (max(col.r, max(col.g, col.b)) < 0.0015) discard;
+  gl_FragColor = vec4(col, 1.0);
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+// ---- pen-tip bloom (additive instanced quad per active pen) ------------------------------------------
+const BLOOM_VERT = /* glsl */ `
+attribute vec2 aq; attribute vec4 iC; uniform float uBloom; uniform float uQ;
+varying vec2 vP; varying vec2 vQ; varying float vA; varying float vE;
+void main(){ float s = 0.5 + 0.5*uBloom; vQ = aq; vP = aq*uQ*s; vA = iC.z; vE = iC.w;
+  gl_Position = projectionMatrix*modelViewMatrix*vec4(iC.xy + vP, 0.0, 1.0); }`;
+const BLOOM_FRAG = /* glsl */ `
+precision highp float;
+uniform vec3 uColor; uniform vec3 uColor2; uniform float uOpacity; uniform float uTemp; uniform float uBloom;
+varying vec2 vP; varying vec2 vQ; varying float vA; varying float vE;
+${GLSL_BB}
+void main(){
+  float s = 0.5 + 0.5*uBloom; vec2 p = vP/s;
+  float fwy = max(fwidth(p.y), fwidth(p.x));
+  float r = length(p);
+  float core = exp(-pow(r/0.017, 2.0));
+  float halo = 0.38/pow(1.0 + pow(r/0.045, 2.0), 1.3);
+  float glow = 0.09*exp(-r/0.1);
+  float ws = max(0.0045, 1.3*fwy);
+  float streak = exp(-abs(p.x)/0.08)*exp(-pow(p.y/ws, 2.0)) + exp(-abs(p.y)/0.08)*exp(-pow(p.x/ws, 2.0));
+  float edge = (1.0 - smoothstep(0.55, 1.0, max(abs(vQ.x), abs(vQ.y))))*(1.0 - smoothstep(0.3, 1.0, length(vQ)));
+  vec3 hot = bbRel(uTemp*1.9)*uColor2; vec3 warm = bbRel(uTemp*1.25)*uColor;
+  hot /= max(max(hot.r, hot.g), max(hot.b, 1e-3)); warm /= max(max(warm.r, warm.g), max(warm.b, 1e-3));
+  vec3 col = hot*(core*1.15 + halo*0.7) + warm*(glow + halo*0.5) + mix(hot, warm, 0.5)*streak*0.22;
+  col *= edge*vA*uOpacity*uBloom*(0.75 + 0.25*vE);
+  gl_FragColor = vec4(col, 1.0);
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+// ---- sparks: closed-form ballistic streaks ---------------------------------------------------------
+const SPARK_VERT = /* glsl */ `
+attribute vec2 aq;
+uniform sampler2D uTip; uniform float uNB; uniform float uJ; uniform float uNs; uniform float uRate; uniform float uSpread; uniform float uTemp;
+uniform float uPx; uniform float uHead; uniform float uDur; uniform float uSince; uniform float uOpacity; uniform float uLife;
+varying vec2 vQ; varying vec3 vCol; varying float vI;
+${GLSL_BB}
+float hh(float a, float b){ return fract(sin(a*127.1 + b*311.7)*43758.5453); }
+void main(){
+  vQ = aq; vI = 0.0; vCol = vec3(0.0);
+  gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
+  float id = float(gl_InstanceID); float J = max(uJ, 1.0); float row = mod(id, J); float slot = floor(id/J);
+  float Rg = max(uRate*uDur, 1e-3);
+  float m = floor((uHead*Rg - slot)/uNs); if (m < 0.0) return;
+  float jit = hh(id, m); float g = (slot + m*uNs + jit)/Rg;
+  if (g > uHead) { m -= 1.0; if (m < 0.0) return; jit = hh(id, m); g = (slot + m*uNs + jit)/Rg; }
+  float age = (uHead - g)*uDur + uSince;
+  float h1 = hh(id + 17.0, m), h2 = hh(id + 31.0, m), h3 = hh(id + 53.0, m);
+  float life = uLife*(0.55 + 0.45*h1);
+  if (age >= life || age < 0.0) return;
+  float bf = g*(uNB - 1.0); float b0 = floor(bf); float fr = bf - b0;
+  vec4 t0 = texelFetch(uTip, ivec2(int(b0), int(row)), 0);
+  vec4 t1 = texelFetch(uTip, ivec2(int(min(b0 + 1.0, uNB - 1.0)), int(row)), 0);
+  float act = t0.z*t1.z; if (act < 0.002) return;
+  vec2 o = mix(t0.xy, t1.xy, fr); vec2 pv = (t1.xy - t0.xy)*(uNB - 1.0)/uDur;
+  float ang = 6.2831853*h2; float sp = uSpread*(0.15 + 1.25*h3*h3);
+  vec2 v0 = vec2(cos(ang), sin(ang))*sp + pv*0.2;
+  float k = 1.9; vec2 vinf = vec2(0.0, -0.95/k); float ek = exp(-k*age);
+  vec2 p = o + (v0 - vinf)*((1.0 - ek)/k) + vinf*age;       // origin + v age + 1/2 g age^2, with linear drag
+  vec2 vel = (v0 - vinf)*ek + vinf;
+  float speed = length(vel); vec2 dir = vel/max(speed, 1e-4); vec2 perp = vec2(-dir.y, dir.x);   // (dir, perp) is right-handed
+  vec4 mv = modelViewMatrix*vec4(p, 0.0, 1.0);
+  float wpp = -mv.z/uPx; float w0 = 0.0038; float w = max(w0, 1.1*wpp); float comp = w0/w;
+  float L = 0.5*max(speed*0.085, 2.0*w) + 1.5*w; float W = 2.6*w;
+  vec2 q = p + dir*(aq.x*L) + perp*(aq.y*W);
+  gl_Position = projectionMatrix*modelViewMatrix*vec4(q, 0.0, 1.0);
+  float a = age/life;
+  float Ts = mix(clamp(uTemp*2.0, 3800.0, 8500.0), 1300.0, pow(a, 0.6));
+  vCol = bbLin(Ts);
+  vI = 1.8*comp*pow(1.0 - a, 1.1)*smoothstep(0.0, 0.025, age)*(0.55 + 0.7*h1)*(0.8 + 0.2*sin(age*38.0 + h2*6.28))*act*uOpacity*(1.0 - smoothstep(0.0, 0.35, uSince));
+}`;
+const SPARK_FRAG = /* glsl */ `
+precision highp float;
+varying vec2 vQ; varying vec3 vCol; varying float vI;
+void main(){
+  float along = pow(smoothstep(-1.0, 0.6, vQ.x), 2.0)*(1.0 - smoothstep(0.6, 1.0, vQ.x));
+  float yw = vQ.y*2.6; float lat = exp(-yw*yw*0.7)*(1.0 - smoothstep(0.75, 1.0, abs(vQ.y)));
+  float a = along*lat*vI; if (a < 0.002) discard;
+  gl_FragColor = vec4(vCol*a, 1.0);
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+const quadIndex = [0, 1, 2, 0, 2, 3];
+function extentPosition(g, strokes, pad) {
+    const e = extentOf(strokes);
+    const x0 = e.x0 - pad, x1 = e.x1 + pad, y0 = e.y0 - pad, y1 = e.y1 + pad;
+    g.setAttribute('position', new THREE.BufferAttribute(new Float32Array([x0, y0, 0, x1, y0, 0, x1, y1, 0, x0, y1, 0]), 3)); // selection bounds only, never read by the shaders
+}
+const num = (name, label, description, min, max, step, unit) => ({ name, label, description, type: 'number', min, max, step, ...(unit ? { unit } : {}) });
+const col = (name, label, description) => ({ name, label, description, type: 'color' });
+export default {
+    key: 'lightPainting', source: 'hand', drawMethods: DRAW_METHODS, eraseMethods: ERASE_METHODS, drawDefault: 'pen', eraseDefault: 'pen',
+    catalog: {
+        name: 'Light Painting',
+        description: 'A long-exposure photograph of a handheld light writing in the dark: trail brightness follows 1/pen speed, colour cools from hot to warm, and a sparkler throws ballistic sparks. Use for night-photo titles, signatures and festive reveals.',
+        tags: ['light-painting', 'long-exposure', 'sparkler', 'handwriting', 'night', 'glow', 'photo'],
+    },
+    defaults: { exposure: 1, temperature: 3000, sparks: 110, spread: 0.7, bloom: 1, width: 0.012, strobe: 0, halation: 0.55, tremor: 0.5, color: '#ffe0b0', color2: '#ffffff', opacity: 1 },
+    ui: {
+        main: [
+            num('exposure', 'Exposure', 'How long the shutter stayed open: trail brightness, bleaching towards white and persistence.', 0.2, 2.5, 0.01),
+            num('temperature', 'Temperature', 'Colour temperature of the light source: low is ember red, high is cold white. Fresh trail is hotter and cools to this.', 1200, 9000, 10, 'K'),
+            num('strobe', 'Strobe', 'The light pulses while writing: the trail becomes dots whose spacing shows pen speed (dense where slow). 0 is continuous.', 0, 1, 0.01),
+            num('sparks', 'Sparks', 'Sparkler mode: sparks thrown per second by the pen tip while writing. 0 is a plain LED torch.', 0, 400, 1, '/s'),
+        ],
+        more: [
+            num('width', 'Trail width', 'Width of the light trail (the source image on the sensor).', 0.004, 0.03, 0.0005, 'em'),
+            num('halation', 'Halation', 'Film halation: a wide dim red-orange glow bleeding around the brightest exposure.', 0, 2, 0.01),
+            num('tremor', 'Hand tremor', 'Physiological 8-12 Hz tremor of the hand: a faint fine ripple on the lines, smaller where the pen is slow.', 0, 1, 0.01),
+            num('spread', 'Spread', 'How violently the sparks are thrown out; low sparks drip, high sparks fan out wide.', 0, 1.6, 0.01),
+            num('bloom', 'Bloom', 'Lens bloom and thin streak cross on the glowing pen tip.', 0, 2, 0.01),
+            col('color', 'Colour', 'Resting colour of the trail (gel over the source), balanced by the temperature.'),
+            col('color2', 'Hot core', 'Colour of the fresh, hot trail and the tip.'),
+            num('opacity', 'Opacity', 'Overall opacity of the light.', 0, 1, 0.01),
+        ],
+    },
+    structural: ['tremor'],
+    presets: [
+        { name: 'Warm LED', description: 'Warm torch trail, a light shower of sparks.', patch: {} },
+        { name: 'Sparkler', description: 'Hot white sparkler: dense, wide spark shower.', patch: { temperature: 3600, sparks: 200, spread: 1.1, exposure: 0.9, bloom: 1.2, color: '#ffcf8a' } },
+        { name: 'Cold Torch', description: 'Cold white LED, no sparks, crisp tip.', patch: { temperature: 6800, sparks: 0, bloom: 0.8, width: 0.01, color: '#cfe6ff', color2: '#ffffff', exposure: 1.1 } },
+        { name: 'Ember', description: 'Glowing red coal drawn slowly: deep exposure, few sparks.', patch: { temperature: 1700, sparks: 25, spread: 0.45, exposure: 1.5, width: 0.016, bloom: 0.7, color: '#ff8a50', color2: '#ffe6c8' } },
+        { name: 'Strobe Gel', description: 'Pulsing magenta-gel LED: dotted trail, spacing shows pen speed.', patch: { temperature: 6500, sparks: 0, strobe: 1, exposure: 1.3, color: '#ff3fb4', color2: '#ffe2f6', width: 0.013, halation: 1.1 } },
+    ],
+    build(layout, cfg, anim) {
+        const strokes = layout.strokes;
+        prepare(strokes, 'hand');
+        const G = layout.glyphs.length;
+        strokes.forEach((s) => { s.glyphN = s.glyph / Math.max(1, G - 1); });
+        shapeExposure(strokes);
+        penClock(strokes, anim.draw.duration);
+        applyTremor(strokes, cfg.tremor);
+        const { infoD, infoE } = applyAnim(strokes, anim, G);
+        const tipMode = !!infoD.tip;
+        // trail
+        const geo = buildCapsules(strokes);
+        extentPosition(geo, strokes, 0.3);
+        {
+            let nseg = 0;
+            for (const s of strokes)
+                nseg += s.pts.length / 2 - 1;
+            const pc = new Float32Array(nseg * 2);
+            let k = 0;
+            for (const s of strokes)
+                for (let i = 0; i < s.pts.length / 2 - 1; i++) {
+                    pc[2 * k] = s.cyc[i];
+                    pc[2 * k + 1] = s.cyc[i + 1];
+                    k++;
+                }
+            geo.setAttribute('iPC', new THREE.InstancedBufferAttribute(pc, 2));
+        }
+        const U = uniformsBase();
+        const mat = new THREE.ShaderMaterial({
+            uniforms: { ...U, uColor: { value: hex(cfg.color) }, uColor2: { value: hex(cfg.color2) }, uOpacity: { value: 1 }, uExposure: { value: 1 }, uTemp: { value: 3000 }, uWidth: { value: 0.012 }, uStrobe: { value: 0 }, uHalation: { value: 0.55 } },
+            vertexShader: TRAIL_VERT, fragmentShader: frag(TRAIL_FRAG),
+            transparent: true, depthWrite: false, side: THREE.DoubleSide,
+            blending: THREE.CustomBlending, blendEquation: THREE.MaxEquation, blendSrc: THREE.OneFactor, blendDst: THREE.OneFactor,
+        });
+        const mesh = new THREE.Mesh(geo, mat);
+        mesh.frustumCulled = false;
+        mesh.renderOrder = 0;
+        // pen rows + baked tip table
+        const rows = tipMode ? packRows(strokes) : [];
+        const J = Math.max(1, rows.length);
+        const tipData = new Float32Array(TIP_BINS * J * 4);
+        const tmp = [0, 0, 0, 0];
+        rows.forEach((row, r) => { for (let b = 0; b < TIP_BINS; b++) {
+            const o = (r * TIP_BINS + b) * 4;
+            if (tipAt(rows, r, b / (TIP_BINS - 1), tmp)) {
+                tipData[o] = tmp[0];
+                tipData[o + 1] = tmp[1];
+                tipData[o + 2] = tmp[2];
+            }
+        } });
+        const tipTex = new THREE.DataTexture(tipData, TIP_BINS, J, THREE.RGBAFormat, THREE.FloatType);
+        tipTex.minFilter = tipTex.magFilter = THREE.NearestFilter;
+        tipTex.generateMipmaps = false;
+        tipTex.needsUpdate = true;
+        // sparks
+        const sg = new THREE.InstancedBufferGeometry();
+        sg.setAttribute('aq', new THREE.BufferAttribute(new Float32Array([-1, -1, 1, -1, 1, 1, -1, 1]), 2));
+        sg.setIndex(quadIndex);
+        extentPosition(sg, strokes, 0.6);
+        sg.instanceCount = 0;
+        sg.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e3);
+        const smat = new THREE.ShaderMaterial({
+            uniforms: { ...U, uTip: { value: tipTex }, uNB: { value: TIP_BINS }, uJ: { value: J }, uNs: { value: 1 }, uRate: { value: 0 }, uSpread: { value: 0.7 }, uTemp: { value: 3000 }, uPx: { value: 800 }, uOpacity: { value: 1 }, uLife: { value: 1.3 } },
+            vertexShader: SPARK_VERT, fragmentShader: SPARK_FRAG, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide,
+        });
+        const sparks = new THREE.Mesh(sg, smat);
+        sparks.frustumCulled = false;
+        sparks.renderOrder = 1;
+        // bloom
+        const bg = new THREE.InstancedBufferGeometry();
+        bg.setAttribute('aq', new THREE.BufferAttribute(new Float32Array([-1, -1, 1, -1, 1, 1, -1, 1]), 2));
+        bg.setIndex(quadIndex);
+        const iC = new THREE.InstancedBufferAttribute(new Float32Array(J * 4), 4);
+        iC.setUsage(THREE.DynamicDrawUsage);
+        bg.setAttribute('iC', iC);
+        extentPosition(bg, strokes, 0.6);
+        bg.instanceCount = J;
+        bg.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e3);
+        const bmat = new THREE.ShaderMaterial({
+            uniforms: { uColor: { value: hex(cfg.color) }, uColor2: { value: hex(cfg.color2) }, uOpacity: { value: 1 }, uTemp: { value: 3000 }, uBloom: { value: 1 }, uQ: { value: 0.9 } },
+            vertexShader: BLOOM_VERT, fragmentShader: BLOOM_FRAG, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide,
+        });
+        const bloom = new THREE.Mesh(bg, bmat);
+        bloom.frustumCulled = false;
+        bloom.renderOrder = 2;
+        const group = new THREE.Group();
+        group.add(mesh, sparks, bloom);
+        const api = {
+            object: group, c: cfg,
+            apply(c) {
+                const u = mat.uniforms;
+                u.uColor.value.set(c.color);
+                u.uColor2.value.set(c.color2);
+                u.uOpacity.value = c.opacity;
+                u.uExposure.value = c.exposure;
+                u.uTemp.value = c.temperature;
+                u.uWidth.value = c.width;
+                u.uStrobe.value = c.strobe;
+                u.uHalation.value = c.halation;
+                u.uHalf.value = c.width * 15;
+                const su = smat.uniforms;
+                su.uRate.value = c.sparks;
+                su.uSpread.value = c.spread;
+                su.uTemp.value = c.temperature;
+                su.uOpacity.value = c.opacity;
+                const ns = clamp(Math.ceil(c.sparks * su.uLife.value * 1.3), 1, Math.floor(MAX_SPARKS / J));
+                su.uNs.value = ns;
+                sg.instanceCount = ns * J;
+                sparks.visible = tipMode && c.sparks > 0.01;
+                const bu = bmat.uniforms;
+                bu.uColor.value.set(c.color);
+                bu.uColor2.value.set(c.color2);
+                bu.uOpacity.value = c.opacity;
+                bu.uTemp.value = c.temperature;
+                bu.uBloom.value = c.bloom;
+                bloom.visible = tipMode && c.bloom > 0.01;
+                api.c = c;
+            },
+            update(S, time, px) {
+                setReveal(U, S, infoD, infoE, anim.draw.duration, time);
+                smat.uniforms.uPx.value = px;
+                if (bloom.visible) {
+                    const head = U.uHead.value;
+                    const pen = tipMode && S.d > 0 && S.d < 1 && S.e <= 0;
+                    const a = iC.array;
+                    for (let r = 0; r < J; r++) {
+                        const on = pen && tipAt(rows, r, head, tmp);
+                        a[4 * r] = on ? tmp[0] : 0;
+                        a[4 * r + 1] = on ? tmp[1] : 0;
+                        a[4 * r + 2] = on ? tmp[2] : 0;
+                        a[4 * r + 3] = on ? tmp[3] : 0;
+                    }
+                    iC.needsUpdate = true;
+                }
+            },
+            dispose() { geo.dispose(); mat.dispose(); sg.dispose(); smat.dispose(); bg.dispose(); bmat.dispose(); tipTex.dispose(); },
+        };
+        api.apply(cfg);
+        return api;
+    },
+};