@bitefoundry/retrieviewer 0.0.0-stage → 0.0.1

package/vendor/procedural-animals/src/species/eagle/sculpt.js

@@ -0,0 +1,137 @@
+// The eagle sculpted as a signed distance field (the feathered silhouette: contour feathers are part
+// of the body shape; flight feathers are cards, see core/build/featherCards.js). Every primitive is
+// attached to a bone and a group (axial / legL / wingL / jaw). The torso is laid out in the upright
+// body-axis frame (rig.js AX); the head in head-local coordinates (HEAD_O, between the eyes).
+import { HEAD_O, NECK_SEGS, AX, U_AX, TILT } from './rig.js';
+import { add, sub, mul, lerp, norm, cross, dot } from '../../core/math/vec.js';
+import { sculptEyeSocket } from '../../core/sdf/eyeSocket.js';
+
+// Eye (head-local, left): large, set under the supraorbital shelf, fairly forward (yaw 52 deg: raptor
+// binocular overlap), visible iris ~15 mm, round aperture slightly flattened from above.
+export const EYE = { c: [0.0242, 0.0, 0.004], r: 0.0118, back: 0.0038, yaw: 0.9, pitch: 0.06, lid: 0.0014, R: 0.0096, d: 0.0012, off: -0.0005, tilt: 0.12, irisZ: 0.0074, irisR: 0.0082 };
+
+const hl = (v) => [v[0] + HEAD_O[0], v[1] + HEAD_O[1], v[2] + HEAD_O[2]];
+const rad = (d) => (d * Math.PI) / 180;
+const axisAt = (deg) => [0, Math.sin(rad(deg)), Math.cos(rad(deg))];
+
+export function sculptEagle(m, rig, params = {}) {
+  const J = rig.J;
+  const booted = params.variant === 'golden';
+  const ellY = (o) => {
+    const y = norm(o.ydir);
+    let x = o.xdir || [1, 0, 0];
+    x = norm(sub(x, mul(y, dot(x, y))));
+    const z = cross(x, y);
+    return m.ell({ ...o, axis: z, up: y });
+  };
+  const A = { bone: 'chest' }, Pv = { bone: 'pelvis' };
+  const tilt = U_AX;
+
+  // ---------------------------------------------------------------- TORSO (feathered)
+  // A streamlined spindle in the body-axis frame (AX: a along the axis, b dorsal): deepest at the breast
+  // under the wing roots, the belly and flanks tapering into the tail. Depth ~0.19 m and width ~0.16 m
+  // at the breast (a 4-6 kg bird: ~6 L torso with its feathers; flight photos:
+  // body depth ~0.18-0.2 of the bill-to-tail length, the back flat, the belly line rising to the vent).
+  m.ell({ ...A, tag: 'breast', c: AX(0.13, -0.02), r: [0.077, 0.074, 0.135], axis: tilt, k: 0 });
+  m.ell({ ...A, tag: 'mantle', c: AX(0.08, 0.032), r: [0.076, 0.058, 0.15], axis: tilt, k: 0.04 });
+  m.ell({ ...Pv, tag: 'belly', c: AX(-0.01, -0.03), r: [0.062, 0.058, 0.13], axis: axisAt(TILT - 8), k: 0.04 });
+  m.ell({ ...Pv, tag: 'rump', c: AX(-0.07, 0.03), r: [0.052, 0.046, 0.085], axis: axisAt(TILT - 6), k: 0.035 });
+  const td = norm(sub(J.tailTip, J.tailBase));
+  m.ell({ bone: 'tail', tag: 'undertail', c: add(J.tailTip, [0, -0.018, 0.01]), r: [0.038, 0.026, 0.1], axis: mul(td, -1), k: 0.03 });
+  m.ell({ bone: 'tail', tag: 'uppertail', c: add(J.tailTip, [0, 0.012, -0.004]), r: [0.038, 0.018, 0.07], axis: mul(td, -1), k: 0.024 });
+  for (const s of [1, -1]) {
+    m.ell({ ...Pv, tag: 'flankfold', c: AX(0.01, -0.036, 0.042 * s), r: [0.032, 0.054, 0.1], axis: tilt, k: 0.04 });
+    m.ell({ ...A, tag: 'scapular', c: AX(0.13, 0.045, 0.05 * s), r: [0.036, 0.028, 0.11], axis: tilt, k: 0.032 });
+  }
+
+  // ---------------------------------------------------------------- NECK (thick, hackled)
+  const nj = ['neckBase', ...Array.from({ length: NECK_SEGS - 1 }, (_, i) => 'neck' + (i + 1)), 'occiput'];
+  const nr = nj.map((_, i) => { const u = i / NECK_SEGS; return 0.054 - 0.012 * Math.pow(u, 0.8); });
+  for (let i = 0; i < NECK_SEGS; i++) m.cone({ bone: 'neck' + i, tag: 'neck', a: J[nj[i]], b: J[nj[i + 1]], ra: nr[i], rb: nr[i + 1], k: 0.04 });
+  // (neck landmarks by fraction of the neck: throat ~40 %, nape ~60 %)
+  const nAt = (f) => { const x = f * NECK_SEGS, i = Math.min(NECK_SEGS - 1, Math.floor(x)); return { bone: 'neck' + i, p: lerp(J[nj[i]], J[nj[i + 1]], x - i) }; };
+  const th = nAt(0.4), np = nAt(0.6);
+  m.ell({ bone: th.bone, tag: 'throat', c: add(th.p, [0, -0.004, 0.024]), r: [0.04, 0.05, 0.034], axis: norm([0, 0.6, 1]), k: 0.04 });
+  m.ell({ bone: np.bone, tag: 'nape', c: add(np.p, [0, 0.01, -0.026]), r: [0.04, 0.046, 0.038], k: 0.04 });
+
+  // ---------------------------------------------------------------- HEAD (head-local, see HEAD_O)
+  // landmarks from face1 / face2 (profile): eyes at (+-0.0235, 0, 0.004), crown 0.04 above the eyes,
+  // occiput (0, -0.026, -0.058), cere 0.03-0.052 ahead of the eye, hook tip (0, -0.036, 0.104)
+  const H = { bone: 'head' };
+  m.ell({ ...H, tag: 'cranium', c: hl([0, -0.005, -0.028]), r: [0.035, 0.032, 0.05], k: 0.02 });
+  m.ell({ ...H, tag: 'crown', c: hl([0, 0.013, -0.006]), r: [0.026, 0.012, 0.042], axis: norm([0, -0.12, 1]), k: 0.016 });
+  m.ell({ ...H, tag: 'hackles', c: hl([0, -0.008, -0.062]), r: [0.034, 0.03, 0.032], k: 0.02 });
+  m.ell({ ...H, tag: 'forehead', c: hl([0, 0.014, 0.022]), r: [0.019, 0.015, 0.024], axis: norm([0, -0.35, 1]), k: 0.012 });
+  m.ell({ ...H, tag: 'chin', c: hl([0, -0.034, -0.012]), r: [0.026, 0.024, 0.044], axis: norm([0, 0.15, 1]), k: 0.02 });
+  for (const s of [1, -1]) {
+    m.ell({ ...H, tag: 'cheek', c: hl([0.019 * s, -0.016, -0.008]), r: [0.017, 0.02, 0.032], k: 0.014 });
+    m.ell({ ...H, tag: 'lore', c: hl([0.013 * s, -0.008, 0.026]), r: [0.011, 0.013, 0.02], axis: norm([0, -0.1, 1]), k: 0.01 });
+    // supraorbital ridge: a hard shelf over the front of the eye (the fierce frown)
+    ellY({ ...H, tag: 'brow', c: hl([0.0225 * s, 0.0138, 0.01]), ydir: [0.25 * s, 1, 0.12], xdir: [1, 0, 0], r: [0.0095, 0.0055, 0.023], k: 0.005 });
+    sculptEyeSocket(m, EYE, HEAD_O, s, { bone: 'head' });
+  }
+  // upper mandible: deep at the base, laterally compressed, culmen curving into a strong hook; the
+  // cere (bare waxy skin with the nostril) covers its base
+  m.ell({ ...H, tag: 'cere', c: hl([0, 0.003, 0.036]), r: [0.0148, 0.0135, 0.016], axis: norm([0, -0.1, 1]), k: 0.008 });
+  m.ell({ ...H, tag: 'bill', c: hl([0, -0.0095, 0.055]), r: [0.0128, 0.0205, 0.036], axis: norm([0, -0.1, 1]), k: 0.008 });
+  m.ell({ ...H, tag: 'bill', c: hl([0, -0.012, 0.082]), r: [0.0095, 0.018, 0.021], axis: norm([0, -0.45, 1]), k: 0.008 });
+  m.ell({ ...H, tag: 'bill', c: hl([0, -0.02, 0.1]), r: [0.0074, 0.016, 0.012], axis: norm([0, -0.95, 0.3]), k: 0.006 });
+  m.cone({ ...H, tag: 'bill', a: hl([0, -0.029, 0.1055]), b: hl([0, -0.0465, 0.108]), ra: 0.006, rb: 0.0012, k: 0.004 });
+  for (const s of [1, -1]) m.ell({ ...H, tag: 'nostril', c: hl([0.0118 * s, 0.003, 0.044]), r: [0.003, 0.0028, 0.005], axis: norm([0, 0.2, 1]), k: 0.002, carve: true });
+  // lower mandible (own surface so the bill can open), tucked inside the hook
+  const Jw = { bone: 'jaw', part: 'jaw' };
+  m.ell({ ...Jw, tag: 'mandible', c: hl([0, -0.035, 0.045]), r: [0.0125, 0.0072, 0.046], axis: norm([0, -0.08, 1]), k: 0.006 });
+  m.cone({ ...Jw, tag: 'mandible', a: hl([0, -0.036, 0.072]), b: hl([0, -0.0395, 0.095]), ra: 0.007, rb: 0.0018, k: 0.005 });
+  m.ell({ ...Jw, tag: 'gonys', c: hl([0, -0.039, 0.02]), r: [0.016, 0.008, 0.03], k: 0.008 });
+
+  // ---------------------------------------------------------------- LEGS
+  for (const s of [1, -1]) {
+    const S = s > 0 ? 'L' : 'R', g = 'leg' + S;
+    const j = (n) => J[n + S];
+    const kn = j('knee'), an = j('ankle'), mt = j('mtp');
+    // feathered "trousers": long loose tibial feathers hanging over the ankle
+    ellY({ bone: 'tibia' + S, group: g, tag: 'thigh', c: lerp(kn, an, 0.25), ydir: sub(an, kn), r: [0.036, 0.058, 0.032], k: 0.04 });
+    m.cone({ bone: 'tibia' + S, group: g, tag: 'trousers', a: lerp(kn, an, 0.3), b: lerp(kn, an, 0.96), ra: 0.029, rb: 0.021, k: 0.02 });
+    if (booted) {
+      // golden eagle: feathered to the toes
+      m.cone({ bone: 'tarsus' + S, group: g, tag: 'boot', a: lerp(an, mt, 0.05), b: lerp(an, mt, 0.66), ra: 0.017, rb: 0.0115, k: 0.006 });
+    } else {
+      m.cone({ bone: 'tarsus' + S, group: g, tag: 'cuff', a: an, b: lerp(an, mt, 0.42), ra: 0.02, rb: 0.0135, k: 0.01 });
+    }
+    m.cone({ bone: 'tarsus' + S, group: g, tag: 'tarsus', a: an, b: mt, ra: 0.0115, rb: 0.0098, k: 0.006 });
+    m.sphere({ bone: 'tarsus' + S, group: g, tag: 'pad', c: add(mt, [0, -0.001, 0.003]), rad: 0.0105, k: 0.005 });
+    for (const t of [1, 2, 3, 4]) {
+      const a = mt, b = J[`t${t}m${S}`], c = J[`t${t}t${S}`];
+      const big = t === 1 || t === 2; // hallux and inner toe carry the largest talons
+      const r0 = t === 1 ? 0.0105 : 0.0092;
+      m.cone({ bone: `toe${t}a${S}`, group: g, tag: 'toe', a, b, ra: r0, rb: 0.0082, k: 0.005 });
+      m.cone({ bone: `toe${t}b${S}`, group: g, tag: 'toe', a: b, b: lerp(b, c, 0.5), ra: 0.0082, rb: 0.0068, k: 0.004 });
+      // talon: thick at the base, strongly curved down to a needle point
+      const q0 = add(lerp(b, c, 0.42), [0, 0.004, 0]), q1 = add(lerp(b, c, 0.78), [0, 0.0035, 0]), q2 = add(c, [0, -0.0035, 0]);
+      const tr = big ? 0.0062 : 0.0054;
+      m.cone({ bone: `toe${t}b${S}`, group: g, tag: 'claw', a: q0, b: q1, ra: tr, rb: tr * 0.62, k: 0.002 });
+      m.cone({ bone: `toe${t}b${S}`, group: g, tag: 'claw', a: q1, b: q2, ra: tr * 0.62, rb: 0.0008, k: 0.0015 });
+    }
+  }
+
+  // ---------------------------------------------------------------- WINGS (arm; flight feathers are cards)
+  for (const s of [1, -1]) {
+    const S = s > 0 ? 'L' : 'R', g = 'wing' + S;
+    const sh = J['shoulder' + S], el = J['elbow' + S], wr = J['wrist' + S], tp = J['handTip' + S];
+    let n = norm(cross(sub(el, sh), sub(wr, el)));
+    if (n[1] < 0) n = mul(n, -1);
+    const seg = (a, b, bone, thick, chord, back, tag, k = 0.016) => {
+      const d = norm(sub(b, a));
+      const t = mul(norm(cross(n, d)), s); // trailing side
+      const c = add(lerp(a, b, 0.5), mul(t, back));
+      return ellY({ bone, group: g, tag, c, ydir: d, xdir: n, r: [thick, Math.hypot(...sub(b, a)) * 0.58, chord], k });
+    };
+    seg(sh, el, 'humerus' + S, 0.019, 0.05, 0.018, 'arm', 0.024);
+    seg(el, wr, 'ulna' + S, 0.015, 0.052, 0.022, 'arm');
+    seg(wr, tp, 'hand' + S, 0.012, 0.026, 0.008, 'hand', 0.012);
+    // leading-edge roll (propatagium) along the forearm: on the ulna only, so it stays on the arm
+    // when the elbow opens (a web spanning shoulder -> wrist would swing forward as a loop)
+    seg(lerp(el, wr, 0.08), wr, 'ulna' + S, 0.011, 0.016, -0.02, 'patagium', 0.014);
+    m.sphere({ bone: 'hand' + S, group: g, tag: 'wrist', c: wr, rad: 0.0135, k: 0.012 });
+  }
+}

package/vendor/procedural-animals/src/species/fish/coat.js

@@ -0,0 +1,271 @@
+// Fish coat: scales (material 6, with iridescence) on the body, smooth glossy skin on the scaleless
+// head, fins as translucent membranes (material 11: ray phase / position along the ray / opacity in
+// `surf`), variant colour schemes (trout spots and pink band, goldfish metallic orange and sarasa
+// patches, clownfish bands with black edging, bluegill bars, ear flap and breast), mouth and gills.
+import { SDFModel } from '../../core/sdf/sdf.js';
+import { finRayCoords } from '../../core/rig/swimmer.js';
+import { norm, sub, dot, cross, clamp, smoothstep, mix, rng, fbm3 } from '../../core/math/vec.js';
+import { srgb, mix3, MAT, poissonFeatures, featureDistance, smoothField } from '../../core/build/coatKit.js';
+import { fishGeo } from './rig.js';
+import { CELL, opEdgeU } from './sculpt.js';
+
+const FIN_MAT = MAT.FIN ?? 11;
+
+export function fishCoat(ctx) {
+  const { model, pos, nrm, nV, lists, regionOf, regionNames, params, weights } = ctx;
+  const G = fishGeo(params);
+  const V = G.V, SL = G.SL, H = V.head;
+  const key = params.variant;
+  const R = rng(4049 + (params.coatSeed || 0));
+  const col = {};
+  for (const [k, hex] of Object.entries(V.colour)) col[k] = srgb(hex);
+  const morph = params.morph || '';
+  const shade = params.coatShade || 0;
+  const tweak = (c, k = 1) => [c[0] * (1 + shade * 0.12 * k), c[1] * (1 + shade * 0.08 * k), c[2] * (1 + shade * 0.04 * k)];
+  const cell = SL * CELL * (V.cellK || 1);
+
+  const comb = new Float32Array(nV * 3);
+  const tint = new Float32Array(nV * 4);
+  const pattern = new Float32Array(nV).fill(1);
+  const patternColor = new Float32Array(nV * 4);
+  const mark = new Float32Array(nV).fill(1);
+  const furLen = new Float32Array(nV);
+  const surf = new Float32Array(nV * 4);
+  const kind = new Uint8Array(nV); // 0 body, 1 head, 2 fin, 5 adipose, 6 jaw, 7 ear flap, 8 buccal cavity, 9 lips' cut faces
+  const finInfo = new Array(nV);
+  const jawRegion = regionNames.indexOf('jaw');
+
+  for (let v = 0; v < nV; v++) {
+    const p = [pos[v * 3], pos[v * 3 + 1], pos[v * 3 + 2]];
+    const n = [nrm[v * 3], nrm[v * 3 + 1], nrm[v * 3 + 2]];
+    let best = null, bd = 1e9, carveHit = null;
+    for (const pr of lists[v]) {
+      const d = SDFModel.dist(pr, p[0], p[1], p[2]);
+      if (pr.carve) { if (Math.abs(d) < cell * 0.9 && (!carveHit || Math.abs(d) < carveHit.d)) carveHit = { pr, d: Math.abs(d) }; continue; }
+      if (d < bd) { bd = d; best = pr; }
+    }
+    const u = G.u(p[2]);
+    const u1 = clamp(u, 0, 1), e1 = (p[1] - G.yc(u1)) / Math.max(1e-6, G.hd(u1));
+    // head (scaleless) in front of the gill cover's free edge, scaled body behind it
+    let k = u < opEdgeU(H.op, clamp(e1, -1.2, 1.2)) ? 1 : 0;
+    if (regionOf[v] === jawRegion) k = 6;
+    if (best && (best.tag === 'fin')) { k = 2; finInfo[v] = { prim: best, rc: finRayCoords(best.fin, p) }; }
+    if (best && best.tag === 'adipose') k = 5;
+    if (carveHit) {
+      const tg = carveHit.pr.tag;
+      if ((tg === 'mouthcut' && n[1] < -0.25) || (tg === 'jawcut' && n[1] > 0.3)) k = 9;
+      else if (tg === 'mouth') k = 8;
+    }
+    if (best && best.tag === 'earflap') k = 7;
+    kind[v] = k;
+    void n;
+  }
+
+  // ---- spots (trout on the body and on the dorsal / adipose / caudal fins; bluegill dorsal blotch)
+  let spotsF = null;
+  if (key === 'trout' || morph === 'sarasa') {
+    const sarasa = morph === 'sarasa';
+    spotsF = poissonFeatures({
+      pos, nrm, nV, R,
+      radius: (v) => {
+        const k = kind[v];
+        const y = pos[v * 3 + 1], u = G.u(pos[v * 3 + 2]);
+        if (sarasa) {
+          if (k !== 0 && k !== 1) return 0;
+          return 0.07 * SL;
+        }
+        if (k === 2) {
+          const fi = finInfo[v];
+          const nm = fi.prim.fin.name;
+          if (!(nm.startsWith('dorsal') || nm === 'caudal')) return 0;
+          return 0.0075 * SL;
+        }
+        if (k !== 0 && k !== 5 && k !== 1) return 0;
+        const e = (y - G.yc(u)) / G.hd(u);
+        const dens = smoothstep(-0.35, 0.25, e) * (u < 0.1 ? 0 : 1);
+        return dens > 0.2 ? (0.0042 + 0.003 * dens) * SL * (params.spotScale || 1) : 0;
+      },
+      spacing: sarasa ? 1.4 : 1.9, gap: sarasa ? 0.01 * SL : 0.003 * SL, cell: sarasa ? 0.12 * SL : 0.03 * SL,
+    });
+  }
+
+  for (let v = 0; v < nV; v++) {
+    const o3 = v * 3, o4 = v * 4;
+    const p = [pos[o3], pos[o3 + 1], pos[o3 + 2]];
+    const n = [nrm[o3], nrm[o3 + 1], nrm[o3 + 2]];
+    const k = kind[v];
+    const u = clamp(G.u(p[2]), 0, 1.3);
+    const uc = Math.min(u, 1);
+    const e = (p[1] - G.yc(uc)) / Math.max(1e-6, G.hd(uc));
+    const noise = fbm3(p[0] * 9 / SL, p[1] * 9 / SL, p[2] * 9 / SL, 3) - 0.5;
+    let c, mat = MAT.SCALES, gl = V.gloss, sz = V.scale * SL, irid = V.irid, sw = 0;
+    let cm = norm(sub([0, 0, -1], mul(n, -n[2])));
+    if (k === 2) {
+      // ---------------- fin membrane
+      const { prim, rc } = finInfo[v];
+      const nm = prim.fin.name;
+      cm = rc.dir;
+      mat = FIN_MAT;
+      c = mix3(col.fin, col.finEdge, 0);
+      let opac = key === 'clownfish' ? 0.86 : key === 'bluegill' ? 0.7 : key === 'goldfish' ? 0.55 : 0.6;
+      const along = rc.along;
+      c = mix3(c, mix3(c, col.back, 0.4), smoothstep(0.5, 0.0, along) * 0.5);
+      if (key === 'trout') {
+        // white leading edge on the pelvic and anal fins, olive elsewhere
+        if (nm.startsWith('pelvic') || nm === 'anal') {
+          const lead = nm === 'anal' ? rc.phase < 1.2 : rc.phase < 1.2;
+          if (lead) c = mix3(c, col.finEdge, 0.85);
+          if (nm.startsWith('pelvic') || nm === 'anal') c = mix3(c, srgb(0xb58a6a), 0.3);
+        }
+      } else if (key === 'goldfish') {
+        c = mix3(col.fin, col.finEdge, smoothstep(0.3, 1, along));
+      } else if (key === 'clownfish') {
+        // black margins: the outer band of every fin
+        const rayLen = 1;
+        void rayLen;
+        const margin = nm.startsWith('pectoral') ? 0.0 : 0.13 * (params.edgeK ?? 1);
+        if (margin > 0) mark[v] = (1 - along - margin) * 0.2 * SL;
+      } else if (key === 'bluegill') {
+        if (nm === 'dorsal1') {
+          // dark blotch at the rear of the soft dorsal fin
+          const ph = rc.phase / Math.max(1, prim.fin.rays.length - 1);
+          const d = Math.hypot((ph - 0.88) * 0.55, (along - 0.32) * 0.45) - 0.16;
+          pattern[v] = d * 0.1 * SL;
+          patternColor.set([...srgb(0x1e1e18), 0.9], o4);
+        }
+        if (nm.startsWith('pelvic') || nm === 'anal') c = mix3(c, srgb(0x3c3a2c), 0.5);
+      }
+      if (morph === 'black' && key === 'clownfish') c = mix3(c, srgb(0x2a160c), 0.7);
+      c = tweak(c, 0.5);
+      sw = opac * (0.92 + 0.16 * noise);
+      surf[o4] = 0.75; surf[o4 + 1] = rc.phase; surf[o4 + 2] = along; surf[o4 + 3] = sw;
+      if (spotsF && (nm.startsWith('dorsal') || nm === 'caudal')) {
+        const [d] = featureDistance(spotsF, p, n);
+        pattern[v] = d; patternColor.set([...col.spot, 1], o4);
+      }
+      tint.set([c[0], c[1], c[2], mat], o4);
+      comb.set(cm, o3);
+      continue;
+    }
+    if (k === 8) {
+      // buccal cavity (seen only when the mouth opens): dark, moist red-brown, not a black hole
+      c = srgb(0x4a2622);
+      tint.set([c[0], c[1], c[2], MAT.SKIN], o4);
+      comb.set(cm, o3);
+      surf.set([0.6, 0, 0, 0], o4);
+      continue;
+    }
+    // ---------------- body, head, jaw, adipose
+    const up = smoothstep(-0.2, 0.9, e * 0.8 + n[1] * 0.35);
+    const lowK = smoothstep(0.2, -0.85, e * 0.85 + n[1] * 0.25);
+    if (key === 'trout') {
+      c = mix3(col.lower, col.upper, smoothstep(-0.35, 0.3, e));
+      c = mix3(c, col.back, smoothstep(0.35, 0.95, up));
+      c = mix3(c, col.belly, smoothstep(0.4, 0.95, lowK));
+      // the pink lateral band from the gill cover to the tail (and a flush on the cheek)
+      const band = (1 - smoothstep(0.1, 0.34, Math.abs(e - 0.02))) * smoothstep(0.16, 0.3, u) * (params.bandK ?? 1);
+      c = mix3(c, col.band, band * 0.55);
+      if (k === 1 || k === 6) {
+        const cheek = (1 - smoothstep(0.2, 0.7, Math.abs(e + 0.1))) * smoothstep(0.1, 0.2, u);
+        c = mix3(mix3(c, col.head, 0.25), col.cheek, cheek * 0.6 * (params.bandK ?? 1));
+      }
+    } else if (key === 'goldfish') {
+      c = mix3(col.lower, col.upper, smoothstep(-0.5, 0.3, e));
+      c = mix3(c, col.back, smoothstep(0.45, 0.95, up));
+      c = mix3(c, col.belly, smoothstep(0.35, 0.95, lowK));
+      if (morph === 'white') c = mix3(srgb(0xf1eee6), srgb(0xf6e7c8), smoothstep(0.3, 0.9, up) * 0.4);
+      if (morph === 'red') c = mix3(c, srgb(0xd83414), 0.72);
+      // common goldfish range from orange-gold to red-orange
+      if (morph === 'common') { const t = (params.hueShift ?? 0.5) - 0.5; c = t < 0 ? mix3(c, srgb(0xf5a834), -t * 1.1) : mix3(c, srgb(0xe85a18), t * 0.8); }
+    } else if (key === 'clownfish') {
+      c = mix3(col.lower, col.upper, smoothstep(-0.5, 0.2, e));
+      c = mix3(c, col.back, smoothstep(0.5, 1.0, up) * 0.6);
+      c = mix3(c, col.belly, smoothstep(0.5, 1.0, lowK) * 0.5);
+      if (morph === 'black') c = mix3(c, srgb(0x1c120c), 0.85);
+    } else {
+      // bluegill: olive back, brassy flanks, orange / yellow breast, dusky vertical bars, blue cheek
+      c = mix3(col.lower, col.upper, smoothstep(-0.5, 0.25, e));
+      c = mix3(c, col.back, smoothstep(0.4, 0.95, up));
+      const breast = smoothstep(0.1, 0.85, lowK) * (1 - smoothstep(0.35, 0.6, u));
+      c = mix3(c, params.sex === 'male' ? col.breast : col.belly, breast * 0.85);
+      c = mix3(c, col.belly, smoothstep(0.55, 1, lowK) * (1 - breast) * 0.5);
+      const barPh = (u - 0.3) / 0.105;
+      const bar = u > 0.28 && u < 0.95 ? Math.pow(0.5 + 0.5 * Math.cos(barPh * 2 * Math.PI), 3) * smoothstep(-0.7, 0.2, e) : 0;
+      c = mix3(c, col.spot, bar * 0.45 * (params.barK ?? 1));
+      if (k === 1 || k === 6) {
+        const streak = 0.5 + 0.5 * Math.sin((p[1] - G.axisY) / SL * 90 + u * 30);
+        // two or three blue-violet streaks across the lower cheek and gill cover
+        const zone = (1 - smoothstep(0.15, 0.45, Math.abs(e + 0.35))) * smoothstep(0.1, 0.18, u) * (1 - smoothstep(0.28, 0.33, u));
+        c = mix3(c, col.cheek, zone * smoothstep(0.55, 0.85, streak) * 0.5);
+      }
+    }
+    if (k === 7) c = col.ear;
+    if (col.ear && (k === 0 || k === 1)) {
+      // the bluegill's opercular flap: a solid black lobe (~0.08 x 0.05 SL) at the top rear of the gill cover
+      const fz = (u - (H.op + 0.03)) / 0.058, fy = (p[1] - (G.yc(H.op) + 0.2 * G.hd(H.op))) / (0.034 * SL);
+      const r = fz * fz + fy * fy;
+      if (r < 1.25) c = mix3(c, col.ear, smoothstep(1.25, 0.9, r));
+    }
+    // the lips' cut faces (the lip line at rest, the inside of the lips when the mouth opens): the
+    // skin colour a little darker, toward the pale pink of the mouth lining
+    if (k === 9) c = mix3(c.map((x) => x * 0.85), srgb(0xb88a80), 0.3);
+    // the gill cover's free edge: a soft shading line (the plate overlaps the body there), the head
+    // colour darkened ~15 %, fading out where the edge runs under the throat and the nape
+    const eC = clamp(e, -1.2, 1.2);
+    const du = u - opEdgeU(H.op, eC);
+    const edgeLine = (k === 0 || k === 1) ? smoothstep(-0.005, 0.0, du) * (1 - smoothstep(0.0015, 0.008, du)) * (1 - smoothstep(0.62, 0.9, Math.abs(eC + 0.05))) : 0;
+    c = c.map((x) => x * (1 - 0.15 * edgeLine));
+    c = mix3(c, c.map((x) => x * 0.8), 0.25 * (noise + 0.5));
+    c = tweak(c);
+    if (k === 5) { sz = 0.0008 * SL; }
+    // the head is scaleless skin (tiny scale size: no scale relief, same sheen); behind the gill
+    // cover the scales fade in over V.scaleFade of SL (surf.w < 0 lowers their contrast), so large
+    // scales (goldfish) do not start at a hard line
+    let sw2 = irid;
+    if (k === 1 || k === 6 || k === 9) sz = 0.0006 * SL;
+    else if (k === 0 && V.scaleFade && du < V.scaleFade) sw2 = mix(-1, irid, clamp(du / V.scaleFade, 0, 1));
+    // spots / patches
+    if (spotsF && (k === 0 || k === 1 || k === 5 || (k === 6 && morph === 'sarasa'))) {
+      const [d] = featureDistance(spotsF, p, n);
+      pattern[v] = d;
+      patternColor.set([...col.spot, 1], o4);
+    }
+    if (key === 'clownfish') {
+      const bandsSD = clownBands(G, u, e);
+      pattern[v] = bandsSD;
+      patternColor.set([...col.spot, 1], o4);
+      // black edging around the bands
+      mark[v] = Math.abs(bandsSD) - 0.012 * SL * (params.edgeK ?? 1);
+      if (morph === 'black') patternColor.set([...col.spot, 1], o4);
+    }
+    tint.set([c[0], c[1], c[2], mat], o4);
+    comb.set(cm, o3);
+    surf.set([gl, sz, 0, sw2], o4);
+  }
+  // far from any feature the SDF is 'infinite': clamp it, or its screen-space derivative (the shader's
+  // antialiasing width) explodes across the triangles on that border and paints a stepped line
+  for (let v = 0; v < nV; v++) { if (pattern[v] > 0.03 * SL) pattern[v] = 0.03 * SL; if (mark[v] > 0.03 * SL) mark[v] = 0.03 * SL; }
+  // soften fin opacity / phase noise across the mesh
+  const w = new Float32Array(nV);
+  for (let v = 0; v < nV; v++) w[v] = surf[v * 4 + 3];
+  smoothField(w, weights.neighbors, 1, (v) => kind[v] !== 2);
+  for (let v = 0; v < nV; v++) if (kind[v] === 2) surf[v * 4 + 3] = w[v];
+  return { comb, tint, pattern, mark, furLen, patternColor, surf, stats: { spots: spotsF ? spotsF.spots.length : 0 } };
+}
+
+const mul = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+
+// clownfish: three white bands (behind the eye curving forward, mid-body with a forward bulge,
+// caudal peduncle), as a signed distance in metres (< 0 inside a band)
+function clownBands(G, u, e) {
+  const SL = G.SL;
+  // the forehead and chin stand above the outline table (the sections overlap there): without the
+  // clamp the head band's forward curve ran onto the snout as a white smear
+  e = clamp(e, -1.1, 1.1);
+  const band = (c, w) => (Math.abs(u - c) - w) * SL;
+  const b1 = band(0.235 - 0.05 * e * e + 0.01 * e, 0.045);
+  const b2 = band(0.53 + 0.07 * Math.exp(-e * e * 4) - 0.03, 0.05 + 0.012 * Math.exp(-e * e * 4));
+  const b3 = band(0.905, 0.035);
+  return Math.min(b1, b2, b3);
+}
+void cross; void dot; void mix;

package/vendor/procedural-animals/src/species/fish/index.js

@@ -0,0 +1,88 @@
+// Fish (teleosts): rainbow trout, goldfish, ocellaris clownfish and bluegill as seeded / explicit
+// variants (createAnimal('fish', { variant: 'trout' })). Swimmer body plan (core/motion/swimmer.js).
+import { fishRig, fishGeo } from './rig.js';
+import { sculptFish, CELL } from './sculpt.js';
+import { fishRegions } from './regions.js';
+import { fishCoat } from './coat.js';
+import { motion } from './motion.js';
+import { VARIANTS, VARIANT_KEYS } from './variants.js';
+import { srgb } from '../../core/build/coatKit.js';
+import { rng } from '../../core/math/vec.js';
+
+const pick = (R, table) => {
+  let x = R(), acc = 0;
+  for (const [k, w] of table) { acc += w; if (x < acc) return k; }
+  return table[table.length - 1][0];
+};
+
+export default {
+  id: 'fish',
+  name: 'Fish',
+  latin: 'Teleostei',
+  group: 'swimmers',
+  plan: 'swimmer',
+  covering: 'scales',
+  variants: VARIANT_KEYS.map((id) => ({ id, name: VARIANTS[id].name, latin: VARIANTS[id].latin })),
+
+  // Seeded individual. The variant (species) comes from opts.variant or from the seed; within a
+  // variant: size, body depth, head size, colour morph, sex (bluegill breeding colours, clownfish
+  // females larger), juveniles smaller with bigger heads and eyes.
+  variation(R, o) {
+    const variant = o.variant && VARIANTS[o.variant] ? o.variant : VARIANT_KEYS[Math.floor(R() * VARIANT_KEYS.length) % VARIANT_KEYS.length];
+    const sex = o.sex || (R() < 0.5 ? 'male' : 'female');
+    const age = o.age || 'adult';
+    const juv = age === 'juvenile';
+    const g = () => (R() + R() + R() - 1.5) / 1.5;
+    const G = fishGeo({ variant });
+    let sexK = 1;
+    if (variant === 'clownfish') sexK = sex === 'female' ? 1.1 : 0.86;
+    if (variant === 'trout') sexK = sex === 'male' ? 1.04 : 0.97;
+    const size = sexK * (1 + 0.1 * g()) * (juv ? 0.45 : 1);
+    // colour morphs from their own hashed stream: consecutive seeds must not correlate
+    const M = rng(Math.imul((o.seed ?? 1) + 0x632be5ab, 0x9e3779b1) ^ 0x5bd1e995);
+    for (let i = 0; i < 4; i++) M();
+    let morph = '';
+    if (variant === 'trout') morph = pick(M, [['stream', 0.72], ['silver', 0.28]]);
+    if (variant === 'goldfish') morph = pick(M, [['common', 0.55], ['red', 0.17], ['sarasa', 0.2], ['white', 0.08]]);
+    if (variant === 'clownfish') morph = pick(M, [['orange', 0.9], ['black', 0.1]]);
+    const shadeM = M();
+    const SL = G.SL;
+    const depthK = 1 + 0.05 * g() + (variant === 'trout' && sex === 'female' ? 0.02 : 0);
+    return {
+      variant, sex, age, size, morph,
+      warps: [
+        { type: 'girth', k: depthK, cy: G.axisY, z0: G.z(0.95), z1: G.z(0.15), fade: 0.12 * SL },
+        { type: 'scaleAbout', c: G.headO, k: (1 + 0.035 * g()) * (juv ? 1.14 : 1), r0: 0.12 * SL, r1: 0.3 * SL },
+      ],
+      coatShade: 0.6 * g(),
+      hueShift: variant === 'goldfish' && morph === 'common' ? shadeM : 0.5,
+      coatSeed: Math.floor(R() * 1e6),
+      bandK: variant === 'trout' ? (morph === 'silver' ? 0.3 : 0.8 + 0.25 * R()) * (sex === 'male' ? 1.15 : 0.9) : 1,
+      barK: variant === 'bluegill' ? (sex === 'male' ? 0.8 : 1.1) * (0.8 + 0.4 * R()) : 1,
+      edgeK: variant === 'clownfish' ? 0.8 + 0.5 * R() : 1,
+      spotScale: 0.8 + 0.4 * R(),
+      tailK: (variant === 'goldfish' && morph !== 'common' && R() < 0.5 ? 1.3 : 1) * (1 + 0.06 * g()),
+      finK: 1 + 0.07 * g() + (juv ? 0.08 : 0),
+      minThick: SL * CELL * (VARIANTS[variant].cellK || 1) * 1.15,
+    };
+  },
+  rig: (params) => fishRig(params),
+  sculpt: (m, rig, params) => sculptFish(m, rig, params),
+  regions: fishRegions,
+  coat: fishCoat,
+  eyeSpecs(params) {
+    const G = fishGeo(params);
+    const E = G.eye, V = G.V;
+    const spec = { c: [E.x, 0, 0], r: E.r, back: 0, yaw: 1.28, pitch: 0.1, lid: 0, R: E.r * 1.0, d: 0, off: 0, tilt: 0, irisZ: E.r * 0.42, irisR: E.r * 0.86 };
+    const iris = V.eye.iris.map((h) => srgb(h));
+    const look = {
+      pupil: 'round', lids: 'none', pupilSize: [0.34, 0.42],
+      iris: { inner: iris[0], mid: iris[1], hi: iris[2], outer: iris[3] },
+      sclera: { color: [0.05, 0.05, 0.05], visible: false },
+    };
+    return [1, -1].map((side) => ({ side, spec, headOrigin: G.headO, bone: 'head', look }));
+  },
+  motion,
+  // scale rim contrast per variant: the goldfish's big scales read as a fine lattice, not outlined cells
+  render: (params) => ({ markColor: [0.008, 0.008, 0.009], scaleEdge: VARIANTS[params?.variant]?.scaleEdge ?? 0.15 }),
+};

package/vendor/procedural-animals/src/species/fish/motion.js

@@ -0,0 +1,92 @@
+// Fish motion data for the swimmer engine (schema: src/core/motion/swimmer.js). Speeds in body
+// lengths per second (BL/s), so one table serves every size. Per-variant overrides in `variants`.
+//
+// Tail-beat frequency vs speed from Bainbridge (1958, dace / trout / goldfish): U/L = 0.75 f - 1 above
+// ~2 BL/s, tail amplitude ~0.2 L peak-to-peak; below that the frequencies and amplitudes are estimates
+// from subcarangiform kinematics (Videler 1993). Bluegill: pectoral (labriform) swimming up to 1.2 BL/s,
+// fin beat 2.8 Hz at the gait transition (Jones et al. 2007). C-start stage 1 ~ 0.24 s per metre of body
+// (Domenici 2023: 16 ms at 5 cm, 60 ms at 25 cm). Wave rows: [v, f Hz, amp p-p / L, lambda / L,
+// pectoral activity, pectoral beat Hz, pectoral fold].
+export const motion = {
+  speeds: { scull: 0.4, cruise: 1.5, sprint: 4 },
+  maxSpeed: 6, burstSpeed: 10, accel: 12, decel: 4, turnRate: 3.2, turnRadius: 0.35,
+  wave: [
+    [0, 0.8, 0.03, 1.0, 1.0, 1.5, 0],
+    [0.5, 1.9, 0.1, 0.95, 0.6, 1.8, 0.3],
+    [1.5, 3.3, 0.17, 0.9, 0.15, 2.0, 0.75],
+    [3, 5.3, 0.2, 0.85, 0, 2, 1],
+    [6, 9.3, 0.2, 0.8, 0, 2, 1],
+    [10, 14.7, 0.21, 0.75, 0, 2, 1],
+  ],
+  envelope: { exp: 3.5 },
+  flex: [0.15, 0.86], bend: 1.4, cBend: 3.1, bank: 0.3, pitchMax: 0.9, hover: 0.35,
+  clearance: 0.1, cruiseDepth: 0.6,
+  pectoral: { rest: [0, 0, 0], flap: 9, row: 14, feather: 22, fold: 24, flare: 45, alternate: 0.25, stiff: 0 },
+  pelvic: { rest: 0, spread: 10, fold: 12 },
+  breath: { rate: 1.2, operculum: 9, mouth: 0.07, ram: 2.5 },
+  jaw: { gape: 30, protrude: 0.02 },
+  actions: {
+    burst: { turn: 90 },
+    jump: { height: 1.4 },
+    eat: { style: 'suction' },
+    drink: { reach: 3 },
+    sleep: { style: 'bottom' },
+  },
+  variants: {
+    trout: {
+      speeds: { scull: 0.4, cruise: 1.5, sprint: 4 },
+      jaw: { gape: 34, protrude: 0.012 },
+      actions: { jump: { height: 1.8 } },
+    },
+    goldfish: {
+      speeds: { scull: 0.35, cruise: 1.3, sprint: 3.5 },
+      maxSpeed: 5, burstSpeed: 9,
+      wave: [
+        [0, 1.0, 0.03, 1.0, 1.0, 2.2, 0],
+        [0.5, 1.8, 0.09, 0.95, 0.8, 2.4, 0.2],
+        [1.3, 3.1, 0.17, 0.9, 0.3, 2.4, 0.6],
+        [3, 5.3, 0.2, 0.85, 0, 2.4, 1],
+        [6, 9.3, 0.2, 0.8, 0, 2.4, 1],
+        [10, 14.7, 0.21, 0.75, 0, 2.4, 1],
+      ],
+      envelope: { exp: 3.0 }, turnRadius: 0.25,
+      pectoral: { rest: [0, 0, 0], flap: 11, row: 16, feather: 26, fold: 26, flare: 48, alternate: 0.8 },
+      jaw: { gape: 36, protrude: 0.03 },
+      breath: { rate: 1.4 },
+      actions: { eat: { style: 'bottom' }, jump: { height: 1.0 } },
+    },
+    clownfish: {
+      speeds: { scull: 0.8, cruise: 2.0, sprint: 4 },
+      maxSpeed: 6, burstSpeed: 9, turnRadius: 0.2, turnRate: 4,
+      wave: [
+        [0, 1.0, 0.02, 1.0, 1.0, 3.5, 0],
+        [0.6, 1.2, 0.03, 1.0, 1.0, 4.5, 0],
+        [1.4, 2.4, 0.08, 0.95, 0.8, 5.0, 0.15],
+        [2.2, 4.0, 0.16, 0.9, 0.2, 4, 0.6],
+        [4, 6.7, 0.2, 0.85, 0, 4, 1],
+        [8, 12, 0.21, 0.8, 0, 4, 1],
+      ],
+      envelope: { exp: 2.8 },
+      pectoral: { rest: [0, 0, 0], flap: 12, row: 20, feather: 28, fold: 28, flare: 45, alternate: 0.08 },
+      breath: { rate: 1.8 },
+      jaw: { gape: 30, protrude: 0.03 },
+      actions: { sleep: { style: 'side' }, jump: { height: 0.8 } },
+    },
+    bluegill: {
+      speeds: { scull: 0.6, cruise: 1.8, sprint: 4 },
+      maxSpeed: 6, burstSpeed: 9, turnRadius: 0.2, turnRate: 3.8,
+      wave: [
+        [0, 0.8, 0.02, 1.0, 1.0, 1.6, 0],
+        [0.6, 1.0, 0.03, 1.0, 1.0, 2.2, 0],
+        [1.2, 2.2, 0.08, 0.95, 0.7, 2.8, 0.2],
+        [1.8, 3.7, 0.17, 0.9, 0.15, 2.8, 0.7],
+        [4, 6.7, 0.2, 0.85, 0, 2.8, 1],
+        [8, 12, 0.21, 0.8, 0, 2.8, 1],
+      ],
+      envelope: { exp: 3.0 },
+      pectoral: { rest: [0, 0, 0], flap: 12, row: 18, feather: 28, fold: 18, flare: 42, alternate: 0.1 },
+      jaw: { gape: 32, protrude: 0.03 },
+      actions: { sleep: { style: 'hover' }, jump: { height: 1.0 } },
+    },
+  },
+};

package/vendor/procedural-animals/src/species/fish/regions.js

@@ -0,0 +1,27 @@
+// Meshing plan: the whole fish (body + fins) as one surface at SL * CELL (0.8 mm for a 26 cm trout at
+// the hero tier), and the lower jaw as its own rigid surface so the mouth can open.
+import { fishGeo } from './rig.js';
+import { CELL } from './sculpt.js';
+
+export function fishRegions(rig, params, Q) {
+  const G = fishGeo(params);
+  const SL = G.SL, V = G.V, r = Q.res;
+  const h = SL * CELL * (V.cellK || 1) * r;
+  // tight box: body outline + the longest dorsal / anal rays + the paired fins
+  let top = 0, bot = 0, hw = 0;
+  for (const r of V.prof) { top = Math.max(top, r[1]); bot = Math.max(bot, r[2]); hw = Math.max(hw, r[3]); }
+  const dl = Math.max(...V.fins.dorsal.map((d) => Math.max(...d.len))), al = Math.max(...V.fins.anal.map((d) => Math.max(...d.len)));
+  const J = rig.J;
+  const xMax = Math.max(hw * SL, Math.abs(J.pecTipL[0]), Math.abs(J.pelTipL[0])) + 0.03 * SL;
+  const topY = G.axisY + (top + dl) * SL + 0.03 * SL;
+  const botY = Math.min(G.axisY - (bot + al * 0.9) * SL, J.pelTipL[1], J.pecTipL[1]) - 0.03 * SL;
+  const zTail = G.z(1 + G.tailLen * 1.08 + 0.03);
+  const g = V.head.mouth.gape;
+  return {
+    jobs: [
+      [{ name: 'body', part: 'body', bmin: [-xMax, botY, zTail], bmax: [xMax, topY, G.z0 + 0.03 * SL], h, F: 6 }],
+      [{ name: 'jaw', part: 'jaw', bmin: [-0.2 * SL, -0.02 * SL, G.z(g + 0.14)], bmax: [0.2 * SL, G.mouthY + 0.03 * SL, G.z0 + 0.04 * SL], h: h * 0.8, F: 4, rigidBone: 'jaw' }],
+    ],
+    fade: () => 1,
+  };
+}