@myvillage/cli 2.6.1 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.6.1",
+  "version": "2.8.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/assets/game-toolkit/myvillage-game.js

@@ -0,0 +1,434 @@
+// MyVillage Game Bridge — the "mvgame" protocol (v2).
+//
+// ONE contract for every MyVillage game, on every surface:
+//   - muni mobile app  (React Native WebView)
+//   - the web          (mvp-video-games, in an iframe)
+//   - MVP Studio preview and standalone `npm run dev`
+//
+// Two calls every game makes:
+//   MyVillageGame.ready()                // once, when your game is interactive
+//   MyVillageGame.complete({ score })    // when the game is finished / won / over
+//
+// One the host ALWAYS provides, but you can trigger too:
+//   MyVillageGame.exit()                 // leave the game
+//
+// Real-time multiplayer (optional) — see "Multiplayer" below:
+//   const mp = await MyVillageGame.multiplayer({ arena, game: 'my-game' });
+//   await mp.quickMatch();              // or mp.host() / mp.join(code)
+//   const net = await mp.connect();     // live match (src/myvillage-realtime.js)
+//
+// The host always renders an Exit control, so a player can leave ANY game at
+// any time even if the game never calls exit() itself.
+//
+// This file is part of the platform. Do not edit it — `myvillage` CLI updates
+// replace it.
+
+const PROTOCOL = 'mvgame';
+const HOST_PROTOCOL = 'mvgame-host';
+const VERSION = 2;
+
+const hasWindow = typeof window !== 'undefined';
+const inReactNative = hasWindow && !!window.ReactNativeWebView;
+const inIframe = hasWindow && window.parent && window.parent !== window;
+const standalone = hasWindow && !inReactNative && !inIframe;
+
+function now() {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+function post(message) {
+  const payload = { source: PROTOCOL, version: VERSION, ...message };
+  const json = JSON.stringify(payload);
+  try {
+    // React Native WebView (muni mobile app)
+    if (inReactNative) window.ReactNativeWebView.postMessage(json);
+    // Iframe parent (mvp-video-games web host)
+    if (inIframe) {
+      window.parent.postMessage(payload, '*');
+      // The web player also listens for the older Unity WebGL names.
+      if (message.type === 'ready') window.parent.postMessage({ type: 'GAME_STARTED' }, '*');
+      if (message.type === 'complete') window.parent.postMessage({ type: 'GAME_COMPLETED', score: message.score }, '*');
+    }
+    if (standalone) {
+      // MVP Studio's preview relays window messages whose type starts with "mvgame".
+      window.postMessage({ ...payload, type: PROTOCOL + ':' + message.type }, '*');
+      console.info('[mvgame] (no host attached) ' + json);
+    }
+  } catch (e) {
+    console.warn('[mvgame] postMessage failed', e);
+  }
+}
+
+// ── Host context ────────────────────────────────────────────────────────────
+// Hosts that support multiplayer hand the game a context:
+//   { apiBase, game, playToken, platform, player: { displayName } }
+// either up front (window.__MYVILLAGE_HOST__) or in reply to our "hello":
+//   { source: 'mvgame-host', type: 'init', context: {...} }
+
+let hostContext = null;
+const hostWaiters = [];
+
+function acceptHost(ctx) {
+  if (!ctx || typeof ctx !== 'object' || hostContext) return;
+  if (typeof ctx.apiBase !== 'string' || typeof ctx.playToken !== 'string' || typeof ctx.game !== 'string') return;
+  hostContext = {
+    apiBase: ctx.apiBase.replace(/\/+$/, ''),
+    game: ctx.game,
+    playToken: ctx.playToken,
+    platform: typeof ctx.platform === 'string' ? ctx.platform : 'webgl',
+    player: { displayName: (ctx.player && ctx.player.displayName) || 'Player' },
+  };
+  while (hostWaiters.length) hostWaiters.shift()(hostContext);
+}
+
+function onHostMessage(event) {
+  let data = event && event.data;
+  if (typeof data === 'string') {
+    try {
+      data = JSON.parse(data);
+    } catch (_) {
+      return;
+    }
+  }
+  if (data && data.source === HOST_PROTOCOL && data.type === 'init') acceptHost(data.context || data);
+}
+
+if (hasWindow) {
+  if (window.__MYVILLAGE_HOST__) acceptHost(window.__MYVILLAGE_HOST__);
+  window.addEventListener('message', onHostMessage);
+  // React Native WebView on Android delivers postMessage on document.
+  if (typeof document !== 'undefined') document.addEventListener('message', onHostMessage);
+}
+
+/** Ask the host for its context; resolves null when there's no capable host. */
+function requestHostContext(timeoutMs) {
+  if (hostContext) return Promise.resolve(hostContext);
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (ctx) => {
+      if (done) return;
+      done = true;
+      clearInterval(retry);
+      clearTimeout(timer);
+      resolve(ctx);
+    };
+    hostWaiters.push(finish);
+    const hello = () => post({ type: 'hello', wants: ['multiplayer'] });
+    hello();
+    const retry = setInterval(hello, 500);
+    const timer = setTimeout(() => finish(null), timeoutMs);
+  });
+}
+
+// ── Multiplayer ─────────────────────────────────────────────────────────────
+//
+// The platform does the plumbing; your game owns the lobby UI. A typical flow:
+//
+//   const mp = await MyVillageGame.multiplayer({ arena, game: 'my-game' });
+//   const match = await mp.quickMatch();     // or mp.host({ visibility: 'village' }) / mp.join('K7PQ2M')
+//   showCode(match.code);
+//   const stop = mp.watch((m) => renderPlayers(m.players));
+//   const net = await mp.connect();          // ArenaClient from src/myvillage-realtime.js
+//   // each frame: net.controls = {...}; net.update(dt); draw(net.view, net.others());
+//
+// Inside the muni app / web player, matches go through the MyVillage platform
+// (real players, village-only quick match, MVT on completion). Standalone —
+// `npm run dev` or the Studio preview — there is no platform session, so it
+// runs in DEV MODE against the public staging match server: open two browser
+// tabs and use the same code (or both press quick match) to play yourself.
+
+const DEFAULT_DEV_SERVER = 'https://myvillage-realtime-staging.myvillage-realtime.workers.dev';
+const CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+
+export class MultiplayerError extends Error {
+  constructor(code, message, status) {
+    super(message);
+    this.name = 'MultiplayerError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+function randomCode() {
+  let s = '';
+  for (let i = 0; i < 6; i++) s += CODE_ALPHABET[Math.floor(Math.random() * CODE_ALPHABET.length)];
+  return s;
+}
+
+function normalizeCode(code) {
+  return String(code || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
+}
+
+function devPlayerId() {
+  const key = 'mvgame.devPlayerId';
+  try {
+    let id = localStorage.getItem(key);
+    if (!id) {
+      id = 'dev-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 10);
+      localStorage.setItem(key, id);
+    }
+    return id;
+  } catch (_) {
+    return 'dev-' + Math.random().toString(36).slice(2, 12);
+  }
+}
+
+class Multiplayer {
+  constructor(ctx, options) {
+    this.mode = ctx ? 'platform' : 'dev';
+    this._ctx = ctx;
+    this._opts = options;
+    this._net = null;
+    this._ticket = null;
+    /** The current match (see MatchView in the platform docs), or null. */
+    this.match = null;
+    this.me = { displayName: ctx ? ctx.player.displayName : options.name || 'Player ' + randomCode().slice(0, 3) };
+  }
+
+  // ── lobby plumbing ──
+
+  /** Host a match. visibility: 'private' (code only) or 'village' (listed + quick match). */
+  async host({ visibility = 'private', maxPlayers, lobby } = {}) {
+    if (this.mode === 'dev') return this._devMatch(randomCode(), true, lobby);
+    return this._enter(await this._api('POST', `/api/v1/games/${this._game()}/matches`, { visibility, maxPlayers, lobby, platform: this._ctx.platform }));
+  }
+
+  /** Join a match by its code (forgiving: "abc-234" works). */
+  async join(code) {
+    if (this.mode === 'dev') return this._devMatch(normalizeCode(code), false);
+    return this._enter(await this._api('POST', `/api/v1/games/${this._game()}/matches/join`, { code, platform: this._ctx.platform }));
+  }
+
+  /** Join the fullest open match in the player's villages, or host one. */
+  async quickMatch({ lobby } = {}) {
+    // Finished match rooms can't be reused, so dev quick match rotates rooms
+    // every 10 minutes; tabs that press it within the same window meet.
+    if (this.mode === 'dev') return this._devMatch('QUICK' + Math.floor(Date.now() / 600000).toString(36).toUpperCase(), false, lobby);
+    return this._enter(await this._api('POST', `/api/v1/games/${this._game()}/matches/quick`, { platform: this._ctx.platform, lobby }));
+  }
+
+  /** Open village matches the player can join, plus matches they're in. */
+  async list() {
+    if (this.mode === 'dev') return this.match ? [this.match] : [];
+    return (await this._api('GET', `/api/v1/games/${this._game()}/matches`)).matches;
+  }
+
+  /** Re-read the current match (players, host, lobby state). */
+  async refresh() {
+    if (!this.match || this.mode === 'dev') return this.match;
+    this.match = (await this._api('GET', `/api/v1/matches/${this.match.id}`)).match;
+    return this.match;
+  }
+
+  /**
+   * Call `onChange(match)` whenever the match changes (polls every
+   * `intervalMs`). Returns a function that stops watching.
+   */
+  watch(onChange, intervalMs = 2000) {
+    let last = '';
+    let stopped = false;
+    const tick = async () => {
+      if (stopped || !this.match) return;
+      try {
+        const m = await this.refresh();
+        const key = JSON.stringify(m);
+        if (key !== last) {
+          last = key;
+          onChange(m);
+        }
+      } catch (e) {
+        console.warn('[mvgame] match refresh failed', e);
+      }
+    };
+    tick();
+    const timer = this.mode === 'dev' ? null : setInterval(tick, intervalMs);
+    return () => {
+      stopped = true;
+      if (timer) clearInterval(timer);
+    };
+  }
+
+  /** Host only: store game-defined lobby state (teams, map pick, ...). Max 4 KB. */
+  async setLobby(lobby) {
+    return this._update({ lobby });
+  }
+
+  /** Host only: stop new players joining. */
+  async lock() {
+    return this._update({ status: 'in_progress' });
+  }
+
+  /** Host only: let players join again. */
+  async unlock() {
+    return this._update({ status: 'open' });
+  }
+
+  /** Host only: cancel the match for everyone. */
+  async cancel() {
+    return this._update({ status: 'cancelled' });
+  }
+
+  /** Leave the match (and disconnect). The host role passes to another player. */
+  async leave() {
+    const match = this.match;
+    if (this._net) this._net.close();
+    this._net = null;
+    this._ticket = null;
+    this.match = null;
+    if (match && this.mode === 'platform') await this._api('POST', `/api/v1/matches/${match.id}/leave`);
+  }
+
+  // ── live match ──
+
+  /**
+   * Connect to the live match and return a connected ArenaClient
+   * (src/myvillage-realtime.js). Call again after a disconnect to rejoin.
+   */
+  async connect() {
+    if (!this.match) throw new MultiplayerError('no_match', 'Host, join or quick match first.');
+    const ticket = await this._freshTicket();
+    const { ArenaClient } = await import('./myvillage-realtime.js');
+    const net = new ArenaClient({ wsUrl: ticket.wsUrl, ticket: ticket.ticket });
+    await net.connect();
+    this._ticket = null; // single use: a reconnect fetches a fresh one
+    this._net = net;
+    return net;
+  }
+
+  // ── internals ──
+
+  _game() {
+    return encodeURIComponent(this._ctx.game);
+  }
+
+  async _api(method, path, body) {
+    const res = await fetch(this._ctx.apiBase + path, {
+      method,
+      headers: { Authorization: 'Bearer ' + this._ctx.playToken, 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    let data = {};
+    try {
+      data = await res.json();
+    } catch (_) {
+      // non-JSON error page
+    }
+    if (!res.ok) throw new MultiplayerError(data.code || 'http_' + res.status, data.error || 'Request failed (' + res.status + ')', res.status);
+    return data;
+  }
+
+  _enter(result) {
+    this.match = result.match;
+    this._ticket = result.realtime;
+    return this.match;
+  }
+
+  async _update(body) {
+    if (!this.match) throw new MultiplayerError('no_match', 'Not in a match.');
+    if (this.mode === 'dev') {
+      if (body.lobby !== undefined) this.match = { ...this.match, lobby: body.lobby };
+      return this.match;
+    }
+    this.match = (await this._api('PATCH', `/api/v1/matches/${this.match.id}`, body)).match;
+    return this.match;
+  }
+
+  async _freshTicket() {
+    if (this._ticket && new Date(this._ticket.expiresAt).getTime() - Date.now() > 30000) return this._ticket;
+    if (this.mode === 'platform') {
+      return (await this._api('POST', `/api/v1/matches/${this.match.id}/ticket`)).realtime;
+    }
+    const server = (this._opts.devServer || DEFAULT_DEV_SERVER).replace(/\/+$/, '');
+    const res = await fetch(server + '/dev/ticket', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        matchId: this.match.id,
+        name: this.me.displayName,
+        villagerId: devPlayerId(),
+        game: this._opts.game || 'dev-game',
+        arena: this._opts.arena,
+      }),
+    });
+    if (!res.ok) throw new MultiplayerError('dev_server_unavailable', 'Dev match server unavailable (' + res.status + ')', res.status);
+    const t = await res.json();
+    return { ticket: t.ticket, wsUrl: t.wsUrl, expiresAt: new Date(Date.now() + 240000).toISOString() };
+  }
+
+  _devMatch(code, isHost, lobby) {
+    const arena = this._opts.arena || {};
+    const gameKey = String(this._opts.game || 'dev-game').replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 40);
+    this.match = {
+      id: 'dev-' + gameKey + '-' + code,
+      code,
+      game: gameKey,
+      status: 'OPEN',
+      visibility: 'PRIVATE',
+      minPlayers: arena.minPlayers || 2,
+      maxPlayers: arena.maxPlayers || 8,
+      playerCount: 1,
+      lobby: lobby || null,
+      isPlaytest: true,
+      dev: true,
+      you: { playerId: 'me', isHost, inMatch: true },
+      // In dev mode other players show up in the live match roster once connected.
+      players: [{ playerId: 'me', displayName: this.me.displayName, isHost, isYou: true }],
+    };
+    return this.match;
+  }
+}
+
+let readySent = false;
+let startedAt = now();
+
+export const MyVillageGame = {
+  /** Call once when the game has loaded and is interactive. */
+  ready() {
+    if (readySent) return;
+    readySent = true;
+    startedAt = now();
+    post({ type: 'ready' });
+  },
+
+  /**
+   * Call when the game is finished. `result` is optional:
+   *   { score?: number, rewards?: number, won?: boolean, custom?: object }
+   * `durationMs` is added automatically.
+   */
+  complete(result = {}) {
+    post({ type: 'complete', durationMs: Math.round(now() - startedAt), ...result });
+  },
+
+  /** Request to leave the game. The host also always offers an Exit control. */
+  exit() {
+    post({ type: 'exit' });
+  },
+
+  /**
+   * The host's context ({ game, platform, player: { displayName } }) or null
+   * when running standalone. Waits briefly for the host to answer.
+   */
+  async host() {
+    const ctx = await requestHostContext(standalone ? 300 : 3000);
+    return ctx && { game: ctx.game, platform: ctx.platform, player: { ...ctx.player } };
+  },
+
+  /**
+   * Real-time multiplayer. Options:
+   *   arena      — this game's arena config (src/arena.json); used for dev-mode matches
+   *   game       — a short id for dev-mode match rooms (e.g. your game's slug)
+   *   name       — dev-mode display name (platform mode uses the player's name)
+   *   devServer  — dev-mode match server (defaults to the MyVillage staging server)
+   */
+  async multiplayer(options = {}) {
+    const ctx = await requestHostContext(standalone ? 300 : 3000);
+    return new Multiplayer(ctx, options);
+  },
+};
+
+// Expose globally too, for non-module games and quick debugging.
+if (hasWindow) {
+  window.MyVillageGame = MyVillageGame;
+}
+
+export default MyVillageGame;

package/src/assets/templates/arena/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md — working on this MyVillage arena game with an AI agent
+
+**{{NAME}}** is a real-time **multiplayer** MyVillage game: a first-person arena built with **Three.js** and Vite. Players meet in a lobby, then play a live match on MyVillage's match servers. It runs inside the MyVillage host (the muni mobile app or the web player), and standalone in a browser.
+
+When editing: make the requested change, keep the **multiplayer contract** intact (below), and keep `npm run build` working.
+
+## How multiplayer works here (read first)
+
+- **The match server is the referee.** Clients only send controls (move, look, fire). The server moves every player, decides every hit, keeps score and runs the clock. The game *draws* what the server reports; it never decides outcomes.
+- **The rules are data:** `src/arena.json` (mode, player counts, duration, speed, damage, the map). `myvillage deploy` sends it to the platform, and every match of this game runs with it.
+- **The lobby is this game's own code** (`src/lobby.js`). The platform only provides the plumbing it calls. Restyle it freely.
+
+So, roughly:
+
+| You want to… | Change |
+|---|---|
+| Restyle or rework the lobby: teams, ready check, list open matches | `src/lobby.js` (+ CSS in `index.html`) |
+| Change how the arena looks: models, colors, effects, sounds, HUD | `src/arena-game.js`, `index.html` |
+| Change the rules: tag vs elimination, players, match length, speed, damage, respawn | `src/arena.json` |
+| Change the map | `src/arena.json` → `map` (the walls and spawns the server uses). `arena-game.js` draws it from the same data. |
+| Add new mechanics the server must judge (jumping, power-ups, grenades, new weapons, vertical aiming) | **Not possible in game code yet.** The match server's rules are fixed per mode; tell the user, and offer a cosmetic version or a config change. |
+
+## File map
+
+| File | Purpose |
+|------|---------|
+| `src/main.js` | Boot: lobby → `mp.connect()` → match → results → lobby. |
+| `src/lobby.js` | **The lobby screen** (Quick match / Host / Join with code). Yours to change. |
+| `src/arena-game.js` | Three.js scene, avatars, shot tracers, HUD, keyboard/mouse/touch input. |
+| `src/arena.json` | **Match rules and map**, shared with the match server. |
+| `src/myvillage-game.js` | Platform bridge and multiplayer plumbing. **Do not edit.** |
+| `src/myvillage-realtime.js` | Match netcode (prediction, interpolation). **Do not edit.** |
+| `index.html` | Page shell + all CSS. |
+| `assets/` | Cover art shipped on deploy. |
+
+## Multiplayer API (`src/myvillage-game.js`)
+
+```js
+const mp = await MyVillageGame.multiplayer({ arena, game: '{{SLUG}}' });
+mp.mode                         // 'platform' (in the app / web player) or 'dev' (standalone)
+mp.me.displayName
+await mp.quickMatch()           // join the fullest open match in the player's village, or host one
+await mp.host({ visibility })   // 'private' (code only) or 'village'
+await mp.join(code)             // join by code ("abc-234" works)
+await mp.list()                 // open village matches + the player's matches (lobby browser)
+mp.match                        // { id, code, status, players: [{ playerId, displayName, isHost, isYou }], lobby, minPlayers, maxPlayers, you: { isHost } }
+const stop = mp.watch(cb)       // cb(match) whenever players / lobby change
+await mp.setLobby({ ... })      // host only: game-defined lobby state (≤ 4 KB), e.g. teams or map pick
+await mp.lock() / unlock() / cancel()   // host only
+await mp.leave()
+const net = await mp.connect()  // live match → ArenaClient
+```
+
+The live match (`net`, an `ArenaClient`):
+
+- Each frame: `net.controls = { mx, mz, yaw, pitch, fire }`, then `net.update(dt)`.
+- Draw yourself at `net.view`: `{ x, z, yaw, hp, alive, it, score }`.
+- Draw everyone else from `net.others()`: `[{ id, n: name, x, z, y: yaw, hp, a: alive, s: score, it }]`.
+- Also available: `net.roster`, `net.phase` (`waiting` / `countdown` / `playing` / `ended`), `net.timeLeft`, `net.cfg`, `net.rttMs`.
+- `net.on('event', e => …)` events: `shot`, `elim`, `tag`, `spawn`, `join`, `leave`.
+- `net.on('end', e => …)` gives the ranked results. `net.on('close', …)` fires on disconnect; call `mp.connect()` again to rejoin.
+
+A match starts by itself once `minPlayers` are connected. Until then players can run around and warm up.
+
+## The multiplayer contract — DO NOT BREAK
+
+- Keep `MyVillageGame.ready()` in `src/main.js`.
+- **Never send positions, hits or scores yourself.** Only `net.controls`. Anything else is ignored by the server, and it's the server's results that award MVT.
+- **Don't call `MyVillageGame.complete()` when a match ends.** The platform records multiplayer results from the match server. Hosts treat `complete()` as "close the game", which would stop players from playing again.
+- Players are identified only by display name and an in-match id. Don't ask for, show or store anything more about them.
+- **Players only play with their own village.** The platform enforces it: codes only admit village-mates of the host, and quick match stays inside the player's villages. Don't build anything that suggests playing with strangers.
+- Don't add an Exit button; the host provides one (top-left). The in-game **Leave** button just returns to the lobby.
+
+## Running it
+
+    npm install
+    npm run dev      # standalone = DEV MODE: uses MyVillage's public test match server
+    npm run build    # production build -> dist/ (must pass before deploy)
+    myvillage deploy # build, then upload + submit (also sends src/arena.json)
+
+**Dev mode:** open the dev URL in **two browser tabs**. Either press Quick match in both, or Host in one and Join with its code in the other. That's how to test multiplayer alone. In dev mode there are no real accounts, no village matching and no MVT; in the app it all works for real.
+
+## Screen layout (phones)
+
+- The game fills the screen edge to edge. Keep HUD inside the safe area with the CSS variables in `index.html` (`--hud-top`, `--safe-bottom`, `--safe-left`, `--safe-right`).
+- Leave the **top-left corner** (`--exit-clear` wide) empty for the host's Exit button.
+- Touch controls: left half of the screen = move stick, right half = drag to look, red button = fire.
+
+## Conventions
+
+- Orientation is **{{ORIENTATION}}** (`package.json` → `myvillage.orientation`).
+- Keep asset URLs relative (Vite `base: './'`).
+- Cover art: `assets/thumbnail.png` (square) and `assets/banner.png`.

package/src/assets/templates/arena/README.md

@@ -0,0 +1,36 @@
+# {{NAME}}
+
+{{DESCRIPTION}}
+
+A real-time multiplayer arena for MyVillage. Players meet in the lobby, then play a live first-person match. The rules ship in `src/arena.json`: **elimination** (blasters) or **tag**, plus player counts, match length and the map.
+
+## Play it
+
+```bash
+npm install
+npm run dev
+```
+
+Open the page in **two browser tabs** and press **Quick match** in both, or **Host** in one and **Join** with its code in the other.
+
+- Desktop: click to aim, WASD to move, Q/E to turn, click or Space to fire.
+- Phone: left thumb moves, right thumb looks, red button fires.
+
+Running standalone uses MyVillage's public test match server ("dev mode"). Inside the MyVillage app, matches are real: village quick match, friends by code, and MVT for finished matches.
+
+## Make it yours
+
+- **Lobby:** `src/lobby.js`
+- **Look and HUD:** `src/arena-game.js` and `index.html`
+- **Rules and map:** `src/arena.json`
+
+See `AGENTS.md` for the full guide, including what the match server decides and what your code can change.
+
+## Deploy
+
+```bash
+npm run build
+myvillage deploy
+```
+
+`deploy` also sends `src/arena.json`, so every match of your game runs with your rules.

package/src/assets/templates/arena/index.html

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+  <!-- orientation: {{ORIENTATION}} -->
+  <title>{{NAME}}</title>
+  <style>
+    /* Screen-edge spacing. On a phone the game runs under the status bar and
+       home indicator; keep HUD inside these. The muni app also injects
+       --mv-safe-* (Android web views don't report env() insets).
+       The TOP-LEFT corner (--exit-clear wide, below --safe-top) belongs to the
+       app's Exit button — keep it empty. */
+    :root {
+      --safe-top: max(env(safe-area-inset-top, 0px), var(--mv-safe-top, 0px));
+      --safe-bottom: max(env(safe-area-inset-bottom, 0px), var(--mv-safe-bottom, 0px));
+      --safe-left: max(env(safe-area-inset-left, 0px), var(--mv-safe-left, 0px));
+      --safe-right: max(env(safe-area-inset-right, 0px), var(--mv-safe-right, 0px));
+      --hud-top: calc(var(--safe-top) + 12px);
+      --exit-clear: 64px;
+      --ink: #f5f1e6;
+      --panel: rgba(18, 22, 28, 0.82);
+      --accent: {{GOLD}};
+      --danger: #e5484d;
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { width: 100%; height: 100%; overflow: hidden; }
+    body { background: {{DARK}}; color: var(--ink); font: 15px/1.4 system-ui, -apple-system, 'Segoe UI', sans-serif; user-select: none; -webkit-user-select: none; }
+    {{CONTAINER_CSS}}
+    /* touch-action: none — drags steer and look, never scroll the page. */
+    canvas { display: block; touch-action: none; }
+    [hidden] { display: none !important; }
+
+    /* Lobby (src/lobby.js) */
+    #lobby { position: absolute; inset: 0; display: grid; place-items: center; padding: 16px; background: rgba(8, 10, 14, 0.45); z-index: 10; }
+    .card { background: var(--panel); border-radius: 16px; padding: 20px; width: min(340px, 100%); display: grid; gap: 10px; }
+    .card h1 { font-size: 26px; color: var(--accent); }
+    .card h2 { font-size: 22px; }
+    .card .who { opacity: 0.85; }
+    .card .hint { font-size: 12px; opacity: 0.65; }
+    .card .error { color: var(--danger); font-size: 13px; min-height: 1em; }
+    .card ol { padding-left: 22px; }
+    button { font: inherit; font-weight: 600; padding: 11px; border-radius: 10px; border: 0; background: #2c333d; color: var(--ink); cursor: pointer; }
+    button.primary { background: var(--accent); color: #1a1408; }
+    button:disabled { opacity: 0.5; }
+    form.join { display: flex; gap: 8px; }
+    form.join input { flex: 1; min-width: 0; font: inherit; letter-spacing: 2px; text-transform: uppercase; padding: 10px; border-radius: 10px; border: 1px solid #39414d; background: #151a21; color: var(--ink); }
+
+    /* HUD (src/arena-game.js) */
+    .hud { position: absolute; inset: 0; pointer-events: none; z-index: 5; }
+    .hud > * { position: absolute; }
+    .hud-status { top: var(--hud-top); left: 50%; transform: translateX(-50%); background: var(--panel); padding: 6px 14px; border-radius: 999px; font-weight: 600; white-space: nowrap; max-width: calc(100% - 2 * var(--exit-clear) - 24px); overflow: hidden; text-overflow: ellipsis; }
+    .hud-board { top: calc(var(--hud-top) + 48px); right: calc(var(--safe-right) + 10px); background: var(--panel); padding: 8px 10px; border-radius: 10px; font-size: 13px; min-width: 120px; }
+    .hud-board div { display: flex; justify-content: space-between; gap: 12px; }
+    .hud-board .me { color: var(--accent); }
+    .hud-leave { top: var(--hud-top); right: calc(var(--safe-right) + 10px); pointer-events: auto; padding: 6px 12px; font-size: 13px; }
+    .hud-crosshair { left: 50%; top: 50%; width: 18px; height: 18px; margin: -9px 0 0 -9px; border: 2px solid rgba(255, 255, 255, 0.8); border-radius: 50%; }
+    .hud-crosshair.hit { border-color: var(--danger); transform: scale(1.3); }
+    .hud-banner { top: 34%; left: 50%; transform: translateX(-50%); font-size: 24px; font-weight: 700; text-shadow: 0 2px 8px #000; text-align: center; width: 90%; }
+    .hud-hp { bottom: calc(var(--safe-bottom) + 14px); left: 50%; transform: translateX(-50%); background: var(--panel); padding: 6px 14px; border-radius: 999px; font-weight: 600; }
+    .hud-ping { bottom: calc(var(--safe-bottom) + 18px); left: calc(var(--safe-left) + 12px); font-size: 11px; opacity: 0.6; }
+    .hud-results { inset: 0; display: grid; place-items: center; background: rgba(8, 10, 14, 0.6); pointer-events: auto; padding: 16px; }
+    .hud-fire { position: absolute; z-index: 6; right: calc(var(--safe-right) + 24px); bottom: calc(var(--safe-bottom) + 28px); width: 84px; height: 84px; border-radius: 50%; background: rgba(229, 72, 77, 0.55); display: grid; place-items: center; font-weight: 700; }
+    .hud-stick { position: fixed; z-index: 6; width: 110px; height: 110px; margin: -55px 0 0 -55px; border-radius: 50%; border: 2px solid rgba(255, 255, 255, 0.35); pointer-events: none; }
+    .hud-stick i { position: absolute; left: 50%; top: 50%; width: 44px; height: 44px; margin: -22px 0 0 -22px; border-radius: 50%; background: rgba(255, 255, 255, 0.45); }
+  </style>
+</head>
+<body>
+  <div id="game-container">
+    <div id="lobby" hidden></div>
+  </div>
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>