@homie-rocks/studio 0.2.0 → 0.3.0

package/port/bots.ts

@@ -0,0 +1,97 @@
+/*
+ * Bot scaffolds. A port's bots fill every empty seat from the first frame, so
+ * a lone stranger is never alone, and each arriving person takes a bot's body.
+ * What made bots good in real rooms:
+ *
+ *   - They play the SAME rules through the same inputs a person has (a stick
+ *     vector and button presses), never a shortcut the person cannot take.
+ *   - They commit to a target for a while (seconds, not frames) and give up a
+ *     target they cannot reach; a stuck detector (little progress in ~3 s)
+ *     picks the most open direction instead of pushing a wall forever.
+ *   - They are beatable: a reaction delay (~250 ms), a little aim error, and a
+ *     skill that eases off when they lead the people.
+ *   - They are kind to newcomers: no bot targets a person in their first
+ *     ~15 s, and a person's first minute is never a pile-on.
+ *   - A body a person left keeps playing as a bot, where it stands.
+ */
+
+export interface V2 { x: number; y: number }
+
+/** Unit vector from `from` toward `to` (a stick push), or zero when there. */
+export function seek(from: V2, to: V2, arrive = 0): V2 {
+  const dx = to.x - from.x; const dy = to.y - from.y; const d = Math.hypot(dx, dy);
+  if (d <= Math.max(1e-6, arrive)) return { x: 0, y: 0 };
+  const m = arrive > 0 ? Math.min(1, d / (arrive * 3)) : 1;
+  return { x: (dx / d) * m, y: (dy / d) * m };
+}
+
+/** Away from a point (flee), unit length. */
+export function flee(from: V2, danger: V2): V2 { const s = seek(danger, from); return s; }
+
+/** A slowly wandering direction that does not jitter frame to frame. */
+export function wanderer(seed = Math.random() * 1000): (dt: number) => V2 {
+  let a = seed;
+  return (dt) => { a += (Math.random() - 0.5) * 2.4 * dt; return { x: Math.cos(a), y: Math.sin(a) }; };
+}
+
+/** The nearest item by straight distance, skipping ones other bots already claimed. */
+export function nearest<T extends V2>(from: V2, items: Iterable<T>, taken?: Set<T>): T | null {
+  let best: T | null = null; let bd = Infinity;
+  for (const it of items) {
+    if (taken?.has(it)) continue;
+    const d = Math.hypot(it.x - from.x, it.y - from.y);
+    if (d < bd) { bd = d; best = it; }
+  }
+  return best;
+}
+
+/**
+ * A bot's intent with a person's limits: it sees the world `reactionMs` late, commits to a target for `commitMs`,
+ * and notices when it is stuck. Call `think(now, pos, choose)` every frame; it returns the stick to push.
+ */
+export class BotBrain<T extends V2 = V2> {
+  target: T | null = null;
+  private chosenAt = 0;
+  private lastCheck: { at: number; x: number; y: number } | null = null;
+  private unstickUntil = 0;
+  private unstick: V2 = { x: 0, y: 0 };
+  private queue: { at: number; v: V2 }[] = [];
+  constructor(readonly opts: { reactionMs?: number; commitMs?: number; stuckMs?: number; stuckDist?: number; aimError?: number } = {}) {}
+
+  think(now: number, pos: V2, choose: () => T | null, arrive = 0): V2 {
+    const { reactionMs = 250, commitMs = 2500, stuckMs = 3000, stuckDist = 24, aimError = 0.12 } = this.opts;
+    if (!this.target || now - this.chosenAt > commitMs) { this.target = choose(); this.chosenAt = now; }
+    if (!this.lastCheck || now - this.lastCheck.at > stuckMs) {
+      if (this.lastCheck && Math.hypot(pos.x - this.lastCheck.x, pos.y - this.lastCheck.y) < stuckDist && this.target) {
+        const a = Math.random() * Math.PI * 2;
+        this.unstick = { x: Math.cos(a), y: Math.sin(a) };
+        this.unstickUntil = now + 700;
+        this.target = null;
+      }
+      this.lastCheck = { at: now, x: pos.x, y: pos.y };
+    }
+    let v: V2 = now < this.unstickUntil ? this.unstick : this.target ? seek(pos, this.target, arrive) : { x: 0, y: 0 };
+    if (aimError > 0 && (v.x || v.y)) {
+      const a = Math.atan2(v.y, v.x) + (Math.random() - 0.5) * aimError; const m = Math.hypot(v.x, v.y);
+      v = { x: Math.cos(a) * m, y: Math.sin(a) * m };
+    }
+    // Reaction delay: the push decided now is acted on reactionMs later.
+    this.queue.push({ at: now + reactionMs, v });
+    while (this.queue.length && (this.queue[0] as { at: number }).at <= now) this.current = (this.queue.shift() as { v: V2 }).v;
+    return this.current;
+  }
+  private current: V2 = { x: 0, y: 0 };
+
+  /** Forget the target (the round restarted, the bot respawned). */
+  reset(): void { this.target = null; this.queue.length = 0; this.current = { x: 0, y: 0 }; this.lastCheck = null; }
+}
+
+/** Ease bots off when they lead the people: 1 = full skill, down to `floor` when the best bot is far ahead. */
+export function rubberBand(bestBot: number, bestPerson: number, floor = 0.6): number {
+  if (bestBot <= bestPerson) return 1;
+  const lead = (bestBot - bestPerson) / Math.max(1, bestPerson + 3);
+  return Math.max(floor, 1 - lead * 0.5);
+}
+
+/** A person is protected from bots for their first `ms` (default 15 s) in a round. */
+export function protectedNewcomer(joinedAt: number, now: number, ms = 15_000): boolean { return now - joinedAt < ms; }

package/port/camera.ts

@@ -0,0 +1,75 @@
+/*
+ * The camera rules a port keeps (people's hands found every one of these):
+ *
+ * 1. Every direction means the same thing on screen, every second. Read the
+ *    stick and WASD against the CAMERA's screen axes, never the character's
+ *    facing. The classic failure: "back" turns the character toward the lens,
+ *    a chase camera swings round to follow the new heading, and "back" now
+ *    points somewhere else, so the character turns again, forever.
+ * 2. The camera never turns by itself while a direction is held. Its yaw
+ *    changes only for an explicit look input (mouse, look-drag) or at a round
+ *    start. A fixed orientation ("north up") is the safe default for top-down
+ *    and three-quarter games; a slow re-align after rest turned the view 80-90°
+ *    on its own and broke the next presses.
+ * 3. Obstacles between the lens and the player fade; the camera does not jump
+ *    in front of them.
+ * 4. Close enough to read: the player character is big in frame (about 14% of
+ *    a phone's height, 20% of a desktop's), the ground ahead visible. A camera
+ *    pulled far overhead reads as "you are so high above".
+ * 5. No cuts, snaps or re-aims except at a round start or a respawn.
+ *
+ * The checks prove rule 1 and 2: hold a direction 5 s → one straight line and
+ * under 10° of camera yaw; alternate directions for 10 s → every press goes
+ * the pressed way on screen.
+ */
+
+/** Minimal shape of a three.js camera (anything with matrixWorld.elements works). */
+export interface CameraLike { matrixWorld: { elements: ArrayLike<number> }; updateMatrixWorld?: (force?: boolean) => void }
+
+export interface GroundBasis {
+  /** Screen-right on the ground plane, as (x, z). */
+  right: [number, number];
+  /** Screen-up (away from the viewer) on the ground plane, as (x, z). */
+  up: [number, number];
+  /** Camera yaw in degrees: 0 when screen-up is world -z (three.js's default look direction). */
+  yawDeg: number;
+}
+
+const norm = (x: number, z: number): [number, number] => { const l = Math.hypot(x, z) || 1; return [x / l, z / l]; };
+
+/** The camera's screen axes laid on the ground (XZ) plane, from its world matrix. */
+export function groundBasis(camera: CameraLike): GroundBasis {
+  const e = camera.matrixWorld.elements;
+  const right = norm(e[0] as number, e[2] as number);
+  // The camera looks down its local -Z: forward = -(column 2). Straight down, fall back to its local +Y.
+  let up = norm(-(e[8] as number), -(e[10] as number));
+  if (Math.hypot(e[8] as number, e[10] as number) < 1e-4) up = norm(e[4] as number, e[6] as number);
+  return { right, up, yawDeg: (Math.atan2(-up[0], -up[1]) * 180) / Math.PI };
+}
+
+/**
+ * Screen-space input (x right, y DOWN, as keys and the touch stick give it) to a ground direction (x, z) for this
+ * camera. This is THE mapping rule: the same push goes the same way on screen whatever the character faces.
+ */
+export function screenToGround(input: { x: number; y: number }, basis: GroundBasis): { x: number; z: number } {
+  const sx = input.x; const sy = -input.y; // screen up is positive here
+  return { x: basis.right[0] * sx + basis.up[0] * sy, z: basis.right[1] * sx + basis.up[1] * sy };
+}
+
+/**
+ * A yaw the player owns: it moves only by `turn(deg)` (mouse, look-drag) or `set()` at a round start. Use it for
+ * chase and first-person cameras; never feed it the character's heading.
+ */
+export class PlayerYaw {
+  yaw: number;
+  constructor(initialDeg = 0) { this.yaw = initialDeg; }
+  turn(deltaDeg: number): number { this.yaw = ((this.yaw + deltaDeg + 540) % 360) - 180; return this.yaw; }
+  set(deg: number): number { this.yaw = ((deg + 540) % 360) - 180; return this.yaw; }
+  /** Screen-space input to a ground direction (x, z) for this yaw (0 = screen-up is world -z). */
+  toGround(input: { x: number; y: number }): { x: number; z: number } {
+    const a = (this.yaw * Math.PI) / 180;
+    const up: [number, number] = [-Math.sin(a), -Math.cos(a)];
+    const right: [number, number] = [Math.cos(a), -Math.sin(a)];
+    return screenToGround(input, { right, up, yawDeg: this.yaw });
+  }
+}

package/port/controls.ts

@@ -0,0 +1,48 @@
+/*
+ * One input for keys AND touch, in screen space. A port that writes its own
+ * input (rather than letting the touch kit press the game's keys) reads this:
+ *
+ *   const input = createControls({ actions: { jump: ['Space', 'KeyW'] }, touch: { buttons: [{ id: 'jump', label: 'JUMP' }] } });
+ *   const m = input.move();          // x right, y DOWN, length ≤ 1 (WASD, arrows or the stick)
+ *   if (input.pressed('jump')) …     // once per press, from a key or a touch button
+ *
+ * Map `move()` to the world with the camera's screen axes (camera.ts), never
+ * with the character's facing.
+ */
+import { createKeys } from './keys';
+import { createTouchControls, type TouchControls, type TouchOptions } from './touch';
+
+export interface ControlsOptions {
+  /** Action → key codes (desktop) that trigger it. A touch button with the same id triggers it too. */
+  actions?: Record<string, string[]>;
+  touch?: TouchOptions;
+}
+
+export interface Controls {
+  move(): { x: number; y: number };
+  held(action: string): boolean;
+  pressed(action: string): boolean;
+  readonly touch: TouchControls;
+  destroy(): void;
+}
+
+export function createControls(opts: ControlsOptions = {}): Controls {
+  const keys = createKeys();
+  const touch = createTouchControls(opts.touch ?? {});
+  const actions = opts.actions ?? {};
+  return {
+    touch,
+    move() {
+      const k = keys.move(); const s = touch.stick();
+      const x = k.x + s.x; const y = k.y + s.y; const len = Math.hypot(x, y);
+      return len > 1 ? { x: x / len, y: y / len } : { x, y };
+    },
+    held(a) { return touch.held(a) || (actions[a] ?? []).some((c) => keys.down(c)); },
+    pressed(a) {
+      let hit = touch.pressed(a);
+      for (const c of actions[a] ?? []) if (keys.pressed(c)) hit = true;
+      return hit;
+    },
+    destroy() { keys.destroy(); touch.destroy(); },
+  };
+}

package/port/early.ts

@@ -0,0 +1,14 @@
+/*
+ * Import this FIRST in a bundled port (before three.js, before the game):
+ *
+ *   import '@homie-rocks/studio/port/early';
+ *
+ * It makes the sandboxed play frame safe for a single-player game's habits
+ * (localStorage, cookies, gamepads) and arms the first-touch audio unlock.
+ * A static port gets the same from homie-port.js, the first script in <head>.
+ */
+import { installAudioUnlock } from './audio';
+import { installSandboxShims } from './sandbox';
+
+installSandboxShims();
+installAudioUnlock();

package/port/global.ts

@@ -0,0 +1,9 @@
+/*
+ * The same toolkit as one classic script for STATIC ports (games made of
+ * plain <script> tags): `homie-studio build` compiles it to homie-port.js in
+ * the game's folder, and `homie-studio port import` loads it first in <head>.
+ * Everything is on window.HomiePort (HomiePort.createRoom, HomiePort.createTouchControls, …).
+ */
+import * as port from './index';
+
+(window as unknown as { HomiePort: typeof port }).HomiePort = port;

package/port/hud.ts

@@ -0,0 +1,96 @@
+/*
+ * A small room HUD for a port that has none of its own: the round clock
+ * (top-left chip), the top scores (top-right, four rows at most), and the
+ * results card between rounds. Everything is text on small translucent chips;
+ * nothing opaque sits in the middle of the screen during play; names are set
+ * with textContent (people type them). A big screen (a spectator) gets the
+ * same board without any "you".
+ *
+ * A game with its own HUD should draw the same facts itself (clock from
+ * room.clock(), results from room.results()) instead.
+ */
+import type { BodyBase, Room } from './room';
+
+export interface HudOptions {
+  /** What a point is called on the board ("gems", "tiles"). */
+  unit?: string;
+  /** A short controls line shown for the first seconds ("Drag to move · tap to jump"). */
+  hint?: { phone: string; desk: string };
+  /** Accent colour for "you". */
+  accent?: string;
+}
+
+const CSS = `
+.hp-hud{position:fixed;z-index:2147482000;pointer-events:none;font:600 14px/1.25 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;color:#eef1f8;text-shadow:0 1px 2px rgba(0,0,0,.7)}
+.hp-chip{background:rgba(6,9,18,.55);border-radius:10px;padding:5px 9px;backdrop-filter:blur(4px)}
+.hp-clock{left:calc(10px + env(safe-area-inset-left));top:calc(10px + env(safe-area-inset-top))}
+.hp-board{right:calc(10px + env(safe-area-inset-right));top:calc(10px + env(safe-area-inset-top));text-align:right;min-width:92px}
+.hp-board div{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:42vw}
+.hp-board .me{color:var(--hp-accent,#ffd166)}
+.hp-board .bot{opacity:.62}
+.hp-results{left:50%;top:50%;transform:translate(-50%,-50%);min-width:220px;max-width:min(360px,86vw);padding:14px 16px;border-radius:14px;background:rgba(6,9,18,.82)}
+.hp-results h2{margin:0 0 8px;font-size:15px;letter-spacing:.04em;text-transform:uppercase;color:var(--hp-accent,#ffd166)}
+.hp-results ol{margin:0;padding-left:20px}
+.hp-hint{left:50%;bottom:calc(14px + env(safe-area-inset-bottom));transform:translateX(-50%);opacity:.85;transition:opacity .8s}
+@media (max-width:540px){.hp-hud{font-size:13px}}
+`;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createHud<B extends BodyBase>(room: Room<B, any, any>, opts: HudOptions = {}): { destroy(): void } {
+  if (typeof document === 'undefined') return { destroy() {} };
+  const style = document.createElement('style');
+  style.textContent = CSS;
+  document.head.append(style);
+  const mk = (cls: string): HTMLDivElement => { const d = document.createElement('div'); d.className = `hp-hud ${cls}`; return d; };
+  const clock = mk('hp-chip hp-clock');
+  const board = mk('hp-chip hp-board');
+  const results = mk('hp-results');
+  results.style.display = 'none';
+  const hint = mk('hp-chip hp-hint');
+  if (opts.accent) document.documentElement.style.setProperty('--hp-accent', opts.accent);
+  const phone = Math.min(innerWidth, innerHeight) <= 540;
+  const spectator = (): boolean => !room.net.offline && room.net.seat === null;
+  if (opts.hint && !spectator()) hint.textContent = phone ? opts.hint.phone : opts.hint.desk; else hint.style.display = 'none';
+  const mount = (): void => { document.body.append(clock, board, results, hint); };
+  if (document.body) mount(); else document.addEventListener('DOMContentLoaded', mount, { once: true });
+  const bornAt = performance.now();
+  let lastResults = '';
+
+  const paint = (): void => {
+    const c = room.clock();
+    clock.textContent = c.phase === 'none' ? 'Joining…' : c.phase === 'live' ? `Round ${c.n} · ${Math.floor(c.secondsLeft / 60)}:${String(c.secondsLeft % 60).padStart(2, '0')}` : `Next round in ${c.secondsLeft}`;
+    const me = room.mySeat();
+    const rows = room.view().slice().sort((a, b) => b.score - a.score || Number(a.bot) - Number(b.bot)).slice(0, phone ? 4 : 5);
+    board.textContent = '';
+    for (const b of rows) {
+      const d = document.createElement('div');
+      const mine = !spectator() && me !== null && b.seat === me && !b.bot;
+      d.className = mine ? 'me' : b.bot ? 'bot' : '';
+      d.textContent = `${mine ? 'You' : b.name}${b.bot ? ' · bot' : ''}  ${b.score}`;
+      board.append(d);
+    }
+    const r = room.round;
+    if (r && r.phase === 'over' && r.results) {
+      const key = `${r.n}:${r.endsAt}`;
+      if (key !== lastResults) {
+        lastResults = key;
+        results.textContent = '';
+        const h = document.createElement('h2'); h.textContent = `Round ${r.n}`;
+        const ol = document.createElement('ol');
+        for (const row of r.results.slice(0, 6)) {
+          const li = document.createElement('li');
+          const mine = !spectator() && me !== null && row.seat === me && !row.bot;
+          li.textContent = `${mine ? 'You' : row.name}${row.bot ? ' (bot)' : ''} — ${row.score}${opts.unit ? ` ${opts.unit}` : ''}`;
+          if (mine) li.style.color = 'var(--hp-accent,#ffd166)';
+          ol.append(li);
+        }
+        results.append(h, ol);
+      }
+      results.style.display = 'block';
+    } else results.style.display = 'none';
+    if (hint.style.display !== 'none' && performance.now() - bornAt > 9000) hint.style.opacity = '0';
+  };
+  const timer = setInterval(paint, 200);
+  paint();
+  return { destroy() { clearInterval(timer); clock.remove(); board.remove(); results.remove(); hint.remove(); style.remove(); } };
+}

package/port/index.ts

@@ -0,0 +1,29 @@
+/*
+ * @homie-rocks/studio/port — the toolkit the port skill uses to make an existing
+ * single-player web game multiplayer on the netplay contract.
+ *
+ *   early        sandbox shims + first-touch audio (import first)
+ *   createRoom   the host scaffold: bots, join-in-progress, rounds, host migration, snapshots
+ *   createControls / createTouchControls / createKeys / synthKey
+ *                keys on computers, a floating stick and small buttons on phones
+ *   groundBasis / screenToGround / PlayerYaw
+ *                the camera rules: input on screen axes, a yaw only the player turns
+ *   exposePort   what `homie-studio port check` reads (owner tests)
+ *   createHud    a minimal clock / scores / results overlay
+ *   BotBrain, seek, nearest, rubberBand
+ *                bot scaffolds
+ * and everything from @homie-rocks/studio/netplay.
+ */
+import './early';
+
+export * from '../netplay/netplay';
+export { installSandboxShims, sandboxReport, type SandboxReport } from './sandbox';
+export { installAudioUnlock, audioReport } from './audio';
+export { createKeys, synthKey, holdKey, tapKey, keyInfo, releaseAllSynthKeys, type Keys, type Dir } from './keys';
+export { createTouchControls, type TouchControls, type TouchOptions, type TouchButton } from './touch';
+export { createControls, type Controls, type ControlsOptions } from './controls';
+export { groundBasis, screenToGround, PlayerYaw, type GroundBasis, type CameraLike } from './camera';
+export { exposePort, type PortProbeOptions, type View } from './probe';
+export { createRoom, type Room, type RoomOptions, type BodyBase, type RoomSnap, type RoomCkpt } from './room';
+export { createHud, type HudOptions } from './hud';
+export { BotBrain, seek, flee, wanderer, nearest, rubberBand, protectedNewcomer, type V2 } from './bots';

package/port/keys.ts

@@ -0,0 +1,102 @@
+/*
+ * Keys on computers, and keys synthesized from touch on phones.
+ *
+ * Most single-player web games read the keyboard. A port keeps that code and
+ * lets the touch kit press the same keys (a stick held left presses ArrowLeft,
+ * a button presses Space), so the game's own input code stays the one truth.
+ * The synthetic events carry the legacy keyCode/which/charCode too, because
+ * older games (and jQuery) read those rather than `key` or `code`.
+ */
+
+export type Dir = 'left' | 'right' | 'up' | 'down';
+
+const CODES: Record<string, [key: string, keyCode: number]> = {
+  ArrowLeft: ['ArrowLeft', 37], ArrowUp: ['ArrowUp', 38], ArrowRight: ['ArrowRight', 39], ArrowDown: ['ArrowDown', 40],
+  Space: [' ', 32], Enter: ['Enter', 13], Escape: ['Escape', 27], Tab: ['Tab', 9], Backspace: ['Backspace', 8],
+  ShiftLeft: ['Shift', 16], ShiftRight: ['Shift', 16], ControlLeft: ['Control', 17], AltLeft: ['Alt', 18],
+};
+
+/** `key`, `keyCode` for a KeyboardEvent.code ('KeyW', 'Digit1', 'ArrowLeft', 'Space', …). */
+export function keyInfo(code: string): { key: string; keyCode: number } {
+  const known = CODES[code];
+  if (known) return { key: known[0], keyCode: known[1] };
+  const letter = /^Key([A-Z])$/.exec(code);
+  if (letter) return { key: (letter[1] as string).toLowerCase(), keyCode: (letter[1] as string).charCodeAt(0) };
+  const digit = /^Digit([0-9])$/.exec(code);
+  if (digit) return { key: digit[1] as string, keyCode: 48 + Number(digit[1]) };
+  return { key: code, keyCode: 0 };
+}
+
+/** Where synthetic keys go: the focused element (it bubbles to document and window), else the body. */
+function keyTarget(): EventTarget {
+  const a = typeof document !== 'undefined' ? document.activeElement : null;
+  return a && a !== document.documentElement ? a : (document.body ?? document);
+}
+
+const synthDown = new Set<string>();
+
+/** Dispatch one synthetic key event that old and new games both understand. */
+export function synthKey(type: 'keydown' | 'keyup', code: string, target: EventTarget = keyTarget()): void {
+  const { key, keyCode } = keyInfo(code);
+  const ev = new KeyboardEvent(type, { key, code, bubbles: true, cancelable: true, composed: true, repeat: false });
+  for (const [prop, value] of [['keyCode', keyCode], ['which', keyCode], ['charCode', type === 'keydown' ? 0 : 0]] as const) {
+    try { Object.defineProperty(ev, prop, { get: () => value }); } catch { /* read-only on this engine */ }
+  }
+  if (type === 'keydown') synthDown.add(code); else synthDown.delete(code);
+  target.dispatchEvent(ev);
+}
+
+/** Hold `code` down (once) or let it go; no repeats, like a real key held still. */
+export function holdKey(code: string, down: boolean): void {
+  if (down && !synthDown.has(code)) synthKey('keydown', code);
+  else if (!down && synthDown.has(code)) synthKey('keyup', code);
+}
+
+/** A quick press and release (a swipe on a board game, a tap). */
+export function tapKey(code: string, holdMs = 40): void {
+  synthKey('keydown', code);
+  setTimeout(() => synthKey('keyup', code), holdMs);
+}
+
+export function releaseAllSynthKeys(): void { for (const c of [...synthDown]) synthKey('keyup', c); }
+
+/** The keyboard, read directly: WASD and arrows as a move vector, and edges for buttons. */
+export interface Keys {
+  /** Screen-space move: x right, y DOWN, length ≤ 1. */
+  move(): { x: number; y: number };
+  down(code: string): boolean;
+  /** True once per press (consumed). */
+  pressed(code: string): boolean;
+  destroy(): void;
+}
+
+export function createKeys(target: Window | HTMLElement = window): Keys {
+  const held = new Set<string>();
+  const edges = new Set<string>();
+  const kd = (e: Event): void => {
+    const k = e as KeyboardEvent;
+    if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Space'].includes(k.code)) k.preventDefault();
+    if (!held.has(k.code)) edges.add(k.code);
+    held.add(k.code);
+  };
+  const ku = (e: Event): void => { held.delete((e as KeyboardEvent).code); };
+  // A lost focus releases keys (a key-up we never saw would hold a direction forever). It never touches fingers.
+  const blur = (): void => { held.clear(); };
+  target.addEventListener('keydown', kd);
+  target.addEventListener('keyup', ku);
+  window.addEventListener('blur', blur);
+  return {
+    move() {
+      let x = 0; let y = 0;
+      if (held.has('KeyA') || held.has('ArrowLeft')) x -= 1;
+      if (held.has('KeyD') || held.has('ArrowRight')) x += 1;
+      if (held.has('KeyW') || held.has('ArrowUp')) y -= 1;
+      if (held.has('KeyS') || held.has('ArrowDown')) y += 1;
+      const len = Math.hypot(x, y);
+      return len > 1 ? { x: x / len, y: y / len } : { x, y };
+    },
+    down: (code) => held.has(code),
+    pressed(code) { const had = edges.has(code); edges.delete(code); return had; },
+    destroy() { target.removeEventListener('keydown', kd); target.removeEventListener('keyup', ku); window.removeEventListener('blur', blur); },
+  };
+}

package/port/probe.ts

@@ -0,0 +1,126 @@
+/*
+ * What `homie-studio port check` reads inside a ported game: one object on
+ * window.__homiePort, sampled every frame into a ring buffer, so the owner
+ * tests can judge motion on SCREEN axes (the camera's, not the game's):
+ *
+ *   hold a direction 5 s     → one straight line the pressed way, camera yaw change < 10°
+ *   alternate directions 10 s → every press goes the pressed way within 600 ms
+ *
+ * A port calls exposePort() once. `self` is the player's own body on the
+ * ground plane; `basis` is the camera's screen axes on that plane (the default
+ * is a flat 2D view: x right, y down). Board and turn-based games have no body:
+ * they report `lastMove` (the direction the game APPLIED) instead, and the
+ * check presses and swipes and compares.
+ */
+import type { Netplay } from '../netplay/netplay';
+import { audioReport } from './audio';
+import { sandboxReport } from './sandbox';
+
+export type View = 'top' | 'side' | 'first-person' | 'board' | 'maze';
+
+export interface PortProbeOptions {
+  /** top: top-down or three-quarter (all four directions move you); side: a side view (left/right run, up jumps);
+   *  first-person: WASD strafes on the camera's axes; board: no body (grid, cards, puzzle); maze: a top view on
+   *  a grid of corridors whose turns are buffered (a turn into a wall waits for the next opening). */
+  view: View;
+  /** My body's position on the ground plane (2D: canvas x, y with y down; 3D: world x and z). null = no body yet. */
+  self?: () => { x: number; y: number } | null;
+  /** The camera's screen-right and screen-up directions on that plane. Default (2D): right (1,0), up (0,-1). */
+  basis?: () => { right: [number, number]; up: [number, number] };
+  /** About how big a body is, in the same units (a radius or half a width). The checks scale distances by it. */
+  size?: number;
+  /** Board games: the last move the game applied ('left' | 'right' | 'up' | 'down' | any word) and a counter. */
+  lastMove?: () => string | null;
+  moves?: () => number;
+  /** My score right now, if the game has one. */
+  score?: () => number | null;
+  /** True while my body is not mine to steer (knocked back, stunned, dead, respawning): the owner tests skip
+   *  those frames, and the recipe's newcomer rule says it should rarely happen in a person's first seconds. */
+  busy?: () => boolean;
+  /** Anything else worth a look in a receipt (numbers or short strings). */
+  extra?: Record<string, () => unknown>;
+  /** The keys that move you (KeyboardEvent.code). Default: the arrows (WASD for first-person). */
+  keys?: { up: string; down: string; left: string; right: string };
+  /** Where the check puts a thumb for the stick, as screen fractions (default [0.24, 0.74]). */
+  thumb?: [number, number];
+  /** CSS selector of the game's own world when it is HTML (a DOM board, a grid of tiles): the check counts it as
+   *  the world, not as UI covering the screen. A canvas game needs nothing here. */
+  world?: string;
+}
+
+interface PortProbe {
+  v: 1;
+  view: View;
+  size: number;
+  keys: { up: string; down: string; left: string; right: string };
+  thumb: [number, number];
+  world: string | null;
+  /** Rows since `t` (performance.now ms): [t, x, y, rightX, rightY, upX, upY, moves, busy (1/0)]. */
+  rows(since?: number): number[][];
+  now(): number;
+  info(): Record<string, unknown>;
+  errors: string[];
+}
+
+const RING = 4000;
+
+export function exposePort(net: Netplay<unknown, unknown, unknown> | null, opts: PortProbeOptions): PortProbe {
+  const rows: number[][] = [];
+  let frames = 0;
+  const frameTimes: number[] = [];
+  const errors: string[] = [];
+  if (typeof window !== 'undefined') {
+    window.addEventListener('error', (e) => { errors.push(String((e as ErrorEvent).message ?? e).slice(0, 300)); if (errors.length > 50) errors.shift(); });
+    window.addEventListener('unhandledrejection', (e) => { errors.push(`unhandled: ${String((e as PromiseRejectionEvent).reason).slice(0, 300)}`); if (errors.length > 50) errors.shift(); });
+  }
+  const flat = (): { right: [number, number]; up: [number, number] } => ({ right: [1, 0], up: [0, -1] });
+  const basisOf = opts.basis ?? flat;
+  const sample = (t: number): void => {
+    frames += 1;
+    frameTimes.push(t); if (frameTimes.length > 120) frameTimes.shift();
+    let me: { x: number; y: number } | null = null;
+    try { me = opts.self ? opts.self() : null; } catch { me = null; }
+    let b = flat();
+    try { b = basisOf(); } catch { /* keep flat */ }
+    let m = 0;
+    try { m = opts.moves ? Number(opts.moves()) || 0 : 0; } catch { /* ignore */ }
+    let busy = 0;
+    try { busy = opts.busy && opts.busy() ? 1 : 0; } catch { /* ignore */ }
+    rows.push([t, me ? me.x : NaN, me ? me.y : NaN, b.right[0], b.right[1], b.up[0], b.up[1], m, busy]);
+    if (rows.length > RING) rows.splice(0, rows.length - RING);
+  };
+  const loop = (t: number): void => { sample(t); requestAnimationFrame(loop); };
+  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(loop);
+  const probe: PortProbe = {
+    v: 1,
+    view: opts.view,
+    size: opts.size ?? 1,
+    keys: opts.keys ?? (opts.view === 'first-person' ? { up: 'KeyW', down: 'KeyS', left: 'KeyA', right: 'KeyD' } : { up: 'ArrowUp', down: 'ArrowDown', left: 'ArrowLeft', right: 'ArrowRight' }),
+    thumb: opts.thumb ?? [0.24, 0.74],
+    world: opts.world ?? null,
+    rows(since = 0) { return rows.filter((r) => (r[0] as number) >= since); },
+    now: () => performance.now(),
+    info() {
+      const fps = frameTimes.length > 10 ? (frameTimes.length - 1) / (((frameTimes[frameTimes.length - 1] as number) - (frameTimes[0] as number)) / 1000) : null;
+      const extra: Record<string, unknown> = {};
+      for (const [k, f] of Object.entries(opts.extra ?? {})) { try { extra[k] = f(); } catch (e) { extra[k] = `error: ${String(e)}`; } }
+      let lastMove: string | null = null;
+      try { lastMove = opts.lastMove ? opts.lastMove() : null; } catch { /* ignore */ }
+      let score: number | null = null;
+      try { score = opts.score ? opts.score() : null; } catch { /* ignore */ }
+      return {
+        view: opts.view, frames, fps: fps === null ? null : Math.round(fps * 10) / 10,
+        role: net?.role ?? null, seat: net?.seat ?? null, offline: net?.offline ?? null, owned: net?.owned ?? null,
+        round: net?.roundInfo ? { n: net.roundInfo.n, phase: net.roundInfo.phase, endsAt: net.roundInfo.endsAt, leftMs: Math.round(net.roundInfo.endsAt - net.now()) } : null,
+        slots: net?.slots?.map((s) => ({ slot: s.slot, seat: s.seat, bot: s.bot })) ?? null,
+        lastMove, moves: opts.moves ? opts.moves() : null, score,
+        audio: audioReport(), sandbox: sandboxReport(), errors: errors.slice(-10), extra,
+      };
+    },
+    errors,
+  };
+  (window as unknown as { __homiePort: PortProbe }).__homiePort = probe;
+  // The contract's own probes too, so the netplay e2e and any older harness can read this game.
+  try { net?.expose({ self: () => { const s = opts.self?.(); return s ? { x: s.x, y: s.y } : null; }, frames: () => frames }); } catch { /* offline */ }
+  return probe;
+}