@appinternalleads/ui 0.4.1 → 0.4.3

package/src/motion/typesurface/engine.ts

@@ -16,6 +16,7 @@
 import { DEFAULT_TYPE_SURFACE, TS_FOLD_KEYS, TS_WRAP_KEYS, type TSFold, type TSWrap, type TypeSurfaceConfig } from './config';
 import { glyphAt, morphGap, type TSTextLayout } from './layout';
 import { bend, bendDistance, crumpleCreases, crumpleField, cylinder, roll, rotate, smoothstep, type Bend, type Crease, type Roll, type Vec3 } from './ops';
+import type { ResolvedMaterial } from './construct';
 import type { SurfaceDef } from './surfaces';
 
 const DEG = Math.PI / 180;
@@ -38,7 +39,9 @@ export type TextMesh = {
   indexVersion: number;
 };
 
-export type PropMesh = { positions: Float32Array; normals: Float32Array; attrs: Float32Array; indices: Uint32Array; vertexCount: number };
+/** A solid's triangles that share one look: the wine bottle (`material: null`), or one part of a constructed object. */
+export type PropRange = { start: number; count: number; material: ResolvedMaterial | null };
+export type PropMesh = { positions: Float32Array; normals: Float32Array; attrs: Float32Array; indices: Uint32Array; vertexCount: number; ranges: PropRange[] };
 
 export type Guides = {
   folds: Float32Array[];
@@ -225,10 +228,16 @@ export function createGeometryEngine(def: SurfaceDef): GeometryEngine {
   };
   let textRect = '';
 
-  const bottle = def.prop === 'bottle' ? bottleMesh(def.curveRadius - 0.0025, def.curveRadius) : null;
+  // The solid the sheet wraps: the wine bottle, or a constructed object's parts.
+  const bottle = def.prop === 'bottle' ? bottleMesh(def.curveRadius - 0.0025, def.curveRadius)
+    : def.solid ? { ...def.solid, attrs: new Float32Array(def.solid.count * 4) } : null;
   const prop: PropMesh | null = bottle
-    ? { positions: new Float32Array(bottle.count * 3), normals: new Float32Array(bottle.count * 3), attrs: bottle.attrs, indices: bottle.indices, vertexCount: bottle.count }
+    ? {
+      positions: new Float32Array(bottle.count * 3), normals: new Float32Array(bottle.count * 3), attrs: bottle.attrs, indices: bottle.indices, vertexCount: bottle.count,
+      ranges: def.solid?.ranges ?? [{ start: 0, count: bottle.indices.length, material: null }],
+    }
     : null;
+  const solid = !!(def.prop || def.solid);
 
   const loose = def.looseSheet
     ? { positions: new Float32Array(12), normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]), uvs: new Float32Array([0, 0, 1, 0, 0, 1, 1, 1]), indices: new Uint32Array([0, 2, 1, 1, 2, 3]) }
@@ -262,6 +271,12 @@ export function createGeometryEngine(def: SurfaceDef): GeometryEngine {
     if (F.roll) roll(p, F.roll);
     if (F.kappa) {
       cylinder(p, F.kappa);
+      if (def.radiusAt) {
+        // Follow the part's own radius at this height (a taper, a bulge), about the cylinder's axis.
+        const k = 1 + (def.radiusAt(p[1]) / def.curveRadius - 1) * F.d.curve, A = 1 / F.kappa;
+        p[0] *= k;
+        p[2] = (p[2] + A) * k - A;
+      }
       if (F.spin) {
         const R = def.curveRadius;
         const zz = p[2] + R, c = Math.cos(F.spin), s = Math.sin(F.spin);
@@ -313,6 +328,15 @@ export function createGeometryEngine(def: SurfaceDef): GeometryEngine {
   };
 
   const scratch: Vec3 = [0, 0, 0];
+  /** The solid turns with its label, about the wrap axis (a mug's handle comes round with the words). */
+  const spinSolid = (p: Vec3, direction = false) => {
+    if (!F.spin) return;
+    const R = direction ? 0 : def.curveRadius;
+    const zz = p[2] + R, c = Math.cos(F.spin), s = Math.sin(F.spin);
+    const xx = p[0] * c + zz * s;
+    p[2] = -p[0] * s + zz * c - R;
+    p[0] = xx;
+  };
 
   const evaluate: GeometryEngine['evaluate'] = (cfg, timeMs, layout, opts) => {
     const d = cfg.deformation;
@@ -347,7 +371,7 @@ export function createGeometryEngine(def: SurfaceDef): GeometryEngine {
       crumpleA: c > 0 ? c * (0.5 + 0.5 * smoothstep(0.5, 1, c)) : 0, shrink: c > 0 ? shrink : 1, bowl: 0.35 * smoothstep(0.55, 1, c),
       wrinkleA: d.wrinkle > 0 ? d.wrinkle * def.wrinkleDepth * 60 : 0,
       bends, roll: rl, kappa,
-      spin: def.prop === 'bottle' ? d.curve * cfg.view.motion * 0.5 * Math.sin((2 * Math.PI * timeMs) / 10000) : 0,
+      spin: solid ? d.curve * cfg.view.motion * 0.5 * Math.sin((2 * Math.PI * timeMs) / 10000) : 0,
       rotA: d.tiltX * 0.6, rotB: -d.tiltY * 0.6, rotC: cfg.view.roll * DEG, shiftX: 0, shiftY: 0,
       creases: field?.creases ?? [],
     };
@@ -369,10 +393,12 @@ export function createGeometryEngine(def: SurfaceDef): GeometryEngine {
     if (prop && bottle) {
       for (let k = 0; k < bottle.count; k++) {
         scratch[0] = bottle.positions[k * 3]!; scratch[1] = bottle.positions[k * 3 + 1]!; scratch[2] = bottle.positions[k * 3 + 2]!;
+        spinSolid(scratch);
         rotate(scratch, F.rotA, F.rotB, F.rotC);
         prop.positions.set(scratch, k * 3);
         for (let a = 0; a < 3; a++) { const v = scratch[a]!; if (v < min[a]!) min[a] = v; if (v > max[a]!) max[a] = v; }
         scratch[0] = bottle.normals[k * 3]!; scratch[1] = bottle.normals[k * 3 + 1]!; scratch[2] = bottle.normals[k * 3 + 2]!;
+        spinSolid(scratch, true);
         rotate(scratch, F.rotA, F.rotB, F.rotC);
         prop.normals.set(scratch, k * 3);
       }
@@ -555,7 +581,7 @@ export function createGeometryEngine(def: SurfaceDef): GeometryEngine {
       guides = { folds, foldZones: zones, roll: rollLine, textOutline: outline, baselines, anchors: new Float32Array(anchors) };
     }
 
-    const radius = def.prop === 'bottle' ? 1.45 : 0.5 * Math.hypot(W, def.height) * 1.04;
+    const radius = def.frameRadius ?? (def.prop === 'bottle' ? 1.45 : 0.5 * Math.hypot(W, def.height) * 1.04);
     return {
       def, nu, nv, uvs, indices,
       sheet: { positions: pos, normals: nrm, attrs },

package/src/motion/typesurface/index.ts

@@ -3,14 +3,18 @@
  * 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 { SURFACES, registerSurface, getSurface, hasSurface, listSurfaces, type SurfaceDef, type SurfaceState, type SurfaceShading, type TableStyle } from './surfaces';
+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 Guides } from './engine';
-export { TYPE_SURFACE_PRESETS, findTypeSurfacePreset, applySurfaceState, switchSurface, createTypeSurface, type TypeSurfacePreset, type TypeSurfaceShorthand } from './presets';
+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/presets.ts

@@ -7,7 +7,9 @@
  */
 import { findTypeSurfaceFont } from './fonts';
 import { DEFAULT_TYPE_SURFACE, REST_DEFORMATION, resolveTypeSurface, type TSStage, type TSSurfaceType, type TypeSurfaceConfig, type TypeSurfaceConfigInput } from './config';
-import { getSurface } from './surfaces';
+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 {
@@ -22,7 +24,7 @@ function merge<T>(base: T, over: unknown): T {
  * change; the text, and how far it has wrapped and morphed, do not.
  */
 export function applySurfaceState(config: TypeSurfaceConfig, stateId: string): TypeSurfaceConfig {
-  const def = getSurface(config.surface.type);
+  const def = surfaceFor(config);
   const state = def.states[stateId];
   if (!state) return config;
   const deformation = merge(REST_DEFORMATION, state.deformation);
@@ -40,7 +42,7 @@ export function applySurfaceState(config: TypeSurfaceConfig, stateId: string): T
  */
 export function switchSurface(config: TypeSurfaceConfig, type: TSSurfaceType | string): TypeSurfaceConfig {
   const def = getSurface(type);
-  const next: TypeSurfaceConfig = { ...config, surface: { ...config.surface, type: type as TSSurfaceType, color: null }, material: { ...config.material, ...def.material } };
+  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);
 }
 
@@ -55,6 +57,49 @@ const on = (type: TSSurfaceType, input: TypeSurfaceConfigInput): TypeSurfaceConf
   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";
 
@@ -167,6 +212,22 @@ export const TYPE_SURFACE_PRESETS: TypeSurfacePreset[] = [
       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 {
@@ -183,17 +244,28 @@ export type TypeSurfaceShorthand = {
   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;
 }

package/src/motion/typesurface/renderer.ts

@@ -10,8 +10,9 @@ import { ART_FONTS, paintGrain, paintSurfaceArt } from './art';
 import { TS_BLEND_MODES, type TypeSurfaceConfig } from './config';
 import { createGeometryEngine, type GeometryEngine, type SceneGeometry } from './engine';
 import { layoutText, morphGap, glyphShift, type TSTextLayout } from './layout';
+import { findTypeSurfaceFont, typeSurfaceFontsUrl } from './fonts';
 import { DEPTH_FS, DEPTH_VS, SURFACE_FS, SURFACE_VS, TEXT_FS, TEXT_VS } from './shaders';
-import { getSurface, type SurfaceDef } from './surfaces';
+import { surfaceFor, type SurfaceDef } from './surfaces';
 import { canvasMeasurer, cssFont, rasterText } from './text';
 import type { Vec3 } from './ops';
 
@@ -104,11 +105,14 @@ export class TypeSurfaceRenderer {
   private shadowFbo!: WebGLFramebuffer;
   private shadowTex!: WebGLTexture;
   private shadowSize = 2048;
-  private indexVersions = new Map<string, number>();
+  private indexVersions = new Map<string, number | string>();
   private viewProj = m4();
   private fontsVersion = 0;
   private lastGeometry: SceneGeometry | null = null;
   private propUv: Float32Array | null = null;
+  /** Bumped when an engine is (re)built, so static buffers (uvs, triangles) are uploaded again. */
+  private geometryVersion = 1;
+  private uvVersions = new Map<string, number>();
   private onFonts = () => { this.fontsVersion++; };
 
   constructor(private canvas: HTMLCanvasElement) {
@@ -210,7 +214,7 @@ export class TypeSurfaceRenderer {
     gl.enableVertexAttribArray(loc);
     gl.vertexAttribPointer(loc, size, gl.FLOAT, false, 0, 0);
   }
-  private elements(key: string, data: Uint32Array, count: number, version: number) {
+  private elements(key: string, data: Uint32Array, count: number, version: number | string) {
     const gl = this.gl;
     if (this.indexVersions.get(key) !== version || !this.bufs.has(key)) {
       this.buffer(key, data, gl.ELEMENT_ARRAY_BUFFER, count);
@@ -220,17 +224,25 @@ export class TypeSurfaceRenderer {
 
   private engine(def: SurfaceDef): GeometryEngine {
     let e = this.engines.get(def.id);
-    if (!e) { e = createGeometryEngine(def); this.engines.set(def.id, e); }
+    // The engine is built for one definition: a re-registered surface, or an edited object, gets a new one.
+    if (!e || e.def !== def) {
+      if (def.solid) for (const [k, v] of this.engines) if (v.def.solid) this.engines.delete(k);
+      e = createGeometryEngine(def);
+      this.engines.set(def.id, e);
+      this.geometryVersion++;
+    }
     return e;
   }
 
   private artFor(def: SurfaceDef, seed: number, color: string) {
-    const key = `${def.id}:${seed}:${color}:${this.fontsVersion}`;
+    // Every constructed object shares one slot, so editing one doesn't pile up textures.
+    const slot = def.solid ? 'object' : def.id;
+    const key = `${slot}:${def.solid ? `${def.width.toFixed(4)}:${def.height.toFixed(4)}:` : ''}${seed}:${color}:${this.fontsVersion}`;
     let a = this.art.get(key);
     if (!a) {
       const aspect = def.height / def.width;
       const { front, back, inner } = paintSurfaceArt(def.art, seed, aspect, color);
-      for (const [k, v] of this.art) if (k.startsWith(`${def.id}:`)) { this.gl.deleteTexture(v.front); this.gl.deleteTexture(v.back); this.gl.deleteTexture(v.inner); this.art.delete(k); }
+      for (const [k, v] of this.art) if (k.startsWith(`${slot}:`)) { this.gl.deleteTexture(v.front); this.gl.deleteTexture(v.back); this.gl.deleteTexture(v.inner); this.art.delete(k); }
       a = { front: this.texture(front, true), back: this.texture(back, true), inner: this.texture(inner, true), aspect };
       this.art.set(key, a);
     }
@@ -271,6 +283,41 @@ export class TypeSurfaceRenderer {
 
   get geometry(): SceneGeometry | null { return this.lastGeometry; }
 
+  /**
+   * Resolves once everything `config` draws with has loaded: its text font and the artwork's faces.
+   * It waits for stylesheets still loading, and (unless `loadFonts` is false) links the lab's Google
+   * Fonts stylesheet when the font is one of `TS_FONTS` and the page has not declared it. Any other
+   * undeclared font resolves with its fallback. Render after it.
+   */
+  async whenReady(config: TypeSurfaceConfig, loadFonts = true): Promise<void> {
+    const fonts = document.fonts;
+    if (!fonts?.load) return;
+    const font = cssFont(config.typography, 100);
+    const load = () => fonts.load(font, config.text || 'A').catch(() => [] as FontFace[]);
+    const sheetLoaded = (l: HTMLLinkElement) => (l.sheet ? Promise.resolve() : new Promise<void>((done) => {
+      l.addEventListener('load', () => done(), { once: true });
+      l.addEventListener('error', () => done(), { once: true });
+    }));
+    // No face for the font yet: `load` resolves empty, which would pass a fallback off as ready. A
+    // stylesheet may still be on its way; failing that, a lab font is fetched from its own stylesheet.
+    if ((await load()).length === 0) {
+      await Promise.all(Array.from(document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]')).map(sheetLoaded));
+      if ((await load()).length === 0 && loadFonts && findTypeSurfaceFont(config.typography.fontFamily.split(',')[0]!)) {
+        const href = typeSurfaceFontsUrl();
+        let link = Array.from(document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]')).find((l) => l.href === href);
+        if (!link) {
+          link = document.createElement('link');
+          link.rel = 'stylesheet'; link.href = href;
+          document.head.appendChild(link);
+        }
+        await sheetLoaded(link);
+        await load();
+      }
+    }
+    await Promise.all(ART_FONTS.map((f) => fonts.load(f).catch(() => undefined)));
+    await fonts.ready;
+  }
+
   /** Draw `config` (already at its timeline moment) at `timeMs`. */
   render(config: TypeSurfaceConfig, timeMs: number, debug: TSDebug = {}): SceneGeometry | null {
     if (!this.ok) return null;
@@ -280,11 +327,15 @@ export class TypeSurfaceRenderer {
     const W = Math.max(2, Math.round(cv.clientWidth * dpr)), H = Math.max(2, Math.round(cv.clientHeight * dpr));
     if (cv.width !== W || cv.height !== H) { cv.width = W; cv.height = H; }
 
-    const def = getSurface(config.surface.type);
+    const def = surfaceFor(config);
+    // Buffers are keyed by surface; every constructed object shares one set, re-uploaded when it changes.
+    const bk = def.solid ? 'object' : def.id;
     const layout = this.layoutFor(config);
     const g = this.engine(def).evaluate(config, timeMs, layout, { guides: !!(debug.folds || debug.bounds || debug.baseline || debug.controls) });
     this.lastGeometry = g;
-    const art = this.artFor(def, config.surface.seed, def.prop ? def.color : config.surface.color ?? def.color);
+    const gv = this.geometryVersion;
+    const sheetOn = def.sheet !== 'hidden';
+    const art = this.artFor(def, config.surface.seed, def.prop || def.solid ? def.color : config.surface.color ?? def.color);
     const textTex = layout && g.text ? this.textTexture(config, layout) : null;
 
     const cam = cameraFor(config, def, g, W / H);
@@ -331,14 +382,14 @@ export class TypeSurfaceRenderer {
     const bindSheet = (positionsKey: string, positions: Float32Array) => {
       this.attr(0, positionsKey, positions, 3);
       this.attrKeep(1, 'sheet.n', 3);
-      this.attrKeep(2, `sheet.uv:${def.id}`, 2);
+      this.attrKeep(2, `sheet.uv:${bk}`, 2);
       this.attrKeep(3, 'sheet.a', 4);
       gl.disableVertexAttribArray(4);
-      this.elements(`sheet.i:${def.id}`, g.indices, g.indices.length, 1);
+      this.elements(`sheet.i:${bk}`, g.indices, g.indices.length, gv);
     };
     this.buffer('sheet.n', g.sheet.normals, gl.ARRAY_BUFFER);
     this.buffer('sheet.a', g.sheet.attrs, gl.ARRAY_BUFFER);
-    if (!this.bufs.has(`sheet.uv:${def.id}`)) this.buffer(`sheet.uv:${def.id}`, g.uvs, gl.ARRAY_BUFFER);
+    if (this.uvVersions.get(bk) !== gv) { this.buffer(`sheet.uv:${bk}`, g.uvs, gl.ARRAY_BUFFER); this.uvVersions.set(bk, gv); }
     const bindProp = () => {
       const pr = g.prop!;
       this.attr(0, 'prop.p', pr.positions, 3);
@@ -347,7 +398,7 @@ export class TypeSurfaceRenderer {
       this.attr(2, 'prop.uv', this.propUv, 2);
       this.attr(3, 'prop.a', pr.attrs, 4);
       gl.disableVertexAttribArray(4);
-      this.elements(`prop.i:${def.id}`, pr.indices, pr.indices.length, 1);
+      this.elements(`prop.i:${bk}`, pr.indices, pr.indices.length, gv);
     };
     const drawSheetGeom = () => gl.drawElements(gl.TRIANGLES, g.indices.length, gl.UNSIGNED_INT, 0);
     const bindText = () => {
@@ -357,7 +408,7 @@ export class TypeSurfaceRenderer {
       this.attr(2, 'text.uv', t.uvs, 2, t.vertexCount);
       this.attr(3, 'text.a', t.attrs, 4, t.vertexCount);
       this.attr(4, 'text.tuv', t.tuv, 2, t.vertexCount);
-      this.elements('text.i', t.indices, t.indexCount, t.indexVersion * 100000 + t.indexCount);
+      this.elements('text.i', t.indices, t.indexCount, `${def.id}:${gv}:${t.indexVersion}:${t.indexCount}`);
     };
     const bindQuad = (key: string, pos: Float32Array, uvs: Float32Array) => {
       this.attr(0, `${key}.p`, pos, 3);
@@ -380,7 +431,7 @@ export class TypeSurfaceRenderer {
     gl.useProgram(dp.p);
     gl.uniformMatrix4fv(this.loc(dp, 'uVP'), false, lightVP);
     gl.uniform1i(this.loc(dp, 'uIsText'), 0);
-    if (!debug.noShadows) { bindSheet('sheet.p', g.sheet.positions); drawSheetGeom(); }
+    if (!debug.noShadows && sheetOn) { bindSheet('sheet.p', g.sheet.positions); drawSheetGeom(); }
     if (!debug.noShadows) g.stack.forEach((s, i) => { bindSheet(`stack${i}.p`, s); drawSheetGeom(); });
     if (g.prop && !debug.noShadows) { bindProp(); gl.drawElements(gl.TRIANGLES, g.prop.indices.length, gl.UNSIGNED_INT, 0); }
     if (layout && g.text && textTex && config.material.shadow > 0.02 && !debug.noShadows) {
@@ -444,13 +495,22 @@ export class TypeSurfaceRenderer {
     g.stack.forEach((s, i) => { bindSheet(`stack${i}.p`, s); drawSheetGeom(); });
     gl.uniform1i(this.loc(sp, 'uDebug'), debug.deformation ? 1 : debug.mapping ? 2 : 0);
     tex(art.front, art.back);
-    bindSheet('sheet.p', g.sheet.positions);
-    drawSheetGeom();
+    if (sheetOn) { bindSheet('sheet.p', g.sheet.positions); drawSheetGeom(); }
     if (g.prop) {
       gl.uniform1i(this.loc(sp, 'uMode'), 2);
       gl.uniform1i(this.loc(sp, 'uDebug'), 0);
       bindProp();
-      gl.drawElements(gl.TRIANGLES, g.prop.indices.length, gl.UNSIGNED_INT, 0);
+      // One draw per part: each has its own material.
+      for (const r of g.prop.ranges) {
+        const mt = r.material;
+        gl.uniform1i(this.loc(sp, 'uPartOn'), mt ? 1 : 0);
+        if (mt) {
+          gl.uniform3fv(this.loc(sp, 'uPropColor'), hexRgb(mt.color));
+          gl.uniform4f(this.loc(sp, 'uPart'), mt.metalness, mt.roughness, mt.reflection, mt.gain);
+        }
+        gl.drawElements(gl.TRIANGLES, r.count, gl.UNSIGNED_INT, r.start * 4);
+      }
+      gl.uniform1i(this.loc(sp, 'uPartOn'), 0);
       gl.uniform1i(this.loc(sp, 'uMode'), 0);
     }
 

package/src/motion/typesurface/shaders.ts

@@ -57,6 +57,12 @@ vec3 envAt(vec3 r) {
   float strip = smoothstep(0.975, 0.992, dot(normalize(r - ax * along), sd)) * (1.0 - smoothstep(0.4, 0.62, abs(along)));
   return base + vec3(1.0, 0.98, 0.95) * key * 3.2 + vec3(0.95, 0.97, 1.0) * strip * 2.4;
 }
+/** The same studio seen in a rough surface: the lights spread into a broad glow. */
+vec3 envSoft(vec3 r) {
+  vec3 base = mix(vec3(0.07, 0.07, 0.075), vec3(0.36, 0.37, 0.39), smoothstep(-0.6, 1.0, r.z));
+  float key = smoothstep(0.3, 1.0, dot(r, uLightDir));
+  return base + vec3(1.0, 0.98, 0.95) * key * key * 0.9;
+}
 float fresnel(float ndv, float f0) { return f0 + (1.0 - f0) * pow(1.0 - ndv, 5.0); }
 
 float hash12(vec2 p) { vec3 p3 = fract(vec3(p.xyx) * 0.1031); p3 += dot(p3, p3.yzx + 33.33); return fract((p3.x + p3.y) * p3.z); }
@@ -79,7 +85,9 @@ void main() { vW = aPos; vN = aNrm; vUv = aUv; vAttr = aAttr; gl_Position = uVP
 
 export const SURFACE_FS = COMMON + /* glsl */ `
 in vec3 vW; in vec3 vN; in vec2 vUv; in vec4 vAttr;
-uniform int uMode;          // 0 sheet, 1 table, 2 prop (bottle)
+uniform int uMode;          // 0 sheet, 1 table, 2 prop (the bottle, or a constructed part)
+uniform int uPartOn;        // 1: a constructed part, shaded by uPart; 0: the wine bottle
+uniform vec4 uPart;         // metalness, roughness, reflection, albedo gain
 uniform int uShading;       // 0 paper, 1 label, 2 film, 3 fabric
 uniform vec3 uPropColor;
 uniform vec3 uCapColor;
@@ -119,6 +127,20 @@ void main() {
     return;
   }
   vec3 V = normalize(uEye - vW);
+  if (uMode == 2 && uPartOn == 1) {
+    if (!gl_FrontFacing) n = -n;
+    float ndv = max(dot(n, V), 0.0);
+    vec3 alb = toLin(uPropColor) * uPart.w;
+    float metal = uPart.x, rough = uPart.y;
+    vec3 body = shade(alb * (1.0 - metal), n, vW, 0.0, uPart.z * (1.0 - rough) * 1.2, rough, 0.0);
+    // A dielectric reflects the studio through its Fresnel term; a metal reflects it in its own colour.
+    vec3 F = mix(vec3(fresnel(ndv, 0.05)), alb + (1.0 - alb) * pow(1.0 - ndv, 5.0), metal);
+    vec3 R = reflect(-V, n);
+    vec3 env = mix(envAt(R), envSoft(R), smoothstep(0.08, 0.5, rough));
+    col = body + env * F * uPart.z;
+    outColor = vec4(toSrgb(tone(col)), 1.0);
+    return;
+  }
   if (uMode == 2) {
     float ndv = max(dot(n, V), 0.0);
     vec3 R = reflect(-V, n);

package/src/motion/typesurface/surfaces.ts

@@ -10,7 +10,8 @@
  * Its `id` becomes a valid `surface.type`, and the renderer paints it with the named `art` (or a
  * plain colour if it has no painter). Pure; no React.
  */
-import type { TSDeformation, TSMaterial, TSSurfaceType, TSView } from './config';
+import type { TSDeformation, TSMaterial, TSSurfaceType, TSView, TypeSurfaceConfig } from './config';
+import { buildObject, createObject, sanitizeObject, type PartRange, type TSObjectSpec } from './construct';
 import { smoothstep, type Vec3 } from './ops';
 
 /** How the substrate itself shades. The renderer maps each to a lighting model. */
@@ -51,6 +52,17 @@ export type SurfaceDef = {
   looseSheet?: boolean;
   /** A solid object the surface is wrapped on. */
   prop?: 'bottle';
+  /**
+   * A constructed object the surface is wrapped on (`objectSurface`): its mesh, already in the
+   * sheet's frame (the wrap axis parallel to y at z = −curveRadius), one triangle range per part.
+   */
+  solid?: { positions: Float32Array; normals: Float32Array; indices: Uint32Array; count: number; ranges: PartRange[] };
+  /** The wrapped sheet's radius at a height y (world): it follows a tapered or bulged part. */
+  radiusAt?: (y: number) => number;
+  /** `hidden`: the sheet is not drawn, so the text reads as printed straight onto the object. */
+  sheet?: 'visible' | 'hidden';
+  /** Radius that frames the object (camera fit); sheets work theirs out from their size. */
+  frameRadius?: number;
   /** How much fine wrinkles lift the surface, as a share of its width. */
   wrinkleDepth: number;
   /** The surface's own shape, before the shared operators. `x, y` are sheet units (1 wide). */
@@ -221,3 +233,68 @@ export function hasSurface(id: string): boolean {
 export function listSurfaces(): SurfaceDef[] {
   return [...REGISTRY.values()];
 }
+
+/* ---------------- constructed objects ---------------- */
+
+/** The gap between a part and the text area wrapped on it: enough depth to keep them apart. */
+const OBJECT_GAP = 0.0025;
+const OBJECTS = new Map<string, SurfaceDef>();
+
+/**
+ * A constructed object as a surface: the parts become the solid, and a sheet the size of the text
+ * area wraps the part that carries the text, following its radius at every height. The sheet is
+ * hidden unless the object asks for a paper label, so the words read as printed on the object. An
+ * invalid spec is repaired first (`sanitizeObject`), so this always returns something drawable.
+ */
+export function objectSurface(input: TSObjectSpec): SurfaceDef {
+  const key = JSON.stringify(input);
+  const hit = OBJECTS.get(key);
+  if (hit) return hit;
+  const spec = sanitizeObject(input).object ?? sanitizeObject(createObject('')).object!;
+  const built = buildObject(spec);
+  const { host } = built;
+  const hostH = host.y1 - host.y0;
+  const height = Math.max(0.02, spec.text.height * hostH);
+  // Keep the text area on the part.
+  const yc = Math.min(host.y1 - height / 2, Math.max(host.y0 + height / 2, host.y0 + spec.text.y * hostH));
+  const R = host.radiusAt(yc) + OBJECT_GAP;
+  const width = (spec.text.arc * Math.PI / 180) * R;
+  // Into the sheet's frame: the text area's centre at the origin, the axis behind it.
+  const positions = new Float32Array(built.positions);
+  for (let k = 0; k < built.count; k++) { positions[k * 3 + 1] = positions[k * 3 + 1]! - yc; positions[k * 3 + 2] = positions[k * 3 + 2]! - R; }
+  const { min, max } = built.bounds;
+  const nu = Math.round(Math.min(260, Math.max(96, spec.text.arc * 1.1)));
+  const def: SurfaceDef = {
+    id: `object:${hashString(key)}`, name: spec.name, blurb: `Built from ${spec.parts.map((p) => p.shape).join(' + ')}.`,
+    width, height, grid: [nu, Math.round(Math.min(220, Math.max(24, (nu * height) / width)))],
+    art: 'plain', shading: 'label', table: spec.scene.table, backdrop: spec.scene.backdrop,
+    color: spec.text.label ?? host.color,
+    material: { type: 'print', halftone: 0, grainInfluence: spec.text.label ? 0.25 : 0.05, paperInfluence: spec.text.label ? 0.35 : 0.15 },
+    curveRadius: R, curveMode: 'cylinder', wrinkleDepth: 0.004,
+    solid: { positions, normals: built.normals, indices: built.indices, count: built.count, ranges: built.ranges },
+    radiusAt: (y) => host.radiusAt(y + yc) + OBJECT_GAP,
+    sheet: spec.text.label ? 'visible' : 'hidden',
+    frameRadius: 0.5 * Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) * 1.06,
+    states: {
+      wrapped: s('Standing', { curve: 1 }),
+      lying: s('Lying on the table', { curve: 1 }, { roll: -28 }),
+      turned: s('Turned away', { curve: 1, tiltX: 0.5 }),
+      tipped: s('Tipped toward you', { curve: 1, tiltY: -0.7 }),
+    },
+    defaultState: 'wrapped', camera: { flat: 0, deep: 48 },
+  };
+  if (OBJECTS.size >= 12) OBJECTS.delete(OBJECTS.keys().next().value!);
+  OBJECTS.set(key, def);
+  return def;
+}
+
+function hashString(v: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < v.length; i++) h = Math.imul(h ^ v.charCodeAt(i), 0x01000193);
+  return (h >>> 0).toString(36);
+}
+
+/** What a config's text meets: its constructed `object` when it has one, else the surface it names. */
+export function surfaceFor(config: Pick<TypeSurfaceConfig, 'surface' | 'object'>): SurfaceDef {
+  return config.object ? objectSurface(config.object) : getSurface(config.surface.type);
+}