@homie-rocks/studio 0.30.2 → 0.31.1

package/lib/characters.mjs

@@ -11,7 +11,7 @@
  *                                   skeleton shares it
  *
  * Both are recorded in assets/manifest.json (the character, kind character or creature; the library, kind clip) with
- * where every clip came from and its licence, so RIGHTS.md, the remix carry-over and `assets check` see them. The model
+ * where every clip came from and its licence, so RIGHTS.md and `assets check` see them. The model
  * names its clip library in its scene's extras (homie.anims), so the game's `loadCharacter(models, url)` finds it.
  *
  *   addCharacter(root, game, { item | file, ... })   in, optimised, clips baked, recorded
@@ -24,8 +24,8 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { LIMITS, checkGlb } from '../assets/safety.mjs';
-import { readManifest, recordAsset } from './asset-manifest.mjs';
-import { VERBS, VERB_IDS, bakeLibrary, findClip, rigOf, writeLibrary } from './clips.mjs';
+import { readManifest, recordAsset, writeManifest } from './asset-manifest.mjs';
+import { VERBS, VERB_IDS, bakeLibrary, findClip, gaitOf, rigOf, writeLibrary } from './clips.mjs';
 import { readDecisions } from './decisions.mjs';
 import { FAMILIES, normaliseRig, skeletonOf, socketBone } from './rig.mjs';
 import { GAME_ID } from './studio.mjs';
@@ -65,7 +65,7 @@ async function docOf(input) {
 /** A clip source (a library item id, or a file): its Document renamed to the standard, and its clip names. */
 async function clipSource(from, { lib = null, cache = new Map() } = {}) {
   if (cache.has(from)) return cache.get(from);
-  let bytes;
+  let bytes; let pack = null;
   if (existsSync(resolve(String(from)))) bytes = readFileSync(resolve(String(from)));
   else {
     const { fetchItemFile, libraryBase, loadIndex } = await import('./library.mjs');
@@ -75,10 +75,14 @@ async function clipSource(from, { lib = null, cache = new Map() } = {}) {
     if (!item) throw new Error(`no library item "${from}" to take clips from`);
     if (item.license !== 'cc0') throw new Error(`${from} is not CC0`);
     ({ bytes } = await fetchItemFile(L, item));
+    // Whose clips these are, kept with the clip library: the credit for them must not depend on a model of the same
+    // pack being in the game (a generated hero borrows the knight's clips and never has a knight).
+    const p = index.packs?.find((x) => x.id === item.pack);
+    pack = { id: item.pack, label: p?.label ?? item.pack, author: item.author ?? null, url: p?.url ?? item.origin ?? null };
   }
   const { doc } = await docOf(bytes);
   normaliseRig(doc, { merge: false, helpers: false, takeClips: false });
-  const src = { from: String(from), doc, rig: rigOf(doc), names: doc.getRoot().listAnimations().map((a) => a.getName()) };
+  const src = { from: String(from), pack, doc, rig: rigOf(doc), names: doc.getRoot().listAnimations().map((a) => a.getName()) };
   cache.set(from, src);
   return src;
 }
@@ -98,7 +102,7 @@ async function pickSources(own, verbs, fallback, opts) {
     if (theirs) sources.push({ rig: fb.rig, anim: fb.doc.getRoot().listAnimations().find((a) => a.getName() === theirs), verb, from: fb.from });
     else missing.push(verb);
   }
-  return { sources, missing, fallbackError: fb?.error ?? null };
+  return { sources, missing, fallbackError: fb?.error ?? null, packs: [own?.pack, fb?.pack].filter(Boolean) };
 }
 
 /** A clip library file's path in a game, for a skeleton. */
@@ -147,7 +151,7 @@ async function bakeFor(root, game, rig, own, verbs, { from = null, lib = null, c
   const fallback = from ?? CLIP_SOURCES[skel.family] ?? null;
   const existing = await existingLibrary(gdir, skel.id);
   const todo = verbs.filter((v) => !existing?.verbs.includes(v));
-  const { sources, missing, fallbackError } = await pickSources(own, todo, fallback, { lib, cache });
+  const { sources, missing, fallbackError, packs: sourcePacks } = await pickSources(own, todo, fallback, { lib, cache });
   const t = await tools();
   const rel = animsPath(skel.id);
   const manifest = readManifest(root, game);
@@ -164,12 +168,16 @@ async function bakeFor(root, game, rig, own, verbs, { from = null, lib = null, c
   writeFileSync(join(gdir, rel), out.bytes);
   const allClips = [...(prev?.clips ?? []).filter((c) => !clips.some((n) => n.verb === c.verb)), ...clips].sort((a, b) => VERB_IDS.indexOf(a.verb) - VERB_IDS.indexOf(b.verb));
   const froms = [...new Set(allClips.map((c) => c.from).filter(Boolean))];
+  const knownPacks = { ...(prev?.from?.packs ?? {}) };
+  for (const p of sourcePacks ?? []) if (froms.some((f) => String(f).startsWith(`${p.id}/`))) knownPacks[p.id] = { label: p.label, author: p.author, url: p.url };
   // Clips taken from CC0 sources (KayKit, Kenney) stay CC0 when retargeted; a character's own clips carry its licence.
-  const lic = license && license.kind !== 'cc0' && allClips.some((c) => c.from && !String(c.from).includes('/')) ? license : { kind: 'cc0', spdx: 'CC0-1.0', owner: null, attribution: null, remix: 'include', notes: `Clips from ${froms.join(', ') || 'the character itself'} (CC0), ${allClips.some((c) => c.retargeted) ? 'retargeted onto this skeleton at build time' : 'as they came'}.` };
+  const lic = license && license.kind !== 'cc0' && allClips.some((c) => c.from && !String(c.from).includes('/')) ? license : { kind: 'cc0', spdx: 'CC0-1.0', owner: null, attribution: null, notes: `Clips from ${froms.join(', ') || 'the character itself'} (CC0), ${allClips.some((c) => c.retargeted) ? 'retargeted onto this skeleton at build time' : 'as they came'}.` };
   const entry = {
     id: entryId, kind: 'clip', tier: 'clip', route: allClips.every((c) => !c.from || String(c.from).includes('/')) ? 'library' : 'imported',
     card: null,
-    from: froms.length ? { library: 'homie-starter', items: froms } : null,
+    // `packs`: each source pack's name, author and page, kept across every later bake (and written by `assets remove`
+    // when a pack's last model leaves), so credits.json can credit the animation for as long as the clips stay.
+    from: froms.length ? { library: 'homie-starter', items: froms, ...(Object.keys(knownPacks).length ? { packs: knownPacks } : {}) } : null,
     files: [{ role: 'clip', path: rel, bytes: out.bytes.length, sha256: sha256(out.bytes) }],
     rig: { family: skel.family, skeleton: skel.id, fingerprint: skel.fingerprint },
     clips: allClips,
@@ -226,7 +234,8 @@ export async function addCharacter(root, game, opts = {}) {
   const raw = skeletonOf(ownDoc);
   if (raw.family === 'none') throw new Error(`${item?.id ?? opts.file} has no skeleton and no moving parts: add it as a prop (assets add without a rig), or rig it first (the animate guide)`);
   normaliseRig(ownDoc, { merge: false, helpers: false, takeClips: false });
-  const own = ownDoc.getRoot().listAnimations().length ? { from: item?.id ?? 'own', doc: ownDoc, rig: rigOf(ownDoc), names: ownDoc.getRoot().listAnimations().map((a) => a.getName()) } : null;
+  const ownPack = item ? { id: item.pack, label: idx?.packs?.find((p) => p.id === item.pack)?.label ?? item.pack, author: item.author ?? null, url: idx?.packs?.find((p) => p.id === item.pack)?.url ?? item.origin ?? null } : null;
+  const own = ownDoc.getRoot().listAnimations().length ? { from: item?.id ?? 'own', pack: ownPack, doc: ownDoc, rig: rigOf(ownDoc), names: ownDoc.getRoot().listAnimations().map((a) => a.getName()) } : null;
 
   // The character as shipped: renamed, helpers out, merged, clips out.
   const { doc } = await docOf(bytes);
@@ -258,7 +267,7 @@ export async function addCharacter(root, game, opts = {}) {
     { what: 'optimise', tool: r.tool, ops: r.ops },
   ];
   const license = item
-    ? { kind: 'cc0', spdx: 'CC0-1.0', owner: item.author ?? null, attribution: null, remix: 'include', notes: `From the Homie starter library (${item.pack}); the pack's own licence text: ${idx?.packs?.find((p) => p.id === item.pack)?.licenseFile ?? 'licenses/'}` }
+    ? { kind: 'cc0', spdx: 'CC0-1.0', owner: item.author ?? null, attribution: null, notes: `From the Homie starter library (${item.pack}); the pack's own licence text: ${idx?.packs?.find((p) => p.id === item.pack)?.licenseFile ?? 'licenses/'}` }
     : { kind: String(opts.license ?? ''), owner: opts.owner ?? (opts.license === 'generated' || opts.license === 'own' ? 'studio' : null), attribution: opts.attribution ?? null, notes: opts.notes ?? (opts.license === 'generated' ? 'Made through fal on the studio\'s own account (a concept image, then Meshy image-to-3D with its auto-rig); its clips are the starter library\'s CC0 clips retargeted onto its skeleton. fal\'s terms do not assign output ownership expressly (RIGHTS.md).' : null) };
   const entry = {
     id, kind, tier: kind === 'creature' ? 'npc' : 'hero', card: opts.card ?? null, route: item ? 'library' : (opts.route === 'generated' ? 'generated' : 'imported'),
@@ -271,7 +280,8 @@ export async function addCharacter(root, game, opts = {}) {
     review: { state: 'auto' },
   };
   const { entry: e, pinned } = recordAsset(root, game, entry);
-  return { ok: true, command: 'assets add', game, asset: e.id, item: item?.id ?? null, route: e.route, raw: opts.rawPath ?? null, license: e.license.kind, model: rel, anims: anims.path, skeleton: rig.skeleton.id, family: rig.skeleton.family, verbs: anims.verbs, missing: anims.missing, clipsFrom: anims.clips.filter((c) => c.retargeted).map((c) => c.from).filter((v, i, a) => a.indexOf(v) === i), merged: rigged.merged, dropped: rigged.dropped, removedHelpers: rigged.removedHelpers.length, before: { tris: r.before.triangles, kb: kb(r.rawBytes), drawCalls: r.before.drawCalls }, after: { tris: after.triangles, kb: kb(r.bytes), heightM: after.heightM, drawCalls: after.drawCalls, bones: after.bones, animsKB: anims.bytes ? kb(anims.bytes) : null }, pinned, warnings: r.warnings, fallbackError: anims.fallbackError };
+  const gait = await recordGait(root, game, e.id).catch(() => null);
+  return { ok: true, command: 'assets add', game, asset: e.id, gait, item: item?.id ?? null, route: e.route, raw: opts.rawPath ?? null, license: e.license.kind, model: rel, anims: anims.path, skeleton: rig.skeleton.id, family: rig.skeleton.family, verbs: anims.verbs, missing: anims.missing, clipsFrom: anims.clips.filter((c) => c.retargeted).map((c) => c.from).filter((v, i, a) => a.indexOf(v) === i), merged: rigged.merged, dropped: rigged.dropped, removedHelpers: rigged.removedHelpers.length, before: { tris: r.before.triangles, kb: kb(r.rawBytes), drawCalls: r.before.drawCalls }, after: { tris: after.triangles, kb: kb(r.bytes), heightM: after.heightM, drawCalls: after.drawCalls, bones: after.bones, animsKB: anims.bytes ? kb(anims.bytes) : null }, pinned, warnings: r.warnings, fallbackError: anims.fallbackError };
 }
 
 /** Whether a library item is a character with a rig or moving parts (assets add sends those here). */
@@ -299,8 +309,91 @@ export async function bakeClips(root, game, asset, { verbs = [], from = null, li
   // The character's own record learns its verbs.
   const fresh = readManifest(root, game);
   const me = fresh.assets.find((x) => x.id === asset);
-  if (me?.rig) { me.rig.verbs = r.verbs; me.measured = { ...(me.measured ?? {}), clips: r.verbs.length }; const { writeManifest } = await import('./asset-manifest.mjs'); writeManifest(root, game, fresh); }
-  return { ok: true, command: 'anim add', game, asset, skeleton: r.skeleton, anims: r.path, verbs: r.verbs, added: want.filter((v) => r.verbs.includes(v)), missing: r.missing, kb: r.bytes ? kb(r.bytes) : null, why: r.fallbackError };
+  if (me?.rig) { me.rig.verbs = r.verbs; me.measured = { ...(me.measured ?? {}), clips: r.verbs.length }; writeManifest(root, game, fresh); }
+  const gait = await recordGait(root, game, asset).catch(() => null);
+  return { ok: true, command: 'anim add', game, asset, gait, skeleton: r.skeleton, anims: r.path, verbs: r.verbs, added: want.filter((v) => r.verbs.includes(v)), missing: r.missing, kb: r.bytes ? kb(r.bytes) : null, why: r.fallbackError };
+}
+
+const clipFile = (x) => (x?.files ?? []).find((f) => f.role === 'clip')?.path ?? null;
+const clipVerbs = (x) => x?.clips?.map((c) => c.verb) ?? x?.measured?.verbs ?? [];
+
+/**
+ * A character's clip libraries, from the manifest: { primary, supplemental, verbs, files, clips }.
+ *
+ *   primary        the clip record whose file the MODEL names (rig.anims), which is what the game loads. Only when no
+ *                  record has that file: the first library of its skeleton that is not declared supplemental.
+ *   supplemental   libraries of the same skeleton that say so ("rig": { "supplemental": true }): more verbs beside the
+ *                  base, which the game loads itself (loadCharacter(models, url, { anims: [base, extra] })).
+ *
+ * It used to be "the last clip record read for that skeleton": a second library of three verbs then stood in for the
+ * first, every original verb read as missing and the previews drew nothing. A second library that is neither named by
+ * the model nor declared is not in anyone's coverage (duplicateLibraries names it).
+ */
+export function librariesFor(manifest, a) {
+  const all = manifest.assets.filter((x) => x.kind === 'clip' && x.rig?.skeleton && x.rig.skeleton === a?.rig?.skeleton);
+  const primary = all.find((x) => a.rig?.anims && clipFile(x) === a.rig.anims) ?? all.find((x) => x.rig?.supplemental !== true) ?? null;
+  const supplemental = all.filter((x) => x !== primary && x.rig?.supplemental === true);
+  const clips = [...(primary?.clips ?? []), ...supplemental.flatMap((x) => (x.clips ?? []).filter((c) => !(primary?.clips ?? []).some((p) => p.verb === c.verb)))];
+  const verbs = [...new Set([...(primary?.clips ? clipVerbs(primary) : a?.rig?.verbs ?? clipVerbs(primary)), ...supplemental.flatMap(clipVerbs)])];
+  return { primary, supplemental, verbs, clips, files: [a?.rig?.anims ?? clipFile(primary), ...supplemental.map(clipFile)].filter(Boolean) };
+}
+
+/**
+ * Clip records that are a SECOND library of a skeleton without saying what they are: Map(asset id -> what to do).
+ * `recordAsset` refuses one at registration; a manifest edited by hand can still hold one, and the check says so.
+ */
+export function duplicateLibraries(manifest) {
+  const out = new Map();
+  const named = new Set(manifest.assets.map((a) => a.rig?.anims).filter(Boolean));
+  const bySkeleton = new Map();
+  for (const x of manifest.assets) if (x.kind === 'clip' && x.rig?.skeleton && x.rig.supplemental !== true) bySkeleton.set(x.rig.skeleton, [...(bySkeleton.get(x.rig.skeleton) ?? []), x]);
+  for (const [skeleton, list] of bySkeleton) {
+    if (list.length < 2) continue;
+    const keep = list.find((x) => named.has(clipFile(x))) ?? list.find((x) => clipFile(x) === animsPath(skeleton)) ?? list[0];
+    for (const x of list) if (x !== keep) out.set(x.id, `a second clip library for the skeleton ${skeleton} (its characters name ${keep.id}'s file): these verbs are in no character's coverage and no preview. Merge them into ${keep.id} (homie-studio anim add <game> <character> --verbs ${clipVerbs(x).join(',') || '…'} --from <this file>), or declare it ("rig": { "supplemental": true }) and load it in the game: loadCharacter(models, url, { anims: [<base>, <this>] })`);
+  }
+  return out;
+}
+
+/** A looping locomotion verb's default ground speed in animate (assets/animate.ts ANIM_TUNING), to compare a rig's against. */
+const DEFAULT_SPEED = { walk: 1.5, run: 4.2 };
+
+/**
+ * How fast a character's walk and run clips move its feet over the ground, measured on ITS rig (the shipped model,
+ * so in metres) from its clip libraries: { walk, run: { mps, seconds, default, feet }, method, note } or null when
+ * neither could be read. A heuristic (lib/clips.mjs gaitOf), cheap enough to run on every bake.
+ */
+export async function measureGait(root, game, assetId) {
+  const m = readManifest(root, game);
+  const a = m.assets.find((x) => x.id === assetId);
+  const model = (a?.files ?? []).find((f) => f.role === 'model');
+  if (!a?.rig || !model) return null;
+  const gdir = join(root, 'games', game);
+  const t = await tools();
+  const read = async (rel) => { const d = await t.io.readBinary(readFileSync(join(gdir, rel))); d.setLogger(t.logger); return d; };
+  const rig = rigOf(await read(model.path));
+  const anims = [];
+  for (const f of librariesFor(m, a).files) if (existsSync(join(gdir, f))) for (const x of (await read(f)).getRoot().listAnimations()) if (!anims.some((y) => y.getName() === x.getName())) anims.push(x);
+  const out = {};
+  for (const verb of ['walk', 'run']) {
+    const anim = anims.find((x) => x.getName() === verb);
+    const g = anim ? gaitOf(rig, anim) : null;
+    if (g) out[verb] = { mps: g.mps, seconds: g.seconds, feet: g.feet, default: DEFAULT_SPEED[verb] };
+  }
+  if (!Object.keys(out).length) return null;
+  return { ...out, method: 'foot bones while down (lowest quarter of each foot\'s height), horizontal speed, averaged', note: 'a guide to start tuning walkSpeed and runSpeed from on this rig; not a verified foot contact' };
+}
+
+/** measureGait, kept on the character's own record (`rig.gait`): the same clips move a taller rig's feet further. */
+export async function recordGait(root, game, assetId) {
+  const gait = await measureGait(root, game, assetId);
+  const m = readManifest(root, game);
+  const a = m.assets.find((x) => x.id === assetId);
+  if (!a?.rig) return gait;
+  if (JSON.stringify(a.rig.gait ?? null) === JSON.stringify(gait)) return gait;
+  if (gait) a.rig.gait = gait; else delete a.rig.gait;
+  writeManifest(root, game, m);
+  return gait;
 }
 
 /** Each character, its skeleton and its clips against the verbs the game needs. */
@@ -308,16 +401,18 @@ export function animPlan(root, game) {
   const m = readManifest(root, game);
   const doc = readDecisions(root, game);
   const need = verbsFor(doc);
-  const libs = new Map(m.assets.filter((a) => a.kind === 'clip').map((a) => [a.rig?.skeleton, a]));
   const rows = m.assets.filter((a) => (a.kind === 'character' || a.kind === 'creature') && a.rig).map((a) => {
-    const L = libs.get(a.rig.skeleton);
-    const have = L?.clips?.map((c) => c.verb) ?? a.rig.verbs ?? [];
+    const libs = librariesFor(m, a);
+    const L = libs.primary ? { ...libs.primary, clips: libs.clips } : null;
+    const have = libs.verbs;
     return {
       id: a.id, kind: a.kind, route: a.route, family: a.rig.family, familyLabel: FAMILIES[a.rig.family]?.label ?? a.rig.family, skeleton: a.rig.skeleton, bones: a.rig.bones, anims: a.rig.anims,
+      // Every library file its clips are in (its own first, then any declared supplemental), and its measured gait.
+      libraries: libs.files, supplemental: libs.supplemental.map((x) => x.id), gait: a.rig.gait ?? null,
       clips: need.map((v) => { const c = L?.clips?.find((x) => x.verb === v); return { verb: v, note: VERBS[v]?.note ?? '', loop: Boolean(VERBS[v]?.loop), have: have.includes(v), source: c?.source ?? null, from: c?.from ?? null, retargeted: Boolean(c?.retargeted), seconds: c?.duration ?? null }; }),
       extra: have.filter((v) => !need.includes(v)),
       missing: need.filter((v) => !have.includes(v)),
-      animsKB: L?.measured?.kb ?? null,
+      animsKB: libs.primary?.measured?.kb ?? null,
     };
   });
   const unrigged = m.assets.filter((a) => (a.kind === 'character' || a.kind === 'creature') && !a.rig).map((a) => a.id);
@@ -356,7 +451,9 @@ export async function animPreview(root, game, { asset = null, verbs = null, size
       const animsFile = join(gdir, row.anims);
       if (!existsSync(animsFile)) { out.push({ id: row.id, verbs: [], why: `${row.anims} is missing` }); continue; }
       const want = verbs ?? row.clips.filter((c) => c.have).map((c) => c.verb).concat(row.extra);
-      const res = await r.frames(modelIn(row.id, model, { anims: readFileSync(animsFile).toString('base64') }), tokens, { verbs: want, count, size, sheet: true, loops: want.filter((v) => VERBS[v]?.loop) });
+      // Its own library, then every declared supplemental one that is on disk: all of them are in the preview.
+      const libraries = [row.anims, ...(row.libraries ?? []).filter((f) => f !== row.anims)].filter((f) => existsSync(join(gdir, f)));
+      const res = await r.frames(modelIn(row.id, model, { anims: libraries.map((f) => readFileSync(join(gdir, f)).toString('base64')) }), tokens, { verbs: want, count, size, sheet: true, loops: want.filter((v) => VERBS[v]?.loop) });
       const files = [];
       for (const v of res.verbs) {
         const file = join(dir, `${row.id}-${v.verb}.webp`);
@@ -370,7 +467,9 @@ export async function animPreview(root, game, { asset = null, verbs = null, size
       }
       let sheet = null;
       if (res.sheet) { sheet = join(dir, `${row.id}-sheet.jpg`); writeFileSync(sheet, dataUrlBytes(res.sheet).bytes); sheet = sheet.slice(root.length + 1); }
-      out.push({ id: row.id, verbs: files, sheet, missing: res.missing });
+      // The ground speed its walk and run cover on this rig, measured again here and kept on its record.
+      const gait = await recordGait(root, game, row.id).catch(() => null);
+      out.push({ id: row.id, verbs: files, sheet, missing: res.missing, libraries, gait });
       log(`${row.id}: ${files.length} preview(s)`);
     }
   }, { log });

package/lib/check.mjs

@@ -15,11 +15,20 @@
  * (up to `rounds` rounds). A person the game lists as a bot while it keeps their seat (an idle player driven by
  * the game's autopilot) is still that person. When no round counts, the result says which seat was missing from
  * each finished round and whether that browser lost its connection, instead of only "no round finished".
+ *
+ * THREE THINGS THAT ARE NOT THE SAME, each reported on its own:
+ *   seated     the shell has a room, a seat and a role (`seats[].seatedMs`)
+ *   ready      the play page's loading cover has lifted, so the game is what is on screen (`readiness[]`, from the
+ *              page's `window.__shell.arrival`). A seated browser drawing 60 frames a second can still be showing
+ *              "Loading the world…": the "playing" picture is only taken, and only named so, once the cover is gone.
+ *   connected  the socket held from the seat to the results (`connection[]`, `uninterrupted`). A round that both
+ *              browsers finished is `ok`; whether one of them reconnected on the way is said beside it, not folded in.
  */
 import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { cpus, loadavg, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SOFTWARE_GL, chromeArgs, findChrome, measureFrames, noChrome } from './chrome.mjs';
+import { reachSite, siteRefusal } from './net.mjs';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -36,6 +45,68 @@ export const CHECK_STEPS = [
 
 class Stopped extends Error {}
 
+/** How long a seated browser is given for its loading cover to lift (the shell lifts it itself 30 s after the page opened). */
+export const READY_TIMEOUT_MS = 35_000;
+
+/**
+ * Is the game on screen? `arrival` is the play page's `window.__shell.arrival` ({ phase, liftedMs, by }) or null.
+ *   ready: true   the cover lifted (`by`: 'game' when the game said it was playable, else the helper or the shell)
+ *   ready: false  still covered after the wait: a picture taken now shows the loading card, not the game
+ *   ready: null   this page reports no arrival state (an older shell, `?arrive=0`): not known, and said so
+ */
+export function arrivalReadiness(arrival, { waitedMs = null } = {}) {
+  if (!arrival || typeof arrival !== 'object') return { ready: null, by: null, liftedMs: null, waitedMs, why: 'this page reports no arrival state: whether the game was on screen is not known' };
+  if (arrival.phase === 'done') return { ready: true, by: arrival.by ?? null, liftedMs: Number.isFinite(arrival.liftedMs) ? arrival.liftedMs : null, waitedMs };
+  return { ready: false, by: null, liftedMs: null, waitedMs, why: `the loading cover was still up${waitedMs !== null ? ` ${Math.round(waitedMs / 1000)} s after the seat` : ''}${arrival.step ? ` ("${String(arrival.step).slice(0, 60)}")` : ''}: seated and drawing is not ready` };
+}
+
+/*
+ * THE LINK (netplay revision 9, NETPLAY.md section 22). The helper says where a browser stands with its room in one
+ * word: `window.__homieNet.link` in the game's frame, and the play page keeps the last change it was told as
+ * `window.__shell.link` = { state, why, hosting }. (`__shell.link` is ALSO the room's invite address, a string,
+ * until the first change arrives: `linkOf` reads either and takes only a state it knows.)
+ *
+ * A browser that is `reconnecting`, `alone`, `offline` or `closed` is not in its room: whatever is sampled there (a
+ * frame, a press, a round that "finished" on a browser hosting by itself) is not two people playing together, and
+ * is labelled, never judged as play.
+ */
+export const LINK_STATES = ['connecting', 'online', 'reconnecting', 'alone', 'offline', 'closed'];
+export const CUT_OFF = ['reconnecting', 'alone', 'offline', 'closed'];
+/** The link's state from whatever a page gave (the helper's word, the shell's { state }), or null: not said. */
+export function linkOf(v) {
+  const state = typeof v === 'string' ? v : v && typeof v === 'object' ? v.state : null;
+  return LINK_STATES.includes(state) ? state : null;
+}
+
+/**
+ * The arrival's facts for a probe, from the play page's `window.__shell.arrival`: who was to say the game is
+ * playable (`mode`: 'auto' the helper, 'game' the game itself, 'seat' an older helper), who gave it the screen
+ * (`by`), when the cover lifted, and when the GAME ITSELF said it was ready (`explicitMs`, the page's clock; null:
+ * it never did), with how long after an automatic lift that was (`lateMs`). Null when the page reports none.
+ */
+export function arrivalFacts(arrival) {
+  if (!arrival || typeof arrival !== 'object') return null;
+  const n = (v) => (Number.isFinite(v) ? Math.round(v) : null);
+  return { mode: ['auto', 'game', 'seat'].includes(arrival.mode) ? arrival.mode : null, by: typeof arrival.by === 'string' ? arrival.by : null, liftedMs: n(arrival.liftedMs), explicitMs: n(arrival.explicitMs), lateMs: n(arrival.lateMs) };
+}
+
+/**
+ * Completion and connection, apart. `connection`: [{ browser, reconnects (null when the page did not say) }].
+ * Returns { reconnects, uninterrupted: true | false | null, note }: one run establishes no cause either way.
+ */
+export function connectionSummary(connection) {
+  const rows = Array.isArray(connection) ? connection : [];
+  const dropped = rows.filter((c) => c.reconnects > 0);
+  const unknown = rows.filter((c) => !Number.isFinite(c.reconnects));
+  // The link states a browser was seen in besides `online` (`cutOff`): a browser seen knocking again or playing
+  // alone was interrupted whether or not its counter moved (and when an older page reports no counter at all).
+  const cut = rows.filter((c) => (c.cutOff ?? []).length && !(c.reconnects > 0));
+  const cutNote = cut.map((c) => `the ${c.browser} was seen cut off from the room (${c.cutOff.join(', ')})`);
+  if (dropped.length || cut.length) return { reconnects: dropped.length ? dropped.reduce((s, c) => s + c.reconnects, 0) : null, uninterrupted: false, note: `${[...dropped.map((c) => `the ${c.browser} reconnected ${c.reconnects} time${c.reconnects === 1 ? '' : 's'}${(c.cutOff ?? []).length ? ` (seen ${c.cutOff.join(', ')})` : ''}`), ...cutNote].join(', ')} during the check: the round finished, the connection did not hold throughout. Run it again; one run does not say why` };
+  if (!rows.length || unknown.length) return { reconnects: null, uninterrupted: null, note: `reconnects were not reported${unknown.length ? ` by the ${unknown.map((c) => c.browser).join(' and the ')}` : ''}: whether the connection held is not known` };
+  return { reconnects: 0, uninterrupted: true, note: 'no reconnects: both connections held from the seat to the results' };
+}
+
 /**
  * WHICH FINISHED ROUND PROVES THE TWO BROWSERS PLAYED TOGETHER. `browsers`: each `{ kind, seats, seen }`, where
  * `seats` is every seat it held (a Set) and `seen` the rounds it saw finish after both were seated (a Map from
@@ -63,6 +134,13 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   const base = String(url).replace(/\/+$/, '');
   const play = `${base}/${game}/play`;
+  // One preflight from this process, in the same words as perf, shoot and port check (lib/net.mjs siteRefusal).
+  // Nothing listening on this computer stops here. Anything else this process was told (a name it cannot look up,
+  // no connection, an error answer) does NOT: a browser may still open a site Node.js cannot (its own DNS, a
+  // firewall that answers a script and a browser differently), and this check drives browsers. If they cannot open
+  // it either, that refusal (for a lookup: BLOCKED, this computer's network, local testing offered) is the report.
+  const cannotAsk = siteRefusal(await reachSite(base, { path: `/${game}/play`, timeout: 15_000 }), { command: 'check', play });
+  if (cannotAsk?.preflight === 'local') return cannotAsk;
   if (shots) mkdirSync(shots, { recursive: true });
   const profiles = [];
   const browsers = [];
@@ -105,7 +183,10 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
       const ua = await browser.userAgent();
       await page.setUserAgent(`${ua} ${userAgentTag}`);
       const t0 = Date.now();
-      await page.goto(play, { waitUntil: 'domcontentloaded', timeout: 90_000 });
+      try { await page.goto(play, { waitUntil: 'domcontentloaded', timeout: 90_000 }); } catch (error) {
+        if (cannotAsk) return { ...cannotAsk, play, why: `${cannotAsk.why} (The ${kind.name} browser could not open it either: ${String(error?.message ?? error).split('\n')[0].slice(0, 120)}.)` };
+        throw error;
+      }
       players.push({ kind: kind.name, page, t0 });
       log(`${kind.name} opened ${play}`);
     }
@@ -150,7 +231,24 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
         if (report?.stopped?.()) break;
       }
     })();
-    if (shots) for (const [i, p] of players.entries()) await p.page.screenshot({ path: join(shots, `${kinds[i].name}-playing.png`) }).catch(() => {});
+    // Ready is not seated: wait for each page's loading cover to lift before the picture called "playing". A browser
+    // still covered when the wait ends gets its picture under another name (-loading.png), so nobody reads a loading
+    // card as gameplay, and `readiness` says so. The check's verdict stays about seats and the round.
+    const readiness = await Promise.all(players.map(async (p, i) => {
+      const t = Date.now(); let arrival = null;
+      const read = () => p.page.evaluate(() => { const a = window.__shell?.arrival; return a ? { phase: a.phase, step: a.step, liftedMs: a.liftedMs, by: a.by } : null; }).catch(() => null);
+      while (Date.now() - t < READY_TIMEOUT_MS) {
+        arrival = await read();
+        if (!arrival || arrival.phase === 'done') break;
+        if (report?.stopped?.()) break;
+        await sleep(250);
+      }
+      const r = { browser: kinds[i].name, ...arrivalReadiness(arrival, { waitedMs: Date.now() - t }) };
+      if (shots) { r.shot = `${kinds[i].name}-${r.ready === false ? 'loading' : 'playing'}.png`; await p.page.screenshot({ path: join(shots, r.shot) }).catch(() => { r.shot = null; }); }
+      if (r.ready === false) log(`${kinds[i].name}: ${r.why}`);
+      return r;
+    }));
+    halt();
     await sleep(1500);
     await picture('Playing: computer and phone in one room');
     // How fast each browser draws the game while it plays (reported, never judged: a VM without a GPU draws
@@ -165,7 +263,7 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
     // person's row as a bot, and that is still the person). A round finished without one of them is a miss: its
     // cause is kept, and the check waits for the next round, up to `rounds` of them.
     const bothSeated = Math.max(...players.map((p) => p.seatedAt));
-    for (const p of players) { p.seats = new Set([p.seat]); p.reconnects = null; p.reconnects0 = null; p.closed = null; p.seen = new Map(); }
+    for (const p of players) { p.seats = new Set([p.seat]); p.reconnects = null; p.reconnects0 = null; p.closed = null; p.seen = new Map(); p.cutOff = new Set(); }
     const t1 = Date.now();
     const budget = roundTimeoutMs * Math.max(1, rounds);
     const missed = new Map();
@@ -174,12 +272,14 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
       for (const p of players) {
         const s = await p.page.evaluate(() => {
           const sh = window.__shell;
-          return sh ? { seat: sh.seat, room: sh.room, closed: sh.closed, reconnects: sh.stats?.reconnects ?? null, results: (sh.results ?? []).map((x) => ({ n: x.n, endsAt: x.endsAt, at: x.at, results: x.results })) } : null;
+          return sh ? { seat: sh.seat, room: sh.room, closed: sh.closed, reconnects: sh.stats?.reconnects ?? null, link: sh.link ?? null, results: (sh.results ?? []).map((x) => ({ n: x.n, endsAt: x.endsAt, at: x.at, results: x.results })) } : null;
         }).catch(() => null);
         if (!s) continue;
         if (Number.isInteger(s.seat)) p.seats.add(s.seat);
         if (Number.isFinite(s.reconnects)) { p.reconnects0 ??= s.reconnects; p.reconnects = s.reconnects; }
         if (s.closed) p.closed = s.closed;
+        // Where it stands with its room right now (the helper's link, as the page was told): anything but in the room is kept.
+        if (CUT_OFF.includes(linkOf(s.link))) p.cutOff.add(linkOf(s.link));
         for (const r of s.results) if (r.at > bothSeated && Array.isArray(r.results) && !p.seen.has(`${r.n}:${r.endsAt}`)) p.seen.set(`${r.n}:${r.endsAt}`, { ...r, room: s.room, ms: Date.now() - p.t0 });
       }
       const before = missed.size;
@@ -192,16 +292,16 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
     playingOn = false;
     await playing.catch(() => {});
     if (shots) for (const [i, p] of players.entries()) await p.page.screenshot({ path: join(shots, `${kinds[i].name}-round-over.png`) }).catch(() => {});
-    const connection = players.map((p) => ({ browser: p.kind, seats: [...p.seats], reconnects: p.reconnects !== null && p.reconnects0 !== null ? p.reconnects - p.reconnects0 : null, closed: p.closed }));
+    const connection = players.map((p) => ({ browser: p.kind, seats: [...p.seats], reconnects: p.reconnects !== null && p.reconnects0 !== null ? p.reconnects - p.reconnects0 : null, closed: p.closed, ...(p.cutOff.size ? { cutOff: [...p.cutOff] } : {}) }));
     const load = { perCore: +(loadavg()[0] / Math.max(1, cpus().length)).toFixed(2), average: +loadavg()[0].toFixed(1), cores: cpus().length };
     if (!hit) {
       const misses = [...missed.values()];
-      const dropped = connection.filter((c) => c.reconnects > 0).map((c) => `the ${c.browser} lost its connection ${c.reconnects} time${c.reconnects === 1 ? '' : 's'}`);
+      const dropped = connection.filter((c) => c.reconnects > 0 || c.cutOff).map((c) => (c.reconnects > 0 ? `the ${c.browser} lost its connection ${c.reconnects} time${c.reconnects === 1 ? '' : 's'}${c.cutOff ? ` (seen ${c.cutOff.join(', ')})` : ''}` : `the ${c.browser} was seen cut off from the room (${c.cutOff.join(', ')})`));
       const why = misses.length
         ? `${misses.length} round${misses.length === 1 ? '' : 's'} finished, and none had both browsers in it: ${misses.map((m) => `round ${m.n} left out the ${m.missing.join(' and the ')}`).join('; ')}.${dropped.length ? ` ${dropped.join(', ')} (a browser silent for 10 s is let go by the relay and its body plays as a bot until it is back).` : ' The game listed that seat\'s body as a bot with no seat: it may hand an idle player to a bot.'}${load.perCore > 1.5 ? ` This computer is busy (load ${load.average} on ${load.cores} cores): run the check again when it is quieter.` : ''}`
         : `no round finished within ${Math.round(budget / 1000)} s of both browsers being seated${load.perCore > 1.5 ? ` (this computer is busy: load ${load.average} on ${load.cores} cores)` : ''}`;
       step('round', 'fail', { note: misses.length ? `${misses.length} round(s) without both` : 'no round finished in time' });
-      return { ok: false, command: 'check', why, play, room: seated[0].room, seated, missed: misses, connection, load, totalMs: Date.now() - started };
+      return { ok: false, command: 'check', why, play, room: seated[0].room, seated, readiness, missed: misses, connection, ...connectionSummary(connection), load, totalMs: Date.now() - started };
     }
     const humans = hit.people;
     step('round', humans >= 2 ? 'pass' : 'fail', { ms: Math.max(...hit.overMs), note: `round ${hit.n}: ${humans} people, ${hit.results.length - humans} bot${hit.results.length - humans === 1 ? '' : 's'}${missed.size ? ` (after ${missed.size} round(s) without both)` : ''}; ${drawn}${software ? ' (software GL: not measurable here)' : ''}` });
@@ -214,7 +314,10 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
       seats: seated.map((s, i) => ({ browser: kinds[i].name, seat: s.seat, role: s.role, seatedMs: s.ms })),
       round: { n: hit.n, humans, bots: hit.results.length - humans, results: hit.results, overMs: hit.overMs },
       ...(missed.size ? { missed: [...missed.values()] } : {}),
+      readiness,
       connection,
+      // Completion (ok) and connection, apart: `uninterrupted` is false when a browser reconnected on the way.
+      ...connectionSummary(connection),
       frames: frames.map((f, i) => ({ browser: kinds[i].name, fps: f.fps, renderer: f.renderer })),
       ...(software ? { software: 'This machine has no GPU (WebGL is SwiftShader): seats, rooms and rounds are measured; the frame rate is not a person\'s.' } : {}),
       why: humans >= 2 ? undefined : `the round's results list ${humans} person(s); both browsers should be in it`,

package/lib/chrome.mjs

@@ -49,6 +49,17 @@ export function findChrome() {
     ?? newestIn(join(home, '.cache', 'ms-playwright'), [['chrome-linux', 'chrome'], ['chrome-linux64', 'chrome']]);
 }
 
+/**
+ * Is this address this computer's own (a local preview)? The play page's shell asks the same of its own hostname
+ * (worker/pages.mjs LOCAL) and leaves the join QR off the big screen there: a code that points at a loopback address
+ * cannot bring another phone in. A check that reads the big screen has to know which kind of site it is looking at.
+ */
+export function isLoopbackUrl(url) {
+  let host;
+  try { host = new URL(String(url)).hostname; } catch { return false; }
+  return /^(localhost|.*\.localhost|127\..*|\[::1\]|0\.0\.0\.0)$/.test(host);
+}
+
 /** Linux without a GPU renders with SwiftShader: say so with every number measured there. */
 export const SOFTWARE_GL = /swiftshader|llvmpipe|softpipe|software/i;
 

package/lib/clips.mjs

@@ -12,6 +12,8 @@
  *   bakeLibrary(to, sources, verbs)      a skeleton's clip library: the target's joints (no mesh) and one clip per verb,
  *                             sampled at 30 fps, constant tracks dropped, quaternions kept continuous
  *   writeLibrary(doc)         resampled and meshopt-compressed bytes, with its measurements
+ *   gaitOf(rig, anim)         how fast a looping walk or run moves its feet over the ground on ONE rig (a heuristic
+ *                             from the foot bones while they are down): the ground speed at which they do not slide
  *
  * Retargeting is plain matrix and quaternion math (three.js's math classes, no renderer), so it runs in Node, in a
  * cloud session and in CI. A clip baked onto a skeleton plays on every character with that skeleton's fingerprint
@@ -163,6 +165,58 @@ function poseAt(rig, channels, t) {
   return world;
 }
 
+/**
+ * How fast a looping, in-place locomotion clip moves its feet over the ground on `rig`, in the rig's world units a
+ * second (metres on a shipped character: its rig carries its scale). While a foot is down it travels backwards under
+ * a body that stays put; the speed it travels at is the ground speed at which that foot does not slide, which is what
+ * animate's `walkSpeed` and `runSpeed` should be for THIS rig. The same clip retargeted onto a taller rig gives a
+ * larger number, so a default tuned on one family is not right for another.
+ *
+ * Deliberately small: each foot counts as down in the lowest quarter of its own height range, and its horizontal
+ * speed is averaged over those frames. No contact solver, no slope, no toe roll: a guide to start tuning from, not a
+ * verified foot contact. `anim` may come from another Document (a clip library): its channels are matched by node
+ * name. Returns { mps, seconds, feet, contact } or null (no foot bones, a foot that never lifts, a clip with no length).
+ */
+export function gaitOf(rig, anim, { fps = 30, feet = ['leftFoot', 'rightFoot'] } = {}) {
+  needThree();
+  const duration = durationOf(anim);
+  if (!(duration > 0)) return null;
+  const ch = new Map();
+  for (const c of anim.listChannels()) {
+    const rec = rig.byName.get(c.getTargetNode()?.getName());
+    if (!rec) continue;
+    if (!ch.has(rec.node)) ch.set(rec.node, {});
+    ch.get(rec.node)[c.getTargetPath()] = c.getSampler();
+  }
+  const recs = feet.map((n) => rig.byName.get(n)).filter(Boolean);
+  if (!recs.length || !ch.size) return null;
+  const frames = Math.max(8, Math.round(duration * fps));
+  const dt = duration / frames;
+  const track = recs.map(() => []);
+  for (let f = 0; f <= frames; f++) {
+    const pose = poseAt(rig, ch, f * dt);
+    recs.forEach((r, i) => { const p = pose.get(r).p; track[i].push([p.x, p.y, p.z]); });
+  }
+  const speeds = []; let down = 0; let all = 0;
+  for (const pts of track) {
+    let lo = Infinity; let hi = -Infinity;
+    for (const p of pts) { lo = Math.min(lo, p[1]); hi = Math.max(hi, p[1]); }
+    // A foot that never leaves the ground has no stance to tell from its swing.
+    if (!(hi - lo > 1e-5)) continue;
+    const line = lo + (hi - lo) * 0.25;
+    let sum = 0; let n = 0;
+    for (let f = 0; f < frames; f++) {
+      all += 1;
+      if (pts[f][1] > line || pts[f + 1][1] > line) continue;
+      sum += Math.hypot(pts[f + 1][0] - pts[f][0], pts[f + 1][2] - pts[f][2]) / dt; n += 1;
+    }
+    down += n;
+    if (n >= 2) speeds.push(sum / n);
+  }
+  if (!speeds.length) return null;
+  return { mps: +(speeds.reduce((a, b) => a + b, 0) / speeds.length).toFixed(2), seconds: +duration.toFixed(3), feet: speeds.length, contact: +(down / Math.max(1, all)).toFixed(2) };
+}
+
 /** A clip's channels by node: Map(node -> { rotation, translation, scale } samplers). */
 function channelsOf(anim) {
   const out = new Map();