@3driseai/3drise-viewer 0.1.28 → 0.1.30

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

@@ -0,0 +1,645 @@
+import * as THREE from 'three';
+import { buildCapsules, capsuleMaterial, frag, uniformsBase, setReveal, headPoint, REVEAL_UNIFORMS } from '../ribbon.js';
+import { prepare, applyAnim, DRAW_METHODS, ERASE_METHODS } from '../methods.js';
+const hex = (h) => new THREE.Color(h);
+const clamp = (x, a, b) => Math.max(a, Math.min(b, x));
+function mulberry32(a) { return function () { a |= 0; a = (a + 0x6D2B79F5) | 0; let t = Math.imul(a ^ (a >>> 15), 1 | a); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; }; }
+// =========================================================================================
+// embroidery — satin stitch along the pen strokes.
+//   Geometry: every stroke is cut into stitches spaced `1/density` apart along arc length (deterministic jitter); a stitch
+//   is a straight thread from one edge of the stroke band to the other at the slant angle theta to the tangent
+//   (D = cos(theta) T + sin(theta) N, half length = W / (2 sin theta), W = pen width * pressure * thickness), drawn as a
+//   round-capped pill. Thread radius r = 0.62 * spacing * sin(theta) so neighbours overlap by ~20%: later stitches lie over
+//   earlier ones, which is what hides the ends ("tucked") and what the cast self-shadow on the previous stitch models.
+//   Shading: each thread is a lump with a cylinder height profile h = sqrt(1 - s^2) (s = distance / radius, round ends) and a
+//   ply twist: slanted bands in the surface normal. The fibre direction on the lump is the thread axis rotated about the
+//   normal by the twist angle; specular is Kajiya-Kay, spec = pow(sqrt(1 - (T.H)^2), shininess): a thin line light that
+//   is brightest where the fibres are perpendicular to the half vector. Because satin stitches turn with the letter, a slowly
+//   orbiting key light lights up the stitches of one orientation at a time: a soft sheen sweeping over the lettering.
+//   Draw: the needle pulls each thread through from one end to the other (age since the pen passed); erase: threads are
+//   unpicked (lift = fade + shrink in width and length).
+// =========================================================================================
+function lightAt(time, out) {
+    // closed form of time: azimuth turns once in ~45 s, elevation breathes slowly
+    const a = 0.9 + time * 0.14, e = 0.46 + 0.14 * Math.sin(time * 0.093 + 0.7);
+    out.set(Math.cos(a) * Math.cos(e), Math.sin(a) * Math.cos(e), Math.sin(e));
+}
+// ---- CPU: stitches ------------------------------------------------------------------------
+// Stitch vocabulary, chosen per stroke / per run like an embroiderer would:
+//   satin   broad strokes: slanted threads across the band (kind 0)
+//   stem    thin runs: overlapping slanted stitches that twist into a rope line (kind 0)
+//   couch   long near-straight strokes: laid thread(s) tacked down by small cross stitches (kind 0 + tacks, kind 3)
+//   knot    dots, tittles and the ends of stem lines: a wound French knot (kind 2)
+//   border  contrast running stitch along satin edges (kind 1)
+function makeSampler(s) {
+    const n = s.pts.length / 2, P = s.pts, cum = s.cum, T = s.t, TO = s.tO, WF = s.wfactor;
+    return function at(a, o) {
+        a = clamp(a, 0, s.len);
+        let lo = 0, hi = n - 1;
+        while (hi - lo > 1) {
+            const m = (lo + hi) >> 1;
+            if (cum[m] <= a)
+                lo = m;
+            else
+                hi = m;
+        }
+        const f = clamp((a - cum[lo]) / Math.max(1e-9, cum[hi] - cum[lo]), 0, 1);
+        o.x = P[2 * lo] + (P[2 * hi] - P[2 * lo]) * f;
+        o.y = P[2 * lo + 1] + (P[2 * hi + 1] - P[2 * lo + 1]) * f;
+        o.t = T[lo] + (T[hi] - T[lo]) * f;
+        o.to = TO[lo] + (TO[hi] - TO[lo]) * f;
+        o.w = WF ? WF[lo] + (WF[hi] - WF[lo]) * f : 1;
+        return o;
+    };
+}
+// thin runs of a stroke: smoothed local width factor with hysteresis, short runs dropped
+function thinRuns(s, at, thin) {
+    const L = s.len, st = 0.01, n = Math.max(2, Math.ceil(L / st)), w = new Float32Array(n + 1), o = {};
+    for (let i = 0; i <= n; i++)
+        w[i] = at(Math.min(L, i * st), o).w;
+    const sm = new Float32Array(n + 1);
+    for (let i = 0; i <= n; i++) {
+        let a = 0, c = 0;
+        for (let j = Math.max(0, i - 4); j <= Math.min(n, i + 4); j++) {
+            a += w[j];
+            c++;
+        }
+        sm[i] = a / c;
+    }
+    const runs = [];
+    let on = false, a0 = 0;
+    for (let i = 0; i <= n; i++) {
+        if (!on && sm[i] < thin) {
+            on = true;
+            a0 = i * st;
+        }
+        else if (on && sm[i] > thin * 1.14) {
+            on = false;
+            runs.push([a0, i * st]);
+        }
+    }
+    if (on)
+        runs.push([a0, L]);
+    return runs.filter((r) => r[1] - r[0] > 0.1).map((r) => [r[0] < 0.02 ? 0 : r[0], r[1] > L - 0.02 ? L : r[1]]);
+}
+const STYLES = ['auto', 'satin', 'stem', 'couching']; // config.style values (index = forced mode, 0 = automatic)
+function genStitches(strokes, natural, density, slantDeg, thick, style) {
+    const th = (clamp(slantDeg, 20, 89) * Math.PI) / 180, sinT = Math.sin(th);
+    const nom = natural * thick;
+    function gen(sp) {
+        const rows = [];
+        const B = {}, C = {}, TA = {}, TB = {};
+        for (let si = 0; si < strokes.length; si++) {
+            const s = strokes[si];
+            if (!(s.len > 1e-5))
+                continue;
+            const at = makeSampler(s);
+            const rnd = mulberry32(7919 + s.glyph * 131 + si * 17);
+            const L = s.len, G = s.glyphN || 0;
+            const tang = (a, o, d) => { const dd = d || Math.max(0.012, sp * 0.9); at(a - dd, TA); at(a + dd, TB); const dx = TB.x - TA.x, dy = TB.y - TA.y, l = Math.hypot(dx, dy) || 1; o[0] = dx / l; o[1] = dy / l; };
+            const push = (x, y, dx, dy, hl, r, kind, a, tt) => rows.push([x, y, dx, dy, hl, r, kind, rnd(), tt.t, tt.to, s.seg[0], s.seg[1], s.segO[0], s.segO[1], a / L, G]);
+            const knot = (a, R) => { at(a, C); push(C.x, C.y, 1, 0, 0, R, 2, a, C); };
+            const T0 = [0, 0], T1 = [0, 0];
+            // --- dots / tittles: French knot
+            if (s.dot || L < 0.05) {
+                at(L / 2, C);
+                const W = Math.max(0.03, nom * C.w);
+                knot(L / 2, clamp(0.5 * W, 0.02, 0.07));
+                continue;
+            }
+            at(L, C);
+            const cx1 = C.x, cy1 = C.y;
+            at(0, C);
+            const straight = Math.hypot(cx1 - C.x, cy1 - C.y) / L;
+            const mode = style === 1 ? 'satin' : style === 2 ? 'stem' : style === 3 ? 'couch' : (L > 0.5 && straight > 0.975 ? 'couch' : 'auto');
+            const runs = mode === 'stem' ? [[0, L]] : mode === 'auto' ? thinRuns(s, at, 0.8) : [];
+            const inRun = (a) => { for (const r of runs)
+                if (a >= r[0] - 0.004 && a <= r[1] + 0.004)
+                    return true; return false; };
+            if (mode === 'couch') {
+                let wm = 0, wc = 0;
+                for (let a = 0; a <= L; a += 0.02) {
+                    wm += at(a, C).w;
+                    wc++;
+                }
+                const Wc = Math.max(0.03, nom * wm / wc);
+                const rc = clamp(0.5 * Wc, 0.009, 0.026), rows_ = Math.max(1, Math.floor(Wc / (2 * rc) + 0.35)), gap = 2 * rc * 0.94;
+                const ns = Math.max(1, Math.ceil(L / 0.16));
+                for (let i = 0; i < ns; i++) {
+                    const a0 = (i * L) / ns, a1 = ((i + 1) * L) / ns;
+                    for (let j = 0; j < rows_; j++) {
+                        const o = (j - (rows_ - 1) / 2) * gap;
+                        tang(a0, T0);
+                        at(a0, C);
+                        const x0 = C.x - T0[1] * o, y0 = C.y + T0[0] * o, tt = { t: C.t, to: C.to };
+                        tang(a1, T1);
+                        at(a1, C);
+                        const x1 = C.x - T1[1] * o, y1 = C.y + T1[0] * o;
+                        const dx = x1 - x0, dy = y1 - y0, l = Math.hypot(dx, dy) || 1;
+                        push((x0 + x1) / 2, (y0 + y1) / 2, dx / l, dy / l, Math.max(0.003, l / 2 - 0.55 * rc), rc, 0, a0, tt);
+                    }
+                }
+                // tacks: tiny contrast cross stitches over the laid thread(s)
+                const nt = Math.max(1, Math.round(L / 0.11)), across = rows_ * rc * 0.95 + 0.4 * rc, tht = 1.0, rt = clamp(0.28 * rc, 0.0035, 0.007);
+                for (let j = 0; j < nt; j++) {
+                    const a = clamp((j + 0.5 + (rnd() - 0.5) * 0.3) * L / nt, 0, L);
+                    at(a, C);
+                    tang(a, T0);
+                    const Nx = -T0[1], Ny = T0[0];
+                    for (const sg of rows_ === 1 ? [-1, 1] : [j % 2 ? -1 : 1]) {
+                        const dx = Math.cos(tht) * T0[0] + sg * Math.sin(tht) * Nx, dy = Math.cos(tht) * T0[1] + sg * Math.sin(tht) * Ny;
+                        push(C.x, C.y, dx, dy, Math.max(0.003, across / Math.sin(tht) - 0.5 * rt), rt, 3, a, C);
+                    }
+                }
+                if (rows_ === 1)
+                    knot(L, clamp(1.25 * rc, 0.012, 0.03));
+                continue;
+            }
+            // --- satin over the broad parts
+            const n = Math.max(2, Math.round(L / sp)), step = L / n;
+            for (let k = 0; k < n; k++) {
+                const r1 = rnd(), r2 = rnd(), r3 = rnd(), r4 = rnd();
+                const a = clamp((k + 0.5 + (r1 - 0.5) * 0.36) * step, 0, L);
+                if (inRun(a))
+                    continue;
+                at(a, C);
+                tang(a, T0);
+                const dc = Math.max(0.03, step * 2);
+                tang(a - dc, T0);
+                tang(a + dc, T1);
+                const kap = Math.abs(Math.atan2(T0[0] * T1[1] - T0[1] * T1[0], T0[0] * T1[0] + T0[1] * T1[1])) / (2 * dc);
+                tang(a, T0);
+                const W = Math.max(0.03, nom * C.w);
+                const theta = th + (r2 - 0.5) * 0.09;
+                const sT = Math.sin(theta), cT = Math.cos(theta);
+                const r = 0.62 * step * sT * (1 + clamp(kap * W * 0.5 * 0.6, 0, 0.45));
+                const Nx = -T0[1], Ny = T0[0];
+                const hl = Math.max(0.004, (W * 0.5 / sT - 0.45 * r) * (1 + 0.08 * (r3 - 0.5)));
+                rows.push([C.x, C.y, cT * T0[0] + sT * Nx, cT * T0[1] + sT * Ny, hl, r, 0, r4, C.t, C.to, s.seg[0], s.seg[1], s.segO[0], s.segO[1], a / L, G]);
+            }
+            // --- stem stitch over the thin runs: each stitch starts half-way along the previous one, slanted: a twisted rope
+            for (const rn of runs) {
+                const len = rn[1] - rn[0];
+                at((rn[0] + rn[1]) / 2, C);
+                const r0 = clamp(0.2 * nom * C.w, 0.006, 0.02), pitch = 1.1 * r0, m = Math.max(1, Math.round(len / pitch)), pst = len / m;
+                for (let j = 0; j < m; j++) {
+                    const a = clamp(rn[0] + (j + 0.5 + (rnd() - 0.5) * 0.2) * pst, 0, L);
+                    at(a, C);
+                    tang(a, T0);
+                    const r = clamp(0.2 * nom * C.w, 0.006, 0.02), phi = 0.5 + (rnd() - 0.5) * 0.08, Nx = -T0[1], Ny = T0[0];
+                    push(C.x, C.y, Math.cos(phi) * T0[0] + Math.sin(phi) * Nx, Math.cos(phi) * T0[1] + Math.sin(phi) * Ny, Math.max(0.004, pst * 1.7 - 0.4 * r), r, 0, a, C);
+                }
+                if (rn[1] >= L - 1e-6)
+                    knot(L, clamp(1.3 * r0, 0.012, 0.04));
+            }
+            // --- border row: running stitch on both edges of the satin band
+            const rB = 0.62 * sp * sinT * 0.36, dashHL = 3.2 * rB, perD = 9.5 * rB;
+            const m = Math.max(1, Math.round(L / perD)), stp = L / m;
+            for (let side = -1; side <= 1; side += 2) {
+                for (let j = 0; j < m; j++) {
+                    const ac = (j + 0.5 + (side > 0 ? 0.5 : 0)) * stp;
+                    if (ac > L + 1e-6 && side > 0)
+                        continue;
+                    if (inRun(ac))
+                        continue;
+                    const a0 = clamp(ac - dashHL, 0, L), a1 = clamp(ac + dashHL, 0, L);
+                    if (a1 - a0 < dashHL * 0.5)
+                        continue;
+                    const edge = (a, o) => { at(a, B); tang(a, T0); const W = Math.max(0.03, nom * B.w); o.x = B.x - side * T0[1] * W * 0.5; o.y = B.y + side * T0[0] * W * 0.5; return o; };
+                    const e0 = edge(a0, {}), e1 = edge(a1, {});
+                    const dx = e1.x - e0.x, dy = e1.y - e0.y, l = Math.hypot(dx, dy);
+                    if (l < 1e-5)
+                        continue;
+                    at(ac, C);
+                    push((e0.x + e1.x) / 2, (e0.y + e1.y) / 2, dx / l, dy / l, Math.max(0.003, l / 2 - 0.5 * rB), rB, 1, ac, C);
+                }
+            }
+        }
+        return rows;
+    }
+    let sp = 1 / Math.max(4, density), rows = gen(sp);
+    for (let it = 0; it < 8 && rows.length > 12000; it++) {
+        sp *= 1.12;
+        rows = gen(sp);
+    }
+    return rows;
+}
+// ---- CPU: fabric pucker field -------------------------------------------------------------------
+// Dense stitching draws the cloth together. From the stitch coverage we build a smoothed density field (RG) and a wrinkle
+// height field (R): ridges that radiate across the stroke from the stitching (phase = arc length along the nearest stroke,
+// amplitude = proximity x local density). Only the fabric layer reads it: the threads never move.
+function blur1(src, nx, ny, rad) {
+    const tmp = new Float32Array(src.length), out = new Float32Array(src.length), k = 1 / (2 * rad + 1);
+    for (let y = 0; y < ny; y++) {
+        const o = y * nx;
+        let acc = 0;
+        for (let x = -rad; x <= rad; x++)
+            acc += src[o + clamp(x, 0, nx - 1)];
+        for (let x = 0; x < nx; x++) {
+            tmp[o + x] = acc * k;
+            acc += src[o + Math.min(nx - 1, x + rad + 1)] - src[o + Math.max(0, x - rad)];
+        }
+    }
+    for (let x = 0; x < nx; x++) {
+        let acc = 0;
+        for (let y = -rad; y <= rad; y++)
+            acc += tmp[clamp(y, 0, ny - 1) * nx + x];
+        for (let y = 0; y < ny; y++) {
+            out[y * nx + x] = acc * k;
+            acc += tmp[Math.min(ny - 1, y + rad + 1) * nx + x] - tmp[Math.max(0, y - rad) * nx + x];
+        }
+    }
+    return out;
+}
+function boxBlur(src, nx, ny, rad, passes) { let a = src; for (let p = 0; p < passes; p++)
+    a = blur1(a, nx, ny, rad); return a; }
+function bakePucker(strokes, rows, natural, thick) {
+    let x0 = 1e9, y0 = 1e9, x1 = -1e9, y1 = -1e9;
+    for (const s of strokes)
+        for (let i = 0; i < s.pts.length; i += 2) {
+            x0 = Math.min(x0, s.pts[i]);
+            x1 = Math.max(x1, s.pts[i]);
+            y0 = Math.min(y0, s.pts[i + 1]);
+            y1 = Math.max(y1, s.pts[i + 1]);
+        }
+    const mg = 0.35, cell = Math.max(0.014, Math.max(x1 - x0, y1 - y0) / 520);
+    const ox = x0 - mg, oy = y0 - mg, nx = Math.ceil((x1 - x0 + 2 * mg) / cell) + 1, ny = Math.ceil((y1 - y0 + 2 * mg) / cell) + 1;
+    const cov = new Float32Array(nx * ny), cA = cell * cell;
+    const wk = [1, 0.3, 0.8, 0.2];
+    for (const r of rows)
+        for (let k = -1; k <= 1; k++) {
+            const x = r[0] + r[2] * r[4] * k, y = r[1] + r[3] * r[4] * k, ix = Math.round((x - ox) / cell), iy = Math.round((y - oy) / cell);
+            if (ix >= 0 && iy >= 0 && ix < nx && iy < ny)
+                cov[iy * nx + ix] += wk[r[6]] * (4 * Math.max(r[4], r[5]) * r[5]) / 3 / cA;
+        }
+    const dsm = boxBlur(cov, nx, ny, 2, 2), dbig = boxBlur(dsm, nx, ny, 7, 2);
+    const best = new Float32Array(nx * ny).fill(1e9), bA = new Float32Array(nx * ny), bH = new Float32Array(nx * ny), bW = new Float32Array(nx * ny), bP = new Float32Array(nx * ny);
+    strokes.forEach((s, si) => {
+        if (!(s.len > 1e-5))
+            return;
+        const at = makeSampler(s), o = {}, ph0 = (si * 2.399) % 6.283;
+        for (let a = 0; a <= s.len + 1e-6; a += 0.008) {
+            at(a, o);
+            const hw = Math.max(0.015, 0.5 * natural * thick * o.w), R = hw + 0.17, wgt = clamp(hw * 2 / 0.1, 0.4, 1.2);
+            const ix0 = Math.max(0, Math.floor((o.x - R - ox) / cell)), ix1 = Math.min(nx - 1, Math.ceil((o.x + R - ox) / cell)), iy0 = Math.max(0, Math.floor((o.y - R - oy) / cell)), iy1 = Math.min(ny - 1, Math.ceil((o.y + R - oy) / cell));
+            for (let iy = iy0; iy <= iy1; iy++)
+                for (let ix = ix0; ix <= ix1; ix++) {
+                    const d = Math.hypot(ox + ix * cell - o.x, oy + iy * cell - o.y), id = iy * nx + ix;
+                    if (d < R && d < best[id]) {
+                        best[id] = d;
+                        bA[id] = a;
+                        bH[id] = hw;
+                        bW[id] = wgt;
+                        bP[id] = ph0;
+                    }
+                }
+        }
+    });
+    let hgt = new Float32Array(nx * ny);
+    for (let i = 0; i < hgt.length; i++) {
+        if (best[i] > 1e8)
+            continue;
+        const env = Math.exp(-Math.pow(Math.max(best[i] - bH[i], 0) / 0.085, 2)), ph = 6.2832 * (bA[i] / 0.07 + 0.2 * Math.sin(bA[i] * 4.7 + bP[i])) + bP[i];
+        hgt[i] = bW[i] * env * Math.sin(ph) * (0.4 + 0.9 * clamp(dsm[i], 0, 1));
+    }
+    hgt = boxBlur(hgt, nx, ny, 1, 1);
+    const data = new Uint8Array(nx * ny * 4);
+    for (let i = 0; i < nx * ny; i++) {
+        data[4 * i] = Math.round(clamp(hgt[i] * 0.5 + 0.5, 0, 1) * 255);
+        data[4 * i + 1] = Math.round(clamp(dsm[i], 0, 1) * 255);
+        data[4 * i + 2] = Math.round(clamp(dbig[i] * 1.6, 0, 1) * 255);
+        data[4 * i + 3] = 255;
+    }
+    const tex = new THREE.DataTexture(data, nx, ny, THREE.RGBAFormat, THREE.UnsignedByteType);
+    tex.magFilter = THREE.LinearFilter;
+    tex.minFilter = THREE.LinearFilter;
+    tex.wrapS = tex.wrapT = THREE.ClampToEdgeWrapping;
+    tex.needsUpdate = true;
+    return { tex, ox, oy, w: nx * cell, h: ny * cell, nx, ny, cell };
+}
+function buildStitchGeometry(rows) {
+    const n = rows.length;
+    const g = new THREE.InstancedBufferGeometry();
+    g.setAttribute('aq', new THREE.BufferAttribute(new Float32Array([-1, -1, 1, -1, 1, 1, -1, 1]), 2));
+    g.setIndex([0, 1, 2, 0, 2, 3]);
+    const cols = [['iC', 0, 2], ['iD', 2, 2], ['iP', 4, 4], ['iT', 8, 2], ['iSg', 10, 4], ['iX', 14, 2]];
+    for (const [name, off, sz] of cols) {
+        const a = new Float32Array(n * sz);
+        for (let i = 0; i < n; i++)
+            for (let j = 0; j < sz; j++)
+                a[i * sz + j] = rows[i][off + j];
+        g.setAttribute(name, new THREE.InstancedBufferAttribute(a, sz));
+    }
+    g.instanceCount = n;
+    g.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e3);
+    return g;
+}
+// ---- GLSL: thread ----------------------------------------------------------------------------
+const VARY = /* 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;
+varying vec2 vXY; varying vec4 vGeo; varying vec2 vDir;`;
+const STITCH_VERT = /* glsl */ `
+attribute vec2 aq; attribute vec2 iC; attribute vec2 iD; attribute vec4 iP; attribute vec2 iT; attribute vec4 iSg; attribute vec2 iX;
+${REVEAL_UNIFORMS}
+${VARY}
+void main(){
+  float hl = iP.x; float r = iP.y;
+  vec2 loc = vec2(aq.x*(hl + r*1.75), aq.y*r*1.75);
+  vec2 perp = vec2(-iD.y, iD.x);
+  vec2 w = iC + iD*loc.x + perp*loc.y;
+  gl_Position = projectionMatrix*modelViewMatrix*vec4(w, 0.0, 1.0);
+  float sp = max(iSg.y - iSg.x, 1e-4), so = max(iSg.w - iSg.z, 1e-4);
+  vXY = loc; vGeo = vec4(hl, r, iP.z, 0.0); vDir = iD; vSide = 0.0; vVar = iP.w; vGlyph = iX.y; vPos = w;
+  vTT = vec4(iT.x, iT.x, iT.y, iT.y); vUU = vec2(iX.x); vSI = vec2(iSg.x, sp);
+  vLL = vec2((uHead - iSg.x)/sp, (uErase - iSg.z)/so);
+  vSeed = iSg.x*91.7 + iX.y*13.1;
+}`;
+// kind: 0 thread (satin / stem / laid), 1 border running stitch, 2 French knot, 3 couching tack
+const STITCH_FRAG = /* glsl */ `
+uniform vec3 uColor; uniform vec3 uColor2; uniform float uOpacity; uniform float uSheen; uniform float uRelief; uniform float uOutline; uniform vec3 uL;
+void main(){
+  float hl = vGeo.x; float r0 = vGeo.y; float kind = vGeo.z; vec2 loc = vXY;
+  float kB = step(0.5, kind)*(1.0 - step(1.5, kind));
+  float kK = step(1.5, kind)*(1.0 - step(2.5, kind));
+  float kT = step(2.5, kind);
+  float kC2 = kB + kT; float kSym = kB + kT + 0.6*kK;
+  float lit = revealIn(0.0); float gone = revealOut(0.0); float age = ageAt(0.0);
+  // needle pulls the thread through from its entry end (a knot winds up and settles); unpicking lifts it: fade + shrink
+  float pull = uFadeIn > 0.5 ? 1.0 : mix(smoothstep(0.0, 0.16, age), smoothstep(0.0, 0.3, age), kK);
+  float lift = 1.0 - gone;
+  float r = mix(r0*(0.84 + 0.16*pull), r0*(0.5 + 0.5*pull + 0.1*sin(pull*3.14159)), kK)*(1.0 - 0.35*lift);
+  float a = -hl*(1.0 - 0.3*lift); float bF = hl*(1.0 - 0.3*lift); float b = mix(a, bF, pull);
+  float c = 0.5*(a + b); float sh = 0.5*(b - a);
+  vec2 q = vec2(loc.x - c - clamp(loc.x - c, -sh, sh), loc.y);
+  float ang = atan(q.y, q.x + 1e-5);
+  float s = length(q)/r*(1.0 + kK*(0.03*sin(ang*3.0 + vVar*30.0) + 0.02*sin(ang*5.0 + vVar*17.0)));
+  float fw = max(fwidth(s), 1e-4);
+  float u = (loc.x + hl)/r0; float v = q.y/r;
+  float ph = mix(u*0.60 + v*0.50 + vVar*5.0, s*5.5 - ang/6.2832 + vVar*5.0, kK);
+  float fwp = mix(fwidth(ph), fwidth(s*5.5), kK);
+  float fibP = mix(v*4.2 + u*0.45 + vVar*11.0, s*7.0 - ang/6.2832*2.0 + vVar*11.0, kK);
+  float fwf = mix(fwidth(fibP), fwidth(s*7.0), kK);
+  float body = 1.0 - smoothstep(1.0 - 1.1*fw, 1.0 + 1.1*fw, s);
+  float vis = lit*gone*smoothstep(0.0, 0.12, pull)*uOpacity*mix(1.0, uOutline, kB);
+  // cast self-shadow of this thread on the previous one (it lies on the +y side); symmetric and weaker for small stitches
+  float ds = max(s - 1.0, 0.0);
+  float skSide = mix(smoothstep(-0.15, 0.55, q.y/r), 0.5, clamp(kSym, 0.0, 1.0));
+  float aS = uRelief*mix(0.5, 0.26, clamp(kB + kT, 0.0, 1.0))*skSide*(1.0 - smoothstep(0.0, 0.7, ds))*(1.0 - body)*vis;
+  float aB = body*vis;
+  if (aB + aS < 0.003) discard;
+  float rl = 0.3 + 0.55*uRelief;
+  float hh = sqrt(max(1.0 - s*s, 0.0));
+  float aaP = 1.0 - smoothstep(0.2, 0.5, fwp);
+  float R = 0.5 + 0.5*cos(6.2832*ph);
+  vec3 n; vec3 Tf;
+  if (kK < 0.5) {
+    // thread: round pill with a slanted ply twist; fibres run along the axis rotated about the normal by the twist angle
+    n = vec3(q/r*rl*(0.35 + 0.9*s), max(hh, 0.06));
+    n.xy += vec2(0.60, 0.50)*sin(6.2832*ph)*0.16*hh*aaP*(0.3 + 0.5*uRelief);
+    n = normalize(n);
+    float al = 0.40 + 0.05*R + (vVar - 0.5)*0.12;
+    Tf = vec3(cos(al), sin(al)*n.z, -sin(al)*n.y); Tf = normalize(Tf - n*dot(Tf, n));
+  } else {
+    // French knot: a dome of thread wound in a spiral; the fibre runs round the coil, so the highlight is a crescent ring
+    vec2 rad = q/max(length(q), 1e-4);
+    n = vec3(rad*s*rl*(0.7 + 0.5*s), max(hh, 0.08));
+    n.xy += rad*sin(6.2832*ph)*0.30*aaP*hh*(0.3 + 0.6*uRelief);
+    n = normalize(n);
+    vec3 e = cross(n, vec3(rad, 0.0)); e = normalize(e + vec3(1e-4, 0.0, 0.0));
+    float al = 0.30 + 0.06*R + (vVar - 0.5)*0.12;
+    Tf = normalize(e*cos(al) + cross(n, e)*sin(al));
+  }
+  vec2 perp = vec2(-vDir.y, vDir.x);
+  vec3 L = normalize(vec3(dot(uL.xy, vDir), dot(uL.xy, perp), uL.z));
+  vec3 H = normalize(L + vec3(0.0, 0.0, 1.0));
+  float TH = dot(Tf, H); float sinTH = sqrt(max(1.0 - TH*TH, 0.0));
+  float TL = dot(Tf, L); float sinTL = sqrt(max(1.0 - TL*TL, 0.0));
+  float nl = max(dot(n, L), 0.0);
+  float diff = mix(nl, sinTL, 0.45);
+  float shadowL = smoothstep(-0.05, 0.3, dot(n, L));
+  // ambient occlusion: groove at the flanks, thread ends dive under the neighbours, ply grooves, the knot's dimple
+  float aoEdge = smoothstep(0.3, 1.0, s);
+  float aoEnd = clamp(max(abs(loc.x) - (hl - 1.2*r0), 0.0)/(1.6*r0), 0.0, 1.0)*(1.0 - kK);
+  float aoPly = (1.0 - R)*0.07*aaP;
+  float ao = clamp(1.0 - uRelief*(0.42*aoEdge + 0.4*aoEnd + aoPly + kK*0.5*exp(-s*s*38.0)), 0.0, 1.0);
+  vec3 alb = mix(uColor, uColor2, kC2)*(0.9 + 0.2*vVar);
+  float fpp = fract(ph); float groove = (1.0 - smoothstep(0.0, 0.11 + fwp, min(fpp, 1.0 - fpp)))*aaP;
+  alb *= (0.95 + 0.1*R*aaP)*(1.0 - 0.34*groove);
+  alb *= 1.0 - 0.16*(0.5 + 0.5*sin(6.2832*fibP))*(1.0 - smoothstep(0.25, 0.5, fwf));
+  vec3 col = alb*(0.07 + 0.66*diff*(0.3 + 0.7*shadowL))*ao;
+  vec3 sheenCol = mix(alb, vec3(1.0), 0.55);
+  float boost = 1.0 + 1.6*exp(-age/0.3)*step(0.5, 1.0 - uFadeIn);
+  float sp1 = pow(sinTH, 70.0)*(0.7 + 0.6*R*aaP + 0.3*(1.0 - aaP));
+  float sp2 = pow(sinTH, 9.0);
+  col += (sheenCol*sp1*1.15 + alb*1.3*sp2*0.55)*uSheen*boost*shadowL*(0.5 + 0.5*ao)*(1.0 + 0.5*lift);
+  // soft shoulder: sustained brightness stays below 1, thin peaks may reach it
+  float m = max(max(col.r, col.g), col.b);
+  if (m > 0.78) col *= (0.78 + 0.28*(1.0 - exp(-(m - 0.78)/0.28)))/m;
+  gl_FragColor = vec4(col*aB, aB + aS*(1.0 - aB));
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+// ---- GLSL: linen weave + pucker under the stitching (capsule field around the strokes) ---------------
+// The weave is displaced and lit by the baked wrinkle height field (R) and darkened by the large-scale stitch density (B);
+// it is lit by the same moving key light as the thread, so the gathers glint slowly. Fabric layer only.
+const FABRIC_FRAG = /* glsl */ `
+uniform vec3 uColor; uniform float uFabric; uniform float uOpacity; uniform float uPitch; uniform float uBase; uniform float uPucker; uniform vec3 uL;
+uniform sampler2D uPk; uniform vec2 uPkO; uniform vec2 uPkI; uniform vec2 uPkT; uniform float uPkC;
+float hh2(vec2 p){ return fract(sin(dot(p, vec2(41.7, 289.3)))*43758.5453); }
+void main(){
+  float dist = length(vec2(max(abs(vXY.x) - vHL, 0.0), vXY.y));
+  float s = dist/uBase;
+  vec2 uv = (vPos - uPkO)*uPkI;
+  vec3 tx = texture2D(uPk, uv).rgb;
+  float hx = texture2D(uPk, uv + vec2(uPkT.x, 0.0)).r - texture2D(uPk, uv - vec2(uPkT.x, 0.0)).r;
+  float hy = texture2D(uPk, uv + vec2(0.0, uPkT.y)).r - texture2D(uPk, uv - vec2(0.0, uPkT.y)).r;
+  vec2 grad = vec2(hx, hy)/uPkC;
+  float pk = uPucker;
+  vec2 p = (vPos + pk*0.0006*grad)/uPitch; vec2 fp = fwidth(p);
+  float lit = revealIn(0.5)*revealOut(0.5);
+  vec2 cell = floor(p); vec2 f = fract(p);
+  float chk = mod(cell.x + cell.y, 2.0);
+  float tx2 = sin(3.14159*f.x), ty = sin(3.14159*f.y);
+  float hgt = mix(ty, tx2, chk)*(0.86 + 0.28*hh2(cell));
+  float shade = 0.3 + 0.7*pow(clamp(hgt, 0.0, 1.0), 0.8);
+  float contrast = 1.0 - smoothstep(0.3, 0.7, max(fp.x, fp.y));
+  shade = mix(0.62, shade, contrast);
+  shade = mix(0.8, shade, clamp(uFabric*1.6, 0.0, 1.0));
+  vec3 nn = normalize(vec3(-pk*0.06*grad, 1.0));
+  float lam = clamp(dot(nn, uL)/max(uL.z, 0.25), 0.4, 1.6);
+  shade *= mix(1.0, lam, 0.8);
+  shade *= 1.0 - 0.5*pk*smoothstep(0.3, 0.85, tx.b);          // tight counters sit deeper in the gathered cloth
+  float fv = clamp(uFabric + 0.3*pk, 0.0, 1.0);
+  float mask = 1.0 - smoothstep(0.2, 0.9, s);
+  mask = max(mask, smoothstep(0.25, 0.6, tx.b)*pk*0.45);
+  vec3 lin = mix(vec3(0.62, 0.57, 0.48), uColor, 0.2);
+  vec3 col = lin*shade*fv*0.2*mask*lit*uOpacity;
+  gl_FragColor = vec4(col, 1.0);
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+// ---- needle + thread tail at the pen tip ---------------------------------------------------------
+const NEEDLE_VERT = /* glsl */ `
+attribute vec2 aq; attribute vec3 iPos; varying vec2 vP; varying float vA;
+void main(){ vec2 p = aq*0.24 + vec2(0.08, 0.08); vP = p; vA = iPos.z; gl_Position = projectionMatrix*modelViewMatrix*vec4(iPos.xy + p, 0.0, 1.0); }`;
+const NEEDLE_FRAG = /* glsl */ `
+precision highp float; uniform vec3 uColor; uniform float uTime; uniform float uOn;
+varying vec2 vP; varying float vA;
+float segd(vec2 p, vec2 a, vec2 b){ vec2 pa = p - a, ba = b - a; float h = clamp(dot(pa, ba)/dot(ba, ba), 0.0, 1.0); return length(pa - ba*h); }
+void main(){
+  vec2 nd = normalize(vec2(0.5, 0.86)); float NL = 0.15; vec2 perp = vec2(-nd.y, nd.x);
+  float aa = max(fwidth(vP.x), 0.0012);
+  float t = clamp(dot(vP, nd)/NL, 0.0, 1.0); vec2 ax = nd*NL*t;
+  float rad = mix(0.0013, 0.0042, smoothstep(0.0, 0.35, t));
+  float dn = length(vP - ax); float needle = 1.0 - smoothstep(rad - aa, rad + aa, dn);
+  float cs = dot(vP - ax, perp)/rad;
+  vec3 steel = vec3(0.62, 0.66, 0.72)*(0.55 + 0.45*(1.0 - abs(cs - 0.35)));
+  float gl = exp(-pow((t - fract(uTime*0.23))*7.0, 2.0)); steel += vec3(0.5)*gl*(1.0 - abs(cs));
+  float eye = 1.0 - smoothstep(0.0, 0.0018, abs(length(vP - nd*0.135 - perp*0.0) - 0.0) - 0.0);
+  vec2 E = nd*0.134; float th = 1.0e3; vec2 prev = E;
+  for (int i = 1; i <= 12; i++) { float u = float(i)/12.0;
+    vec2 cur = E + vec2(0.105*u, 0.045*u - 0.085*u*u + 0.010*u*sin(u*8.0 - uTime*2.0));
+    th = min(th, segd(vP, prev, cur)); prev = cur; }
+  float tr = 0.0024; float thread = (1.0 - smoothstep(tr - aa, tr + aa, th))*0.9;
+  vec3 tc = uColor*(0.8 + 0.3*(1.0 - smoothstep(0.0, tr, th))) + vec3(0.12);
+  float a = max(needle, thread)*vA*uOn;
+  vec3 col = mix(tc, steel, needle);
+  col = min(col, vec3(0.95));
+  gl_FragColor = vec4(col*a, a);
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+export default {
+    key: 'embroidery', source: 'hand',
+    drawMethods: ['stitch', ...DRAW_METHODS], eraseMethods: ['undraw', 'unpick', ...ERASE_METHODS.filter((m) => m !== 'undraw')],
+    drawDefault: 'stitch', eraseDefault: 'undraw',
+    methodInfo: {
+        stitch: { label: 'Stitch', hint: 'A needle pulls each satin stitch through, one after the other along the stroke' },
+        unpick: { label: 'Unpick', hint: 'Stitches are pulled out in reverse, lifting and thinning as they go' },
+    },
+    catalog: { name: 'Embroidery', description: 'Hand-embroidered lettering that picks satin, stem stitch, couching and French knots per stroke, with silk thread sheen under a moving light on puckered linen. Use for monograms, heritage brands and textile titles.', tags: ['embroidery', 'satin-stitch', 'thread', 'silk', 'textile', 'sewing', 'stitch'] },
+    defaults: { color: '#c92f48', color2: '#e8c47a', density: 44, slant: 66, thickness: 1.35, sheen: 1, relief: 1, outline: 0.65, fabric: 0.4, pucker: 0.6, style: 'auto', opacity: 1 },
+    ui: {
+        main: [
+            { name: 'color', label: 'Thread', description: 'Main satin thread colour', type: 'color' },
+            { name: 'sheen', label: 'Sheen', description: 'Strength of the silk highlight that sweeps over the stitching', type: 'number', min: 0, max: 2, step: 0.01 },
+            { name: 'density', label: 'Density', description: 'Stitches per em along the stroke', type: 'number', min: 14, max: 70, step: 1, unit: '/em' },
+            { name: 'thickness', label: 'Thickness', description: 'Width of the satin column relative to the pen stroke', type: 'number', min: 0.6, max: 2.4, step: 0.01 },
+        ],
+        more: [
+            { name: 'color2', label: 'Contrast thread', description: 'Border running-stitch thread', type: 'color' },
+            { name: 'relief', label: 'Relief', description: 'Raised look: thread height, groove shadows and stitch ends diving under neighbours', type: 'number', min: 0, max: 1.5, step: 0.01 },
+            { name: 'outline', label: 'Border row', description: 'Visibility of the contrast running-stitch border', type: 'number', min: 0, max: 1, step: 0.01 },
+            { name: 'fabric', label: 'Fabric', description: 'Faint linen weave behind the stitching', type: 'number', min: 0, max: 1, step: 0.01 },
+            { name: 'pucker', label: 'Pucker', description: 'Dense stitching gathers the cloth: soft wrinkles around the stitching, deeper tight counters (fabric layer only)', type: 'number', min: 0, max: 1, step: 0.01 },
+            { name: 'style', label: 'Stitch style', description: 'Automatic picks per stroke: satin, stem stitch, couching, French knots. Or force one', type: 'select', options: ['auto', 'satin', 'stem', 'couching'], optionLabels: ['Automatic', 'Satin', 'Stem', 'Couching'] },
+            { name: 'slant', label: 'Slant', description: 'Satin stitch angle to the stroke direction', type: 'number', min: 40, max: 85, step: 1, unit: '°' },
+            { name: 'opacity', label: 'Opacity', description: 'Overall opacity', type: 'number', min: 0, max: 1, step: 0.01 },
+        ],
+    },
+    structural: ['density', 'slant', 'thickness', 'style'],
+    presets: [
+        { name: 'Crimson silk', description: 'Red satin with a gold running-stitch border', patch: {} },
+        { name: 'Ivory & gold', description: 'Cream thread, gold border, glossy', patch: { color: '#eadfc6', color2: '#d4a24a', sheen: 1.2, fabric: 0.3 } },
+        { name: 'Indigo on linen', description: 'Blue thread on a visible linen weave', patch: { color: '#4766e0', color2: '#d9defa', sheen: 0.8, fabric: 0.85, outline: 0.5, pucker: 0.9 } },
+        { name: 'Matte cotton', description: 'Soft, low-sheen floss with strong relief', patch: { color: '#e4cfae', color2: '#b9553f', sheen: 0.25, relief: 1.3, fabric: 0.55, outline: 0.8, pucker: 0.8 } },
+        { name: 'Emerald satin', description: 'Deep green, high gloss, bold border', patch: { color: '#14a66f', color2: '#f2d27a', sheen: 1.6, outline: 0.95, fabric: 0.2, pucker: 0.4 } },
+    ],
+    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); });
+        const a2 = { ...anim, draw: { ...anim.draw, method: anim.draw.method === 'stitch' ? 'pen' : anim.draw.method }, erase: { ...anim.erase, method: anim.erase.method === 'unpick' ? 'undraw' : anim.erase.method } };
+        const { infoD: iD0, infoE: iE0 } = applyAnim(strokes, a2, G);
+        const infoD = { ...iD0, tip: iD0.tip && !iD0.fade };
+        const infoE = { ...iE0 };
+        if (!infoE.fade)
+            infoE.soft = Math.max(infoE.soft, 0.03); // threads leave over a short window, never pop
+        const natural = layout.natural || 0.05;
+        const rows = genStitches(strokes, natural, cfg.density, cfg.slant, cfg.thickness, STYLES.indexOf(cfg.style));
+        const geo = buildStitchGeometry(rows);
+        const mat = new THREE.ShaderMaterial({
+            uniforms: { ...uniformsBase(), uColor: { value: hex(cfg.color) }, uColor2: { value: hex(cfg.color2) }, uOpacity: { value: 1 }, uSheen: { value: 1 }, uRelief: { value: 1 }, uOutline: { value: 1 }, uL: { value: new THREE.Vector3(0, 0, 1) } },
+            vertexShader: STITCH_VERT, fragmentShader: frag(STITCH_FRAG, 'varying vec2 vXY; varying vec4 vGeo; varying vec2 vDir;\n'),
+            transparent: true, depthWrite: false, side: THREE.DoubleSide,
+            blending: THREE.CustomBlending, blendEquation: THREE.AddEquation, blendSrc: THREE.OneFactor, blendDst: THREE.OneMinusSrcAlphaFactor,
+        });
+        const mesh = new THREE.Mesh(geo, mat);
+        mesh.frustumCulled = false;
+        mesh.renderOrder = 1;
+        // fabric: capsule field around the strokes
+        const fgeo = buildCapsules(strokes);
+        const pk = bakePucker(strokes, rows, natural, cfg.thickness);
+        const fBase = natural * cfg.thickness * 0.6 + 0.05;
+        const fmat = capsuleMaterial(FABRIC_FRAG, { uColor: { value: hex(cfg.color) }, uFabric: { value: cfg.fabric }, uOpacity: { value: 1 }, uPitch: { value: 0.022 }, uBase: { value: fBase }, uPucker: { value: cfg.pucker }, uL: { value: new THREE.Vector3(0, 0, 1) },
+            uPk: { value: pk.tex }, uPkO: { value: new THREE.Vector2(pk.ox, pk.oy) }, uPkI: { value: new THREE.Vector2(1 / pk.w, 1 / pk.h) }, uPkT: { value: new THREE.Vector2(1 / pk.nx, 1 / pk.ny) }, uPkC: { value: pk.cell } });
+        fmat.uniforms.uHalf.value = fBase + 0.07 * cfg.pucker;
+        const fab = new THREE.Mesh(fgeo, fmat);
+        fab.frustumCulled = false;
+        fab.renderOrder = 0;
+        // needle pool
+        const NP = 8;
+        const ng = new THREE.InstancedBufferGeometry();
+        ng.setAttribute('aq', new THREE.BufferAttribute(new Float32Array([-1, -1, 1, -1, 1, 1, -1, 1]), 2));
+        ng.setIndex([0, 1, 2, 0, 2, 3]);
+        const iPos = new THREE.InstancedBufferAttribute(new Float32Array(NP * 3), 3);
+        iPos.setUsage(THREE.DynamicDrawUsage);
+        ng.setAttribute('iPos', iPos);
+        ng.instanceCount = 0;
+        ng.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e3);
+        const nmat = new THREE.ShaderMaterial({ uniforms: { uColor: { value: hex(cfg.color) }, uTime: { value: 0 }, uOn: { value: 1 } }, vertexShader: NEEDLE_VERT, fragmentShader: NEEDLE_FRAG, transparent: true, depthWrite: false, side: THREE.DoubleSide, blending: THREE.CustomBlending, blendEquation: THREE.AddEquation, blendSrc: THREE.OneFactor, blendDst: THREE.OneMinusSrcAlphaFactor });
+        const needle = new THREE.Mesh(ng, nmat);
+        needle.frustumCulled = false;
+        needle.renderOrder = 2;
+        const group = new THREE.Group();
+        group.add(fab, mesh, needle);
+        const api = {
+            object: group,
+            apply(c) {
+                const u = mat.uniforms;
+                u.uColor.value.set(c.color);
+                u.uColor2.value.set(c.color2);
+                u.uOpacity.value = c.opacity;
+                u.uSheen.value = c.sheen;
+                u.uRelief.value = c.relief;
+                u.uOutline.value = c.outline;
+                fmat.uniforms.uColor.value.set(c.color);
+                fmat.uniforms.uFabric.value = c.fabric;
+                fmat.uniforms.uOpacity.value = c.opacity;
+                fmat.uniforms.uPucker.value = c.pucker;
+                fmat.uniforms.uHalf.value = fBase + 0.07 * c.pucker;
+                nmat.uniforms.uColor.value.set(c.color);
+                nmat.uniforms.uOn.value = c.opacity;
+                api.c = c;
+            },
+            update(S, time, px) {
+                setReveal(mat.uniforms, S, infoD, infoE, anim.draw.duration, time);
+                setReveal(fmat.uniforms, S, infoD, infoE, anim.draw.duration, time);
+                lightAt(time, mat.uniforms.uL.value);
+                fmat.uniforms.uL.value.copy(mat.uniforms.uL.value);
+                nmat.uniforms.uTime.value = time;
+                let k = 0;
+                if (infoD.tip && S.d > 0 && S.d < 1 && S.e <= 0) {
+                    const head = mat.uniforms.uHead.value;
+                    for (const s of strokes) {
+                        if (k >= NP)
+                            break;
+                        const p = headPoint(s, head);
+                        if (!p)
+                            continue;
+                        const u = (head - s.seg[0]) / Math.max(1e-6, s.seg[1] - s.seg[0]);
+                        iPos.setXYZ(k++, p[0], p[1], Math.min(1, u / 0.04, (1 - u) / 0.04));
+                    }
+                }
+                ng.instanceCount = k;
+                if (k)
+                    iPos.needsUpdate = true;
+            },
+            dispose() { geo.dispose(); mat.dispose(); fgeo.dispose(); fmat.dispose(); pk.tex.dispose(); ng.dispose(); nmat.dispose(); },
+        };
+        api.apply(cfg);
+        api.count = rows.length;
+        api.kinds = [0, 1, 2, 3].map((k) => rows.filter((r) => r[6] === k).length);
+        return api;
+    },
+};