@netforge/tabletop 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetNet Capital Management
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,6 @@
+@netforge/tabletop
+Copyright (c) 2026 NetNet Capital Management
+
+Dependencies (unmodified, via npm)
+- three.js 0.186.1 (https://github.com/mrdoob/three.js), MIT.
+- @netforge/engine and @netforge/asset-library (this repository); see their NOTICE files.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @netforge/tabletop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The client kit the board-style Net Forge templates share (tower defense,
+idle, card battler, monster collector): the room connection and input clock
+for rules genres, the styled 3D stage, the store, stake and gear wiring, and
+the HUD shell. Used by `@netforge/template-*` clients; see
+`@netforge/kit-play` to run one on your own computer.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@netforge/tabletop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The client kit the board-style templates share (tower defense, idle, card battler, monster collector): the room connection and input clock for rules genres, the styled 3D stage, the Kit store, stake and gear wiring, and the HUD shell.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/measure.ts",
+    "README.md",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netnetdev/net-forge.git",
+    "directory": "packages/tabletop"
+  },
+  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/tabletop#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "three": "0.186.1",
+    "@netforge/asset-library": "0.1.0",
+    "@netforge/engine": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "@types/three": "0.186.0",
+    "typescript": "5.8.3",
+    "vitest": "3.2.7"
+  },
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests"
+  }
 }

package/src/boot.ts

@@ -0,0 +1,333 @@
+/**
+ * Boots a board template's page: the Kit flags from Net Forge, the
+ * renderer and the stage in the game's art style, the room by link, the
+ * input clock, the store, sound and the stats overlay. The template then
+ * draws its own board on `stage` and reads its own run state from `view()`.
+ *
+ * URL parameters (every board template):
+ *   ?room=<id>        join a friend's instance (the Invite link)
+ *   ?place=<name>     the place
+ *   ?server=<url>     room server (default: VITE_ROOMS_URL, else this host on :2567)
+ *   ?webgl=1          force the WebGL2 backend
+ *   ?autopilot=1      the genre's bot plays (measurement and screenshots)
+ *   ?preview=1        a style preview: the camera frames the board, the HUD hides
+ *   ?stats=1          show frame, network and server numbers (also the ` key)
+ *   ?shapes=1         draw the fallback shapes instead of library models
+ *   ?style=<style>    another art style (toon, ps1, pixel, voxel, handdrawn)
+ *   ?library=<url>    asset library base URL (default: VITE_LIBRARY_URL, else ./library)
+ *   ?host=netnet, ?coin=, ?title=, ?player=   set by Net Forge (host.ts)
+ */
+import type { GameManifest } from "@netforge/engine";
+import type { SimAdapter } from "@netforge/engine/net";
+import type { RulesInput, RulesWorld } from "@netforge/engine/rules";
+import { createRenderer, FeelAudio, FrameStats, pickStyle, SoundPlayer } from "@netforge/engine/runtime";
+import type { LookPreset } from "@netforge/engine/runtime";
+import { soundBank } from "@netforge/asset-library";
+import { LibraryClient } from "@netforge/asset-library/three";
+import { InputClock, joinBoard, roomsEndpoint, type BoardConnection } from "./connect.js";
+import { hostFlags, namedPlayer, onHostPlayer, postReady, type PlayerMode } from "./host.js";
+import { Hud, wireStore, type EarnProgress, type HudLabels, type HudTheme } from "./hud.js";
+import { mockKit, type KitStoreBridge, type SkuPrice } from "./kit.js";
+import { BoardStage } from "./stage.js";
+
+export interface BoardBootOptions<S> {
+  readonly adapter: SimAdapter<RulesWorld<S>, RulesInput>;
+  readonly manifest: GameManifest;
+  /** Room template and default place. */
+  readonly template: string;
+  readonly place: string;
+  readonly version: string;
+  readonly labels: HudLabels;
+  readonly theme: HudTheme;
+  /** The template's own coin until a creator renames it. */
+  readonly coin: { name: string; symbol: string; logo: string | null };
+  readonly cosmetics: Readonly<Record<string, number>>;
+  readonly swatch: (cosmetic: number) => string;
+  /** Ground the stage frames, metres. */
+  readonly ground: { w: number; h: number };
+  readonly preset?: LookPreset;
+  readonly theme3d?: string;
+  readonly groundColor?: number;
+  readonly pitch?: number;
+  /** false: no style-built land (voxel) under the game's own surface. */
+  readonly field?: boolean;
+  /** The autopilot's input (?autopilot=1): the genre's own bot over the latest run state. */
+  readonly autopilot?: (tick: number) => RulesInput | null;
+  /** Key for the remembered mute. */
+  readonly soundKey: string;
+}
+
+/** The per-player run state every board view carries (adapter infoFor). */
+export interface BoardView {
+  readonly you?: number;
+  readonly phase?: "playing" | "ended";
+  readonly outcome?: "won" | "lost" | null;
+  readonly endsIn?: number | null;
+  readonly earn?: readonly EarnProgress[];
+  readonly upgrades?: Readonly<Record<string, number>>;
+  readonly [k: string]: unknown;
+}
+
+export interface BoardApp<S> {
+  readonly params: URLSearchParams;
+  readonly conn: () => BoardConnection<S>;
+  readonly self: number;
+  readonly hud: Hud;
+  readonly stage: BoardStage;
+  readonly clock: InputClock;
+  readonly kit: KitStoreBridge;
+  readonly sfx: FeelAudio;
+  readonly sound: SoundPlayer;
+  readonly autopilot: boolean;
+  readonly preview: boolean;
+  readonly style: string;
+  readonly canvas: HTMLCanvasElement;
+  readonly joinMs: number;
+  /** The latest per-player run state. */
+  view<V extends BoardView>(): V | null;
+  /** Every frame: dt in seconds. The stage draws after `fn`. */
+  loop(fn: (dt: number, now: number) => void): void;
+  /** Extra lines for the stats overlay and window.__board. */
+  extraStats(fn: () => Record<string, unknown>): void;
+}
+
+export interface BoardStats {
+  backend: string;
+  fps: number;
+  frameMs: { mean: number; p50: number; p95: number; p99: number };
+  drawCalls: number;
+  triangles: number;
+  downKBps: number;
+  upKBps: number;
+  rttMs: number;
+  joinMs: number;
+  firstFrameMs: number;
+  /** First drawn frame since navigation start (download, parse, join and the first draw). */
+  firstFrameNavMs: number;
+  corrections: number;
+  frames: number;
+  roomId: string;
+  style: string;
+  models: number;
+  failedModels: number;
+  actions: number;
+  extra: Record<string, unknown>;
+}
+
+declare global {
+  interface Window {
+    __board?: BoardStats;
+  }
+}
+
+export async function bootBoard<S>(o: BoardBootOptions<S>): Promise<BoardApp<S>> {
+  const bootAt = performance.now();
+  const params = new URLSearchParams(location.search);
+  const launcher = hostFlags(params);
+  if (launcher.framed) document.documentElement.dataset.host = "netnet";
+  const preview = params.get("preview") === "1";
+  const hud = new Hud(o.labels, o.theme, o.manifest);
+  if (preview) document.documentElement.dataset.preview = "1";
+  let playerMode: PlayerMode = launcher.player;
+  let hostMode: PlayerMode | null = namedPlayer(params);
+  onHostPlayer(launcher, (mode) => {
+    playerMode = mode;
+    hostMode = mode;
+    hud.player(mode);
+  });
+  const title = launcher.title ?? o.labels.title;
+  hud.title(title);
+
+  const host = document.getElementById("game");
+  if (!host) throw new Error("missing #game");
+  const canvas = document.createElement("canvas");
+  host.append(canvas);
+  const handle = await createRenderer(canvas, { forceWebGL: params.get("webgl") === "1", antialias: true });
+  const env = (import.meta as unknown as { env?: Record<string, string | undefined> }).env ?? {};
+  const libraryBase = params.get("library") ?? env.VITE_LIBRARY_URL ?? "./library";
+  const style = pickStyle(o.manifest.game.style, params.get("style"));
+  const library = params.get("shapes") === "1" ? null : new LibraryClient(handle, { baseUrl: libraryBase, style });
+  const stage = new BoardStage(handle, {
+    style,
+    library,
+    ground: o.ground,
+    ...(o.preset ? { preset: o.preset } : {}),
+    ...(o.theme3d ? { theme: o.theme3d } : {}),
+    ...(o.groundColor !== undefined ? { groundColor: o.groundColor } : {}),
+    ...(o.pitch !== undefined ? { pitch: o.pitch } : {}),
+    ...(o.field !== undefined ? { field: o.field } : {}),
+  });
+
+  const endpoint = roomsEndpoint(params);
+  const friendRoomId = params.get("room") ?? undefined;
+  const place = params.get("place") ?? o.place;
+  const { conn: first, joinMs } = await joinBoard(o.adapter, { endpoint, place, template: o.template, ...(friendRoomId ? { friendRoomId } : {}) });
+  const conn = first;
+  const self = conn.welcome.player;
+  if (friendRoomId && conn.roomId !== friendRoomId) setTimeout(() => hud.toast("Room full, new room"), 500);
+  if (conn.welcome.version !== o.version) setTimeout(() => hud.toast("Update ready. Reload."), 800);
+  const autopilot = params.get("autopilot") === "1";
+  const linkFor = (base: string) => `${base}?room=${conn.roomId}${place !== o.place ? `&place=${encodeURIComponent(place)}` : ""}${params.has("server") ? `&server=${encodeURIComponent(endpoint)}` : ""}`;
+  const keep = ["autopilot", "webgl", "stats", "style", "preview", "shapes", "host", "coin", "title", "player", "library"].filter((k) => params.has(k)).map((k) => `&${k}=${encodeURIComponent(params.get(k) ?? "")}`).join("");
+  history.replaceState(null, "", `${linkFor(location.pathname)}${keep}`);
+
+  let latest: BoardView | null = null;
+  conn.onRun((info) => {
+    latest = info as BoardView;
+  });
+
+  // The Kit plugs in here (packages/kit, kit.init({ game })): kit.coins and kit.store have these exact names.
+  const prices: Record<string, SkuPrice> = Object.fromEntries(o.manifest.skus);
+  const coin = launcher.coin ? { name: launcher.coin, symbol: launcher.coin, logo: null } : o.coin;
+  const kit = mockKit({ earned: 120, wallet: 0, usdg: 5 }, prices, coin);
+  hud.coin(kit.coins.name(), kit.coins.symbol(), kit.coins.logo());
+  hud.player(playerMode);
+  conn.onEarn((e) => {
+    hud.earned(e.rule, e.units);
+    sfx.play("coin");
+  });
+
+  const sfx = new FeelAudio();
+  const sound = new SoundPlayer(sfx, { key: o.soundKey, musicVolume: 0.25 });
+  try {
+    sound.load(soundBank(libraryBase));
+  } catch {
+    // no library audio: the synth cues play
+  }
+  const soundBtn = document.getElementById("sound");
+  if (soundBtn) {
+    soundBtn.textContent = sound.muted ? "Sound off" : "Sound";
+    soundBtn.addEventListener("click", () => {
+      sfx.unlock();
+      soundBtn.textContent = sound.toggle() ? "Sound off" : "Sound";
+    });
+  }
+  addEventListener("pointerdown", () => sfx.unlock(), { once: true });
+  addEventListener("keydown", () => sfx.unlock(), { once: true });
+  wireStore({ hud, manifest: o.manifest, kit, conn: conn as never, labels: o.labels, cosmetics: o.cosmetics, swatch: o.swatch, hostMode: () => hostMode, unlock: () => sfx.unlock() });
+  document.getElementById("invite")?.addEventListener("click", () => {
+    const url = linkFor(`${location.origin}${location.pathname}`);
+    void navigator.clipboard?.writeText(url).then(
+      () => hud.toast("Invite link copied"),
+      () => hud.toast(url),
+    );
+  });
+  postReady(launcher);
+
+  const clock = new InputClock(() => conn as BoardConnection<unknown>, autopilot && o.autopilot ? o.autopilot : null);
+  clock.start();
+
+  let rtt = 0;
+  conn.room.onMessage("pong", (t: number) => {
+    rtt = performance.now() - t;
+  });
+  setInterval(() => conn.room.send("ping", performance.now()), 2000);
+  addEventListener("keydown", (e) => {
+    if (e.code === "Backquote") document.getElementById("stats")?.classList.toggle("show");
+  });
+  if (params.get("stats") === "1") document.getElementById("stats")?.classList.add("show");
+
+  const resize = () => stage.resize(Math.max(1, host.clientWidth), Math.max(1, host.clientHeight));
+  resize();
+  new ResizeObserver(resize).observe(host);
+
+  const frame = new FrameStats(600);
+  const extras: (() => Record<string, unknown>)[] = [];
+  let fns: ((dt: number, now: number) => void)[] = [];
+  let last = 0;
+  let frames = 0;
+  let firstFrameMs = 0;
+  let firstFrameNavMs = 0;
+  let lastBytes = 0;
+  let lastUp = 0;
+  let lastNet = performance.now();
+  let downKBps = 0;
+  let upKBps = 0;
+  let lastStats = 0;
+  handle.renderer.setAnimationLoop((t: number) => {
+    const real = performance.now();
+    const dt = last === 0 ? 1 / 60 : Math.min(0.1, (t - last) / 1000);
+    if (last !== 0) frame.push(t - last);
+    last = t;
+    for (const f of fns) f(dt, real);
+    stage.frame(dt);
+    if (frames === 0) {
+      firstFrameMs = real - bootAt;
+      firstFrameNavMs = real;
+      hud.ready();
+    }
+    frames++;
+    hud.balance(kit.coins.balance());
+    const v = latest;
+    if (v) {
+      hud.goals(v.earn);
+    }
+    if (real - lastNet >= 1000) {
+      const secs = (real - lastNet) / 1000;
+      downKBps = (conn.bytesIn() - lastBytes) / secs / 1024;
+      upKBps = (conn.net.stats.inputBytes - lastUp) / secs / 1024;
+      lastBytes = conn.bytesIn();
+      lastUp = conn.net.stats.inputBytes;
+      lastNet = real;
+    }
+    const info = handle.renderer.info.render;
+    const mean = frame.mean();
+    const extra: Record<string, unknown> = {};
+    for (const e of extras) Object.assign(extra, e());
+    const stats: BoardStats = {
+      backend: handle.backend,
+      fps: mean > 0 ? 1000 / mean : 0,
+      frameMs: { mean, p50: frame.percentile(0.5), p95: frame.percentile(0.95), p99: frame.percentile(0.99) },
+      drawCalls: info.drawCalls,
+      triangles: info.triangles,
+      downKBps,
+      upKBps,
+      rttMs: rtt,
+      joinMs,
+      firstFrameMs,
+      firstFrameNavMs,
+      corrections: conn.net.corrections,
+      frames,
+      roomId: conn.roomId,
+      style,
+      models: stage.counts.models,
+      failedModels: stage.counts.failed,
+      actions: clock.sent,
+      extra,
+    };
+    window.__board = stats;
+    if (real - lastStats > 250) {
+      lastStats = real;
+      hud.stats(
+        [
+          `${stats.backend.toUpperCase()}  ${stats.fps.toFixed(0)} fps  p95 ${stats.frameMs.p95.toFixed(1)} ms  ${style}`,
+          `draws ${stats.drawCalls}  tris ${(stats.triangles / 1000).toFixed(0)}k  models ${stats.models}`,
+          `down ${downKBps.toFixed(1)} KB/s  up ${upKBps.toFixed(2)} KB/s  rtt ${rtt.toFixed(0)} ms`,
+          `join ${joinMs.toFixed(0)} ms  first frame ${firstFrameMs.toFixed(0)} ms  corrections ${conn.net.corrections}`,
+        ].join("\n"),
+      );
+    }
+  });
+
+  return {
+    params,
+    conn: () => conn,
+    self,
+    hud,
+    stage,
+    clock,
+    kit,
+    sfx,
+    sound,
+    autopilot,
+    preview,
+    style,
+    canvas,
+    joinMs,
+    view: <V extends BoardView>() => latest as V | null,
+    loop: (fn) => {
+      fns = [...fns, fn];
+    },
+    extraStats: (fn) => extras.push(fn),
+  };
+}

package/src/connect.ts

@@ -0,0 +1,116 @@
+/**
+ * The room connection for a board template: join by link, an input clock
+ * that sends one input a tick (the server consumes one a tick), the avatar
+ * predicted from it, and actions queued so each rides exactly one input.
+ */
+import { guestId, joinRoom, savedSession } from "@netforge/engine/net";
+import type { RoomConnection } from "@netforge/engine/net";
+import type { RulesInput, RulesWorld } from "@netforge/engine/rules";
+import { IDLE_INPUT } from "@netforge/engine/rules";
+import type { SimAdapter } from "@netforge/engine/net";
+
+export interface BoardJoin {
+  readonly endpoint: string;
+  readonly place: string;
+  readonly template: string;
+  readonly friendRoomId?: string;
+}
+
+export type BoardConnection<S> = RoomConnection<RulesWorld<S>, RulesInput>;
+
+/** Joins the room (saves under the signed-in wallet or this browser's guest id). */
+export async function joinBoard<S>(adapter: SimAdapter<RulesWorld<S>, RulesInput>, j: BoardJoin): Promise<{ conn: BoardConnection<S>; joinMs: number }> {
+  const t0 = performance.now();
+  const session = savedSession(j.endpoint);
+  const conn = await joinRoom(adapter, {
+    endpoint: j.endpoint,
+    place: j.place,
+    template: j.template,
+    guest: guestId(),
+    ...(session ? { session: session.token } : {}),
+    ...(j.friendRoomId ? { friendRoomId: j.friendRoomId } : {}),
+  });
+  return { conn, joinMs: performance.now() - t0 };
+}
+
+/**
+ * One input a tick, on the server's clock (clock adjustment from the
+ * snapshot headers). The cursor and the stick are sampled each tick; an
+ * action waits in a queue and rides the next tick's input, one per tick.
+ */
+export class InputClock {
+  private stickX = 0;
+  private stickZ = 0;
+  private cursorX = 0;
+  private cursorZ = 0;
+  private readonly queue: { act: number; a: number; b: number; c: number }[] = [];
+  ticks = 0;
+  /** Actions sent so far. */
+  sent = 0;
+  private timer = 0;
+
+  constructor(
+    private readonly conn: () => BoardConnection<unknown>,
+    /** An autopilot input (playtest and measure), or null to play from the queue. */
+    private readonly auto: ((tick: number) => RulesInput | null) | null = null,
+  ) {}
+
+  /** Stick, -1..1 each axis (walking heroes). */
+  stick(x: number, z: number): void {
+    this.stickX = Math.max(-1, Math.min(1, x));
+    this.stickZ = Math.max(-1, Math.min(1, z));
+  }
+
+  /** Cursor on the ground, metres. */
+  cursor(x: number, z: number): void {
+    this.cursorX = x;
+    this.cursorZ = z;
+  }
+
+  /** Queue an action (sent on the next tick). */
+  act(act: number, a = 0, b = 0, c = 0): void {
+    if (this.queue.length < 16) this.queue.push({ act, a, b, c });
+  }
+
+  private sample(): RulesInput {
+    const auto = this.auto?.(this.ticks) ?? null;
+    if (auto) return auto;
+    const q = this.queue.shift();
+    return {
+      ...IDLE_INPUT,
+      mx: Math.round(this.stickX * 127),
+      mz: Math.round(this.stickZ * 127),
+      cx: Math.round(this.cursorX * 16),
+      cz: Math.round(this.cursorZ * 16),
+      ...(q ? { act: q.act, a: q.a, b: q.b, c: q.c } : {}),
+    };
+  }
+
+  start(): void {
+    let next = performance.now();
+    this.timer = window.setInterval(() => {
+      const now = performance.now();
+      let n = 0;
+      const c = this.conn();
+      while (next <= now && n < 8) {
+        const i = this.sample();
+        if (i.act !== 0) this.sent++;
+        c.net.tick(i, now);
+        this.ticks++;
+        next += c.net.tickIntervalMs();
+        n++;
+      }
+      if (n === 8) next = now + c.net.tickIntervalMs();
+    }, 4);
+  }
+
+  stop(): void {
+    clearInterval(this.timer);
+  }
+}
+
+/** The room server: ?server=, else VITE_ROOMS_URL, else this host on :2567. */
+export function roomsEndpoint(params: URLSearchParams): string {
+  const env = (import.meta as unknown as { env?: Record<string, string | undefined> }).env ?? {};
+  return params.get("server") ?? env.VITE_ROOMS_URL ?? `${location.protocol}//${location.hostname}:2567`;
+}

package/src/host.ts

@@ -0,0 +1,96 @@
+/**
+ * Net Forge as host. Framed by Net Forge, the page URL carries
+ * the Kit flags and the host posts one message; played on its own, none of
+ * this applies and the game behaves exactly as before.
+ *
+ *   ?host=netnet       the host draws Invite and sign-in; the game hides its own
+ *   ?coin=TICKER       the coin the HUD names (2 to 6 capitals or digits)
+ *   ?title=NAME        the game's own name for the wordmark and the tab title
+ *   ?player=guest      no wallet is connected: play pays nothing, and the HUD
+ *                      says "not earning" instead of a balance
+ *   ?player=play       the token has not launched: coins are play money
+ *
+ * The player flag changes while the game runs (a wallet connects), so the
+ * host also posts { kind: "netnet-kit", type: "player", mode }. Only the
+ * parent window is listened to, and only when the URL says it is the host.
+ */
+
+export type PlayerMode = "earning" | "guest" | "play";
+
+export interface HostFlags {
+  /** Framed by Net Forge. */
+  readonly framed: boolean;
+  /** The coin's ticker, when the host names one. */
+  readonly coin: string | null;
+  /** The game's own name, when the host names one. */
+  readonly title: string | null;
+  /** What play pays the person at the screen. Standalone play is "earning" (the game's own kit decides). */
+  readonly player: PlayerMode;
+}
+
+const TICKER_RE = /^[A-Z0-9]{2,6}$/;
+
+export function hostFlags(params: URLSearchParams): HostFlags {
+  const framed = params.get("host") === "netnet";
+  const coin = params.get("coin");
+  // eslint-disable-next-line no-control-regex
+  const title = (params.get("title") ?? "").replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, 40);
+  const player = params.get("player");
+  return {
+    framed,
+    coin: coin && TICKER_RE.test(coin) ? coin : null,
+    title: title || null,
+    player: framed && (player === "guest" || player === "play") ? player : "earning",
+  };
+}
+
+/**
+ * The player mode the host named on the URL, or null when it named none (a
+ * connected player on a live game gets no flag, only the posted message) or
+ * the page is not framed by Net Forge.
+ */
+export function namedPlayer(params: URLSearchParams): PlayerMode | null {
+  if (params.get("host") !== "netnet") return null;
+  const player = params.get("player");
+  return player === "earning" || player === "guest" || player === "play" ? player : null;
+}
+
+/**
+ * The store's note under its prices, from one source of truth. Once the host
+ * has named the player mode (on the URL or in a message), that mode decides,
+ * exactly as it does for the coin box: a live game never calls its coins play
+ * money. Standalone play, or a host that names no mode (the studio's drafts),
+ * keeps the room's own word (`welcome.earnLive`).
+ */
+export function storeNote(hostMode: PlayerMode | null, earnLive: boolean, symbol: string): string {
+  if (hostMode === "play") return "Play money until launch";
+  if (hostMode === "guest") return `Connect a wallet to earn ${symbol}`;
+  if (hostMode === "earning") return "";
+  return earnLive ? "" : "Play money until launch";
+}
+
+/** A host message, checked: anything else is ignored. */
+export function playerFrom(data: unknown): PlayerMode | null {
+  if (typeof data !== "object" || data === null) return null;
+  const m = data as Record<string, unknown>;
+  if (m["kind"] !== "netnet-kit" || m["type"] !== "player") return null;
+  const mode = m["mode"];
+  return mode === "earning" || mode === "guest" || mode === "play" ? mode : null;
+}
+
+/** Calls `cb` with each player mode the host posts. Framed pages only. */
+export function onHostPlayer(flags: HostFlags, cb: (mode: PlayerMode) => void): void {
+  if (!flags.framed || window.parent === window) return;
+  window.addEventListener("message", (e: MessageEvent<unknown>) => {
+    if (e.source !== window.parent) return;
+    const mode = playerFrom(e.data);
+    if (mode) cb(mode);
+  });
+}
+
+/** Tells the host the game is up, so it can post the current player mode. */
+export function postReady(flags: HostFlags): void {
+  if (!flags.framed || window.parent === window) return;
+  // The host's origin is not known to an opaque-origin frame; the message is one public flag.
+  window.parent.postMessage({ kind: "netnet-kit", type: "ready" }, "*");
+}