@pieai/swimmer-avatar-kit 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+import type { Group, Material, Texture } from "three";
+export interface AvatarPartRecipe {
+    params?: unknown | null;
+    rr?: number;
+}
+export interface AvatarRecipe {
+    seed: number;
+    species: string | null;
+    body: string | null;
+    stance: string | null;
+    palette: string | null;
+    colorIx: number | null;
+    material: string | null;
+    parts: Record<string, AvatarPartRecipe>;
+}
+export type AvatarSeed = number | string;
+export type AvatarExpression = "idle" | "happy" | "angry" | "sad" | "surprised";
+export interface AvatarOption {
+    id: string;
+    label: string;
+}
+export interface AvatarPaletteOption extends AvatarOption {
+    colors: readonly string[];
+}
+export type AvatarMaterialFor = (finish: string, color: string, shell?: boolean, print?: {
+    key: string;
+    tex: Texture;
+} | null) => Material;
+export interface AvatarBuildStats {
+    buildMs: number;
+    verts: number;
+    meshes: number;
+}
+export interface AvatarBounds {
+    w: number;
+    h: number;
+    cy: number;
+    minY: number;
+    maxY: number;
+}
+export interface AvatarBuildOptions {
+    materialFor: AvatarMaterialFor;
+    gaze?: boolean;
+}
+export interface AvatarHandle {
+    readonly object: Group;
+    readonly recipe: AvatarRecipe;
+    readonly stats: AvatarBuildStats;
+    readonly bounds: AvatarBounds;
+    update(deltaSeconds: number): void;
+    getExpression(): AvatarExpression;
+    setExpression(expression: AvatarExpression): void;
+    isDisposed(): boolean;
+    dispose(): void;
+}
+export interface AvatarRecipeDocumentV1 {
+    schema: "@pieai/swimmer-avatar-kit/recipe";
+    version: 1;
+    renderer: "gloss";
+    recipe: AvatarRecipe;
+}
+export type AvatarRecipeDocument = AvatarRecipeDocumentV1;

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@pieai/swimmer-avatar-kit",
+  "version": "0.1.0",
+  "description": "Shared procedural 3D avatar recipes, Three.js runtime, and React Three Fiber adapter for PieAI products.",
+  "keywords": [
+    "avatar",
+    "procedural-generation",
+    "react-three-fiber",
+    "swimmer",
+    "threejs",
+    "typescript"
+  ],
+  "homepage": "https://github.com/PieAIStudio/SwimmerAvatarKit#readme",
+  "bugs": {
+    "url": "https://github.com/PieAIStudio/SwimmerAvatarKit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PieAIStudio/SwimmerAvatarKit.git"
+  },
+  "files": [
+    "dist",
+    "vendor",
+    "README.md",
+    "NOTICE.md",
+    "UPSTREAM.md",
+    "upstream-lock.json",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./materials": {
+      "types": "./dist/materials.d.ts",
+      "import": "./dist/materials.js"
+    },
+    "./react-three-fiber": {
+      "types": "./dist/react-three-fiber.d.ts",
+      "import": "./dist/react-three-fiber.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@pieai/doc-gov": "0.9.3",
+    "@pieai/pro-gov": "0.9.3",
+    "@react-three/fiber": "9.6.1",
+    "@types/node": "24.13.2",
+    "@types/react": "19.2.17",
+    "@types/three": "0.185.1",
+    "lefthook": "2.1.10",
+    "oxfmt": "0.58.0",
+    "oxlint": "1.73.0",
+    "react": "19.2.7",
+    "three": "0.185.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@react-three/fiber": ">=9 <10",
+    "react": ">=19 <20",
+    "three": ">=0.180.0 <1"
+  },
+  "peerDependenciesMeta": {
+    "@react-three/fiber": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "oxlint src tests scripts -c ./.oxlintrc.json",
+    "format": "oxfmt package.json tsconfig.json tsconfig.build.json .oxlintrc.json src tests scripts --write --ignore-path ./.oxfmtignore",
+    "format:check": "oxfmt package.json tsconfig.json tsconfig.build.json .oxlintrc.json src tests scripts --check --ignore-path ./.oxfmtignore",
+    "test": "vitest run --pool threads",
+    "test:package-consumer": "node scripts/test-package-consumer.mjs",
+    "host-links:check": "node scripts/verify-host-links.mjs",
+    "vendor:verify": "node scripts/verify-vendor.mjs",
+    "upstream:check": "node scripts/check-upstream.mjs",
+    "verify": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm vendor:verify && pnpm test && pnpm build",
+    "verify:release": "pnpm verify && pnpm docs:check && pnpm test:package-consumer",
+    "doc-gov": "doc-gov",
+    "pro-gov": "pro-gov",
+    "docs:check": "pnpm pro-gov doctor --strict-hooks && pnpm host-links:check && pnpm doc-gov router-check && pnpm doc-gov check && pnpm doc-gov scan --check && pnpm doc-gov links && pnpm doc-gov audit && pnpm doc-gov doctor"
+  }
+}

package/upstream-lock.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "repository": "https://github.com/albertobeiz/kindergrimm.git",
+  "defaultBranch": "main",
+  "commit": "811214c6dd5de18cc20335cd3d4ab0a06e45ffd4",
+  "commitDate": "2026-08-21T12:51:30+02:00",
+  "importedAt": "2026-08-22",
+  "license": "Unlicense",
+  "excludedEntrypoints": ["src/gloss/gcrowd.js", "src/gloss/gloss.js"],
+  "files": {
+    "LICENSE": "c290d5a44ba844c2aa271e3be836c25176fe1f8b",
+    "src/gloss/catmullClark.js": "3fa76213faa27595836365a451218fb650529fc5",
+    "src/gloss/gface.js": "f0e90be3039ddd93adb06254943985ee1a37e0d4",
+    "src/gloss/gform.js": "c07865a29b7741fa454238a724e330f05f0f0747",
+    "src/gloss/ghair.js": "bfb35aa765415f9d2fe4f14b6dd5cf947ecece4b",
+    "src/gloss/glayout.js": "21667e34b7f486b89608698abe2527a9dc565c26",
+    "src/gloss/gmedia.js": "aef88b617f3f694b1051237055fd5edcd8be546e",
+    "src/gloss/gpalette.js": "31d1fd17decc8a8f779aa06288bf2fe057aec9dd",
+    "src/gloss/gparts/blush.js": "daed9e66e45b918569490be71392858fa5e502ec",
+    "src/gloss/gparts/body.js": "5f15d76362ec47dc24846a3eacb5f5ba6a435484",
+    "src/gloss/gparts/brows.js": "d646a477b73de7e7d0fa4443848aff9d5c328f45",
+    "src/gloss/gparts/crest.js": "fb5470509ff75ad2d03addc4d9ba02109f7f5521",
+    "src/gloss/gparts/eyes.js": "9188e13c0df544620d951ecf5b0dba05b59ab55b",
+    "src/gloss/gparts/frame.js": "957727c53a6f9f9c4bd95399378ae3cdaa5a1423",
+    "src/gloss/gparts/hair.js": "b962f6fe0e30bbed537054b4fa0d6193052e5b87",
+    "src/gloss/gparts/hat.js": "27fbc817ab9797dd706bde93913dccbdfebb2c48",
+    "src/gloss/gparts/index.js": "82fc74c3c2cec69e11b28bfebbdee2df60dc3052",
+    "src/gloss/gparts/mark.js": "046143fdedab6bc03c0e7495338b342cef5c4fc9",
+    "src/gloss/gparts/mouth.js": "1d6cdcb271b002b37469c985517764aed1647091",
+    "src/gloss/gparts/nose.js": "82683b6bda2bb2fcae9b833686aaf9a10c039e52",
+    "src/gloss/gparts/specs.js": "780de9e2584f68eb34c199756c1fc045187f0159",
+    "src/gloss/grig.js": "2bc489a2bf05d9299a56bca808522a9e2f5fdf49",
+    "src/gloss/gshape.js": "c44e0b43ddfebef130d7ec8d6be26f4e9b4e7448",
+    "src/gloss/gspecies.js": "1805c18339956068354a6c85c1ca93d39e1758f1",
+    "src/gloss/gtexture.js": "00a4c3ddc46496357f7232ea6f68ff537a432697",
+    "src/rng.js": "5a6e8fe001552cf8ae860d70318e1c85da58baec"
+  }
+}

package/vendor/kindergrimm/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/vendor/kindergrimm/src/gloss/catmullClark.js

@@ -0,0 +1,129 @@
+/**
+ * Catmull-Clark subdivision for closed quad/n-gon meshes.
+ *
+ * three.js used to ship SubdivisionModifier but it was removed, and the
+ * community replacement (three-subdivide) is Loop subdivision on triangles,
+ * which does not give the same surface. Catmull-Clark on quads is what C4D and
+ * Blender do, and it is about 60 lines, so we just do it.
+ *
+ * Mesh format is plain arrays:
+ *   verts: [[x, y, z], ...]
+ *   faces: [[i, j, k, l], ...]   (any arity, wound consistently)
+ */
+
+function addTo(out, v) {
+  out[0] += v[0];
+  out[1] += v[1];
+  out[2] += v[2];
+}
+
+function scale(v, s) {
+  return [v[0] * s, v[1] * s, v[2] * s];
+}
+
+export function subdivide({ verts, faces }) {
+  const nv = verts.length;
+
+  // 1. face points: the centroid of each face
+  const facePoints = faces.map((f) => {
+    const c = [0, 0, 0];
+    for (const vi of f) addTo(c, verts[vi]);
+    return scale(c, 1 / f.length);
+  });
+
+  // 2. edges. Every edge in a closed mesh is shared by exactly two faces.
+  const edges = new Map(); // "a_b" (a<b) -> { a, b, faces: [] }
+  const edgeKey = (a, b) => (a < b ? `${a}_${b}` : `${b}_${a}`);
+  faces.forEach((f, fi) => {
+    for (let i = 0; i < f.length; i++) {
+      const a = f[i];
+      const b = f[(i + 1) % f.length];
+      const key = edgeKey(a, b);
+      let e = edges.get(key);
+      if (!e) edges.set(key, (e = { a: Math.min(a, b), b: Math.max(a, b), faces: [] }));
+      e.faces.push(fi);
+    }
+  });
+
+  // 3. edge points: average of the two endpoints and the two face points.
+  //    A border edge (one face) falls back to the midpoint.
+  const edgePointIndex = new Map();
+  const edgePoints = [];
+  for (const [key, e] of edges) {
+    const p = [0, 0, 0];
+    addTo(p, verts[e.a]);
+    addTo(p, verts[e.b]);
+    if (e.faces.length === 2) {
+      addTo(p, facePoints[e.faces[0]]);
+      addTo(p, facePoints[e.faces[1]]);
+      edgePointIndex.set(key, nv + faces.length + edgePoints.length);
+      edgePoints.push(scale(p, 0.25));
+    } else {
+      edgePointIndex.set(key, nv + faces.length + edgePoints.length);
+      edgePoints.push(scale(p, 0.5));
+    }
+  }
+
+  // 4. move the original vertices: (F + 2R + (n-3)P) / n
+  const F = Array.from({ length: nv }, () => [0, 0, 0]);
+  const R = Array.from({ length: nv }, () => [0, 0, 0]);
+  const faceValence = new Array(nv).fill(0);
+  const edgeValence = new Array(nv).fill(0);
+
+  faces.forEach((f, fi) => {
+    for (const vi of f) {
+      addTo(F[vi], facePoints[fi]);
+      faceValence[vi]++;
+    }
+  });
+  for (const e of edges.values()) {
+    const mid = scale([
+      verts[e.a][0] + verts[e.b][0],
+      verts[e.a][1] + verts[e.b][1],
+      verts[e.a][2] + verts[e.b][2],
+    ], 0.5);
+    addTo(R[e.a], mid);
+    edgeValence[e.a]++;
+    addTo(R[e.b], mid);
+    edgeValence[e.b]++;
+  }
+
+  const newVerts = new Array(nv);
+  for (let i = 0; i < nv; i++) {
+    const n = faceValence[i];
+    const f = scale(F[i], 1 / n);
+    const r = scale(R[i], 1 / edgeValence[i]);
+    const p = verts[i];
+    newVerts[i] = [
+      (f[0] + 2 * r[0] + (n - 3) * p[0]) / n,
+      (f[1] + 2 * r[1] + (n - 3) * p[1]) / n,
+      (f[2] + 2 * r[2] + (n - 3) * p[2]) / n,
+    ];
+  }
+
+  // 5. each n-gon becomes n quads
+  const outVerts = newVerts.concat(facePoints, edgePoints);
+  const outFaces = [];
+  faces.forEach((f, fi) => {
+    const fp = nv + fi;
+    for (let i = 0; i < f.length; i++) {
+      const prev = f[(i - 1 + f.length) % f.length];
+      const cur = f[i];
+      const next = f[(i + 1) % f.length];
+      outFaces.push([
+        cur,
+        edgePointIndex.get(edgeKey(cur, next)),
+        fp,
+        edgePointIndex.get(edgeKey(prev, cur)),
+      ]);
+    }
+  });
+
+  return { verts: outVerts, faces: outFaces };
+}
+
+export function subdivideN(mesh, times) {
+  let m = mesh;
+  for (let i = 0; i < times; i++) m = subdivide(m);
+  return m;
+}

package/vendor/kindergrimm/src/gloss/gface.d.ts

@@ -0,0 +1,25 @@
+import type { GlossBuilt } from "./grig.js";
+
+export type GlossExpression = "idle" | "happy" | "angry" | "sad" | "surprised";
+
+export const GLOSS_FACES: readonly GlossExpression[];
+
+export interface GlossHeadOffset {
+  x: number;
+  y: number;
+  yaw: number;
+  pitch: number;
+  rot: number;
+}
+
+export interface GlossLife {
+  head: GlossHeadOffset;
+  face: () => GlossExpression;
+  setFace: (id: GlossExpression) => void;
+  update: (elapsedSeconds: number, deltaSeconds: number) => GlossHeadOffset;
+}
+
+export function createGlossFace(
+  built: GlossBuilt,
+  options?: { gaze?: boolean },
+): GlossLife;

package/vendor/kindergrimm/src/gloss/gface.js

@@ -0,0 +1,226 @@
+// ---------------------------------------------------------------
+// THE FACE LIFE — the autonomic half of `anim.js`, ported to a character
+// that has no bones.
+//
+// The drawn rig gets its life from blink, gaze, sway and breath. Only
+// one of those needs a skeleton, so the other three come over intact,
+// and gaze is the one that matters:
+//
+//   SOMETHING CATCHES THE EYE, gets looked at, and is let go. The eyes
+//   move FIRST and FAST — a saccade is ballistic, it lands and stops —
+//   and the head follows late, slower, and only some of the time,
+//   because most real glances are eyes-only. Two separate springs,
+//   both critically damped: an under-damped head was tried (the
+//   cartoon whip-and-overshoot) and it read as bouncing, not looking.
+//   The life is in the eyes leading, not in the head ringing.
+//
+// Here the character IS the head, so the head spring drives the whole body —
+// and because every feature is its own mesh (see `gshape.js`), the
+// eyes leading the head is two translations, not a rebuild.
+//
+// EVERYTHING WRITTEN HERE IS AN OFFSET FROM REST. Each frame the
+// features are put back where the rig left them and the offsets are
+// re-applied, so expressions blend and nothing accumulates drift —
+// the same rule the drawn poses follow.
+// ---------------------------------------------------------------
+
+import { Vector3 } from 'three';
+
+// the ball-eye lid's hinge. WORLD x, not the lid's own: a wide-set
+// eye's normal tips ~30° off the camera, and a lid rolled about its
+// own tilted axis closes off-camera and leaves a rim of white showing
+const X_AXIS = new Vector3(1, 0, 0);
+
+const DIRS = ['left', 'right', 'up', 'down'];
+const OPPOSITE = { left: 'right', right: 'left', up: 'down', down: 'up' };
+
+// Expressions are OFFSETS, not drawings. A gloss face cannot swap a
+// mouth without rebuilding it, but it can raise a brow, narrow an eye
+// and open a mouth — which turns out to be most of what an expression
+// is anyway.
+const FACES = {
+  idle:      {},
+  happy:     { eyeSY: .78, browLift:  .16, mouthSY: 1.14 },
+  angry:     { eyeSY: .88, browLift: -.26, browRoll: -.55 },
+  sad:       { eyeSY: .94, browLift:  .12, browRoll:  .48, mouthSY: .9 },
+  surprised: { eyeS:  1.13, browLift: .36, mouthSY: 1.3 },
+};
+export const GLOSS_FACES = Object.keys(FACES);
+
+const isEye = id => id.startsWith('eye');
+const isBrow = id => id.startsWith('brow');
+
+/**
+ * built → an animator that owns every write to the face meshes.
+ * `update(t, dt)` then leaves the head's offset on `.head`, which the
+ * page adds to whatever else it is doing with that character.
+ */
+export function createGlossFace(built, opts = {}) {
+  const u = built.L.s;                       // one unit: the body radius
+  const rest = new Map();
+  for (const [id, m] of Object.entries(built.face)) {
+    rest.set(id, {
+      pos: m.position.clone(), quat: m.quaternion.clone(),
+      scale: m.scale.clone(), side: id.endsWith('L') || id.includes('L') ? -1 : 1,
+    });
+  }
+
+  let nextBlink = 1 + Math.random() * 3, blinkT = -1;
+  let dir = null, until = 0, next = 1 + Math.random() * 4, queue = [];
+  let ex = 0, ey = 0, evx = 0, evy = 0;      // the eyes — a saccade
+  let gx = 0, gy = 0, gvx = 0, gvy = 0;      // the head — settles, never rings
+  let headFollow = 1;                        // does THIS glance turn the head?
+  let cur = 'idle', target = 'idle', w = 1;
+
+  const api = {
+    // x/y in the CHARACTER's own units (a page at cell scale must multiply),
+    // yaw/pitch/rot in radians
+    head: { x: 0, y: 0, yaw: 0, pitch: 0, rot: 0 },
+    face: () => target,
+    setFace(id) {
+      if (!FACES[id] || id === target) return;
+      cur = target; target = id; w = 0;
+      // pull a blink forward: a face that changes behind shut lids
+      // reads as a decision, and one that changes in the open reads
+      // as a glitch
+      if (blinkT <= 0) { blinkT = .13; nextBlink = 1.2 + Math.random() * 3; }
+    },
+
+    update(t, dt) {
+      // ---- blink ----
+      if (blinkT > 0) blinkT -= dt;
+      else if (t > nextBlink) { blinkT = .13; nextBlink = t + 1.4 + Math.random() * 3.4; }
+      const shut = blinkT > 0 ? Math.max(.06, 1 - Math.sin((1 - blinkT / .13) * Math.PI)) : 1;
+
+      // ---- gaze: caught, held, let go ----
+      if (opts.gaze !== false) {
+        if (!dir && t > next) {
+          const d = DIRS[(Math.random() * 4) | 0];
+          // a third of the time it looks back the other way, which is
+          // what stops the sheet reading as everyone scanning a room
+          queue = Math.random() < .3 ? [d, OPPOSITE[d]] : [d];
+          dir = queue.shift();
+          // most real glances are eyes-only — the head stays put and
+          // only the eyes dart. The head joining in is the exception,
+          // and an eyes-only glance is quicker: a dart, not a stare
+          headFollow = Math.random() < .45 ? 1 : 0;
+          until = t + (headFollow ? .5 + Math.random() * 1.4
+                                  : .3 + Math.random() * .8);
+        } else if (dir && t > until) {
+          dir = queue.shift() ?? null;
+          if (dir) until = t + .4 + Math.random() * 1.1;
+          else next = t + 1.4 + Math.random() * 4;
+        }
+      }
+      const tx = dir === 'left' ? -1 : dir === 'right' ? 1 : 0;
+      const ty = dir === 'up' ? 1 : dir === 'down' ? -1 : 0;
+      // Both springs are stepped with the EXACT critically-damped
+      // solution, not Euler: the eye spring is stiff (ω·dt > 1 on any
+      // long frame, and building a character costs ~20ms), and an Euler step
+      // there flips the damping term's sign and flings every eye into
+      // a corner. The closed form cannot blow up at any dt.
+      const step = (x, v, tgt, om, h) => {
+        const dx = x - tgt, e = Math.exp(-om * h), b = v + om * dx;
+        return [tgt + (dx + b * h) * e, (v - om * b * h) * e];
+      };
+      // the EYES: fast — a saccade is ballistic, it lands and stops,
+      // it does not ease and it does not ring
+      const eo = 24;
+      [ex, evx] = step(ex, evx, tx, eo, dt);
+      [ey, evy] = step(ey, evy, ty, eo, dt);
+      // the HEAD: slower, chasing the same target only when this
+      // glance turns it — so the eyes visibly arrive first and the
+      // head settles after them without bouncing
+      const ho = 6;
+      [gx, gvx] = step(gx, gvx, tx * headFollow, ho, dt);
+      [gy, gvy] = step(gy, gvy, ty * headFollow, ho, dt);
+
+      // ---- expression blend ----
+      if (w < 1) w = Math.min(1, w + dt * 4);
+      const A = FACES[cur], B = FACES[target];
+      const mix = (key, d = 0) => (A[key] ?? d) * (1 - w) + (B[key] ?? d) * w;
+      const eyeSY = mix('eyeSY', 1), eyeS = mix('eyeS', 1);
+      const browLift = mix('browLift'), browRoll = mix('browRoll');
+      const mouthSY = mix('mouthSY', 1);
+
+      // ---- write ----
+      for (const [id, m] of Object.entries(built.face)) {
+        const r = rest.get(id);
+        m.position.copy(r.pos);
+        m.quaternion.copy(r.quat);
+        m.scale.copy(r.scale);
+
+        if (isEye(id)) {
+          // A feature carrying its own budget uses it: that is a PUPIL
+          // crossing its white, or the white itself barely stirring.
+          // Anything else is a whole eye, and it has to travel far
+          // enough to see — an offset you must look for is the same as
+          // no offset at all.
+          //
+          // The budget is scaled by `shut` so a pupil is back at centre
+          // by the time the lid closes over it: the white squashes
+          // about the eye's middle and a pupil left out at the edge
+          // would be squashed about somewhere else and slide clear.
+          const tv = m.userData.travel;
+          if (tv) { m.translateX(ex * tv[0] * shut); m.translateY(ey * tv[1] * shut); }
+          else { m.translateX(ex * u * .17); m.translateY(ey * u * .13); }
+
+          // A parked pupil comes back to the middle as the lid closes.
+          // The white squashes about the EYE's centre; a pupil resting
+          // up at the top would squash about its OWN and slide clear.
+          const park = m.userData.anchorY;
+          if (park) m.translateY(-park * (1 - shut));
+
+          // A LID does not squash, it COMES DOWN. Scaling it with the
+          // eye would just shrink it out of the way, which is the one
+          // thing a closing lid must not do.
+          const drop = m.userData.lidDrop;
+          if (drop) { m.translateY(-(1 - shut) * drop); continue; }
+
+          // A BALL eye's lid does not slide either, it ROLLS: the cap
+          // is centred on the ball, so pitching it forward wraps it
+          // over the front the way a real lid wraps an eyeball. A
+          // translate here would slide the cap off its own sphere.
+          const roll = m.userData.lidRoll;
+          if (roll) { m.rotateOnWorldAxis(X_AXIS, roll * (1 - shut)); continue; }
+
+          m.scale.set(r.scale.x * eyeS, r.scale.y * eyeS * eyeSY * (m.userData.shut ? 1 : shut), r.scale.z);
+        } else if (isBrow(id)) {
+          // brows belong to the eyes, not the skull — they ride the
+          // saccade, so an eyes-only glance still moves them
+          m.translateX(ex * u * .13);
+          m.translateY(ey * u * .12 + browLift * u * .11);
+          m.rotateZ(browRoll * r.side);
+        } else if (id.startsWith('mouth')) {
+          // ALL the mouth's plates: a maw is an outline, an interior,
+          // teeth and a tongue, and an expression that opened only the
+          // outline would leave the furniture poking through the lip
+          m.translateX(gx * u * .07);
+          m.translateY(gy * u * .04);
+          m.scale.set(r.scale.x, r.scale.y * mouthSY, r.scale.z);
+        } else if (id.startsWith('hair') || id.startsWith('hat')) {
+          // HAIR AND HATS DO NOT RIDE. Every other feature slides a
+          // little with the gaze because it is painted on a face that
+          // is turning. These are not on the face — the group's own
+          // spring already carries them, and a second offset on top
+          // slides the cut off the skull and the hat off the head.
+          continue;
+        } else {
+          m.translateX(gx * u * .09);          // nose, cheeks: they ride
+          m.translateY(gy * u * .07);
+        }
+      }
+
+      // What the head does about it. The TURN is what sells a look —
+      // a head that only slides is a head on a rail — so the yaw and
+      // pitch carry it and the shift is the follow-through.
+      api.head.x = gx * u * .16;
+      api.head.y = gy * u * .11;
+      api.head.yaw = gx * .34;
+      api.head.pitch = -gy * .22;
+      api.head.rot = -gx * .07;
+      return api.head;
+    },
+  };
+  return api;
+}