@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/typesurface/engine.ts

@@ -0,0 +1,586 @@
+/**
+ * **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, type TSFold, type TSWrap, type TypeSurfaceConfig } from './config';
+import { glyphAt, morphGap, type TSTextLayout } from './layout';
+import { bend, bendDistance, crumpleCreases, crumpleField, cylinder, roll, rotate, smoothstep, type Bend, type Crease, type Roll, type Vec3 } from './ops';
+import type { SurfaceDef } from './surfaces';
+
+const DEG = Math.PI / 180;
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+const sstep = (v: number) => { const t = clamp01(v); return t * t * (3 - 2 * t); };
+
+export type TextMesh = {
+  positions: Float32Array;
+  normals: Float32Array;
+  /** The sheet's uv under each vertex: the text samples the paper it sits on. */
+  uvs: Float32Array;
+  /** Block coordinates, 0–1 across and down the text block. */
+  tuv: Float32Array;
+  /** Per vertex: conform (0 floating … 1 on the surface), crease light, cavity, flight. */
+  attrs: Float32Array;
+  indices: Uint32Array;
+  vertexCount: number;
+  indexCount: number;
+  /** Changes whenever `indices` does. */
+  indexVersion: number;
+};
+
+export type PropMesh = { positions: Float32Array; normals: Float32Array; attrs: Float32Array; indices: Uint32Array; vertexCount: number };
+
+export type Guides = {
+  folds: Float32Array[];
+  foldZones: Float32Array[];
+  roll: Float32Array | null;
+  textOutline: Float32Array | null;
+  baselines: Float32Array[];
+  /** Control points: text anchor and corners, crease ends. xyz triples. */
+  anchors: Float32Array;
+};
+
+export type SceneGeometry = {
+  def: SurfaceDef;
+  nu: number;
+  nv: number;
+  /** Sheet uv (static) and triangles (static). */
+  uvs: Float32Array;
+  indices: Uint32Array;
+  sheet: { positions: Float32Array; normals: Float32Array; attrs: Float32Array };
+  stack: Float32Array[];
+  loose: { positions: Float32Array; normals: Float32Array; uvs: Float32Array; indices: Uint32Array } | null;
+  text: TextMesh | null;
+  prop: PropMesh | null;
+  bounds: { min: Vec3; max: Vec3 };
+  tableZ: number;
+  target: Vec3;
+  /** Radius that frames the surface at rest (camera fit). */
+  radius: number;
+  guides: Guides | null;
+};
+
+export type GeometryEngine = {
+  def: SurfaceDef;
+  evaluate(config: TypeSurfaceConfig, timeMs: number, layout: TSTextLayout | null, opts?: { guides?: boolean }): SceneGeometry;
+  /** A sheet point (u, v in 0–1, v down) where it is right now, in world space. */
+  mapUv(u: number, v: number, out?: Vec3): Vec3;
+};
+
+type BendSpec = { b: Bend; infl: number; zone: number };
+
+/** Normals by central differences over a grid, and cavity (how much a vertex sits in a valley). */
+function gridNormals(pos: Float32Array, nrm: Float32Array, ni: number, nj: number, cav: Float32Array | null, cavStride: number, cavOffset: number, h: number): void {
+  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: number, nj: number, i0: number, j0: number, out?: Uint32Array): Uint32Array {
+  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: number, axis: number): { positions: Float32Array; normals: Float32Array; attrs: Float32Array; indices: Uint32Array; count: number } {
+  // (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: [number, number][] = [
+    [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: [number, number][] = [];
+  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: number[] = [];
+  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: SurfaceDef): GeometryEngine {
+  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<string, { creases: Crease[]; full: Float32Array; fine: Float32Array }>();
+  const fieldFor = (seed: number, scale: number) => {
+    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: Vec3 = [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: TextMesh = {
+    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 = '';
+
+  const bottle = def.prop === 'bottle' ? bottleMesh(def.curveRadius - 0.0025, def.curveRadius) : null;
+  const prop: PropMesh | null = bottle
+    ? { positions: new Float32Array(bottle.count * 3), normals: new Float32Array(bottle.count * 3), attrs: bottle.attrs, indices: bottle.indices, vertexCount: bottle.count }
+    : null;
+
+  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: [] as BendSpec[], roll: null as Roll | null, kappa: 0, spin: 0,
+    rotA: 0, rotB: 0, rotC: 0, shiftX: 0, shiftY: 0,
+    creases: [] as Crease[],
+  };
+
+  /** One sheet point through the surface's operators (before the object's rigid turns). Returns crease light. */
+  const pipe = (x0: number, y0: number, fx: number, fy: number, fz: number, gz: number, p: Vec3): number => {
+    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 (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: Vec3) => {
+    rotate(p, F.rotA, F.rotB, F.rotC);
+    p[0] += F.shiftX; p[1] += F.shiftY;
+  };
+
+  const fieldAt = (x0: number, y0: number, o: Vec3, g: Vec3) => {
+    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: number, y0: number, out: Vec3): Vec3 => {
+    const o: Vec3 = [0, 0, 0], g: Vec3 = [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: number, orientation: TSFold['orientation'], side: TSFold['side'], shrink: number) => {
+    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: TSFold, shrink: number): BendSpec | null => {
+    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: Bend = { ...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: TSWrap, shrink: number): BendSpec | null => {
+    if (w.amount <= 0.0005) return null;
+    const turn = w.angle * w.amount * DEG;
+    const theta = turn * (w.direction === 'over' ? 1 : -1);
+    const b: Bend = { ...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: Vec3 = [0, 0, 0];
+
+  const evaluate: GeometryEngine['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 is BendSpec => !!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: Roll | null = 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: def.prop === 'bottle' ? 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: Vec3 = [Infinity, Infinity, Infinity], max: Vec3 = [-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]!;
+        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]!;
+        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: number, e: number) => {
+            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: [number, number][] = [[-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: TextMesh | null = 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]] as const) {
+        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: Guides | null = null;
+    if (opts?.guides) {
+      const line = (from: [number, number], to: [number, number], steps = 80) => {
+        const out = new Float32Array((steps + 1) * 3);
+        const p: Vec3 = [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: Float32Array[] = [], zones: Float32Array[] = [];
+      const anchors: number[] = [];
+      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: Float32Array | null = 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: Float32Array | null = null;
+      const baselines: Float32Array[] = [];
+      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: number, by: number): [number, number] => [
+          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.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: SceneGeometry, textVertex: number): number {
+  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);
+}

package/src/motion/typesurface/fonts.ts

@@ -0,0 +1,63 @@
+/**
+ * **Fonts for the lab.** Seven categories, because deformation reads differently on each: a thin
+ * serif's hairlines vanish into a crease where a condensed display face's slabs don't, and a
+ * monospace line lands letter by letter at an even beat. The page loads them with one Google Fonts
+ * stylesheet (`typeSurfaceFontsUrl`); the artwork's own faces (masthead, body copy) are in it too.
+ */
+export type TSFontCategory = 'sans' | 'serif' | 'condensed' | 'display' | 'italic' | 'mono' | 'decorative';
+
+export type TSFont = {
+  id: string;
+  name: string;
+  category: TSFontCategory;
+  /** CSS font-family list. */
+  family: string;
+  weights: number[];
+  italic: boolean;
+  /** Google Fonts css2 `family=` value. */
+  google: string;
+};
+
+const f = (id: string, name: string, category: TSFontCategory, fallback: string, weights: number[], italic: boolean): TSFont => {
+  const plus = name.replace(/ /g, '+');
+  const google = weights.length === 1 && !italic
+    ? plus
+    : italic
+      ? `${plus}:ital,wght@${[...weights.map((w) => `0,${w}`), ...weights.map((w) => `1,${w}`)].join(';')}`
+      : `${plus}:wght@${weights.join(';')}`;
+  return { id, name, category, family: `'${name}', ${fallback}`, weights, italic, google };
+};
+
+export const TS_FONT_CATEGORIES: Record<TSFontCategory, string> = {
+  sans: 'Sans serif', serif: 'Serif', condensed: 'Condensed', display: 'Bold display', italic: 'Italic', mono: 'Monospace', decorative: 'Decorative',
+};
+
+export const TS_FONTS: TSFont[] = [
+  f('inter', 'Inter', 'sans', 'system-ui, sans-serif', [400, 600, 800, 900], false),
+  f('archivo-black', 'Archivo Black', 'sans', 'Arial Black, sans-serif', [400], false),
+  f('playfair', 'Playfair Display', 'serif', 'Georgia, serif', [400, 700, 900], true),
+  f('old-standard', 'Old Standard TT', 'serif', 'Times New Roman, serif', [400, 700], true),
+  f('anton', 'Anton', 'condensed', 'Impact, sans-serif', [400], false),
+  f('oswald', 'Oswald', 'condensed', 'Arial Narrow, sans-serif', [300, 500, 700], false),
+  f('bebas', 'Bebas Neue', 'condensed', 'Impact, sans-serif', [400], false),
+  f('abril', 'Abril Fatface', 'display', 'Georgia, serif', [400], false),
+  f('dm-serif', 'DM Serif Display', 'display', 'Georgia, serif', [400], true),
+  f('libre-baskerville', 'Libre Baskerville', 'italic', 'Georgia, serif', [400, 700], true),
+  f('ibm-plex-mono', 'IBM Plex Mono', 'mono', 'ui-monospace, monospace', [400, 700], true),
+  f('space-mono', 'Space Mono', 'mono', 'ui-monospace, monospace', [400, 700], false),
+  f('lobster', 'Lobster', 'decorative', 'cursive', [400], false),
+  f('permanent-marker', 'Permanent Marker', 'decorative', 'cursive', [400], false),
+  f('unifraktur', 'UnifrakturMaguntia', 'decorative', 'serif', [400], false),
+  f('monoton', 'Monoton', 'decorative', 'cursive', [400], false),
+];
+
+/** Find a font by id, name or family ("Anton", "anton", "'Anton', Impact"). */
+export function findTypeSurfaceFont(q: string): TSFont | undefined {
+  const s = q.trim().toLowerCase().replace(/^'|'.*$/g, '');
+  return TS_FONTS.find((x) => x.id === s || x.name.toLowerCase() === s || x.family.toLowerCase().startsWith(`'${s}'`));
+}
+
+/** One stylesheet URL for every lab font. */
+export function typeSurfaceFontsUrl(): string {
+  return `https://fonts.googleapis.com/css2?${TS_FONTS.map((x) => `family=${x.google}`).join('&')}&display=swap`;
+}

package/src/motion/typesurface/index.ts

@@ -0,0 +1,16 @@
+/**
+ * **Typography × surface** — text that physically meets a surface: it wraps, morphs, folds,
+ * crumples, rolls and finally prints into the material. `docs/TYPE-SURFACE.md`.
+ *
+ *   text → layout (TextGeometry) → surface pipeline (SurfaceMapping) → deformation → material → renderer
+ */
+export * from './config';
+export { stageEnvelope, envelopes, configAt, stageLabels, activeStage } from './timeline';
+export { bend, bendDistance, roll, cylinder, crumpleCreases, crumpleField, rotate, smoothstep, type Bend, type Roll, type Crease, type Vec3 } from './ops';
+export { SURFACES, registerSurface, getSurface, hasSurface, listSurfaces, type SurfaceDef, type SurfaceState, type SurfaceShading, type TableStyle } from './surfaces';
+export { layoutText, estimateMeasurer, morphGap, glyphShift, glyphAt, type TSMeasurer, type TSGlyph, type TSLine, type TSTextLayout } from './layout';
+export { createGeometryEngine, textVertexOnSheet, type GeometryEngine, type SceneGeometry, type TextMesh, type PropMesh, type Guides } from './engine';
+export { TYPE_SURFACE_PRESETS, findTypeSurfacePreset, applySurfaceState, switchSurface, createTypeSurface, type TypeSurfacePreset, type TypeSurfaceShorthand } from './presets';
+export { TS_FONTS, TS_FONT_CATEGORIES, findTypeSurfaceFont, typeSurfaceFontsUrl, type TSFont, type TSFontCategory } from './fonts';
+export { TypeSurfaceRenderer, drawDebugOverlay, cameraFor, type TSDebug } from './renderer';
+export { TypeSurfaceCanvas, type TypeSurfaceCanvasProps } from './TypeSurfaceCanvas';