@3driseai/3drise-viewer 0.1.27 → 0.1.29

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

@@ -0,0 +1,590 @@
+import * as THREE from 'three';
+import { prepare, applyAnim, DRAW_METHODS, ERASE_METHODS } from '../methods.js';
+import { buildField, fieldMaterial, fieldQuad } from '../fieldkit.js';
+import { setReveal, REVEAL_UNIFORMS } from '../ribbon.js';
+// =========================================================================================
+// inkBleed — fountain-pen ink soaking into absorbent paper (single-stroke pen paths, per-pixel field).
+//
+// THE MATHS (what is modelled):
+//  1. Capillary wicking (Washburn / diffusion): the wetting front around a pen stroke advances as r(age) = bleed * tanh(1.25*sqrt(age/T)):
+//     sqrt(age) growth at first (fast), saturating at `bleed` once the paper has drunk what it can. `age` = seconds since the pen
+//     passed that very pixel (ageG), so the feather visibly grows behind the pen.
+//  2. The paper is a fixed procedural fibre network (jittered cells, each with fibres of random orientation, length and strength)
+//     plus a low-frequency "formation" cloud (mass density of the sheet). Ink wicks further where fibres are dense: the front is
+//     r_eff = r(age) * (1 + fibre * noise) (ragged contour) and each fibre carries ink out to ~2.4 r along its own axis (feathering).
+//  3. Ink density across the line is the diffusion kernel: D = core(pen half-width, widened by pressure wf) + H*exp(-(d/r_eff)^2)
+//     (+ the fibre wicks). Slow pen = more pressure = wider, denser, wetter.
+//  4. Coffee ring: as the ink dries (1 - exp(-age/T)) solute is carried to the contact line, so a darker rim forms at the edge
+//     of the pen line and at the feather front; strength = pooling * dryness.
+//  5. Colour is dye TRANSMISSION, not a flat colour: T = exp(-(k1*D1 + k2*D2)), k = -ln(colour) per channel (Beer-Lambert),
+//     so thin ink = lighter, same hue; and chromatography: the second dye (colour2) is the lighter, faster-wicking component, it
+//     travels further (r*1.55) so a brown/teal fringe separates from the dark core. Paper colour * T = what the eye sees.
+//  6. Iron-gall oxidation: ink is written pale blue-grey and darkens (ox = 1-exp(-age*rate(density)/tau), smoothstepped) to its final dye; denser ink oxidises
+//     faster, so the front runs from the core outwards. Slowly, ink acid browns the paper (same sqrt diffusion law, wider, stronger under pressure) + a faint verso ghost.
+//  7. Burn (look-native erase, default): the whole deckled sheet burns with the ink on it. Combustion is a front with arrival time T(p) solving the eikonal
+//     equation |grad T| = 1/v(p), solved for real at build (multi-source Dijkstra on a 384-wide grid of the sheet) from a few seeded ignition points; the fire
+//     runs ~1.7x faster along the iron-gall lines (corrosive ink: letters char first). In the shader T is warped by fbm (uneven local speed) and the front is
+//     ragged. Erase progress S.e drives it: pixel p ignites at e = (1-L)*T'(p) and lives for a lifecycle L, so everything is gone by S.e = 1. By age behind the
+//     front: ember line (blackbody 1750 K -> 900 K, I ~ T^4) -> cracked char (Voronoi F2-F1, glowing in the cracks) -> ash -> gone (alpha eaten, edges first);
+//     the ink survives as a fragile ash lace of the letters that collapses just before the end. Paper curl shading at the front, rising sparks (closed form).
+//  8. Idle: a soft light drifting over the sheet (specular sheen weighted by the fibre relief) and the slow creep of drying.
+// =========================================================================================
+const BURN_COMMON = /* glsl */ `
+uniform sampler2D uArr; uniform vec4 uArrExt; uniform float uL; uniform float uV; uniform float uRough; uniform vec2 uSeedV; uniform float uFire;
+float bh(vec2 p){ vec3 p3 = fract(vec3(p.xyx)*0.1031); p3 += dot(p3, p3.yzx + 33.33); return fract((p3.x + p3.y)*p3.z); }
+float vnz(vec2 p){ vec2 i = floor(p); vec2 f = fract(p); f = f*f*(3.0 - 2.0*f);
+  return mix(mix(bh(i), bh(i + vec2(1.0, 0.0)), f.x), mix(bh(i + vec2(0.0, 1.0)), bh(i + vec2(1.0, 1.0)), f.x), f.y); }
+float fbm4(vec2 p){ float a = 0.5; float s = 0.0; for (int i = 0; i < 4; i++){ s += a*vnz(p); p = p*2.03 + vec2(17.1, 9.7); a *= 0.5; } return s/0.9375; }
+vec3 S(vec3 c){ return pow(c, vec3(2.2)); }
+// ember colour from temperature (orange blackbody ramp): cooler = deeper and redder, hotter = paler and more yellow-white; radiance ~ T^4
+vec3 ember(float T){ vec3 b = vec3(1.0, 0.48, 0.11); float h = smoothstep(900.0, 1800.0, T); return pow(b, vec3(mix(1.7, 0.45, h))); }
+float irad(float T){ return pow(T/1500.0, 4.0); }
+// arrival of the front at p in erase-progress units (0 .. 1-L); the eikonal arrival is warped by low-frequency fbm = uneven local speed
+float burnArr(vec2 p){
+  float A = texture2D(uArr, (p - uArrExt.xy)/uArrExt.zw).r;
+  float amp = 0.34*uRough; float n = fbm4(p*1.5 + uSeedV);
+  float w = (1.0 + amp*1.5*(2.0*n - 1.0))/(1.0 + amp*1.5);
+  return (1.0 - uL)*clamp(A*w, 0.0, 1.0);
+}
+`;
+const SPARK_VERT = /* glsl */ `
+${REVEAL_UNIFORMS}${BURN_COMMON}
+attribute vec4 aR;
+uniform float uScale; uniform float uSize;
+varying float vA; varying vec3 vCol;
+void main(){
+  vec2 pos = position.xy; float a = 0.0; float T = 1300.0; float sz = 1.0;
+  float arr = burnArr(position.xy);
+  float life = uL*(0.3 + 0.55*aR.x);
+  float k = (uE - arr)/life;
+  if (uFire > 0.5 && k > 0.0 && k < 1.0){
+    float e = 1.0 - pow(1.0 - k, 1.7);
+    pos.y += 0.012 + (0.14 + 0.26*aR.y)*e;
+    pos.x += (aR.z - 0.5)*0.10*e + 0.025*sin(k*5.0 + aR.w*6.28)*e;
+    a = smoothstep(0.0, 0.06, k)*(1.0 - smoothstep(0.45, 1.0, k))*(0.5 + 0.5*aR.w);
+    T = mix(1700.0, 950.0, k); sz = 0.7 + 0.6*aR.x;
+  }
+  a *= 0.75 + 0.25*sin(uTime*(3.0 + 4.0*aR.w) + aR.z*30.0);
+  vA = a; vCol = ember(T)*irad(T)*1.1;
+  vec4 mv = modelViewMatrix*vec4(pos, 0.001, 1.0); gl_Position = projectionMatrix*mv;
+  gl_PointSize = a > 0.001 ? max(2.0, sz*uSize*uScale/-mv.z) : 0.0;
+}`;
+const SPARK_FRAG = /* glsl */ `
+precision highp float; varying float vA; varying vec3 vCol;
+void main(){ vec2 p = gl_PointCoord*2.0 - 1.0; float r = length(p);
+  float core = 1.0 - smoothstep(0.0, 0.32, r); float halo = pow(max(1.0 - r, 0.0), 2.6)*0.5;
+  float a = (core*0.95 + halo)*vA; if (a < 0.004) discard;
+  vec3 c = vCol*a; c /= max(1.0, max(c.r, max(c.g, c.b)));
+  gl_FragColor = vec4(c, 1.0);
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+// ---- CPU: eikonal solve on the sheet (multi-source Dijkstra, 16-neighbour stencil) ----------------------------------------------
+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; }; }
+function burnMap(strokes, field) {
+    const ex = field.ext, ew = ex.z, eh = ex.w;
+    const W = 384, H = Math.max(8, Math.round(W * eh / ew)), sx = ew / W, sy = eh / H, N = W * H;
+    const rng = mulberry32(7 * 7919 + 13);
+    // sheet mask: the same rounded rectangle as paperSD in the shader (without the deckle noise)
+    const cx0 = ex.x + ew / 2, cy0 = ex.y + eh / 2, hx = ew / 2 - 0.125, hy = eh / 2 - 0.125;
+    const sheet = new Uint8Array(N);
+    for (let y = 0; y < H; y++)
+        for (let x = 0; x < W; x++) {
+            const dx = Math.abs(ex.x + (x + 0.5) * sx - cx0) - hx, dy = Math.abs(ex.y + (y + 0.5) * sy - cy0) - hy;
+            sheet[y * W + x] = (Math.hypot(Math.max(dx, 0), Math.max(dy, 0)) + Math.min(Math.max(dx, dy), 0) - 0.05) < 0 ? 1 : 0;
+        }
+    // the ink: strokes rasterised with a pen-wide line; fire runs faster along it (iron-gall ink is corrosive)
+    const cv = document.createElement('canvas');
+    cv.width = W;
+    cv.height = H;
+    const g = cv.getContext('2d', { willReadFrequently: true });
+    g.fillStyle = '#000';
+    g.fillRect(0, 0, W, H);
+    g.strokeStyle = '#fff';
+    g.lineCap = 'round';
+    g.lineJoin = 'round';
+    g.lineWidth = Math.max(1.5, 0.14 / sx);
+    for (const s of strokes) {
+        g.beginPath();
+        for (let i = 0; i < s.pts.length; i += 2) {
+            const X = (s.pts[i] - ex.x) / sx, Y = H - (s.pts[i + 1] - ex.y) / sy;
+            if (i === 0)
+                g.moveTo(X, Y);
+            else
+                g.lineTo(X, Y);
+        }
+        g.stroke();
+    }
+    const im = g.getImageData(0, 0, W, H).data;
+    const speed = new Float32Array(N);
+    for (let y = 0; y < H; y++)
+        for (let x = 0; x < W; x++)
+            speed[y * W + x] = 1 + 0.7 * (im[((H - 1 - y) * W + x) * 4] / 255);
+    // ignition: two seeded points on the sheet rim and one on the writing (lit a little later)
+    const cellAt = (X, Y) => { const ix = Math.max(0, Math.min(W - 1, Math.floor((X - ex.x) / sx))), iy = Math.max(0, Math.min(H - 1, Math.floor((Y - ex.y) / sy))); return iy * W + ix; };
+    const nearestSheet = (c) => { let best = -1, bd = 1e30; const X = c % W, Y = (c / W) | 0; for (let p = 0; p < N; p++)
+        if (sheet[p]) {
+            const d2 = ((p % W) - X) ** 2 + (((p / W) | 0) - Y) ** 2;
+            if (d2 < bd) {
+                bd = d2;
+                best = p;
+            }
+        } return best; };
+    const rimCells = [];
+    for (let y = 0; y < H; y++)
+        for (let x = 0; x < W; x++) {
+            const p = y * W + x;
+            if (!sheet[p])
+                continue;
+            const edge = x === 0 || y === 0 || x === W - 1 || y === H - 1 || !sheet[p - 1] || !sheet[p + 1] || !sheet[p - W] || !sheet[p + W];
+            if (edge)
+                rimCells.push(p);
+        }
+    const src = []; // [cell, delay]
+    for (let k = 0; k < 2 && rimCells.length; k++)
+        src.push([rimCells[Math.floor(rng() * rimCells.length) % rimCells.length], 0]);
+    const cands = [];
+    strokes.forEach((s) => { const n = s.pts.length / 2; for (let i = 0; i < n; i++)
+        cands.push([s.pts[2 * i], s.pts[2 * i + 1]]); });
+    if (cands.length) {
+        const c = cands[Math.floor(rng() * cands.length) % cands.length];
+        const cell = cellAt(c[0], c[1]);
+        src.push([sheet[cell] ? cell : nearestSheet(cell), 0.45]);
+    }
+    const dist = new Float64Array(N).fill(1e30);
+    let hk = new Float64Array(1024), hv = new Int32Array(1024), hn = 0;
+    const push = (k, v) => { if (hn === hk.length) {
+        const a = new Float64Array(hn * 2), b = new Int32Array(hn * 2);
+        a.set(hk);
+        b.set(hv);
+        hk = a;
+        hv = b;
+    } let i = hn++; while (i > 0) {
+        const p = (i - 1) >> 1;
+        if (hk[p] <= k)
+            break;
+        hk[i] = hk[p];
+        hv[i] = hv[p];
+        i = p;
+    } hk[i] = k; hv[i] = v; };
+    const pop = () => { const rk = hk[0], rv = hv[0]; const k = hk[--hn], v = hv[hn]; let i = 0; for (;;) {
+        let c = 2 * i + 1;
+        if (c >= hn)
+            break;
+        if (c + 1 < hn && hk[c + 1] < hk[c])
+            c++;
+        if (hk[c] >= k)
+            break;
+        hk[i] = hk[c];
+        hv[i] = hv[c];
+        i = c;
+    } hk[i] = k; hv[i] = v; return [rk, rv]; };
+    for (const [c, dl] of src)
+        if (c >= 0) {
+            dist[c] = Math.min(dist[c], dl);
+            push(dl, c);
+        }
+    const NB = [[1, 0], [-1, 0], [0, 1], [0, -1], [1, 1], [1, -1], [-1, 1], [-1, -1], [2, 1], [2, -1], [-2, 1], [-2, -1], [1, 2], [1, -2], [-1, 2], [-1, -2]];
+    const NL = NB.map(([a, b]) => Math.hypot(a * sx, b * sy));
+    while (hn > 0) {
+        const [dk, c] = pop();
+        if (dk > dist[c])
+            continue;
+        const cx = c % W, cy = (c / W) | 0;
+        for (let j = 0; j < 16; j++) {
+            const xx = cx + NB[j][0], yy = cy + NB[j][1];
+            if (xx < 0 || yy < 0 || xx >= W || yy >= H)
+                continue;
+            const q = yy * W + xx;
+            if (!sheet[q])
+                continue;
+            const nd = dk + NL[j] / (0.5 * (speed[c] + speed[q]));
+            if (nd < dist[q]) {
+                dist[q] = nd;
+                push(nd, q);
+            }
+        }
+    }
+    let Tmax = 1e-3;
+    for (let p = 0; p < N; p++)
+        if (sheet[p] && dist[p] < 1e29)
+            Tmax = Math.max(Tmax, dist[p]);
+    // steady pace: blend T with its cdf over the sheet area (monotone, topology unchanged)
+    const ord = [];
+    for (let p = 0; p < N; p++)
+        if (sheet[p] && dist[p] < 1e29)
+            ord.push(p);
+    ord.sort((a, b) => dist[a] - dist[b]);
+    const EQ = 0.45;
+    const A = new Float32Array(N).fill(1);
+    const set = new Uint8Array(N);
+    ord.forEach((p, i) => { A[p] = ((1 - EQ) * dist[p] / Tmax + EQ * i / Math.max(1, ord.length - 1)); set[p] = 1; });
+    // dilate the arrival outwards so the deckle, the shadow and the light spilling over the edge have a front too
+    for (let r = 0; r < 9; r++) {
+        const nA = A.slice(), nS = set.slice();
+        for (let y = 0; y < H; y++)
+            for (let x = 0; x < W; x++) {
+                const p = y * W + x;
+                if (set[p])
+                    continue;
+                let m = 2, f = 0;
+                for (let dy = -1; dy <= 1; dy++)
+                    for (let dx = -1; dx <= 1; dx++) {
+                        const xx = x + dx, yy = y + dy;
+                        if (xx < 0 || yy < 0 || xx >= W || yy >= H)
+                            continue;
+                        const q = yy * W + xx;
+                        if (set[q] && A[q] < m) {
+                            m = A[q];
+                            f = 1;
+                        }
+                    }
+                if (f) {
+                    nA[p] = m;
+                    nS[p] = 1;
+                }
+            }
+        A.set(nA);
+        set.set(nS);
+    }
+    const hf = THREE.DataUtils.toHalfFloat;
+    const data = new Uint16Array(N * 4);
+    const one = hf(1);
+    for (let p = 0; p < N; p++) {
+        data[4 * p] = hf(A[p]);
+        data[4 * p + 1] = 0;
+        data[4 * p + 2] = 0;
+        data[4 * p + 3] = one;
+    }
+    const tex = new THREE.DataTexture(data, W, H, THREE.RGBAFormat, THREE.HalfFloatType);
+    tex.minFilter = tex.magFilter = THREE.LinearFilter;
+    tex.wrapS = tex.wrapT = THREE.ClampToEdgeWrapping;
+    tex.generateMipmaps = false;
+    tex.needsUpdate = true;
+    // spark seeds stratified over the burn order: a spark is born every so often along the whole fire
+    const seeds = [];
+    const NB2 = 56;
+    if (ord.length)
+        for (let i = 0; i < NB2; i++) {
+            const c = ord[Math.min(ord.length - 1, Math.floor(((i + rng()) / NB2) * ord.length))];
+            seeds.push({ x: ex.x + ((c % W) + rng()) * sx, y: ex.y + (((c / W) | 0) + rng()) * sy, r: [rng(), rng(), rng(), rng()] });
+        }
+    return { tex, Tmax, seeds };
+}
+function sparkGeometry(map) {
+    const n = map.seeds.length;
+    const pos = new Float32Array(n * 3), aR = new Float32Array(n * 4);
+    map.seeds.forEach((s, i) => { pos[3 * i] = s.x; pos[3 * i + 1] = s.y; aR.set(s.r, 4 * i); });
+    const g = new THREE.BufferGeometry();
+    g.setAttribute('position', new THREE.BufferAttribute(pos, 3));
+    g.setAttribute('aR', new THREE.BufferAttribute(aR, 4));
+    g.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e3);
+    return g;
+}
+const FRAG = /* glsl */ `
+uniform vec3 uColor; uniform vec3 uColor2; uniform float uBleed; uniform float uDry; uniform float uFibre; uniform float uPool;
+uniform float uWeight; uniform float uPaper; uniform float uOpacity; uniform float uPen; uniform float uTexel; uniform float uOx; uniform float uBurn; uniform float uChar;
+
+vec2 h22(vec2 p){ return vec2(h21(p), h21(p + vec2(17.3, 9.1))); }
+float vnoise(vec2 p){ vec2 i = floor(p), 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); }
+
+// fibre network: two fibres per jittered cell, random orientation / length / strength, tapered ends. 18 segment evaluations.
+float fibres(vec2 p, float cell, float w, float seed){
+  vec2 ic = floor(p/cell); float best = 0.0;
+  for (int j = -1; j <= 1; j++) for (int i = -1; i <= 1; i++) {
+    vec2 c = ic + vec2(float(i), float(j));
+    for (int k = 0; k < 2; k++) {
+      vec2 s = c + vec2(float(k)*7.7 + seed, float(k)*3.1);
+      vec2 ctr = (c + h22(s))*cell;
+      float ang = h21(s + 3.3)*3.14159265;
+      float hl = (0.5 + 0.7*h21(s + 8.1))*cell;
+      vec2 dir = vec2(cos(ang), sin(ang)); vec2 pa = p - ctr;
+      float t = dot(pa, dir); float d = abs(pa.x*dir.y - pa.y*dir.x);
+      float str = (0.4 + 0.6*h21(s + 5.5))*(1.0 - smoothstep(0.55, 1.0, abs(t)/hl));
+      best = max(best, str*exp(-(d*d)/(w*w)));
+    }
+  }
+  return best;
+}
+vec3 vor(vec2 p){ vec2 n = floor(p); vec2 f = fract(p); float F1 = 8.0; float F2 = 8.0; float id = 0.0;
+  for (int j = -1; j <= 1; j++) for (int i = -1; i <= 1; i++){
+    vec2 g = vec2(float(i), float(j)); vec2 c = n + g;
+    vec2 o = vec2(bh(c), bh(c + vec2(31.7, 17.3)));
+    float d = length(g + o - f);
+    if (d < F1){ F2 = F1; F1 = d; id = bh(c + vec2(5.1, 9.2)); } else if (d < F2) F2 = d;
+  } return vec3(F1, F2 - F1, id); }
+float tanhs(float x){ float e = exp(-2.0*min(x, 12.0)); return (1.0 - e)/(1.0 + e); }
+// deckled sheet: rounded rectangle inside the field extent + torn-edge noise. > 0 inside.
+float paperSD(vec2 q){
+  vec2 c = uFExt.xy + 0.5*uFExt.zw; vec2 hh = 0.5*uFExt.zw - 0.075 - 0.05; vec2 dd = abs(q - c) - hh;
+  float sd = -(length(max(dd, 0.0)) + min(max(dd.x, dd.y), 0.0) - 0.05);
+  return sd + (vnoise(q*19.0) - 0.5)*0.034 + (vnoise(q*53.0) - 0.5)*0.014;
+}
+
+void main(){
+  vec2 p = vPos;
+  float px = max(fwidth(p.x), 1e-4);                         // em per screen pixel
+  vec4 A = fieldA(p); vec4 B = fieldB(p);
+  float d = max(A.x, 0.0); float wf = clamp(B.y, 0.35, 1.8);
+  float T0 = max(uDry, 0.05);
+  float rpen = 0.5*uPen*uWeight*(0.55 + 0.45*wf);              // pressure widens the line
+  // round pen tip: pixels within the nib radius of the pen are inked even when their nearest centreline point is still ahead of it
+  float ee = 5.0*uTexel;
+  vec2 gr = vec2(fieldA(p + vec2(ee, 0.0)).y - fieldA(p - vec2(ee, 0.0)).y, fieldA(p + vec2(0.0, ee)).y - fieldA(p - vec2(0.0, ee)).y)/(2.0*ee);
+  float gm = min(length(gr), 0.5);
+  float gEff = A.y - gm*sqrt(max(rpen*rpen - d*d, 0.0));
+  float vis = revealInG(gEff)*(uFire > 0.5 ? 1.0 : revealOutG(A.z));               // ink presence (draw front, erase front)
+  float age = ageG(A.y);
+
+  // ---- sheet presence: appears as the pen starts, leaves with the last of the ink ----
+  float pres = smoothstep(0.0, 0.05, uD)*(uFire > 0.5 ? 1.0 : 1.0 - smoothstep(0.78, 1.0, uE));
+  float sd = paperSD(p);
+  float mask = smoothstep(-px, px*1.5, sd);
+  float shd = smoothstep(-0.05, 0.0, paperSD(p - vec2(0.012, -0.02)))*0.34;
+
+  // ---- paper: fibre relief + formation ----
+  float wfib = max(0.0068, 0.8*px);
+  float Fv = fibres(p, 0.085, wfib, 0.0);
+  float Q = 0.6*vnoise(p*11.0 + vec2(3.7, 1.3)) + 0.4*vnoise(p*27.0 + vec2(5.1, 8.2));
+  float Q2 = 0.65*vnoise(p*38.0 + vec2(9.0, 2.0)) + 0.35*vnoise(p*61.0 + vec2(1.0, 6.0));
+  float grain = vnoise(p*210.0);
+  vec3 paperCol = vec3(0.74, 0.675, 0.52);
+  vec3 paperLit = paperCol*(1.0 + 0.10*(Q - 0.5) + 0.05*(grain - 0.5) + uFibre*0.05*(Fv - 0.3));
+  // constant state: a soft light drifting over the sheet (specular on the fibre relief; the paper itself never moves)
+  float ti = uTime*0.11*uIdleSpeed*uIdle;
+  vec2 lp = uFExt.xy + uFExt.zw*vec2(0.5 + 0.42*sin(ti), 0.5 + 0.30*sin(ti*0.63 + 1.0));
+  vec2 dl = (p - lp)/vec2(1.6, 1.0);
+  float spot = exp(-dot(dl, dl)/(0.55*uFExt.w*uFExt.w + 0.5));
+  paperLit += vec3(0.95, 0.9, 0.78)*spot*(0.25 + 0.75*Fv + 0.35*grain)*0.12*uIdle;
+  // paper browning ("ink burn"): the acid of the ink diffuses into the sheet with the same sqrt law as the bleed, only slower and wider,
+  // and is strongest beside heavy pen pressure. It stays in the paper when the ink is later erased.
+  float visIn = revealInG(A.y);
+  float Tb = 4.0*max(uDry, 0.05) + 3.0;
+  float gb = tanhs(1.25*sqrt(age/Tb));
+  float rBur = (0.05 + 1.6*uBleed)*(0.7 + 0.3*wf)*max(0.35, 1.0 + 0.5*uFibre*(Q - 0.5));
+  float pw = pow(clamp(wf, 0.4, 1.8), 1.5);
+  float burn = uBurn*gb*(0.75 + 0.25*(1.0 - exp(-age/60.0)))*visIn*pw*(0.5*exp(-(d*d)/(rBur*rBur + 1e-6)) + 0.35*exp(-(d*d)/(0.12*rBur*rBur + 1e-6)));
+  // faint show-through of the ink from the verso: a soft, slightly offset greyish-brown imprint of the line
+  float dg = max(fieldA(p + vec2(0.006, -0.009)).x, 0.0);
+  float ghost = uBurn*gb*visIn*0.5*exp(-(dg*dg)/(6.0*rpen*rpen + 1e-6));
+  paperLit *= mix(vec3(1.0), vec3(0.74, 0.55, 0.34), clamp(burn, 0.0, 0.85));
+  paperLit *= mix(vec3(1.0), vec3(0.66, 0.62, 0.6), clamp(ghost*0.28, 0.0, 0.3));
+
+  // ---- ink: wicking front, diffusion kernel, fibre wicks ----
+  float x = 1.25*sqrt(age/T0); float grow = tanhs(x);
+  float wet = exp(-age/(0.9*T0)); float dry = 1.0 - exp(-age/(1.7*T0));
+  float dryL = 0.82*dry + 0.18*(1.0 - exp(-age/40.0));        // residual slow drying keeps raising the rim contrast
+  float rb = uBleed*grow*(0.6 + 0.4*wf);
+  float rag = max(0.3, 1.0 + uFibre*(1.5*(Q - 0.5) + 0.7*(Q2 - 0.5)));
+  float rE = rb*rag;
+  float aa = px*0.9;
+
+  float soft = (mix(0.05, 0.2, grow)*rpen + aa);
+  float core = 1.0 - smoothstep(rpen - soft*0.5, rpen + soft, d);
+  float haloK = exp(-(d*d)/(rE*rE + 1e-6));
+  float wick = uFibre*Fv*Fv*smoothstep(0.25, 0.8, Q + 0.25*(Q2 - 0.5))*exp(-(d*d)/(rb*rb*3.2 + 1e-6));   // fibres in dense paper carry ink ~1.8 r outwards
+  float D1 = (0.98 + 0.28*(wf - 0.9))*core*(1.0 + 0.2*wet)
+           + 0.3*(0.6 + 0.4*wf)*grow*haloK
+           + 0.26*wick*grow;
+  float rE2 = rE*1.4 + 0.003*grow;
+  float D2 = 0.55*grow*exp(-(d*d)/(rE2*rE2 + 1e-6))*(0.85 + 0.9*(Q - 0.5))
+           + 0.35*uFibre*Fv*Fv*exp(-(d*d)/(rb*rb*6.0 + 1e-6))*grow;
+  // coffee ring: solute pooled at the contact line of the pen stroke and at the feather front
+  float rimC = exp(-pow((d - rpen)/(0.26*rpen + aa), 2.0))*0.5;
+  float rimB = exp(-pow((d - rE*0.9)/(0.15*rE + aa), 2.0))*0.12*smoothstep(0.0, 0.012, rE);
+  D1 += uPool*dryL*(rimC*(1.0 - 0.6*core) + rimB + rimC*core*0.35);
+  // iron-gall oxidation: Fe(II) -> Fe(III) tannate. Written pale blue-grey, it darkens toward the final dye as ox goes 0 -> 1.
+  // The reaction runs fastest where the ink is dense, so the front moves from the core outwards and the thin edges stay pale / turn warm.
+  float Dn = clamp(D1, 0.0, 1.3);
+  float ox = 1.0 - exp(-age*(0.18 + 1.1*Dn)/max(uOx, 0.05));
+  ox = ox*ox*(3.0 - 2.0*ox);
+  D1 *= vis; D2 *= vis;
+
+  vec3 freshCol = min(mix(pow(max(uColor, vec3(1e-3)), vec3(0.3)), vec3(0.42, 0.46, 0.52), 0.55), vec3(0.85))*0.82;   // pale blue-grey version of the ink
+  vec3 colNow = mix(freshCol, uColor, ox);
+  vec3 k1 = -log(clamp(colNow/paperCol, vec3(0.01), vec3(1.0))); vec3 k2 = -log(clamp(uColor2/paperCol, vec3(0.01), vec3(1.0)));   // k s.t. paper*T = colour at unit density
+  k1 = mix(k1, k2, 0.4*(1.0 - clamp(Dn, 0.0, 1.0))*ox);   // thin oxidised edges turn warm (rust) rather than navy
+  vec3 Tr = exp(-(k1*D1 + k2*D2));                          // dye transmission (Beer-Lambert)
+  vec3 onPaper = paperLit*Tr;
+  // wet gloss: fresh ink reflects the light for a moment (also marks where the pen is)
+  float gloss = exp(-age/(0.45*T0))*exp(-(d*d)/(0.07*rpen*rpen + 1e-6))*vis*(0.35 + 0.65*spot)*0.09;   // a thin specular streak along the wet line
+  onPaper += vec3(0.55, 0.58, 0.62)*gloss*uPaper;
+
+  // no paper (paper knob 0): ink as pigment over the scene, coverage from density (luminous inks work too)
+  float aI = 1.0 - exp(-1.7*(D1 + 0.7*D2));
+  vec3 pig = (colNow*D1 + uColor2*0.7*D2)/(D1 + 0.7*D2 + 1e-4);
+  vec3 inkOver = pig*aI + vec3(0.7)*gloss*(1.0 - uPaper);
+
+  float pa = uPaper*mask*pres;
+  float sh = shd*uPaper*pres;
+  vec3 rgb = pa*onPaper + (1.0 - uPaper)*inkOver;
+  float al = pa + (1.0 - pa)*sh + (1.0 - uPaper)*aI*(1.0 - pa);
+
+  // ======== BURN: the sheet and the ink burn together (look-native erase) ========
+  if (uFire > 0.5) {
+    float arr = max(0.0, burnArr(p) + uRough*(0.009*(2.0*fbm4(p*13.0 + uSeedV*3.1) - 1.0) + 0.003*(2.0*fbm4(p*41.0 + uSeedV*1.7) - 1.0)));
+    float tt = uE - arr; float phi = tt/uL; float Dd = tt*uV; float aheadEm = max(-Dd, 0.0);
+    float gEnd = mix(0.14, 1.0, uChar); float psi = max(phi, 0.0)/gEnd;
+    float qs = max(sd, 0.0); float qe = mix(max(rpen - d, 0.0)*2.0, qs, uPaper);
+    vec2 wp = vec2(vnz(p*7.0 + uSeedV), vnz(p*7.0 + uSeedV + 19.7)) - 0.5;
+    vec3 vc = vor(p*15.0 + wp*1.6 + uSeedV*0.37); vec3 vf = vor(p*38.0 + wp*2.5 + uSeedV*0.91 + 7.3);
+    float nh = fbm4(p*9.0 + uSeedV*1.3); float cn = fbm4(p*21.0 + uSeedV*2.0);
+    float fibB = 0.5 + (Fv - 0.3)*0.5 + (grain - 0.5)*0.4;
+    float wC = 0.035 + fwidth(vc.y);
+    float cr = max(1.0 - smoothstep(0.02, 0.02 + wC, vc.y), 0.55*(1.0 - smoothstep(0.015, 0.075 + fwidth(vf.y), vf.y)));
+    vec3 charC = S(vec3(0.17, 0.13, 0.105))*(0.5 + 0.95*cn)*(0.85 + 0.3*vc.z)*(1.0 - 0.75*cr)*(0.8 + 0.4*fibB);
+    vec3 ashC = S(vec3(0.40, 0.375, 0.345))*(0.5 + 0.8*cn)*(0.92 + 0.16*vc.z)*(0.8 + 0.4*fibB)*(1.0 - 0.3*cr);
+    float ashMix = smoothstep(0.30, 0.85, psi + 0.3*(nh - 0.5));
+    float charMix = smoothstep(0.0, 0.006 + 1.5*px, Dd);
+    vec3 burnt = mix(charC, ashC, ashMix)*mix(vec3(1.0), Tr, 0.45*(1.0 - ashMix));   // the ink darkens / tints the char it sits in
+    float hh = mix(0.5*nh + 0.5*cn, vc.z, 0.22);
+    float thr = mix(0.42, 0.93, hh) - 0.20*exp(-qe/0.03);
+    float alive = 1.0 - smoothstep(thr - 0.09, thr + 0.02, psi);
+    // paper ahead of the front toasts
+    float toast = exp(-aheadEm/0.03);
+    vec3 sheetAhead = onPaper*mix(vec3(1.0), vec3(0.62, 0.45, 0.28), toast*0.7);
+    vec3 sheetRGB = mix(sheetAhead, burnt, charMix);
+    vec3 pigRGB = mix(pig, burnt, charMix);
+    // curl: the charring edge lifts toward the viewer (shading only)
+    float gate = smoothstep(0.0, 0.02, uE);
+    float curlP = 0.6*smoothstep(0.0, 0.012, Dd)*exp(-max(Dd, 0.0)/0.07);
+    float hgt = 0.03*curlP*(0.35 + 0.65*exp(-qs/0.04))*(0.8 + 0.4*cn);
+    float gx = dFdx(p.x); gx = abs(gx) > 1.0e-6 ? gx : 1.0e-6; float gy = dFdy(p.y); gy = abs(gy) > 1.0e-6 ? gy : 1.0e-6;
+    vec2 slope = vec2(dFdx(hgt)/gx, dFdy(hgt)/gy);
+    vec3 nrm = normalize(vec3(-slope*0.9, 1.0)); vec3 Ld = normalize(vec3(-0.5, 0.6, 0.65));
+    sheetRGB *= clamp(dot(nrm, Ld)/Ld.z, 0.45, 1.5);
+    sheetRGB = mix(sheetRGB, S(vec3(0.045, 0.03, 0.02)), clamp(curlP*exp(-qs/0.007), 0.0, 1.0)*0.85*(1.0 - smoothstep(0.0, 0.01, sd)));
+    sheetRGB *= 1.0 - 0.38*0.6*gate*exp(-aheadEm/0.04)*(0.4 + 0.6*exp(-qs/0.05));
+    // ash lace: the ink outlasts the paper as a fragile skeleton of the letters, cooling to blue-grey, collapsing just before the end
+    float thread = smoothstep(0.42, 0.66, fbm4(p*22.0 + uSeedV*0.7));
+    float outl = exp(-pow((d - 0.8*rpen)/(0.16*rpen + px), 2.0));
+    float lace = max(outl, 0.3*smoothstep(0.35, 0.9, D1))*(0.15 + 0.85*thread);
+    float wv = clamp((p.x - uArrExt.x)/uArrExt.z, 0.0, 1.0);
+    float tc = mix(0.62, 0.93, clamp(0.6*wv + 0.4*vc.z, 0.0, 1.0));
+    float collapse = 1.0 - smoothstep(tc - 0.035, tc + 0.03, uE);
+    float laceA = lace*0.55*mix(0.5, 1.0, uChar)*smoothstep(0.30, 0.75, psi)*collapse;
+    float cool = smoothstep(0.4, 1.0, psi);
+    float shn = pow(vnz(vec2(p.x*4.0 + uTime*0.12*uIdleSpeed, p.y*8.0 + 3.1*vc.z)), 3.0);
+    vec3 laceC = mix(S(vec3(0.44, 0.41, 0.38)), S(vec3(0.36, 0.43, 0.52)), cool)*(0.55 + 0.9*shn*cool);
+    // the front itself: thin ember line, glowing bed in the cracks, heat halo ahead
+    float Dp = max(Dd, 0.0); float onFront = smoothstep(0.0, 0.0035 + 1.5*px, Dd);
+    float Te = mix(1750.0, 1150.0, 1.0 - exp(-Dp/0.03)); float line = exp(-Dp/0.012);
+    float beat = 0.55 + 0.45*sin(uTime*0.9*uIdleSpeed + vc.z*40.0);
+    float bed = exp(-Dp/0.06)*cr*beat*(1.0 - smoothstep(0.04, 0.4, psi));
+    float Tbd = mix(1150.0, 880.0, smoothstep(0.0, 0.3, psi));
+    vec3 emis = (ember(Te)*irad(Te)*line*0.62 + ember(Tbd)*irad(Tbd)*bed*0.8 + ember(1250.0)*0.09*exp(-Dp/0.035))*onFront;
+    emis += ember(1250.0)*0.09*exp(-aheadEm/0.03)*(1.0 - onFront);
+    // composite
+    float aSheet = uPaper*mask*pres*alive*mix(1.0, 1.0 - 0.2*cr, ashMix*charMix)*(1.0 - 0.5*smoothstep(0.4, 1.0, psi)*charMix);
+    float aPig = (1.0 - uPaper)*aI*alive*(1.0 - 0.5*smoothstep(0.4, 1.0, psi)*charMix);
+    float aBody = aSheet + aPig*(1.0 - aSheet);
+    vec3 bodyC = (sheetRGB*aSheet + pigRGB*aPig*(1.0 - aSheet))/max(aBody, 1.0e-4);
+    float aOut = aBody + laceA*(1.0 - aBody);
+    vec3 colOut = (bodyC*aBody + laceC*laceA*(1.0 - aBody))/max(aOut, 1.0e-4);
+    float cov = max(uPaper*mask*pres, (1.0 - uPaper)*clamp(aI, 0.0, 1.0));
+    float spill = exp(-max(-sd, 0.0)/0.014)*(1.0 - smoothstep(0.025, 0.045, max(-sd, 0.0)))*uPaper*pres;
+    float mEm = (cov + (1.0 - cov)*spill*0.55)*alive;
+    vec3 em = emis*mEm; em /= max(1.0, max(em.r, max(em.g, em.b)));
+    float shF = 1.0 - smoothstep(0.45, 0.95, psi);
+    rgb = colOut*aOut + em;
+    al = aOut + (1.0 - aOut)*(sh*shF);
+  }
+  rgb *= uOpacity; al = clamp(al*uOpacity, 0.0, 1.0);
+  if (al < 0.002) discard;
+  gl_FragColor = vec4(rgb, al);
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+const hex = (h) => new THREE.Color(h);
+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: 'inkBleed', source: 'hand', drawMethods: DRAW_METHODS, eraseMethods: ['burn', ...ERASE_METHODS], drawDefault: 'pen', eraseDefault: 'burn',
+    animDefaults: { eraseDuration: 6, holdTime: 2.5, eraseEase: 'linear' },
+    methodInfo: { burn: { label: 'Burn', hint: 'The whole sheet burns with the ink on it: seeded ignition points, an ember front along the sheet and the writing, char, ash lace, nothing.' } },
+    catalog: {
+        name: 'Ink Bleed',
+        description: 'Fountain-pen ink soaking into fibrous paper: a wetting front feathers along the fibres, dye separates into a coloured fringe and dries to a darker rim. Use for letters, journals and artisanal titles.',
+        tags: ['ink', 'bleed', 'paper', 'fountain-pen', 'handwriting', 'calligraphy', 'organic'],
+    },
+    defaults: { color: '#1b2d6a', color2: '#b0703c', bleed: 0.042, dryTime: 2.4, fibre: 0.7, pooling: 0.7, weight: 0.7, paper: 1, oxidation: 3.5, burn: 0.6, char: 0.6, spread: 1, opacity: 1 },
+    ui: {
+        main: [
+            num('bleed', 'Bleed', 'How far the ink feathers into the paper', 0, 0.12, 0.002, 'em'),
+            col('color', 'Ink', 'Colour of the dense dye (the dark core)'),
+            num('weight', 'Pen weight', 'Thickness of the pen line', 0.3, 1.6, 0.01),
+            num('paper', 'Paper', '0 = ink only, 1 = a sheet of paper behind the text', 0, 1, 0.01),
+        ],
+        more: [
+            col('color2', 'Fringe dye', 'Colour of the lighter dye that separates into the halo'),
+            num('dryTime', 'Drying time', 'How long the ink keeps wicking before it dries', 0.3, 8, 0.05, 's'),
+            num('fibre', 'Fibre', 'How strongly the paper fibres guide and rag the feathering', 0, 1.5, 0.01),
+            num('pooling', 'Pooling', 'Dark rim where the ink collects as it dries', 0, 1.5, 0.01),
+            num('oxidation', 'Oxidation', 'Seconds the ink takes to darken from pale blue-grey to its final colour (iron-gall oxidation)', 0.3, 20, 0.1, 's'),
+            num('burn', 'Ink burn', 'Slow browning of the paper around the lines, strongest where the pen pressed hard', 0, 1.5, 0.01),
+            num('char', 'Char', 'How much cracked char and ash the fire leaves behind (0 = clean burn); used by the Burn erase', 0, 1, 0.01),
+            num('spread', 'Spread', 'Speed of the fire front; faster fronts leave their remains lingering longer (Burn erase)', 0.3, 2.2, 0.01),
+            num('opacity', 'Opacity', 'Overall opacity', 0, 1, 0.01),
+        ],
+    },
+    structural: [],
+    presets: [
+        { name: 'Blue-black shading', description: 'Navy core with a warm brown fringe on cream paper.', patch: {} },
+        { name: 'Sepia quill', description: 'Brown dye that separates to teal.', patch: { color: '#4a2a14', color2: '#2f8f86', bleed: 0.052, dryTime: 3.2, fibre: 0.9, pooling: 0.9, weight: 0.8, oxidation: 5, burn: 0.8 } },
+        { name: 'Iron gall', description: 'Near-black ink with a rust fringe, crisp and dry.', patch: { color: '#14110f', color2: '#a2491f', bleed: 0.032, dryTime: 1.2, fibre: 0.5, pooling: 1.1, weight: 0.62, oxidation: 6, burn: 1.1 } },
+        { name: 'Soaked blotter', description: 'A wet nib on soft paper: wide, ragged feathering.', patch: { color: '#1a2a6a', color2: '#9a3a5a', bleed: 0.1, dryTime: 5.5, fibre: 1.25, pooling: 0.5, weight: 0.9, oxidation: 2.5, burn: 0.5 } },
+        { name: 'Gold gel', description: 'Luminous gold ink straight on the scene, no paper.', patch: { color: '#e8b64a', color2: '#fff0c0', bleed: 0.022, dryTime: 2, fibre: 0.3, pooling: 0.4, weight: 0.8, paper: 0, oxidation: 0.3, burn: 0 } },
+    ],
+    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 { infoD, infoE } = applyAnim(strokes, anim, G);
+        const field = buildField(strokes, { source: 'hand', texels: 1024, pad: 0.3, maxDist: 0.4 });
+        const map = burnMap(strokes, field);
+        const mat = fieldMaterial(field, FRAG, {
+            uArr: { value: map.tex }, uArrExt: { value: field.ext }, uL: { value: 0.3 }, uV: { value: 3 }, uRough: { value: 0.6 }, uSeedV: { value: new THREE.Vector2(91.4 % 97, 49.8 % 89) },
+            uFire: { value: anim.erase.method === 'burn' ? 1 : 0 }, uChar: { value: cfg.char },
+            uColor: { value: hex(cfg.color) }, uColor2: { value: hex(cfg.color2) }, uBleed: { value: cfg.bleed }, uDry: { value: cfg.dryTime }, uFibre: { value: cfg.fibre },
+            uPool: { value: cfg.pooling }, uWeight: { value: cfg.weight }, uPaper: { value: cfg.paper }, uOpacity: { value: 1 }, uTexel: { value: field.texel }, uOx: { value: cfg.oxidation }, uBurn: { value: cfg.burn }, uPen: { value: layout.natural || 0.08 },
+        }, { extra: BURN_COMMON });
+        const mesh = fieldQuad(field, mat);
+        const sgeo = sparkGeometry(map);
+        const smat = new THREE.ShaderMaterial({ uniforms: { ...mat.uniforms }, vertexShader: SPARK_VERT, fragmentShader: SPARK_FRAG, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending });
+        smat.uniforms.uScale = { value: 800 };
+        smat.uniforms.uSize = { value: 0.016 };
+        const sparks = new THREE.Points(sgeo, smat);
+        sparks.frustumCulled = false;
+        const group = new THREE.Group();
+        group.add(mesh, sparks);
+        const api = {
+            object: group,
+            apply(c) {
+                const u = mat.uniforms;
+                u.uColor.value.set(c.color);
+                u.uColor2.value.set(c.color2);
+                u.uBleed.value = c.bleed;
+                u.uDry.value = c.dryTime;
+                u.uFibre.value = c.fibre;
+                u.uPool.value = c.pooling;
+                u.uWeight.value = c.weight;
+                u.uPaper.value = c.paper;
+                u.uOpacity.value = c.opacity;
+                u.uOx.value = c.oxidation;
+                u.uBurn.value = c.burn;
+                u.uChar.value = c.char;
+                // spread: fire speed vs. how long the remains linger. L = lifecycle length in erase progress (the front uses 1-L), so S.e = 1 always finishes.
+                const L = Math.max(0.12, Math.min(0.62, 0.12 + 0.22 * c.spread));
+                u.uL.value = L;
+                u.uV.value = map.Tmax / (1 - L);
+                api.c = c;
+            },
+            update(S, time, px) { setReveal(mat.uniforms, S, infoD, infoE, anim.draw.duration, time); smat.uniforms.uScale.value = px; },
+            dispose() { field.dispose(); map.tex.dispose(); mat.dispose(); mesh.geometry.dispose(); sgeo.dispose(); smat.dispose(); },
+        };
+        api.apply(cfg);
+        return api;
+    },
+};