@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/typesurface/shaders.ts

@@ -0,0 +1,303 @@
+/**
+ * **GLSL for the renderer.** Three programs:
+ *   surface  paper, pages, table and props: textured, lit by one key light with a soft shadow map,
+ *            a sky/ground ambient, cavity darkening in valleys and crease light along folds
+ *   text     the letters: alpha from the text raster, then the material. Floating, they are a flat
+ *            graphic; as they blend in they take the surface's light, then its colour (the blend
+ *            mode, against the paper under them), its grain, ragged edges, and a halftone screen
+ *   depth    the shadow pass (letters cast their shape while they float)
+ */
+export const COMMON = /* glsl */ `#version 300 es
+precision highp float;
+precision highp sampler2DShadow;
+uniform vec3 uLightDir;
+uniform vec3 uEye;
+uniform mat4 uLightVP;
+uniform sampler2DShadow uShadow;
+uniform vec3 uKey;
+uniform float uAmb;
+uniform vec3 uBackdrop;
+uniform vec3 uTarget;
+uniform float uRadius;
+
+vec3 toLin(vec3 c) { return pow(max(c, 0.0), vec3(2.2)); }
+vec3 toSrgb(vec3 c) { return pow(max(c, 0.0), vec3(1.0 / 2.2)); }
+vec3 tone(vec3 c) { c *= 0.92; return clamp((c * (2.51 * c + 0.03)) / (c * (2.43 * c + 0.59) + 0.14), 0.0, 1.0); }
+
+float shadowAt(vec3 wp, vec3 n) {
+  vec4 lp = uLightVP * vec4(wp + n * 0.003, 1.0);
+  vec3 c = lp.xyz / lp.w * 0.5 + 0.5;
+  if (c.x < 0.0 || c.x > 1.0 || c.y < 0.0 || c.y > 1.0 || c.z > 1.0) return 1.0;
+  vec2 texel = 1.0 / vec2(textureSize(uShadow, 0));
+  float s = 0.0;
+  for (int x = -2; x <= 2; x++) for (int y = -2; y <= 2; y++) s += texture(uShadow, vec3(c.xy + vec2(x, y) * texel * 1.5, c.z - 0.0012));
+  return s / 25.0;
+}
+
+vec3 shade(vec3 alb, vec3 n, vec3 wp, float cav, float spec, float rough, float translucency) {
+  float sh = shadowAt(wp, n);
+  float nl = dot(n, uLightDir);
+  float diff = max(nl, 0.0) * sh;
+  float back = max(-nl, 0.0) * translucency;
+  vec3 sky = vec3(0.66, 0.68, 0.74), gnd = vec3(0.3, 0.27, 0.23);
+  vec3 amb = mix(gnd, sky, n.z * 0.5 + 0.5) * (1.0 - max(cav, 0.0) * 0.6) * (0.75 + 0.25 * sh);
+  vec3 V = normalize(uEye - wp);
+  vec3 H = normalize(uLightDir + V);
+  float sp = pow(max(dot(n, H), 0.0), mix(6.0, 160.0, 1.0 - rough)) * spec * sh;
+  return alb * (uKey * (diff + back) + amb * uAmb) + uKey * sp;
+}
+
+/** A photo studio, as seen in a reflection: dim room, the key softbox toward the light, a long strip light opposite. */
+vec3 envAt(vec3 r) {
+  vec3 base = mix(vec3(0.05, 0.05, 0.055), vec3(0.42, 0.43, 0.45), smoothstep(-0.3, 0.9, r.z));
+  float key = smoothstep(0.9, 0.965, dot(r, uLightDir));
+  vec3 sd = normalize(vec3(0.72, -0.25, 0.64));
+  vec3 ax = normalize(cross(sd, vec3(0.0, 0.0, 1.0)));
+  float along = dot(r, ax);
+  float strip = smoothstep(0.975, 0.992, dot(normalize(r - ax * along), sd)) * (1.0 - smoothstep(0.4, 0.62, abs(along)));
+  return base + vec3(1.0, 0.98, 0.95) * key * 3.2 + vec3(0.95, 0.97, 1.0) * strip * 2.4;
+}
+float fresnel(float ndv, float f0) { return f0 + (1.0 - f0) * pow(1.0 - ndv, 5.0); }
+
+float hash12(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 vnoise(vec2 p) {
+  vec2 i = floor(p), f = fract(p); f = f * f * (3.0 - 2.0 * f);
+  return mix(mix(hash12(i), hash12(i + vec2(1, 0)), f.x), mix(hash12(i + vec2(0, 1)), hash12(i + vec2(1, 1)), f.x), f.y);
+}
+float fbm(vec2 p) { float s = 0.0, a = 0.5; for (int i = 0; i < 5; i++) { s += a * vnoise(p); p *= 2.03; a *= 0.5; } return s; }
+`;
+
+export const SURFACE_VS = /* glsl */ `#version 300 es
+layout(location = 0) in vec3 aPos;
+layout(location = 1) in vec3 aNrm;
+layout(location = 2) in vec2 aUv;
+layout(location = 3) in vec4 aAttr;
+uniform mat4 uVP;
+out vec3 vW; out vec3 vN; out vec2 vUv; out vec4 vAttr;
+void main() { vW = aPos; vN = aNrm; vUv = aUv; vAttr = aAttr; gl_Position = uVP * vec4(aPos, 1.0); }
+`;
+
+export const SURFACE_FS = COMMON + /* glsl */ `
+in vec3 vW; in vec3 vN; in vec2 vUv; in vec4 vAttr;
+uniform int uMode;          // 0 sheet, 1 table, 2 prop (bottle)
+uniform int uShading;       // 0 paper, 1 label, 2 film, 3 fabric
+uniform vec3 uPropColor;
+uniform vec3 uCapColor;
+uniform int uTable;         // 0 desk, 1 studio, 3 wood
+uniform sampler2D uFront;
+uniform sampler2D uBackTex;
+uniform sampler2D uGrain;
+uniform float uAspect;
+uniform float uSpec;
+uniform float uRough;
+uniform float uTranslucent;
+uniform int uDebug;         // 1 deformation, 2 mapping
+out vec4 outColor;
+
+vec3 tableColor(vec2 p) {
+  if (uTable == 0) {
+    float g = fbm(vec2(p.x * 1.2, p.y * 14.0) + fbm(p * 3.0) * 1.5);
+    float rings = sin((p.y * 26.0 + g * 6.0)) * 0.5 + 0.5;
+    return toLin(mix(vec3(0.20, 0.12, 0.07), vec3(0.34, 0.21, 0.12), g * 0.7 + rings * 0.3));
+  }
+  if (uTable == 3) {
+    float g = fbm(vec2(p.x * 1.0, p.y * 10.0) + fbm(p * 2.0));
+    return toLin(mix(vec3(0.46, 0.33, 0.21), vec3(0.62, 0.47, 0.31), g));
+  }
+  return toLin(uBackdrop * (0.96 + 0.06 * fbm(p * 4.0)));
+}
+
+void main() {
+  vec3 n = normalize(vN);
+  vec3 col;
+  if (uMode == 1) {
+    vec3 alb = tableColor(vW.xy);
+    col = shade(alb, vec3(0, 0, 1), vW, 0.0, 0.05, 0.8, 0.0);
+    vec3 disp = toSrgb(tone(col));
+    float f = smoothstep(uRadius * 1.3, uRadius * 3.2, length(vW.xy - uTarget.xy));
+    outColor = vec4(mix(disp, uBackdrop, f), 1.0);
+    return;
+  }
+  vec3 V = normalize(uEye - vW);
+  if (uMode == 2) {
+    float ndv = max(dot(n, V), 0.0);
+    vec3 R = reflect(-V, n);
+    if (vAttr.x < 0.5) {
+      // Dark glass: almost black body, the room in its reflection.
+      vec3 body = shade(toLin(uPropColor) * 0.55, n, vW, 0.0, 1.4, 0.04, 0.0);
+      col = body + envAt(R) * fresnel(ndv, 0.06) * 1.1;
+    } else {
+      // Foil capsule: coloured metal, crinkled.
+      vec3 c = toLin(uCapColor);
+      float crink = fbm(vec2(atan(vW.x, vW.z + 0.36) * 9.0, vW.y * 30.0)) - 0.5;
+      vec3 nb = normalize(n + vec3(crink * 0.25, 0.0, crink * 0.2));
+      col = shade(c * 0.3, nb, vW, 0.0, 0.8, 0.3, 0.0) + c * envAt(reflect(-V, nb)) * 0.7;
+    }
+    outColor = vec4(toSrgb(tone(col)), 1.0);
+    return;
+  }
+  bool front = gl_FrontFacing;
+  if (!front) n = -n;
+  vec2 uv = front ? vUv : vec2(1.0 - vUv.x, vUv.y);
+  vec4 tex = front ? texture(uFront, uv) : texture(uBackTex, uv);
+  if (tex.a < 0.5) discard;   // punched holes
+  vec3 alb = toLin(tex.rgb);
+  if (uMode == 0) {
+    float gr = texture(uGrain, vUv * vec2(5.0, 5.0 * uAspect)).r - 0.5;
+    alb *= 1.0 + gr * 0.1;
+    alb *= 1.0 - vAttr.x * 0.1;
+  }
+  if (uDebug == 1) alb = mix(vec3(0.05, 0.1, 0.6), vec3(1.0, 0.25, 0.05), clamp(vAttr.z * 6.0, 0.0, 1.0));
+  if (uDebug == 2) { vec2 c = floor(vUv * vec2(20.0, 20.0 * uAspect)); alb = mix(alb, mod(c.x + c.y, 2.0) < 1.0 ? vec3(0.9, 0.3, 0.3) : vec3(0.3, 0.5, 0.9), 0.55); }
+  float ndv = max(dot(n, V), 0.0);
+  col = shade(alb, n, vW, vAttr.y, uSpec, uRough, uTranslucent);
+  if (uShading == 1) col += envAt(reflect(-V, n)) * fresnel(ndv, 0.02) * 0.35;
+  if (uShading == 2) col += envAt(reflect(-V, n)) * fresnel(ndv, 0.07) * 0.9;
+  if (uShading == 3) col += alb * uKey * pow(1.0 - ndv, 3.0) * 0.45;
+  col += uKey * alb * vAttr.x * 0.05;
+  outColor = vec4(toSrgb(tone(col)), 1.0);
+}
+`;
+
+export const TEXT_VS = /* glsl */ `#version 300 es
+layout(location = 0) in vec3 aPos;
+layout(location = 1) in vec3 aNrm;
+layout(location = 2) in vec2 aUv;
+layout(location = 3) in vec4 aAttr;
+layout(location = 4) in vec2 aTuv;
+uniform mat4 uVP;
+out vec3 vW; out vec3 vN; out vec2 vUv; out vec4 vAttr; out vec2 vTuv;
+void main() { vW = aPos; vN = aNrm; vUv = aUv; vAttr = aAttr; vTuv = aTuv; gl_Position = uVP * vec4(aPos, 1.0); }
+`;
+
+/** The glyph remap (letters spread mid-morph) and alpha sampling, shared by text and its shadow. */
+const TEXT_ALPHA = /* glsl */ `
+uniform sampler2D uText;
+uniform vec2 uBlock;
+uniform float uGap;
+uniform vec4 uGlyphs[96];   // x0, x1, shift, _
+uniform vec4 uLines[8];     // top, _, first glyph, count
+uniform int uLineCount;
+
+// Returns the source point, and z = 0 when it falls outside the chosen letter (a neighbour's ink).
+vec3 remap(vec2 b) {
+  if (uGap <= 0.0) return vec3(b, 1.0);
+  int li = 0;
+  for (int k = 0; k < 8; k++) if (k < uLineCount && b.y >= uLines[k].x) li = k;
+  vec4 L = uLines[li];
+  int first = int(L.z), cnt = int(L.w);
+  float best = 1e9, shift = 0.0, x0 = 0.0, x1 = 0.0;
+  for (int i = 0; i < 96; i++) {
+    if (i >= cnt) break;
+    vec4 g = uGlyphs[first + i];
+    float d = abs(b.x - ((g.x + g.y) * 0.5 + g.z));
+    if (d < best) { best = d; shift = g.z; x0 = g.x; x1 = g.y; }
+  }
+  float sx = b.x - shift;
+  float m = (x1 - x0) * 0.06;
+  return vec3(sx, b.y, (sx >= x0 - m && sx <= x1 + m) ? 1.0 : 0.0);
+}
+float alphaAt(vec2 tc, float lod) {
+  if (tc.x < 0.0 || tc.y < 0.0 || tc.x > 1.0 || tc.y > 1.0) return 0.0;
+  return textureLod(uText, tc, lod).a;
+}
+`;
+
+export const TEXT_FS = COMMON + TEXT_ALPHA + /* glsl */ `
+in vec3 vW; in vec3 vN; in vec2 vUv; in vec4 vAttr; in vec2 vTuv;
+uniform sampler2D uPaper;
+uniform sampler2D uGrain;
+uniform float uAspect;
+uniform vec3 uColor; uniform vec3 uColor2; uniform float uGradOn; uniform float uGradAngle;
+uniform float uOpacity; uniform int uBlendMode; uniform int uMat;
+uniform float uBlendAmt, uInkStrength, uSpread, uRough, uPaperInf, uGrainInf, uHalftone, uDisp, uContrast, uGloss, uEmboss;
+uniform float uLod;
+out vec4 outColor;
+
+vec3 blendWith(vec3 b, vec3 s) {
+  if (uBlendMode == 1) return b * s;
+  if (uBlendMode == 2) return 1.0 - (1.0 - b) * (1.0 - s);
+  if (uBlendMode == 3) return mix(2.0 * b * s, 1.0 - 2.0 * (1.0 - b) * (1.0 - s), step(0.5, b));
+  if (uBlendMode == 4) return min(b, s);
+  if (uBlendMode == 5) return max(b, s);
+  if (uBlendMode == 6) return 1.0 - min(vec3(1.0), (1.0 - b) / max(s, vec3(0.001)));
+  if (uBlendMode == 7) return mix(2.0 * b * s + b * b * (1.0 - 2.0 * s), sqrt(b) * (2.0 * s - 1.0) + 2.0 * b * (1.0 - s), step(0.5, s));
+  return s;
+}
+
+void main() {
+  if (!gl_FrontFacing) discard;
+  float lit = smoothstep(0.0, 0.35, uBlendAmt);
+  float prn = smoothstep(0.25, 0.7, uBlendAmt);
+  float emb = smoothstep(0.6, 1.0, uBlendAmt);
+  float gr = texture(uGrain, vUv * vec2(9.0, 9.0 * uAspect)).r;
+  float gr2 = texture(uGrain, vUv * vec2(2.1, 2.1 * uAspect) + 0.37).r;
+  vec3 rm = remap(vTuv * uBlock);
+  vec2 b = rm.xy + (vec2(gr2, gr) - 0.5) * uDisp * prn;
+  vec2 tc = b / uBlock;
+  float a = alphaAt(tc, 0.0) * rm.z;
+  float ab = alphaAt(tc, uLod + 1.0 + uSpread * 2.0);
+  a = max(a, smoothstep(0.1, 0.6, ab) * uSpread * prn * 0.85 * rm.z);
+  // Ragged edges: noise only where the letter is partly covered.
+  float edge = 1.0 - abs(a * 2.0 - 1.0);
+  a = clamp(a + (gr - 0.5) * 2.2 * uRough * prn * edge, 0.0, 1.0);
+  // Paper tooth breaks the ink up.
+  a *= 1.0 - uGrainInf * prn * smoothstep(0.45, 0.85, 1.0 - gr) * 0.75;
+  if (uHalftone > 0.0 && emb > 0.0) {
+    vec2 hp = mat2(0.7071, -0.7071, 0.7071, 0.7071) * (vUv * vec2(1000.0, 1000.0 * uAspect)) / 3.6;
+    float d = length(fract(hp) - 0.5);
+    float r = sqrt(clamp(a * uInkStrength, 0.0, 1.0)) * 0.64;
+    float dotm = 1.0 - smoothstep(r - 0.07, r + 0.07, d);
+    a = mix(a, dotm * step(0.03, a), uHalftone * emb);
+  }
+  vec2 dir = vec2(cos(radians(uGradAngle)), sin(radians(uGradAngle)));
+  float gt = clamp(dot(vTuv - 0.5, dir) + 0.5, 0.0, 1.0);
+  vec3 base = mix(uColor, uColor2, uGradOn * gt);
+  vec3 col = toLin(base);
+  vec4 paperTex = texture(uPaper, vUv);
+  if (paperTex.a < 0.5 && lit > 0.5) discard;
+  vec3 paper = toLin(paperTex.rgb);
+  vec3 printed = mix(paper, blendWith(paper, col), uInkStrength);
+  col = mix(col, printed, prn * uPaperInf);
+  vec3 n = normalize(vN);
+  if (uEmboss > 0.0) {
+    float e = 1.5 / (uBlock.x);
+    float gx = alphaAt(tc + vec2(e * 2.0, 0.0), uLod + 1.0) - alphaAt(tc - vec2(e * 2.0, 0.0), uLod + 1.0);
+    float gy = alphaAt(tc + vec2(0.0, e * 2.0 * uBlock.x / uBlock.y), uLod + 1.0) - alphaAt(tc - vec2(0.0, e * 2.0 * uBlock.x / uBlock.y), uLod + 1.0);
+    vec3 t = normalize(dFdx(vW)), bt = normalize(dFdy(vW));
+    n = normalize(n - (t * gx - bt * gy) * uEmboss * emb * 0.8);
+  }
+  vec3 lit3 = shade(col, n, vW, vAttr.z, 0.03 + uGloss * 0.6, 1.0 - uGloss * 0.75, 0.2);
+  lit3 *= 1.0 - vAttr.y * 0.12 * lit;
+  vec3 Vt = normalize(uEye - vW);
+  lit3 += envAt(reflect(-Vt, n)) * fresnel(max(dot(n, Vt), 0.0), 0.04) * uGloss * 0.8;
+  vec3 disp = mix(base, toSrgb(tone(lit3)), clamp(lit * uContrast, 0.0, 1.0));
+  outColor = vec4(disp, a * uOpacity);
+}
+`;
+
+export const DEPTH_VS = /* glsl */ `#version 300 es
+layout(location = 0) in vec3 aPos;
+layout(location = 3) in vec4 aAttr;
+layout(location = 4) in vec2 aTuv;
+uniform mat4 uVP;
+out vec2 vTuv; out float vConform;
+void main() { vTuv = aTuv; vConform = aAttr.x; gl_Position = uVP * vec4(aPos, 1.0); }
+`;
+
+export const DEPTH_FS = /* glsl */ `#version 300 es
+precision highp float;
+` + TEXT_ALPHA + /* glsl */ `
+in vec2 vTuv; in float vConform;
+uniform int uIsText;
+uniform float uCast;
+out vec4 outColor;
+void main() {
+  if (uIsText == 1) {
+    if (vConform > 0.97) discard;
+    vec3 b = remap(vTuv * uBlock);
+    if (alphaAt(b.xy / uBlock, 0.0) * b.z * uCast < 0.4) discard;
+  }
+  outColor = vec4(1.0);
+}
+`;

package/src/motion/typesurface/surfaces.ts

@@ -0,0 +1,223 @@
+/* eslint-disable comppack/no-raw-colour -- paper, film, cloth and backdrop colours are surface artwork, not theme colours. */
+/**
+ * **Surfaces** — the physical things text meets. A surface is data: its size, how finely it is
+ * meshed, which artwork paints it, how it shades, and its named states. Only a few have their own
+ * shape (a pillow pack inflates, cloth drapes); everything else, folds, rolls,
+ * cylinders and crumples, comes from the shared operators in `ops.ts`, so a new surface gets every
+ * transformation, and the text on it, without touching the typography.
+ *
+ * To add one: `registerSurface({ id, name, width, height, grid, art, shading, table, states, … })`.
+ * Its `id` becomes a valid `surface.type`, and the renderer paints it with the named `art` (or a
+ * plain colour if it has no painter). Pure; no React.
+ */
+import type { TSDeformation, TSMaterial, TSSurfaceType, TSView } from './config';
+import { smoothstep, type Vec3 } from './ops';
+
+/** How the substrate itself shades. The renderer maps each to a lighting model. */
+export type SurfaceShading = 'newsprint' | 'paper' | 'label' | 'film' | 'fabric';
+/** What the object lies on. */
+export type TableStyle = 'desk' | 'studio' | 'wood';
+
+type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+
+export type SurfaceState = { label: string; deformation: DeepPartial<TSDeformation>; view?: Partial<TSView> };
+
+export type SurfaceDef = {
+  id: string;
+  name: string;
+  blurb: string;
+  /** World units. The text's surface units map 1000 → `width`. */
+  width: number;
+  height: number;
+  /** Mesh vertices across and down. Enough for a crease a few cells wide. */
+  grid: [number, number];
+  /** The artwork painter (`art.ts`). An unknown name paints `color`. */
+  art: string;
+  shading: SurfaceShading;
+  table: TableStyle;
+  /** Backdrop gradient, top → bottom. */
+  backdrop: [string, string];
+  /** The surface's own colour where the artwork uses one (film, cloth). */
+  color: string;
+  /** The text material that suits it, and any material defaults. */
+  material: Partial<TSMaterial> & { type: TSMaterial['type'] };
+  /** `curve` wraps a cylinder of this radius (world) at 1… */
+  curveRadius: number;
+  /** …or, for a pack, inflates it (`shape` reads `curve`). */
+  curveMode: 'cylinder' | 'inflate';
+  /** Loose sheets stacked under this one (a newspaper's pages). */
+  stack?: { sheets: number; gap: number };
+  /** Another page lying on the table under it. */
+  looseSheet?: boolean;
+  /** A solid object the surface is wrapped on. */
+  prop?: 'bottle';
+  /** How much fine wrinkles lift the surface, as a share of its width. */
+  wrinkleDepth: number;
+  /** The surface's own shape, before the shared operators. `x, y` are sheet units (1 wide). */
+  shape?: (p: Vec3, x: number, y: number, d: TSDeformation, timeMs: number, motion: number) => void;
+  states: Record<string, SurfaceState>;
+  defaultState: string;
+  /** Degrees of camera tilt at perspective 0 and 1. */
+  camera: { flat: number; deep: number };
+};
+
+/* ---------------- shapes ---------------- */
+
+/** A newspaper remembers the fold it was delivered in: a faint ridge across the middle. */
+const newspaperShape: SurfaceDef['shape'] = (p, _x, y) => {
+  p[2] += 0.0035 * (1 - smoothstep(0, 0.035, Math.abs(y)));
+};
+
+/** A pillow pack: inflated body, flat crimped seals at both ends, film gathered into ribs near them. */
+const wrapperShape: SurfaceDef['shape'] = (p, x, y, d) => {
+  const X = x / 0.5; // −1…1 across
+  const Y = y / (0.8 / 1.4 / 2); // −1…1 down (height/width = 0.8/1.4)
+  const ax = Math.abs(X);
+  const a = d.curve;
+  const body = 1 - smoothstep(0.7, 0.9, ax);
+  const seal = smoothstep(0.86, 0.92, ax);
+  const prof = Math.pow(Math.max(0, 1 - Y * Y), 0.62);
+  p[2] += a * 0.085 * prof * body;
+  // Inflation pulls the film in from the edges; the seals stay full height.
+  p[1] *= 1 - a * 0.12 * body * (1 - Y * Y * 0.3);
+  p[0] *= 1 - a * 0.035;
+  // Film gathered between body and seal: ribs that run toward the seal.
+  const gather = smoothstep(0.55, 0.8, ax) * (1 - seal);
+  p[2] += (a * 0.8 + d.wrinkle * 0.6) * 0.012 * gather * Math.sin(Y * 11 + x * 3) * (0.6 + 0.4 * Math.sin(Y * 23.7 + 1.3));
+  // The crimped seal: a fine serration.
+  p[2] += seal * 0.0045 * Math.sin(Y * 70);
+};
+
+/** Cloth: rounded folds that mostly share a direction, gathering the cloth, drifting in a breeze. */
+const fabricShape: SurfaceDef['shape'] = (p, x, y, d, timeMs, motion) => {
+  const w = d.wave;
+  if (w <= 0) return;
+  const t = (timeMs / 1000) * motion;
+  const folds: [number, number, number, number, number][] = [
+    // angle, frequency, amplitude, phase, drift
+    [1.35, 6.2, 1, 0.3, 0.35], [1.62, 9.4, 0.55, 1.7, -0.25], [1.1, 4.1, 0.8, 2.2, 0.18], [0.35, 7.3, 0.35, 0.9, 0.3],
+  ];
+  let z = 0;
+  let gx = 0, gy = 0;
+  for (const [ang, f, amp, ph, drift] of folds) {
+    const dx = Math.cos(ang), dy = Math.sin(ang);
+    const s = (x * dx + y * dy) * f * 2.4 + ph + t * drift + 0.6 * Math.sin(x * 2.3 - y * 1.7 + ph);
+    const ridge = Math.pow(0.5 + 0.5 * Math.cos(s), 1.6);
+    z += amp * ridge;
+    gx += dx * amp * 0.5; gy += dy * amp * 0.5;
+  }
+  p[2] += w * 0.034 * z;
+  // Folds take up cloth across them.
+  const take = w * 0.05;
+  p[0] -= take * x * Math.abs(gx) * 0.5;
+  p[1] -= take * y * Math.abs(gy) * 0.5;
+};
+
+/* ---------------- states ---------------- */
+
+const s = (label: string, deformation: SurfaceState['deformation'], view?: Partial<TSView>): SurfaceState => ({ label, deformation, view });
+
+const PAPER_STATES: Record<string, SurfaceState> = {
+  flat: s('Flat', {}),
+  folded: s('Folded', { fold: { amount: 1, position: 0.5, direction: 'under', orientation: 'horizontal' } }),
+  'double-folded': s('Double folded', { fold: { amount: 1, position: 0.5, direction: 'under', orientation: 'horizontal' }, fold2: { amount: 1, position: 0.5, direction: 'under', orientation: 'vertical' } }),
+  rolled: s('Rolled', { roll: { amount: 1, edge: 'bottom', direction: 'under' } }),
+  'partially-folded': s('Partially folded', { fold: { amount: 0.55, position: 0.52, direction: 'over', orientation: 'vertical' } }),
+  'letter-folded': s('Letter folded (3 panels)', {
+    fold: { amount: 1, position: 0.667, direction: 'over', orientation: 'horizontal', side: 'far', width: 0.02 },
+    fold2: { amount: 1, position: 0.333, direction: 'over', orientation: 'horizontal', side: 'near', width: 0.02 },
+  }),
+  'folded-in-four': s('Folded four times', {
+    fold: { amount: 1, position: 0.5, direction: 'under', orientation: 'horizontal', width: 0.02 },
+    fold2: { amount: 1, position: 0.5, direction: 'under', orientation: 'vertical', width: 0.02 },
+    fold3: { amount: 1, position: 0.25, direction: 'under', orientation: 'vertical', side: 'near', width: 0.02 },
+    fold4: { amount: 0.5, position: 0.25, direction: 'over', orientation: 'horizontal', side: 'near', width: 0.02 },
+  }),
+  'wrapped-rod': s('Wrapped on rods', {
+    wrap1: { amount: 1, position: 0.78, radius: 0.05, angle: 200, direction: 'under', orientation: 'vertical', side: 'far' },
+    wrap2: { amount: 1, position: 0.22, radius: 0.05, angle: 200, direction: 'under', orientation: 'vertical', side: 'near' },
+  }),
+  crumpled: s('Crumpled', { crumple: { amount: 0.5 } }),
+  'heavily-crumpled': s('Heavily crumpled', { crumple: { amount: 1 } }),
+};
+
+/* ---------------- the built-in surfaces ---------------- */
+
+const newspaper: SurfaceDef = {
+  id: 'newspaper', name: 'Newspaper', blurb: 'A broadsheet page on a stack of pages: columns, photos, ads, grain and the fold it was delivered in.',
+  width: 1, height: 1.36, grid: [160, 218], art: 'newspaper', shading: 'newsprint', table: 'desk', backdrop: ['#2b2723', '#15130f'],
+  color: '#ECE6D6', material: { type: 'ink', halftone: 0.35 }, curveRadius: 0.16, curveMode: 'cylinder',
+  stack: { sheets: 2, gap: 0.0026 }, looseSheet: true, wrinkleDepth: 0.02, shape: newspaperShape,
+  states: PAPER_STATES, defaultState: 'flat', camera: { flat: 0, deep: 56 },
+};
+
+const paper: SurfaceDef = {
+  id: 'paper', name: 'Paper', blurb: 'A plain letter sheet: fine tooth, a watermark, nothing printed but your words.',
+  width: 0.85, height: 1.1, grid: [140, 182], art: 'paper', shading: 'paper', table: 'wood', backdrop: ['#2f2a25', '#171411'],
+  color: '#F6F1E6', material: { type: 'ink', halftone: 0 }, curveRadius: 0.14, curveMode: 'cylinder', wrinkleDepth: 0.02,
+  states: PAPER_STATES, defaultState: 'flat', camera: { flat: 0, deep: 54 },
+};
+
+const bottle: SurfaceDef = {
+  id: 'bottle', name: 'Bottle', blurb: 'A paper label on a dark glass wine bottle: the label wraps the cylinder, the text wraps with it.',
+  width: 1.81, height: 0.86, grid: [220, 96], art: 'label', shading: 'label', table: 'studio', backdrop: ['#d9dadc', '#b9bbbf'],
+  color: '#1A1512', material: { type: 'print', halftone: 0, grainInfluence: 0.25, paperInfluence: 0.35 }, curveRadius: 0.3625, curveMode: 'cylinder',
+  prop: 'bottle', wrinkleDepth: 0.004,
+  states: {
+    flat: s('Flat label', {}),
+    curved: s('Curving', { curve: 0.5 }),
+    wrapped: s('Wrapped', { curve: 1 }),
+    lying: s('Lying on the table', { curve: 1 }, { roll: -28 }),
+  },
+  defaultState: 'wrapped', camera: { flat: 0, deep: 48 },
+};
+
+const wrapper: SurfaceDef = {
+  id: 'wrapper', name: 'Wrapper', blurb: 'A glossy pillow pack: an inflated body, crimped seals, film gathered into ribs.',
+  width: 1.4, height: 0.8, grid: [210, 120], art: 'wrapper', shading: 'film', table: 'studio', backdrop: ['#e8e2d8', '#c8c0b2'],
+  color: '#F2B705', material: { type: 'print', halftone: 0, grainInfluence: 0.1, paperInfluence: 0.25, gloss: 0.7 }, curveRadius: 0.4, curveMode: 'inflate',
+  wrinkleDepth: 0.012, shape: wrapperShape,
+  states: {
+    flat: s('Flat film', {}),
+    pillow: s('Inflated', { curve: 1 }),
+    folded: s('Folded end', { curve: 0.8, fold: { amount: 0.85, position: 0.8, angle: 160, direction: 'under', width: 0.05 } }),
+    wrinkled: s('Wrinkled', { curve: 1, wrinkle: 0.9, crumple: { amount: 0.12, scale: 0.7 } }),
+  },
+  defaultState: 'pillow', camera: { flat: 0, deep: 52 },
+};
+
+const fabric: SurfaceDef = {
+  id: 'fabric', name: 'Fabric', blurb: 'Woven cotton lying in soft folds that drift in a breeze; the print moves with the cloth.',
+  width: 1.4, height: 1.1, grid: [180, 142], art: 'fabric', shading: 'fabric', table: 'wood', backdrop: ['#28231e', '#12100d'],
+  color: '#2F4A73', material: { type: 'print', halftone: 0, grainInfluence: 0.6, paperInfluence: 0.45, inkRoughness: 0.55 }, curveRadius: 0.3, curveMode: 'cylinder',
+  wrinkleDepth: 0.018, shape: fabricShape,
+  states: {
+    flat: s('Laid flat', {}),
+    draped: s('Soft folds', { wave: 0.7 }),
+    folded: s('Folded over', { wave: 0.45, fold: { amount: 0.8, position: 0.66, angle: 170, width: 0.07, direction: 'over' } }),
+    creased: s('Creased', { wave: 0.5, wrinkle: 0.8, crumple: { amount: 0.2, scale: 1.3 } }),
+  },
+  defaultState: 'draped', camera: { flat: 0, deep: 52 },
+};
+
+const BUILT_IN: SurfaceDef[] = [newspaper, paper, bottle, wrapper, fabric];
+const REGISTRY = new Map<string, SurfaceDef>(BUILT_IN.map((d) => [d.id, d]));
+
+/** The built-in surfaces, by id. */
+export const SURFACES: Readonly<Record<TSSurfaceType, SurfaceDef>> = Object.fromEntries(BUILT_IN.map((d) => [d.id, d])) as Record<TSSurfaceType, SurfaceDef>;
+
+/** Add (or replace) a surface. Its id becomes a valid `surface.type`. */
+export function registerSurface(def: SurfaceDef): SurfaceDef {
+  REGISTRY.set(def.id, def);
+  return def;
+}
+/** A surface by id; unknown ids fall back to the newspaper so something always draws. */
+export function getSurface(id: string): SurfaceDef {
+  return REGISTRY.get(id) ?? newspaper;
+}
+export function hasSurface(id: string): boolean {
+  return REGISTRY.has(id);
+}
+export function listSurfaces(): SurfaceDef[] {
+  return [...REGISTRY.values()];
+}

package/src/motion/typesurface/text.ts

@@ -0,0 +1,35 @@
+/**
+ * **The text raster.** The layout (`layout.ts`) drawn into a canvas as white letters on nothing:
+ * an alpha mask. Colour, gradient, blend mode and ink are applied by the renderer on top of it,
+ * so changing a colour never repaints, and changing a word repaints only this. Live fonts; never
+ * outlines. Browser-only; no React.
+ */
+import type { TSTypography } from './config';
+import type { TSMeasurer, TSTextLayout } from './layout';
+
+export const cssFont = (t: TSTypography, px: number) => `${t.fontStyle} ${t.fontWeight} ${px}px ${t.fontFamily}`;
+
+let measureCtx: CanvasRenderingContext2D | null = null;
+/** Width in surface units, measured by the browser at 100 px and scaled. */
+export const canvasMeasurer: TSMeasurer = (text, t) => {
+  measureCtx ??= document.createElement('canvas').getContext('2d');
+  if (!measureCtx) return text.length * t.fontSize * 0.55;
+  measureCtx.font = cssFont(t, 100);
+  return (measureCtx.measureText(text).width / 100) * t.fontSize;
+};
+
+/** Paint the layout. `maxPx` caps the longer side; returns the canvas and its pixels per unit. */
+export function rasterText(layout: TSTextLayout, t: TSTypography, maxPx = 2048): { canvas: HTMLCanvasElement; ppu: number } {
+  const ppu = Math.min(4, maxPx / layout.width, maxPx / 2 / layout.height);
+  const c = document.createElement('canvas');
+  c.width = Math.max(4, Math.ceil(layout.width * ppu));
+  c.height = Math.max(4, Math.ceil(layout.height * ppu));
+  const ctx = c.getContext('2d')!;
+  ctx.fillStyle = 'white';
+  ctx.font = cssFont(t, t.fontSize * ppu);
+  ctx.textBaseline = 'alphabetic';
+  for (const line of layout.lines) {
+    for (const g of line.glyphs) if (g.ch !== ' ') ctx.fillText(g.ch, g.x0 * ppu, line.baseline * ppu);
+  }
+  return { canvas: c, ppu };
+}

package/src/motion/typesurface/timeline.ts

@@ -0,0 +1,58 @@
+/**
+ * **The transformation timeline.** A config says how FAR each transformation goes (its sliders);
+ * its stages say WHEN. At progress p (0–1) a driven amount is `value × envelope(p)`: the envelope
+ * rises 0 → 1 between `start` and `end` and, for a stage with `outStart`/`outEnd`, falls back.
+ * Envelopes are eased and continuous, so scrubbing never jumps. Amounts no stage drives stay at
+ * their slider value the whole time.
+ */
+import { ease } from '../easing';
+import { getPath, setPath, TS_ANIMATABLE_PATHS, type TSAnimatable, type TSStage, type TypeSurfaceConfig } from './config';
+
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+const ramp = (p: number, a: number, b: number) => (b <= a ? (p >= b ? 1 : 0) : clamp01((p - a) / (b - a)));
+
+/** 0–1: how far one stage has gone at progress `p`. */
+export function stageEnvelope(stage: TSStage, p: number): number {
+  const curve = stage.easing ?? 'ease-in-out';
+  const up = ease(curve, ramp(p, stage.start, stage.end));
+  if (stage.outStart === undefined || stage.outEnd === undefined) return up;
+  return up * (1 - ease(curve, ramp(p, stage.outStart, stage.outEnd)));
+}
+
+/**
+ * The envelope of every driven amount at `p`. Several stages on one key combine by maximum, so a
+ * fold can come in, go out, and come in again.
+ */
+export function envelopes(stages: readonly TSStage[], p: number): Partial<Record<TSAnimatable, number>> {
+  const out: Partial<Record<TSAnimatable, number>> = {};
+  for (const s of stages) out[s.key] = Math.max(out[s.key] ?? 0, stageEnvelope(s, p));
+  return out;
+}
+
+/** The config as drawn at progress `p`: every driven amount scaled by its stage. Pure. */
+export function configAt(config: TypeSurfaceConfig, p: number): TypeSurfaceConfig {
+  const env = envelopes(config.animation.stages, clamp01(p));
+  let out = config;
+  for (const [key, k] of Object.entries(env) as [TSAnimatable, number][]) {
+    const path = TS_ANIMATABLE_PATHS[key];
+    const v = getPath(config, path);
+    if (typeof v === 'number') out = setPath(out, path, v * k);
+  }
+  return out;
+}
+
+/** The ordered labels a timeline shows: "FLAT → WRAP → FOLD → CRUMPLE → PRINT". */
+export function stageLabels(stages: readonly TSStage[]): string[] {
+  return ['flat', ...[...stages].sort((a, b) => a.start - b.start).map((s) => s.label ?? s.key)];
+}
+
+/** Which stage is moving at `p` (for the playground's readout); null between stages. */
+export function activeStage(stages: readonly TSStage[], p: number): TSStage | null {
+  let best: TSStage | null = null;
+  for (const s of stages) {
+    const inRamp = p >= s.start && p <= s.end;
+    const outRamp = s.outStart !== undefined && s.outEnd !== undefined && p >= s.outStart && p <= s.outEnd;
+    if ((inRamp || outRamp) && (!best || s.start > best.start)) best = s;
+  }
+  return best;
+}