@appinternalleads/ui 0.4.1 → 0.4.2

package/src/motion/typesurface/construct.ts

@@ -0,0 +1,828 @@
+/* eslint-disable comppack/no-raw-colour -- object, material and backdrop colours are scene content, not theme colours. */
+/**
+ * **The construction layer** — objects built from parts, not a catalogue of finished objects.
+ *
+ *   primitives     cylinder, sphere, ring, revolve (any profile), tube (along a path), box
+ *   manipulators   taper, flare, bulge, twist, bend, scale: applied to a part, in order
+ *   materials      plastic, matte, ceramic, glass, metal, chrome, in any colour
+ *   text           wraps one round part: printed straight onto it, or on a paper label
+ *   recipes        tumbler, mug, can, bottle: compositions of the above, nothing they alone can do
+ *
+ * An object is JSON (`TSObjectSpec`) and lives in the config as `object`, so what an agent builds
+ * is a preset it can save and edit later. `describeConstruction()` is the machine-readable
+ * manifest: every primitive, what can be done to it, and every parameter with its range, so an
+ * agent composes a tumbler (cylinder + taper + ring) without one having been written for it.
+ * `sanitizeObject` reads the same manifest: it never throws and always returns something drawable.
+ *
+ * Frame: y is up and is the object's axis; x is to the right of the camera, z toward it. Units are
+ * the lab's world units (the wine bottle's body is 0.36 in radius); the camera frames whatever is
+ * built. Pure; no DOM, no React.
+ */
+import { smoothstep, type Vec3 } from './ops';
+
+/* ---------------- the manifest ---------------- */
+
+export type TSParam =
+  | { type: 'number'; min: number; max: number; default: number; unit?: string; hint: string }
+  | { type: 'boolean'; default: boolean; hint: string }
+  | { type: 'enum'; options: readonly string[]; default: string; hint: string }
+  /** A list of points: `dims` numbers each, at least `min` of them. */
+  | { type: 'points'; dims: 2 | 3; min: number; max: number; hint: string };
+
+const num = (min: number, max: number, def: number, hint: string, unit?: string): TSParam => ({ type: 'number', min, max, default: def, hint, ...(unit ? { unit } : {}) });
+
+export const TS_MANIPULATOR_IDS = ['taper', 'flare', 'bulge', 'twist', 'bend', 'scale'] as const;
+export type TSManipulatorId = (typeof TS_MANIPULATOR_IDS)[number];
+
+/** What can be done to a part. Each acts in the part's own frame, before it is turned and placed. */
+export const TS_MANIPULATORS: Record<TSManipulatorId, { summary: string; keepsRound: boolean; params: Record<string, TSParam> }> = {
+  taper: {
+    summary: 'Scales the part about its axis, from one factor at the bottom to another at the top: a cone, a tapered cup.',
+    keepsRound: true,
+    params: { bottom: num(0.05, 3, 1, 'radius factor at the bottom of the part'), top: num(0.05, 3, 1, 'radius factor at the top of the part') },
+  },
+  flare: {
+    summary: 'Widens (or, negative, narrows) the part toward one end: a lip, a shoulder, a can’s necked top.',
+    keepsRound: true,
+    params: {
+      amount: num(-0.9, 2, 0.2, 'extra radius at the end, as a share of the radius; negative narrows'),
+      start: num(0, 0.98, 0.7, 'where along the part the flare begins, 0–1 toward the end'),
+      end: { type: 'enum', options: ['top', 'bottom'], default: 'top', hint: 'which end flares' },
+    },
+  },
+  bulge: {
+    summary: 'Swells (or, negative, pinches) the part around a height: a belly, a waist, a grip.',
+    keepsRound: true,
+    params: {
+      amount: num(-0.9, 2, 0.2, 'extra radius at the centre of the bulge; negative pinches'),
+      center: num(0, 1, 0.5, 'where along the part, 0 bottom – 1 top'),
+      width: num(0.03, 1, 0.25, 'how much of the part it spans'),
+    },
+  },
+  twist: { summary: 'Turns the part about its axis, more with height.', keepsRound: true, params: { angle: num(-720, 720, 90, 'turn reached at the top', '°') } },
+  bend: { summary: 'Bends the part’s axis into an arc toward +x: a spout, a curved neck.', keepsRound: false, params: { angle: num(-270, 270, 45, 'the arc the axis turns through', '°') } },
+  scale: {
+    summary: 'Stretches the part along x, y and z: an oval body, a squashed sphere.',
+    keepsRound: false,
+    params: { x: num(0.05, 5, 1, 'across'), y: num(0.05, 5, 1, 'along the axis'), z: num(0.05, 5, 1, 'toward the camera') },
+  },
+};
+
+export const TS_PRIMITIVE_IDS = ['cylinder', 'sphere', 'ring', 'revolve', 'tube', 'box'] as const;
+export type TSPrimitiveId = (typeof TS_PRIMITIVE_IDS)[number];
+/** A manipulator a primitive accepts, plus `material` (every part) and `text-wrap` (it can carry the text). */
+export type TSCapability = TSManipulatorId | 'material' | 'text-wrap';
+
+const ALL_OPS: TSCapability[] = [...TS_MANIPULATOR_IDS, 'material'];
+
+/** What an object is built from. `origin` says where `at` puts the part. */
+export const TS_PRIMITIVES: Record<TSPrimitiveId, { summary: string; origin: 'base' | 'centre' | 'path'; capabilities: readonly TSCapability[]; params: Record<string, TSParam> }> = {
+  cylinder: {
+    summary: 'A round body standing on its base. `hollow` makes it a cup with a wall, a floor and a rounded rim.',
+    origin: 'base', capabilities: [...ALL_OPS, 'text-wrap'],
+    params: {
+      radius: num(0.01, 2, 0.36, 'outer radius'),
+      height: num(0.005, 4, 1, 'from base to top'),
+      hollow: num(0, 0.5, 0, 'wall thickness; 0 is solid, anything else is open at the top'),
+      round: num(0, 0.5, 0, 'radius of the rounded top and bottom edges'),
+    },
+  },
+  sphere: { summary: 'A ball, centred.', origin: 'centre', capabilities: [...ALL_OPS, 'text-wrap'], params: { radius: num(0.01, 2, 0.3, 'radius') } },
+  ring: {
+    summary: 'A torus lying flat around the axis: a rim, a lip, a band, a gasket.',
+    origin: 'centre', capabilities: ALL_OPS,
+    params: { radius: num(0.01, 2, 0.36, 'from the axis to the centre of the band'), thickness: num(0.002, 0.5, 0.02, 'radius of the band itself') },
+  },
+  revolve: {
+    summary: 'Any profile turned about the axis: a vase, a bottle with shoulders, a lampshade, a bowl. Draw the outline as [radius, y] points; draw down the inside too for a hollow one.',
+    origin: 'base', capabilities: [...ALL_OPS, 'text-wrap'],
+    params: {
+      profile: { type: 'points', dims: 2, min: 2, max: 64, hint: '[radius, y] points along the outline, in order' },
+      smooth: { type: 'boolean', default: false, hint: 'run a smooth curve through the points instead of straight segments' },
+    },
+  },
+  tube: {
+    summary: 'A round bar along a path: a handle, a straw, a spout, a strap.',
+    origin: 'path', capabilities: ALL_OPS,
+    params: {
+      path: { type: 'points', dims: 3, min: 2, max: 32, hint: '[x, y, z] points the bar runs through, in order' },
+      radius: num(0.003, 1, 0.04, 'radius of the bar'),
+      smooth: { type: 'boolean', default: true, hint: 'run a smooth curve through the points' },
+    },
+  },
+  box: {
+    summary: 'A block, centred: a lid tab, a foot, a slab, a clip.',
+    origin: 'centre', capabilities: ALL_OPS,
+    params: { width: num(0.005, 4, 0.5, 'along x'), height: num(0.005, 4, 0.5, 'along y'), depth: num(0.005, 4, 0.5, 'along z') },
+  },
+};
+
+export const TS_OBJECT_MATERIAL_IDS = ['plastic', 'matte', 'ceramic', 'glass', 'metal', 'chrome'] as const;
+export type TSObjectMaterialId = (typeof TS_OBJECT_MATERIAL_IDS)[number];
+
+/** How a part shades. `metalness` tints the reflection with the colour; `reflection` is how much of the studio it shows. */
+export const TS_OBJECT_MATERIALS: Record<TSObjectMaterialId, { summary: string; metalness: number; roughness: number; reflection: number; gain: number }> = {
+  plastic: { summary: 'Moulded plastic: coloured, a soft highlight.', metalness: 0, roughness: 0.38, reflection: 0.35, gain: 1 },
+  matte: { summary: 'Powder coat, rubber, card: colour with almost no shine.', metalness: 0, roughness: 0.9, reflection: 0.06, gain: 1 },
+  ceramic: { summary: 'Glazed ceramic or enamel: colour under a glossy coat.', metalness: 0, roughness: 0.12, reflection: 0.7, gain: 1 },
+  glass: { summary: 'Dark, tinted glass: nearly black in the body, the studio in its reflection. Not see-through.', metalness: 0, roughness: 0.04, reflection: 1.1, gain: 0.55 },
+  metal: { summary: 'Brushed or satin metal (stainless, aluminium); a colour anodises it.', metalness: 1, roughness: 0.4, reflection: 1, gain: 1 },
+  chrome: { summary: 'Polished metal: a mirror of the studio.', metalness: 1, roughness: 0.05, reflection: 1.15, gain: 1 },
+};
+
+export const TS_OBJECT_TABLES = ['studio', 'desk', 'wood'] as const;
+
+/* ---------------- the spec ---------------- */
+
+export type TSOp = { op: TSManipulatorId } & Record<string, number | string>;
+
+export type TSPartMaterial = {
+  type: TSObjectMaterialId;
+  color: string;
+  /** Override the material's own roughness / metalness, 0–1. */
+  roughness?: number;
+  metalness?: number;
+};
+
+export type TSPart = {
+  /** Unique within the object; `text.on` names one. */
+  id: string;
+  shape: TSPrimitiveId;
+  /** The primitive's parameters (`TS_PRIMITIVES[shape].params`); anything omitted takes its default. */
+  params: Record<string, unknown>;
+  /** Manipulators, applied in order. */
+  ops: TSOp[];
+  material: TSPartMaterial;
+  /** Where the part goes, in the object's frame. */
+  at: [number, number, number];
+  /** Degrees about x, then y, then z. */
+  rotate: [number, number, number];
+};
+
+export type TSObjectText = {
+  /** The part the text wraps. It must be round, on the axis and unturned. */
+  on: string;
+  /** Centre of the text area along the part's height, 0 bottom – 1 top. */
+  y: number;
+  /** Height of the text area, as a share of the part's height. */
+  height: number;
+  /** How far round the part the text area reaches, degrees (360 goes all the way). */
+  arc: number;
+  /** A paper label in this colour; null prints straight onto the part. */
+  label: string | null;
+};
+
+export type TSObjectSpec = {
+  name: string;
+  parts: TSPart[];
+  text: TSObjectText;
+  scene: { table: (typeof TS_OBJECT_TABLES)[number]; backdrop: [string, string] };
+};
+
+export const TS_OBJECT_TEXT_PARAMS: Record<'y' | 'height' | 'arc', TSParam> = {
+  y: num(0, 1, 0.5, 'centre of the text area along the part, 0 bottom – 1 top'),
+  height: num(0.05, 1, 0.6, 'height of the text area, as a share of the part'),
+  arc: num(20, 360, 160, 'how far round the part the text area reaches', '°'),
+};
+
+export const MAX_OBJECT_PARTS = 24;
+/** How much of a round part's circumference reads from the front, degrees: text wider than this runs out of sight. */
+export const OBJECT_FRONT_ARC = 110;
+const DEFAULT_SCENE: TSObjectSpec['scene'] = { table: 'studio', backdrop: ['#d9dadc', '#b9bbbf'] };
+const FALLBACK_COLOR = '#8A8F98';
+
+/* ---------------- sanitize / validate ---------------- */
+
+export type TSObjectError = { path: string; message: string };
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isHex = (v: unknown): v is string => typeof v === 'string' && /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(v);
+const isNum = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+
+function fixParam(spec: TSParam, v: unknown, path: string, errors: TSObjectError[], required = false): unknown {
+  switch (spec.type) {
+    case 'number':
+      if (v === undefined && !required) return spec.default;
+      if (!isNum(v)) { errors.push({ path, message: `Must be a number between ${spec.min} and ${spec.max}.` }); return spec.default; }
+      if (v < spec.min || v > spec.max) { errors.push({ path, message: `Must be between ${spec.min} and ${spec.max}.` }); return Math.min(spec.max, Math.max(spec.min, v)); }
+      return v;
+    case 'boolean':
+      if (v === undefined) return spec.default;
+      if (typeof v !== 'boolean') { errors.push({ path, message: 'Must be true or false.' }); return spec.default; }
+      return v;
+    case 'enum':
+      if (v === undefined) return spec.default;
+      if (typeof v !== 'string' || !spec.options.includes(v)) { errors.push({ path, message: `Must be one of: ${spec.options.join(', ')}.` }); return spec.default; }
+      return v;
+    case 'points': {
+      const ok = Array.isArray(v) && v.length >= spec.min && v.length <= spec.max
+        && v.every((p) => Array.isArray(p) && p.length === spec.dims && p.every((n) => isNum(n) && Math.abs(n) <= 8));
+      if (!ok) { errors.push({ path, message: `Must be ${spec.min}–${spec.max} points of ${spec.dims} numbers each.` }); return null; }
+      return (v as number[][]).map((p) => [...p]);
+    }
+  }
+}
+
+function fixVec3(v: unknown, limit: number, path: string, errors: TSObjectError[]): [number, number, number] {
+  if (v === undefined) return [0, 0, 0];
+  if (!Array.isArray(v) || v.length !== 3 || !v.every((n) => isNum(n) && Math.abs(n) <= limit)) {
+    errors.push({ path, message: `Must be three numbers within ±${limit}.` });
+    return [0, 0, 0];
+  }
+  return [v[0] as number, v[1] as number, v[2] as number];
+}
+
+/** A part that can carry the text: a round primitive, on the axis, unturned, with only round-keeping manipulators. */
+function textCapable(p: TSPart): string | null {
+  if (!TS_PRIMITIVES[p.shape].capabilities.includes('text-wrap')) return `a ${p.shape} cannot carry text; use a cylinder, sphere or revolve`;
+  if (p.at[0] !== 0 || p.at[2] !== 0 || p.rotate.some((r) => r !== 0)) return 'the part that carries text must sit on the axis, unturned (at x = z = 0, rotate 0)';
+  const bad = p.ops.find((o) => !TS_MANIPULATORS[o.op].keepsRound);
+  if (bad) return `the part that carries text must stay round; remove its ${bad.op}`;
+  return null;
+}
+
+/**
+ * A spec that always builds: every bad field is replaced (numbers are clamped, the rest take their
+ * default, parts and manipulators that make no sense are dropped) and named in `errors`. Returns
+ * `object: null` only when nothing in it can be drawn.
+ */
+export function sanitizeObject(input: unknown, base = 'object'): { object: TSObjectSpec | null; errors: TSObjectError[] } {
+  const errors: TSObjectError[] = [];
+  if (!isObj(input)) return { object: null, errors: [{ path: base, message: 'An object must be { name, parts, text }.' }] };
+  const rawParts = Array.isArray(input.parts) ? input.parts : [];
+  if (!Array.isArray(input.parts) || rawParts.length === 0) errors.push({ path: `${base}.parts`, message: 'An object needs at least one part.' });
+  if (rawParts.length > MAX_OBJECT_PARTS) errors.push({ path: `${base}.parts`, message: `An object has at most ${MAX_OBJECT_PARTS} parts.` });
+
+  const parts: TSPart[] = [];
+  const ids = new Set<string>();
+  rawParts.slice(0, MAX_OBJECT_PARTS).forEach((raw, i) => {
+    const p = `${base}.parts.${i}`;
+    if (!isObj(raw)) { errors.push({ path: p, message: 'A part must be an object.' }); return; }
+    const shape = raw.shape as TSPrimitiveId;
+    if (!TS_PRIMITIVE_IDS.includes(shape)) { errors.push({ path: `${p}.shape`, message: `A part is one of: ${TS_PRIMITIVE_IDS.join(', ')}.` }); return; }
+    let id = typeof raw.id === 'string' && raw.id.trim() ? raw.id : '';
+    if (!id || ids.has(id)) {
+      errors.push({ path: `${p}.id`, message: id ? `Two parts are called “${id}”.` : 'A part needs an id.' });
+      id = `${shape}-${i}`;
+    }
+    ids.add(id);
+    const prim = TS_PRIMITIVES[shape];
+    const rawParams = isObj(raw.params) ? raw.params : {};
+    if (raw.params !== undefined && !isObj(raw.params)) errors.push({ path: `${p}.params`, message: 'params must be an object.' });
+    const params: Record<string, unknown> = {};
+    let drawable = true;
+    for (const [k, spec] of Object.entries(prim.params)) {
+      const v = fixParam(spec, rawParams[k], `${p}.params.${k}`, errors);
+      if (v === null) drawable = false; else params[k] = v;
+    }
+    for (const k of Object.keys(rawParams)) if (!(k in prim.params)) errors.push({ path: `${p}.params.${k}`, message: `A ${shape} has no “${k}”; it takes: ${Object.keys(prim.params).join(', ')}.` });
+    if (!drawable) return;
+
+    const ops: TSOp[] = [];
+    if (raw.ops !== undefined && !Array.isArray(raw.ops)) errors.push({ path: `${p}.ops`, message: 'ops must be a list.' });
+    (Array.isArray(raw.ops) ? raw.ops : []).forEach((o, k) => {
+      const op = `${p}.ops.${k}`;
+      const name = isObj(o) ? (o.op as TSManipulatorId) : undefined;
+      if (!isObj(o) || !name || !TS_MANIPULATOR_IDS.includes(name)) { errors.push({ path: op, message: `A manipulator is { op } with op one of: ${TS_MANIPULATOR_IDS.join(', ')}.` }); return; }
+      if (!prim.capabilities.includes(name)) { errors.push({ path: op, message: `A ${shape} cannot ${name}.` }); return; }
+      const out: TSOp = { op: name };
+      for (const [key, spec] of Object.entries(TS_MANIPULATORS[name].params)) out[key] = fixParam(spec, o[key], `${op}.${key}`, errors) as number | string;
+      for (const key of Object.keys(o)) if (key !== 'op' && !(key in TS_MANIPULATORS[name].params)) errors.push({ path: `${op}.${key}`, message: `${name} has no “${key}”; it takes: ${Object.keys(TS_MANIPULATORS[name].params).join(', ')}.` });
+      ops.push(out);
+    });
+
+    const rm = isObj(raw.material) ? raw.material : {};
+    if (!isObj(raw.material)) errors.push({ path: `${p}.material`, message: 'A part needs a material: { type, color }.' });
+    let type = rm.type as TSObjectMaterialId;
+    if (!TS_OBJECT_MATERIAL_IDS.includes(type)) {
+      if (isObj(raw.material)) errors.push({ path: `${p}.material.type`, message: `A material is one of: ${TS_OBJECT_MATERIAL_IDS.join(', ')}.` });
+      type = 'plastic';
+    }
+    let color = rm.color as string;
+    if (!isHex(color)) {
+      if (isObj(raw.material)) errors.push({ path: `${p}.material.color`, message: 'A colour is a hex like #1F8A8A.' });
+      color = FALLBACK_COLOR;
+    }
+    const material: TSPartMaterial = { type, color };
+    for (const k of ['roughness', 'metalness'] as const) {
+      if (rm[k] === undefined) continue;
+      if (!isNum(rm[k]) || (rm[k] as number) < 0 || (rm[k] as number) > 1) errors.push({ path: `${p}.material.${k}`, message: 'Must be between 0 and 1.' });
+      else material[k] = rm[k] as number;
+    }
+    parts.push({ id, shape, params, ops, material, at: fixVec3(raw.at, 8, `${p}.at`, errors), rotate: fixVec3(raw.rotate, 360, `${p}.rotate`, errors) });
+  });
+  if (parts.length === 0) return { object: null, errors };
+
+  // The text: on a part that can carry it; otherwise the first that can.
+  const rt = isObj(input.text) ? input.text : {};
+  if (input.text !== undefined && !isObj(input.text)) errors.push({ path: `${base}.text`, message: 'text must be { on, y, height, arc, label }.' });
+  const firstCapable = parts.find((p) => textCapable(p) === null);
+  let host = parts.find((p) => p.id === rt.on);
+  if (!host) {
+    if (rt.on !== undefined) errors.push({ path: `${base}.text.on`, message: `No part is called “${String(rt.on)}”; parts: ${parts.map((p) => p.id).join(', ')}.` });
+    host = firstCapable;
+  } else {
+    const why = textCapable(host);
+    if (why) { errors.push({ path: `${base}.text.on`, message: `Text cannot wrap “${host.id}”: ${why}.` }); host = firstCapable; }
+  }
+  if (!host) {
+    errors.push({ path: `${base}.text.on`, message: 'No part can carry text: the object needs a cylinder, sphere or revolve on the axis.' });
+    return { object: null, errors };
+  }
+  let label: string | null = null;
+  if (rt.label !== undefined && rt.label !== null) {
+    if (isHex(rt.label)) label = rt.label; else errors.push({ path: `${base}.text.label`, message: 'label is a hex colour, or null to print straight onto the part.' });
+  }
+  const text: TSObjectText = {
+    on: host.id,
+    y: fixParam(TS_OBJECT_TEXT_PARAMS.y, rt.y, `${base}.text.y`, errors) as number,
+    height: fixParam(TS_OBJECT_TEXT_PARAMS.height, rt.height, `${base}.text.height`, errors) as number,
+    arc: fixParam(TS_OBJECT_TEXT_PARAMS.arc, rt.arc, `${base}.text.arc`, errors) as number,
+    label,
+  };
+
+  const rs = isObj(input.scene) ? input.scene : {};
+  let table = rs.table as TSObjectSpec['scene']['table'];
+  if (!TS_OBJECT_TABLES.includes(table)) {
+    if (rs.table !== undefined) errors.push({ path: `${base}.scene.table`, message: `table is one of: ${TS_OBJECT_TABLES.join(', ')}.` });
+    table = DEFAULT_SCENE.table;
+  }
+  let backdrop = DEFAULT_SCENE.backdrop;
+  if (rs.backdrop !== undefined) {
+    if (Array.isArray(rs.backdrop) && rs.backdrop.length === 2 && rs.backdrop.every(isHex)) backdrop = [rs.backdrop[0] as string, rs.backdrop[1] as string];
+    else errors.push({ path: `${base}.scene.backdrop`, message: 'backdrop is two hex colours, top and bottom.' });
+  }
+  let name = input.name as string;
+  if (typeof name !== 'string' || !name.trim() || name.length > 80) {
+    if (input.name !== undefined) errors.push({ path: `${base}.name`, message: 'name is a short label.' });
+    name = 'Object';
+  }
+  return { object: { name, parts, text, scene: { table, backdrop } }, errors };
+}
+
+/** `[]` when the spec is drawable as written; otherwise every problem as `{ path, message }`. Never throws. */
+export function validateObject(spec: unknown, base = 'object'): TSObjectError[] {
+  return sanitizeObject(spec, base).errors;
+}
+
+/* ---------------- geometry ---------------- */
+
+type P2 = [number, number];
+type Grid = { positions: number[]; rows: number; cols: number };
+
+/** Round the interior corners of a polyline; `radii[k]` is the cut for corner k (0 leaves it sharp). */
+function fillet(pts: P2[], radii: number[]): P2[] {
+  const out: P2[] = [pts[0]!];
+  for (let k = 1; k < pts.length - 1; k++) {
+    const a = pts[k - 1]!, b = pts[k]!, c = pts[k + 1]!;
+    const la = Math.hypot(a[0] - b[0], a[1] - b[1]), lc = Math.hypot(c[0] - b[0], c[1] - b[1]);
+    const t = Math.min(radii[k] ?? 0, la * 0.5, lc * 0.5);
+    if (t < 1e-5) { out.push(b); continue; }
+    const p0: P2 = [b[0] + ((a[0] - b[0]) / la) * t, b[1] + ((a[1] - b[1]) / la) * t];
+    const p1: P2 = [b[0] + ((c[0] - b[0]) / lc) * t, b[1] + ((c[1] - b[1]) / lc) * t];
+    const steps = 6;
+    for (let s = 0; s <= steps; s++) {
+      const u = s / steps, v = 1 - u;
+      out.push([v * v * p0[0] + 2 * u * v * b[0] + u * u * p1[0], v * v * p0[1] + 2 * u * v * b[1] + u * u * p1[1]]);
+    }
+  }
+  out.push(pts[pts.length - 1]!);
+  return out;
+}
+
+/** A Catmull-Rom curve through the points. */
+function smoothPath(pts: number[][], sub: number): number[][] {
+  if (pts.length < 3) return pts;
+  const out: number[][] = [];
+  for (let k = 0; k < pts.length - 1; k++) {
+    const p0 = pts[Math.max(0, k - 1)]!, p1 = pts[k]!, p2 = pts[k + 1]!, p3 = pts[Math.min(pts.length - 1, k + 2)]!;
+    for (let s = 0; s < sub; s++) {
+      const t = s / sub, t2 = t * t, t3 = t2 * t;
+      out.push(p1.map((_, d) => 0.5 * (2 * p1[d]! + (p2[d]! - p0[d]!) * t + (2 * p0[d]! - 5 * p1[d]! + 4 * p2[d]! - p3[d]!) * t2 + (3 * p1[d]! - p0[d]! - 3 * p2[d]! + p3[d]!) * t3)));
+    }
+  }
+  out.push(pts[pts.length - 1]!);
+  return out;
+}
+
+/** Split long segments so manipulators have rows to bend. */
+function densify(pts: P2[], step: number): P2[] {
+  const out: P2[] = [];
+  for (let k = 0; k < pts.length - 1; k++) {
+    const a = pts[k]!, b = pts[k + 1]!;
+    const n = Math.max(1, Math.min(48, Math.ceil(Math.hypot(b[0] - a[0], b[1] - a[1]) / step)));
+    for (let s = 0; s < n; s++) out.push([a[0] + ((b[0] - a[0]) * s) / n, a[1] + ((b[1] - a[1]) * s) / n]);
+  }
+  out.push(pts[pts.length - 1]!);
+  return out;
+}
+
+const SEGS = 64;
+
+/** Turn a profile about the y axis. The profile runs anticlockwise (up the outside), so normals face out. */
+function revolve(profile: P2[]): Grid {
+  const cols = SEGS + 1;
+  const positions: number[] = [];
+  for (const [r0, y] of profile) {
+    const r = Math.max(0, r0);
+    for (let q = 0; q <= SEGS; q++) {
+      const a = (q / SEGS) * Math.PI * 2;
+      positions.push(r * Math.sin(a), y, r * Math.cos(a));
+    }
+  }
+  return { positions, rows: profile.length, cols };
+}
+
+function profileFor(shape: TSPrimitiveId, pr: Record<string, unknown>): P2[] {
+  if (shape === 'cylinder') {
+    const r = pr.radius as number, h = pr.height as number, w = Math.min(pr.hollow as number, r * 0.9), e = Math.min(pr.round as number, r * 0.95, h * 0.5);
+    if (w <= 0) return densify(fillet([[0, 0], [r, 0], [r, h], [0, h]], [0, e, e, 0]), h / 28);
+    const floor = Math.min(w, h * 0.5);
+    return densify(fillet([[0, 0], [r, 0], [r, h], [r - w, h], [r - w, floor], [0, floor]], [0, e, w * 0.5, w * 0.5, Math.min(e, (r - w) * 0.9), 0]), h / 28);
+  }
+  if (shape === 'sphere') {
+    const r = pr.radius as number, n = 28;
+    return Array.from({ length: n + 1 }, (_, k): P2 => { const a = -Math.PI / 2 + (Math.PI * k) / n; return [k === 0 || k === n ? 0 : r * Math.cos(a), r * Math.sin(a)]; });
+  }
+  if (shape === 'ring') {
+    const R = pr.radius as number, t = Math.min(pr.thickness as number, R), n = 20;
+    return Array.from({ length: n + 1 }, (_, k): P2 => { const a = (Math.PI * 2 * k) / n - Math.PI / 2; return [R + t * Math.cos(a), t * Math.sin(a)]; });
+  }
+  // revolve: the user's outline, made to run anticlockwise so the outside faces out.
+  let pts = (pr.profile as number[][]).map((p): P2 => [Math.max(0, p[0]!), p[1]!]);
+  if (pr.smooth) pts = smoothPath(pts, 6).map((p): P2 => [Math.max(0, p[0]!), p[1]!]);
+  let area = 0;
+  for (let k = 0; k < pts.length; k++) { const a = pts[k]!, b = pts[(k + 1) % pts.length]!; area += a[0] * b[1] - b[0] * a[1]; }
+  if (area < 0) pts.reverse();
+  const span = Math.max(1e-3, Math.max(...pts.map((p) => p[1])) - Math.min(...pts.map((p) => p[1])));
+  return densify(pts, span / 28);
+}
+
+/** A bar of `radius` along a path, capped at both ends. */
+function tube(path: number[][], radius: number): Grid {
+  const segs = 20, cols = segs + 1;
+  const n = path.length;
+  const positions: number[] = [];
+  const tangent = (k: number): Vec3 => {
+    const a = path[Math.max(0, k - 1)]!, b = path[Math.min(n - 1, k + 1)]!;
+    const l = Math.hypot(b[0]! - a[0]!, b[1]! - a[1]!, b[2]! - a[2]!) || 1;
+    return [(b[0]! - a[0]!) / l, (b[1]! - a[1]!) / l, (b[2]! - a[2]!) / l];
+  };
+  // A frame carried along the path (parallel transport), so the bar doesn't twist.
+  const t0 = tangent(0);
+  const ref: Vec3 = Math.abs(t0[2]) < 0.9 ? [0, 0, 1] : [1, 0, 0];
+  let N = norm3(cross3(cross3(t0, ref), t0));
+  const ring = (k: number, r: number) => {
+    const T = tangent(k);
+    N = norm3([N[0] - T[0] * dot3(N, T), N[1] - T[1] * dot3(N, T), N[2] - T[2] * dot3(N, T)]);
+    const B = cross3(T, N);
+    const c = path[k]!;
+    for (let q = 0; q <= segs; q++) {
+      const a = (q / segs) * Math.PI * 2, ca = Math.cos(a) * r, sa = Math.sin(a) * r;
+      positions.push(c[0]! + N[0] * ca + B[0] * sa, c[1]! + N[1] * ca + B[1] * sa, c[2]! + N[2] * ca + B[2] * sa);
+    }
+  };
+  ring(0, 0);
+  for (let k = 0; k < n; k++) ring(k, radius);
+  ring(n - 1, 0);
+  return { positions, rows: n + 2, cols };
+}
+
+/** A block: six faces, each its own grid so the edges stay sharp. */
+function box(w: number, h: number, d: number): Grid[] {
+  const half: Vec3 = [w / 2, h / 2, d / 2];
+  const n = 6;
+  // normal axis, u axis, v axis, sign: u × v = sign · normal.
+  const faces: [number, number, number, number][] = [[0, 1, 2, 1], [0, 2, 1, -1], [1, 2, 0, 1], [1, 0, 2, -1], [2, 0, 1, 1], [2, 1, 0, -1]];
+  return faces.map(([an, au, av, sign]) => {
+    const positions: number[] = [];
+    for (let j = 0; j <= n; j++) for (let i = 0; i <= n; i++) {
+      const p: Vec3 = [0, 0, 0];
+      p[an] = sign * half[an]!;
+      p[au] = (i / n - 0.5) * 2 * half[au]!;
+      p[av] = (j / n - 0.5) * 2 * half[av]!;
+      positions.push(p[0], p[1], p[2]);
+    }
+    return { positions, rows: n + 1, cols: n + 1 };
+  });
+}
+
+const cross3 = (a: Vec3, b: Vec3): Vec3 => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const dot3 = (a: Vec3, b: Vec3) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const norm3 = (a: Vec3): Vec3 => { const l = Math.hypot(a[0], a[1], a[2]) || 1; return [a[0] / l, a[1] / l, a[2] / l]; };
+
+const RAD = Math.PI / 180;
+
+/** Apply a part's manipulators, in order, in its own frame. `v` runs 0–1 up the part as it was before any of them. */
+function manipulate(pos: number[], ops: TSOp[]): void {
+  if (ops.length === 0) return;
+  let y0 = Infinity, y1 = -Infinity;
+  for (let k = 1; k < pos.length; k += 3) { if (pos[k]! < y0) y0 = pos[k]!; if (pos[k]! > y1) y1 = pos[k]!; }
+  const H = Math.max(1e-6, y1 - y0);
+  for (let k = 0; k < pos.length; k += 3) {
+    const v = (pos[k + 1]! - y0) / H;
+    let x = pos[k]!, y = pos[k + 1]!, z = pos[k + 2]!;
+    for (const o of ops) {
+      const g = (key: string) => o[key] as number;
+      if (o.op === 'taper') { const s = g('bottom') + (g('top') - g('bottom')) * v; x *= s; z *= s; }
+      else if (o.op === 'flare') { const s = 1 + g('amount') * smoothstep(g('start'), 1, o.end === 'bottom' ? 1 - v : v); x *= s; z *= s; }
+      else if (o.op === 'bulge') { const s = 1 + g('amount') * Math.exp(-(((v - g('center')) / g('width')) ** 2)); x *= s; z *= s; }
+      else if (o.op === 'twist') { const a = g('angle') * RAD * v, c = Math.cos(a), s = Math.sin(a); const nx = x * c + z * s; z = -x * s + z * c; x = nx; }
+      else if (o.op === 'bend') {
+        const th = g('angle') * RAD;
+        if (Math.abs(th) > 1e-4) { const R = H / th, phi = th * v, d = R - x; x = R - d * Math.cos(phi); y = y0 + d * Math.sin(phi); }
+      } else if (o.op === 'scale') { x *= g('x'); y = y0 + (y - y0) * g('y'); z *= g('z'); }
+    }
+    pos[k] = x; pos[k + 1] = y; pos[k + 2] = z;
+  }
+}
+
+/** Turn about x, then y, then z (degrees). */
+function turn(p: Vec3, r: readonly [number, number, number]): void {
+  if (r[0]) { const c = Math.cos(r[0] * RAD), s = Math.sin(r[0] * RAD); const y = p[1] * c - p[2] * s; p[2] = p[1] * s + p[2] * c; p[1] = y; }
+  if (r[1]) { const c = Math.cos(r[1] * RAD), s = Math.sin(r[1] * RAD); const x = p[0] * c + p[2] * s; p[2] = -p[0] * s + p[2] * c; p[0] = x; }
+  if (r[2]) { const c = Math.cos(r[2] * RAD), s = Math.sin(r[2] * RAD); const x = p[0] * c - p[1] * s; p[1] = p[0] * s + p[1] * c; p[0] = x; }
+}
+
+export type ResolvedMaterial = { color: string; metalness: number; roughness: number; reflection: number; gain: number };
+/** One part's triangles in the object's index buffer, and how they shade. */
+export type PartRange = { id: string; start: number; count: number; material: ResolvedMaterial };
+
+export type BuiltObject = {
+  positions: Float32Array;
+  normals: Float32Array;
+  indices: Uint32Array;
+  count: number;
+  ranges: PartRange[];
+  bounds: { min: Vec3; max: Vec3 };
+  /** The part that carries the text: its extent along y and its outer radius at any height. */
+  host: { id: string; y0: number; y1: number; radiusAt: (y: number) => number; color: string };
+};
+
+export function resolveMaterial(m: TSPartMaterial): ResolvedMaterial {
+  const base = TS_OBJECT_MATERIALS[m.type];
+  return { color: m.color, metalness: m.metalness ?? base.metalness, roughness: m.roughness ?? base.roughness, reflection: base.reflection, gain: base.gain };
+}
+
+/**
+ * Build a spec into one mesh in the object's frame: every part through its manipulators, turned and
+ * placed, with smooth normals and a triangle range per part. The spec is repaired first (omitted
+ * parameters take their defaults); it throws only when nothing in it can be drawn.
+ */
+export function buildObject(input: TSObjectSpec): BuiltObject {
+  const spec = sanitizeObject(input).object;
+  if (!spec) throw new Error('construct: nothing in this object can be drawn (see validateObject).');
+  const positions: number[] = [], normals: number[] = [], indices: number[] = [];
+  const ranges: PartRange[] = [];
+  const min: Vec3 = [Infinity, Infinity, Infinity], max: Vec3 = [-Infinity, -Infinity, -Infinity];
+  let host: BuiltObject['host'] | null = null;
+
+  for (const part of spec.parts) {
+    const pr = part.params;
+    const grids: Grid[] = part.shape === 'tube'
+      ? [tube(pr.smooth ? smoothPath(pr.path as number[][], 8) : (pr.path as number[][]), pr.radius as number)]
+      : part.shape === 'box' ? box(pr.width as number, pr.height as number, pr.depth as number)
+        : [revolve(profileFor(part.shape, pr))];
+    const base = positions.length / 3;
+    const start = indices.length;
+    const local: number[] = [];
+    const tris: number[] = [];
+    for (const g of grids) {
+      const off = local.length / 3;
+      for (const v of g.positions) local.push(v);
+      for (let p = 0; p < g.rows - 1; p++) for (let q = 0; q < g.cols - 1; q++) {
+        const a = off + p * g.cols + q, b = a + 1, c = a + g.cols, d = c + 1;
+        tris.push(a, b, c, b, d, c);
+      }
+    }
+    manipulate(local, part.ops);
+    const n = local.length / 3;
+    // Face normals summed onto vertices, then welded across coincident vertices (seams, poles) unless
+    // the faces meet at a hard edge.
+    const raw = new Float64Array(n * 3);
+    for (let t = 0; t < tris.length; t += 3) {
+      const a = tris[t]! * 3, b = tris[t + 1]! * 3, c = tris[t + 2]! * 3;
+      const fn = cross3([local[b]! - local[a]!, local[b + 1]! - local[a + 1]!, local[b + 2]! - local[a + 2]!], [local[c]! - local[a]!, local[c + 1]! - local[a + 1]!, local[c + 2]! - local[a + 2]!]);
+      for (const i of [a, b, c]) { raw[i] = raw[i]! + fn[0]; raw[i + 1] = raw[i + 1]! + fn[1]; raw[i + 2] = raw[i + 2]! + fn[2]; }
+    }
+    const unit = new Float64Array(n * 3);
+    const groups = new Map<string, number[]>();
+    for (let i = 0; i < n; i++) {
+      const u = norm3([raw[i * 3]!, raw[i * 3 + 1]!, raw[i * 3 + 2]!]);
+      const zero = Math.hypot(raw[i * 3]!, raw[i * 3 + 1]!, raw[i * 3 + 2]!) < 1e-12;
+      unit[i * 3] = zero ? 0 : u[0]; unit[i * 3 + 1] = zero ? 0 : u[1]; unit[i * 3 + 2] = zero ? 0 : u[2];
+      const key = `${Math.round(local[i * 3]! * 2e4)},${Math.round(local[i * 3 + 1]! * 2e4)},${Math.round(local[i * 3 + 2]! * 2e4)}`;
+      const g = groups.get(key);
+      if (g) g.push(i); else groups.set(key, [i]);
+    }
+    const smooth = new Float64Array(n * 3);
+    for (const g of groups.values()) {
+      for (const i of g) {
+        const ui: Vec3 = [unit[i * 3]!, unit[i * 3 + 1]!, unit[i * 3 + 2]!];
+        const none = ui[0] === 0 && ui[1] === 0 && ui[2] === 0;
+        let sx = 0, sy = 0, sz = 0;
+        for (const j of g) {
+          if (!none && j !== i && ui[0] * unit[j * 3]! + ui[1] * unit[j * 3 + 1]! + ui[2] * unit[j * 3 + 2]! < 0.4) continue;
+          sx += raw[j * 3]!; sy += raw[j * 3 + 1]!; sz += raw[j * 3 + 2]!;
+        }
+        const s = norm3([sx, sy, sz]);
+        smooth[i * 3] = s[0]; smooth[i * 3 + 1] = s[1]; smooth[i * 3 + 2] = s[2];
+      }
+    }
+    const p: Vec3 = [0, 0, 0];
+    let py0 = Infinity, py1 = -Infinity;
+    for (let i = 0; i < n; i++) {
+      p[0] = local[i * 3]!; p[1] = local[i * 3 + 1]!; p[2] = local[i * 3 + 2]!;
+      turn(p, part.rotate);
+      p[0] += part.at[0]; p[1] += part.at[1]; p[2] += part.at[2];
+      positions.push(p[0], p[1], p[2]);
+      for (let a = 0; a < 3; a++) { if (p[a]! < min[a]!) min[a] = p[a]!; if (p[a]! > max[a]!) max[a] = p[a]!; }
+      if (p[1] < py0) py0 = p[1]; if (p[1] > py1) py1 = p[1];
+      p[0] = smooth[i * 3]!; p[1] = smooth[i * 3 + 1]!; p[2] = smooth[i * 3 + 2]!;
+      turn(p, part.rotate);
+      normals.push(p[0], p[1], p[2]);
+    }
+    for (const t of tris) indices.push(base + t);
+    ranges.push({ id: part.id, start, count: indices.length - start, material: resolveMaterial(part.material) });
+
+    if (part.id === spec.text.on) {
+      // The outer radius at each height, from one meridian of the placed part.
+      const BINS = 128;
+      const table = new Float32Array(BINS + 1).fill(-1);
+      const g = grids[0]!;
+      const span = Math.max(1e-6, py1 - py0);
+      const at = (row: number): P2 => { const k = (base + row * g.cols) * 3; return [Math.hypot(positions[k]!, positions[k + 2]!), positions[k + 1]!]; };
+      for (let row = 0; row < g.rows - 1; row++) {
+        const [ra, ya] = at(row), [rb, yb] = at(row + 1);
+        const b0 = Math.round(((Math.min(ya, yb) - py0) / span) * BINS), b1 = Math.round(((Math.max(ya, yb) - py0) / span) * BINS);
+        for (let b = b0; b <= b1; b++) {
+          const y = py0 + (b / BINS) * span;
+          const f = Math.abs(yb - ya) < 1e-9 ? 0.5 : Math.min(1, Math.max(0, (y - ya) / (yb - ya)));
+          const r = Math.abs(yb - ya) < 1e-9 ? Math.max(ra, rb) : ra + (rb - ra) * f;
+          if (r > table[b]!) table[b] = r;
+        }
+      }
+      for (let b = 1; b <= BINS; b++) if (table[b]! < 0) table[b] = table[b - 1]!;
+      for (let b = BINS - 1; b >= 0; b--) if (table[b]! < 0) table[b] = table[b + 1]!;
+      const y0 = py0;
+      host = {
+        id: part.id, y0: py0, y1: py1, color: part.material.color,
+        radiusAt: (y) => {
+          const f = Math.min(1, Math.max(0, (y - y0) / span)) * BINS;
+          const b = Math.min(BINS - 1, Math.floor(f));
+          return Math.max(1e-3, table[b]! + (table[b + 1]! - table[b]!) * (f - b));
+        },
+      };
+    }
+  }
+  if (!host) throw new Error(`construct: no part “${spec.text.on}” to carry the text.`);
+  return { positions: new Float32Array(positions), normals: new Float32Array(normals), indices: new Uint32Array(indices), count: positions.length / 3, ranges, bounds: { min, max }, host };
+}
+
+/* ---------------- recipes ---------------- */
+
+export type TSRecipeOptions = { color?: string; material?: TSObjectMaterialId; accent?: string; label?: string | null };
+
+const part = (id: string, shape: TSPrimitiveId, params: Record<string, unknown>, material: TSPartMaterial, rest: Partial<Pick<TSPart, 'ops' | 'at' | 'rotate'>> = {}): TSPart =>
+  ({ id, shape, params, material, ops: rest.ops ?? [], at: rest.at ?? [0, 0, 0], rotate: rest.rotate ?? [0, 0, 0] });
+
+/**
+ * Semantic starting points. A recipe is only a composition of the primitives and manipulators above,
+ * returned as a plain spec to edit: nothing here is special-cased anywhere else, so an object with
+ * no recipe is built the same way, part by part.
+ */
+export const TS_RECIPES: Record<string, { summary: string; composition: string; build: (o?: TSRecipeOptions) => TSObjectSpec }> = {
+  tumbler: {
+    summary: 'A tapered travel tumbler with a metal rim and a dark foot.',
+    composition: 'cylinder (hollow, taper) + ring (rim) + cylinder (foot)',
+    build: (o = {}) => ({
+      name: 'Tumbler',
+      parts: [
+        part('body', 'cylinder', { radius: 0.38, height: 1.5, hollow: 0.025, round: 0.05 }, { type: o.material ?? 'matte', color: o.color ?? '#1F8A8A' }, { ops: [{ op: 'taper', bottom: 0.78, top: 1 }] }),
+        part('rim', 'ring', { radius: 0.372, thickness: 0.02 }, { type: 'chrome', color: o.accent ?? '#D9DCE1' }, { at: [0, 1.5, 0] }),
+        part('foot', 'cylinder', { radius: 0.305, height: 0.07, round: 0.02 }, { type: 'matte', color: '#1B1D20' }, { at: [0, -0.04, 0] }),
+      ],
+      text: { on: 'body', y: 0.52, height: 0.62, arc: 170, label: o.label ?? null },
+      scene: DEFAULT_SCENE,
+    }),
+  },
+  mug: {
+    summary: 'A coffee mug: a hollow body and a handle.',
+    composition: 'cylinder (hollow) + tube (handle)',
+    build: (o = {}) => {
+      const m: TSPartMaterial = { type: o.material ?? 'ceramic', color: o.color ?? '#17181A' };
+      return {
+        name: 'Mug',
+        parts: [
+          part('body', 'cylinder', { radius: 0.42, height: 0.95, hollow: 0.035, round: 0.06 }, m),
+          part('handle', 'tube', { path: [[0.39, 0.74, 0], [0.62, 0.78, 0], [0.74, 0.5, 0], [0.64, 0.2, 0], [0.39, 0.22, 0]], radius: 0.05, smooth: true }, m),
+        ],
+        text: { on: 'body', y: 0.5, height: 0.7, arc: 170, label: o.label ?? null },
+        scene: DEFAULT_SCENE,
+      };
+    },
+  },
+  can: {
+    summary: 'A drinks can: a body necked in at both ends, a lid and its rim.',
+    composition: 'cylinder (flare in, both ends) + cylinder (lid) + ring (rim)',
+    build: (o = {}) => ({
+      name: 'Can',
+      parts: [
+        part('body', 'cylinder', { radius: 0.33, height: 1.22, round: 0.02 }, { type: o.material ?? 'metal', color: o.color ?? '#C8102E' }, {
+          ops: [{ op: 'flare', amount: -0.14, start: 0.88, end: 'top' }, { op: 'flare', amount: -0.16, start: 0.93, end: 'bottom' }],
+        }),
+        part('lid', 'cylinder', { radius: 0.27, height: 0.012 }, { type: 'metal', color: o.accent ?? '#C9CDD3' }, { at: [0, 1.214, 0] }),
+        part('rim', 'ring', { radius: 0.277, thickness: 0.012 }, { type: 'chrome', color: o.accent ?? '#C9CDD3' }, { at: [0, 1.224, 0] }),
+      ],
+      text: { on: 'body', y: 0.5, height: 0.7, arc: 200, label: o.label ?? null },
+      scene: DEFAULT_SCENE,
+    }),
+  },
+  bottle: {
+    summary: 'A shampoo or lotion bottle: a rounded body, a neck and a cap.',
+    composition: 'cylinder (rounded) + cylinder (neck) + cylinder (cap)',
+    build: (o = {}) => ({
+      name: 'Bottle',
+      parts: [
+        part('body', 'cylinder', { radius: 0.36, height: 1.25, round: 0.12 }, { type: o.material ?? 'plastic', color: o.color ?? '#E9E4DA' }),
+        part('neck', 'cylinder', { radius: 0.13, height: 0.14 }, { type: o.material ?? 'plastic', color: o.color ?? '#E9E4DA' }, { at: [0, 1.22, 0] }),
+        part('cap', 'cylinder', { radius: 0.17, height: 0.24, round: 0.03 }, { type: 'plastic', color: o.accent ?? '#2B2D31' }, { at: [0, 1.3, 0] }),
+      ],
+      text: { on: 'body', y: 0.5, height: 0.6, arc: 170, label: o.label ?? null },
+      scene: DEFAULT_SCENE,
+    }),
+  },
+};
+
+/** A recipe's spec, ready to edit; unknown names fall back to a plain cylinder so something always draws. */
+export function createObject(recipe: string, options: TSRecipeOptions = {}): TSObjectSpec {
+  const r = TS_RECIPES[recipe];
+  if (r) return r.build(options);
+  return {
+    name: recipe || 'Object',
+    parts: [part('body', 'cylinder', { radius: 0.36, height: 1.2, round: 0.03 }, { type: options.material ?? 'plastic', color: options.color ?? FALLBACK_COLOR })],
+    text: { on: 'body', y: 0.5, height: 0.6, arc: 160, label: options.label ?? null },
+    scene: DEFAULT_SCENE,
+  };
+}
+
+/**
+ * Everything an agent needs to compose an object, as JSON: the primitives and what each can take,
+ * the manipulators, the materials, how text attaches, the recipes and what cannot be done.
+ */
+export function describeConstruction() {
+  return {
+    frame: 'y is up and is the object’s axis; x is to the right of the camera, z toward it. Units are world units: a wine bottle’s body is 0.36 in radius. The camera frames whatever is built.',
+    part: {
+      shape: 'id, shape, params, ops (manipulators, in order), material { type, color, roughness?, metalness? }, at [x, y, z], rotate [x, y, z] in degrees',
+      origin: { base: '`at` is the centre of its base; it grows up', centre: '`at` is its centre', path: 'the path is already in the object’s frame; `at` shifts it' },
+    },
+    primitives: TS_PRIMITIVES,
+    manipulators: TS_MANIPULATORS,
+    materials: TS_OBJECT_MATERIALS,
+    text: {
+      summary: 'The text wraps one round part. It is its own layer: every typography, placement, deformation and material control of the config still applies to it.',
+      params: TS_OBJECT_TEXT_PARAMS,
+      label: 'a hex colour for a paper label under the text, or null to print straight onto the part',
+      carriers: TS_PRIMITIVE_IDS.filter((id) => TS_PRIMITIVES[id].capabilities.includes('text-wrap')),
+      sizing: {
+        unit: 'typography.fontSize, letterSpacing and placement.maxWidth are in units where the text area (text.arc degrees round the part) is 1000 wide',
+        frontArc: OBJECT_FRONT_ARC,
+        rule: 'only about frontArc degrees face the camera, so text wider than 1000 × frontArc / text.arc units runs out of sight; text taller than 1000 × areaHeight / areaWidth units leaves the area',
+        helper: 'fitObjectText(config) sets fontSize to the largest that fits the front face; createTypeSurface({ object }) already calls it',
+      },
+      rules: ['the carrier sits on the axis, unturned (at x = z = 0, rotate 0)', `the carrier takes only: ${TS_MANIPULATOR_IDS.filter((id) => TS_MANIPULATORS[id].keepsRound).join(', ')}`],
+    },
+    scene: { table: TS_OBJECT_TABLES, backdrop: 'two hex colours, top and bottom' },
+    view: {
+      summary: 'The camera looks straight at the front of the standing object. To see it from another side, turn the object, not the camera.',
+      states: { wrapped: 'standing, front-on (the default)', lying: 'lying on the table, diagonal', turned: 'turned to show its side', tipped: 'tipped toward the camera to show the top or the opening' },
+      apply: 'applySurfaceState(config, state)',
+      controls: {
+        'deformation.tiltX': '−1…1: turns the object about its own axis (left/right); the text goes round with it',
+        'deformation.tiltY': '−1…1: tips it; negative brings the top toward the camera, positive the base',
+        'view.roll': 'degrees: leans the object in the picture (−28 is the lying pose)',
+        'view.zoom': '1 fills the frame',
+      },
+      avoid: 'view.yaw and view.pitch orbit the camera about the table, not the object: yaw spins the picture and pitch looks up from under the base. Leave both at 0 for objects.',
+    },
+    recipes: Object.fromEntries(Object.entries(TS_RECIPES).map(([id, r]) => [id, {
+      summary: r.summary, composition: r.composition,
+      // Every default is only a starting value: pass options, or edit the spec the recipe returns.
+      defaults: { color: r.build().parts[0]!.material.color, material: r.build().parts[0]!.material.type, label: null },
+      options: {
+        color: 'hex: the main part’s colour', material: `one of materials: the main part’s material (${TS_OBJECT_MATERIAL_IDS.join(', ')})`,
+        accent: 'hex: the secondary parts (rim, lid, cap)', label: 'hex for a paper label under the text, or null to print on the part',
+      },
+      use: `createObject('${id}', { color, material })  or  createTypeSurface({ text, object: '${id}', objectColor, objectMaterial })`,
+    }])),
+    limits: [
+      `at most ${MAX_OBJECT_PARTS} parts`,
+      'no boolean cut or union: parts overlap, they do not subtract. A hollow comes from `hollow` or from a profile drawn down the inside',
+      'text wraps round parts only; for a flat face (a card, a box side, a poster) use a sheet surface instead',
+      'one text block per object',
+      'materials are opaque: glass is dark and reflective, not see-through',
+      'the lighting is one studio key light with a soft shadow; it is not configurable',
+    ],
+  };
+}