@joystack/cli 0.0.0-stage → 0.1.43

package/lib/model-bake.mjs

@@ -0,0 +1,869 @@
+// model bake — turn a rigged GLB into the artifacts the room needs to hit the
+// model's true animated surface:
+//
+//   <model>.skeleton.json   bones (parent, rest transform) + baked clips — what
+//                           shared/ui/room/lib/rig.js poses
+//   <model>.mesh.json       vertices, skin weights, triangles, per-triangle zone
+//                           bytes, broadphase radius — what skin-hit.js shoots
+//
+// Both are emitted TOGETHER from one read of one loaded model, because they share
+// a bone ordering: the mesh's skin indices are meaningless against a differently
+// ordered skeleton.
+//
+// The GLB is parsed by three.js's own GLTFLoader in a REAL browser (playwright),
+// not by a node-side parser. The browser's loader is the same code that will draw
+// the model at runtime, so whatever it decides about the asset (bone order, node
+// transforms, interleaved buffers) is by construction what the drawn model does.
+// A second parser would be a second opinion, and a second opinion is exactly the
+// drift class this pipeline exists to delete. The page is hermetic: every request
+// (three, the loader, the GLB bytes) is fulfilled from local disk via route
+// interception — no network, no server.
+//
+// Baking is normally AUTOMATIC: dev/test/publish call `ensureBaked()` and re-bake
+// any referenced GLB whose content hash no longer matches the artifact's recorded
+// source hash. `joystack model bake <glb>` is the explicit escape hatch (debugging,
+// forcing a re-bake). Artifacts are committed next to the model like any other
+// game file.
+//
+// ── Optional bake config: <model>.bake.json next to the GLB ──────────────────
+//   {
+//     "zones": { "head": ["Head", "Neck*"], "arm": ["*_Arm*"] },
+//     "clips": ["fly", "idle"],       // subset to bake; default = all
+//     "generate": "drifter-gen.mjs",  // generator script, relative to the GLB
+//     "pivot": "center"               // where body.(x,y,z) sits in the model:
+//   }                                 // "origin" (default) | "center" | "feet" | [x,y,z]
+// Zones use the dominant-bone rule (a triangle belongs to whichever bone most
+// influences its vertices — the same rule the big engines use to size their
+// bone-attached proxy shapes, pointed at triangles). Patterns match bone
+// names, `*` is a wildcard. Without config the mesh gets NO zones: hits still land
+// on the exact surface, damage is uniform, and `hitRay` reports `zone: null`.
+//
+// `generate` names a game-committed script that runs AT BAKE TIME with the
+// parsed model and returns data the engine carries: additive clips baked from a
+// procedural pose function (`export clips`) and/or per-triangle zone bytes for
+// meshes bone names can't describe (`export zones`). See the generator-script
+// section below for the exact contract. The script's text participates in the
+// staleness hash, so editing it re-bakes exactly like editing the GLB.
+//
+// ── What a bake rejects, loudly ──────────────────────────────────────────────
+//   - scale tracks in a clip (the runtime rig is uniform-scale; a scaling clip
+//     cannot be reproduced, so it fails the bake instead of silently drifting)
+//   - >4 skin influences per vertex, non-uniform bone scale, non-unit rotations
+//     (scale left in a matrix — the drifter's 17° bug, caught at bake)
+//   - skin weights outside [0,1] or not summing to ~1 (the fingerprint of reading
+//     interleaved attributes through `.array` instead of the accessors)
+// Root-bone POSITION tracks are stripped by default and reported: the entity's
+// own movement owns where the creature is, and keeping root motion would apply
+// it twice.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve, basename, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveEngine } from './project.mjs';
+
+// Version stamped into artifacts. Bump when the bake OUTPUT changes shape or
+// meaning — it participates in the staleness hash, so old artifacts re-bake.
+// v2: the staleness hash gained the generator-script component, and skeletons
+// may carry generated additive clips.
+// v3: skeletons carry a resolved `pivot`, and the broadphase radius is
+// measured about it instead of the model origin.
+export const BAKE_VERSION = 3;
+
+// ── pure helpers (unit-tested without a browser) ─────────────────────────────
+
+// Sort bones parent-first and produce old→new remap. rig.js poses in one forward
+// pass, so every parent must precede its children; a GLB does not promise that.
+export function sortBonesParentFirst(raw) {
+  const order = [];
+  const placed = new Set();
+  for (let guard = 0; order.length < raw.length && guard <= raw.length; guard++) {
+    for (let i = 0; i < raw.length; i++) {
+      if (placed.has(i)) continue;
+      if (raw[i].parent < 0 || placed.has(raw[i].parent)) { order.push(i); placed.add(i); }
+    }
+  }
+  if (order.length !== raw.length) throw new Error('skeleton is not a tree (parent cycle)');
+  const remap = new Int32Array(raw.length);
+  order.forEach((old, neu) => { remap[old] = neu; });
+  return { order, remap };
+}
+
+// Bone-name pattern matching for the zones config. `*` matches any run of
+// characters; matching is case-sensitive (bone names are authored identifiers).
+export function matchesPattern(name, pattern) {
+  if (!pattern.includes('*')) return name === pattern;
+  const rx = new RegExp(`^${pattern.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
+  return rx.test(name);
+}
+
+// Map each bone to a zone byte from the config. Zone 0 is always the implicit
+// "body" (every unmatched bone); config keys become zones 1..n in key order.
+export function boneZonesFromConfig(boneNames, zonesConfig) {
+  const names = ['body', ...Object.keys(zonesConfig)];
+  const byBone = new Uint8Array(boneNames.length);
+  boneNames.forEach((bn, i) => {
+    for (let z = 1; z < names.length; z++) {
+      if (zonesConfig[names[z]].some((p) => matchesPattern(bn, p))) { byBone[i] = z; return; }
+    }
+  });
+  return { names, byBone };
+}
+
+// Resolve the config's `pivot` — the model-space point that lands ON the
+// entity's body.(x,y,z) — against the bind-pose bounding box. There is no
+// universal right anchor (a flyer wants its centre, a walker its feet, a turret
+// its base), so it's a per-model choice; "origin" reproduces the GLB's own
+// origin and is the default. The resolved vector is written into the skeleton
+// artifact; the runtime composes it into PLACEMENT only, never the inverse
+// bind, so skinning is unaffected.
+export function resolvePivot(pivotCfg, bbox) {
+  if (pivotCfg == null || pivotCfg === 'origin') return [0, 0, 0];
+  const mid = (a) => (bbox.min[a] + bbox.max[a]) / 2;
+  if (pivotCfg === 'center') return [mid(0), mid(1), mid(2)];
+  if (pivotCfg === 'feet') return [mid(0), bbox.min[1], mid(2)];
+  if (Array.isArray(pivotCfg) && pivotCfg.length === 3 && pivotCfg.every((n) => Number.isFinite(n))) {
+    return [pivotCfg[0], pivotCfg[1], pivotCfg[2]];
+  }
+  throw new Error(`"pivot" must be "origin", "center", "feet", or [x, y, z] — got ${JSON.stringify(pivotCfg)}`);
+}
+
+// The dominant bone of a triangle: the bone with the highest summed skin weight
+// across its three vertices. `acc` is scratch sized to the bone count.
+export function dominantBone(skinIndex, skinWeight, influences, index, tri, acc) {
+  acc.fill(0);
+  for (let k = 0; k < 3; k++) {
+    const v = index[tri * 3 + k];
+    for (let j = 0; j < influences; j++) acc[skinIndex[v * influences + j]] += skinWeight[v * influences + j];
+  }
+  let best = 0, bestW = -1;
+  for (let b = 0; b < acc.length; b++) if (acc[b] > bestW) { bestW = acc[b]; best = b; }
+  return best;
+}
+
+export function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+// The staleness key an artifact records: GLB bytes + bake config + generator
+// script + bake version. If any of the four changes, the artifact is stale and
+// auto-bake re-runs — editing the generator's wing maths re-bakes exactly like
+// editing the GLB does.
+export function sourceHash(glbBytes, configText, generatorText = '') {
+  return sha256(Buffer.concat([
+    Buffer.from(`bake${BAKE_VERSION}!`),
+    Buffer.from(sha256(glbBytes)),
+    Buffer.from(sha256(Buffer.from(configText ?? ''))),
+    Buffer.from(sha256(Buffer.from(generatorText ?? ''))),
+  ]));
+}
+
+export function artifactPaths(glbPath) {
+  const stem = glbPath.replace(/\.glb$/i, '');
+  return { skeleton: `${stem}.skeleton.json`, mesh: `${stem}.mesh.json`, config: `${stem}.bake.json` };
+}
+
+// The generator script's current text, resolved from the bake config — '' when
+// the config names none. A named-but-missing script reads as null so staleness
+// can answer "stale" and the bake itself can fail with the real error.
+function generatorText(glbPath, configText) {
+  if (!configText) return '';
+  let gen;
+  try { gen = JSON.parse(configText)?.generate; } catch { return ''; }   // bad JSON fails in bakeModel with the real message
+  if (!gen) return '';
+  const p = resolve(dirname(glbPath), gen);
+  if (!existsSync(p)) return null;
+  return readFileSync(p, 'utf8');
+}
+
+// Is the artifact pair current for this GLB + config + generator? (Missing → stale.)
+export function isStale(glbPath) {
+  const { skeleton, mesh, config } = artifactPaths(glbPath);
+  if (!existsSync(skeleton) || !existsSync(mesh)) return true;
+  try {
+    const configText = existsSync(config) ? readFileSync(config, 'utf8') : '';
+    const genText = generatorText(glbPath, configText);
+    if (genText === null) return true;   // config names a script that is gone
+    const want = sourceHash(readFileSync(glbPath), configText, genText);
+    const have = JSON.parse(readFileSync(skeleton, 'utf8'))?._source?.hash;
+    return have !== want;
+  } catch {
+    return true;   // unreadable artifact = stale artifact
+  }
+}
+
+// ── generator scripts: game code runs at bake time, the engine ships data ────
+// bake.json may name a game-committed script: { "generate": "drifter-gen.mjs" }
+// (path relative to the GLB). The script receives the parsed model and returns
+// DATA — additive clip samples and/or per-triangle zone bytes. The engine
+// validates and carries what it returns; it learns no geometric language and
+// runs no game code after the bake. Two exports, both optional, each either the
+// value or a function of the model:
+//
+//   export function clips(model) {
+//     return { beat: { duration: 1, additive: true, keys: 64, sample: (t) => ({
+//       WingL: { rot: [x, y, z, w] },        // delta from rest, unit quaternion
+//       Chest: { pos: [x, y, z] },           // delta from rest, model units
+//     }) } };
+//   }
+//   export function zones(model) {
+//     return { names: ['body', 'wing'], tri: bytes };   // one byte per triangle
+//   }
+//
+// `model` = { bones, clips, mesh: { vertexCount, triangleCount, influences,
+// position, skinIndex, skinWeight, index } } — everything the bake read from
+// the GLB, typed arrays decoded.
+//
+// sample(t) must be DETERMINISTIC (no Math.random(), no Date.now()): the tracks
+// it produces are replicated pose truth, and a re-bake must reproduce them
+// byte-identically or the staleness hash lies.
+
+// Sample each generated clip definition into baked additive tracks.
+export function buildGeneratedClips(defs, boneNames, existingClipNames = []) {
+  const known = new Set(boneNames);
+  const existing = new Set(existingClipNames);
+  const clips = {};
+  for (const [name, def] of Object.entries(defs ?? {})) {
+    if (existing.has(name)) {
+      throw new Error(`generated clip "${name}" collides with a clip already in the GLB — rename one of them`);
+    }
+    if (def?.additive !== true) {
+      throw new Error(`generated clip "${name}" must declare additive: true — generated clips are deltas layered over the base pose; base clips come from the GLB`);
+    }
+    if (typeof def.sample !== 'function') {
+      throw new Error(`generated clip "${name}": "sample" must be a function of time`);
+    }
+    const duration = def.duration ?? 0;
+    // Key times are INCLUSIVE of the end (0..duration), so a looping clip
+    // interpolates across the seam instead of stepping at the wrap.
+    const keys = duration > 0 ? Math.max(2, Math.round(def.keys ?? 64)) : 0;
+    const times = duration > 0
+      ? Array.from({ length: keys + 1 }, (_, k) => (k / keys) * duration)
+      : [0];
+
+    // Determinism probe: the cheapest check that catches the whole class of
+    // Math.random()/Date.now() mistakes before they become flickering re-bakes.
+    if (JSON.stringify(def.sample(times[0])) !== JSON.stringify(def.sample(times[0]))) {
+      throw new Error(`generated clip "${name}": sample(t) is not deterministic — identical t must return identical output (no Math.random(), no Date.now()); these tracks are replicated pose truth and a re-bake must reproduce them exactly`);
+    }
+
+    let shape = null;                 // bone -> { rot: bool, pos: bool }, fixed by the first sample
+    const acc = new Map();            // bone -> { times, rot[], pos[] }
+    for (const t of times) {
+      const frame = def.sample(t) ?? {};
+      const frameBones = Object.keys(frame);
+      if (shape === null) {
+        shape = new Map();
+        for (const bn of frameBones) {
+          if (!known.has(bn)) {
+            throw new Error(`generated clip "${name}": sample() returned bone "${bn}" — the skeleton has no such bone. Bones are: ${boneNames.join(', ')}`);
+          }
+          shape.set(bn, { rot: !!frame[bn]?.rot, pos: !!frame[bn]?.pos });
+        }
+        if (!shape.size) throw new Error(`generated clip "${name}": sample() returned no bones`);
+      } else if (frameBones.length !== shape.size || !frameBones.every((bn) => shape.has(bn))) {
+        throw new Error(`generated clip "${name}": sample() must return the same bones (with the same rot/pos properties) at every time — t=${t} differs from t=${times[0]}`);
+      }
+      for (const [bn, spec] of shape) {
+        const v = frame[bn];
+        if (!!v?.rot !== spec.rot || !!v?.pos !== spec.pos) {
+          throw new Error(`generated clip "${name}": sample() must return the same bones (with the same rot/pos properties) at every time — bone "${bn}" at t=${t} differs`);
+        }
+        let entry = acc.get(bn);
+        if (!entry) { entry = { times: [], rot: spec.rot ? [] : null, pos: spec.pos ? [] : null }; acc.set(bn, entry); }
+        entry.times.push(t);
+        if (spec.rot) {
+          const q = v.rot;
+          const L = Math.hypot(q[0], q[1], q[2], q[3]);
+          if (!(L > 0) || Math.abs(L - 1) > 1e-3) {
+            throw new Error(`generated clip "${name}", bone "${bn}" at t=${t}: rotation is not unit length (${L.toFixed(4)}) — normalize your quaternions`);
+          }
+          entry.rot.push(q[0] / L, q[1] / L, q[2] / L, q[3] / L);
+        }
+        if (spec.pos) entry.pos.push(v.pos[0], v.pos[1], v.pos[2]);
+      }
+    }
+    clips[name] = {
+      duration,
+      additive: true,
+      tracks: [...acc.entries()].map(([bone, e]) => ({
+        bone, times: e.times,
+        ...(e.rot ? { rot: e.rot } : {}),
+        ...(e.pos ? { pos: e.pos } : {}),
+      })),
+    };
+  }
+  return clips;
+}
+
+// Validate a zone generator's return: bring-your-own-bytes, checked hard.
+export function validateGeneratedZones(z, triangleCount) {
+  if (!z || !Array.isArray(z.names) || z.names.length === 0 || !z.names.every((n) => typeof n === 'string')) {
+    throw new Error('zone generator: "names" must be a non-empty array of zone name strings (index 0 is the default zone)');
+  }
+  if (z.names.length > 256) {
+    throw new Error(`zone generator: at most 256 zone names (got ${z.names.length}) — zones are stored one byte per triangle`);
+  }
+  const tri = z.tri;
+  const len = tri?.length ?? -1;
+  if (len !== triangleCount) {
+    throw new Error(`zone generator: "tri" must carry one byte per triangle — the mesh has ${triangleCount} triangles, got ${len}`);
+  }
+  const out = new Uint8Array(triangleCount);
+  for (let i = 0; i < triangleCount; i++) {
+    const v = tri[i];
+    if (!Number.isInteger(v) || v < 0 || v >= z.names.length) {
+      throw new Error(`zone generator: zone byte ${v} at triangle ${i} is out of range — must be an integer 0..${z.names.length - 1}`);
+    }
+    out[i] = v;
+  }
+  return { names: [...z.names], tri: out };
+}
+
+// ── the in-page bake ─────────────────────────────────────────────────────────
+// Runs inside the browser with three + GLTFLoader importable. Everything it
+// returns is plain JSON (typed arrays as b64).
+
+const PAGE_HTML = `<!doctype html><html><head>
+</head><body><script type="module">
+import { THREE, GLTFLoader } from '/vendor/three-gltf.js';
+window.THREE = THREE; window.GLTFLoader = GLTFLoader; window.__ready = true;
+</script></body></html>`;
+
+// Serialized into the page. `cfg` = { zones, clips } (already parsed).
+async function bakeInPage(page, cfg) {
+  return page.evaluate(async (config) => {
+    const THREE = window.THREE;
+    const notes = [];
+
+    const buf = await (await fetch('/model.glb')).arrayBuffer();
+    const gltf = await new window.GLTFLoader().parseAsync(buf, '/');
+    const scene = gltf.scene;
+    scene.updateMatrixWorld(true);
+
+    // The mesh: the largest SkinnedMesh (a model may carry extras — eyes, teeth).
+    const skinned = [];
+    scene.traverse((o) => { if (o.isSkinnedMesh) skinned.push(o); });
+    if (!skinned.length) return { error: 'no skinned mesh in this GLB — is the model rigged?' };
+    skinned.sort((a, b) => b.geometry.attributes.position.count - a.geometry.attributes.position.count);
+    const sk = skinned[0];
+    if (skinned.length > 1) {
+      notes.push(`model has ${skinned.length} skinned meshes — baked the largest ` +
+        `(${sk.geometry.attributes.position.count} verts); the others are visual-only`);
+    }
+
+    // REST = BIND. skin-hit derives the inverse bind from the rig's rest pose, so
+    // the rest transforms recorded here MUST be the bind pose — not whatever pose
+    // the file happened to save. three's Skeleton.pose() restores exactly that.
+    sk.skeleton.pose();
+    scene.updateMatrixWorld(true);
+
+    const bones = sk.skeleton.bones;
+    const srcIdx = new Map(bones.map((b, i) => [b, i]));
+    const raw = bones.map((b) => ({
+      name: b.name,
+      parent: srcIdx.has(b.parent) ? srcIdx.get(b.parent) : -1,
+      t: [b.position.x, b.position.y, b.position.z],
+      r: [b.quaternion.x, b.quaternion.y, b.quaternion.z, b.quaternion.w],
+      s: [b.scale.x, b.scale.y, b.scale.z],
+    }));
+
+    // Parent-first sort (rig.js poses in one forward pass); remap carried into
+    // skinIndex below. Mirrors sortBonesParentFirst — this copy runs in-page.
+    const order = [];
+    const placed = new Set();
+    for (let guard = 0; order.length < raw.length && guard <= raw.length; guard++) {
+      for (let i = 0; i < raw.length; i++) {
+        if (placed.has(i)) continue;
+        if (raw[i].parent < 0 || placed.has(raw[i].parent)) { order.push(i); placed.add(i); }
+      }
+    }
+    if (order.length !== raw.length) return { error: 'skeleton is not a tree (parent cycle)' };
+    const remap = new Int32Array(raw.length);
+    order.forEach((old, neu) => { remap[old] = neu; });
+    const outBones = order.map((old) => {
+      const b = raw[old];
+      return { name: b.name, parent: b.parent < 0 ? -1 : remap[b.parent], t: b.t, r: b.r, s: b.s };
+    });
+    const boneNames = outBones.map((b) => b.name);
+
+    // Model-space root: from scene origin to the skeleton's parent. The artifact
+    // is baked in the GLB's own space; the GAME places it in the world at runtime
+    // (rig.evaluate's `root`), so the artifact stays game-agnostic.
+    const topBone = bones.find((b) => !srcIdx.has(b.parent)) || bones[0];
+    const rootM = topBone.parent ? topBone.parent.matrixWorld.clone() : new THREE.Matrix4();
+    const rp = new THREE.Vector3(), rq = new THREE.Quaternion(), rs = new THREE.Vector3();
+    rootM.decompose(rp, rq, rs);
+
+    // ── mesh, in scene space at bind pose ────────────────────────────────────
+    const geo = sk.geometry;
+    const V = geo.attributes.position.count;
+    const v3 = new THREE.Vector3();
+    const position = new Float32Array(V * 3);
+    for (let i = 0; i < V; i++) {
+      sk.getVertexPosition(i, v3);           // bind-pose surface (skeleton is posed to bind)
+      position[i * 3] = v3.x; position[i * 3 + 1] = v3.y; position[i * 3 + 2] = v3.z;
+    }
+
+    const si = geo.attributes.skinIndex, sw = geo.attributes.skinWeight;
+    if (geo.attributes.skinIndex1) return { error: 'mesh uses >4 skin influences (skinIndex1) — unsupported' };
+    const inf = si.itemSize;
+    const skinIndex = new Uint16Array(V * inf);
+    const skinWeight = new Float32Array(V * inf);
+    // Through the ACCESSORS, never `.array`: interleaved buffers make `.array`
+    // return neighbouring attributes — silently, with the right length.
+    const get = (attr, i, k) => (k === 0 ? attr.getX(i) : k === 1 ? attr.getY(i) : k === 2 ? attr.getZ(i) : attr.getW(i));
+    for (let v = 0; v < V; v++) {
+      for (let k = 0; k < inf; k++) {
+        skinIndex[v * inf + k] = remap[get(si, v, k)];
+        skinWeight[v * inf + k] = get(sw, v, k);
+      }
+    }
+
+    const idxAttr = geo.index;
+    const index = new Uint32Array(idxAttr ? idxAttr.count : V);
+    if (idxAttr) for (let i = 0; i < idxAttr.count; i++) index[i] = idxAttr.getX(i);
+    else for (let i = 0; i < V; i++) index[i] = i;
+    const T = index.length / 3;
+
+    // ── zones: dominant bone → configured zone, per triangle ─────────────────
+    let zones = null;
+    if (config.zones && Object.keys(config.zones).length) {
+      const names = ['body', ...Object.keys(config.zones)];
+      const match = (name, pattern) => {
+        if (!pattern.includes('*')) return name === pattern;
+        const rx = new RegExp('^' + pattern.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$');
+        return rx.test(name);
+      };
+      const byBone = new Uint8Array(outBones.length);
+      const unmatchedPatterns = [];
+      for (let z = 1; z < names.length; z++) {
+        for (const p of config.zones[names[z]]) {
+          if (!boneNames.some((bn) => match(bn, p))) unmatchedPatterns.push(p);
+        }
+      }
+      if (unmatchedPatterns.length) {
+        return { error: `zone patterns match no bone: ${unmatchedPatterns.join(', ')} — bones are: ${boneNames.join(', ')}` };
+      }
+      boneNames.forEach((bn, i) => {
+        for (let z = 1; z < names.length; z++) {
+          if (config.zones[names[z]].some((p) => match(bn, p))) { byBone[i] = z; return; }
+        }
+      });
+      const zoneTri = new Uint8Array(T);
+      const acc = new Float64Array(outBones.length);
+      for (let t = 0; t < T; t++) {
+        acc.fill(0);
+        for (let k = 0; k < 3; k++) {
+          const v = index[t * 3 + k];
+          for (let j = 0; j < inf; j++) acc[skinIndex[v * inf + j]] += skinWeight[v * inf + j];
+        }
+        let best = 0, bestW = -1;
+        for (let b = 0; b < acc.length; b++) if (acc[b] > bestW) { bestW = acc[b]; best = b; }
+        zoneTri[t] = byBone[best];
+      }
+      const counts = {};
+      names.forEach((n) => { counts[n] = 0; });
+      for (let t = 0; t < T; t++) counts[names[zoneTri[t]]]++;
+      zones = { names, zoneTri, counts };
+    }
+
+    // ── clips: every GLB animation, rotation + position tracks ───────────────
+    const wanted = config.clips ?? null;
+    const clips = {};
+    const rootBoneName = outBones.find((b) => b.parent === -1)?.name;
+    for (const anim of gltf.animations ?? []) {
+      if (wanted && !wanted.includes(anim.name)) continue;
+      const tracks = [];
+      for (const tr of anim.tracks) {
+        const m = tr.name.match(/^(.*)\.(quaternion|position|scale)$/);
+        if (!m) { notes.push(`clip "${anim.name}": skipped unrecognised track ${tr.name}`); continue; }
+        const [, nodeName, prop] = m;
+        if (!boneNames.includes(nodeName)) {
+          notes.push(`clip "${anim.name}": track for "${nodeName}" targets a non-bone node — skipped`);
+          continue;
+        }
+        if (prop === 'scale') {
+          return { error: `clip "${anim.name}" has a SCALE track on bone "${nodeName}". The room's rig is uniform-scale ` +
+            `and cannot reproduce it, so the hit surface would drift off the drawn model. Strip scale tracks in your export.` };
+        }
+        if (prop === 'position' && nodeName === rootBoneName) {
+          notes.push(`clip "${anim.name}": stripped root-motion position track on "${nodeName}" — ` +
+            `the entity's own movement carries the creature; keeping it would apply the motion twice`);
+          continue;
+        }
+        const entry = { bone: nodeName, times: Array.from(tr.times) };
+        if (prop === 'quaternion') entry.rot = Array.from(tr.values);
+        else entry.pos = Array.from(tr.values);
+        tracks.push(entry);
+      }
+      clips[anim.name] = { duration: anim.duration, tracks };
+    }
+
+    // ── pivot: where body.(x,y,z) sits in the model ──────────────────────────
+    // Resolved against the bind-pose bbox of the extracted positions. Mirrors
+    // resolvePivot — this copy runs in-page, because the broadphase radius
+    // below must be measured about the pivot: the runtime centres its sphere on
+    // body, and body IS the pivot point, so a radius measured about the origin
+    // could undersize the sphere and silently reject true edge hits.
+    const bbox = { min: [Infinity, Infinity, Infinity], max: [-Infinity, -Infinity, -Infinity] };
+    for (let i = 0; i < V * 3; i += 3) {
+      for (let a = 0; a < 3; a++) {
+        const c = position[i + a];
+        if (c < bbox.min[a]) bbox.min[a] = c;
+        if (c > bbox.max[a]) bbox.max[a] = c;
+      }
+    }
+    let pivot;
+    {
+      const p = config.pivot;
+      const mid = (a) => (bbox.min[a] + bbox.max[a]) / 2;
+      if (p == null || p === 'origin') pivot = [0, 0, 0];
+      else if (p === 'center') pivot = [mid(0), mid(1), mid(2)];
+      else if (p === 'feet') pivot = [mid(0), bbox.min[1], mid(2)];
+      else if (Array.isArray(p) && p.length === 3 && p.every((n) => Number.isFinite(n))) pivot = [p[0], p[1], p[2]];
+      else return { error: `"pivot" must be "origin", "center", "feet", or [x, y, z] — got ${JSON.stringify(p)}` };
+    }
+
+    // ── broadphase radius: worst case across rest + every baked clip ─────────
+    // The sphere exists to REJECT cheaply, so it must never reject a true hit:
+    // measure every pose the clips can produce, then carry 3% slack (a ray
+    // grazing an extremity is near-tangent, and float error then discards a hit
+    // that visibly connects). Distances are about the pivot — the sphere's
+    // runtime centre.
+    let radius = 0;
+    const measure = () => {
+      scene.updateMatrixWorld(true);
+      sk.skeleton.update?.();
+      for (let i = 0; i < V; i++) {
+        sk.getVertexPosition(i, v3);
+        const d = Math.hypot(v3.x - pivot[0], v3.y - pivot[1], v3.z - pivot[2]);
+        if (d > radius) radius = d;
+      }
+    };
+    measure();                                             // rest pose
+    const mixer = new THREE.AnimationMixer(scene);
+    for (const anim of gltf.animations ?? []) {
+      if (wanted && !wanted.includes(anim.name)) continue;
+      const action = mixer.clipAction(anim);
+      action.play();
+      const STEPS = 24;
+      for (let s = 0; s <= STEPS; s++) {
+        mixer.setTime((anim.duration * s) / STEPS);
+        measure();
+      }
+      action.stop();
+    }
+    sk.skeleton.pose();                                    // back to bind
+    scene.updateMatrixWorld(true);
+    radius *= 1.03;
+
+    // ── weight sanity, while the source is still in hand ─────────────────────
+    let min = Infinity, max = -Infinity, outOfRange = 0, badSums = 0;
+    for (let i = 0; i < skinWeight.length; i++) {
+      const w = skinWeight[i];
+      if (w < min) min = w; if (w > max) max = w;
+      if (w < -1e-4 || w > 1 + 1e-4) outOfRange++;
+    }
+    for (let v = 0; v < V; v++) {
+      let s = 0;
+      for (let k = 0; k < inf; k++) s += skinWeight[v * inf + k];
+      if (Math.abs(s - 1) > 0.02) badSums++;
+    }
+
+    const b64 = (ta) => {
+      const u8 = new Uint8Array(ta.buffer, ta.byteOffset, ta.byteLength);
+      let s = '';
+      const CH = 0x8000;
+      for (let i = 0; i < u8.length; i += CH) s += String.fromCharCode.apply(null, u8.subarray(i, i + CH));
+      return btoa(s);
+    };
+
+    return {
+      notes,
+      root: { t: [rp.x, rp.y, rp.z], r: [rq.x, rq.y, rq.z, rq.w], s: [rs.x, rs.y, rs.z] },
+      pivot,
+      bones: outBones,
+      clips,
+      mesh: {
+        vertexCount: V, triangleCount: T, influences: inf, radius,
+        position: { b64: b64(position) },
+        skinIndex: { b64: b64(skinIndex) },
+        skinWeight: { b64: b64(skinWeight) },
+        index: { b64: b64(index) },
+        ...(zones ? { zones: { names: zones.names, tri: { b64: b64(zones.zoneTri) } } } : {}),
+      },
+      weightCheck: { min, max, outOfRange, badSums },
+      stats: {
+        V, T, inf, radius, bones: outBones.length,
+        clips: Object.keys(clips),
+        ...(zones ? { zoneCounts: zones.counts } : {}),
+      },
+    };
+  }, cfg);
+}
+
+// ── locating the loader bundle (served to the hermetic page) ─────────────────
+// three + GLTFLoader ship VENDORED inside the engine (shared/ui/room/vendor/
+// three-gltf.js, one self-contained ESM file) rather than as a dependency of
+// this CLI — a 2D game must never download three just to own a `joystack` binary.
+// The engine is also the right owner of the version pin: the code that DRAWS
+// models lives there, so the loader that bakes and the loader that draws move
+// together, on engine releases. The bake never touches the network.
+const VENDOR_REL = 'shared/ui/room/vendor/three-gltf.js';
+function engineFile(dir, rel) {
+  const candidates = [
+    // A standalone game: the engine installed under node_modules.
+    join(dir, 'node_modules/@joystack/engine', rel),
+    // This CLI running from inside the engine repo itself.
+    join(import.meta.dirname, '../../..', rel),
+  ];
+  for (const c of candidates) if (existsSync(c)) return c;
+  throw new Error(
+    `the installed engine does not include ${rel} — run \`npx joystack update\` to get a newer engine`,
+  );
+}
+const threeBundle = (dir) => engineFile(dir, VENDOR_REL);
+
+// ── the driver ───────────────────────────────────────────────────────────────
+
+export async function bakeModel(glbPath, { dir = process.cwd(), log = console.log } = {}) {
+  const abs = resolve(glbPath);
+  if (!existsSync(abs)) throw new Error(`no such file: ${glbPath}`);
+  const paths = artifactPaths(abs);
+  const glbBytes = readFileSync(abs);
+  const configText = existsSync(paths.config) ? readFileSync(paths.config, 'utf8') : '';
+  let cfg = {};
+  if (configText) {
+    try { cfg = JSON.parse(configText); } catch (e) {
+      throw new Error(`${basename(paths.config)} is not valid JSON: ${e.message}`);
+    }
+  }
+
+  const { chromium } = await import('playwright');
+  const bundle = threeBundle(dir);
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    const pageErrors = [];
+    page.on('pageerror', (e) => pageErrors.push(e.message));
+    await page.route('**/*', (route) => {
+      const url = new URL(route.request().url());
+      const p = url.pathname;
+      if (p === '/' || p === '/bake.html') return route.fulfill({ contentType: 'text/html', body: PAGE_HTML });
+      if (p === '/model.glb') return route.fulfill({ contentType: 'model/gltf-binary', body: glbBytes });
+      if (p === '/vendor/three-gltf.js') {
+        return route.fulfill({ contentType: 'text/javascript', body: readFileSync(bundle) });
+      }
+      return route.fulfill({ status: 404, body: 'not baked in' });
+    });
+    await page.goto('http://bake.joystack.invalid/bake.html');
+    await page.waitForFunction(() => window.__ready === true, { timeout: 30_000 });
+
+    const baked = await bakeInPage(page, cfg);
+    if (baked.error) {
+      throw new Error(`${baked.error}${pageErrors.length ? `\n(page errors: ${pageErrors.join('; ')})` : ''}`);
+    }
+
+    // ── validate before writing — a bad artifact must never reach the room ───
+    const problems = [];
+    const uni = (s, what) => {
+      const m = Math.max(Math.abs(s[0]), Math.abs(s[1]), Math.abs(s[2])) || 1;
+      if (Math.abs(s[0] - s[1]) / m > 1e-3 || Math.abs(s[0] - s[2]) / m > 1e-3) problems.push(`${what} scale is non-uniform: ${s}`);
+      return (s[0] + s[1] + s[2]) / 3;
+    };
+    const rootS = uni(baked.root.s, 'root');
+    baked.bones.forEach((b, i) => {
+      if (b.parent >= i) problems.push(`bone ${i} ${b.name}: parent ${b.parent} does not precede it`);
+      const L = Math.hypot(...b.r);
+      if (Math.abs(L - 1) > 1e-3) problems.push(`bone ${i} ${b.name}: rotation not unit (${L.toFixed(4)}) — scale left in the matrix`);
+      b.sAvg = uni(b.s, `bone ${i} ${b.name}`);
+    });
+    if (!(baked.mesh.radius > 0)) problems.push('broadphase radius is not positive');
+    const w = baked.weightCheck;
+    if (w.outOfRange > 0) problems.push(`${w.outOfRange} skin weights outside [0,1] (range ${w.min.toFixed(3)}..${w.max.toFixed(3)}) — attributes read wrongly?`);
+    if (w.badSums > 0) problems.push(`${w.badSums} vertices whose weights do not sum to ~1`);
+    if (problems.length) throw new Error(`BAKE INVALID:\n  ${problems.join('\n  ')}`);
+
+    const skeletonJson = {
+      root: { t: baked.root.t, r: baked.root.r, s: rootS },
+      pivot: baked.pivot,
+      bones: baked.bones.map((b) => ({ name: b.name, parent: b.parent, t: b.t, r: b.r, s: b.sAvg })),
+      clips: baked.clips,
+    };
+
+    // ── the generator script, if the config names one ────────────────────────
+    let genText = '';
+    let generatedNames = [];
+    let genZones = null;
+    if (cfg.generate) {
+      const scriptPath = resolve(dirname(abs), cfg.generate);
+      if (!existsSync(scriptPath)) {
+        throw new Error(`${basename(paths.config)} names generate: "${cfg.generate}" but ${scriptPath} does not exist`);
+      }
+      genText = readFileSync(scriptPath, 'utf8');
+      // The hash query re-imports a changed script within one process (node
+      // caches module URLs forever; ensureBaked may bake twice in one run).
+      const mod = await import(`${pathToFileURL(scriptPath).href}?v=${sha256(Buffer.from(genText)).slice(0, 12)}`);
+      if (!mod.clips && !mod.zones) {
+        throw new Error(`generator ${cfg.generate} exports neither clips nor zones — nothing to generate`);
+      }
+      const fromB64 = (Ctor, entry) => {
+        const buf = Buffer.from(entry.b64, 'base64');
+        return new Ctor(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+      };
+      const model = {
+        bones: skeletonJson.bones,
+        clips: baked.clips,
+        mesh: {
+          vertexCount: baked.mesh.vertexCount,
+          triangleCount: baked.mesh.triangleCount,
+          influences: baked.mesh.influences,
+          position: fromB64(Float32Array, baked.mesh.position),
+          skinIndex: fromB64(Uint16Array, baked.mesh.skinIndex),
+          skinWeight: fromB64(Float32Array, baked.mesh.skinWeight),
+          index: fromB64(Uint32Array, baked.mesh.index),
+        },
+      };
+      const boneNames = skeletonJson.bones.map((b) => b.name);
+      if (mod.clips) {
+        const defs = typeof mod.clips === 'function' ? mod.clips(model) : mod.clips;
+        const generated = buildGeneratedClips(defs, boneNames, Object.keys(baked.clips));
+        generatedNames = Object.keys(generated);
+        Object.assign(skeletonJson.clips, generated);
+
+        // The broadphase sphere must contain every pose the LAYERS can reach —
+        // the in-page measure only saw the GLB's own clips. Skin the mesh
+        // through each generated clip alone at weight 1 and add each clip's
+        // worst vertex displacement to the radius. A sum over clips is
+        // deliberately conservative (layers combine): an oversized sphere only
+        // costs broadphase efficiency, an undersized one silently discards
+        // true hits on a flared wing. Weights are expected in [0, 1].
+        const rigLib = await import(pathToFileURL(engineFile(dir, 'shared/ui/room/lib/rig.js')).href);
+        const skinLib = await import(pathToFileURL(engineFile(dir, 'shared/ui/room/lib/skin-hit.js')).href);
+        const rig = rigLib.createRig(skeletonJson);
+        const root = { t: skeletonJson.root.t, r: skeletonJson.root.r, s: skeletonJson.root.s };
+        const skinned = skinLib.createSkinnedMesh({
+          vertexCount: model.mesh.vertexCount, influences: model.mesh.influences,
+          position: model.mesh.position, skinIndex: model.mesh.skinIndex,
+          skinWeight: model.mesh.skinWeight, index: model.mesh.index,
+          invBind: skinLib.restInvBind(rig, root),
+        });
+        const rest = Float32Array.from(skinLib.skin(skinned, rigLib.evaluate(rig, { root })));
+        let inflate = 0;
+        for (const name of generatedNames) {
+          const clip = skeletonJson.clips[name];
+          const STEPS = clip.duration > 0 ? 24 : 1;
+          let worst = 0;
+          for (let s = 0; s <= STEPS; s++) {
+            const t = clip.duration > 0 ? (clip.duration * s) / STEPS : 0;
+            const sample = rigLib.sampleAdditive(rig, name, t, 1);
+            const posed = skinLib.skin(skinned, rigLib.evaluate(rig, { ...sample, root }));
+            for (let v = 0; v < model.mesh.vertexCount * 3; v += 3) {
+              const d = Math.hypot(posed[v] - rest[v], posed[v + 1] - rest[v + 1], posed[v + 2] - rest[v + 2]);
+              if (d > worst) worst = d;
+            }
+          }
+          inflate += worst;
+        }
+        if (inflate > 0) baked.mesh.radius = (baked.mesh.radius + inflate) * 1.03;
+      }
+      if (mod.zones) {
+        if (cfg.zones && Object.keys(cfg.zones).length) {
+          throw new Error(`${basename(paths.config)} has BOTH a "zones" bone-name map and a generator exporting zones() — pick one strategy per model`);
+        }
+        const raw = typeof mod.zones === 'function' ? mod.zones(model) : mod.zones;
+        genZones = validateGeneratedZones(raw, baked.mesh.triangleCount);
+        const b64 = Buffer.from(genZones.tri).toString('base64');
+        baked.mesh.zones = { names: genZones.names, tri: { b64 } };
+        const counts = {};
+        genZones.names.forEach((n) => { counts[n] = 0; });
+        for (const z of genZones.tri) counts[genZones.names[z]]++;
+        baked.stats.zoneCounts = counts;
+      }
+    }
+
+    const source = { hash: sourceHash(glbBytes, configText, genText), glb: basename(abs), bakeVersion: BAKE_VERSION };
+    const note = 'GENERATED by the Joystack model baker — do not hand-edit; edit the GLB or its .bake.json and re-bake.';
+    writeFileSync(paths.skeleton, JSON.stringify({
+      _generated: note,
+      _source: source,
+      ...skeletonJson,
+    }, null, 1) + '\n');
+    writeFileSync(paths.mesh, JSON.stringify({ _generated: note, _source: source, ...baked.mesh }) + '\n');
+
+    const s = baked.stats;
+    log(`baked ${basename(abs)} → ${basename(paths.skeleton)} + ${basename(paths.mesh)}`);
+    log(`  bones ${s.bones}   vertices ${s.V}   triangles ${s.T}   radius ${baked.mesh.radius.toFixed(3)}`);
+    log(`  clips: ${s.clips.length ? s.clips.join(', ') : '(none in this GLB)'}`);
+    if (generatedNames.length) log(`  generated additive clips: ${generatedNames.join(', ')}`);
+    if (s.zoneCounts) log(`  zones: ${Object.entries(s.zoneCounts).map(([k, v]) => `${k} ${v}`).join('  ')}`);
+    for (const n of baked.notes) log(`  note: ${n}`);
+    return { paths, stats: s, notes: baked.notes };
+  } finally {
+    await browser.close();
+  }
+}
+
+// ── auto-bake: the staleness sweep dev/test/publish run ──────────────────────
+// The game's DECLARATION says which models matter: every `src` in `assets.js`
+// that names a `.glb`. Paths there are GAME-ROOT-relative — the same string is
+// the presenter's fetch URL (the page sits at the game root) — so they resolve
+// against the game dir here too. Each declared GLB whose artifacts are missing
+// or stale re-bakes. A bake failure is a real failure, surfaced with the model
+// named and never swallowed: a stale artifact means the server shoots at a shape
+// the player no longer sees.
+//
+// Entity definitions are NOT scanned. A `rig-hitbox.model` is an asset id, so
+// there is no path in an entity.json left to find — and the declaration is the
+// better list anyway, because it also holds models a game loads from its own
+// code, which the entity scan never saw.
+//
+// Read as TEXT rather than imported, by the engine's own reader
+// (`shared/ui/assets/declared.js`) — the same one the entity lint uses, so the
+// two gates cannot disagree about what a game declares. Its blind spot is a
+// computed `src`, which mirrors the one the entity scan had for a computed model
+// reference.
+
+// The reader is passed IN rather than imported: it lives in the engine tree
+// (which the CLI resolves at run time — in a creator's repo it sits under
+// node_modules), and handing it over keeps this function a pure filter over a
+// parse somebody else did.
+export function referencedModels(gameDir, readDeclaration) {
+  const manifest = join(gameDir, 'assets.js');
+  if (!existsSync(manifest) || typeof readDeclaration !== 'function') return [];
+  let declared;
+  try {
+    declared = readDeclaration(readFileSync(manifest, 'utf8'));
+  } catch {
+    return [];                        // unreadable assets.js fails its own gate
+  }
+  const found = new Set();
+  for (const src of declared.sources.values()) {
+    if (/\.glb$/i.test(src)) found.add(resolve(gameDir, src));
+  }
+  return [...found].filter(existsSync);
+}
+
+// The engine's declaration reader, or null when there is no engine to read with.
+async function declarationReader(gameDir) {
+  try {
+    const { dir } = resolveEngine(gameDir);
+    const mod = await import(pathToFileURL(join(dir, 'shared', 'ui', 'assets', 'declared.js')).href);
+    return mod.readDeclaration;
+  } catch {
+    return null;
+  }
+}
+
+export async function ensureBaked({ dir = process.cwd(), log = console.log } = {}) {
+  const models = referencedModels(dir, await declarationReader(dir));
+  const baked = [];
+  for (const glb of models) {
+    if (!isStale(glb)) continue;
+    log(`model ${basename(glb)} changed — re-baking so the server hits the surface you see…`);
+    await bakeModel(glb, { dir, log });
+    baked.push(glb);
+  }
+  return { models, baked };
+}