@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/typesurface/config.ts

@@ -0,0 +1,486 @@
+/* eslint-disable comppack/no-raw-colour -- type, ink and surface colours are experiment content, not theme colours. */
+/**
+ * **The typography × surface experiment, as one JSON object.** Six concerns that never reach into
+ * each other:
+ *
+ *   text         what it says ("BREAKING NEWS", "SUMMER\nSALE", anything)
+ *   typography   how the letters look: font, weight, size, spacing, colour, gradient, blend mode
+ *   placement    where the text sits ON the surface (surface coordinates, 0–1), its angle and width
+ *   surface      which physical thing it meets (newspaper, bottle, wrapper…) and in which state
+ *   deformation  how far each transformation has gone: wrap, morph, fold, roll, crumple…
+ *   material     how the letters become part of the surface: ink, print, foil, emboss
+ *   view         the camera: perspective comes from here, not from the text
+ *   animation    stages over a 0–1 timeline; each stage drives one deformation amount
+ *
+ * So BREAKING NEWS → SUMMER SALE changes `text` only, and newspaper → bottle changes `surface`
+ * only: the text is never flattened into the artwork. Units: `fontSize`, `letterSpacing` and
+ * `maxWidth` are **surface units**. Every surface is 1000 units wide, so 96 is 9.6 % of its width.
+ * Angles are degrees, times are ms. `docs/TYPE-SURFACE.md`.
+ */
+import type { Easing } from '../types';
+import { hasSurface } from './surfaces';
+
+export const TS_SURFACES = ['newspaper', 'paper', 'bottle', 'wrapper', 'fabric'] as const;
+export type TSSurfaceType = (typeof TS_SURFACES)[number];
+export const TS_TEXT_MATERIALS = ['ink', 'print', 'foil', 'emboss'] as const;
+/**
+ * How the letters join the surface once they land.
+ * - `ink`: absorbed into paper (multiplied into it, grain shows through, halftone when embedded).
+ * - `print`: a printed film on a label or film: opaque, slightly glossier than what's under it.
+ * - `foil`: metallic ink; reflects the room in the text colour.
+ * - `emboss`: pressed into the material; mostly relief, a little colour.
+ */
+export type TSTextMaterial = (typeof TS_TEXT_MATERIALS)[number];
+export const TS_BLEND_MODES = ['normal', 'multiply', 'screen', 'overlay', 'darken', 'lighten', 'color-burn', 'soft-light'] as const;
+export type TSBlendMode = (typeof TS_BLEND_MODES)[number];
+export const TS_ALIGNS = ['left', 'center', 'right'] as const;
+export type TSAlign = (typeof TS_ALIGNS)[number];
+export const TS_FOLD_ORIENTATIONS = ['vertical', 'horizontal'] as const;
+export const TS_FOLD_DIRECTIONS = ['over', 'under'] as const;
+export const TS_ROLL_EDGES = ['bottom', 'top', 'left', 'right'] as const;
+export const TS_FOLD_SIDES = ['far', 'near'] as const;
+/** The folds and the wraps, in the order they are applied. Up to four of each. */
+export const TS_FOLD_KEYS = ['fold', 'fold2', 'fold3', 'fold4'] as const;
+export const TS_WRAP_KEYS = ['wrap1', 'wrap2', 'wrap3', 'wrap4'] as const;
+
+export type TSTypography = {
+  /** Any CSS font-family list. The page must load the font; nothing is converted to outlines. */
+  fontFamily: string;
+  fontWeight: number;
+  fontStyle: 'normal' | 'italic';
+  /** Surface units (the surface is 1000 wide). */
+  fontSize: number;
+  /** Extra space between letters, surface units. */
+  letterSpacing: number;
+  /** Line pitch as a multiple of fontSize. */
+  lineHeight: number;
+  align: TSAlign;
+  color: string;
+  gradient: { enabled: boolean; from: string; to: string; angle: number };
+  opacity: number;
+  blendMode: TSBlendMode;
+};
+
+export type TSPlacement = {
+  /** Centre of the text block on the surface, 0–1 from the left edge. */
+  x: number;
+  /** Centre of the text block on the surface, 0–1 from the top edge. */
+  y: number;
+  /** Degrees, clockwise on the surface. */
+  rotation: number;
+  /** Lines wrap past this width (surface units). 0 = never wrap. */
+  maxWidth: number;
+};
+
+export type TSSurface = {
+  type: TSSurfaceType;
+  /** A named state from `SURFACE_STATES[type]`; applying it sets `deformation`. Informational after. */
+  state: string;
+  /** Seeds every random choice: creases, wrinkles, the newspaper's copy and photos. */
+  seed: number;
+  /** The surface's own colour where it has one (wrapper film, fabric, bottle glass). null → its default. */
+  color: string | null;
+};
+
+export type TSFold = {
+  /** 0–1: how far the fold has gone. The angle reached is `angle × amount`. */
+  amount: number;
+  /** Where the crease runs, 0–1 across the surface. */
+  position: number;
+  /** The angle at full amount, degrees (180 = folded flat). */
+  angle: number;
+  /** Width of the rounded crease, as a share of the surface width. */
+  width: number;
+  /** How strongly the crease shades paper and letters (0 = no crease light). */
+  influence: number;
+  orientation: (typeof TS_FOLD_ORIENTATIONS)[number];
+  /** `over`: the moving side lifts toward the camera. `under`: it tucks beneath. */
+  direction: (typeof TS_FOLD_DIRECTIONS)[number];
+  /** Which side moves: `far` = right of a vertical crease / below a horizontal one; `near` = left / above. */
+  side: (typeof TS_FOLD_SIDES)[number];
+};
+
+/**
+ * A wrap: from a line, the sheet wraps round a rod of `radius` (share of the width). `amount`
+ * wraps `angle × amount` of the way round; the rest carries on, tangent. 360° goes all the way.
+ */
+export type TSWrap = {
+  amount: number;
+  position: number;
+  radius: number;
+  angle: number;
+  orientation: (typeof TS_FOLD_ORIENTATIONS)[number];
+  direction: (typeof TS_FOLD_DIRECTIONS)[number];
+  side: (typeof TS_FOLD_SIDES)[number];
+};
+
+export type TSDeformation = {
+  /** 0–1: floating typography (0) → conformed to the surface (1). */
+  wrap: number;
+  /** 0–1: letters peel off and land one by one, spreading apart mid-way. */
+  morph: number;
+  /** 0–1: camera from straight above (flat) to a low, wide-angle view. */
+  perspective: number;
+  /** −1–1: turns the object left/right (horizontal distortion). */
+  tiltX: number;
+  /** −1–1: tips the object toward/away from the camera (vertical distortion). */
+  tiltY: number;
+  /** −1–1: shears the surface in its own plane. */
+  skew: number;
+  /** 0–1: cylindrical curvature (a bottle label, a curved plate, a pillow pack's inflation). */
+  curve: number;
+  fold: TSFold;
+  /** A second crease, perpendicular to the first by default: double folded. */
+  fold2: TSFold;
+  fold3: TSFold;
+  fold4: TSFold;
+  wrap1: TSWrap;
+  wrap2: TSWrap;
+  wrap3: TSWrap;
+  wrap4: TSWrap;
+  roll: { amount: number; edge: (typeof TS_ROLL_EDGES)[number]; radius: number; direction: 'over' | 'under' };
+  crumple: { amount: number; scale: number };
+  /** 0–1: soft waves (fabric drape, a rippled pane). */
+  wave: number;
+  /** 0–1: fine wrinkles (a wrapper's film, creased cloth). */
+  wrinkle: number;
+};
+
+export type TSMaterial = {
+  type: TSTextMaterial;
+  /** 0–1: floating graphic → lit by the surface → printed → embedded ink. */
+  blend: number;
+  /** How dark and saturated the ink prints. */
+  inkStrength: number;
+  /** Ink bleeding into the fibres (dilates the letters a little). */
+  inkSpread: number;
+  /** Ragged, uneven ink edges. */
+  inkRoughness: number;
+  /** How much of the surface's own colour the letters take on (multiply). */
+  paperInfluence: number;
+  /** How much of the paper grain breaks up the ink. */
+  grainInfluence: number;
+  /** 0–1: embedded ink becomes a printing screen (newsprint dots). */
+  halftone: number;
+  /** Small ink misregistration, surface units. */
+  displacement: number;
+  /** How much the surface's light and shadow fall on the letters. */
+  surfaceContrast: number;
+  /** How high floating letters hover, as a share of the surface width. */
+  lift: number;
+  /** Strength of the shadow the letters cast while they float. */
+  shadow: number;
+  /** Varnish: specular shine of the letters. */
+  gloss: number;
+  /** Relief depth for `emboss` (and a little for every material once embedded). */
+  emboss: number;
+};
+
+export type TSView = {
+  /** Degrees added to the camera's orbit, left/right. */
+  yaw: number;
+  /** Degrees added to the camera's tilt. */
+  pitch: number;
+  /** 1 = the object fills the frame. */
+  zoom: number;
+  /** Degrees: turns the object on the table (the bottle lies diagonally). */
+  roll: number;
+  /** Keep the object centred as it folds and rolls. */
+  autoCenter: boolean;
+  /** Time-driven motion (fabric in a breeze, a bottle turning). */
+  motion: number;
+};
+
+export const TS_ANIMATABLE = ['wrap', 'morph', 'perspective', 'curve', 'fold', 'fold2', 'fold3', 'fold4', 'wrap1', 'wrap2', 'wrap3', 'wrap4', 'roll', 'crumple', 'wave', 'wrinkle', 'blend'] as const;
+/** A transformation amount a timeline stage can drive. */
+export type TSAnimatable = (typeof TS_ANIMATABLE)[number];
+/** Where each animatable amount lives in the config. */
+export const TS_ANIMATABLE_PATHS: Record<TSAnimatable, string> = {
+  wrap: 'deformation.wrap', morph: 'deformation.morph', perspective: 'deformation.perspective', curve: 'deformation.curve',
+  fold: 'deformation.fold.amount', fold2: 'deformation.fold2.amount', fold3: 'deformation.fold3.amount', fold4: 'deformation.fold4.amount',
+  wrap1: 'deformation.wrap1.amount', wrap2: 'deformation.wrap2.amount', wrap3: 'deformation.wrap3.amount', wrap4: 'deformation.wrap4.amount', roll: 'deformation.roll.amount',
+  crumple: 'deformation.crumple.amount', wave: 'deformation.wave', wrinkle: 'deformation.wrinkle', blend: 'material.blend',
+};
+
+/**
+ * One stage of the timeline. Between `start` and `end` (0–1 of the timeline) its amount rises from
+ * 0 to the value in the config; with `outStart`/`outEnd` it falls back to 0 (a fold that unfolds).
+ * Sliders set how FAR a transformation goes; stages set WHEN.
+ */
+export type TSStage = { key: TSAnimatable; start: number; end: number; outStart?: number; outEnd?: number; easing?: Easing; label?: string };
+
+export type TSAnimation = {
+  /** One pass of the timeline, ms. */
+  duration: number;
+  loop: boolean;
+  stages: TSStage[];
+};
+
+export type TypeSurfaceConfig = {
+  version: 1;
+  text: string;
+  typography: TSTypography;
+  placement: TSPlacement;
+  surface: TSSurface;
+  deformation: TSDeformation;
+  material: TSMaterial;
+  view: TSView;
+  animation: TSAnimation;
+};
+
+type DeepPartial<T> = T extends (infer U)[] ? U[] : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+export type TypeSurfaceConfigInput = DeepPartial<TypeSurfaceConfig>;
+
+const FOLD_OFF: TSFold = { amount: 0, position: 0.5, angle: 180, width: 0.035, influence: 0.7, orientation: 'vertical', direction: 'over', side: 'far' };
+const WRAP_OFF: TSWrap = { amount: 0, position: 0.7, radius: 0.06, angle: 300, orientation: 'vertical', direction: 'under', side: 'far' };
+
+/** Every transformation at rest: flat, floating, un-inked. States and presets start here. */
+export const REST_DEFORMATION: TSDeformation = {
+  wrap: 0, morph: 0, perspective: 0, tiltX: 0, tiltY: 0, skew: 0, curve: 0,
+  fold: FOLD_OFF,
+  fold2: { ...FOLD_OFF, orientation: 'horizontal' },
+  fold3: { ...FOLD_OFF, position: 0.25 },
+  fold4: { ...FOLD_OFF, position: 0.25, orientation: 'horizontal' },
+  wrap1: WRAP_OFF,
+  wrap2: { ...WRAP_OFF, side: 'near', position: 0.3 },
+  wrap3: { ...WRAP_OFF, orientation: 'horizontal' },
+  wrap4: { ...WRAP_OFF, orientation: 'horizontal', side: 'near', position: 0.3 },
+  roll: { amount: 0, edge: 'bottom', radius: 0.085, direction: 'under' },
+  crumple: { amount: 0, scale: 1 },
+  wave: 0, wrinkle: 0,
+};
+
+export const DEFAULT_TYPE_SURFACE: TypeSurfaceConfig = {
+  version: 1,
+  text: 'BREAKING NEWS',
+  typography: {
+    fontFamily: "'Anton', 'Impact', sans-serif", fontWeight: 400, fontStyle: 'normal', fontSize: 128, letterSpacing: 2, lineHeight: 1,
+    align: 'center', color: '#E0271B', gradient: { enabled: false, from: '#E0271B', to: '#7A0C06', angle: 90 }, opacity: 1, blendMode: 'multiply',
+  },
+  placement: { x: 0.5, y: 0.34, rotation: 0, maxWidth: 900 },
+  surface: { type: 'newspaper', state: 'flat', seed: 7, color: null },
+  deformation: { ...REST_DEFORMATION, wrap: 1 },
+  material: {
+    type: 'ink', blend: 0.75, inkStrength: 0.9, inkSpread: 0.35, inkRoughness: 0.4, paperInfluence: 0.75, grainInfluence: 0.5, halftone: 0,
+    displacement: 0.6, surfaceContrast: 1, lift: 0.1, shadow: 0.6, gloss: 0.1, emboss: 0.15,
+  },
+  view: { yaw: 0, pitch: 0, zoom: 1, roll: 0, autoCenter: true, motion: 1 },
+  animation: {
+    duration: 9000, loop: true,
+    stages: [
+      { key: 'wrap', start: 0.04, end: 0.24, easing: 'ease-in-out', label: 'wrap' },
+      { key: 'blend', start: 0.3, end: 0.62, easing: 'ease-in-out', label: 'print' },
+    ],
+  },
+};
+
+/* ---------------- controls: the schema a UI or an agent reads ---------------- */
+
+export type TSControl = {
+  path: string;
+  label: string;
+  group: 'text' | 'typography' | 'placement' | 'surface' | 'deformation' | 'fold' | 'wraps' | 'material' | 'view' | 'animation';
+  kind: 'number' | 'enum' | 'color' | 'boolean' | 'text';
+  min?: number;
+  max?: number;
+  step?: number;
+  options?: readonly (string | number)[];
+  unit?: string;
+  hint: string;
+};
+
+const n = (path: string, label: string, group: TSControl['group'], min: number, max: number, step: number, hint: string, unit?: string): TSControl =>
+  ({ path, label, group, kind: 'number', min, max, step, hint, unit });
+const e = (path: string, label: string, group: TSControl['group'], options: readonly (string | number)[], hint: string): TSControl =>
+  ({ path, label, group, kind: 'enum', options, hint });
+const c = (path: string, label: string, group: TSControl['group'], hint: string): TSControl => ({ path, label, group, kind: 'color', hint });
+const b = (path: string, label: string, group: TSControl['group'], hint: string): TSControl => ({ path, label, group, kind: 'boolean', hint });
+
+const foldControls = (key: (typeof TS_FOLD_KEYS)[number], name: string): TSControl[] => [
+  n(`deformation.${key}.amount`, `${name} amount`, 'fold', 0, 1, 0.01, 'how far the fold has gone; the angle reached is angle × amount'),
+  n(`deformation.${key}.position`, `${name} position`, 'fold', 0.05, 0.95, 0.005, 'where the crease runs, across the surface'),
+  n(`deformation.${key}.angle`, `${name} angle`, 'fold', 0, 180, 1, 'the angle at full amount; 180 folds flat', '°'),
+  n(`deformation.${key}.width`, `${name} width`, 'fold', 0.004, 0.5, 0.001, 'the rounded crease, as a share of the width'),
+  n(`deformation.${key}.influence`, `${name} influence`, 'fold', 0, 1, 0.01, 'how strongly the crease shades the paper and the letters'),
+  e(`deformation.${key}.orientation`, `${name} orientation`, 'fold', TS_FOLD_ORIENTATIONS, 'a vertical crease folds left/right; horizontal folds top/bottom'),
+  e(`deformation.${key}.direction`, `${name} direction`, 'fold', TS_FOLD_DIRECTIONS, 'over lifts toward the camera; under tucks beneath'),
+  e(`deformation.${key}.side`, `${name} side`, 'fold', TS_FOLD_SIDES, 'which side moves: far = right/below the crease, near = left/above'),
+];
+const wrapControls = (key: (typeof TS_WRAP_KEYS)[number], name: string): TSControl[] => [
+  n(`deformation.${key}.amount`, `${name} amount`, 'wraps', 0, 1, 0.01, 'how far round the rod the sheet has wrapped'),
+  n(`deformation.${key}.position`, `${name} position`, 'wraps', 0.02, 0.98, 0.005, 'where the wrap starts, across the surface'),
+  n(`deformation.${key}.radius`, `${name} radius`, 'wraps', 0.01, 0.5, 0.005, 'the rod, as a share of the width'),
+  n(`deformation.${key}.angle`, `${name} angle`, 'wraps', 0, 360, 1, 'how far round at full amount; 360 goes all the way', '°'),
+  e(`deformation.${key}.orientation`, `${name} orientation`, 'wraps', TS_FOLD_ORIENTATIONS, 'vertical rod or horizontal rod'),
+  e(`deformation.${key}.direction`, `${name} direction`, 'wraps', TS_FOLD_DIRECTIONS, 'over wraps toward the camera; under wraps away'),
+  e(`deformation.${key}.side`, `${name} side`, 'wraps', TS_FOLD_SIDES, 'which side wraps: far = right/below, near = left/above'),
+];
+
+/** Every knob: path, range, unit and what it does. Validation, the playground and agents all read this. */
+export const TS_CONTROLS: TSControl[] = [
+  { path: 'text', label: 'Text', group: 'text', kind: 'text', hint: 'any words; \\n breaks a line' },
+  { path: 'typography.fontFamily', label: 'Font family', group: 'typography', kind: 'text', hint: 'any CSS font-family list the page has loaded' },
+  n('typography.fontWeight', 'Weight', 'typography', 100, 900, 100, 'font weight'),
+  e('typography.fontStyle', 'Style', 'typography', ['normal', 'italic'], 'upright or italic'),
+  n('typography.fontSize', 'Size', 'typography', 12, 400, 1, 'surface units; the surface is 1000 wide', 'u'),
+  n('typography.letterSpacing', 'Letter spacing', 'typography', -40, 120, 1, 'extra space between letters', 'u'),
+  n('typography.lineHeight', 'Line height', 'typography', 0.6, 2.5, 0.01, 'line pitch as a multiple of the size'),
+  e('typography.align', 'Alignment', 'typography', TS_ALIGNS, 'how lines align in the block'),
+  c('typography.color', 'Colour', 'typography', 'the letters'),
+  b('typography.gradient.enabled', 'Gradient', 'typography', 'fill the letters with a two-colour gradient'),
+  c('typography.gradient.from', 'Gradient from', 'typography', 'first stop'),
+  c('typography.gradient.to', 'Gradient to', 'typography', 'last stop'),
+  n('typography.gradient.angle', 'Gradient angle', 'typography', 0, 360, 1, '0 runs left → right; 90 runs top → bottom', '°'),
+  n('typography.opacity', 'Opacity', 'typography', 0, 1, 0.01, 'of the letters'),
+  e('typography.blendMode', 'Blend mode', 'typography', TS_BLEND_MODES, 'how the letters combine with the surface once printed'),
+  n('placement.x', 'Position X', 'placement', 0, 1, 0.001, 'centre of the text, 0–1 across the surface'),
+  n('placement.y', 'Position Y', 'placement', 0, 1, 0.001, 'centre of the text, 0–1 down the surface'),
+  n('placement.rotation', 'Rotation', 'placement', -180, 180, 0.5, 'on the surface, clockwise', '°'),
+  n('placement.maxWidth', 'Max width', 'placement', 0, 1000, 5, 'lines wrap past this width; 0 never wraps', 'u'),
+  e('surface.type', 'Surface', 'surface', TS_SURFACES, 'what the text meets'),
+  { path: 'surface.state', label: 'State', group: 'surface', kind: 'text', hint: 'a named state of the surface (flat, folded, crumpled…)' },
+  n('surface.seed', 'Seed', 'surface', 0, 99999, 1, 'every crease, wrinkle, photo and line of copy'),
+  n('deformation.wrap', 'Wrap', 'deformation', 0, 1, 0.01, 'floating typography → conformed to the surface'),
+  n('deformation.morph', 'Morph', 'deformation', 0, 1, 0.01, 'letters peel off and land one at a time'),
+  n('deformation.perspective', 'Perspective', 'deformation', 0, 1, 0.01, 'from straight above to a low, wide-angle view'),
+  n('deformation.tiltX', 'Horizontal distortion', 'deformation', -1, 1, 0.01, 'turns the object left/right'),
+  n('deformation.tiltY', 'Vertical distortion', 'deformation', -1, 1, 0.01, 'tips the object toward/away'),
+  n('deformation.skew', 'Skew', 'deformation', -1, 1, 0.01, 'shears the surface in its own plane'),
+  n('deformation.curve', 'Curve', 'deformation', 0, 1, 0.01, 'cylindrical curvature: a label on a bottle, a bent plate, an inflated pack'),
+  ...foldControls('fold', 'Fold'),
+  ...foldControls('fold2', 'Second fold'),
+  ...foldControls('fold3', 'Third fold'),
+  ...foldControls('fold4', 'Fourth fold'),
+  ...wrapControls('wrap1', 'Wrap 1'),
+  ...wrapControls('wrap2', 'Wrap 2'),
+  ...wrapControls('wrap3', 'Wrap 3'),
+  ...wrapControls('wrap4', 'Wrap 4'),
+  n('deformation.roll.amount', 'Roll', 'deformation', 0, 1, 0.01, 'rolls the surface up from one edge'),
+  e('deformation.roll.edge', 'Roll from', 'deformation', TS_ROLL_EDGES, 'the edge that rolls first'),
+  n('deformation.roll.radius', 'Roll radius', 'deformation', 0.03, 0.3, 0.005, 'outer radius of the roll, as a share of the width'),
+  e('deformation.roll.direction', 'Roll direction', 'deformation', TS_FOLD_DIRECTIONS, 'under keeps the printed side outside'),
+  n('deformation.crumple.amount', 'Crumple', 'deformation', 0, 1, 0.01, 'creased facets; past 0.6 the sheet is crushed'),
+  n('deformation.crumple.scale', 'Crumple scale', 'deformation', 0.4, 2.5, 0.01, 'size of the facets'),
+  n('deformation.wave', 'Wave', 'deformation', 0, 1, 0.01, 'soft waves: fabric drape, a rippled pane'),
+  n('deformation.wrinkle', 'Wrinkle', 'deformation', 0, 1, 0.01, 'fine wrinkles: film, creased cloth'),
+  e('material.type', 'Material', 'material', TS_TEXT_MATERIALS, 'how the letters join the surface'),
+  n('material.blend', 'Blend', 'material', 0, 1, 0.01, 'floating → lit by the surface → printed → embedded'),
+  n('material.inkStrength', 'Ink strength', 'material', 0, 1, 0.01, 'how dark and saturated the ink prints'),
+  n('material.inkSpread', 'Ink spread', 'material', 0, 1, 0.01, 'ink bleeding into the fibres'),
+  n('material.inkRoughness', 'Ink roughness', 'material', 0, 1, 0.01, 'ragged, uneven ink edges'),
+  n('material.paperInfluence', 'Paper influence', 'material', 0, 1, 0.01, 'how much of the surface colour shows through'),
+  n('material.grainInfluence', 'Grain influence', 'material', 0, 1, 0.01, 'paper grain breaking up the ink'),
+  n('material.halftone', 'Halftone', 'material', 0, 1, 0.01, 'embedded ink becomes a printing screen'),
+  n('material.displacement', 'Displacement', 'material', 0, 4, 0.05, 'ink misregistration, surface units', 'u'),
+  n('material.surfaceContrast', 'Surface contrast', 'material', 0, 1.5, 0.01, 'how much surface light and shadow fall on the letters'),
+  n('material.lift', 'Float height', 'material', 0, 0.4, 0.005, 'how high floating letters hover'),
+  n('material.shadow', 'Float shadow', 'material', 0, 1, 0.01, 'the shadow the letters cast while floating'),
+  n('material.gloss', 'Gloss', 'material', 0, 1, 0.01, 'varnish on the letters'),
+  n('material.emboss', 'Emboss', 'material', 0, 1, 0.01, 'relief depth'),
+  n('view.yaw', 'Orbit', 'view', -180, 180, 0.5, 'camera left/right', '°'),
+  n('view.pitch', 'Tilt', 'view', -30, 60, 0.5, 'camera tilt, added to perspective', '°'),
+  n('view.zoom', 'Zoom', 'view', 0.4, 3, 0.01, '1 fills the frame'),
+  n('view.roll', 'Object angle', 'view', -180, 180, 0.5, 'turns the object on the table', '°'),
+  b('view.autoCenter', 'Auto-centre', 'view', 'keep the object centred while it folds and rolls'),
+  n('view.motion', 'Ambient motion', 'view', 0, 2, 0.01, 'time-driven motion: fabric in a breeze, a bottle turning'),
+  n('animation.duration', 'Length', 'animation', 1000, 60000, 100, 'one pass of the timeline', 'ms'),
+  b('animation.loop', 'Loop', 'animation', 'play again from the start'),
+];
+
+/* ---------------- resolve, validate, sanitize ---------------- */
+
+export type TSConfigError = { path: string; message: string };
+export const MAX_TS_TEXT_LENGTH = 160;
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+export const isHexColor = (v: unknown): v is string => typeof v === 'string' && /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(v);
+
+export function getPath(obj: unknown, path: string): unknown {
+  return path.split('.').reduce<unknown>((o, k) => (isObj(o) ? o[k] : undefined), obj);
+}
+export function setPath<T>(obj: T, path: string, value: unknown): T {
+  const [head, ...rest] = path.split('.');
+  const o = (isObj(obj) ? obj : {}) as Record<string, unknown>;
+  return { ...o, [head!]: rest.length ? setPath(o[head!], rest.join('.'), value) : value } as T;
+}
+
+/** Deep merge of plain objects; arrays and scalars in `over` replace. */
+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] = v === undefined ? out[k] : merge((base as Record<string, unknown>)[k], v);
+  return out as T;
+}
+
+/** Defaults ← input. Pure; does not validate (see `validateTypeSurface` / `sanitizeTypeSurface`). */
+export function resolveTypeSurface(input: TypeSurfaceConfigInput = {}, base: TypeSurfaceConfig = DEFAULT_TYPE_SURFACE): TypeSurfaceConfig {
+  return merge(base, input);
+}
+
+function checkControl(ctl: TSControl, v: unknown): string | null {
+  switch (ctl.kind) {
+    case 'number':
+      if (typeof v !== 'number' || !Number.isFinite(v)) return `${ctl.label} must be a number.`;
+      if (v < ctl.min! || v > ctl.max!) return `${ctl.label} must be between ${ctl.min} and ${ctl.max}.`;
+      return null;
+    case 'enum':
+      if (ctl.path === 'surface.type' && typeof v === 'string' && hasSurface(v)) return null;
+      return ctl.options!.includes(v as string) ? null : `${ctl.label} must be one of: ${ctl.options!.join(', ')}.`;
+    case 'color': return isHexColor(v) ? null : `${ctl.label} must be a hex colour like #E0271B.`;
+    case 'boolean': return typeof v === 'boolean' ? null : `${ctl.label} must be true or false.`;
+    case 'text':
+      if (typeof v !== 'string') return `${ctl.label} must be text.`;
+      if (ctl.path === 'text' && v.length > MAX_TS_TEXT_LENGTH) return `Text is limited to ${MAX_TS_TEXT_LENGTH} characters.`;
+      if (ctl.path === 'typography.fontFamily' && !v.trim()) return 'Font family must name a font.';
+      return null;
+  }
+}
+
+function checkStages(stages: unknown): TSConfigError[] {
+  if (!Array.isArray(stages)) return [{ path: 'animation.stages', message: 'Stages must be a list.' }];
+  const errors: TSConfigError[] = [];
+  stages.forEach((s, i) => {
+    const p = `animation.stages.${i}`;
+    if (!isObj(s)) { errors.push({ path: p, message: 'A stage must be an object.' }); return; }
+    if (!TS_ANIMATABLE.includes(s.key as TSAnimatable)) errors.push({ path: `${p}.key`, message: `A stage drives one of: ${TS_ANIMATABLE.join(', ')}.` });
+    const t = (k: string) => typeof s[k] === 'number' && Number.isFinite(s[k] as number) && (s[k] as number) >= 0 && (s[k] as number) <= 1;
+    if (!t('start') || !t('end')) errors.push({ path: p, message: 'start and end are 0–1 of the timeline.' });
+    else if ((s.end as number) < (s.start as number)) errors.push({ path: p, message: 'end must not come before start.' });
+    if ((s.outStart !== undefined || s.outEnd !== undefined)) {
+      if (!t('outStart') || !t('outEnd')) errors.push({ path: p, message: 'outStart and outEnd are 0–1 of the timeline.' });
+      else if ((s.outEnd as number) < (s.outStart as number) || (s.outStart as number) < (s.end as number)) errors.push({ path: p, message: 'A stage goes out after it comes in: end ≤ outStart ≤ outEnd.' });
+    }
+  });
+  return errors;
+}
+
+/** `[]` when the config can be drawn; otherwise every problem as `{ path, message }`. Never throws. */
+export function validateTypeSurface(config: unknown): TSConfigError[] {
+  if (!isObj(config)) return [{ path: '', message: 'The config must be an object.' }];
+  const errors: TSConfigError[] = [];
+  for (const ctl of TS_CONTROLS) {
+    const msg = checkControl(ctl, getPath(config, ctl.path));
+    if (msg) errors.push({ path: ctl.path, message: msg });
+  }
+  errors.push(...checkStages(getPath(config, 'animation.stages')));
+  return errors;
+}
+
+/**
+ * A config that always draws: every invalid field is replaced by its default and named in
+ * `invalid`. The renderer draws the result and the playground lists what it replaced.
+ */
+export function sanitizeTypeSurface(input: unknown): { config: TypeSurfaceConfig; invalid: string[] } {
+  let config = resolveTypeSurface(isObj(input) ? (input as TypeSurfaceConfigInput) : {});
+  const invalid: string[] = [];
+  for (const err of validateTypeSurface(config)) {
+    if (err.path.startsWith('animation.stages')) {
+      config = { ...config, animation: { ...config.animation, stages: [] } };
+      if (!invalid.includes('animation.stages')) invalid.push('animation.stages');
+      continue;
+    }
+    config = setPath(config, err.path, getPath(DEFAULT_TYPE_SURFACE, err.path));
+    invalid.push(err.path);
+  }
+  return { config, invalid };
+}