@idle-screens/saver-metaquarium 0.21.0 → 0.23.0

package/dist/{chunk-5DJ5WBVN.js → chunk-M2PKNQNY.js}

@@ -1620,7 +1620,7 @@ function shardGeometry(rng) {
   for (let i = 0; i < n; i += 1) tris.push([top[i], tip, top[(i + 1) % n]]);
   const positions = new Float32Array(tris.length * 9);
   const normals = new Float32Array(tris.length * 9);
-  const smooth3 = new Float32Array(tris.length * 9);
+  const smooth4 = new Float32Array(tris.length * 9);
   tris.forEach((tri, t) => {
     const [a, b, c] = tri;
     const ux = b[0] - a[0], uy = b[1] - a[1], uz = b[2] - a[2];
@@ -1648,12 +1648,12 @@ function shardGeometry(rng) {
       normals[o + 2] = nz;
       const sy = (p[1] - 0.55) * 0.25;
       const sl = Math.hypot(p[0], sy, p[2]) || 1;
-      smooth3[o] = p[0] / sl;
-      smooth3[o + 1] = sy / sl;
-      smooth3[o + 2] = p[2] / sl;
+      smooth4[o] = p[0] / sl;
+      smooth4[o + 1] = sy / sl;
+      smooth4[o + 2] = p[2] / sl;
     });
   });
-  return { positions, normals, smooth: smooth3, triangles: tris.length };
+  return { positions, normals, smooth: smooth4, triangles: tris.length };
 }
 var HABIT_RINGS = {
   lotus: [[1, 0], [6, 30], [9, 55], [16, 85]],
@@ -2500,10 +2500,196 @@ function parseSignMix(value) {
   return { entries, problems };
 }
 
+// src/choreo.ts
+var STARFISH_MOVE_NAMES = [
+  "march",
+  "jacks",
+  "reach",
+  "kick",
+  "twist",
+  "circles",
+  "disco",
+  "spin",
+  "mambo",
+  "sway",
+  "twirl",
+  "dip",
+  "hold",
+  "walk",
+  "lie",
+  "crawl",
+  "curl",
+  "wave",
+  "pop",
+  "rise",
+  "sit"
+];
+var CHOREO_MARKS = {
+  home: [0, 0],
+  left: [-2, 0],
+  right: [2, 0],
+  front: [0, 1.2],
+  back: [0, -1.5],
+  centre: "centre"
+};
+var MAX_CUES = 256;
+function parseChoreography(value, moves) {
+  const lines = /* @__PURE__ */ new Map(), problems = [];
+  const known = new Set(moves);
+  for (const rawLine of value.split("|").map((s) => s.trim()).filter(Boolean)) {
+    const head = /^([a-z]|\*)\s*:\s*(?=\d|\.)/.exec(rawLine);
+    const actor = head ? head[1] === "*" ? "*" : head[1].charCodeAt(0) - 97 : "*";
+    const body = head ? rawLine.slice(head[0].length) : rawLine;
+    if (lines.has(actor)) problems.push(`dancer ${actor === "*" ? "*" : String.fromCharCode(97 + actor)} has two lines; the later one wins`);
+    const cues = [];
+    let b0 = 0;
+    for (const raw of body.split(/,\s*(?=(?:\d+(?:\.\d+)?|\.\d+)\s*:)/).map((s) => s.trim()).filter(Boolean)) {
+      if (cues.length >= MAX_CUES) {
+        problems.push(`more than ${MAX_CUES} cues on one line; the rest are dropped`);
+        break;
+      }
+      const m = /^(\d+(?:\.\d+)?|\.\d+)\s*:\s*([a-z][a-z_]*)([^a-z_].*)?$/.exec(raw);
+      if (!m) {
+        problems.push(`"${raw}" is not <beats>:<move>`);
+        continue;
+      }
+      const beats = Number(m[1]);
+      if (!(beats > 0)) {
+        problems.push(`"${raw}": a cue needs some beats`);
+        continue;
+      }
+      if (!known.has(m[2])) {
+        problems.push(`"${raw}": no move "${m[2]}" (moves: ${moves.join(" ")})`);
+        continue;
+      }
+      const cue = { b0, beats: Math.min(beats, 512), move: m[2], turn: 0, lift: 0 };
+      for (const tok of (m[3] ?? "").replace(/^[,\s]+/, "").split(/\s+/).filter(Boolean)) {
+        const mod = /^([>@~^/%*x=])(.+)$/.exec(tok);
+        if (!mod) {
+          problems.push(`"${raw}": "${tok}" is not >to, @face, ~turn, ^leap, /lean, %crouch, *groove, xspeed or =pose`);
+          continue;
+        }
+        const [, op, arg] = mod;
+        if (op === ">") {
+          const mark = CHOREO_MARKS[arg];
+          const xy = /^(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)$/.exec(arg);
+          if (mark) cue.to = mark;
+          else if (xy) cue.to = [clamp(Number(xy[1]), -6, 6), clamp(Number(xy[2]), -6, 6)];
+          else problems.push(`"${raw}": travel to "${arg}" \u2014 a mark (${Object.keys(CHOREO_MARKS).join(" ")}) or side,depth`);
+        } else if (op === "@") {
+          const named = { cam: "cam", room: 0, front: 0, back: 180, left: -90, right: 90 };
+          if (arg in named) cue.face = named[arg];
+          else if (Number.isFinite(Number(arg))) cue.face = Number(arg);
+          else problems.push(`"${raw}": face "${arg}" \u2014 degrees, cam, room, left, right or back`);
+        } else if (op === "/") {
+          if (Number.isFinite(Number(arg))) cue.lean = clamp(Number(arg), -60, 60);
+          else problems.push(`"${raw}": lean "${arg}" is not degrees`);
+        } else if (op === "%") {
+          if (Number.isFinite(Number(arg)) && Number(arg) > 0) cue.squash = clamp(Number(arg), 0.4, 1.5);
+          else problems.push(`"${raw}": crouch "${arg}" is not a height scale`);
+        } else if (op === "=") {
+          if (arg !== "" && Number.isFinite(Number(arg)) && Number(arg) >= 0 && Number(arg) <= 1) cue.pose = Number(arg);
+          else problems.push(`"${raw}": pose "${arg}" is not a fraction of the move (0\u20131)`);
+        } else if (op === "x") {
+          if (Number.isFinite(Number(arg)) && Number(arg) > 0) cue.rate = clamp(Number(arg), 0.25, 4);
+          else problems.push(`"${raw}": speed "${arg}" is not a multiple`);
+        } else if (op === "*") {
+          if (Number.isFinite(Number(arg)) && Number(arg) > 0) cue.groove = clamp(Number(arg), 0.02, 0.3);
+          else problems.push(`"${raw}": groove "${arg}" is not a depth`);
+        } else if (op === "~") {
+          if (Number.isFinite(Number(arg))) cue.turn = clamp(Number(arg), -1440, 1440);
+          else problems.push(`"${raw}": turn "${arg}" is not degrees`);
+        } else {
+          if (Number.isFinite(Number(arg)) && Number(arg) >= 0) cue.lift = Math.min(Number(arg), 3);
+          else problems.push(`"${raw}": leap "${arg}" is not a height`);
+        }
+      }
+      cues.push(cue);
+      b0 += cue.beats;
+    }
+    if (cues.length) lines.set(actor, { cues, beats: b0 });
+    else problems.push(`line "${rawLine}" has no cues`);
+  }
+  return { lines, problems };
+}
+var CHOREO_HANDOVER = 0.5;
+var clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+var smooth3 = (u) => {
+  const c = clamp(u, 0, 1);
+  return c * c * (3 - 2 * c);
+};
+var posMod = (v, m) => (v % m + m) % m;
+function choreoLine(sheet, slot) {
+  return sheet?.lines.get(slot) ?? sheet?.lines.get("*") ?? null;
+}
+function choreoAt(line, beats) {
+  const b = posMod(beats, line.beats);
+  const n = line.cues.length;
+  let i = 0;
+  while (i < n - 1 && b >= line.cues[i].b0 + line.cues[i].beats) i++;
+  const cue = line.cues[i], next = line.cues[(i + 1) % n], prev = line.cues[(i + n - 1) % n];
+  let side = 0, depth = 0, centre = 0, face = 0, faceCam = 0, turn = 0;
+  const end = (c) => {
+    if (c.to === "centre") centre = 1;
+    else if (c.to) {
+      side = c.to[0];
+      depth = c.to[1];
+      centre = 0;
+    }
+    turn += c.turn;
+  };
+  const facing = (c) => {
+    if (c.face === "cam") faceCam = 1;
+    else if (c.face !== void 0) {
+      face = c.face;
+      faceCam = 0;
+    }
+  };
+  for (let k = 0; k < i; k++) {
+    end(line.cues[k]);
+    facing(line.cues[k]);
+  }
+  facing(cue);
+  const beat = b - cue.b0, u = clamp(beat / cue.beats, 0, 1);
+  const s = smooth3(u);
+  if (cue.to === "centre") centre += (1 - centre) * s;
+  else if (cue.to) {
+    side += (cue.to[0] - side) * s;
+    depth += (cue.to[1] - depth) * s;
+    centre *= 1 - s;
+  }
+  turn += cue.turn * s;
+  const lift = cue.lift > 0 ? cue.lift * Math.sin(Math.PI * u) : 0;
+  const last = i === n - 1;
+  const h = Math.min(CHOREO_HANDOVER, cue.beats / 2, next.beats / 2);
+  const ahead = smooth3((beat - (cue.beats - h)) / h);
+  if (ahead > 0) {
+    if (next.face === "cam") faceCam += (1 - faceCam) * ahead;
+    else if (next.face !== void 0 && !last) {
+      face += angleTo(face, next.face) * ahead;
+      faceCam *= 1 - ahead;
+    } else if (last) {
+      face += angleTo(face, next.face === void 0 ? 0 : next.face) * ahead;
+      faceCam *= 1 - ahead;
+    }
+  }
+  const lean = (cue.lean ?? 0) + ((next.lean ?? 0) - (cue.lean ?? 0)) * ahead;
+  let squash = (cue.squash ?? 1) + ((next.squash ?? 1) - (cue.squash ?? 1)) * ahead;
+  if (next.lift > 0) squash *= 1 - 0.16 * ahead;
+  if (cue.lift > 0) squash *= u < 0.15 ? 0.84 + 0.26 * smooth3(u / 0.15) : 1 + 0.1 * Math.sin(Math.PI * u) - 0.16 * smooth3((u - 0.85) / 0.15);
+  if (prev.lift > 0 && n > 1) squash *= 0.84 + 0.16 * smooth3(beat / Math.min(0.75, cue.beats));
+  const groove = cue.groove ?? 0;
+  if (groove > 0 && cue.lift === 0) squash *= 1 - groove * (1 + Math.cos(2 * Math.PI * posMod(beats, 1))) / 2;
+  return { cue, beat, u, next, ahead, side, depth, centre, face, faceCam, turn, lift, lean, squash };
+}
+function angleTo(a, b) {
+  return posMod(b - a + 180, 360) - 180;
+}
+
 // src/vignette.ts
 var DANCES = ["toprock", "footwork", "windmill", "headspin", "freeze", "drop"];
-var GESTURES = ["talk", "nod", "shake", "hop", "spin", "wiggle", "rest", "peek", "bow", "ink", ...DANCES];
-var BREED_GESTURES = { ink: ["octopus"] };
+var GESTURES = ["talk", "nod", "shake", "hop", "spin", "wiggle", "rest", "peek", "bow", "ink", "puff", ...DANCES];
+var BREED_GESTURES = { ink: ["octopus"], puff: ["blowfish"] };
 var OPEN_MARKS = {
   centre: { x: 0, y: 36, z: 0 },
   left: { x: -70, y: 34, z: 0 },
@@ -2788,6 +2974,7 @@ function poseOf(v, actor, tSec, own) {
           pitch = -0.08 * e;
           break;
         // ink: the body holds still; the octopus squirts its cloud (the tank's InkLayer) and pales.
+        // puff: the body holds still; the blowfish gulps itself round (puffer.ts PufferInput.puffCue).
         // The dances, for a fish with no clips for them: the whole body does what it can.
         case "toprock":
           roll += Math.sin(bt * Math.PI * 2) * 0.3 * e;
@@ -3121,23 +3308,25 @@ var PARAM_DOCS = {
   cameraAzimuth: "Orbit bearing in degrees. 0 looks at the village from the front.",
   cameraElevation: "Degrees above the floor. 8\u201315 is eye level with the fish; 40+ looks down on a castle.",
   cameraDistance: "Distance from the tank centre. 80 is a close-up, 170\u2013220 a village, 300+ a landmark.",
-  shot: "A framing: `orbit` (default), `hero` (three-quarter), `front` (level, long lens), `low` (looking up), `top` (a map), `surface` (the underside), `macro` (nearest landmark), `cast` (the mix's first three). Azimuth and autoRotate turn it, distance scales it.",
+  shot: "A framing: `orbit`, `hero` (three-quarter), `front` (level, long lens), `low`, `top` (a map), `surface`, `macro` (nearest landmark), `cast` (the mix's first three). Azimuth and autoRotate turn it, distance scales it.",
   shotBlend: "Seconds a change of `shot` takes (0 = a cut): the camera moves to the new framing, eased.",
-  cameraFollow: "Ride with one fish (cast slot); -1 is the orbit camera, whose params are ignored while following. With `followSpot` on the slot, a spotlit chase.",
-  followAngle: "Where round the followed fish the chase camera stands, degrees: 0 behind (default), 90 beside, 180 in front looking back at its face.",
-  followDistance: "How far behind the followed fish the camera rides (40\u201370 is a chase). Under ~18 it is the fish's eye; a floor walker sees from its own head height.",
-  autoRotate: "Turntable speed, degrees/second. 0 holds the shot (stages, vignettes); 1\u20132 is a slow reveal. frame.state.camera.bearing: where it stands now.",
-  followAvoid: "Keep the followed fish in view, 0\u20131: the chase camera rises over low clutter or pulls in, eased. For walks through a village.",
-  nearFade: "A creature at the lens dissolves instead of being sliced, 0\u20131. The followed fish never fades.",
+  cameraFollow: "Ride with one fish (cast slot); -1 is the orbit camera (its params ignored while following).",
+  followAngle: "Where round the followed fish the chase camera stands, degrees: 0 behind (default), 90 beside, 180 facing it. A choreographed dancer is measured from the stage's facing instead.",
+  followDistance: "How far behind the followed fish the camera rides (40\u201370 is a chase). Under ~18 it is the fish's eye (a walker's: its head height).",
+  autoRotate: "Turntable speed, degrees/second. 0 holds the shot, 1\u20132 a slow reveal. frame.state.camera.bearing: where it stands now.",
+  followAvoid: "Keep the followed fish in view, 0\u20131: the chase camera rises or pulls in, eased.",
+  followHeight: "Chase camera height in body lengths over its feet, aimed at them (0.2: feet); -1 off.",
+  followLens: "Chase lens, degrees (0: 55; 25 long).",
+  nearFade: "A creature at the lens dissolves, not sliced, 0\u20131. The followed fish never fades.",
   // cast
   fishCount: "How many fish when `fishMix` is empty (all are `fishUrl`).",
   finish: "A final full-screen pass: gentle grade, soft vignette, dither against banding, and restrained bloom on high-end devices (0 = none; never on the low tier).",
   tiltShift: "Tilt-shift, 0\u20131: sharp through the middle, soft above and below, like a model. Mid/high tiers.",
-  depthOfField: "Depth of field, 0\u20131: the subject sharp (followed fish, `cast` leads), the rest soft. High tier.",
+  depthOfField: "Depth of field, 0\u20131: the subject (followed fish, `cast` leads) sharp, the rest soft. High tier.",
   ambientOcclusion: "Ambient occlusion, 0\u20131: crevices darken. High tier.",
-  highlights: "Bright light rolls off instead of clipping, 0\u20131: a fish in a shaft stays a fish. Bright rooms want it. Mid/high tiers.",
+  highlights: "Bright light rolls off instead of clipping, 0\u20131: a fish in a shaft stays a fish. Mid/high tiers.",
   fishUrl: "The single model used when `fishMix` is empty: ipfs://, https://assets.idlescreens.com/, or a URL on the page's own origin. Any other host is refused and the default fish swims.",
-  fishMix: "The cast: `id[:count][@style]`, comma-separated: `100:2@drift, 257:1, seahorse:3, shark:1@patrol`. Minted breeds plus bundled: shark crab dori glowfish babyfish hackerfish blowfish starfish octopus snail dot dolphin. Floor walkers keep their own pace: crab, starfish (dances with `starfishDance`), snail. `dot` (a courier box on legs) and `dolphin` (chatters, flips, breaches; stands on its tail to act) play vignette gestures. Overrides fishCount/fishUrl.",
+  fishMix: "The cast: `id[:count][@style]`, comma-separated: `100:2@drift, seahorse:3, shark:1@patrol`. Minted breeds plus bundled: shark crab dori glowfish babyfish hackerfish blowfish starfish octopus snail dot dolphin. Floor walkers keep their own pace: crab, starfish (dances: `starfishDance`, `choreography`), snail. `dot` (a box on legs), `dolphin` (flips, breaches) play vignette gestures. Overrides fishCount/fishUrl.",
   dracoPath: "Where the Draco decoder lives; leave empty on a channel. Only the page's own origin or the shipped copy is used.",
   swimSpeed: "Global swim speed multiplier. 0.4 is contemplative, 1 lively.",
   swimStyle: "How the cast swims unless a fishMix entry says otherwise (`@style`). `auto` picks by breed.",
@@ -3161,14 +3350,16 @@ var PARAM_DOCS = {
   fishGlow: "How strongly GLOW- parts of a fish bloom and light their neighbours and the floor.",
   fishMetal: "`on` (default) gives METAL- parts a polished, reflective finish.",
   snailShell: "Snail shells: `banded`, `pearl` (iridescent), `gold`, `glow` (a spiral breathing light; best at night); `mix` (default), each its own. Lit fish only. frame.state.fish[i].shell says which.",
-  starfishDance: "Starfish dance: `aerobics`, a class in unison facing the camera; `freestyle`, each its own move every eight counts; `duet`, couples face to face (with `spotRig: 0/#ffd27a*26, 1/#ff8ad0*26`); `off` (default). Cast a few (`starfish:7`), `shot: front`, `autoRotate: 0`, a bright room.",
-  danceTempo: "Beats per minute for the starfish dance (60\u2013180, default 128). Glides on the beat.",
+  starfishDance: "Starfish dance: `aerobics` (a class in unison), `freestyle` (a move each per eight counts), `duet` (couples), `off`. Cast a few: `starfish:7`.",
+  danceTempo: "Dance BPM; glides on the beat.",
+  choreography: "Starfish dance cues, on the beat (see grammar).",
   fishLook: "`neon` dresses the bundled creatures for blacklight: near-black coats, eyes (and a crab's mouth) glowing a neon of their own. Best in a dark room with `finish`. Default `natural`.",
   fishRim: "A thin edge of the water's light round each fish, 0\u20131 (lit mode): dark fish on dark water. 0.6\u20131 in dark rooms.",
-  fishShadows: "Soft shadows on the ground under the swimmers, 0\u20131: dark near the sand, faint high up.",
-  fishFadeIn: "Seconds an arriving fish takes to dissolve in (0 = it pops in).",
-  sceneryShadows: "Soft shadows under rocks, homes, castle, pyramids, geodes and lamps, 0\u20131, so nothing floats.",
-  voxelAO: "Plant cubes darken where they touch each other and the sand, 0\u20131: solid coral. All tiers.",
+  fishShadows: "Soft shadows under the swimmers, 0\u20131: dark near the sand, faint high up.",
+  fishAO: "A fish's own corners darken, 0\u20131: solid fish. All tiers.",
+  fishFadeIn: "Seconds an arriving fish takes to fade in (0 pops in).",
+  sceneryShadows: "Soft shadows under rocks, homes, castle, pyramids, geodes, lamps, 0\u20131: nothing floats.",
+  voxelAO: "Plant cubes darken where they touch each other and the sand, 0\u20131. All tiers.",
   swimWave: "Fish bend as they swim: a wave nose to tail, the body curling into turns (0 = rigid wiggle). Skips the turtle, crab and fish with a skeleton; the seahorse gets fin, tail and nod instead.",
   fishAvoid: "Fish make way for each other: a pair about to meet parts a second ahead, the smaller giving more, over or under before round. 1 (default) on, 0 pass-through. `inspect().crowding` counts pairs still touching.",
   eyeLife: "Eyes blink, look, and emote (0 = painted on). Redraws each token's own pixel-grid eye; black and white only.",
@@ -3188,7 +3379,7 @@ var PARAM_DOCS = {
   waterY: "Height of the water ceiling; -1 = the environment's own.",
   rayStrength: "Surface light shafts, within device budget: 5 high tier, 2 standard; none on the lowest tier with a surface (abyss, vent, universe keep 2; perceiveChannel then reads 0).",
   raySoftness: "Shafts as soft volume, not flat sheets, 0\u20131. 1 for anything cinematic.",
-  floorDetail: "A seabed, not a coloured plane, 0\u20131: ripples, silt, grain; the floor's far edge fades into the fog.",
+  floorDetail: "A seabed, not a coloured plane, 0\u20131: ripples, silt, grain; its far edge fades into the fog.",
   caustics: "The dancing net of light from the surface on the floor, rocks, plants and fish (0 = none). Sharp near the top, soft and dim deep down.",
   causticScale: "Size of the caustic cells: below 1 a fine shimmer, above 1 broad slow bands.",
   surfaceMirror: "The surface from below: a window to the light in a rippling mirror of the tank (0 = plain). Needs reef, kelp, ice or lagoon; for the `surface` and `low` shots. High tier mirrors the tank, mid the deep water.",
@@ -3243,7 +3434,7 @@ var PARAM_DOCS = {
   spotColor: "Colour of the single `followSpot`.",
   spotShadow: "The spotted fish's shadow in its pool. 0 none, 1 true size.",
   spotRig: "Up to three spots: `slot[/color][*radius]` follows a fish, `@mark` stands on a mark (`@mic` lights whoever steps up). They are a, b, c in order. Overrides followSpot.",
-  spotCues: "A looping cue sheet for the rig: `8s:a, 8s:b, 12s:a+b, 4s:-` (`-` = blackout). Spots cross-fade at each cue.",
+  spotCues: "Looping cues for the rig: `8s:a, 12s:a+b, 4s:-` (`-` blackout, cues \u2265 2 s). Spots cross-fade.",
   vignette: "A small scene for the first 2\u20133 fish: a preset (tea\xB7bedtime\xB7seek indoors; duet\xB7trio\xB7openmic on the open stage) or a script of beats. A floor creature cast as an actor stays on the floor. Grammar below."
 };
 var GRAMMAR = `
@@ -3269,13 +3460,14 @@ geodeMineral  world | mineral, \u2026   amethyst agate celestine citrine carneli
 floraPalette  world | #rrggbb, \u2026  (\u22646)                          world \xB7 #ff4fa0, #ffb347, #4fd1ff
 spotRig   slot|@mark[/color][*radius], \u2026  (\u22643; they become a, b, c)   0/#ffd27a*24, 1/#ff8ad0*24, 2/#7fdcff*24
 spotCues  <sec>s:<spots>, \u2026  loops                               4s:-, 7s:a, 7s:b, 12s:a+b
+choreography  [a|*:] <beats>:<move> [>to @face ~turn ^leap /lean %crouch *groove xspeed =pose],\u2026|\u2026  moves ${STARFISH_MOVE_NAMES.join(" ")}
 signs     kind[@place][>target][/#color][*size][:text], \u2026   plank@gate:"Welcome to the reef", neon@home1/#ff4fa0:OPEN, led@plaza:TIDE 4.2M
           kinds plank arrow ring porthole neon led \xB7 places gate plaza courtyard hub fountain home1 home2 home3 centre left right front back
           an arrow points at >target \xB7 text \u2264 plank 24, arrow 16, ring 10, porthole 4 (empty = a fish), neon 14, led 64 (scrolls) \xB7 \u2264 8 signs
 vignette  beats separated by |, cues by comma; actors a b c d are fish slots 0 1 2 3
           [<sec>s:] actor =mark  be there, no travel (a later beat's = snaps at its start)    actor >mark  swim there
           actor @mark | @actor   face it    a b circle mark  each named actor rings it, back to its spot by the beat's end; others stay put
-          actor follow actor     gestures: talk nod shake hop spin wiggle rest peek bow \xB7 ink (octopus only: a cloud of ink)
+          actor follow actor     gestures: talk nod shake hop spin wiggle rest peek bow \xB7 ink (octopus) \xB7 puff (blowfish)
           dances: toprock footwork windmill headspin freeze drop (a betafish dances them with its own body; 2 s beats keep them on a 120 bpm bar)
           Give every beat a duration and end where you began and a spotCues sheet stays in step forever.
           Fish cast @audience sit out front facing the stage: they laugh as each talk ends and applaud each bow.
@@ -3288,7 +3480,7 @@ vignette  beats separated by |, cues by comma; actors a b c d are fish slots 0 1
 var NIGHT = { fogColor: "#0a0a1a", fogNear: 120, fogFar: 700 };
 var STAGE = { fogColor: "#01030a", floorColor: "#0a1322", fogNear: 120, fogFar: 650, autoRotate: 0 };
 var ALIVE = { eyeLife: 1 };
-var CINEMATIC = { highlights: 1, raySoftness: 1, nearFade: 1, finish: 0.6 };
+var CINEMATIC = { highlights: 1, raySoftness: 1, nearFade: 1, voxelAO: 1, fishAO: 1, finish: 0.6 };
 var RECIPES = [
   {
     id: "geode-harbor",
@@ -3567,7 +3759,7 @@ var RECIPES = [
   {
     id: "starfish-class",
     label: "Starfish aerobics",
-    what: "Seven starfish stand up on a pale ice floor, face the camera and dance an aerobics routine in unison, an instructor in front.",
+    what: "Seven starfish stand up on a pale ice floor, face the camera and dance aerobics in unison, an instructor in front.",
     params: { environment: "ice", fishMix: "starfish:7", starfishDance: "aerobics", danceTempo: 120, shot: "front", autoRotate: 0 }
   },
   {
@@ -3609,7 +3801,7 @@ var RECIPES = [
   {
     id: "snail-night",
     label: "Snails by night",
-    what: "Glowing snails on a dark floor: each spiral breathes light, the feelers pool green on the sand, and the camera rides beside one.",
+    what: "Glowing snails on a dark floor: each spiral breathes light, feelers pool green on the sand, the camera beside one.",
     params: {
       ...ALIVE,
       ...NIGHT,
@@ -3628,7 +3820,7 @@ var RECIPES = [
   {
     id: "reef-cinematic",
     label: "Reef, cinematic",
-    what: "A small reef cast framed close wherever it swims, in soft shafts, each fish over its shadow. The polished look.",
+    what: "A small reef cast framed close wherever it swims, in soft shafts, each fish over its shadow.",
     params: {
       ...ALIVE,
       ...CINEMATIC,
@@ -3653,7 +3845,7 @@ var RECIPES = [
   {
     id: "night-cinematic",
     label: "Deep night, cinematic",
-    what: "The deep at night: glowfish under jellyfish lanterns, a shark sliding through, every outline rimmed in light.",
+    what: "The deep at night: glowfish under jellyfish lanterns, a shark sliding through, outlines rimmed in light.",
     params: {
       ...ALIVE,
       ...CINEMATIC,
@@ -3677,7 +3869,7 @@ var RECIPES = [
   {
     id: "village-cinematic",
     label: "Village, cinematic",
-    what: "Dot, Puff and Hex meet in a sunlit village of stone homes, seen high through a tilt-shift lens: a model village.",
+    what: "Dot, Puff and Hex meet in a sunlit village of stone homes, seen through a tilt-shift lens.",
     params: {
       ...ALIVE,
       ...CINEMATIC,
@@ -3725,6 +3917,7 @@ function validateMetaquariumParams(params) {
   if (str("townProps")) push("townProps", parseTownProps(str("townProps")).problems);
   if (str("floorCover")) push("floorCover", parseFloorCover(str("floorCover")).problems);
   if (str("pyramidShow")) push("pyramidShow", parsePyramidShow(str("pyramidShow")).problems);
+  if (str("choreography")) push("choreography", parseChoreography(str("choreography"), STARFISH_MOVE_NAMES).problems);
   if (str("geodeMineral")) push("geodeMineral", parseGeodeMineral(str("geodeMineral")).problems);
   const rig = parseSpotRig(str("spotRig"));
   push("spotRig", rig.problems);
@@ -3841,9 +4034,11 @@ function dependencyProblems(params) {
   if (dance !== "off" && !starfishSwims) {
     out.push({ path: "starfishDance", also: ["fishMix"], message: "no starfish in the cast to dance \u2014 add e.g. starfish:7 (slots past the cap never swim)" });
   }
-  if (set("danceTempo") && dance === "off") out.push({ path: "danceTempo", also: ["starfishDance"], message: "does nothing while starfishDance is off" });
+  const choreographed = !!str("choreography").trim();
+  if (set("danceTempo") && dance === "off" && !choreographed) out.push({ path: "danceTempo", also: ["starfishDance"], message: "does nothing while starfishDance is off" });
+  if (choreographed && !starfishSwims) out.push({ path: "choreography", also: ["fishMix"], message: "no starfish in the cast to dance it \u2014 add e.g. starfish:5" });
   if (follow < 0) {
-    for (const k of ["followDistance", "followAngle", "followAvoid"]) if (set(k)) out.push({ path: k, also: ["cameraFollow"], message: "does nothing while cameraFollow is -1 (the orbit camera)" });
+    for (const k of ["followDistance", "followAngle", "followAvoid", "followHeight", "followLens"]) if (set(k)) out.push({ path: k, also: ["cameraFollow"], message: "does nothing while cameraFollow is -1 (the orbit camera)" });
   } else if (follow < cast) {
     for (const k of ORBIT_PARAMS) if (set(k)) out.push({ path: k, also: ["cameraFollow"], message: `ignored while cameraFollow rides with slot ${follow} \u2014 they return when it is -1` });
   }
@@ -3995,6 +4190,7 @@ function describeMetaquarium(params, timed = []) {
     stage.push(VIGNETTES[v] ? `vignette: ${v}` : `vignette: ${v.split(/[|\n]/).filter((b) => b.trim()).length} beats`);
   }
   if (str("starfishDance") !== "off") stage.push(`starfish ${str("starfishDance")}${has("danceTempo") ? ` at ${num("danceTempo")} bpm` : ""}`);
+  if (str("choreography").trim()) stage.push(`a starfish choreography${has("danceTempo") ? ` at ${num("danceTempo")} bpm` : ""}`);
   const camera = [];
   const follow = Math.round(num("cameraFollow"));
   if (follow >= 0) {
@@ -4074,7 +4270,8 @@ var METAQUARIUM_PARAMS = {
   followDistance: { type: "number", default: 45, min: 0, max: 160, ease: "smooth" },
   /** Where round the followed fish the chase camera stands, degrees: 0 behind
    *  it (the default), 90 at its side, 180 in front looking back at its face
-   *  — a hackerfish's screen, a crab's smile. */
+   *  — a hackerfish's screen, a crab's smile. A choreographed dancer is framed
+   *  from its stage's front instead, so a spin turns the dancer, not the shot. */
   followAngle: { type: "number", default: 0, min: -180, max: 180, ease: "smooth" },
   /** Keep the followed fish in view (sightline.ts): when a home, a wall, a lamp
    *  or a kelp stand comes between it and the chase camera, the camera rises a
@@ -4082,6 +4279,15 @@ var METAQUARIUM_PARAMS = {
    *  a game camera's spring arm does — eased, never a snap. 0 (default) is the
    *  plain chase camera; 1 the full arm. Not the fish's-eye view (it has none). */
   followAvoid: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" },
+  /** The chase camera's height over the followed fish's feet, in its body
+   *  lengths. -1 (default) rides a little above it, looking at its middle;
+   *  set, the camera stands at that height aimed at its feet — 0.1–0.3 on a
+   *  long lens is a shot of a walker's feet, the floor behind them. */
+  followHeight: { type: "number", default: -1, min: -1, max: 3, ease: "step" },
+  /** The chase camera's lens: degrees of view, top to bottom. 0 (default) is
+   *  the orbit camera's 55; 20–30 is a long lens — flatter and tighter, from
+   *  further back. */
+  followLens: { type: "number", default: 0, min: 0, max: 90, ease: "step" },
   /** Continuous orbit speed, degrees/second. Zero by default: the tank is
    *  still, letting the fish movement carry the scene. Steer up for an orbit. */
   autoRotate: { type: "number", default: 0, min: 0, max: 12, ease: "smooth" },
@@ -4284,6 +4490,10 @@ var METAQUARIUM_PARAMS = {
    *  mode), brighter on top: what separates a dark fish from dark water.
    *  0 is none. */
   fishRim: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" },
+  /** The fish's own corners darken — a fin's root, the step at the head, the
+   *  gap under a shell — read off the voxels they are built from. Baked once
+   *  per breed, the first frame it is on; every tier. 0 is off. */
+  fishAO: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" },
   /** A soft shadow on the ground under every swimmer: small and dark near
    *  the sand, wide and faint high up — what puts a fish at a height instead
    *  of floating in front of the floor. 0 is none (floor walkers always
@@ -4352,6 +4562,13 @@ var METAQUARIUM_PARAMS = {
   /** The dance's tempo, beats per minute. Every move is a bar of four beats.
    *  Integrated when steered, so a glide speeds the class up on the beat. */
   danceTempo: { type: "number", default: 128, min: 60, max: 180, ease: "smooth" },
+  /** An authored dance on the beat (choreo.ts): a cue sheet per dancer —
+   *  `a: 8:lie, 4:rise, 4:reach >right @cam | *: 4:march ~360, 4:jacks ^0.5`.
+   *  Set, every starfish dances it (in the class's places, or the couples'
+   *  under `starfishDance: duet`), facing `cameraAzimuth`; a dancer it leaves
+   *  out keeps `starfishDance`'s routine, or stands and waits. Beats on the
+   *  `danceTempo` clock from the start, so a sheet lines up with music. */
+  choreography: { type: "string", default: "", ease: "step" },
   /** Eye life, 0..1: blinks on a personal clock, idle saccades, pupils that
    *  lead a turn or a climb, eyes on whoever a vignette has it talking to, a
    *  glance at the camera now and then, wide for a hop and shut for a rest.
@@ -4751,6 +4968,10 @@ export {
   SIGN_TEXT_MAX,
   MAX_SIGNS,
   parseSignMix,
+  STARFISH_MOVE_NAMES,
+  parseChoreography,
+  choreoLine,
+  choreoAt,
   GESTURES,
   OPEN_MARKS,
   parseVignette,
@@ -4777,4 +4998,4 @@ export {
   paramSpaceWith,
   coerceNum
 };
-//# sourceMappingURL=chunk-5DJ5WBVN.js.map
+//# sourceMappingURL=chunk-M2PKNQNY.js.map