@wenathlan/stealthhead 0.0.0-stage → 2.0.94

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# stealthhead
+
+FPS game platform. Imports versawase from cadria and audio from debonair via the published library, with no engine file of its own; only game logics (match, ranking, weapons, world). This folder receives the stealthhead application per the complete tree.
+
+---
+
+# The Sol theme
+
+# Stealthhead Sol
+
+Stealthhead is the FPS world and game application of the DevThink family: matches, rounds, ranking ladders, weapons and world assets under one game shell. This Sol theme is its web surface — a Vite + React SPA whose home, match, ranking, weapons and world routes render from the same sqlite database that `schema.prisma` and `drizzle.config.ts` describe.
+
+```bash
+pnpm install
+pnpm dev
+```
 
-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.

package/package.json

@@ -1,6 +1,143 @@
 {
   "name": "@wenathlan/stealthhead",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.94",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wenathlan/devthink"
+  },
+  "description": "stealthhead is the FPS game platform of the wenathlan family: it imports versawase from cadria and audio from debonair via the published library, with no engine file of its own — only game logics (match, ranking, weapons, world). The envelope distributes the documentation set and the tests directory as one package.",
+  "keywords": [
+    "stealthhead",
+    "fps",
+    "game",
+    "match",
+    "ranking",
+    "gameplay",
+    "documentation"
+  ],
+  "license": "GPL-3.0-only",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host",
+    "build": "vite build",
+    "start": "vite preview --host",
+    "preview": "vite preview --host",
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.3",
+    "@prisma/adapter-libsql": "^7.10.0",
+    "hono": "^4.13.12",
+    "ink": "^7.1.1",
+    "react-devtools-core": "^8.0.0",
+    "z-ai-web-dev-sdk": "^0.0.18"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@capacitor/android": "^8.5.2",
+    "@capacitor/cli": "^8.5.2",
+    "@capacitor/core": "^8.5.2",
+    "@capacitor/ios": "^8.5.2",
+    "@hookform/resolvers": "^5.9.1",
+    "@libsql/client": "^0.18.0",
+    "@opencode-ai/sdk": "^1.18.34",
+    "@prisma/client": "^7.10.0",
+    "@radix-ui/react-accordion": "^1.2.20",
+    "@radix-ui/react-alert-dialog": "^1.1.23",
+    "@radix-ui/react-aspect-ratio": "^1.1.15",
+    "@radix-ui/react-avatar": "^1.2.6",
+    "@radix-ui/react-checkbox": "^1.3.11",
+    "@radix-ui/react-collapsible": "^1.1.20",
+    "@radix-ui/react-context-menu": "^2.3.7",
+    "@radix-ui/react-dialog": "^1.1.23",
+    "@radix-ui/react-dropdown-menu": "^2.1.24",
+    "@radix-ui/react-hover-card": "^1.1.23",
+    "@radix-ui/react-label": "^2.1.15",
+    "@radix-ui/react-menubar": "^1.1.24",
+    "@radix-ui/react-navigation-menu": "^1.2.22",
+    "@radix-ui/react-popover": "^1.1.23",
+    "@radix-ui/react-progress": "^1.1.16",
+    "@radix-ui/react-radio-group": "^1.4.7",
+    "@radix-ui/react-scroll-area": "^1.2.18",
+    "@radix-ui/react-select": "^2.3.7",
+    "@radix-ui/react-separator": "^1.1.15",
+    "@radix-ui/react-slider": "^1.4.7",
+    "@radix-ui/react-slot": "^1.3.3",
+    "@radix-ui/react-switch": "^1.3.7",
+    "@radix-ui/react-tabs": "^1.1.21",
+    "@radix-ui/react-toggle": "^1.1.18",
+    "@radix-ui/react-toggle-group": "^1.1.19",
+    "@radix-ui/react-tooltip": "^1.2.16",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@tailwindcss/typography": "^0.5.20",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tsconfig/node26": "^26.0.1",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/chrome": "^0.3.4",
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "add": "^2.0.9",
+    "autoprefixer": "^10.6.1",
+    "axios": "^1.20.0",
+    "better-sqlite3": "^13.0.3",
+    "bun-types": "^1.4.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.3",
+    "embla-carousel-react": "^8.6.0",
+    "esbuild": "^0.28.2",
+    "express": "^5.2.1",
+    "fast-check": "^4.10.2",
+    "framer-motion": "^13.5.0",
+    "input-otp": "^1.5.0",
+    "lucide-react": "^1.49.0",
+    "mysql2": "^3.23.1",
+    "nanoid": "^6.0.1",
+    "next-themes": "^0.4.6",
+    "pnpm": "^12.8.1",
+    "postcss": "^8.5.28",
+    "prettier": "^3.9.9",
+    "prisma": "^7.10.0",
+    "react": "^19.3.0",
+    "react-day-picker": "^10.0.2",
+    "react-dom": "^19.3.0",
+    "react-hook-form": "^7.89.0",
+    "react-resizable-panels": "^4.14.1",
+    "recharts": "^3.10.1",
+    "sonner": "^2.0.8",
+    "streamdown": "^2.7.0",
+    "tailwind-merge": "^3.7.0",
+    "tailwindcss": "^4.3.3",
+    "tailwindcss-animate": "^1.0.7",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^7.0.2",
+    "vaul": "^1.1.2",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3",
+    "wouter": "^3.13.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "files": [
+    "README.md",
+    "docs",
+    "tests"
+  ],
+  "homepage": "https://github.com/wenathlan/devthink/tree/main/stealthhead",
+  "bugs": {
+    "url": "https://github.com/wenathlan/devthink/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "pnpm@12.3.4"
+}

package/tests/familyurl.test.ts

@@ -0,0 +1,25 @@
+/**
+ * familyurl.test.ts — the sibling link builder of the rail foot: one slug
+ * in, the relative family URL out (edge slashes trimmed, trailing slash
+ * included), exactly the shape the window chrome links the family with.
+ */
+import { describe, expect, it } from "vitest";
+import { familyurl } from "../familyurl";
+
+describe("familyurl", () => {
+  it("builds the relative sibling url with the trailing slash", () => {
+    expect(familyurl("cadria")).toBe("../cadria/");
+  });
+
+  it("trims the surrounding slashes of the slug", () => {
+    expect(familyurl("/cadria/")).toBe("../cadria/");
+  });
+
+  it("trims repeated edge slashes on both sides", () => {
+    expect(familyurl("///debonair///")).toBe("../debonair/");
+  });
+
+  it("keeps the interior of the slug untouched", () => {
+    expect(familyurl("devthink")).toBe("../devthink/");
+  });
+});

package/tests/hud.test.ts

@@ -0,0 +1,204 @@
+// # hud.test — honest unit tests for the hud state logic (vital bands,
+// minimap transforms, hitmarkers, killfeed, damage pings), runnable with
+// the vitest runner:
+//   pnpm test
+// Every case feeds plain structs and checks exact numbers — no dom, no
+// rendering, no mocks, no randomness.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  activehitmarkers,
+  applydamage,
+  DAMAGESTRENGTHFLOOR,
+  directionaldamage,
+  effectivepool,
+  HITWINDOWS,
+  type Hitmarker,
+  healthfraction,
+  hitmarkerfor,
+  hitmarkerwindow,
+  isalive,
+  KILLFEEDCAP,
+  KILLFEEDTTL,
+  type KillfeedEntry,
+  killfeedline,
+  minimapbounds,
+  minimapconfig,
+  poolfraction,
+  prunekillfeed,
+  pushhitmarker,
+  pushkillfeed,
+  sectorof,
+  shieldfraction,
+  tominimap,
+  VITALTHRESHOLDS,
+  type Vitals,
+  vitaltier,
+} from "../hud.ts";
+
+/** full vitals: 100 health behind 50 shield. */
+const FULL: Vitals = { health: 100, maxhealth: 100, shields: 50, maxshields: 50 };
+
+/** a widget transform over a 100x100 world on a 200px map (10px rim). */
+const WIDGET = { bounds: { minx: -50, minz: -50, maxx: 50, maxz: 50 }, sizepx: 200, padding: 10, yaw: 0 };
+
+/** one killfeed row builder. */
+function kill(id: string, at: number): KillfeedEntry {
+  return { id, killer: "ember-1", victim: "tide-2", weapon: "raven", at, headshot: false };
+}
+
+describe("vital bands", () => {
+  it("reads the pool fraction clamped to [0, 1]", () => {
+    assert.equal(poolfraction(FULL), 1);
+    assert.ok(Math.abs(poolfraction({ health: 40, maxhealth: 100, shields: 20, maxshields: 50 }) - 0.4) < 1e-9);
+    assert.equal(poolfraction({ health: 999, maxhealth: 100, shields: 999, maxshields: 50 }), 1);
+    assert.equal(poolfraction({ health: 0, maxhealth: 0, shields: 0, maxshields: 0 }), 0);
+  });
+
+  it("bands the vitals through the four thresholds", () => {
+    assert.equal(vitaltier(FULL), "healthy");
+    assert.equal(vitaltier({ health: 70, maxhealth: 100, shields: 10, maxshields: 50 }), "wounded");
+    assert.equal(vitaltier({ health: 40, maxhealth: 100, shields: 10, maxshields: 50 }), "low");
+    assert.equal(vitaltier({ health: 20, maxhealth: 100, shields: 0, maxshields: 50 }), "critical");
+    assert.equal(VITALTHRESHOLDS.critical, 0.25);
+    assert.equal(VITALTHRESHOLDS.wounded, 0.75);
+  });
+
+  it("applies damage with shields first and counts the overflow", () => {
+    const shielded = applydamage(FULL, 30);
+    assert.equal(shielded.absorbed, 30);
+    assert.deepEqual(shielded.vitals, { health: 100, maxhealth: 100, shields: 20, maxshields: 50 });
+    const spillover = applydamage({ health: 100, maxhealth: 100, shields: 20, maxshields: 50 }, 70);
+    assert.equal(spillover.absorbed, 20);
+    assert.equal(spillover.vitals.health, 50);
+    assert.equal(spillover.overflow, 0);
+    const lethal = applydamage({ health: 100, maxhealth: 100, shields: 0, maxshields: 50 }, 200);
+    assert.equal(lethal.vitals.health, 0);
+    assert.equal(lethal.overflow, 100);
+    assert.equal(applydamage(FULL, -5).overflow, 0);
+  });
+
+  it("answers life and the armor-perk effective pool", () => {
+    assert.equal(healthfraction(FULL), 1);
+    assert.ok(Math.abs(healthfraction({ ...FULL, health: 25 }) - 0.25) < 1e-9);
+    assert.ok(Math.abs(shieldfraction({ ...FULL, shields: 25 }) - 0.5) < 1e-9);
+    assert.equal(shieldfraction({ health: 1, maxhealth: 1, shields: 0, maxshields: 0 }), 0);
+    assert.equal(isalive(FULL), true);
+    assert.equal(isalive({ health: 0, maxhealth: 100, shields: 50, maxshields: 50 }), false);
+    assert.equal(effectivepool({ health: 50, maxhealth: 100, shields: 40, maxshields: 50 }, 0.5), 70);
+    assert.equal(effectivepool({ health: 50, maxhealth: 100, shields: 40, maxshields: 50 }, 2), 90);
+    assert.equal(effectivepool({ health: 50, maxhealth: 100, shields: 40, maxshields: 50 }, -1), 50);
+  });
+});
+
+describe("minimap transform", () => {
+  it("computes the padded bounds of a position cloud", () => {
+    assert.deepEqual(
+      minimapbounds(
+        [
+          { x: 0, z: 10 },
+          { x: 30, z: -10 },
+        ],
+        5,
+      ),
+      { minx: -5, minz: -15, maxx: 35, maxz: 15 },
+    );
+    assert.deepEqual(minimapbounds([], 5), { minx: -5, minz: -5, maxx: 5, maxz: 5 });
+  });
+
+  it("maps the world with facing up and z flipped into screen y", () => {
+    assert.deepEqual(tominimap(WIDGET, { x: 0, z: 0 }), { x: 90, y: 90, clamped: false });
+    assert.deepEqual(tominimap(WIDGET, { x: 0, z: 40 }), { x: 90, y: 18, clamped: false });
+    assert.deepEqual(tominimap(WIDGET, { x: 40, z: 0 }), { x: 162, y: 90, clamped: false });
+  });
+
+  it("rotates the world by the receiver yaw", () => {
+    const rotated = minimapconfig(WIDGET.bounds, WIDGET.sizepx, Math.PI / 2, WIDGET.padding);
+    assert.deepEqual(tominimap(rotated, { x: 40, z: 0 }), { x: 90, y: 18, clamped: false });
+    assert.deepEqual(tominimap(rotated, { x: 0, z: -40 }), { x: 162, y: 90, clamped: false });
+  });
+
+  it("clamps outside positions onto the rim with the flag", () => {
+    const rimmed = tominimap(WIDGET, { x: 100, z: 0 });
+    assert.equal(rimmed.x, 190);
+    assert.equal(rimmed.y, 90);
+    assert.equal(rimmed.clamped, true);
+    assert.equal(tominimap(WIDGET, { x: 10, z: 10 }).clamped, false);
+  });
+});
+
+describe("hitmarkers", () => {
+  it("ranks the kinds and exposes their windows", () => {
+    assert.equal(hitmarkerfor(true, true), "kill");
+    assert.equal(hitmarkerfor(false, true), "headshot");
+    assert.equal(hitmarkerfor(false, false), "body");
+    assert.equal(hitmarkerwindow("body"), HITWINDOWS.body);
+    assert.equal(hitmarkerwindow("headshot"), HITWINDOWS.headshot);
+    assert.equal(hitmarkerwindow("kill"), HITWINDOWS.kill);
+  });
+
+  it("keeps only the markers still inside their window", () => {
+    const markers: Hitmarker[] = [
+      { id: "m1", at: 0, kind: "body" },
+      { id: "m2", at: 100, kind: "headshot" },
+      { id: "m3", at: 300, kind: "kill" },
+    ];
+    assert.deepEqual(
+      activehitmarkers(markers, 400).map((marker) => marker.id),
+      ["m2", "m3"],
+    );
+    assert.equal(activehitmarkers(markers, 900).length, 0);
+    assert.equal(pushhitmarker(markers, { id: "m4", at: 500, kind: "body" }).length, 4);
+  });
+});
+
+describe("killfeed", () => {
+  it("dedups by id and caps the feed", () => {
+    const feed = pushkillfeed([], kill("k1", 100));
+    const refreshed = pushkillfeed(feed, { ...kill("k1", 150), victim: "tide-3" });
+    assert.equal(refreshed.length, 1);
+    assert.equal(refreshed[0].at, 150);
+    assert.equal(refreshed[0].victim, "tide-3");
+    let capped: KillfeedEntry[] = [];
+    for (let i = 0; i < 8; i++) capped = pushkillfeed(capped, kill(`k${i}`, i * 100));
+    assert.equal(capped.length, KILLFEEDCAP);
+    assert.equal(capped[0].id, "k2");
+    assert.equal(capped[capped.length - 1].id, "k7");
+  });
+
+  it("expires rows past the ttl", () => {
+    const feed = [kill("k1", 1000), kill("k2", 7000)];
+    assert.deepEqual(
+      prunekillfeed(feed, 8500, KILLFEEDTTL).map((row) => row.id),
+      ["k1", "k2"],
+    );
+    assert.deepEqual(
+      prunekillfeed(feed, 9100, KILLFEEDTTL).map((row) => row.id),
+      ["k2"],
+    );
+  });
+
+  it("renders the plain feed line with the headshot mark", () => {
+    assert.equal(killfeedline(kill("k1", 0)), "ember-1 [raven] tide-2");
+    assert.equal(killfeedline({ ...kill("k1", 0), headshot: true }), "ember-1 [raven] tide-2 ⊕");
+  });
+});
+
+describe("directional damage", () => {
+  it("points front, right, behind and left relative to the yaw", () => {
+    assert.equal(directionaldamage({ x: 0, z: 20 }, { x: 0, z: 0 }, 0).sector, "front");
+    assert.equal(directionaldamage({ x: 20, z: 0 }, { x: 0, z: 0 }, 0).sector, "right");
+    assert.equal(directionaldamage({ x: 0, z: -20 }, { x: 0, z: 0 }, 0).sector, "behind");
+    assert.equal(directionaldamage({ x: -20, z: 0 }, { x: 0, z: 0 }, 0).sector, "left");
+    const faced = directionaldamage({ x: 20, z: 0 }, { x: 0, z: 0 }, Math.PI / 2);
+    assert.equal(faced.sector, "front");
+    assert.ok(Math.abs(faced.angle) < 1e-9);
+  });
+
+  it("fades the ping strength with distance to the floor", () => {
+    assert.ok(Math.abs(directionaldamage({ x: 0, z: 20 }, { x: 0, z: 0 }, 0).strength - 0.5) < 1e-9);
+    assert.equal(directionaldamage({ x: 0, z: 200 }, { x: 0, z: 0 }, 0).strength, DAMAGESTRENGTHFLOOR);
+    assert.equal(sectorof(Math.PI), "behind");
+    assert.equal(sectorof((7 * Math.PI) / 4), "left");
+  });
+});

package/tests/matchrules.test.ts

@@ -0,0 +1,219 @@
+// # matchrules.test — honest unit tests for the match rules state machine,
+// runnable with the vitest runner:
+//   pnpm test
+// The fixtures reuse the match seed rows of the root match logic.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { MATCHPLAYERSEED, MATCHSEED, type MatchLobby } from "../match.ts";
+import {
+  addscore,
+  advancelobby,
+  canlobbytransition,
+  canroundtransition,
+  matchruleserror,
+  nextactions,
+  openround,
+  progressof,
+  scoreround,
+  seatplayers,
+  transitionlobby,
+} from "../matchrules.ts";
+
+/** finds one seeded lobby by id (the tests key on the seed rows). */
+function lobby(id: string): MatchLobby {
+  const row = MATCHSEED.find((candidate) => candidate.id === id);
+  assert.ok(row, `seed lobby ${id} missing`);
+  return row;
+}
+
+describe("match rules transitions", () => {
+  it("allows only the table transitions for lobbies", () => {
+    assert.equal(canlobbytransition("open", "live"), true);
+    assert.equal(canlobbytransition("open", "closed"), true);
+    assert.equal(canlobbytransition("live", "open"), false);
+    assert.equal(canlobbytransition("closed", "live"), false);
+    assert.equal(canlobbytransition("closed", "closed"), false);
+  });
+
+  it("allows only pending -> live -> scored for rounds", () => {
+    assert.equal(canroundtransition("pending", "live"), true);
+    assert.equal(canroundtransition("live", "scored"), true);
+    assert.equal(canroundtransition("pending", "scored"), false);
+    assert.equal(canroundtransition("scored", "live"), false);
+  });
+
+  it("moves a lobby and never mutates the input row", () => {
+    const open = lobby("m-2202");
+    const live = transitionlobby(open, "live");
+    assert.equal(live.state, "live");
+    assert.equal(open.state, "open");
+    assert.notEqual(live, open);
+  });
+
+  it("rejects a forbidden lobby transition with a typed error", () => {
+    const closed = lobby("m-2204");
+    assert.throws(
+      () => transitionlobby(closed, "live"),
+      (error: unknown) => {
+        assert.ok(error instanceof matchruleserror);
+        assert.equal(error.code, "bad-transition");
+        assert.equal(error.lobbyid, "m-2204");
+        assert.equal(error.from, "closed");
+        assert.equal(error.to, "live");
+        return true;
+      },
+    );
+  });
+
+  it("opens one pending round of a live lobby", () => {
+    const seeded = lobby("m-2202");
+    const live = transitionlobby(seeded, "live");
+    const running = openround(live, "r-4");
+    assert.equal(running.rounds.find((row) => row.id === "r-4")?.state, "live");
+  });
+
+  it("refuses to open a round while another runs or the lobby is not live", () => {
+    const m2201 = lobby("m-2201");
+    assert.throws(() => openround(m2201, "r-3"), matchruleserror);
+    const live = transitionlobby(lobby("m-2202"), "live");
+    const running = openround(live, "r-4");
+    assert.throws(
+      () => openround(running, "r-5"),
+      (error: unknown) => {
+        assert.ok(error instanceof matchruleserror);
+        assert.equal(error.code, "bad-transition");
+        return true;
+      },
+    );
+    assert.throws(() => openround(transitionlobby(lobby("m-2202"), "closed"), "r-4"), matchruleserror);
+  });
+
+  it("rejects an unknown round with the unknown-round code", () => {
+    const live = transitionlobby(lobby("m-2202"), "live");
+    assert.throws(
+      () => openround(live, "r-404"),
+      (error: unknown) => {
+        assert.ok(error instanceof matchruleserror);
+        assert.equal(error.code, "unknown-round");
+        return true;
+      },
+    );
+  });
+
+  it("scores the live round and the scored table rows stay scoreable by id", () => {
+    const live = transitionlobby(lobby("m-2202"), "live");
+    const running = openround(live, "r-4");
+    const done = scoreround(running);
+    assert.equal(done.rounds.find((row) => row.id === "r-4")?.state, "scored");
+    const reopened = openround(done, "r-5");
+    const scored = scoreround(reopened, "r-5");
+    assert.equal(scored.rounds.find((row) => row.id === "r-5")?.state, "scored");
+  });
+});
+
+describe("match rules capacity and scoring", () => {
+  it("seats players while the capacity holds and refuses overflow", () => {
+    const seated = lobby("m-2202");
+    const ok = seatplayers(
+      seated,
+      MATCHPLAYERSEED.filter((player) => player.lobbyid === "m-2202"),
+    );
+    assert.equal(ok.length, 2);
+    const overflow = [
+      ...MATCHPLAYERSEED,
+      { id: "p-99", lobbyid: "m-2202", handle: "overflow.seat", squad: "ash", score: 0, ping: 60 },
+    ];
+    assert.throws(
+      () => seatplayers(seated, overflow),
+      (error: unknown) => {
+        assert.ok(error instanceof matchruleserror);
+        assert.equal(error.code, "lobby-full");
+        return true;
+      },
+    );
+  });
+
+  it("adds score, floors penalties at zero and refuses non finite deltas", () => {
+    const seat = MATCHPLAYERSEED[0];
+    assert.equal(addscore(seat, 120).score, seat.score + 120);
+    assert.equal(addscore({ ...seat, score: 40 }, -90).score, 0);
+    assert.throws(() => addscore(seat, Number.NaN), matchruleserror);
+  });
+});
+
+describe("match rules tick simulator", () => {
+  it("opens an open lobby on the first tick", () => {
+    const result = advancelobby(lobby("m-2202"), 0, { roundbudgetseconds: 300, autoadvance: false });
+    assert.equal(result.lobby.state, "live");
+    assert.deepEqual(
+      result.events.map((event) => event.kind),
+      ["lobby-live"],
+    );
+  });
+
+  it("expires a live round past its budget and autoadvances the next one", () => {
+    const seeded = lobby("m-2202");
+    const first = advancelobby(seeded, 0, { roundbudgetseconds: 300, autoadvance: true });
+    assert.equal(first.lobby.rounds.find((row) => row.id === "r-4")?.state, "live");
+    const second = advancelobby(first.lobby, 301, { roundbudgetseconds: 300, autoadvance: true });
+    assert.equal(second.lobby.rounds.find((row) => row.id === "r-4")?.state, "scored");
+    assert.equal(second.lobby.rounds.find((row) => row.id === "r-5")?.state, "live");
+    assert.ok(second.events.some((event) => event.kind === "round-expired" && event.roundid === "r-4"));
+    assert.ok(second.events.some((event) => event.kind === "round-live" && event.roundid === "r-5"));
+  });
+
+  it("closes the lobby when every round is scored", () => {
+    let current = transitionlobby(lobby("m-2202"), "live");
+    current = scoreround(openround(current, "r-4"));
+    current = scoreround(openround(current, "r-5"));
+    const ticked = advancelobby(current, 0, { roundbudgetseconds: 300, autoadvance: true });
+    assert.equal(ticked.lobby.state, "closed");
+    assert.deepEqual(
+      ticked.events.map((event) => event.kind),
+      ["lobby-closed"],
+    );
+  });
+
+  it("keeps a live round inside its budget untouched", () => {
+    const seeded = lobby("m-2202");
+    const first = advancelobby(seeded, 0, { roundbudgetseconds: 300, autoadvance: true });
+    const second = advancelobby(first.lobby, 120, { roundbudgetseconds: 300, autoadvance: true });
+    assert.equal(second.lobby.state, "live");
+    assert.equal(second.lobby.rounds.find((row) => row.id === "r-4")?.state, "live");
+    assert.equal(second.events.length, 0);
+  });
+
+  it("refuses a bad clock or a bad budget", () => {
+    assert.throws(
+      () => advancelobby(lobby("m-2202"), -1, { roundbudgetseconds: 300, autoadvance: true }),
+      matchruleserror,
+    );
+    assert.throws(
+      () => advancelobby(lobby("m-2202"), 10, { roundbudgetseconds: 0, autoadvance: true }),
+      matchruleserror,
+    );
+  });
+});
+
+describe("match rules board hints", () => {
+  it("hints the board actions in lifecycle order", () => {
+    assert.deepEqual(nextactions(lobby("m-2202")), ["start the match"]);
+    assert.deepEqual(nextactions(lobby("m-2201")), ["score the live round"]);
+    assert.deepEqual(nextactions(lobby("m-2204")), []);
+  });
+
+  it("hints the close action for a live lobby with everything scored", () => {
+    const allscored: MatchLobby = {
+      ...lobby("m-2202"),
+      state: "live",
+      rounds: lobby("m-2202").rounds.map((row) => ({ ...row, state: "scored" })),
+    };
+    assert.deepEqual(nextactions(allscored), ["close the lobby"]);
+  });
+
+  it("measures the scored progress of a lobby", () => {
+    assert.equal(progressof(lobby("m-2201")), 33);
+    assert.equal(progressof(lobby("m-2204")), 100);
+    assert.equal(progressof({ ...lobby("m-2203"), rounds: [] }), 0);
+  });
+});