@appinternalleads/ui 0.4.0 → 0.4.2

package/dist/esm/motion/typesurface/engine.js

@@ -0,0 +1,627 @@
+/**
+ * **The geometry engine.** One surface, one mesh, evaluated for a config at a moment:
+ *
+ *   sheet     the surface through its own shape → wrinkles → crumple → folds → roll → cylinder,
+ *             then the rigid turns of the whole object (horizontal/vertical distortion)
+ *   stack     the pages under a newspaper's top sheet, offset along its normals
+ *   text      a mesh made of the SHEET'S OWN CELLS under the text block. Each vertex blends from
+ *             its floating position (flat, above everything) to the sheet vertex it belongs to, so
+ *             conformed letters lie on exactly the paper's triangles, crease for crease
+ *   prop      a solid the surface wraps (the bottle)
+ *   guides    fold lines, the roll line, the text outline and baselines, for the debug view
+ *
+ * Everything is written into buffers allocated once per surface, so a frame allocates nothing.
+ * Pure: no DOM, no React. The renderer uploads what this returns.
+ */
+import { DEFAULT_TYPE_SURFACE, TS_FOLD_KEYS, TS_WRAP_KEYS } from './config';
+import { glyphAt, morphGap } from './layout';
+import { bend, bendDistance, crumpleCreases, crumpleField, cylinder, roll, rotate, smoothstep } from './ops';
+const DEG = Math.PI / 180;
+const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v);
+const sstep = (v) => { const t = clamp01(v); return t * t * (3 - 2 * t); };
+/** Normals by central differences over a grid, and cavity (how much a vertex sits in a valley). */
+function gridNormals(pos, nrm, ni, nj, cav, cavStride, cavOffset, h) {
+    for (let j = 0; j < nj; j++) {
+        const jp = j > 0 ? j - 1 : j, jm = j < nj - 1 ? j + 1 : j;
+        for (let i = 0; i < ni; i++) {
+            const ip = i < ni - 1 ? i + 1 : i, im = i > 0 ? i - 1 : i;
+            const a = (j * ni + ip) * 3, b = (j * ni + im) * 3, c = (jp * ni + i) * 3, d = (jm * ni + i) * 3;
+            const tx0 = pos[a] - pos[b], tx1 = pos[a + 1] - pos[b + 1], tx2 = pos[a + 2] - pos[b + 2];
+            const ty0 = pos[c] - pos[d], ty1 = pos[c + 1] - pos[d + 1], ty2 = pos[c + 2] - pos[d + 2];
+            let nx = tx1 * ty2 - tx2 * ty1, ny = tx2 * ty0 - tx0 * ty2, nz = tx0 * ty1 - tx1 * ty0;
+            const l = Math.hypot(nx, ny, nz) || 1;
+            nx /= l;
+            ny /= l;
+            nz /= l;
+            const k = (j * ni + i) * 3;
+            nrm[k] = nx;
+            nrm[k + 1] = ny;
+            nrm[k + 2] = nz;
+            if (cav) {
+                let v = 0;
+                if (i > 0 && i < ni - 1 && j > 0 && j < nj - 1) {
+                    const lx = (pos[a] + pos[b] + pos[c] + pos[d]) / 4 - pos[k];
+                    const ly = (pos[a + 1] + pos[b + 1] + pos[c + 1] + pos[d + 1]) / 4 - pos[k + 1];
+                    const lz = (pos[a + 2] + pos[b + 2] + pos[c + 2] + pos[d + 2]) / 4 - pos[k + 2];
+                    v = Math.max(-1, Math.min(1, ((lx * nx + ly * ny + lz * nz) / h) * 2.5));
+                }
+                cav[(j * ni + i) * cavStride + cavOffset] = v;
+            }
+        }
+    }
+}
+/** Two triangles per cell; the diagonal alternates by the SHEET's cell parity, so a sub-grid shares it. */
+function gridIndices(ni, nj, i0, j0, out) {
+    const idx = out ?? new Uint32Array((ni - 1) * (nj - 1) * 6);
+    let o = 0;
+    for (let j = 0; j < nj - 1; j++) {
+        for (let i = 0; i < ni - 1; i++) {
+            const a = j * ni + i, b = a + 1, c = a + ni, d = c + 1;
+            if (((i + i0 + j + j0) & 1) === 1) {
+                idx[o++] = a;
+                idx[o++] = c;
+                idx[o++] = b;
+                idx[o++] = b;
+                idx[o++] = c;
+                idx[o++] = d;
+            }
+            else {
+                idx[o++] = a;
+                idx[o++] = c;
+                idx[o++] = d;
+                idx[o++] = a;
+                idx[o++] = d;
+                idx[o++] = b;
+            }
+        }
+    }
+    return idx;
+}
+/**
+ * A wine bottle of glass radius `radius`, revolved about the LABEL's axis (parallel to y at z = −axis),
+ * so a wrapped label sits exactly `axis − radius` off the glass all the way round.
+ */
+function bottleMesh(radius, axis) {
+    // (r, y) from the centre of the base to the centre of the lip, label-centred coordinates, drawn at
+    // a 0.36 body radius and scaled to `radius`.
+    const scale = radius / 0.36;
+    const key = [
+        [0, -0.93], [0.2, -0.95], [0.31, -0.955], [0.345, -0.94], [0.36, -0.9], [0.36, 0.7], [0.352, 0.8], [0.32, 0.9], [0.26, 0.98], [0.19, 1.05],
+        [0.145, 1.12], [0.128, 1.2], [0.125, 1.3], [0.126, 1.55], [0.14, 1.565], [0.142, 1.63], [0.12, 1.645], [0, 1.65],
+    ];
+    // Densify so the shoulder is smooth.
+    const prof = [];
+    for (let k = 0; k < key.length - 1; k++) {
+        const [r0, y0] = key[k], [r1, y1] = key[k + 1];
+        const steps = Math.max(1, Math.round(Math.hypot(r1 - r0, y1 - y0) / 0.04));
+        for (let s = 0; s < steps; s++)
+            prof.push([r0 + ((r1 - r0) * s) / steps, y0 + ((y1 - y0) * s) / steps]);
+    }
+    prof.push(key[key.length - 1]);
+    const segs = 96;
+    const np = prof.length;
+    const count = np * (segs + 1);
+    const positions = new Float32Array(count * 3), normals = new Float32Array(count * 3), attrs = new Float32Array(count * 4);
+    for (let p = 0; p < np; p++) {
+        const r = prof[p][0] * scale, y = prof[p][1];
+        const [ra, ya] = prof[Math.max(0, p - 1)], [rb, yb] = prof[Math.min(np - 1, p + 1)];
+        let n0 = yb - ya, n1 = -(rb - ra);
+        const l = Math.hypot(n0, n1) || 1;
+        n0 /= l;
+        n1 /= l;
+        for (let q = 0; q <= segs; q++) {
+            const a = (q / segs) * Math.PI * 2;
+            const k = p * (segs + 1) + q;
+            positions[k * 3] = r * Math.sin(a);
+            positions[k * 3 + 1] = y;
+            positions[k * 3 + 2] = -axis + r * Math.cos(a);
+            normals[k * 3] = n0 * Math.sin(a);
+            normals[k * 3 + 1] = n1;
+            normals[k * 3 + 2] = n0 * Math.cos(a);
+            attrs[k * 4] = y > 1.2 ? 1 : 0; // 1: foil capsule
+        }
+    }
+    const idx = [];
+    for (let p = 0; p < np - 1; p++) {
+        for (let q = 0; q < segs; q++) {
+            const a = p * (segs + 1) + q, b = a + 1, c = a + segs + 1, d = c + 1;
+            idx.push(a, b, c, b, d, c);
+        }
+    }
+    return { positions, normals, attrs, indices: new Uint32Array(idx), count };
+}
+/** Build the engine for one surface. Allocates its buffers once. */
+export function createGeometryEngine(def) {
+    const [nu, nv] = def.grid;
+    const N = nu * nv;
+    const W = def.width;
+    const Hs = def.height / def.width;
+    const h = W / (nu - 1);
+    const sx = new Float32Array(N), sy = new Float32Array(N);
+    const uvs = new Float32Array(N * 2);
+    for (let j = 0; j < nv; j++) {
+        for (let i = 0; i < nu; i++) {
+            const k = j * nu + i;
+            sx[k] = i / (nu - 1) - 0.5;
+            sy[k] = (0.5 - j / (nv - 1)) * Hs;
+            uvs[k * 2] = i / (nu - 1);
+            uvs[k * 2 + 1] = j / (nv - 1);
+        }
+    }
+    const indices = gridIndices(nu, nv, 0, 0);
+    const pos = new Float32Array(N * 3), nrm = new Float32Array(N * 3), attrs = new Float32Array(N * 4);
+    const stack = Array.from({ length: def.stack?.sheets ?? 0 }, () => new Float32Array(N * 3));
+    // Crumple fields, cached per (seed, scale): a whole-sheet evaluation is ~20 ms, a frame reuses it.
+    const fieldCache = new Map();
+    const fieldFor = (seed, scale) => {
+        const key = `${seed}:${scale.toFixed(3)}`;
+        let f = fieldCache.get(key);
+        if (!f) {
+            const creases = crumpleCreases(seed, scale, Hs);
+            const full = new Float32Array(N * 3), fine = new Float32Array(N);
+            const o = [0, 0, 0];
+            for (let k = 0; k < N; k++) {
+                crumpleField(creases, sx[k], sy[k], o);
+                full[k * 3] = o[0];
+                full[k * 3 + 1] = o[1];
+                full[k * 3 + 2] = o[2];
+                crumpleField(creases, sx[k], sy[k], o, true);
+                fine[k] = o[2];
+            }
+            if (fieldCache.size > 6)
+                fieldCache.clear();
+            f = { creases, full, fine };
+            fieldCache.set(key, f);
+        }
+        return f;
+    };
+    const text = {
+        positions: new Float32Array(N * 3), normals: new Float32Array(N * 3), uvs: new Float32Array(N * 2), tuv: new Float32Array(N * 2),
+        attrs: new Float32Array(N * 4), indices: new Uint32Array((nu - 1) * (nv - 1) * 6), vertexCount: 0, indexCount: 0, indexVersion: 0,
+    };
+    let textRect = '';
+    // The solid the sheet wraps: the wine bottle, or a constructed object's parts.
+    const bottle = def.prop === 'bottle' ? bottleMesh(def.curveRadius - 0.0025, def.curveRadius)
+        : def.solid ? { ...def.solid, attrs: new Float32Array(def.solid.count * 4) } : null;
+    const prop = bottle
+        ? {
+            positions: new Float32Array(bottle.count * 3), normals: new Float32Array(bottle.count * 3), attrs: bottle.attrs, indices: bottle.indices, vertexCount: bottle.count,
+            ranges: def.solid?.ranges ?? [{ start: 0, count: bottle.indices.length, material: null }],
+        }
+        : null;
+    const solid = !!(def.prop || def.solid);
+    const loose = def.looseSheet
+        ? { positions: new Float32Array(12), normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]), uvs: new Float32Array([0, 0, 1, 0, 0, 1, 1, 1]), indices: new Uint32Array([0, 2, 1, 1, 2, 3]) }
+        : null;
+    // ---- the frame's parameters, set by `evaluate`, read by `pipe` ----
+    let F = {
+        d: DEFAULT_TYPE_SURFACE.deformation, t: 0, motion: 1, skew: 0, crumpleA: 0, shrink: 1, bowl: 0, wrinkleA: 0,
+        bends: [], roll: null, kappa: 0, spin: 0,
+        rotA: 0, rotB: 0, rotC: 0, shiftX: 0, shiftY: 0,
+        creases: [],
+    };
+    /** One sheet point through the surface's operators (before the object's rigid turns). Returns crease light. */
+    const pipe = (x0, y0, fx, fy, fz, gz, p) => {
+        const x = x0 * W, y = y0 * W;
+        p[0] = x + F.skew * 0.35 * y;
+        p[1] = y;
+        p[2] = 0;
+        def.shape?.(p, x0, y0, F.d, F.t, F.motion);
+        if (F.wrinkleA)
+            p[2] += gz * W * F.wrinkleA;
+        if (F.crumpleA) {
+            p[0] += fx * W * F.crumpleA;
+            p[1] += fy * W * F.crumpleA;
+            p[2] += fz * W * F.crumpleA;
+            p[0] *= F.shrink;
+            p[1] *= F.shrink;
+            if (F.bowl)
+                p[2] += F.bowl * W * ((p[0] / W) ** 2 + (p[1] / W) ** 2);
+        }
+        let crease = 0;
+        for (const s of F.bends) {
+            const dist = bendDistance(p[0], p[1], s.b);
+            crease += s.infl * Math.exp(-((dist / s.zone) ** 2));
+            bend(p, s.b);
+        }
+        if (F.roll)
+            roll(p, F.roll);
+        if (F.kappa) {
+            cylinder(p, F.kappa);
+            if (def.radiusAt) {
+                // Follow the part's own radius at this height (a taper, a bulge), about the cylinder's axis.
+                const k = 1 + (def.radiusAt(p[1]) / def.curveRadius - 1) * F.d.curve, A = 1 / F.kappa;
+                p[0] *= k;
+                p[2] = (p[2] + A) * k - A;
+            }
+            if (F.spin) {
+                const R = def.curveRadius;
+                const zz = p[2] + R, c = Math.cos(F.spin), s = Math.sin(F.spin);
+                const xx = p[0] * c + zz * s;
+                p[2] = -p[0] * s + zz * c - R;
+                p[0] = xx;
+            }
+        }
+        return crease;
+    };
+    const place = (p) => {
+        rotate(p, F.rotA, F.rotB, F.rotC);
+        p[0] += F.shiftX;
+        p[1] += F.shiftY;
+    };
+    const fieldAt = (x0, y0, o, g) => {
+        if (F.crumpleA)
+            crumpleField(F.creases, x0, y0, o);
+        else {
+            o[0] = 0;
+            o[1] = 0;
+            o[2] = 0;
+        }
+        if (F.wrinkleA)
+            crumpleField(F.creases, x0, y0, g, true);
+        else
+            g[2] = 0;
+    };
+    const mapSheet = (x0, y0, out) => {
+        const o = [0, 0, 0], g = [0, 0, 0];
+        fieldAt(x0, y0, o, g);
+        pipe(x0, y0, o[0], o[1], o[2], g[2], out);
+        place(out);
+        return out;
+    };
+    /** A crease line; `near` flips which side moves. */
+    const creaseLine = (position, orientation, side, shrink) => {
+        const flip = side === 'near' ? -1 : 1;
+        return orientation === 'vertical'
+            ? { px: (position - 0.5) * W * shrink, py: 0, dx: 0, dy: flip }
+            : { px: 0, py: (0.5 - position) * def.height * shrink, dx: flip, dy: 0 };
+    };
+    const foldBend = (f, shrink) => {
+        if (f.amount <= 0.0005)
+            return null;
+        const theta = f.angle * f.amount * DEG * (f.direction === 'over' ? 1 : -1);
+        const width = Math.max(0.002, f.width * W);
+        const b = { ...creaseLine(f.position, f.orientation, f.side ?? 'far', shrink), theta, width };
+        return { b, infl: f.influence * Math.min(1, f.amount * 2.5), zone: width * 0.8 + 0.004 };
+    };
+    /** A wrap is a bend whose zone is a rod: its width grows with the angle so the radius stays put. */
+    const wrapBend = (w, shrink) => {
+        if (w.amount <= 0.0005)
+            return null;
+        const turn = w.angle * w.amount * DEG;
+        const theta = turn * (w.direction === 'over' ? 1 : -1);
+        const b = { ...creaseLine(w.position, w.orientation, w.side ?? 'far', shrink), theta, width: Math.max(0.002, turn * w.radius * W) };
+        return { b, infl: 0, zone: 1 };
+    };
+    const scratch = [0, 0, 0];
+    /** The solid turns with its label, about the wrap axis (a mug's handle comes round with the words). */
+    const spinSolid = (p, direction = false) => {
+        if (!F.spin)
+            return;
+        const R = direction ? 0 : def.curveRadius;
+        const zz = p[2] + R, c = Math.cos(F.spin), s = Math.sin(F.spin);
+        const xx = p[0] * c + zz * s;
+        p[2] = -p[0] * s + zz * c - R;
+        p[0] = xx;
+    };
+    const evaluate = (cfg, timeMs, layout, opts) => {
+        const d = cfg.deformation;
+        const c = d.crumple.amount;
+        const field = c > 0 || d.wrinkle > 0 ? fieldFor(cfg.surface.seed, d.crumple.scale) : null;
+        const shrink = 1 - 0.06 * c - 0.2 * smoothstep(0.55, 1, c);
+        const bends = [...TS_FOLD_KEYS.map((k) => foldBend(d[k], shrink)), ...TS_WRAP_KEYS.map((k) => wrapBend(d[k], shrink))].filter((x) => !!x);
+        // A later crease in the same direction wraps the layers the earlier one laid on its inner side.
+        for (let i = 1; i < bends.length; i++) {
+            for (let k = 0; k < i; k++) {
+                const a = bends[k].b, b = bends[i].b;
+                if (Math.sign(a.theta) === Math.sign(b.theta))
+                    b.core = (b.core ?? 0) + (2 * a.width / Math.abs(a.theta)) * Math.min(1, Math.abs(a.theta) / Math.PI);
+                else if (Math.abs(a.theta) > Math.PI)
+                    b.core = (b.core ?? 0) + (a.width / Math.abs(a.theta)) * 2;
+            }
+        }
+        let rl = null;
+        if (d.roll.amount > 0.0005) {
+            const edge = d.roll.edge;
+            const vertical = edge === 'bottom' || edge === 'top';
+            const len = (vertical ? def.height : W) * shrink;
+            const sgn = edge === 'bottom' || edge === 'left' ? -1 : 1;
+            const radius = d.roll.radius * W;
+            rl = {
+                ox: vertical ? 0 : (sgn * W * shrink) / 2, oy: vertical ? (sgn * def.height * shrink) / 2 : 0,
+                ex: vertical ? 0 : -sgn, ey: vertical ? -sgn : 0,
+                reach: d.roll.amount * len, radius, inner: radius * 0.45, length: len, sign: d.roll.direction === 'under' ? -1 : 1,
+            };
+        }
+        const kappa = def.curveMode === 'cylinder' && d.curve > 0.0005 ? d.curve / def.curveRadius : 0;
+        F = {
+            d, t: timeMs, motion: cfg.view.motion, skew: d.skew,
+            crumpleA: c > 0 ? c * (0.5 + 0.5 * smoothstep(0.5, 1, c)) : 0, shrink: c > 0 ? shrink : 1, bowl: 0.35 * smoothstep(0.55, 1, c),
+            wrinkleA: d.wrinkle > 0 ? d.wrinkle * def.wrinkleDepth * 60 : 0,
+            bends, roll: rl, kappa,
+            spin: solid ? d.curve * cfg.view.motion * 0.5 * Math.sin((2 * Math.PI * timeMs) / 10000) : 0,
+            rotA: d.tiltX * 0.6, rotB: -d.tiltY * 0.6, rotC: cfg.view.roll * DEG, shiftX: 0, shiftY: 0,
+            creases: field?.creases ?? [],
+        };
+        // ---- the sheet ----
+        let zTop = -Infinity;
+        const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+        for (let k = 0; k < N; k++) {
+            const x0 = sx[k], y0 = sy[k];
+            const crease = pipe(x0, y0, field ? field.full[k * 3] : 0, field ? field.full[k * 3 + 1] : 0, field ? field.full[k * 3 + 2] : 0, field ? field.fine[k] : 0, scratch);
+            if (scratch[2] > zTop)
+                zTop = scratch[2];
+            const fxw = x0 * W + F.skew * 0.35 * y0 * W;
+            attrs[k * 4] = Math.min(1, crease);
+            attrs[k * 4 + 2] = Math.hypot(scratch[0] - fxw, scratch[1] - y0 * W, scratch[2]) / W;
+            rotate(scratch, F.rotA, F.rotB, F.rotC);
+            pos[k * 3] = scratch[0];
+            pos[k * 3 + 1] = scratch[1];
+            pos[k * 3 + 2] = scratch[2];
+            for (let a = 0; a < 3; a++) {
+                const v = scratch[a];
+                if (v < min[a])
+                    min[a] = v;
+                if (v > max[a])
+                    max[a] = v;
+            }
+        }
+        if (prop && bottle) {
+            for (let k = 0; k < bottle.count; k++) {
+                scratch[0] = bottle.positions[k * 3];
+                scratch[1] = bottle.positions[k * 3 + 1];
+                scratch[2] = bottle.positions[k * 3 + 2];
+                spinSolid(scratch);
+                rotate(scratch, F.rotA, F.rotB, F.rotC);
+                prop.positions.set(scratch, k * 3);
+                for (let a = 0; a < 3; a++) {
+                    const v = scratch[a];
+                    if (v < min[a])
+                        min[a] = v;
+                    if (v > max[a])
+                        max[a] = v;
+                }
+                scratch[0] = bottle.normals[k * 3];
+                scratch[1] = bottle.normals[k * 3 + 1];
+                scratch[2] = bottle.normals[k * 3 + 2];
+                spinSolid(scratch, true);
+                rotate(scratch, F.rotA, F.rotB, F.rotC);
+                prop.normals.set(scratch, k * 3);
+            }
+        }
+        if (cfg.view.autoCenter) {
+            F.shiftX = -(min[0] + max[0]) / 2;
+            F.shiftY = -(min[1] + max[1]) / 2;
+            for (let k = 0; k < N; k++) {
+                pos[k * 3] = pos[k * 3] + F.shiftX;
+                pos[k * 3 + 1] = pos[k * 3 + 1] + F.shiftY;
+            }
+            if (prop)
+                for (let k = 0; k < prop.vertexCount; k++) {
+                    prop.positions[k * 3] = prop.positions[k * 3] + F.shiftX;
+                    prop.positions[k * 3 + 1] = prop.positions[k * 3 + 1] + F.shiftY;
+                }
+            min[0] += F.shiftX;
+            max[0] += F.shiftX;
+            min[1] += F.shiftY;
+            max[1] += F.shiftY;
+        }
+        gridNormals(pos, nrm, nu, nv, attrs, 4, 1, h);
+        // ---- the pages under it: offset along the normal, edges not quite aligned ----
+        const st = def.stack;
+        stack.forEach((out, si) => {
+            const gap = (st?.gap ?? 0.003) * (si + 1);
+            const ext = si === 0 ? [0.004, 0.007, 0.003, 0.009] : [0.009, 0.003, 0.006, 0.004]; // left, right, top, bottom
+            for (let j = 0; j < nv; j++) {
+                for (let i = 0; i < nu; i++) {
+                    const k = j * nu + i;
+                    let x = pos[k * 3] - nrm[k * 3] * gap, y = pos[k * 3 + 1] - nrm[k * 3 + 1] * gap, z = pos[k * 3 + 2] - nrm[k * 3 + 2] * gap;
+                    const push = (to, e) => {
+                        const tx = pos[k * 3] - pos[to * 3], ty = pos[k * 3 + 1] - pos[to * 3 + 1], tz = pos[k * 3 + 2] - pos[to * 3 + 2];
+                        const l = Math.hypot(tx, ty, tz) || 1;
+                        x += (tx / l) * e * W;
+                        y += (ty / l) * e * W;
+                        z += (tz / l) * e * W;
+                    };
+                    if (i === 0)
+                        push(k + 1, ext[0]);
+                    if (i === nu - 1)
+                        push(k - 1, ext[1]);
+                    if (j === 0)
+                        push(k + nu, ext[2]);
+                    if (j === nv - 1)
+                        push(k - nu, ext[3]);
+                    out[k * 3] = x;
+                    out[k * 3 + 1] = y;
+                    out[k * 3 + 2] = z;
+                    if (z < min[2])
+                        min[2] = z;
+                }
+            }
+        });
+        const tableZ = min[2] - 0.004 * W;
+        if (loose) {
+            const a = -7 * DEG, cx = 0.2 * W + (cfg.view.autoCenter ? F.shiftX : 0), cy = -0.12 * W + (cfg.view.autoCenter ? F.shiftY : 0);
+            const hw = W / 2, hh = def.height / 2;
+            const corners = [[-hw, hh], [hw, hh], [-hw, -hh], [hw, -hh]];
+            corners.forEach(([x, y], k) => {
+                loose.positions[k * 3] = cx + x * Math.cos(a) - y * Math.sin(a);
+                loose.positions[k * 3 + 1] = cy + x * Math.sin(a) + y * Math.cos(a);
+                loose.positions[k * 3 + 2] = tableZ + 0.0008;
+            });
+        }
+        // ---- the text: the sheet's own cells under the block ----
+        let textOut = null;
+        if (layout) {
+            const pl = cfg.placement;
+            const fs = layout.fontSize;
+            const gap = morphGap(d.morph, layout);
+            const most = Math.max(1, ...layout.lines.map((l) => l.glyphs.length));
+            const spread = (gap * (most - 1)) / 2 + fs * 0.1;
+            const rot = pl.rotation * DEG;
+            const ax = [Math.cos(rot), -Math.sin(rot)], ay = [-Math.sin(rot), -Math.cos(rot)]; // block x, block y (down) on the sheet
+            const cx = pl.x - 0.5, cy = (0.5 - pl.y) * Hs;
+            const bw = layout.width, bh = layout.height;
+            let iMin = nu, iMax = 0, jMin = nv, jMax = 0;
+            for (const [bx, by] of [[-spread, 0], [bw + spread, 0], [-spread, bh], [bw + spread, bh]]) {
+                const ux = cx + (ax[0] * (bx - bw / 2) + ay[0] * (by - bh / 2)) / 1000;
+                const uy = cy + (ax[1] * (bx - bw / 2) + ay[1] * (by - bh / 2)) / 1000;
+                const fi = (ux + 0.5) * (nu - 1), fj = (0.5 - uy / Hs) * (nv - 1);
+                iMin = Math.min(iMin, Math.floor(fi) - 1);
+                iMax = Math.max(iMax, Math.ceil(fi) + 1);
+                jMin = Math.min(jMin, Math.floor(fj) - 1);
+                jMax = Math.max(jMax, Math.ceil(fj) + 1);
+            }
+            iMin = Math.max(0, iMin);
+            jMin = Math.max(0, jMin);
+            iMax = Math.min(nu - 1, iMax);
+            jMax = Math.min(nv - 1, jMax);
+            if (iMax > iMin && jMax > jMin) {
+                const ni = iMax - iMin + 1, nj = jMax - jMin + 1;
+                const rect = `${iMin},${jMin},${ni},${nj}`;
+                if (rect !== textRect) {
+                    textRect = rect;
+                    gridIndices(ni, nj, iMin, jMin, text.indices);
+                    text.indexCount = (ni - 1) * (nj - 1) * 6;
+                    text.indexVersion++;
+                }
+                text.vertexCount = ni * nj;
+                const liftH = cfg.material.lift * W;
+                const eps = 0.0009 * W;
+                const S = 1.6;
+                const denom = Math.max(1, layout.glyphCount - 1);
+                const rp = text.positions, rn = text.normals;
+                for (let j = 0; j < nj; j++) {
+                    for (let i = 0; i < ni; i++) {
+                        const t = j * ni + i;
+                        const k = (j + jMin) * nu + (i + iMin);
+                        const rx = sx[k] - cx, ry = sy[k] - cy;
+                        const bx = (rx * ax[0] + ry * ax[1]) * 1000 + bw / 2;
+                        const by = (rx * ay[0] + ry * ay[1]) * 1000 + bh / 2;
+                        const tu = bx / bw, tv = by / bh;
+                        text.tuv[t * 2] = tu;
+                        text.tuv[t * 2 + 1] = tv;
+                        text.uvs[t * 2] = uvs[k * 2];
+                        text.uvs[t * 2 + 1] = uvs[k * 2 + 1];
+                        const wrapW = sstep(d.wrap * 1.3 - clamp01(tu) * 0.3);
+                        let mg = 0;
+                        if (d.morph > 0) {
+                            const g = glyphAt(layout, bx, by, gap);
+                            const o = g ? Math.min(1, g.glyph.order / denom) : 0;
+                            mg = sstep(d.morph * (1 + S) - o * S);
+                        }
+                        const w = 1 - (1 - wrapW) * (1 - mg);
+                        const flight = 4 * mg * (1 - mg) * (1 - wrapW);
+                        // Floating position: the flat sheet, lifted above everything, then the same rigid turns.
+                        scratch[0] = sx[k] * W + F.skew * 0.35 * sy[k] * W;
+                        scratch[1] = sy[k] * W;
+                        scratch[2] = zTop + liftH * (1 + flight * 0.6);
+                        place(scratch);
+                        const sxp = pos[k * 3] + nrm[k * 3] * eps, syp = pos[k * 3 + 1] + nrm[k * 3 + 1] * eps, szp = pos[k * 3 + 2] + nrm[k * 3 + 2] * eps;
+                        rp[t * 3] = scratch[0] + (sxp - scratch[0]) * w;
+                        rp[t * 3 + 1] = scratch[1] + (syp - scratch[1]) * w;
+                        rp[t * 3 + 2] = scratch[2] + (szp - scratch[2]) * w;
+                        text.attrs[t * 4] = w;
+                        text.attrs[t * 4 + 1] = attrs[k * 4];
+                        text.attrs[t * 4 + 2] = attrs[k * 4 + 1];
+                        text.attrs[t * 4 + 3] = flight;
+                    }
+                }
+                gridNormals(rp, rn, ni, nj, null, 0, 0, h);
+                textOut = text;
+            }
+        }
+        // ---- debug guides ----
+        let guides = null;
+        if (opts?.guides) {
+            const line = (from, to, steps = 80) => {
+                const out = new Float32Array((steps + 1) * 3);
+                const p = [0, 0, 0];
+                for (let s = 0; s <= steps; s++) {
+                    const f = s / steps;
+                    mapSheet(from[0] + (to[0] - from[0]) * f, from[1] + (to[1] - from[1]) * f, p);
+                    out.set(p, s * 3);
+                }
+                return out;
+            };
+            const half = Hs / 2;
+            const folds = [], zones = [];
+            const anchors = [];
+            for (const f of [...TS_FOLD_KEYS.map((k) => d[k]), ...TS_WRAP_KEYS.map((k) => ({ ...d[k], width: d[k].angle * DEG * d[k].amount * d[k].radius }))]) {
+                if (f.amount <= 0.0005)
+                    continue;
+                const wz = f.width * ((f.side ?? 'far') === 'near' ? -1 : 1);
+                if (f.orientation === 'vertical') {
+                    const x = f.position - 0.5;
+                    folds.push(line([x, -half], [x, half]));
+                    zones.push(line([x + wz, -half], [x + wz, half]));
+                }
+                else {
+                    const y = (0.5 - f.position) * Hs;
+                    folds.push(line([-0.5, y], [0.5, y]));
+                    zones.push(line([-0.5, y - wz], [0.5, y - wz]));
+                }
+                const fl = folds[folds.length - 1];
+                anchors.push(fl[0], fl[1], fl[2], fl[fl.length - 3], fl[fl.length - 2], fl[fl.length - 1]);
+            }
+            let rollLine = null;
+            if (d.roll.amount > 0.0005) {
+                const e = d.roll.edge, a = d.roll.amount;
+                rollLine = e === 'bottom' ? line([-0.5, -half + a * Hs], [0.5, -half + a * Hs]) : e === 'top' ? line([-0.5, half - a * Hs], [0.5, half - a * Hs])
+                    : e === 'left' ? line([-0.5 + a, -half], [-0.5 + a, half]) : line([0.5 - a, -half], [0.5 - a, half]);
+            }
+            let outline = null;
+            const baselines = [];
+            if (layout) {
+                const pl = cfg.placement, rot = pl.rotation * DEG;
+                const ax = [Math.cos(rot), -Math.sin(rot)], ay = [-Math.sin(rot), -Math.cos(rot)];
+                const cx = pl.x - 0.5, cy = (0.5 - pl.y) * Hs;
+                const toSheet = (bx, by) => [
+                    cx + (ax[0] * (bx - layout.width / 2) + ay[0] * (by - layout.height / 2)) / 1000,
+                    cy + (ax[1] * (bx - layout.width / 2) + ay[1] * (by - layout.height / 2)) / 1000,
+                ];
+                const p = layout.pad;
+                const c0 = toSheet(p, p), c1 = toSheet(layout.width - p, p), c2 = toSheet(layout.width - p, layout.height - p), c3 = toSheet(p, layout.height - p);
+                const parts = [line(c0, c1, 40), line(c1, c2, 20), line(c2, c3, 40), line(c3, c0, 20)];
+                outline = new Float32Array(parts.reduce((n, a) => n + a.length, 0));
+                let o = 0;
+                for (const a of parts) {
+                    outline.set(a, o);
+                    o += a.length;
+                }
+                for (const l of layout.lines)
+                    baselines.push(line(toSheet(l.left, l.baseline), toSheet(l.left + l.width, l.baseline), 40));
+                const mid = mapSheet(cx, cy, [0, 0, 0]);
+                anchors.push(...mid, ...outline.subarray(0, 3));
+            }
+            guides = { folds, foldZones: zones, roll: rollLine, textOutline: outline, baselines, anchors: new Float32Array(anchors) };
+        }
+        const radius = def.frameRadius ?? (def.prop === 'bottle' ? 1.45 : 0.5 * Math.hypot(W, def.height) * 1.04);
+        return {
+            def, nu, nv, uvs, indices,
+            sheet: { positions: pos, normals: nrm, attrs },
+            stack, loose, text: textOut, prop,
+            bounds: { min, max }, tableZ,
+            target: [0, 0, (min[2] + max[2]) / 2],
+            radius, guides,
+        };
+    };
+    return {
+        def,
+        evaluate,
+        mapUv: (u, v, out = [0, 0, 0]) => mapSheet(u - 0.5, (0.5 - v) * Hs, out),
+    };
+}
+/** Which sheet vertex a text vertex sits on (exposed for tests: conformed text is the sheet). */
+export function textVertexOnSheet(geometry, textVertex) {
+    const t = geometry.text;
+    if (!t)
+        return -1;
+    // The text mesh is a sub-grid; recover its origin from its first uv.
+    const i0 = Math.round(t.uvs[0] * (geometry.nu - 1)), j0 = Math.round(t.uvs[1] * (geometry.nv - 1));
+    const iEnd = Math.round(t.uvs[(t.vertexCount - 1) * 2] * (geometry.nu - 1));
+    const ni = iEnd - i0 + 1;
+    const i = textVertex % ni, j = Math.floor(textVertex / ni);
+    return (j + j0) * geometry.nu + (i + i0);
+}
+//# sourceMappingURL=engine.js.map