swarmbox 0.0.0-stage → 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Swarmify contributors
+
+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/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# Swarmbox
 
-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.
+A sandbox where AI agents use your product the way people do: in real browsers, against a throwaway copy of
+it (a _world_), as each of your roles at once. The agent sees what a person sees and what the server did,
+logs what isn't right, and ends with your checks and a report anyone can read.
+
+Built for Swarmify's agents, and usable by any team whose product runs locally. MIT licensed.
+
+## What it gives an agent
+
+- **Sight.** Open dialogs come first and whole when it reads a screen. Every action reports what changed
+  (a dialog opened or closed, a status line, the address), what the server did (its own command and what
+  that set off, and anything that failed or was refused), and requests refused. A click that can't land
+  says what is in the way; of two buttons with one name, the one in the dialog in front is meant.
+- **Worlds.** Each run starts your product the way it is deployed, with its own data, on tenant hosts that
+  resolve only inside the browsers Swarmbox launches. Nothing is shared with other runs or with real data.
+- **People.** Everyone in the world, signed in without a password, each on their own screen; a tablet
+  app past its first screen; a customer at a link, with no sign-in at all. Any screen can be a phone, a
+  tablet either way up or a desktop, light or dark.
+- **The device and props.** Swarmbox makes the photos, documents and signatures a person would use, each tagged
+  with its id. It puts them in a screen's file chooser (a tablet's camera button) or in front of its live camera,
+  and sets where the device is and whether it shows notifications.
+- **Hands on the screen.** Click, type, choose, press keys, draw (a signature pad) and drag with the pointer
+  (a block onto another lane, an edge to resize), each element found by its accessible role and name. A styled
+  radio or checkbox is clicked through the label drawn over it, and of two alike in stacked layers, the one in
+  front is taken.
+- **Time.** Move a world's clock forward, and every screen follows; people stay signed in across the jump
+  (`renewSignIn`). A kept world that comes back with its clock moved on an earlier run starts its screens on its
+  own time. A scenario can say when its day starts (`world.startsAt`: "09:00", or a date and time
+  in the tenant's zone, to test across a time change). Swarmbox works out times with Node's tzdata; a
+  screen shows them with Chromium's own, and the two can differ on a zone whose rules changed recently.
+  A time a screen shows an hour out may be that, not your product.
+- **Runs.** A scenario in plain words (what to try, what good looks like, who is on screen), findings with
+  screenshots, Playwright traces of every screen, your checks at the end, and one HTML report.
+- **A control room** at http://127.0.0.1:3100: every screen live, and take-over, during which the agent's
+  actions on that screen are refused.
+- **The world's own log** (`world_log`), when the product shares it: the stack behind a screen's
+  "something went wrong", while the world runs.
+- **A daily budget** in browser-minutes and runs.
+
+## Install
+
+```sh
+pnpm add -D swarmbox playwright-core
+pnpm exec playwright-core install chromium
+```
+
+`playwright-core` is a peer dependency, so your product and Swarmbox share one copy. Node 24 or later.
+
+## Plugging a product in
+
+A product is one object (`Product` in `src/product.ts`): how to start a world, who is in it, how each of
+them signs in, and how to check the world afterwards. Then:
+
+```ts
+import { serve } from 'swarmbox';
+import { myProduct } from './product.ts';
+
+await serve(myProduct());
+```
+
+```sh
+claude mcp add --transport http swarmbox-myproduct http://127.0.0.1:3101/mcp
+```
+
+`test/fixtures/sample-product.ts` is a complete product in about 200 lines.
+
+A product can take options of its own for a world (`worldOptions`, as zod fields): a tenant still
+migrating from another system, a feature switched on. `world_create` takes them as `options` and a
+scenario as `world.options`.
+
+What adapters have learnt so far:
+
+- **Mint sessions on the world's time.** A world's clock can be days ahead of the machine's, so a session dated on
+  the machine's clock may already be over to the product. Date it from the product's own clock (its hooks).
+- **Renew by extending, not replacing** (`renewSignIn`). An open page often keeps something derived from its
+  session (a CSRF token); a fresh session under it ends in the product's "sign in again".
+- **Share the server's output** (`log`): `world_log` is how an agent gets from a screen's "something went wrong" to
+  the stack.
+- **In the product's own tests, check for the tools it relies on, not Swarmbox's whole list**: each release adds
+  tools.
+- **Give each of the product's system tests its own port**, apart from the one a running sandbox uses.
+
+### In production
+
+A product that uses stand-ins calls the guard as it starts in production, before it builds any provider client:
+
+```ts
+import { assertNoStandins } from 'swarmbox';
+
+if (process.env.NODE_ENV === 'production') assertNoStandins(process.env, { allowLoopback: ['METRICS_URL'] });
+```
+
+It refuses to start with anything a stand-in issued (marked keys, fictional 555-01xx numbers), a provider address on
+this machine however it's written, or Swarmbox's local certificate authority. It names the variable, never its
+value. `allowLoopback` lists variables that really do point at this machine in production.
+
+### Hooks
+
+A product can serve Swarmbox's hooks (protocol v0, `src/hooks.ts`) in its sandbox worlds: a feed of what the
+server did, the clock, the phone inbox, and fake providers with rules (fail the next text, a customer
+replying). Without them Swarmbox still drives the screens; with them the agent sees the `server:` lines
+after each action and can move time.
+
+## Developing
+
+```sh
+pnpm install
+pnpm run check          # typecheck, lint, formatting
+pnpm test               # unit tests
+pnpm exec playwright-core install chromium
+pnpm run test:browser   # everything, the browser tests too
+```
+
+Node 24. The source runs as TypeScript in tests; the package ships `dist/` (`pnpm run build`).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to send a change, and [SECURITY.md](SECURITY.md) to report a
+security problem.
+
+## Licence
+
+[MIT](LICENSE).

package/dist/checks.d.ts

@@ -0,0 +1,48 @@
+export type Outcome = 'pass' | 'fail' | 'nothing-to-check' | 'error' | 'known-red' | 'known-red-now-passes';
+export interface Violation {
+    summary: string;
+    /** The rows behind it, for the report (a few are shown). */
+    rows?: Record<string, unknown>[];
+}
+export interface CheckResult {
+    id: string;
+    title: string;
+    /** Where it ran: a tenant, or what the product calls its other scopes ("control", "code"). */
+    where: string;
+    outcome: Outcome;
+    /** How much it looked at: a check with nothing to look at says so instead of passing. */
+    examined: number;
+    unit: string;
+    violations: Violation[];
+    error?: string;
+    /** A known, ticketed defect this check is red for. */
+    knownRed?: {
+        ref: string;
+        why: string;
+    };
+}
+/** Background work still outstanding when settling gave up: an event a handler has not finished. */
+export interface Pending {
+    seq: number;
+    type: string;
+    handler: string;
+    /** Null when the handler has not picked the work up at all. */
+    status: string | null;
+    lastError: string | null;
+}
+export interface Settled {
+    settled: boolean;
+    /** How long it took, or how long it waited before giving up. */
+    ms: number;
+    /** What was still outstanding when it gave up; empty when settled. */
+    pending: Pending[];
+    /** Outstanding work that is a known, ticketed defect: reported, never dropped, and never waited for. */
+    known: Array<Pending & {
+        ref: string;
+    }>;
+}
+/** A plain-text report: failures first, then what could not be checked, then passes. */
+export declare function formatReport(results: CheckResult[]): string;
+/** Failing or broken checks: what a run's end counts. */
+export declare const failing: (results: CheckResult[]) => CheckResult[];
+//# sourceMappingURL=checks.d.ts.map

package/dist/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../src/checks.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,kBAAkB,GAAG,OAAO,GAAG,WAAW,GAAG,sBAAsB,CAAC;AAE5G,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAED,oGAAoG;AACpG,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,wGAAwG;IACxG,KAAK,EAAE,KAAK,CAAC,OAAO,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzC;AAWD,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAqB3D;AAED,yDAAyD;AACzD,eAAO,MAAM,OAAO,GAAI,SAAS,WAAW,EAAE,KAAG,WAAW,EACU,CAAC"}

package/dist/checks.js

@@ -0,0 +1,43 @@
+// What a product's checks report, and how a run shows them. The checks themselves are the product's: rules
+// its data must always obey, asked of its database or its code, never of a model.
+//
+// Outcomes are kept distinct on purpose. "Nothing to check" is not a pass, an error is not a pass, and a
+// known defect that starts passing is announced, not quietly taken as good news.
+const MARK = {
+    pass: 'pass',
+    fail: 'FAIL',
+    error: 'ERROR',
+    'nothing-to-check': 'nothing to check yet',
+    'known-red': 'known red',
+    'known-red-now-passes': 'KNOWN RED NOW PASSES',
+};
+/** A plain-text report: failures first, then what could not be checked, then passes. */
+export function formatReport(results) {
+    const order = ['fail', 'error', 'known-red-now-passes', 'known-red', 'nothing-to-check', 'pass'];
+    const sorted = [...results].sort((a, b) => order.indexOf(a.outcome) - order.indexOf(b.outcome));
+    const tally = order
+        .map((o) => [o, results.filter((r) => r.outcome === o).length])
+        .filter(([, n]) => n > 0)
+        .map(([o, n]) => `${n} ${MARK[o]}`)
+        .join(', ');
+    const lines = [`${results.length} checks: ${tally}`];
+    for (const r of sorted) {
+        const head = `[${MARK[r.outcome]}] ${r.id} @ ${r.where} — ${r.examined} ${r.unit}`;
+        lines.push(head);
+        if (r.error)
+            lines.push(`    error: ${r.error}`);
+        if (r.knownRed)
+            lines.push(`    known defect ${r.knownRed.ref}: ${r.knownRed.why}`);
+        for (const v of r.violations) {
+            lines.push(`    ${v.summary}`);
+            for (const row of v.rows?.slice(0, 5) ?? [])
+                lines.push(`      ${JSON.stringify(row)}`);
+            if ((v.rows?.length ?? 0) > 5)
+                lines.push(`      … ${v.rows.length - 5} more`);
+        }
+    }
+    return lines.join('\n');
+}
+/** Failing or broken checks: what a run's end counts. */
+export const failing = (results) => results.filter((c) => c.outcome === 'fail' || c.outcome === 'error');
+//# sourceMappingURL=checks.js.map

package/dist/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../src/checks.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// swarmbox call <tool> ['{"json":"args"}'] [--port 3101]
+//
+// Call one Swarmbox tool from a shell, through the same MCP server an agent uses: for a session that cannot
+// load the MCP server itself (one already running when Swarmbox started), and for scripts. It prints the
+// tool's text; an image result is saved to a file and its path printed. A refusal prints ERROR and exits 1,
+// so a pipe through grep cannot hide it.
+import { writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { DEFAULT_PORTS } from "./serve.js";
+const USAGE = "usage: swarmbox call <tool> ['{json args}'] [--port <mcp port>]";
+const args = process.argv.slice(2);
+const portAt = args.indexOf('--port');
+const port = portAt >= 0
+    ? Number(args.splice(portAt, 2)[1])
+    : Number(process.env.SWARMBOX_MCP_PORT ?? DEFAULT_PORTS.mcp);
+const [command, tool, raw] = args;
+if (command !== 'call' || !tool || !Number.isInteger(port)) {
+    console.error(USAGE);
+    process.exit(2);
+}
+const client = new Client({ name: 'swarmbox-call', version: '0.1.0' });
+await client.connect(new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${port}/mcp`)));
+try {
+    // Starting a world or a run can take minutes (a product's seed data): past the client's default timeout.
+    const r = (await client.callTool({ name: tool, arguments: raw ? JSON.parse(raw) : {} }, undefined, {
+        timeout: 600_000,
+    }));
+    if (r.isError)
+        console.log('ERROR');
+    for (const c of r.content) {
+        if (c.type === 'text')
+            (r.isError ? console.error : console.log)(c.text);
+        else if (c.type === 'image' && c.data) {
+            const file = join(tmpdir(), `swarmbox-${tool}-${Date.now()}.${c.mimeType?.split('/')[1] ?? 'png'}`);
+            writeFileSync(file, Buffer.from(c.data, 'base64'));
+            console.log(`image: ${file}`);
+        }
+    }
+    process.exitCode = r.isError ? 1 : 0;
+}
+finally {
+    await client.close();
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/control-room/page.d.ts

@@ -0,0 +1,2 @@
+export declare const page: (title: string) => string;
+//# sourceMappingURL=page.d.ts.map

package/dist/control-room/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/control-room/page.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,IAAI,GAAI,OAAO,MAAM,KAAG,MA6MpC,CAAC"}

package/dist/control-room/page.js

@@ -0,0 +1,212 @@
+// The control room page. One file, no build step, no dependencies: it is served by the harness itself.
+//
+// Names and URLs shown here come from the world's data, which an AI tester can write to, so every value
+// is set with textContent and never parsed as HTML. The title is the product's own, escaped here.
+const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+export const page = (title) => /* html */ `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)} · Swarmbox</title>
+<style>
+  :root {
+    --bg: #f6f5f2; --panel: #ffffff; --ink: #1c1b19; --muted: #6b6860; --line: #e2dfd8;
+    --agent: #2f6f4f; --agent-bg: #e3f0e8; --person: #9a4a12; --person-bg: #fbeadb;
+    color-scheme: light;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #141413; --panel: #1d1c1a; --ink: #ece9e2; --muted: #9a968c; --line: #2e2d2a;
+      --agent: #7fc8a1; --agent-bg: #1d3328; --person: #f0a26a; --person-bg: #3a2516;
+      color-scheme: dark;
+    }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--ink);
+    font: 14px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; }
+  header { display: flex; align-items: baseline; gap: 16px; padding: 18px 24px 8px; flex-wrap: wrap; }
+  h1 { font-size: 17px; margin: 0; font-weight: 650; letter-spacing: -0.01em; }
+  #worlds { color: var(--muted); font-size: 13px; }
+  #worlds a { color: inherit; }
+  main { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 520px), 1fr)); gap: 16px; padding: 12px 24px 32px; }
+  .tile { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; overflow: hidden; display: flex; flex-direction: column; }
+  .tile.person { border-color: var(--person); box-shadow: 0 0 0 1px var(--person); }
+  .bar { display: flex; align-items: center; gap: 10px; padding: 10px 12px; border-bottom: 1px solid var(--line); }
+  .who { font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .where { color: var(--muted); font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; flex: 1; min-width: 0; }
+  .badge { font-size: 12px; font-weight: 600; padding: 2px 8px; border-radius: 999px; white-space: nowrap; }
+  .badge.agent { color: var(--agent); background: var(--agent-bg); }
+  .badge.person { color: var(--person); background: var(--person-bg); }
+  button { font: inherit; font-size: 12px; font-weight: 600; padding: 5px 10px; border-radius: 6px; cursor: pointer;
+    border: 1px solid var(--line); background: var(--bg); color: var(--ink); white-space: nowrap; }
+  button:hover { border-color: var(--muted); }
+  .view { aspect-ratio: 16 / 10; background: var(--bg); display: grid; place-items: center; }
+  .view img { width: 100%; height: 100%; object-fit: contain; display: block; }
+  .view:focus { outline: none; }
+  .tile.person .view { cursor: crosshair; }
+  .tile.person .view:focus { box-shadow: inset 0 0 0 2px var(--person); }
+  .hint { padding: 6px 12px; font-size: 12px; color: var(--person); border-top: 1px solid var(--line); }
+  .url { padding: 6px 12px; font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--muted);
+    border-top: 1px solid var(--line); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .empty { grid-column: 1 / -1; color: var(--muted); padding: 48px 0; text-align: center; }
+  .empty code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--ink); }
+</style>
+</head>
+<body>
+<header><h1>${esc(title)} · Swarmbox</h1><div id="worlds"></div></header>
+<main id="tiles"></main>
+<script>
+  const tiles = new Map();
+  const main = document.getElementById('tiles');
+  const worldsEl = document.getElementById('worlds');
+
+  function el(tag, cls, text) {
+    const n = document.createElement(tag);
+    if (cls) n.className = cls;
+    if (text !== undefined) n.textContent = text;
+    return n;
+  }
+
+  async function post(path, body) {
+    try {
+      await fetch(path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+    } catch {}
+  }
+
+  // Where on the screen a point on the picture is, as fractions: the picture is letterboxed in the tile
+  // (object-fit: contain), so the margins are not part of the screen.
+  function pointOn(img, e) {
+    const r = img.getBoundingClientRect();
+    const iw = img.naturalWidth || 16, ih = img.naturalHeight || 10;
+    const scale = Math.min(r.width / iw, r.height / ih);
+    const w = iw * scale, h = ih * scale;
+    const left = r.left + (r.width - w) / 2, top = r.top + (r.height - h) / 2;
+    const x = (e.clientX - left) / w, y = (e.clientY - top) / h;
+    return x >= 0 && x <= 1 && y >= 0 && y <= 1 ? { x, y } : null;
+  }
+
+  const KEYS = new Set(['Enter', 'Backspace', 'Tab', 'Escape', 'Delete', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown']);
+
+  function tile(s) {
+    const root = el('section', 'tile');
+    const bar = el('div', 'bar');
+    const who = el('div', 'who');
+    const where = el('div', 'where');
+    const badge = el('span', 'badge');
+    const btn = el('button');
+    bar.append(who, where, badge, btn);
+    const view = el('div', 'view');
+    view.tabIndex = 0;
+    const img = el('img');
+    img.alt = 'Live view of ' + s.person;
+    view.append(img);
+    const hint = el('div', 'hint', 'You have this screen: click, scroll and type here. Hand back when done.');
+    const url = el('div', 'url');
+    root.append(bar, view, hint, url);
+    const t = { root, who, where, badge, btn, url, img, view, hint, seq: -1, loading: false, objectUrl: null, id: s.id };
+    const mine = () => root.dataset.controller === 'person';
+    btn.addEventListener('click', async () => {
+      const to = mine() ? 'agent' : 'person';
+      await post('/screens/' + s.id + '/control', { controller: to });
+      await refresh();
+      if (to === 'person') view.focus();
+    });
+    view.addEventListener('click', (e) => {
+      if (!mine()) return;
+      view.focus();
+      const p = pointOn(img, e);
+      if (p) post('/screens/' + s.id + '/input', { type: 'click', x: p.x, y: p.y }).then(() => refresh());
+    });
+    let wheel = 0, wheelAt = null, wheelTimer = null;
+    view.addEventListener('wheel', (e) => {
+      if (!mine()) return;
+      e.preventDefault();
+      wheel += e.deltaY;
+      wheelAt = pointOn(img, e) || { x: 0.5, y: 0.5 };
+      if (!wheelTimer) wheelTimer = setTimeout(() => {
+        const dy = wheel;
+        wheel = 0; wheelTimer = null;
+        post('/screens/' + s.id + '/input', { type: 'wheel', x: wheelAt.x, y: wheelAt.y, dy });
+      }, 80);
+    }, { passive: false });
+    view.addEventListener('keydown', (e) => {
+      if (!mine() || e.metaKey || e.ctrlKey) return;
+      if (e.key.length === 1) {
+        e.preventDefault();
+        post('/screens/' + s.id + '/input', { type: 'text', text: e.key });
+      } else if (KEYS.has(e.key)) {
+        e.preventDefault();
+        post('/screens/' + s.id + '/input', { type: 'key', key: e.key });
+      }
+    });
+    return t;
+  }
+
+  // The tile's picture, fetched only when the screen has a new frame.
+  async function picture(t, seq) {
+    if (t.loading || seq === t.seq) return;
+    t.loading = true;
+    try {
+      const r = await fetch('/screens/' + t.id + '/frame', { cache: 'no-store' });
+      if (r.status === 200) {
+        const next = URL.createObjectURL(await r.blob());
+        const prev = t.objectUrl;
+        t.img.onload = () => { if (prev) URL.revokeObjectURL(prev); };
+        t.img.src = next;
+        t.objectUrl = next;
+        t.seq = Number(r.headers.get('x-frame-seq') || seq);
+      }
+    } catch {} finally {
+      t.loading = false;
+    }
+  }
+
+  function update(t, s) {
+    t.root.dataset.controller = s.controller;
+    t.root.classList.toggle('person', s.controller === 'person');
+    t.hint.hidden = s.controller !== 'person';
+    t.who.textContent = s.person;
+    t.where.textContent = s.tenant + ' · ' + s.world + ' · ' + s.id;
+    t.badge.className = 'badge ' + s.controller;
+    t.badge.textContent = s.controller === 'person' ? 'You have it' : 'Agent driving';
+    t.btn.textContent = s.controller === 'person' ? 'Hand back' : 'Take over';
+    t.url.textContent = s.url;
+    picture(t, s.frameSeq);
+  }
+
+  async function refresh() {
+    let state;
+    try { state = await (await fetch('/state', { cache: 'no-store' })).json(); } catch { return; }
+    worldsEl.replaceChildren();
+    for (const w of state.worlds) {
+      for (const c of w.tenants) {
+        const a = el('a', null, c.slug);
+        a.href = c.origin;
+        worldsEl.append(w.id + ' ', a, '  ');
+      }
+    }
+    const seen = new Set();
+    for (const s of state.screens) {
+      seen.add(s.id);
+      let t = tiles.get(s.id);
+      if (!t) { t = tile(s); tiles.set(s.id, t); main.append(t.root); }
+      update(t, s);
+    }
+    for (const [id, t] of tiles) if (!seen.has(id)) { t.root.remove(); if (t.objectUrl) URL.revokeObjectURL(t.objectUrl); tiles.delete(id); }
+    const empty = main.querySelector('.empty');
+    if (state.screens.length === 0 && !empty) {
+      const e = el('div', 'empty');
+      e.append('No screens open. From Claude: ', el('code', null, 'world_create'), ', then ', el('code', null, 'screen_open'), '.');
+      main.append(e);
+    } else if (state.screens.length && empty) empty.remove();
+  }
+
+  // Short, frequent requests: a tile's picture is fetched only when its screen has a new frame.
+  refresh();
+  setInterval(refresh, 300);
+</script>
+</body>
+</html>
+`;
+//# sourceMappingURL=page.js.map

package/dist/control-room/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../../src/control-room/page.ts"],"names":[],"mappings":"AAAA,uGAAuG;AACvG,EAAE;AACF,wGAAwG;AACxG,kGAAkG;AAElG,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CACxB,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;AAE9G,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,UAAU,CAAC;;;;;SAKjD,GAAG,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8CL,GAAG,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0JvB,CAAC"}

package/dist/control-room/server.d.ts

@@ -0,0 +1,8 @@
+import type { Harness } from '../harness.ts';
+import type { ProductWorld } from '../product.ts';
+export interface ControlRoom {
+    url: string;
+    close(): Promise<void>;
+}
+export declare function serveControlRoom<W extends ProductWorld>(h: Harness<W>, port: number): Promise<ControlRoom>;
+//# sourceMappingURL=server.d.ts.map

package/dist/control-room/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/control-room/server.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAMlD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,YAAY,EAC3D,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EACb,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,CAAC,CA6KtB"}