@docyrus/animaguru 0.27.0 → 0.29.0

package/templates/video/shared/locales/en/style-studies.json

@@ -3,6 +3,7 @@
   "resourceArt": "Study artwork",
   "resourceMaterial": "Material & background",
   "resourceText": "Study typography",
+  "resourceScene": "3D scene",
   "styles": {
     "dark-tech-stage": {
       "name": "Dark Tech Stage",
@@ -357,5 +358,39 @@
         "Sun · arches · profile · ring"
       ]
     }
+  },
+  "threeStyles": {
+    "product-turntable-3d": {
+      "name": "3D Product Turntable",
+      "lines": [
+        "One product, every angle.",
+        "Studio light · orbit · push-in",
+        "Brushed metal"
+      ]
+    },
+    "character-stage-3d": {
+      "name": "3D Character Stage",
+      "lines": [
+        "A character steps onto the page.",
+        "Painted backdrop · real shadow",
+        "Walk · turn · wave"
+      ]
+    },
+    "toy-diorama-3d": {
+      "name": "3D Toy Diorama",
+      "lines": [
+        "A whole town on a tabletop.",
+        "Tilt-shift focus",
+        "Little loops, all day"
+      ]
+    },
+    "exploded-teardown-3d": {
+      "name": "3D Exploded Teardown",
+      "lines": [
+        "Every part, in its place.",
+        "Orbit · separate · label",
+        "Battery"
+      ]
+    }
   }
 }

package/templates/video/shared/locales/en/timeline.json

@@ -20,6 +20,7 @@
   "text": "Text",
   "captions": "Captions",
   "audio": "Audio",
+  "model": "3D model",
   "paper": "Paper backdrop",
   "branding": "Studio wordmark",
   "tagline": "Film tagline",

package/templates/video/src/kit/index.ts

@@ -10,3 +10,4 @@ export * from "./story";
 export * from "./layout";
 export * from "./film-base";
 export * from "./dark-stage";
+export * from "./three-stage";

package/templates/video/src/kit/three-stage.ts

@@ -0,0 +1,262 @@
+import { Sprite, Texture } from "pixi.js";
+import * as THREE from "three";
+import { GLTFLoader, type GLTF } from "three/addons/loaders/GLTFLoader.js";
+import { HDRLoader } from "three/addons/loaders/HDRLoader.js";
+import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { RenderPass } from "three/addons/postprocessing/RenderPass.js";
+import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js";
+import { BokehPass } from "three/addons/postprocessing/BokehPass.js";
+import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
+import type { Pass } from "three/addons/postprocessing/Pass.js";
+import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+import { publicAsset } from "../assets";
+import { easeInOut } from "./motion";
+
+/*
+  3D shots for the film: three.js draws into its own canvas, which the film shows as one Pixi Sprite,
+  so 2D art can sit behind it (the canvas is transparent where nothing is drawn) and text, captions
+  and leader lines on top. Everything stays a function of film time: pose rigs with Rig.pose(), move
+  cameras with vecAt(), never use THREE.Clock, mixer.update(delta) or Math.random() in a frame, and draw
+  last, from the film.on() update registered after every 3D update. See the animaguru-3d-models skill.
+*/
+
+export { THREE };
+
+export type StageOptions = {
+  /** The design size the sprite covers, in film coordinates. */
+  width: number;
+  height: number;
+  /** Render scale: 1.5–2 renders larger and lets Pixi downsample it, on top of MSAA. */
+  supersample?: number;
+};
+
+/** `passes` (for example tilt-shift or colour grading ShaderPasses) run after depth of field and bloom, before tone mapping. */
+export type PostOptions = { bloom?: { strength: number; radius: number; threshold: number }; bokeh?: { focus: number; aperture: number; maxblur: number }; passes?: Pass[] };
+
+export class ThreeStage {
+  readonly renderer: THREE.WebGLRenderer;
+  readonly sprite: Sprite;
+  readonly width: number;
+  readonly height: number;
+  private readonly scale: number;
+  private readonly composers = new Map<THREE.Scene, EffectComposer>();
+  private readonly gltf = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
+
+  constructor({ width, height, supersample = 1.5 }: StageOptions) {
+    this.width = width;
+    this.height = height;
+    this.scale = supersample;
+    const canvas = document.createElement("canvas");
+    // preserveDrawingBuffer: Pixi reads the canvas after three.js has presented it.
+    this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true, preserveDrawingBuffer: true, powerPreference: "high-performance" });
+    this.renderer.setPixelRatio(supersample);
+    this.renderer.setSize(width, height, false);
+    this.renderer.setClearColor(0x000000, 0);
+    this.renderer.toneMapping = THREE.AgXToneMapping;
+    this.renderer.shadowMap.enabled = true;
+    this.renderer.shadowMap.type = THREE.PCFShadowMap;
+    this.sprite = new Sprite(Texture.from(canvas));
+    this.sprite.width = width;
+    this.sprite.height = height;
+  }
+
+  /** Loads a GLB from public/ (meshopt-compressed files too); its meshes cast and receive shadows. */
+  async load(path: string): Promise<GLTF> {
+    const gltf = await this.gltf.loadAsync(publicAsset(path));
+    gltf.scene.traverse((node) => { if ((node as THREE.Mesh).isMesh) { node.castShadow = true; node.receiveShadow = true; } });
+    return gltf;
+  }
+
+  /** An equirectangular .hdr from public/ as image-based lighting; `hdr` can also be a scene's background. */
+  async environment(path: string) {
+    const hdr = await new HDRLoader().loadAsync(publicAsset(path));
+    hdr.mapping = THREE.EquirectangularReflectionMapping;
+    const pmrem = new THREE.PMREMGenerator(this.renderer);
+    const env = pmrem.fromEquirectangular(hdr).texture;
+    pmrem.dispose();
+    return { hdr, env };
+  }
+
+  /** A soft studio environment generated in code, for image-based lighting without an HDR file. */
+  room(blur = 0.04) {
+    const pmrem = new THREE.PMREMGenerator(this.renderer);
+    const env = pmrem.fromScene(new RoomEnvironment(), blur).texture;
+    pmrem.dispose();
+    return env;
+  }
+
+  /** Post-processing for one scene: an MSAA target, optional depth of field and bloom, then tone mapping. Returns the depth-of-field pass, whose focus the film sets each frame. */
+  post(scene: THREE.Scene, camera: THREE.PerspectiveCamera, { bloom, bokeh, passes = [] }: PostOptions) {
+    const w = this.width * this.scale, h = this.height * this.scale;
+    const composer = new EffectComposer(this.renderer, new THREE.WebGLRenderTarget(w, h, { type: THREE.HalfFloatType, samples: 4 }));
+    composer.setPixelRatio(this.scale);
+    composer.setSize(this.width, this.height);
+    composer.addPass(new RenderPass(scene, camera));
+    const depth = bokeh ? new BokehPass(scene, camera, bokeh) : undefined;
+    if (depth) composer.addPass(depth);
+    if (bloom) composer.addPass(new UnrealBloomPass(new THREE.Vector2(w, h), bloom.strength, bloom.radius, bloom.threshold));
+    for (const pass of passes) composer.addPass(pass);
+    composer.addPass(new OutputPass());
+    this.composers.set(scene, composer);
+    return depth;
+  }
+
+  /** Compiles the scene's materials and draws it once, so the first exported frame never waits on shaders. Await it in build(). */
+  async warm(scene: THREE.Scene, camera: THREE.Camera) {
+    await this.renderer.compileAsync(scene, camera);
+    this.draw(scene, camera);
+  }
+
+  /** Draws the scene and hands the canvas to Pixi for this frame. */
+  draw(scene: THREE.Scene, camera: THREE.Camera) {
+    const composer = this.composers.get(scene);
+    if (composer) composer.render();
+    else this.renderer.render(scene, camera);
+    this.sprite.texture.source.update();
+  }
+
+  /** Film position of a world point, for 2D labels and leader lines that follow a 3D part. `behind` is true when the point is behind the camera. */
+  project(point: THREE.Vector3, camera: THREE.Camera) {
+    // three.js refreshes matrices while rendering, which happens after this; without this the label follows last frame's camera.
+    camera.updateMatrixWorld();
+    const v = point.clone().project(camera);
+    return { x: (v.x + 1) / 2 * this.width, y: (1 - v.y) / 2 * this.height, behind: v.z > 1 };
+  }
+
+  dispose() {
+    for (const composer of this.composers.values()) composer.dispose();
+    this.renderer.dispose();
+    this.sprite.destroy({ texture: true, textureSource: true });
+  }
+}
+
+/** Scales a model to `height` scene units (metres), stands it on y = 0 and centres it on the origin. Saved AnimaGuru models face +Z. */
+export function normalize<T extends THREE.Object3D>(object: T, height: number): T {
+  object.updateMatrixWorld(true);
+  const box = new THREE.Box3().setFromObject(object);
+  object.scale.multiplyScalar(height / box.getSize(new THREE.Vector3()).y);
+  object.updateMatrixWorld(true);
+  box.setFromObject(object);
+  const center = box.getCenter(new THREE.Vector3());
+  object.position.x -= center.x;
+  object.position.z -= center.z;
+  object.position.y -= box.min.y;
+  return object;
+}
+
+export type ClipLayer = { clip: string; time: number; weight?: number; loop?: boolean };
+
+/**
+  A rigged model's clips sampled at absolute times. pose() sets every clip's time and weight and applies
+  them with a zero-length update, so a frame depends only on its arguments, never on the frame before:
+  crossfade by easing two weights against film time.
+*/
+export class Rig {
+  readonly mixer: THREE.AnimationMixer;
+  private readonly actions = new Map<string, THREE.AnimationAction>();
+
+  constructor(root: THREE.Object3D, clips: THREE.AnimationClip[]) {
+    this.mixer = new THREE.AnimationMixer(root);
+    for (const clip of clips) {
+      const action = this.mixer.clipAction(clip);
+      action.play();
+      action.setEffectiveWeight(0);
+      this.actions.set(clip.name, action);
+    }
+  }
+
+  get clips() { return [...this.actions.keys()]; }
+  duration(clip: string) { return this.action(clip).getClip().duration; }
+
+  /** `loop: false` holds a clip's last pose after it ends. */
+  pose(layers: ClipLayer[]) {
+    for (const action of this.actions.values()) { action.enabled = true; action.paused = false; action.setEffectiveWeight(0); }
+    for (const layer of layers) {
+      const action = this.action(layer.clip);
+      const length = action.getClip().duration;
+      action.time = layer.loop === false ? Math.min(Math.max(layer.time, 0), length - 1e-4) : ((layer.time % length) + length) % length;
+      action.setEffectiveWeight(layer.weight ?? 1);
+    }
+    this.mixer.update(0);
+  }
+
+  private action(clip: string) {
+    const action = this.actions.get(clip);
+    if (!action) throw new Error(`No clip "${clip}"; the model has ${this.clips.join(", ")}`);
+    return action;
+  }
+}
+
+/**
+  Removes a clip's horizontal root motion (clips from motion capture or other rigs often travel forward) and
+  returns the speed it had in world units a second at the model's current scale, so the film moves the
+  character itself; it returns 0 for in-place clips such as Meshy's, whose speed strideSpeed() measures. Call it
+  after normalize() and before posing.
+*/
+export function inPlace(model: THREE.Object3D, clip: THREE.AnimationClip, bone = "Hips") {
+  const track = clip.tracks.find((item) => item.name === `${bone}.position`);
+  const node = model.getObjectByName(bone);
+  if (!track || !node?.parent) return 0;
+  model.updateMatrixWorld(true);
+  const parent = node.parent.matrixWorld, inverse = parent.clone().invert(), v = track.values, p = new THREE.Vector3();
+  const first = new THREE.Vector3(v[0], v[1], v[2]).applyMatrix4(parent);
+  const last = new THREE.Vector3(v[v.length - 3], v[v.length - 2], v[v.length - 1]).applyMatrix4(parent);
+  for (let i = 0; i < v.length; i += 3) {
+    p.set(v[i], v[i + 1], v[i + 2]).applyMatrix4(parent);
+    p.x = first.x;
+    p.z = first.z;
+    p.applyMatrix4(inverse);
+    v[i] = p.x; v[i + 1] = p.y; v[i + 2] = p.z;
+  }
+  return Math.hypot(last.x - first.x, last.z - first.z) / clip.duration;
+}
+
+/**
+ * Walking speed of an in-place walk cycle, in world units a second at the model's current scale. Meshy's clips
+ * have no root motion: while a foot is at its lowest it slides backwards at the speed the body must travel for it
+ * to stay planted. Call it after normalize(), with the model facing +Z and its holder not yet turned.
+ */
+export function strideSpeed(rig: Rig, model: THREE.Object3D, clip: string, feet = ["LeftToeBase", "RightToeBase"]) {
+  const bones = feet.map((name) => model.getObjectByName(name)).filter((bone): bone is THREE.Object3D => Boolean(bone));
+  if (!bones.length) return 0;
+  const length = rig.duration(clip), step = 1 / 120, p = new THREE.Vector3();
+  const tracks = bones.map(() => [] as { y: number; z: number }[]);
+  for (let t = 0; t <= length; t += step) {
+    rig.pose([{ clip, time: t }]);
+    model.updateMatrixWorld(true);
+    bones.forEach((bone, i) => { bone.getWorldPosition(p); tracks[i].push({ y: p.y, z: p.z }); });
+  }
+  const speeds: number[] = [];
+  for (const track of tracks) {
+    const low = Math.min(...track.map((sample) => sample.y));
+    for (let i = 1; i < track.length; i++) if (track[i].y < low + 0.012 && track[i - 1].y < low + 0.012) speeds.push((track[i - 1].z - track[i].z) / step);
+  }
+  speeds.sort((a, b) => a - b);
+  return speeds.length ? speeds[Math.floor(speeds.length / 2)] : 0;
+}
+
+/** Sets a named blend shape on every mesh that has it, for models that carry expressions or visemes. */
+export function setMorph(root: THREE.Object3D, name: string, weight: number) {
+  root.traverse((node) => {
+    const mesh = node as THREE.Mesh;
+    const index = mesh.morphTargetDictionary?.[name];
+    if (index !== undefined && mesh.morphTargetInfluences) mesh.morphTargetInfluences[index] = weight;
+  });
+}
+
+export type Key<T> = [time: number, value: T];
+
+/** Eased keyframes for a position or target: holds before the first key and after the last. */
+export function vecAt(t: number, keys: Key<[number, number, number]>[], out = new THREE.Vector3()) {
+  if (t <= keys[0][0]) return out.fromArray(keys[0][1]);
+  for (let i = 1; i < keys.length; i++) {
+    const [t1, b] = keys[i];
+    if (t <= t1) {
+      const [t0, a] = keys[i - 1];
+      const k = easeInOut((t - t0) / (t1 - t0));
+      return out.set(a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k, a[2] + (b[2] - a[2]) * k);
+    }
+  }
+  return out.fromArray(keys[keys.length - 1][1]);
+}

package/templates/video/src/resource-timeline.ts

@@ -9,6 +9,7 @@ const icons = {
   graphics: "m12 3 9 9-9 9-9-9Z", image: "M3 3h18v18H3zM3 17l6-6 4 4 3-3 5 5M15 7h.01",
   video: "M3 5h13v14H3zM16 9l5-3v12l-5-3", text: "M4 5h16M12 5v15M8 20h8",
   captions: "M3 5h18v14H3zM10 9H7v6h3m7-6h-3v6h3", audio: "M4 9v6m4-10v14m4-16v18m4-15v12m4-9v6",
+  model: "M12 3 3 7.5v9L12 21l9-4.5v-9ZM3 7.5 12 12l9-4.5M12 12v9",
 };
 
 /** A navigable resource view. It changes the playhead, never the film's clip timing. */

package/templates/video/src/studies/three/character-stage-3d.ts

@@ -0,0 +1,172 @@
+import { Container, FillGradient, Graphics } from "pixi.js";
+import { THREE, ThreeStage, clamp01, easeInOut, inOut, lerp, show, txt, win } from "../../kit";
+import type { ThreeStudy } from ".";
+
+/*
+  3D Character Stage study: a wooden artist's mannequin, built from primitives in a joint hierarchy and posed by
+  functions of t, walks across a painted 2D square, turns to the camera and waves, casting a real shadow onto
+  the painting. The 3D camera is matched to the painting: level, at its eye height, with the lens shifted so the
+  horizon sits where it is painted. A film replaces the mannequin with a generated, rigged character
+  (animaguru-3d-models) posed with Rig.pose(), and the drawn square with a painted backdrop.
+*/
+
+const W = 1920, H = 1080;
+/** The painted horizon and the matching camera: eye 1.0 m above the ground, 34° vertical field. */
+const HORIZON = 610, EYE = 1.0, FOV = 34;
+/** The walk crosses the square on this line and stops at its middle. */
+const FROM = new THREE.Vector3(-3.2, 0, -9.5), STOP = new THREE.Vector3(0.35, 0, -6.2);
+/** Two steps take CYCLE seconds; a 0.3 rad leg swing reaches ±0.27 m, so the body moves 2 × 0.54 m a cycle. */
+const CYCLE = 1.1, SWING = 0.3, SPEED = (4 * 0.9 * Math.sin(SWING)) / CYCLE;
+const ARRIVE = Math.min(4, FROM.distanceTo(STOP) / SPEED);
+
+/** The square, painted in flat strokes: sky, sun, roofs, the lit ground and the lines that recede to the horizon. */
+function paintSquare() {
+  const paint = new Container();
+  const sky = new FillGradient({ type: "linear", start: { x: 0, y: 0 }, end: { x: 0, y: 1 }, colorStops: [{ offset: 0, color: "#f2b563" }, { offset: 1, color: "#fde7b8" }] });
+  paint.addChild(new Graphics().rect(0, 0, W, HORIZON + 20).fill(sky));
+  for (const [r, a] of [[260, 0.16], [150, 0.28], [70, 0.9]] as const) paint.addChild(new Graphics().circle(760, HORIZON - 150, r).fill({ color: 0xfff3d1, alpha: a }));
+  paint.addChild(new Graphics().poly([0, HORIZON - 40, 380, HORIZON - 120, 760, HORIZON - 70, 1180, HORIZON - 150, 1600, HORIZON - 80, W, HORIZON - 110, W, HORIZON, 0, HORIZON]).fill({ color: 0xc98a5a, alpha: 0.55 }));
+  const houses = new Graphics();
+  const house = (x: number, w: number, h: number, wall: number, roof: number) => {
+    houses.rect(x, HORIZON - h, w, h).fill(wall);
+    houses.poly([x - 14, HORIZON - h, x + w / 2, HORIZON - h - w * 0.28, x + w + 14, HORIZON - h]).fill(roof);
+    for (let wx = x + 22; wx < x + w - 30; wx += 58) for (let wy = HORIZON - h + 34; wy < HORIZON - 60; wy += 78) houses.roundRect(wx, wy, 26, 40, 6).fill({ color: 0x5f7f8a, alpha: 0.8 });
+  };
+  house(-40, 300, 520, 0xe8b88a, 0xb5573c); house(250, 220, 360, 0xf1cf98, 0xa9573f); house(460, 180, 250, 0xe9c2a0, 0xb86a48);
+  house(1290, 200, 260, 0xefd0a6, 0xb0603f); house(1480, 230, 380, 0xe6b37f, 0xa8533a); house(1700, 260, 540, 0xf0c890, 0xb5573c);
+  paint.addChild(houses);
+  const ground = new FillGradient({ type: "linear", start: { x: 0, y: 0 }, end: { x: 0, y: 1 }, colorStops: [{ offset: 0, color: "#e8b27a" }, { offset: 1, color: "#c98656" }] });
+  paint.addChild(new Graphics().rect(0, HORIZON, W, H - HORIZON).fill(ground));
+  // Paving joints drawn toward the vanishing point: the 3D ground plane must agree with them.
+  const joints = new Graphics();
+  for (let i = -14; i <= 14; i++) joints.moveTo(W / 2 + i * 34, HORIZON).lineTo(W / 2 + i * 260, H);
+  for (let d = 1.5; d < 40; d *= 1.32) { const y = HORIZON + (H / 2 / Math.tan((FOV / 2) * Math.PI / 180)) * EYE / d; joints.moveTo(0, y).lineTo(W, y); }
+  joints.stroke({ color: 0xa8683f, alpha: 0.35, width: 2 });
+  paint.addChild(joints);
+  return paint;
+}
+
+type Limb = { top: THREE.Group; lower: THREE.Group; end: THREE.Group };
+
+/** A jointed wooden mannequin, 1.75 m tall, facing +Z like a generated model; each joint is a Group to rotate. */
+function mannequin() {
+  const wood = new THREE.MeshStandardMaterial({ color: 0xd7a066, roughness: 0.48 });
+  const knob = new THREE.MeshStandardMaterial({ color: 0xa8713f, roughness: 0.4 });
+  const piece = (length: number, radius: number, down = true) => {
+    const mesh = new THREE.Mesh(new THREE.CapsuleGeometry(radius, Math.max(0.01, length - 2 * radius), 6, 18), wood);
+    mesh.position.y = down ? -length / 2 : length / 2;
+    mesh.castShadow = true;
+    return mesh;
+  };
+  const ball = (radius: number) => { const mesh = new THREE.Mesh(new THREE.SphereGeometry(radius, 20, 14), knob); mesh.castShadow = true; return mesh; };
+  const joint = (parent: THREE.Object3D, x: number, y: number, z = 0) => { const group = new THREE.Group(); group.position.set(x, y, z); parent.add(group); return group; };
+  const root = new THREE.Group();
+  const hips = joint(root, 0, 0.95);
+  hips.add(new THREE.Mesh(new THREE.SphereGeometry(0.15, 22, 16).scale(1.2, 0.7, 0.85), wood));
+  const spine = joint(hips, 0, 0.05);
+  spine.add(piece(0.42, 0.13, false));
+  const chest = joint(spine, 0, 0.42);
+  chest.add(new THREE.Mesh(new THREE.SphereGeometry(0.17, 22, 16).scale(1.25, 0.8, 0.8), wood));
+  const neck = joint(chest, 0, 0.1);
+  neck.add(piece(0.1, 0.045, false));
+  const head = joint(neck, 0, 0.12);
+  head.add(new THREE.Mesh(new THREE.SphereGeometry(0.11, 24, 18).scale(0.88, 1.15, 0.95).translate(0, 0.1, 0.01), wood));
+  const limb = (parent: THREE.Object3D, x: number, y: number, upper: number, lower: number, radius: number, foot: boolean): Limb => {
+    const top = joint(parent, x, y);
+    top.add(ball(radius * 1.15), piece(upper, radius));
+    const knee = joint(top, 0, -upper);
+    knee.add(ball(radius * 0.95), piece(lower, radius * 0.85));
+    const end = joint(knee, 0, -lower);
+    end.add(foot ? Object.assign(new THREE.Mesh(new THREE.BoxGeometry(0.1, 0.06, 0.24).translate(0, -0.02, 0.06), wood), { castShadow: true }) : Object.assign(new THREE.Mesh(new THREE.SphereGeometry(0.05, 16, 12).scale(0.8, 1.4, 0.6).translate(0, -0.05, 0), wood), { castShadow: true }));
+    return { top, lower: knee, end };
+  };
+  const legs = [limb(hips, -0.1, -0.03, 0.44, 0.42, 0.06, true), limb(hips, 0.1, -0.03, 0.44, 0.42, 0.06, true)];
+  const arms = [limb(chest, -0.22, 0.02, 0.3, 0.27, 0.045, false), limb(chest, 0.22, 0.02, 0.3, 0.27, 0.045, false)];
+  root.traverse((node) => { if ((node as THREE.Mesh).isMesh) node.castShadow = true; });
+  return { root, hips, spine, head, legs, arms };
+}
+
+const study: ThreeStudy = async (root, lines) => {
+  const stage = new ThreeStage({ width: W, height: H, supersample: 1.5 });
+  stage.renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  const scene = new THREE.Scene();
+  scene.environment = stage.room();
+  scene.environmentIntensity = 0.3;
+  const camera = new THREE.PerspectiveCamera(FOV, W / H, 0.1, 80);
+  camera.position.set(0, EYE, 0);
+  // Lens shift instead of tilt: verticals stay vertical, as in the painting, and the horizon lands on HORIZON.
+  camera.updateProjectionMatrix();
+  camera.projectionMatrix.elements[9] = -(1 - 2 * HORIZON / H);
+  camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
+
+  const figure = mannequin();
+  const holder = new THREE.Group();
+  holder.add(figure.root);
+  // The painted sun sits back left: the shadow falls right, toward the camera.
+  const sun = new THREE.DirectionalLight(0xffcf94, 2.8);
+  sun.position.set(STOP.x - 7, 5, STOP.z - 8);
+  sun.target.position.copy(STOP);
+  sun.castShadow = true;
+  sun.shadow.mapSize.set(2048, 2048);
+  Object.assign(sun.shadow.camera, { left: -8, right: 8, top: 8, bottom: -8, near: 1, far: 30 });
+  sun.shadow.radius = 5;
+  sun.shadow.bias = -0.0005;
+  const ground = new THREE.Mesh(new THREE.PlaneGeometry(50, 50), new THREE.ShadowMaterial({ color: 0x4a2412, opacity: 0.55 }));
+  ground.rotation.x = -Math.PI / 2;
+  ground.receiveShadow = true;
+  scene.add(holder, sun, sun.target, ground, new THREE.HemisphereLight(0xffe0b0, 0xc98050, 1.6));
+
+  const caption = txt(lines[0], 46, { family: "heading", weight: "700", fill: 0xfff4e2, dropShadow: { color: 0x3a1a08, alpha: 0.6, blur: 8, distance: 2, angle: Math.PI / 2 } });
+  caption.anchor.set(0.5, 1);
+  caption.position.set(W / 2, H - 70);
+  const eyebrow = txt(lines[1], 30, { family: "mono", weight: "700", fill: 0x6b3a1c });
+  eyebrow.position.set(96, 84);
+  const beat = txt(lines[2], 30, { family: "heading", weight: "700", fill: 0x3b2414 });
+  const leader = new Graphics();
+  root.addChild(paintSquare(), stage.sprite, leader, beat, eyebrow, caption);
+  await stage.warm(scene, camera);
+
+  const direction = STOP.clone().sub(FROM).normalize();
+  const start = STOP.clone().addScaledVector(direction, -SPEED * ARRIVE);
+  const heading = Math.atan2(direction.x, direction.z);
+  const head = new THREE.Vector3();
+
+  return (t) => {
+    // Walk: legs and arms swing in opposition, knees bend in the swing, hips bob twice a cycle.
+    const phase = (t / CYCLE) * Math.PI * 2, walking = 1 - clamp01((t - ARRIVE + 0.2) / 0.4);
+    // Facing +Z, his right side is -X: arms[0] is the right arm, the one that waves.
+    const [left, right] = figure.legs, [armR, armL] = figure.arms;
+    for (const [leg, sign] of [[left, 1], [right, -1]] as const) {
+      const swing = Math.sin(phase) * sign;
+      leg.top.rotation.x = -SWING * swing * walking;
+      leg.lower.rotation.x = Math.max(0, Math.sin(phase * sign + 1.2)) * 0.7 * walking;
+      leg.end.rotation.x = -(leg.top.rotation.x + leg.lower.rotation.x) * 0.6;
+    }
+    figure.hips.position.y = 0.95 + Math.cos(phase * 2) * 0.02 * walking;
+    figure.spine.rotation.y = Math.sin(phase) * 0.08 * walking;
+    holder.position.lerpVectors(start, STOP, clamp01(t / ARRIVE));
+    // Turn to the camera, then wave: the right arm rises and the forearm rocks.
+    holder.rotation.y = lerp(heading, 0, easeInOut(win(t, ARRIVE - 0.1, 0.8)));
+    const wave = easeInOut(win(t, ARRIVE + 0.5, 0.5)) * (1 - easeInOut(win(t, 7.1, 0.6)));
+    armL.top.rotation.x = SWING * 1.1 * Math.sin(phase) * walking;
+    armL.top.rotation.z = 0.12;
+    armR.top.rotation.x = -SWING * 1.1 * Math.sin(phase) * walking;
+    armR.top.rotation.z = lerp(-0.12, -2.55, wave);
+    armR.lower.rotation.z = -lerp(0, 0.35 + 0.45 * Math.sin((t - ARRIVE) * Math.PI * 2 * 1.6), wave);
+    armL.lower.rotation.x = -0.25;
+    figure.head.rotation.z = Math.sin((t - ARRIVE) * 3) * 0.08 * wave;
+
+    // Text: the caption and eyebrow hold; the beat label follows his head through the shot.
+    show(caption, inOut(t, 0.4, 7.6));
+    show(eyebrow, inOut(t, 0.2, 7.6));
+    holder.updateMatrixWorld(true);
+    figure.head.getWorldPosition(head).y += 0.35;
+    const p = stage.project(head, camera), label = inOut(t, ARRIVE + 0.4, 7.6);
+    leader.clear().moveTo(p.x, p.y).lineTo(p.x + 70, p.y - 70).lineTo(p.x + 110, p.y - 70).stroke({ color: 0x3b2414, width: 3 }).circle(p.x, p.y, 6).fill(0x3b2414);
+    show(leader, label);
+    beat.position.set(p.x + 120, p.y - 90);
+    show(beat, label);
+    stage.draw(scene, camera);
+  };
+};
+export default study;