@homie-rocks/studio 0.2.0 → 0.5.0

package/netplay/netplay.ts

@@ -254,6 +254,17 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
   readonly spectator: boolean;
   readonly offline: boolean;
   readonly connected: boolean;
+  /** Why the client stopped for good (a refusal reconnecting would repeat: 'replaced', 'room-full', ...), else null. */
+  readonly closedWhy: string | null;
+  /** How long the socket has been down while it reconnects (ms; 0 while connected). */
+  readonly downMs: number;
+  /**
+   * Host: hand the room to another browser — a checkpoint, then the protocol's `yield` (the same road a hidden
+   * tab takes). The relay elects the best other candidate, or keeps me host when nobody else can host.
+   * Use it when a big screen or a struggling phone should give the room to a seated computer (never in a
+   * host's first 30 s, at most once a minute); false when not sent.
+   */
+  handOff(): boolean;
   /** Seated replica: true while my browser moves my body; false while the host does (host movement, or taken). */
   readonly owned: boolean;
   readonly id: string | null;
@@ -476,8 +487,26 @@ export class Roster {
 /* --------------------------------------------------------------- the client */
 
 const LADDER = [250, 500, 1000, 2000, 4000];
-/** Relay errors after which reconnecting would only repeat the refusal. */
-const FINAL_ERRORS = new Set(['replaced', 'version', 'room-full', 'too-many', 'flood']);
+/**
+ * Relay errors after which reconnecting would only repeat the refusal. A 'flood' kick is NOT one: a replica's
+ * inputs bunch up behind a stall it did not cause (a host migration, a relay or network hiccup that delivers a
+ * second of frames at once), and a kick that ended the page's play for good left a phone frozen with no word.
+ * After one it comes back (its seat token keeps its body), sending at the slow rate below.
+ */
+const FINAL_ERRORS = new Set(['replaced', 'version', 'room-full', 'too-many']);
+/**
+ * Input pacing (NETPLAY.md §5): at most this many `in` frames in any rolling second from this browser, whatever
+ * the frame rate or the press rate: two thirds of the relay's cap of 60, so frames that reach it bunched (a
+ * stall anywhere between) still fit under the cap.
+ */
+const IN_CAP_PER_S = 32;
+/** Longest a page with a live socket listens for the relay's welcome before it plays alone (ms of time it could listen). */
+const CONNECT_OPEN_MAX_MS = 10_000;
+/** After the relay reports dropped inputs (or kicked this browser for them): the cap for the next while. */
+const IN_SLOW_CAP_PER_S = 15;
+const IN_SLOW_MS = 8000;
+/** A socket with this much still unsent does not queue another input frame (the newest one waits instead). */
+const IN_BACKLOG_BYTES = 2048;
 
 function heldList(held: Iterable<string> | Record<string, boolean> | undefined): string[] {
   if (!held) return [];
@@ -606,6 +635,13 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   let prevHeld = new Set<string>();
   let pendingPresses: Record<string, number> = {};
   let inputTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Wall times of the input frames sent in the last second, and until when the slow cap holds. */
+  const inSent: number[] = [];
+  let inSlowUntil = 0;
+  /** Why this client stopped for good (a FINAL_ERRORS refusal), or null while it plays or reconnects. */
+  let closedWhy: string | null = null;
+  /** Wall time the socket went down (0 while connected): how long a reconnect has taken. */
+  let downSince = 0;
   const sentHist: { q: number; a: A; h: string[]; at: number; r: number }[] = [];
   const inputs = new Map<number, InputFrame<A>>();
   const presses = new Map<number, Record<string, number>>();
@@ -798,12 +834,15 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       }
       case 'error': {
         const code = String(m['code'] ?? '');
+        // Inputs over the relay's cap were dropped: send fewer for a while (the newest frame still goes out).
+        if ((code === 'rate' && m['of'] === 'in') || code === 'flood') inSlowUntil = wall() + IN_SLOW_MS;
         if (code === 'rate' || code === 'state-full') { warnOnce(`${code}:${String(m['of'] ?? '')}`, m['message']); return; }
         console.warn('[netplay] relay refused:', code, m['message']);
         // The same seat opened in another tab, a full room, a version the relay does not speak: reconnecting
         // would repeat the refusal (or, for 'replaced', make the two tabs evict each other for ever).
         if (FINAL_ERRORS.has(code)) {
           closed = true;
+          closedWhy = code;
           post?.({ what: 'closed', why: code });
         }
         return;
@@ -846,6 +885,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (next === 'host' && !snap && !continuing) snap = localSnap();
     offline = false;
     connected = true;
+    downSince = 0;
     attempt = 0;
     emit('status', true);
     post?.({ what: 'token', token, seat, room: cfg?.room ?? null });
@@ -897,10 +937,14 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
         if (ages.length > 40) ages.shift();
         const sorted = [...ages].sort((x, y) => x - y);
         ageP90 = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.9))] as number;
+        // The 95th percentile and 1.4 intervals, not the 90th and 1.2. A phone host's frame
+        // quantisation (snapshots at 50/67 ms) plus 30-50 ms relay jitter held the picture on 5-8 % of a desktop
+        // replica's frames in the contract e2e (interpolation-not-starved); this buys ~20 ms of delay for it.
+        const ageP95 = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))] as number;
         // Render far enough back that the next snapshot is normally here before we need it: its age, plus one
         // interval. Rise up to 6 ms a snapshot (a hold is visible); fall 6% of the excess a snapshot, at least 3 ms
         // (boot-time jank clears in about a second, as a brief time-warp nobody sees).
-        const target = Math.max(50, Math.min(400, ageP90 + iv * 1.2 + 4));
+        const target = Math.max(50, Math.min(400, ageP95 + iv * 1.4 + 6));
         if (!delaySmooth || ages.length <= 3) delaySmooth = target;
         else if (target > delaySmooth) delaySmooth += Math.min(6, target - delaySmooth);
         else delaySmooth -= Math.min(delaySmooth - target, Math.max(3, (delaySmooth - target) * 0.06));
@@ -1010,9 +1054,24 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     raw({ t: 'ckpt', k: c.k, st: c.st, d: c.d, c: c.c });
   }
 
+  /** How long until one more input frame fits the rolling-second cap (0: now). */
+  function inputBudgetWait(): number {
+    const t = wall();
+    while (inSent.length && (inSent[0] as number) <= t - 1000) inSent.shift();
+    const cap = t < inSlowUntil ? IN_SLOW_CAP_PER_S : IN_CAP_PER_S;
+    if (inSent.length < cap) return 0;
+    return Math.max(1, (inSent[inSent.length - cap] as number) + 1000 - t);
+  }
+
   function flushInput(): void {
     inputTimer = null;
     if (role === 'host' || seat === null || offline || !connected || pendingA === undefined) return;
+    // Never a burst: over the cap, or with the last frames still unsent on the socket, the newest frame waits
+    // (it replaces whatever was pending, so nothing stale is ever flushed after a stall).
+    const budget = inputBudgetWait();
+    const backlog = (ws?.bufferedAmount ?? 0) > IN_BACKLOG_BYTES;
+    if (budget > 0 || backlog) { inputTimer = setTimeout(flushInput, backlog ? Math.max(budget, 30) : budget); return; }
+    inSent.push(wall());
     inSeq += 1;
     const msg: Record<string, unknown> = { t: 'in', q: inSeq, a: pendingA, h: pendingHeld, r: mine.rs };
     if (Object.keys(pendingPresses).length) msg['p'] = pendingPresses;
@@ -1026,7 +1085,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
 
   function scheduleInput(urgent: boolean): void {
     const since = wall() - lastInputSentAt;
-    const wait = urgent ? Math.max(0, 16 - since) : Math.max(0, inputMs - since);
+    const wait = Math.max(inputBudgetWait(), urgent ? Math.max(0, 16 - since) : Math.max(0, inputMs - since));
     if (wait <= 0) { if (inputTimer) { clearTimeout(inputTimer); inputTimer = null; } flushInput(); return; }
     if (inputTimer) return;
     inputTimer = setTimeout(flushInput, wait);
@@ -1071,6 +1130,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (why !== 'closed') { try { sock.close(4000, why); } catch { /* gone */ } }
     const was = connected;
     connected = false;
+    if (was) downSince = wall();
     if (was) emit('status', false);
     notifyStats(true);
     retry();
@@ -1106,8 +1166,24 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   } else {
     post?.({ what: 'attached', v: NETPLAY_VERSION });
     open();
-    // A relay that never answers must not leave a game on a black screen.
-    connectTimer = setTimeout(() => { if (!roleKnown) goOfflineHost('relay-timeout'); }, connectTimeoutMs);
+    // A relay that never answers must not leave a game on a black screen. But the wait is counted only while
+    // this page is able to listen: a phone compiling shaders under load is blocked for seconds at a time, and
+    // neither its socket's open nor the relay's welcome can be handled meanwhile. Giving up on the wall clock
+    // started a private fight 1 at every loaded boot and swapped it for the room's a moment later. A socket
+    // that is connecting or open gets CONNECT_OPEN_MAX_MS of that listening time; one that failed outright
+    // (ws is null between retries) gets connectTimeoutMs.
+    let listenedMs = 0;
+    let lastCheckAt = wall();
+    const connectCheck = (): void => {
+      if (roleKnown) return;
+      const t = wall();
+      listenedMs += Math.min(t - lastCheckAt, 600);
+      lastCheckAt = t;
+      const live = Boolean(ws && (ws.readyState === 0 || ws.readyState === 1));
+      if (listenedMs < (live ? CONNECT_OPEN_MAX_MS : connectTimeoutMs)) { connectTimer = setTimeout(connectCheck, 250); return; }
+      goOfflineHost('relay-timeout');
+    };
+    connectTimer = setTimeout(connectCheck, 250);
     pingTimer = setInterval(ping, 2000);
     ckptTimer = setInterval(sendCheckpoint, checkpointMs);
     statsTimer = setInterval(() => notifyStats(true), 500);
@@ -1133,6 +1209,8 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     get spectator() { return seat === null && !offline; },
     get offline() { return offline; },
     get connected() { return connected; },
+    get closedWhy() { return closedWhy; },
+    get downMs() { return connected || !downSince ? 0 : wall() - downSince; },
     get owned() { return role === 'host' || offline || seat === null ? true : mine.own; },
     get id() { return id; },
     get name() { return name; },
@@ -1161,8 +1239,10 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       const c = ctlWire();
       const text = JSON.stringify(c.length ? { t: 'snap', k: tick, st, d, c } : { t: 'snap', k: tick, st, d });
       if (!ws || ws.readyState !== 1) return false;
-      // A congested socket drops a snapshot rather than queueing a stale one.
-      if ((ws.bufferedAmount ?? 0) > 256 * 1024) return false;
+      // A congested socket drops a snapshot rather than queueing a stale one. At 3 KB (about six
+      // snapshots), not 256 KB. A starved network thread on a loaded phone held a second of snapshots and then
+      // flushed them at once; the relay counted 30+ in a second, dropped them, and called the host stalled.
+      if ((ws.bufferedAmount ?? 0) > 3 * 1024) return false;
       try { ws.send(text); } catch { return false; }
       countBytes(bytesOut, text.length);
       lastSnapSentAt = wall();
@@ -1173,6 +1253,11 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       return true;
     },
     checkpointNow: sendCheckpoint,
+    handOff() {
+      if (role !== 'host' || offline || !connected || peers.size < 2) return false;
+      sendCheckpoint();
+      return raw({ t: 'yield' });
+    },
     round(r) {
       roundInfo = r;
       post?.({ what: 'round', round: r });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.2.0",
-  "description": "A game studio on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, the site Worker with public rooms (Table/Lobby Durable Objects, D1, R2), deploy, and the homie.rocks directory.",
+  "version": "0.5.0",
+  "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), song and video pages from the music/ and videos/ manifests, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
   "homepage": "https://homie.rocks/studio/",
@@ -18,6 +18,14 @@
       "types": "./netplay/netplay.ts",
       "default": "./netplay/netplay.ts"
     },
+    "./port": {
+      "types": "./port/index.ts",
+      "default": "./port/index.ts"
+    },
+    "./port/early": {
+      "types": "./port/early.ts",
+      "default": "./port/early.ts"
+    },
     "./worker": "./worker/index.mjs",
     "./package.json": "./package.json"
   },
@@ -25,8 +33,10 @@
     "bin/",
     "lib/",
     "netplay/",
+    "port/",
     "worker/",
     "starters/",
+    "media/",
     "README.md",
     "LICENSE",
     "NOTICE"

package/port/audio.ts

@@ -0,0 +1,96 @@
+/*
+ * Sound that starts on the first touch, with no "tap for sound" screen.
+ *
+ * Browsers start every AudioContext suspended and refuse media.play() until a
+ * person has touched the page. A single-player game usually handled that with
+ * a title screen; a multiplayer port drops the player straight into a live
+ * round, so the unlock has to ride the first real input instead:
+ *
+ *   - every AudioContext the game makes is remembered (the constructor is
+ *     wrapped, so install this BEFORE the game's code runs);
+ *   - on pointerdown / pointerup / touchstart / touchend / keydown / click
+ *     (capture phase, so a game that stops propagation still unlocks), every
+ *     suspended context is resumed inside the gesture and plays one silent
+ *     sample (iOS needs a sound started inside the gesture);
+ *   - a media element whose play() was refused is played again on that gesture;
+ *   - iOS's silent switch mutes Web Audio unless the audio session says
+ *     "playback".
+ * A held stick only counts as a gesture when the finger lifts (browsers grant
+ * activation on touchend), so the first tap or the first release is when sound
+ * begins. Say so nowhere: it just works.
+ */
+
+type Ctx = AudioContext;
+const contexts = new Set<Ctx>();
+const refused = new Set<HTMLMediaElement>();
+let installed = false;
+let unlockedAt = 0;
+let gestures = 0;
+
+function silentTick(ctx: Ctx): void {
+  try {
+    const b = ctx.createBuffer(1, 1, 22050);
+    const s = ctx.createBufferSource();
+    s.buffer = b;
+    s.connect(ctx.destination);
+    s.start(0);
+  } catch { /* a closed context */ }
+}
+
+function onGesture(): void {
+  gestures += 1;
+  for (const ctx of contexts) {
+    if (ctx.state === 'closed') { contexts.delete(ctx); continue; }
+    if (ctx.state !== 'running') { void ctx.resume().catch(() => {}); silentTick(ctx); }
+  }
+  for (const el of [...refused]) {
+    refused.delete(el);
+    const p = realPlay?.call(el);
+    if (p && typeof p.catch === 'function') p.catch(() => { refused.add(el); });
+  }
+  if (!unlockedAt && [...contexts].some((c) => c.state === 'running')) unlockedAt = performance.now();
+}
+
+let realPlay: (() => Promise<void>) | null = null;
+
+/** Wrap AudioContext and media play() so the first gesture unlocks everything. Idempotent. */
+export function installAudioUnlock(): void {
+  if (installed || typeof window === 'undefined') return;
+  installed = true;
+  const w = window as unknown as Record<string, unknown>;
+  for (const name of ['AudioContext', 'webkitAudioContext']) {
+    const Real = w[name] as (new (...a: unknown[]) => Ctx) | undefined;
+    if (typeof Real !== 'function') continue;
+    // A subclass keeps instanceof, static members and every method; it only remembers the instance.
+    const Tracked = class extends (Real as new (...a: unknown[]) => Ctx) {
+      constructor(...args: unknown[]) { super(...args); contexts.add(this as unknown as Ctx); }
+    };
+    try { Object.defineProperty(window, name, { value: Tracked, configurable: true, writable: true }); } catch { /* keep the real one */ }
+  }
+  try {
+    const session = (navigator as unknown as { audioSession?: { type: string } }).audioSession;
+    if (session) session.type = 'playback';
+  } catch { /* not iOS */ }
+  if (typeof HTMLMediaElement !== 'undefined') {
+    realPlay = HTMLMediaElement.prototype.play;
+    const play = realPlay;
+    HTMLMediaElement.prototype.play = function patchedPlay(this: HTMLMediaElement): Promise<void> {
+      const p = play.call(this);
+      if (!p || typeof p.catch !== 'function') return p;
+      // Refused for want of a gesture: it plays on the first one. Any other failure is the game's to see.
+      return p.catch((e: unknown) => {
+        if (e && (e as { name?: string }).name === 'NotAllowedError') { refused.add(this); return undefined; }
+        throw e;
+      }) as Promise<void>;
+    };
+  }
+  for (const ev of ['pointerdown', 'pointerup', 'touchstart', 'touchend', 'mousedown', 'keydown', 'click']) {
+    window.addEventListener(ev, onGesture, { capture: true, passive: true });
+  }
+  document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') for (const c of contexts) if (c.state === 'suspended' && gestures) void c.resume().catch(() => {}); });
+}
+
+/** What the check harness reads: each context's state, and when the first one started running. */
+export function audioReport(): { contexts: string[]; refusedMedia: number; gestures: number; unlockedAtMs: number | null } {
+  return { contexts: [...contexts].map((c) => c.state), refusedMedia: refused.size, gestures, unlockedAtMs: unlockedAt || null };
+}

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;