@idle-screens/saver-metaquarium 0.5.1 → 0.7.0

package/README.md

@@ -58,12 +58,15 @@ frame loop (rAF or renderFrame(t)):
 | swimSpeed | number | 1 | Swim time-scale multiplier |
 | fogColor | color | #030009 | Atmosphere / background |
 | fishUrl | string | ipfs://…/fish_257_….glb | GLB model URL, single-breed mode (playground can override to a local asset) |
-| fishMix | string | "" | Mixed population DSL: `id[:count]` comma-separated, catalog ids or breed aliases (`"257:2,100:1"`). Non-empty overrides fishUrl + fishCount; counts absolute, tier-capped |
+| fishMix | string | "" | Mixed population DSL: `id[:count][@style]` comma-separated, catalog ids or breed aliases (`"257:2,100:1"`, `"457:3@hover,257:6@school"` — per-token swim style; untagged tokens follow `swimStyle`). Non-empty overrides fishUrl + fishCount; counts absolute, tier-capped |
 | fogNear | number | 60 | Fog start distance (the old hardcoded Fog near) |
 | fogFar | number | 500 | Fog full-opacity distance; tank enforces > near + 20 |
 | moteDensity | number | 0 | Plankton motes, 0–1 of the tier budget (400/250/120). 0 = off |
 | moteColor | color | #7fd6ff | Mote tint |
 | floorColor | color | #0a1d33 | Floor disc color (the old hardcoded navy) |
+| swimStyle | enum | loop | `loop` (pre-style), `school`, `drift`, `hover`, `patrol`, `bottom`, `surface`; relationship styles `follow` / `pair` / `chase` bond a fish to the nearest preceding unbonded fish in the mix (and swim in its depth band); `auto` gives each untagged token its breed's default |
+| lightSeek | number | 0 | Free fish drawn toward the room's light shafts, each to its own pool (needs rays) |
+| formationBreathe | number | 0 | The school relaxes outward and back on a ~15 s cycle; only ever expands |
 
 ## File map
 

package/dist/{chunk-23P73MYY.js → chunk-RTUYWDDZ.js}

@@ -1,55 +1,69 @@
 // src/environments.ts
 var FLOOR_KINDS = ["flat", "dunes", "ridges", "basin"];
 var ENVIRONMENTS = [
-  { name: "void", label: "Void", water: null, floor: "flat", rays: null },
+  { name: "void", label: "Void", water: null, floor: "flat", rays: null, seedSalt: 0 },
   {
     name: "abyss",
     label: "Abyss",
     water: null,
     floor: "basin",
-    rays: { strength: 0.35, color: "#0e4a6e", y: -620 }
+    seedSalt: 161,
+    rays: { strength: 0.35, color: "#0e4a6e", y: -620 },
+    palette: { fog: "#02030a", floor: "#05070f", mote: "#4fd4a8" }
   },
   {
     name: "reef",
     label: "Reef",
     water: { y: 150, color: "#2ad4ff", opacity: 0.18 },
     floor: "dunes",
-    rays: { strength: 0.5, color: "#bfefff", y: 900 }
+    rays: { strength: 0.5, color: "#bfefff", y: 900 },
+    seedSalt: 162,
+    palette: { fog: "#0a3d5c", floor: "#123c50", mote: "#bfe8ff" }
   },
   {
     name: "kelp",
     label: "Kelp forest",
     water: { y: 170, color: "#1e6f5c", opacity: 0.2 },
     floor: "ridges",
-    rays: { strength: 0.4, color: "#9ef5d0", y: 820 }
+    rays: { strength: 0.4, color: "#9ef5d0", y: 820 },
+    seedSalt: 163,
+    palette: { fog: "#07271e", floor: "#0c2f22", mote: "#a5f2c6" }
   },
   {
     name: "ice",
     label: "Under ice",
     water: { y: 132, color: "#cfefff", opacity: 0.32 },
     floor: "flat",
-    rays: { strength: 0.6, color: "#eaf8ff", y: 1e3 }
+    rays: { strength: 0.6, color: "#eaf8ff", y: 1e3 },
+    seedSalt: 164,
+    palette: { fog: "#12283c", floor: "#1b3d59", mote: "#d8f2ff" }
   },
   {
     name: "vent",
     label: "Hydrothermal vent",
     water: null,
     floor: "ridges",
-    rays: { strength: 0.45, color: "#ff7a3c", y: -520 }
+    seedSalt: 165,
+    rays: { strength: 0.45, color: "#ff7a3c", y: -520 },
+    palette: { fog: "#170502", floor: "#4a1a0a", mote: "#ff8a3c" }
   },
   {
     name: "lagoon",
     label: "Lagoon",
     water: { y: 118, color: "#7ff3d0", opacity: 0.22 },
     floor: "dunes",
-    rays: { strength: 0.55, color: "#fff3b0", y: 950 }
+    rays: { strength: 0.55, color: "#fff3b0", y: 950 },
+    seedSalt: 166,
+    palette: { fog: "#0d453f", floor: "#6e4457", mote: "#eafff4" }
   },
   {
     name: "universe",
     label: "Universe",
     water: null,
     floor: "ridges",
-    rays: { strength: 0.3, color: "#c39bff", y: 1200 }
+    seedSalt: 167,
+    rays: { strength: 0.3, color: "#c39bff", y: 1200 },
+    palette: { fog: "#0d0618", floor: "#171030", mote: "#cfa8ff" }
   }
 ];
 var ENVIRONMENT_NAMES = ENVIRONMENTS.map((e) => e.name);
@@ -74,11 +88,50 @@ var SWIM_STYLES = [
   { name: "loop", label: "Loop", speedMul: 1, band: "free", bobAmp: 0, bobHz: 0, formation: false, travel: 1 },
   { name: "school", label: "School", speedMul: 1, band: "free", bobAmp: 1.5, bobHz: 0.5, formation: true, travel: 1 },
   { name: "drift", label: "Drift", speedMul: 0.35, band: "mid", bobAmp: 5, bobHz: 0.13, formation: false, travel: 0.6 },
-  { name: "hover", label: "Hover", speedMul: 0.2, band: "free", bobAmp: 7, bobHz: 0.3, formation: false, travel: 0.12 },
+  // speedMul 0.55, not 0.2: QA measured hover at swimSpeed 0.5 pinned to a
+  // fixed screen x for 8+ seconds — frozen, not station-keeping. The two
+  // multiplied slowdowns (speedMul x travel) were the freeze.
+  { name: "hover", label: "Hover", speedMul: 0.55, band: "free", bobAmp: 7, bobHz: 0.3, formation: false, travel: 0.12 },
   { name: "patrol", label: "Patrol", speedMul: 0.55, band: "mid", bobAmp: 1, bobHz: 0.09, formation: false, travel: 1 },
   { name: "bottom", label: "Bottom-hugger", speedMul: 0.7, band: "floor", bobAmp: 2, bobHz: 0.4, formation: false, travel: 1 },
-  { name: "surface", label: "Surface-skimmer", speedMul: 0.9, band: "ceiling", bobAmp: 3, bobHz: 0.55, formation: false, travel: 1 }
+  { name: "surface", label: "Surface-skimmer", speedMul: 0.9, band: "ceiling", bobAmp: 3, bobHz: 0.55, formation: false, travel: 1 },
+  // Relationships (MQ31). A bonded fish has no route of its own: it rides
+  // its leader's plan at a lag, so a `@follow` trio behind a turtle is a
+  // file, a `@pair` couple orbits a shared point, and a `@chase` closes on
+  // its leader and falls back. All three stay pure in t because the leader
+  // is — the follower samples the SAME closed form at `d - lag`.
+  { name: "follow", label: "Follower", speedMul: 1, band: "free", bobAmp: 1.2, bobHz: 0.5, formation: false, travel: 1, bond: "follow" },
+  { name: "pair", label: "Pair", speedMul: 0.8, band: "free", bobAmp: 2.5, bobHz: 0.35, formation: false, travel: 1, bond: "pair" },
+  { name: "chase", label: "Chaser", speedMul: 1, band: "free", bobAmp: 1, bobHz: 0.6, formation: false, travel: 1, bond: "chase" }
 ];
+var AUTO_STYLE_BY_BREED = {
+  angelfish: "school",
+  betafish: "drift",
+  seahorse: "hover",
+  seaturtle: "surface",
+  // The unminted NPC set.
+  blowfish: "hover",
+  hackerfish: "loop",
+  glowfish: "drift",
+  babyfish: "school",
+  shark: "patrol",
+  crab: "bottom",
+  jellyfish: "drift",
+  dori: "school"
+};
+function autoStyleFor(breed) {
+  const name = breed ? AUTO_STYLE_BY_BREED[breed.toLowerCase()] : void 0;
+  return swimStyleOf(name ?? "loop");
+}
+function formationBreathe(tSec, amount) {
+  const a = Math.max(0, Math.min(1, amount));
+  if (a <= 0) return 1;
+  return 1 + a * 0.22 * (0.5 + 0.5 * Math.sin(tSec * 0.42));
+}
+function idleSway(style, tSec, phase) {
+  if (style.travel >= 1 || style.formation) return 0;
+  return (1 - style.travel) * 0.5 * Math.sin(tSec * 0.45 + phase);
+}
 var SWIM_STYLE_NAMES = SWIM_STYLES.map((s) => s.name);
 function swimStyleOf(name) {
   return SWIM_STYLES.find((s) => s.name === name) ?? SWIM_STYLES[0];
@@ -105,9 +158,13 @@ function fishVariation(index, variance) {
     anchor: fishHash(index, 7)
   };
 }
+function anchorFraction(style, index, variance) {
+  if (style.name === "loop") return 0;
+  return fishVariation(index, variance).anchor;
+}
 var FISH_LENGTH = 18;
 var FORMATION_HALF_WIDTH = 62;
-var FORMATION_SHAPES = ["phalanx", "line", "ring", "wedge", "ball"];
+var FORMATION_SHAPES = ["phalanx", "line", "ring", "wedge", "ball", "wheel"];
 function formationSlot(index, count, variance, halfWidth = FORMATION_HALF_WIDTH, shape = "phalanx") {
   const j = 0.35 + 0.65 * Math.max(0, Math.min(1, variance));
   if (shape === "line") {
@@ -131,6 +188,15 @@ function formationSlot(index, count, variance, halfWidth = FORMATION_HALF_WIDTH,
       back: Math.sin(a) * r
     };
   }
+  if (shape === "wheel") {
+    const r = Math.max(FISH_LENGTH * 1.6, count * FISH_LENGTH * 1.35 / (Math.PI * 2));
+    const a = index / Math.max(1, count) * Math.PI * 2;
+    return {
+      side: Math.cos(a) * r,
+      up: Math.sin(a) * Math.min(r * 0.55, 24) + (fishHash(index, 5) - 0.5) * FISH_LENGTH * 0.3 * j,
+      back: Math.sin(a) * r
+    };
+  }
   if (shape === "wedge") {
     const VSIZE = 9;
     const layers = Math.ceil(Math.max(1, count) / VSIZE);
@@ -138,12 +204,12 @@ function formationSlot(index, count, variance, halfWidth = FORMATION_HALF_WIDTH,
     const within = index % VSIZE;
     const rank = within + 1 >> 1;
     const wing = within === 0 ? 0 : within % 2 === 1 ? -1 : 1;
+    const droop = (rank - 2) * FISH_LENGTH * (layers === 1 ? 0.24 : 0.12);
+    const pitch2 = layers === 1 ? 1.5 : 1.2;
+    const jit2 = layers === 1 ? 0.2 : 0.15;
     return {
       side: wing * rank * FISH_LENGTH * 1.25 + (fishHash(index, 4) - 0.5) * FISH_LENGTH * 0.3 * j,
-      // 1.5 body lengths per layer with a small jitter: adjacent layers seat
-      // the same rank directly above each other, so pitch minus worst-case
-      // jitter closure must clear one body length.
-      up: (layer - (layers - 1) / 2) * FISH_LENGTH * 1.5 + (fishHash(index, 5) - 0.5) * FISH_LENGTH * 0.2 * j,
+      up: (layer - (layers - 1) / 2) * FISH_LENGTH * pitch2 + (fishHash(index, 5) - 0.5) * FISH_LENGTH * jit2 * j - droop,
       back: (rank - 2) * FISH_LENGTH * 1.35
     };
   }
@@ -189,6 +255,12 @@ function formationExtent(count, variance, shape = "phalanx") {
   }
   return { side, up, back, reach };
 }
+function fitBreath(extent, lattice, bounds, margin = FISH_LENGTH * 0.5) {
+  let fit = lattice;
+  if (extent.up > 0) fit = Math.min(fit, Math.max(1, (bounds.yRange / 2 - margin) / extent.up));
+  if (extent.reach > 0) fit = Math.min(fit, Math.max(1, (bounds.radius - margin) / extent.reach));
+  return fit;
+}
 function bandRange(band) {
   switch (band) {
     // Tight, because 0..0.3 of a 57-unit volume is nearly two body lengths of
@@ -226,10 +298,32 @@ function splineAt(points, g) {
     catmullRom(p0[2], p1[2], p2[2], p3[2], u)
   ];
 }
-var PATH_SHAPES = ["wander", "orbit", "eight", "helix", "canyon"];
-function shapeWaypoints(shape, rng, bounds) {
+var PATH_SHAPES = ["wander", "orbit", "eight", "helix", "canyon", "crossing"];
+function shapeWaypoints(shape, rng, bounds, opts = {}) {
   const points = [];
   const ySpan = bounds.yMax - bounds.yMin;
+  if (shape === "crossing") {
+    const n2 = 16;
+    const az = (opts.cameraAzimuthDeg ?? 0) * Math.PI / 180;
+    const rx = Math.cos(az), rz = -Math.sin(az);
+    const dx = Math.sin(az), dz = Math.cos(az);
+    const len = bounds.radius * 0.9;
+    const depth = bounds.radius * rng.range(0.18, 0.3);
+    const y0 = bounds.yMin + ySpan * rng.range(0.35, 0.6);
+    const lift = ySpan * rng.range(0.04, 0.1);
+    for (let i = 0; i < n2; i++) {
+      const u = i / n2 * Math.PI * 2;
+      const along = Math.sin(u) * len;
+      const toward = Math.cos(u) * depth;
+      points.push([
+        rx * along + dx * toward,
+        // The far leg rides a little higher so it never hides behind the near one.
+        y0 + (toward < 0 ? lift : 0) + ySpan * rng.range(0, 0.04),
+        rz * along + dz * toward
+      ]);
+    }
+    return points;
+  }
   if (shape === "orbit") {
     const n2 = 14 + rng.int(0, 4);
     const r0 = bounds.radius * rng.range(0.45, 0.8);
@@ -304,8 +398,8 @@ function shapeWaypoints(shape, rng, bounds) {
   }
   return points;
 }
-function compileSwimPlan(rng, bounds, shape = "wander") {
-  const points = shapeWaypoints(shape, rng, bounds);
+function compileSwimPlan(rng, bounds, shape = "wander", opts = {}) {
+  const points = shapeWaypoints(shape, rng, bounds, opts);
   const n = points.length;
   const arc = new Float32Array(ARC_SAMPLES + 1);
   let prev = splineAt(points, 0);
@@ -371,11 +465,13 @@ function swimPoseAtDistance(plan, dist) {
 // src/maneuver.ts
 var MANEUVERS = ["none", "dart", "startle", "graze", "curious", "zoomies"];
 var SPECS = {
-  dart: { name: "dart", dur: 2.4, interval: 14, advance: 4.5, kick: 0.5, lift: 0, flurry: 1.1, bursts: 1 },
-  startle: { name: "startle", dur: 1.8, interval: 18, advance: 1.2, kick: 2.8, lift: 0.4, flurry: 1.3, bursts: 1 },
-  graze: { name: "graze", dur: 5.5, interval: 16, advance: -3.2, kick: 0.6, lift: -0.7, flurry: 0.3, bursts: 1 },
-  curious: { name: "curious", dur: 4, interval: 15, advance: 0.8, kick: 2, lift: 0.2, flurry: 0.5, bursts: 1 },
-  zoomies: { name: "zoomies", dur: 3.2, interval: 20, advance: 7.5, kick: 0.9, lift: 0.15, flurry: 1.5, bursts: 3 }
+  dart: { name: "dart", dur: 2.4, interval: 14, advance: 4.5, kick: 0.5, lift: 0, flurry: 1.1, bursts: 1, pitch: 0, contagious: false },
+  startle: { name: "startle", dur: 1.8, interval: 18, advance: 1.2, kick: 2.8, lift: 0.4, flurry: 1.3, bursts: 1, pitch: 0.18, contagious: true },
+  // Graze sinks for real now: lift beyond ±1 is deliberate — QA measured the
+  // old -0.7 × 0.6 at 7.6u of drop, indistinguishable from hover's idle bob.
+  graze: { name: "graze", dur: 5.5, interval: 16, advance: -3.2, kick: 0.6, lift: -2.1, flurry: 0.3, bursts: 1, pitch: -0.55, contagious: false },
+  curious: { name: "curious", dur: 4, interval: 15, advance: 0.8, kick: 2, lift: 0.2, flurry: 0.5, bursts: 1, pitch: 0.12, contagious: false },
+  zoomies: { name: "zoomies", dur: 3.2, interval: 20, advance: 7.5, kick: 0.9, lift: 0.15, flurry: 1.5, bursts: 3, pitch: 0, contagious: false }
 };
 function maneuverSpecOf(name) {
   return Object.hasOwn(SPECS, name) ? SPECS[name] : null;
@@ -390,38 +486,44 @@ function surges(u, bursts) {
   if (u <= 0) return 0;
   if (u >= 1) return 1;
   const x = u * bursts;
-  return (Math.floor(x) + smooth(x - Math.floor(x))) / bursts;
+  const frac = x - Math.floor(x);
+  return (Math.floor(x) + smooth(frac / 0.55)) / bursts;
 }
-var IDLE = { along: 0, alongBump: 0, side: 0, up: 0, flurry: 0 };
-function maneuverAt(spec, index, tSec, rate, intensity) {
+var IDLE = { along: 0, alongBump: 0, side: 0, up: 0, flurry: 0, pitch: 0 };
+function maneuverAt(spec, index, tSec, rate, intensity, seatDelay = null) {
   if (!spec || rate <= 0 || intensity <= 0 || tSec < 0) return IDLE;
-  const interval = spec.interval * (3 - 2 * Math.min(1, rate));
+  const interval = rate <= 1 ? spec.interval * (3 - 2 * rate) : Math.max(spec.dur * 1.15, spec.interval / rate);
   const k0 = Math.floor(tSec / interval);
   let along = 0;
   let side = 0;
   let up = 0;
   let flurry = 0;
+  let pitch = 0;
   let alongBump = 0;
   const done = Math.max(0, k0 - 1);
-  along += done * spec.advance * intensity;
+  const perm = 0.6 + 0.8 * fishHash(index, 37);
+  along += done * spec.advance * intensity * perm;
   for (const k of [k0 - 1, k0, k0 + 1]) {
     if (k < 0) continue;
-    const start = (k + fishHash(index, 11 + k)) * interval;
+    const wave = spec.contagious && seatDelay !== null;
+    const jitter = wave ? fishHash(1013, 11 + k) : fishHash(index, 11 + k);
+    const start = (k + jitter) * interval + (wave ? seatDelay : 0);
     const u = (tSec - start) / spec.dur;
     if (u <= 0) continue;
     if (u >= 1) {
-      if (k >= done) along += spec.advance * intensity;
+      if (k >= done) along += spec.advance * intensity * perm;
       continue;
     }
     const sign = fishHash(index, 23 + k) < 0.5 ? -1 : 1;
     const env = bump(u) * intensity;
-    along += spec.advance * surges(u, spec.bursts) * intensity;
+    along += spec.advance * surges(u, spec.bursts) * intensity * perm;
     alongBump += spec.advance * bump(u) * intensity;
     side += sign * spec.kick * env;
     up += spec.lift * spec.kick * env;
     flurry += spec.flurry * env;
+    pitch += spec.pitch * env;
   }
-  return { along, alongBump, side, up, flurry };
+  return { along, alongBump, side, up, flurry, pitch };
 }
 
 // src/asset-cids.ts
@@ -1095,10 +1197,59 @@ var NPC_CATALOG = [
 function parseFishMix(mix, catalog = FISH_CATALOG) {
   const entries = [];
   const problems = [];
+  const unique = catalog === FISH_CATALOG;
+  const used = /* @__PURE__ */ new Set();
+  const resolvesAsToken = (core) => {
+    const [idRaw, countRaw, ...extra] = core.split(":");
+    if (extra.length > 0) return false;
+    if (countRaw !== void 0) {
+      const count = Number(countRaw.trim());
+      if (!Number.isInteger(count) || count < 1) return false;
+    }
+    const key = (idRaw ?? "").trim().toLowerCase();
+    if (/^\d+$/.test(key)) {
+      if (catalog.some((fish) => fish.id === Number(key))) return true;
+      return catalog === FISH_CATALOG && fishAsset(Number(key), "3d") !== null && breedOf(Number(key)) !== null;
+    }
+    return catalog.some((fish) => fish.breed.toLowerCase() === key);
+  };
+  const allocate = (breed, want) => {
+    const b = BREEDS.find((x) => x.breed === breed);
+    if (!b?.range) return null;
+    const [lo, hi] = b.range;
+    if (!used.has(want) && want >= lo && want <= hi) {
+      used.add(want);
+      return want;
+    }
+    for (let d = 1; d <= hi - lo; d += 1) {
+      for (const cand of [want + d, want - d]) {
+        if (cand >= lo && cand <= hi && !used.has(cand)) {
+          used.add(cand);
+          return cand;
+        }
+      }
+    }
+    return null;
+  };
   for (const rawToken of mix.split(",")) {
     const token = rawToken.trim();
     if (token === "") continue;
-    const [idRaw, countRaw, ...extra] = token.split(":");
+    let style;
+    let core = token;
+    const at = token.lastIndexOf("@");
+    if (at >= 0) {
+      const styleRaw = token.slice(at + 1).trim().toLowerCase();
+      const styledCore = token.slice(0, at).trim();
+      if (resolvesAsToken(token)) {
+      } else if (SWIM_STYLE_NAMES.includes(styleRaw)) {
+        core = styledCore;
+        style = styleRaw;
+      } else if (resolvesAsToken(styledCore)) {
+        core = styledCore;
+        problems.push(`"${token}": unknown style "${styleRaw}" (${SWIM_STYLE_NAMES.join(", ")}) \u2014 swimming with the scene's swimStyle`);
+      }
+    }
+    const [idRaw, countRaw, ...extra] = core.split(":");
     if (extra.length > 0) {
       problems.push(`"${token}": too many ':' \u2014 expected id[:count]`);
       continue;
@@ -1108,8 +1259,8 @@ function parseFishMix(mix, catalog = FISH_CATALOG) {
     if (!fish && catalog === FISH_CATALOG && /^\d+$/.test(key)) {
       const n = Number(key);
       const url2 = fishAsset(n, "3d");
-      const breed = breedOf(n);
-      if (url2 && breed) fish = { id: n, name: `Fish ${n}`, breed, ipfs3d: url2, localGlb: "" };
+      const breed2 = breedOf(n);
+      if (url2 && breed2) fish = { id: n, name: `Fish ${n}`, breed: breed2, ipfs3d: url2, localGlb: "" };
     }
     if (!fish) {
       const breeds = [...new Set(catalog.map((f) => f.breed))].join(", ");
@@ -1137,16 +1288,48 @@ function parseFishMix(mix, catalog = FISH_CATALOG) {
         count = n;
       }
     }
-    entries.push({ id: fish.id, url, count });
+    if (!unique || fish.id > TOTAL_SUPPLY) {
+      entries.push({ id: fish.id, breed: fish.breed, url, count, ...style ? { style } : {} });
+      continue;
+    }
+    const breed = breedOf(fish.id);
+    if (!breed) {
+      entries.push({ id: fish.id, breed: fish.breed, url, count, ...style ? { style } : {} });
+      continue;
+    }
+    const isAlias = !/^\d+$/.test(key);
+    const b = BREEDS.find((x) => x.breed === breed);
+    for (let i = 0; i < count; i += 1) {
+      const want = isAlias && b?.range ? b.range[0] + Math.floor((b.range[1] - b.range[0]) * i / Math.max(1, count)) : fish.id;
+      const got = allocate(breed, want);
+      if (got === null) {
+        problems.push(`"${token}": only ${i} distinct ${breed} left \u2014 a minted fish appears once per scene`);
+        break;
+      }
+      if (!isAlias && i === 0 && got !== fish.id) {
+        problems.push(`fish ${fish.id} already cast \u2014 fish ${got} swims instead`);
+      }
+      const gotUrl = fishAsset(got, "3d");
+      if (!gotUrl) {
+        problems.push(`fish ${got}: no asset URL`);
+        continue;
+      }
+      entries.push({ id: got, breed: fish.breed, url: gotUrl, count: 1, ...style ? { style } : {} });
+    }
   }
   return { entries, problems };
 }
 function expandFishMix(entries, cap) {
-  const urls = [];
+  return expandFishMixSlots(entries, cap).map((s) => s.url);
+}
+function expandFishMixSlots(entries, cap) {
+  const slots = [];
   for (const e of entries) {
-    for (let i = 0; i < e.count && urls.length < cap; i++) urls.push(e.url);
+    for (let i = 0; i < e.count && slots.length < cap; i++) {
+      slots.push(e.style ? { url: e.url, breed: e.breed, style: e.style } : { url: e.url, breed: e.breed });
+    }
   }
-  return urls;
+  return slots;
 }
 
 // src/manifest.ts
@@ -1173,9 +1356,15 @@ var METAQUARIUM_PARAMS = {
   fishUrl: { type: "string", default: "ipfs://QmaHbEQAP6k2zopJHJBzyaK62zNX5yH8yASDjkaG4DY9Dp/fish_257_of_the_metaquarium_3d.glb" },
   /** Mixed population DSL: comma-separated `id[:count]` of a minted token id
    *  (1-512, default catalog) or breed name — e.g. "257:3,100:2,seaturtle:1".
-   *  A custom catalog is a closed world (no farm/IPFS fallback). Counts are
+   *  A minted fish is an INDIVIDUAL: no id appears twice in a scene, and a
+   *  count casts that many DISTINCT fish of the breed ("300:12" is twelve
+   *  different angelfish). A custom catalog is a closed world (no farm/IPFS
+   *  fallback, no uniqueness — NPC entries are species). Counts are
    *  absolute; the expanded total clamps to the device tier's fish cap.
-   *  Non-empty mix OVERRIDES fishUrl and fishCount; empty string = single-
+   *  A token may carry its own swim style — `id[:count]@style`, e.g.
+   *  "457:3@hover,257:6@school,497:1@surface" — so one tank holds several
+   *  behaviours; untagged tokens follow `swimStyle`. Non-empty mix
+   *  OVERRIDES fishUrl and fishCount; empty string = single-
    *  breed mode. Unknown ids/bad counts degrade (good tokens still parse);
    *  raw URLs are not accepted here — use fishUrl for a custom single-breed GLB. */
   fishMix: { type: "string", default: "", ease: "step" },
@@ -1217,15 +1406,23 @@ var METAQUARIUM_PARAMS = {
   rayStrength: { type: "number", default: -1, min: -1, max: 1, ease: "step" },
   /** How the fish move. `loop` is exactly the pre-style behaviour, so the
    *  default changes nothing. A small named set on purpose: a silhouette of
-   *  movement you can name is one you can choose from. */
-  swimStyle: { type: "enum", default: "loop", options: [...SWIM_STYLE_NAMES], ease: "step" },
+   *  movement you can name is one you can choose from. `auto` lets each
+   *  untagged fishMix token swim the way its breed does (seahorse hover,
+   *  turtle skim the surface, angelfish school, betafish drift); a token's
+   *  `@style` still wins. The relationship styles — `follow`, `pair`,
+   *  `chase` — bond a fish to the nearest preceding unbonded fish in the mix
+   *  (`seaturtle:1, 257:3@follow` is a turtle with an escort). */
+  swimStyle: { type: "enum", default: "loop", options: [...SWIM_STYLE_NAMES, "auto"], ease: "step" },
   /** The shape a fish's loop is drawn on. `wander` is the original roaming
    *  itinerary, so the default changes nothing. `orbit` laps, `eight` crosses
-   *  the middle, `helix` tours the water column, `canyon` sweeps low — same
-   *  spline engine, different itinerary. */
+   *  the middle, `helix` tours the water column, `canyon` sweeps low,
+   *  `crossing` is a camera-relative parade lane (across the frame in front,
+   *  back the other way behind; laid against cameraAzimuth when chosen) —
+   *  same spline engine, different itinerary. */
   pathShape: { type: "enum", default: "wander", options: [...PATH_SHAPES], ease: "step" },
   /** How a `school` holds together: the original lattice, single file, a
-   *  carousel ring, the migratory V, or a bait-ball. Ignored by every
+   *  carousel ring, the migratory V, a bait-ball, or the ring tilted into a
+   *  `wheel` that reads from a side camera. Ignored by every
    *  non-formation style; the same no-pair-inside-a-body-length law holds
    *  for all of them. */
   formationShape: { type: "enum", default: "phalanx", options: [...FORMATION_SHAPES], ease: "step" },
@@ -1239,8 +1436,9 @@ var METAQUARIUM_PARAMS = {
    *  addressable. `none` (default) changes nothing. */
   maneuver: { type: "enum", default: "none", options: [...MANEUVERS], ease: "step" },
   /** How often events fire: 0 never, 1 the maneuver's own tempo (roughly
-   *  every 14-20s per fish, desynchronised). */
-  maneuverRate: { type: "number", default: 0.5, min: 0, max: 1, ease: "smooth" },
+   *  every 14-20s per fish, desynchronised), above 1 faster — 3 packs events
+   *  nearly back to back. Values <=1 mean exactly what they always did. */
+  maneuverRate: { type: "number", default: 0.5, min: 0, max: 3, ease: "smooth" },
   /** How hard: scales the surge, the kick, and the tail flurry together. */
   maneuverIntensity: { type: "number", default: 0.7, min: 0, max: 1, ease: "smooth" },
   /** Procedural body yaw for models that carry NO animation clip — most of
@@ -1253,7 +1451,18 @@ var METAQUARIUM_PARAMS = {
    *  behaviour, and a scene already on someone's wall should not start moving
    *  differently because a dependency was bumped. 0.3–0.4 is the recommended
    *  value for a clip-less cast — the studio swim variants all set it. */
-  bodyWiggle: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" }
+  bodyWiggle: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" },
+  /** Light-seeking: free-swimming fish are drawn toward the room's light
+   *  shafts, each fish to its own pool. 0 (default) leaves every route
+   *  where it was; 1 pulls a fish most of the way into its shaft, so the
+   *  cast gathers in the light and a `rayStrength` dial becomes a staging
+   *  dial too. Needs a room with rays; formations are steered by their
+   *  carrier and ignore it. */
+  lightSeek: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" },
+  /** Formation breathing: the school relaxes outward and draws back in on a
+   *  slow (~15 s) cycle. 0 (default) is the rigid lattice; 1 opens it by up
+   *  to a fifth. Only ever expands, so the spacing guarantee holds. */
+  formationBreathe: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" }
 };
 var MIAMI_VICE_COLORS = [
   "#ff6ad5",
@@ -1351,14 +1560,20 @@ export {
   RAY_COUNT,
   affordableLayers,
   SWIM_STYLES,
+  AUTO_STYLE_BY_BREED,
+  autoStyleFor,
+  formationBreathe,
+  idleSway,
   SWIM_STYLE_NAMES,
   swimStyleOf,
   fishHash,
   fishVariation,
+  anchorFraction,
   FISH_LENGTH,
   FORMATION_SHAPES,
   formationSlot,
   formationExtent,
+  fitBreath,
   bandRange,
   PATH_SHAPES,
   compileSwimPlan,
@@ -1386,6 +1601,7 @@ export {
   NPC_CATALOG,
   parseFishMix,
   expandFishMix,
+  expandFishMixSlots,
   METAQUARIUM_PARAMS,
   MIAMI_VICE_COLORS,
   BLOOM_COLORS,
@@ -1394,4 +1610,4 @@ export {
   paramSpaceWith,
   coerceNum
 };
-//# sourceMappingURL=chunk-23P73MYY.js.map
+//# sourceMappingURL=chunk-RTUYWDDZ.js.map