@appinternalleads/ui 0.4.0 → 0.4.2

package/src/motion/typesurface/index.ts

@@ -0,0 +1,20 @@
+/**
+ * **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
+ *
+ * The text meets a built-in surface, or an object composed from primitives (`construct.ts`):
+ * `describeConstruction()` is the manifest an agent reads to build one.
+ */
+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 * from './construct';
+export { SURFACES, registerSurface, getSurface, hasSurface, listSurfaces, objectSurface, surfaceFor, 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 PropRange, type Guides } from './engine';
+export { TYPE_SURFACE_PRESETS, findTypeSurfacePreset, applySurfaceState, switchSurface, withObject, fitObjectText, 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';

package/src/motion/typesurface/layout.ts

@@ -0,0 +1,133 @@
+/**
+ * **Text geometry.** The text is laid out once into a block (surface units): lines, and each
+ * glyph's box on its line. The raster draws exactly this layout, and the mesh uses the glyph boxes
+ * to land letters one by one (morph) and to spread them apart mid-morph. Kerning is kept: a
+ * glyph's position is the width of everything before it on the line. Pure; the width of a string
+ * comes from a measurer (a canvas in the browser, an estimate on a server).
+ */
+import type { TSTypography } from './config';
+
+/** Width of `text` in surface units at `typography.fontSize`, letter spacing excluded. */
+export type TSMeasurer = (text: string, typography: TSTypography) => number;
+
+export type TSGlyph = { ch: string; x0: number; x1: number; order: number };
+export type TSLine = { text: string; glyphs: TSGlyph[]; left: number; width: number; top: number; baseline: number; bottom: number };
+export type TSTextLayout = {
+  /** Block size, surface units, padding included. */
+  width: number;
+  height: number;
+  pad: number;
+  fontSize: number;
+  lines: TSLine[];
+  /** Glyphs that are not spaces, in reading order. */
+  glyphCount: number;
+};
+
+const NARROW = new Set([...'iljtfr.,:;!|\'`I1()[]{} ']);
+const WIDE = new Set([...'MWmw@%&']);
+
+/** A font-free width estimate: good enough for a server render or a test. */
+export const estimateMeasurer: TSMeasurer = (text, t) => {
+  const fam = t.fontFamily.toLowerCase();
+  const mono = /mono|courier|code/.test(fam);
+  const condensed = /condensed|oswald|bebas|anton|league gothic|narrow|compressed/.test(fam);
+  let w = 0;
+  for (const ch of text) {
+    if (mono) { w += 0.6; continue; }
+    if (ch === ' ') w += 0.27;
+    else if (NARROW.has(ch)) w += 0.3;
+    else if (WIDE.has(ch)) w += 0.86;
+    else if (ch >= 'A' && ch <= 'Z') w += 0.66;
+    else if (ch >= '0' && ch <= '9') w += 0.56;
+    else w += 0.52;
+  }
+  const weight = 1 + (t.fontWeight - 400) / 2200;
+  return w * t.fontSize * weight * (condensed ? 0.7 : 1);
+};
+
+function wrapLine(line: string, maxWidth: number, width: (s: string) => number): string[] {
+  if (maxWidth <= 0 || width(line) <= maxWidth) return [line];
+  const words = line.split(/(\s+)/);
+  const out: string[] = [];
+  let cur = '';
+  for (const w of words) {
+    const next = cur + w;
+    if (cur.trim() && width(next.trimEnd()) > maxWidth) {
+      out.push(cur.trimEnd());
+      cur = w.trimStart();
+    } else cur = next;
+  }
+  if (cur.trim()) out.push(cur.trimEnd());
+  return out.length ? out : [line];
+}
+
+/** Lay out `text` as a block. Pure. */
+export function layoutText(text: string, t: TSTypography, maxWidth: number, measure: TSMeasurer = estimateMeasurer): TSTextLayout {
+  const fs = t.fontSize;
+  const ls = t.letterSpacing;
+  const chars = (s: string) => [...s];
+  const width = (s: string) => {
+    const n = chars(s).length;
+    return n ? measure(s, t) + ls * (n - 1) : 0;
+  };
+  const rows = (text || ' ').split('\n').flatMap((l) => wrapLine(l, maxWidth, width));
+  const pad = Math.round(fs * 0.45 + 12);
+  const pitch = fs * t.lineHeight;
+  const widths = rows.map(width);
+  const inner = Math.max(1, ...widths);
+  let order = 0;
+  const lines: TSLine[] = rows.map((row, k) => {
+    const w = widths[k]!;
+    const left = pad + (t.align === 'left' ? 0 : t.align === 'right' ? inner - w : (inner - w) / 2);
+    const top = pad + k * pitch;
+    const cs = chars(row);
+    const glyphs: TSGlyph[] = [];
+    let prefix = '';
+    for (let i = 0; i < cs.length; i++) {
+      const x0 = left + (prefix ? measure(prefix, t) : 0) + ls * i;
+      prefix += cs[i];
+      const x1 = left + measure(prefix, t) + ls * i;
+      glyphs.push({ ch: cs[i]!, x0, x1, order: cs[i] === ' ' ? order : order++ });
+    }
+    // Cap height ≈ 0.7 em sits centred in the line.
+    const baseline = top + pitch / 2 + fs * 0.35;
+    return { text: row, glyphs, left, width: w, top, baseline, bottom: top + pitch };
+  });
+  return { width: inner + pad * 2, height: pitch * rows.length + pad * 2, pad, fontSize: fs, lines, glyphCount: order };
+}
+
+/**
+ * How far letters move apart at morph `m`: nothing at rest and when landed, most mid-way. Capped so
+ * the longest line grows by at most a quarter, and stays on the surface.
+ */
+export function morphGap(m: number, layout: TSTextLayout): number {
+  const most = Math.max(2, ...layout.lines.map((l) => l.glyphs.length));
+  const cap = (0.25 * (layout.width - layout.pad * 2)) / (most - 1);
+  return Math.pow(Math.sin(Math.PI * Math.min(1, Math.max(0, m))), 1.4) * Math.min(layout.fontSize * 0.42, cap);
+}
+
+/** A glyph's sideways shift when letters are `gap` apart: centred on its line. */
+export function glyphShift(line: TSLine, index: number, gap: number): number {
+  const n = line.glyphs.length;
+  return (index - (n - 1) / 2) * gap;
+}
+
+/**
+ * The glyph under block point (bx, by) when letters are `gap` apart, or null off the text. The
+ * shader runs the same search, so a vertex and the pixels around it agree on their letter.
+ */
+export function glyphAt(layout: TSTextLayout, bx: number, by: number, gap: number): { line: number; index: number; glyph: TSGlyph; shift: number } | null {
+  let li = 0;
+  for (let k = 0; k < layout.lines.length; k++) if (by >= layout.lines[k]!.top) li = k;
+  const line = layout.lines[li];
+  if (!line || !line.glyphs.length) return null;
+  let best = 0, bestD = Infinity;
+  for (let i = 0; i < line.glyphs.length; i++) {
+    const g = line.glyphs[i]!;
+    const sh = glyphShift(line, i, gap);
+    const c = (g.x0 + g.x1) / 2 + sh;
+    const d = Math.abs(bx - c);
+    if (d < bestD) { bestD = d; best = i; }
+  }
+  return { line: li, index: best, glyph: line.glyphs[best]!, shift: glyphShift(line, best, gap) };
+}

package/src/motion/typesurface/ops.ts

@@ -0,0 +1,196 @@
+/**
+ * **Deformation operators** — the shared vocabulary every surface is built from. Each maps a point
+ * of a sheet to where it is after one physical operation, in place, with no allocation:
+ *
+ *   bend      a crease: one side rotates about a line through a rounded zone (fold, double fold)
+ *   roll      the sheet winds up from an edge onto a tightening spiral (a rolled newspaper)
+ *   cylinder  the sheet wraps a cylinder (a bottle label, a curved plate, a rolled tube)
+ *   crumple   a network of sharp creases: planar facets, ridges and valleys, and shrinkage
+ *   rotate    rigid turns of the whole object (horizontal / vertical distortion)
+ *
+ * Frame: the sheet starts in the plane z = 0, x right, y up, the printed side facing +z (the
+ * camera). Every operator is an isometry of the sheet, or close to one, so text on it keeps its
+ * length and only bends, which is what makes the letters look physically attached. Pure; no React.
+ */
+import { hash32 } from '../neon/random';
+
+export type Vec3 = [number, number, number];
+
+const clamp = (v: number, lo: number, hi: number) => (v < lo ? lo : v > hi ? hi : v);
+export const smoothstep = (a: number, b: number, v: number) => {
+  const t = clamp((v - a) / (b - a), 0, 1);
+  return t * t * (3 - 2 * t);
+};
+
+/* ---------------- bend (a fold) ---------------- */
+
+/**
+ * A crease. `px, py` is a point on the crease line, `dx, dy` its unit direction; the moving side is
+ * the one `(nx, ny) = (dy, −dx)` points to. `theta` is the signed angle reached (radians; positive
+ * lifts toward +z) and `width` the arc length of the rounded zone. Points in the zone lie on a
+ * circular arc of radius width/|θ|; beyond it they turn rigidly by θ. Height above the sheet (z)
+ * is carried through the bend, so stacked layers and creased paper fold together. `core` widens the
+ * crease so layers already folded onto its inner side wrap around instead of turning inside out.
+ */
+export type Bend = { px: number; py: number; dx: number; dy: number; theta: number; width: number; core?: number };
+
+export function bend(p: Vec3, b: Bend): void {
+  if (Math.abs(b.theta) < 1e-5) return;
+  const nx = b.dy, ny = -b.dx;
+  const rx = p[0] - b.px, ry = p[1] - b.py;
+  const d = rx * nx + ry * ny;
+  if (d <= 0) return;
+  const t = rx * b.dx + ry * b.dy;
+  const h = p[2];
+  const w = Math.max(b.width, 1e-5);
+  const sig = b.theta > 0 ? 1 : -1;
+  const R = w / Math.abs(b.theta) + (b.core ?? 0);
+  const zone = Math.abs(b.theta) * R;
+  const s = Math.min(d, zone);
+  const phi = b.theta * (s / zone);
+  // Rotate the radial vector (0, h − σR) about the centre (0, σR) by φ.
+  const vy = h - sig * R;
+  const c = Math.cos(phi), sn = Math.sin(phi);
+  let dd = -vy * sn;
+  let zz = sig * R + vy * c;
+  if (d > zone) {
+    dd += (d - zone) * Math.cos(b.theta);
+    zz += (d - zone) * Math.sin(b.theta);
+  }
+  p[0] = b.px + t * b.dx + dd * nx;
+  p[1] = b.py + t * b.dy + dd * ny;
+  p[2] = zz;
+}
+
+/** Signed distance from the crease (positive on the moving side), for shading and debug. */
+export function bendDistance(x: number, y: number, b: Bend): number {
+  return (x - b.px) * b.dy - (y - b.py) * b.dx;
+}
+
+/* ---------------- roll (a spiral from one edge) ---------------- */
+
+/**
+ * The sheet winds up from an edge. `e` measures the distance from the rolling edge into the sheet
+ * along (ex, ey); everything nearer the edge than `reach` is wound onto a spiral whose outer radius
+ * is `radius` and that tightens toward the edge (the edge is the innermost turn), so turns never
+ * pass through each other. `sign` −1 curls away from the camera: the printed side stays outside.
+ */
+export type Roll = { ox: number; oy: number; ex: number; ey: number; reach: number; radius: number; inner: number; length: number; sign: number };
+
+export function roll(p: Vec3, r: Roll): void {
+  if (r.reach <= 1e-5) return;
+  const rx = p[0] - r.ox, ry = p[1] - r.oy;
+  const e = rx * r.ex + ry * r.ey;
+  if (e >= r.reach) return;
+  const t = rx * -r.ey + ry * r.ex;
+  const s = r.reach - Math.max(e, r.reach - r.length);
+  // r(φ) = R − kφ, s(φ) = Rφ − kφ²/2, and the spiral ends at `inner` after the whole length.
+  const R = r.radius;
+  const k = Math.max(1e-6, ((R - r.inner) * (R + r.inner)) / (2 * r.length));
+  const disc = Math.max(0, R * R - 2 * k * s);
+  const phi = (R - Math.sqrt(disc)) / k;
+  const rad = Math.max(1e-4, R - k * phi - r.sign * p[2]);
+  const ee = r.reach - rad * Math.sin(phi);
+  const zz = r.sign * R - rad * r.sign * Math.cos(phi);
+  p[0] = r.ox + ee * r.ex + t * -r.ey;
+  p[1] = r.oy + ee * r.ey + t * r.ex;
+  p[2] = zz;
+}
+
+/* ---------------- cylinder (wrap around an axis) ---------------- */
+
+/**
+ * Wrap onto a cylinder whose axis is parallel to y, behind the sheet, at distance 1/κ. κ = 0 is
+ * flat; the front (x = 0) never moves, so the text in the middle stays put while its ends curve
+ * away. Arc length is kept: a label of width w covers w / radius radians.
+ */
+export function cylinder(p: Vec3, kappa: number): void {
+  if (Math.abs(kappa) < 1e-6) return;
+  const r = 1 / kappa + p[2];
+  const a = p[0] * kappa;
+  p[0] = Math.sin(a) * r;
+  p[2] = Math.cos(a) * r - 1 / kappa;
+}
+
+/* ---------------- crumple (a crease network) ---------------- */
+
+/**
+ * One crease of a crumple: a straight ridge (or valley) with planar flanks. Crumpled paper is a
+ * network of such creases; their sum gives flat facets, sharp ridges and the shrinkage the ridges
+ * take up.
+ */
+export type Crease = { cx: number; cy: number; dx: number; dy: number; half: number; width: number; height: number };
+
+/** The creases of one crumple, in sheet units where the sheet is 1 wide. Deterministic per seed. */
+export function crumpleCreases(seed: number, scale: number, aspect: number): Crease[] {
+  const out: Crease[] = [];
+  const r = (i: number, salt: number) => hash32(seed, i, salt) / 4294967296;
+  const layer = (count: number, base: number, lenMin: number, lenMax: number, wMin: number, wMax: number, amp: number, salt: number) => {
+    for (let i = 0; i < count; i++) {
+      const a = r(i, salt + 1) * Math.PI;
+      const sgn = r(i, salt + 2) < 0.62 ? 1 : -1;
+      out.push({
+        cx: (r(i, salt + 3) - 0.5) * 1.25,
+        cy: (r(i, salt + 4) - 0.5) * 1.25 * aspect,
+        dx: Math.cos(a), dy: Math.sin(a),
+        half: (lenMin + (lenMax - lenMin) * r(i, salt + 5)) * scale * base,
+        width: (wMin + (wMax - wMin) * r(i, salt + 6)) * scale,
+        height: sgn * amp * (0.35 + 0.65 * r(i, salt + 7)),
+      });
+    }
+  };
+  const k = Math.round(26 / Math.max(0.5, scale));
+  layer(k, 1, 0.3, 0.85, 0.06, 0.17, 1, 10);
+  layer(k * 2 + 12, 1, 0.12, 0.35, 0.035, 0.08, 0.3, 20);
+  return out;
+}
+
+/**
+ * The crumple field at (x, y) (sheet units, 1 wide): `out = [dx, dy, dz]` for a unit crumple.
+ * `fine` keeps only the small creases, which are the wrinkles.
+ */
+export function crumpleField(creases: readonly Crease[], x: number, y: number, out: Vec3, fine = false): void {
+  let dx = 0, dy = 0, dz = 0;
+  for (const c of creases) {
+    if (fine && Math.abs(c.height) > 0.5) continue;
+    const rx = x - c.cx, ry = y - c.cy;
+    const along = rx * c.dx + ry * c.dy;
+    const across = rx * -c.dy + ry * c.dx;
+    const aa = Math.abs(across);
+    if (aa >= c.width) continue;
+    const la = Math.abs(along) / c.half;
+    if (la >= 1) continue;
+    const win = la < 0.55 ? 1 : 1 - smoothstep(0.55, 1, la);
+    const tent = (1 - aa / c.width) * win;
+    dz += c.height * tent * c.width;
+    // The paper a ridge stands up in comes from both sides of it: pull the flanks in.
+    const pull = -0.12 * Math.sign(across) * Math.abs(c.height) * c.width * tent;
+    dx += pull * -c.dy;
+    dy += pull * c.dx;
+  }
+  out[0] = dx; out[1] = dy; out[2] = dz;
+}
+
+/* ---------------- rigid transforms ---------------- */
+
+/** Rotate about the y axis (a), then x (b), then z (c), radians. */
+export function rotate(p: Vec3, a: number, b: number, c: number): void {
+  if (a) {
+    const ca = Math.cos(a), sa = Math.sin(a);
+    const x = p[0] * ca + p[2] * sa;
+    p[2] = -p[0] * sa + p[2] * ca;
+    p[0] = x;
+  }
+  if (b) {
+    const cb = Math.cos(b), sb = Math.sin(b);
+    const y = p[1] * cb - p[2] * sb;
+    p[2] = p[1] * sb + p[2] * cb;
+    p[1] = y;
+  }
+  if (c) {
+    const cc = Math.cos(c), sc = Math.sin(c);
+    const x = p[0] * cc - p[1] * sc;
+    p[1] = p[0] * sc + p[1] * cc;
+    p[0] = x;
+  }
+}

package/src/motion/typesurface/presets.ts

@@ -0,0 +1,271 @@
+/* eslint-disable comppack/no-raw-colour -- preset type and ink colours are experiment content. */
+/**
+ * **Experiments.** Each preset is a complete config: text, typography, surface and state, how far
+ * every transformation goes, the material, and the stages that play it. They are starting points
+ * for looking, not fixed animations: every value is still a slider. Plus the helpers that put a
+ * surface into a named state and build an experiment from a few words (for agents).
+ */
+import { findTypeSurfaceFont } from './fonts';
+import { DEFAULT_TYPE_SURFACE, REST_DEFORMATION, resolveTypeSurface, type TSStage, type TSSurfaceType, type TypeSurfaceConfig, type TypeSurfaceConfigInput } from './config';
+import { createObject, OBJECT_FRONT_ARC, type TSObjectMaterialId, type TSObjectSpec } from './construct';
+import { estimateMeasurer, layoutText, type TSMeasurer } from './layout';
+import { getSurface, objectSurface, surfaceFor } from './surfaces';
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+function merge<T>(base: T, over: unknown): T {
+  if (!isObj(base) || !isObj(over)) return (over === undefined ? base : over) as T;
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(over)) out[k] = merge((base as Record<string, unknown>)[k], v);
+  return out as T;
+}
+
+/**
+ * Put the surface in a named state (`SURFACES[type].states`). The surface's shape and the camera
+ * change; the text, and how far it has wrapped and morphed, do not.
+ */
+export function applySurfaceState(config: TypeSurfaceConfig, stateId: string): TypeSurfaceConfig {
+  const def = surfaceFor(config);
+  const state = def.states[stateId];
+  if (!state) return config;
+  const deformation = merge(REST_DEFORMATION, state.deformation);
+  return {
+    ...config,
+    surface: { ...config.surface, state: stateId },
+    deformation: { ...deformation, wrap: config.deformation.wrap, morph: config.deformation.morph },
+    view: { ...config.view, roll: 0, ...state.view },
+  };
+}
+
+/**
+ * Switch surface: its default state and its natural text material, keeping the words and type.
+ * Stages that drive a transformation the new surface has no use for are kept; they just do nothing.
+ */
+export function switchSurface(config: TypeSurfaceConfig, type: TSSurfaceType | string): TypeSurfaceConfig {
+  const def = getSurface(type);
+  const next: TypeSurfaceConfig = { ...config, object: null, surface: { ...config.surface, type: type as TSSurfaceType, color: null }, material: { ...config.material, ...def.material } };
+  return applySurfaceState(next, def.defaultState);
+}
+
+const stage = (key: TSStage['key'], start: number, end: number, label?: string, out?: [number, number]): TSStage =>
+  ({ key, start, end, easing: 'ease-in-out', label: label ?? key, ...(out ? { outStart: out[0], outEnd: out[1] } : {}) });
+
+export type TypeSurfacePreset = { id: string; name: string; description: string; config: TypeSurfaceConfig };
+
+const on = (type: TSSurfaceType, input: TypeSurfaceConfigInput): TypeSurfaceConfig => {
+  const def = getSurface(type);
+  const base = { ...DEFAULT_TYPE_SURFACE, material: { ...DEFAULT_TYPE_SURFACE.material, ...def.material } };
+  return resolveTypeSurface({ ...input, surface: { type, state: def.defaultState, seed: 7, color: null, ...input.surface } }, { ...base, deformation: REST_DEFORMATION });
+};
+
+/**
+ * Put the text on a constructed object: the object replaces the surface, the text wraps the part it
+ * names and prints in its own colour (not multiplied into the part's). The words and type are kept.
+ */
+export function withObject(config: TypeSurfaceConfig, object: TSObjectSpec): TypeSurfaceConfig {
+  const def = objectSurface(object);
+  return {
+    ...config, object,
+    surface: { ...config.surface, type: 'object', state: def.defaultState, color: null },
+    typography: { ...config.typography, blendMode: 'normal' },
+    placement: { ...config.placement, x: 0.5, y: 0.5, rotation: 0 },
+    deformation: { ...merge(REST_DEFORMATION, def.states[def.defaultState]!.deformation), wrap: 1 },
+    material: { ...config.material, ...def.material, blend: 1, gloss: 0.2 },
+    view: { ...config.view, roll: 0 },
+  };
+}
+
+/**
+ * Size the text to the object: as large as fits the part's front face (`OBJECT_FRONT_ARC` of its
+ * circumference) and the text area's height, on one block that never wraps. Without an object the
+ * config is returned as it is. Pass the canvas measurer in a browser for exact widths.
+ */
+export function fitObjectText(config: TypeSurfaceConfig, measure: TSMeasurer = estimateMeasurer): TypeSurfaceConfig {
+  if (!config.object || !config.text.trim()) return config;
+  const def = objectSurface(config.object);
+  const arc = (def.width / def.curveRadius) * (180 / Math.PI);
+  const wide = 1000 * Math.min(1, OBJECT_FRONT_ARC / arc) * 0.95;
+  const high = 1000 * (def.height / def.width) * 0.8;
+  const at100 = layoutText(config.text, { ...config.typography, fontSize: 100 }, 0, measure);
+  const fontSize = Math.max(12, Math.min(400, Math.floor(100 * Math.min(wide / at100.width, high / at100.height))));
+  return { ...config, typography: { ...config.typography, fontSize }, placement: { ...config.placement, maxWidth: 0 } };
+}
+
+/** Near-white or near-black, whichever reads on a colour. */
+const inkOn = (hex: string): string => {
+  const h = hex.length === 4 ? hex.slice(1).split('').map((c) => c + c).join('') : hex.slice(1);
+  const n = parseInt(h, 16);
+  return 0.299 * ((n >> 16) & 255) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255) > 140 ? '#1B1D20' : '#FFFFFF';
+};
+
+const onObject = (object: TSObjectSpec, input: TypeSurfaceConfigInput): TypeSurfaceConfig =>
+  resolveTypeSurface(input, withObject({ ...DEFAULT_TYPE_SURFACE, deformation: REST_DEFORMATION }, object));
+
+const ANTON = "'Anton', Impact, sans-serif";
+const PLAYFAIR = "'Playfair Display', Georgia, serif";
+
+export const TYPE_SURFACE_PRESETS: TypeSurfacePreset[] = [
+  {
+    id: 'newspaper-fold', name: 'Newspaper · Fold', description: 'The headline lands, then the page folds under through NEWS: the letters wrap round the crease and vanish beneath.',
+    config: on('newspaper', {
+      text: 'BREAKING NEWS', typography: { fontFamily: ANTON, fontSize: 132, color: '#E0271B' },
+      deformation: { wrap: 1, fold: { amount: 1, position: 0.7, angle: 180, width: 0.03, direction: 'under', influence: 0.8 } },
+      material: { blend: 0.55 },
+      animation: { duration: 9000, stages: [stage('wrap', 0.03, 0.22), stage('blend', 0.12, 0.28, 'print'), stage('fold', 0.32, 0.75)] },
+    }),
+  },
+  {
+    id: 'newspaper-fold-word', name: 'Newspaper · Crease through a word', description: 'The hard case: a crease runs through the middle of a word. Letters compress, turn, darken and pass behind.',
+    config: on('newspaper', {
+      text: 'EXTRAORDINARY', typography: { fontFamily: "'Playfair Display', Georgia, serif", fontWeight: 900, fontSize: 118, letterSpacing: 0, color: '#141210' },
+      placement: { y: 0.3 },
+      deformation: { wrap: 1, tiltX: -0.12, fold: { amount: 1, position: 0.5, angle: 80, width: 0.018, direction: 'over', influence: 1 } },
+      material: { blend: 0.9 },
+      animation: { duration: 7000, stages: [stage('fold', 0.1, 0.7)] },
+    }),
+  },
+  {
+    id: 'newspaper-four-folds', name: 'Newspaper · Four folds', description: 'An accordion of four creases, the farthest folded first; the last crease runs through the headline, so the lower half of the letters tilts away.',
+    config: on('newspaper', {
+      text: 'BREAKING NEWS', typography: { fontFamily: ANTON, fontSize: 150, color: '#E0271B' }, placement: { y: 0.3 },
+      deformation: {
+        wrap: 1,
+        fold: { amount: 1, position: 0.84, angle: 100, direction: 'under', orientation: 'horizontal', width: 0.02 },
+        fold2: { amount: 1, position: 0.68, angle: 100, direction: 'over', orientation: 'horizontal', width: 0.02 },
+        fold3: { amount: 1, position: 0.52, angle: 100, direction: 'under', orientation: 'horizontal', width: 0.02 },
+        fold4: { amount: 1, position: 0.31, angle: 50, direction: 'over', orientation: 'horizontal', width: 0.02, influence: 1 },
+      },
+      material: { blend: 0.85 },
+      animation: { duration: 10000, stages: [stage('fold', 0.05, 0.28), stage('fold2', 0.28, 0.5), stage('fold3', 0.5, 0.72), stage('fold4', 0.72, 0.94)] },
+    }),
+  },
+  {
+    id: 'newspaper-wraps', name: 'Newspaper · Wraps', description: 'Both sides wrap round rods and the bottom rolls under a third: the headline stays on the flat middle, the columns curve away.',
+    config: on('newspaper', {
+      text: 'BREAKING NEWS', typography: { fontFamily: ANTON, fontSize: 120, color: '#E0271B' }, placement: { y: 0.34 },
+      deformation: {
+        wrap: 1,
+        wrap1: { amount: 1, position: 0.9, radius: 0.05, angle: 190, direction: 'under', orientation: 'vertical', side: 'far' },
+        wrap2: { amount: 1, position: 0.1, radius: 0.05, angle: 190, direction: 'under', orientation: 'vertical', side: 'near' },
+        wrap3: { amount: 1, position: 0.72, radius: 0.07, angle: 210, direction: 'under', orientation: 'horizontal', side: 'far' },
+        wrap4: { amount: 0.6, position: 0.12, radius: 0.04, angle: 120, direction: 'over', orientation: 'horizontal', side: 'near' },
+      },
+      material: { blend: 0.8 },
+      animation: { duration: 10000, stages: [stage('wrap1', 0.05, 0.3, 'wrap 1'), stage('wrap2', 0.25, 0.5, 'wrap 2'), stage('wrap3', 0.5, 0.75, 'wrap 3'), stage('wrap4', 0.72, 0.95, 'wrap 4')] },
+    }),
+  },
+  {
+    id: 'newspaper-crumple', name: 'Newspaper · Crumple', description: 'Printed headline → folded once → crushed. The letters break across facets like real newsprint.',
+    config: on('newspaper', {
+      text: 'BREAKING NEWS', typography: { fontFamily: PLAYFAIR, fontWeight: 900, fontSize: 124, letterSpacing: -2, color: '#161412' },
+      deformation: { wrap: 1, fold: { amount: 0.55, position: 0.5, orientation: 'horizontal', direction: 'under', width: 0.05 }, crumple: { amount: 0.9, scale: 1 } },
+      material: { blend: 1, halftone: 0 },
+      animation: { duration: 9000, stages: [stage('fold', 0.08, 0.3), stage('crumple', 0.32, 0.8, 'crumple')] },
+    }),
+  },
+  {
+    id: 'newspaper-roll', name: 'Newspaper · Roll', description: 'The page rolls up from the bottom into a tube; the headline rides the outside of the roll.',
+    config: on('newspaper', {
+      text: 'BREAKING NEWS', typography: { fontFamily: ANTON, fontSize: 132, color: '#E0271B' }, placement: { y: 0.3 },
+      deformation: { wrap: 1, roll: { amount: 0.7, edge: 'bottom', direction: 'under', radius: 0.085 } },
+      material: { blend: 0.8 },
+      animation: { duration: 8000, stages: [stage('roll', 0.1, 0.8, 'roll')] },
+    }),
+  },
+  {
+    id: 'bottle-wrap', name: 'Bottle · Wrap', description: 'Flat label → cylinder → the type wraps it → glass reflections → printed.',
+    config: on('bottle', {
+      text: 'HELLO\nWORLD', typography: { fontFamily: "'Archivo Black', 'Arial Black', sans-serif", fontSize: 150, lineHeight: 0.92, letterSpacing: -3, color: '#161616', align: 'left' },
+      placement: { x: 0.5, y: 0.47 },
+      deformation: { wrap: 1, curve: 1 },
+      material: { blend: 1, gloss: 0.25 },
+      view: { roll: -28, motion: 0.8 },
+      animation: { duration: 9000, stages: [stage('curve', 0.05, 0.38, 'cylinder'), stage('wrap', 0.3, 0.55), stage('blend', 0.55, 0.85, 'print')] },
+    }),
+  },
+  {
+    id: 'wrapper-fold', name: 'Wrapper · Fold', description: 'Flat film → inflated pack → the end folds under → wrinkles → printed on the foil.',
+    config: on('wrapper', {
+      text: 'SUMMER\nSALE', typography: { fontFamily: ANTON, fontSize: 170, lineHeight: 0.9, color: '#C8102E', gradient: { enabled: true, from: '#E3262B', to: '#8E0B1F', angle: 90 } },
+      placement: { x: 0.46, y: 0.5, rotation: -6 },
+      deformation: { wrap: 1, curve: 1, wrinkle: 0.7, fold: { amount: 0.85, position: 0.82, angle: 150, width: 0.05, direction: 'under' } },
+      material: { blend: 1 },
+      animation: { duration: 9000, stages: [stage('curve', 0.05, 0.3, 'inflate'), stage('wrap', 0.12, 0.36), stage('fold', 0.36, 0.58), stage('wrinkle', 0.55, 0.75), stage('blend', 0.7, 0.92, 'print')] },
+    }),
+  },
+  {
+    id: 'fabric-fold', name: 'Fabric · Fold', description: 'Screen print on cotton: the cloth drifts into folds, then folds over; the ink moves with the weave.',
+    config: on('fabric', {
+      text: 'WEEKEND\nCLUB', typography: { fontFamily: "'Oswald', 'Arial Narrow', sans-serif", fontWeight: 700, fontSize: 150, lineHeight: 0.95, letterSpacing: 6, color: '#F2EBDD' },
+      placement: { y: 0.46 },
+      deformation: { wrap: 1, wave: 0.75, fold: { amount: 1, position: 0.88, angle: 170, width: 0.05, direction: 'over' } },
+      material: { blend: 1 }, view: { motion: 1 },
+      animation: { duration: 9000, stages: [stage('wrap', 0.03, 0.2), stage('wave', 0.15, 0.5, 'folds'), stage('fold', 0.55, 0.85)] },
+    }),
+  },
+  {
+    id: 'paper-crumple', name: 'Paper · Note', description: 'A marker note on a plain sheet, crushed.',
+    config: on('paper', {
+      text: 'Call me\nback!', typography: { fontFamily: "'Permanent Marker', cursive", fontSize: 118, lineHeight: 1.05, color: '#1F3FA8', letterSpacing: 0 },
+      placement: { y: 0.42, rotation: -5 },
+      deformation: { wrap: 1, crumple: { amount: 0.75, scale: 0.9 } },
+      material: { blend: 1, inkRoughness: 0.2 },
+      animation: { duration: 8000, stages: [stage('crumple', 0.15, 0.7, 'crush')] },
+    }),
+  },
+  {
+    id: 'object-tumbler', name: 'Tumbler · Built from parts', description: 'No tumbler exists in the library: a hollow tapered cylinder, a ring for the rim and a short cylinder for the foot. The name wraps the taper.',
+    config: onObject(createObject('tumbler'), {
+      text: 'Shekhar', typography: { fontFamily: "'Archivo Black', 'Arial Black', sans-serif", fontSize: 120, letterSpacing: 0, color: '#F4F1EA' },
+      view: { motion: 0.8 },
+      animation: { duration: 8000, stages: [stage('curve', 0.05, 0.45, 'wrap round'), stage('blend', 0.45, 0.85, 'print')] },
+    }),
+  },
+  {
+    id: 'object-mug', name: 'Mug · Built from parts', description: 'A hollow cylinder and a tube along a path for the handle, glazed black; the name is printed in white.',
+    config: onObject(createObject('mug'), {
+      text: 'Tushar', typography: { fontFamily: PLAYFAIR, fontWeight: 900, fontSize: 150, letterSpacing: 0, color: '#FFFFFF' },
+      view: { motion: 0.8 },
+      animation: { duration: 8000, stages: [stage('curve', 0.05, 0.45, 'wrap round'), stage('blend', 0.45, 0.85, 'print')] },
+    }),
+  },
+];
+
+export function findTypeSurfacePreset(id: string): TypeSurfacePreset | undefined {
+  return TYPE_SURFACE_PRESETS.find((p) => p.id === id);
+}
+
+/** A few words an agent can say → a config. Unknown fonts/states are ignored, not fatal. */
+export type TypeSurfaceShorthand = {
+  text?: string;
+  surface?: TSSurfaceType | string;
+  state?: string;
+  font?: string;
+  color?: string;
+  material?: TypeSurfaceConfig['material']['type'];
+  /** One of the preset ids to start from. */
+  preset?: string;
+  /** Instead of a surface: a recipe name (`TS_RECIPES`), or a whole object spec built from primitives. */
+  object?: string | TSObjectSpec;
+  /** With a recipe name: the object's colour and material. The text is then sized to the object (`fitObjectText`) and, with no `color`, inked to read on it. */
+  objectColor?: string;
+  objectMaterial?: TSObjectMaterialId;
+};
+
+/** Build an experiment from shorthand: preset → surface → state → text, font, colour, material. */
+export function createTypeSurface(s: TypeSurfaceShorthand = {}): TypeSurfaceConfig {
+  let cfg = findTypeSurfacePreset(s.preset ?? '')?.config ?? TYPE_SURFACE_PRESETS[0]!.config;
+  if (s.surface && s.surface !== cfg.surface.type) cfg = switchSurface(cfg, s.surface);
+  if (s.object) cfg = withObject(cfg, typeof s.object === 'string' ? createObject(s.object, { color: s.objectColor, material: s.objectMaterial }) : s.object);
+  if (s.state) cfg = applySurfaceState(cfg, s.state);
+  if (s.text !== undefined) cfg = { ...cfg, text: s.text };
+  const font = s.font ? findTypeSurfaceFont(s.font) : undefined;
+  if (font) cfg = { ...cfg, typography: { ...cfg.typography, fontFamily: font.family, fontWeight: font.weights.includes(cfg.typography.fontWeight) ? cfg.typography.fontWeight : font.weights[font.weights.length - 1]! } };
+  if (s.color && /^#[0-9a-f]{6}$/i.test(s.color)) cfg = { ...cfg, typography: { ...cfg.typography, color: s.color.toUpperCase() } };
+  if (s.material) cfg = { ...cfg, material: { ...cfg.material, type: s.material } };
+  if (cfg.object && s.object) {
+    // On an object the words start legible: sized to its front face, in an ink that reads on it.
+    if (!s.color) cfg = { ...cfg, typography: { ...cfg.typography, color: inkOn(objectSurface(cfg.object).color) } };
+    cfg = fitObjectText(cfg);
+  }
+  return cfg;
+}