@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/vendor/verify/src/page/mechanic_check.js

@@ -0,0 +1,272 @@
+// One mechanic check, run inside the page (@funpixel/verify).
+//
+// A single function expression of one argument, so the SAME file is loaded by
+// funpixel-browser (Rust `include_str!`, wrapped as
+// `async () => (FILE)(ARGS_JSON)`) and by local `funtools verify` — one
+// implementation, never two that drift. Arguments are JSON, never spliced into
+// the source.
+//
+// a = { drive: 'key'|'pointer'|'verb', key, code, selector, verb, mode:
+//       'verb'|'input', subject, axis: 'x'|'y', field, times, hold, trace,
+//       settle }
+//
+// Everything happens inside the page, so the before/after reads bracket the
+// drive with no round-trip in between. Two things are read: the declared
+// state field, and — when a subject is named — that object's SCREEN-space
+// position, projected through the live camera by us, not by the game. The
+// sounds started while it ran are counted too, from the log audio.js keeps
+// (`sounds` -1 = no log on this page, which is not observed, never silence).
+async (a) => {
+  // How the check drives the game: the REAL key (keydown on the focused
+  // element or body, so document- and window-level listeners both see it,
+  // then keyup), the REAL on-screen control (pointerdown/up at the element's
+  // centre with a touch pointer), or the declared verb.
+  const drivers = (a) => {
+    if (a.drive === 'key') {
+      return [
+        async () => {
+          const init = { key: a.key, code: a.code, bubbles: true, cancelable: true };
+          const target = document.activeElement || document.body;
+          window.__fpxKeyTarget = target; window.__fpxKeyInit = init;
+          target.dispatchEvent(new KeyboardEvent('keydown', init));
+        },
+        async () => {
+          window.__fpxKeyTarget.dispatchEvent(new KeyboardEvent('keyup', window.__fpxKeyInit));
+        },
+      ];
+    }
+    if (a.drive === 'pointer') {
+      return [
+        async () => {
+          const el = document.querySelector(a.selector);
+          if (!el) throw new Error('no element matches ' + a.selector);
+          const r = el.getBoundingClientRect();
+          const init = { bubbles: true, cancelable: true, pointerId: 1, pointerType: 'touch', isPrimary: true,
+                         clientX: r.left + r.width / 2, clientY: r.top + r.height / 2, button: 0, buttons: 1 };
+          window.__fpxPtrEl = el; window.__fpxPtrInit = init;
+          el.dispatchEvent(new PointerEvent('pointerdown', init));
+        },
+        async () => {
+          window.__fpxPtrEl.dispatchEvent(new PointerEvent('pointerup', { ...window.__fpxPtrInit, buttons: 0 }));
+        },
+      ];
+    }
+    return [
+      async () => {
+        const verb = (window.__FPX_VERBS__ || {})[a.verb];
+        if (typeof verb !== 'function') throw new Error('no such verb');
+        await verb();
+      },
+      async () => {},
+    ];
+  };
+  const raf = () => new Promise(r => requestAnimationFrame(r));
+  const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+  const read = () => {
+    try { return window.__FPX_STATE__(); } catch (e) { return null; }
+  };
+  const subject = a.subject;
+  const axis = a.axis;
+  // The subject's SCREEN position on the chosen axis, read by US:
+  // a DOM element by selector, a Pixi object by .label, or a Three
+  // object by .name projected through the live camera. Screen y
+  // grows DOWN in every branch, so "up" is a decrease.
+  const screenPos = () => {
+    if (!subject) return null;
+    try {
+      if (/^[#.\[]/.test(subject)) {
+        const el = document.querySelector(subject);
+        if (el) {
+          const r = el.getBoundingClientRect();
+          return axis === 'y' ? r.top + r.height / 2 : r.left + r.width / 2;
+        }
+      }
+      const app = window.__PIXI_APP__;
+      if (app && app.stage && typeof app.stage.getChildByLabel === 'function') {
+        const s = app.stage.getChildByLabel(subject, true);
+        if (s && typeof s.getGlobalPosition === 'function') {
+          // A container whose children move (one game: a "kite" container stays at 0,0 while its sail flies) is
+          // where its drawing is: the centre of its world bounds. A leaf is where its position is.
+          if (Array.isArray(s.children) && s.children.length && typeof s.getBounds === 'function') {
+            try {
+              const b = s.getBounds();
+              const w = b.width ?? (b.maxX - b.minX), h = b.height ?? (b.maxY - b.minY);
+              const x0 = b.x ?? b.minX, y0 = b.y ?? b.minY;
+              if (w > 0 && h > 0 && Number.isFinite(x0) && Number.isFinite(y0)) return axis === 'y' ? y0 + h / 2 : x0 + w / 2;
+            } catch (e) { /* fall back to its position */ }
+          }
+          const p = s.getGlobalPosition();
+          return axis === 'y' ? p.y : p.x;
+        }
+      }
+      const scene = window.__THREEJS_SCENE__, cam = window.camera;
+      if (scene && cam && typeof scene.getObjectByName === 'function') {
+        const o = scene.getObjectByName(subject);
+        if (o && o.position && typeof o.getWorldPosition === 'function') {
+          const v = o.getWorldPosition(o.position.clone());
+          v.project(cam);
+          return axis === 'y' ? (1 - v.y) / 2 * innerHeight : (v.x + 1) / 2 * innerWidth;
+        }
+      }
+    } catch (e) {}
+    return null;
+  };
+  // CAN THE PLAYER BE SEEN? A subject can exist, sit at the right
+  // coordinates and move exactly as promised while rendering
+  // nothing: visible=false on it or any ancestor, a material that
+  // never loaded, opacity 0, a scale of 0, or a mesh outside the
+  // frustum. The screen-position read passes every one of those —
+  // a game shipped that way (Stele Run, 2026-09-14), where the
+  // corridor rendered and the runner did not. Returns null when
+  // there is nothing to judge, so "unknown" never reads as "bad".
+  const visibility = () => {
+    if (!subject) return null;
+    try {
+      if (/^[#.\[]/.test(subject)) {
+        const el = document.querySelector(subject);
+        if (!el) return null;
+        const st = getComputedStyle(el);
+        const r = el.getBoundingClientRect();
+        return {
+          found: true,
+          visible: st.display !== 'none' && st.visibility !== 'hidden' && parseFloat(st.opacity || '1') > 0.01,
+          px: Math.round(Math.min(r.width, r.height)),
+          onscreen: r.right > 0 && r.bottom > 0 && r.left < innerWidth && r.top < innerHeight,
+          why: st.display === 'none' ? 'display:none'
+             : st.visibility === 'hidden' ? 'visibility:hidden'
+             : parseFloat(st.opacity || '1') <= 0.01 ? 'opacity 0' : '',
+        };
+      }
+      const app = window.__PIXI_APP__;
+      if (app && app.stage && typeof app.stage.getChildByLabel === 'function') {
+        const o = app.stage.getChildByLabel(subject, true);
+        if (!o) return null;
+        let vis = true, why = '';
+        for (let n = o; n; n = n.parent) {
+          if (n.visible === false) { vis = false; why = n === o ? 'visible=false' : 'an ancestor is visible=false'; break; }
+          if (typeof n.alpha === 'number' && n.alpha <= 0.01) { vis = false; why = n === o ? 'alpha 0' : 'an ancestor has alpha 0'; break; }
+        }
+        let px = 0;
+        try { const b = o.getBounds(); px = Math.round(Math.min(b.width, b.height)); } catch (e) {}
+        return { found: true, visible: vis, px, onscreen: true, why };
+      }
+      const scene = window.__THREEJS_SCENE__, cam = window.camera;
+      if (scene && cam && typeof scene.getObjectByName === 'function') {
+        const o = scene.getObjectByName(subject);
+        if (!o) return null;
+        let vis = true, why = '';
+        for (let n = o; n; n = n.parent) {
+          if (n.visible === false) { vis = false; why = n === o ? 'visible=false' : 'an ancestor is visible=false'; break; }
+        }
+        // A group whose meshes never loaded renders nothing, and
+        // an empty group is the shape a failed GLB fetch leaves.
+        let meshes = 0, opaque = 0;
+        o.traverse((n) => {
+          if (!n.isMesh) return;
+          meshes++;
+          const mats = Array.isArray(n.material) ? n.material : (n.material ? [n.material] : []);
+          if (mats.some((m) => m && (m.opacity === undefined || m.opacity > 0.01) && m.visible !== false)) opaque++;
+        });
+        if (vis && meshes === 0) { vis = false; why = 'no mesh under it — the model may have failed to load'; }
+        else if (vis && opaque === 0) { vis = false; why = 'every material is transparent or invisible'; }
+        // On-screen SIZE, from the world bounding box through the
+        // camera: a subject scaled to nothing is present, moving
+        // and unseeable.
+        let px = 0, onscreen = true, upright_ratio = -1;
+        try {
+          const THREE_ = window.THREE;
+          if (THREE_ && THREE_.Box3 && THREE_.Vector3) {
+            const box = new THREE_.Box3().setFromObject(o);
+            if (!box.isEmpty()) {
+              const pts = [];
+              for (const xs of [box.min.x, box.max.x]) for (const ys of [box.min.y, box.max.y]) for (const zs of [box.min.z, box.max.z]) {
+                const v = new THREE_.Vector3(xs, ys, zs).project(cam);
+                pts.push([(v.x + 1) / 2 * innerWidth, (1 - v.y) / 2 * innerHeight, v.z]);
+              }
+              const xsAll = pts.map((q) => q[0]), ysAll = pts.map((q) => q[1]);
+              const w = Math.max(...xsAll) - Math.min(...xsAll), h = Math.max(...ysAll) - Math.min(...ysAll);
+              px = Math.round(Math.min(w, h));
+              onscreen = pts.some((q) => q[2] > -1 && q[2] < 1)
+                && Math.max(...xsAll) > 0 && Math.min(...xsAll) < innerWidth
+                && Math.max(...ysAll) > 0 && Math.min(...ysAll) < innerHeight;
+              // IS IT THE RIGHT WAY UP? Read from the WORLD box,
+              // not the projected one: a chase camera behind a
+              // runner foreshortens depth, so an upright character
+              // can project wider than tall and a screen-space
+              // read would call it fallen. The world box is the
+              // model's own extent and the camera cannot fool it.
+              const wx = box.max.x - box.min.x;
+              const wy = box.max.y - box.min.y;
+              const wz = box.max.z - box.min.z;
+              const ground = Math.max(wx, wz);
+              // Only humanoids and other tall things have an
+              // opinion about "up". A ball, a car, a tile or a
+              // platform is legitimately wider than it is tall, so
+              // the reading is reported and NEVER judged here —
+              // the caller decides, and only for a named subject.
+              upright_ratio = ground > 0.0001 ? wy / ground : -1;
+            }
+          }
+        } catch (e) {}
+        return { found: true, visible: vis, px, onscreen, why, upright_ratio };
+      }
+    } catch (e) {}
+    return null;
+  };
+  // Sound starts (Web Audio sources + media plays) and per-cue counts, from
+  // audio.js's log; null when it is not installed.
+  const soundMark = () => {
+    const log = window.__FPX_AUDIO_LOG__;
+    return log ? { n: log.starts + log.plays, cues: Object.assign({}, log.cues) } : null;
+  };
+  const soundDelta = (m0) => {
+    const m1 = soundMark();
+    if (!m0 || !m1) return { sounds: -1, sound_cues: '' };
+    const d = Object.keys(m1.cues).map((k) => [k, m1.cues[k] - (m0.cues[k] || 0)]).filter((e) => e[1] > 0)
+      .sort((x, y) => y[1] - x[1] || (x[0] < y[0] ? -1 : 1));
+    return { sounds: m1.n - m0.n, sound_cues: d.slice(0, 3).map((e) => e[0] + ' x' + e[1]).join(', ') };
+  };
+  const [down, up] = drivers(a);
+  const drive = async () => { await down(); await raf(); await sleep(a.hold); await up(); };
+  if (a.mode === 'verb' && typeof (window.__FPX_VERBS__ || {})[a.verb] !== 'function')
+    return JSON.stringify({ ok:false, reason:'no such verb' });
+  const s0 = read();
+  if (!s0 || !((a.field) in s0)) return JSON.stringify({ ok:false, reason:'no such field' });
+  const before = JSON.stringify(s0[a.field]);
+  const screen_before = screenPos();
+  const snd0 = soundMark();
+  // TRACE MODE: the traced value is the subject on screen when one
+  // is named, else the field itself when it is a number. Sampled
+  // once before the input, then on every frame while it is held.
+  const TRACE = a.trace;
+  const series = [];
+  const traced = () => {
+    if (subject) return screenPos();
+    const s = read(); const v = s ? s[a.field] : null;
+    return typeof v === 'number' && isFinite(v) ? v : null;
+  };
+  if (TRACE > 0) {
+    series.push(traced());
+    try { await down(); } catch (e) {
+      return JSON.stringify({ ok:false, reason:'drive threw: ' + (e && e.message ? e.message : String(e)), before });
+    }
+    for (let i = 0; i < TRACE; i++) { await raf(); series.push(traced()); }
+    try { await up(); } catch (e) {}
+    await raf();
+    await sleep(a.settle);
+  } else {
+    for (let i = 0; i < a.times; i++) {
+      try { await drive(); } catch (e) {
+        return JSON.stringify({ ok:false, reason:'drive threw: ' + (e && e.message ? e.message : String(e)), before });
+      }
+      await raf();
+      await sleep(a.settle);
+    }
+  }
+  const s1 = read();
+  const after = JSON.stringify(s1 ? s1[a.field] : null);
+  const screen_after = screenPos();
+  const snd = soundDelta(snd0);
+  return JSON.stringify({ ok:true, before, after, screen_before, screen_after, series, seen: visibility(), sounds: snd.sounds, sound_cues: snd.sound_cues });
+}
+

package/dist/vendor/verify/src/page/moments.js

@@ -0,0 +1,36 @@
+// Moment marks (plan f18): a game calls window.__FPX_MOMENT__(name, weight)
+// at its payoffs — a boss down, a combo, a level cleared — and the capture
+// tour screenshots right then, so the share video lands on the payoff rather
+// than on whatever pixels moved. a = { op: 'install' | 'drain' }.
+//
+// 'install' puts the recorder in place unless the game (or @funpixel/sdk's
+// markMoment, which records the same shape) already did: each call appends
+// { name, weight, t } to window.__FPX_MOMENTS__, at most 64 kept. 'drain'
+// returns what was recorded since the last drain and empties the log,
+// three-state: `observed` false = nothing ever installed a recorder.
+//
+// Part of @funpixel/verify: one function expression of one argument, loaded by
+// funpixel-browser (include_str!) and by local `funtools verify`. See
+// mechanic_check.js for the calling convention.
+(a) => {
+  const w = window;
+  if (a && a.op === 'drain') {
+    const log = w.__FPX_MOMENTS__;
+    if (!Array.isArray(log)) return JSON.stringify({ observed: false, moments: [] });
+    const moments = log.splice(0, log.length).map((m) => ({
+      name: String((m && m.name) || 'moment').slice(0, 40),
+      weight: Math.max(0, Math.min(1, Number(m && m.weight) || 0)),
+      t: Number(m && m.t) || 0,
+    }));
+    return JSON.stringify({ observed: true, moments });
+  }
+  if (!Array.isArray(w.__FPX_MOMENTS__)) w.__FPX_MOMENTS__ = [];
+  if (typeof w.__FPX_MOMENT__ === 'function') return 'already';
+  w.__FPX_MOMENT__ = (name, weight) => {
+    const log = w.__FPX_MOMENTS__;
+    if (!Array.isArray(log)) return;
+    if (log.length >= 64) log.shift();
+    log.push({ name: String(name || 'moment'), weight: weight === undefined ? 1 : Number(weight), t: performance.now() });
+  };
+  return 'installed';
+}

package/dist/vendor/verify/src/page/motion.js

@@ -0,0 +1,139 @@
+// Do the actors come alive, or slide about as stills? (research 16: our best
+// games shipped every character as one PNG moved whole.) Samples the engine's
+// scene graph every `every_ms` for `ms` of play and says, per actor, whether
+// its picture changed (a texture or a sheet frame) or its pose did (scale,
+// rotation, skew, alpha of it or anything under it — a breathe, a squash, a
+// lean, a rigged clip), and whether it moved across the screen. Read-only.
+//
+// Actors are the nodes whose name (Pixi `label`/`name`, Three `name`) matches
+// the player, threat or pickup pattern, as actors.js finds them; a matched
+// node's children are part of it. Pixi (v7, v8) and Three.
+//
+// Part of @funpixel/verify: one function expression of one argument. See
+// mechanic_check.js for the calling convention.
+//
+// a = { player, threats, pickups: regex sources; ms (1000); every_ms (100); max (24) }
+//
+// Answers JSON:
+//   engine   — three | pixi | none; samples — how many were taken
+//   actors   — [{ name, role, moved_px, frames (distinct pictures seen), pose (bool),
+//                verdict: animated | slides | still }]
+//                animated = its picture or pose changed; slides = it moved but
+//                never changed either; still = neither
+//   names    — up to 40 node names seen, so a caller can say what to match
+async (a) => {
+  const MS = a.ms || 1000, EVERY = a.every_ms || 100, MAX = a.max || 24;
+  const player = new RegExp(a.player || 'player|hero|avatar', 'i');
+  const threat = new RegExp(a.threats || 'enemy|enemies|foe|threat|monster|mob|zombie|hazard|boss|creep', 'i');
+  const pickup = new RegExp(a.pickups || 'pickup|coin|gem|collectible|powerup|power-up', 'i');
+  const roleOf = (n) => (!n ? null : player.test(n) ? 'player' : threat.test(n) ? 'threat' : pickup.test(n) ? 'pickup' : null);
+  const out = { engine: 'none', samples: 0, actors: [], names: [] };
+  const seen = new Set();
+  const noteName = (n) => { if (n && !seen.has(n) && seen.size < 40) { seen.add(n); out.names.push(n); } };
+  const EPS = 0.01;
+
+  const app = window.__PIXI_APP__ || (window.__PIXI_DEVTOOLS__ && window.__PIXI_DEVTOOLS__.app) || null;
+  const stage = (app && app.stage) || window.__PIXI_STAGE__ || null;
+  const scene = window.__THREEJS_SCENE__ || (window.scene && window.scene.isScene ? window.scene : null);
+  const cam = window.camera || window.__THREEJS_CAMERA__ || null;
+  const pixi = !!(stage && Array.isArray(stage.children));
+  const three = !pixi && !!(scene && scene.isObject3D);
+  if (!pixi && !three) return JSON.stringify(out);
+  out.engine = pixi ? 'pixi' : 'three';
+
+  // One node's pose numbers and picture key, and its children's, as one list.
+  const pixiLocal = (o) => [o.scale?.x ?? 1, o.scale?.y ?? 1, o.rotation ?? 0, o.skew?.x ?? 0, o.skew?.y ?? 0, o.alpha ?? 1];
+  const pixiPicture = (o) => {
+    const t = o.texture;
+    if (!t) return '';
+    const f = t.frame || {};
+    return `${t.uid ?? t.label ?? (t.baseTexture && t.baseTexture.uid) ?? ''}:${f.x},${f.y},${f.width},${f.height}`;
+  };
+  const threeLocal = (o) => {
+    const q = o.quaternion || {}, s = o.scale || {};
+    const m = o.material && !Array.isArray(o.material) ? o.material : null;
+    return [s.x ?? 1, s.y ?? 1, s.z ?? 1, q.x ?? 0, q.y ?? 0, q.z ?? 0, q.w ?? 1, m ? m.opacity ?? 1 : 1];
+  };
+  const threePicture = (o) => {
+    const m = o.material && !Array.isArray(o.material) ? o.material : null;
+    const t = m && m.map;
+    return t ? `${t.uuid}:${t.offset ? `${t.offset.x},${t.offset.y}` : ''}` : '';
+  };
+  // A matched node's own pose, and its subtree's (children below the root count as pose:
+  // a limb swinging, a bone turning, a child sprite swapping its picture).
+  const read = (o) => {
+    const local = pixi ? pixiLocal : threeLocal, picture = pixi ? pixiPicture : threePicture;
+    const pose = [];
+    const pics = [picture(o)];
+    const walk = (n, depth) => {
+      if (depth > 6) return;
+      for (const c of n.children || []) {
+        if (c.visible === false) continue;
+        pose.push(...local(c));
+        pics.push(picture(c));
+        walk(c, depth + 1);
+      }
+    };
+    walk(o, 0);
+    return { self: local(o), pose, picture: pics.join('|') };
+  };
+
+  let project = null;
+  if (pixi) {
+    project = (o) => { try { const p = o.getGlobalPosition(); return [p.x, p.y]; } catch (e) { return [o.x || 0, o.y || 0]; } };
+  } else {
+    const r = window.__THREEJS_RENDERER__ || window.renderer;
+    const canvas = (r && r.domElement) || document.querySelector('canvas');
+    const rect = canvas ? canvas.getBoundingClientRect() : { width: innerWidth, height: innerHeight };
+    const V = scene.position.constructor;
+    project = (o) => {
+      const e = o.matrixWorld.elements;
+      if (!cam || !cam.isCamera) return [e[12], e[14]];
+      const p = new V(e[12], e[13], e[14]).project(cam);
+      return [((p.x + 1) / 2) * rect.width, ((1 - p.y) / 2) * rect.height];
+    };
+  }
+
+  const tracks = new Map();
+  const sample = () => {
+    if (three) scene.updateMatrixWorld && scene.updateMatrixWorld();
+    const walk = (o, on) => {
+      const shown = on && o.visible !== false && (o.alpha ?? 1) > 0.01;
+      if (!shown) return;
+      const name = o.label || o.name || '';
+      noteName(name);
+      const role = roleOf(name);
+      if (!role) { for (const c of o.children || []) walk(c, shown); return; }
+      let t = tracks.get(o);
+      if (!t) {
+        if (tracks.size >= MAX) return;
+        t = { name, role, first: null, pictures: new Set(), moved: 0, posed: false };
+        tracks.set(o, t);
+      }
+      const r = read(o), at = project(o);
+      if (!t.first) t.first = { at, self: r.self, pose: r.pose };
+      t.moved = Math.max(t.moved, Math.hypot(at[0] - t.first.at[0], at[1] - t.first.at[1]));
+      t.pictures.add(r.picture);
+      const differs = (x, y) => x.length !== y.length || x.some((v, i) => Math.abs(v - y[i]) > EPS);
+      if (differs(r.self, t.first.self) || differs(r.pose, t.first.pose)) t.posed = true;
+    };
+    walk(pixi ? stage : scene, true);
+    out.samples++;
+  };
+
+  const end = performance.now() + MS;
+  sample();
+  while (performance.now() < end) {
+    await new Promise((res) => setTimeout(res, EVERY));
+    sample();
+  }
+  for (const t of tracks.values()) {
+    const moved = Math.round(t.moved);
+    const alive = t.pictures.size > 1 || !!t.posed;
+    out.actors.push({
+      name: t.name, role: t.role, moved_px: moved, frames: t.pictures.size, pose: !!t.posed,
+      verdict: alive ? 'animated' : moved > 2 ? 'slides' : 'still',
+    });
+  }
+  return JSON.stringify(out);
+}