chesspal 0.3.5 → 0.4.0

package/dist/server/page/table.js

@@ -1,9 +1,10 @@
 import { setTimeout as delay } from "node:timers/promises";
-import { gameAt, samePosition } from "../../commands/index.js";
+import { analystOf, gameAt, samePosition } from "../../commands/index.js";
 import { endOf, gameInAnalysis } from "../../games/index.js";
 import { gameFolder } from "../../profiles/index.js";
 import { tellWatchers } from "./events.js";
 import { bodyOf, isJson, jsonOf, runRoute, sendJson } from "./http.js";
+import { giveOpening, releaseOpening } from "./windows.js";
 /** What the table's page shows of its chat: whether one is at the table, with which host, the hosts it can open one in, and one opening. */
 export function tableShown(served) {
     const { table, attached } = served;
@@ -21,7 +22,8 @@ export function tableShown(served) {
             ...(held === undefined ? {} : { started: held }),
             hosts: table.chats?.hosts() ?? [],
             ...(now === undefined ? {} : { opening: now }),
-            ...(served.restartWanted === undefined ? {} : { waiting: true }),
+            ...(served.chatWait === undefined ? {} : { waiting: served.chatWait.for }),
+            ...(served.waitRefused === undefined ? {} : { refused: served.waitRefused }),
         },
     };
 }
@@ -36,6 +38,9 @@ export function answerTable(request, response, url, served) {
         sendJson(response, 200, { quitting: true });
         served.table.quit();
     }
+    else if (path === "/api/table/open") {
+        runRoute(response, () => openWindow(request, response, served));
+    }
     else if (path === "/api/table/chat") {
         runRoute(response, () => openChat(request, response, served));
     }
@@ -50,7 +55,7 @@ export function answerTable(request, response, url, served) {
     }
     else {
         sendJson(response, 404, {
-            error: `${path} is no route of the table's: it answers POST /api/table/chat, /api/table/restart, /api/table/waiting, /api/table/update and /api/table/quit.`,
+            error: `${path} is no route of the table's: it answers POST /api/table/open, /api/table/chat, /api/table/restart, /api/table/waiting, /api/table/update and /api/table/quit.`,
         });
     }
     return true;
@@ -72,26 +77,47 @@ export function relaunchChat(served, how = "again", host) {
     const folder = served.attached?.chat.folder;
     // Another host may first ask whether it trusts the table's folder: the pages say so, as for a chat opened.
     const switching = how === "restart" && host !== undefined && host !== hostAtTable(served);
-    if (folder === undefined || served.table?.chats?.relaunch(folder, host) !== true) {
+    if (folder === undefined || heldChat(served) === undefined || served.table?.chats?.relaunch(folder, host) !== true) {
         return false;
     }
     noteOpening(served, switching ? "chat" : how);
     return true;
 }
-/** Starts the chat again as the page asked while it was at work, now that it has ended its answer; a chat gone meanwhile takes the request with it. */
-export function restartWhenAtRest(served) {
-    const wanted = served.restartWanted;
-    if (wanted === undefined) {
+/**
+ * Whether a new game that wants a clean chat waits for the chat at the table to end its answer, then starts it again (D-57, D-107): `chesspal play` holds
+ * it, it is at work, and no analyst of it is; with an analyst at work the player is asked for /clear, as with a chat opened by hand.
+ */
+export function chatToWaitFor(served) {
+    return heldChat(served) !== undefined && !chatAtRest(served) && !analystAtWork(served);
+}
+/**
+ * Does what the page asked while the chat was at work, now that it has ended its answer. A chat gone meanwhile takes a start again with it; a new game
+ * starts without it, and loses nothing: the next chat at the table is a clean one.
+ */
+export function startWhenAtRest(served) {
+    const wanted = served.chatWait;
+    const gone = heldChat(served) === undefined;
+    if (wanted === undefined || (!gone && !chatAtRest(served))) {
         return;
     }
-    if (heldChat(served) === undefined) {
-        served.restartWanted = undefined;
-    }
-    else if (chatAtRest(served)) {
-        served.restartWanted = undefined;
-        relaunchChat(served, "restart", wanted.host);
+    served.chatWait = undefined;
+    if (!gone || wanted.for === "new-game") {
+        startWaited(served, wanted);
     }
 }
+/** A new game that waited for the chat could not start (D-107): the pages say why, each once. */
+export function refuseWaited(served, refused) {
+    served.waitRefused = { ...refused, number: (served.waitRefused?.number ?? 0) + 1 };
+    tellWatchers(served.watchers);
+}
+/**
+ * chesspal asks to open the table's window, the newest one staying and the others closing; or, with `release`, lets go of the opening it was given when no
+ * window that reaches the table opened, so that the next chesspal opens its own.
+ */
+async function openWindow(request, response, served) {
+    const release = jsonOf(await bodyOf(request))?.release;
+    sendJson(response, 200, release === undefined ? giveOpening(served) : releaseOpening(served, release));
+}
 // A terminal takes a few seconds to open and its chat to attach: a second click meanwhile would open a second chat, which serves a page of its own.
 const openingFor = 30_000;
 /**
@@ -138,34 +164,38 @@ async function restartChat(request, response, served) {
         sendJson(response, 200, { restarting: relaunchChat(served, "restart", offered.name) });
     }
     else {
-        served.restartWanted = { host: offered.name };
+        served.chatWait = { for: "restart", host: offered.name };
         tellWatchers(served.watchers);
         sendJson(response, 200, { waiting: true });
     }
 }
 /**
- * Ends a start again the page asked while the chat was at work (D-107): `now` starts it at once, cutting the answer it gives, as after an Esc, when it would
- * never end; else the request is let go. Asked by the table's own page alone.
+ * Ends a start again or a new game the page asked while the chat was at work (D-107): `now` starts it at once, cutting the answer the chat gives, as after
+ * an Esc, when it would never end; else the request is let go, and nothing changes. Asked by the table's own page alone.
  */
 async function endWaiting(request, response, served) {
     const now = jsonOf(await bodyOf(request))?.now;
-    const wanted = served.restartWanted;
+    const wanted = served.chatWait;
     if (!fromTablePage(request, served)) {
-        sendJson(response, 403, { error: "Only the table's own page ends a start again that waits." });
+        sendJson(response, 403, { error: "Only the table's own page ends what waits for the chat." });
     }
     else if (typeof now !== "boolean") {
-        sendJson(response, 400, { error: "Say now: true to start the chat again at once, cutting its answer, or now: false to let the request go." });
+        sendJson(response, 400, { error: "Say now: true to start the chat again or the new game at once, cutting its answer, or now: false to let the request go." });
     }
     else if (wanted === undefined) {
-        sendJson(response, 409, { error: "No start again waits: ask for one from the chat's window." });
+        sendJson(response, 409, { error: "Nothing waits for the chat: ask for a start again from the chat's window, or for a new game." });
     }
     else {
-        served.restartWanted = undefined;
-        const restarting = now && heldChat(served) !== undefined && relaunchChat(served, "restart", wanted.host);
+        served.chatWait = undefined;
+        const restarting = now && startWaited(served, wanted);
         tellWatchers(served.watchers);
         sendJson(response, 200, now ? { restarting } : { waiting: false });
     }
 }
+// What waited for the chat to end its answer, done now: the chat starts again with the host asked, or the new game starts with it starting again clean.
+function startWaited(served, wanted) {
+    return wanted.for === "new-game" ? wanted.start() : relaunchChat(served, "restart", wanted.host);
+}
 /**
  * Once npm has installed the newer Chesspal (D-108), and no game goes on and the chat is at rest, as a game or a chat may have started while npm worked:
  * the chat `chesspal play` holds starts again from it, clean, and once it has left the table, the table closes to start again from it too.
@@ -252,14 +282,24 @@ function hostAtTable(served) {
     return served.attached === undefined ? undefined : served.table?.chats?.hosts().find((one) => said.includes(one.name))?.name;
 }
 // The chat at the table when `chesspal play` holds it, which the table can start again: the model and effort it started with.
+// The chat at the table when it is the one `chesspal play` holds: in its folder and started by it, not another opened there by hand.
 function heldChat(served) {
     const { attached } = served;
-    return attached === undefined ? undefined : served.table?.chats?.held(attached.chat.folder);
+    const held = attached === undefined ? undefined : served.table?.chats?.held(attached.chat.folder);
+    return held === undefined || held.seat !== attached?.chat.seat ? undefined : { model: held.model, effort: held.effort };
 }
 // The chat waits for the doorbell, out of a turn, and no analyst of it is at work: starting it again loses nothing.
 function chatAtRest(served) {
     const { bell } = served;
-    return bell.listening && !bell.inTurn && gameInAnalysis(gameFolder(served.context.home()))?.analyst === undefined;
+    return bell.listening && !bell.inTurn && !analystAtWork(served);
+}
+/**
+ * Whether the chat's analyst is at work, on `game` when named: one whose chat started again since it took its game, or that has written nothing for half an
+ * hour, is gone (D-109). The chat's starts are in its own folder: on the table, the attached chat's.
+ */
+export function analystAtWork(served, game = gameInAnalysis(gameFolder(served.context.home()))?.analyst?.game) {
+    const chat = { ...served.context, folder: served.attached?.chat.folder ?? served.folder };
+    return game !== undefined && analystOf(chat, game) !== undefined;
 }
 // The pages show a chat opening from now until it attaches; one that has not by then lets them open another. The opening noted.
 function noteOpening(served, how) {

package/dist/server/page/update.d.ts

@@ -8,7 +8,7 @@ export interface UpdateShown {
     readonly installing?: true;
     readonly installed?: true;
 }
-/** Asks npm for Chesspal's latest version now and once a day after, the pages told when it is newer than this one; how to stop. None in the tests. */
+/** Asks npm for Chesspal's latest version now and every hour after, the pages told when it is newer than this one; how to stop. None in the tests. */
 export declare function watchForUpdates(served: Served, every?: number): () => void;
 /** The newer Chesspal the page shows, when npm has one. */
 export declare function updateShown(served: Served): {

package/dist/server/page/update.js

@@ -1,10 +1,10 @@
-// A newer Chesspal on npm (D-108): the page's server asks as it starts and once a day after; the table's page offers to install it, a chat's own page says
+// A newer Chesspal on npm (D-108): the page's server asks as it starts and every hour after; the table's page offers to install it, a chat's own page says
 // the command to type.
 import { answerTime, askSite } from "../../sites/index.js";
 import { isOlder, version } from "../../version.js";
 import { tellWatchers } from "./events.js";
-/** Asks npm for Chesspal's latest version now and once a day after, the pages told when it is newer than this one; how to stop. None in the tests. */
-export function watchForUpdates(served, every = aDay) {
+/** Asks npm for Chesspal's latest version now and every hour after, the pages told when it is newer than this one; how to stop. None in the tests. */
+export function watchForUpdates(served, every = anHour) {
     const fetch = served.context.fetch;
     if (fetch === undefined) {
         return () => undefined;
@@ -37,4 +37,4 @@ export async function latestVersion(fetch) {
     return answer?.status === 200 && typeof said === "string" && /^\d+\.\d+\.\d+$/.test(said) ? said : undefined;
 }
 const latestUrl = "https://registry.npmjs.org/chesspal/latest";
-const aDay = 24 * 60 * 60 * 1000;
+const anHour = 60 * 60 * 1000;

package/dist/server/page/windows.d.ts

@@ -0,0 +1,22 @@
+import type { Served } from "./page.ts";
+/** What the table keeps of its windows: the opening last given, the one that has not connected yet, and the newest window connected. */
+export interface TableWindows {
+    given: number;
+    pending?: {
+        readonly opening: number;
+        readonly at: number;
+    } | undefined;
+    newest: number;
+}
+/** How long, in milliseconds, an opening given waits for its window to connect before another may open one. */
+export declare const openingWait = 10000;
+/** Answers `chesspal` asking to open a window: its opening's number, or none while another opening has not connected yet. */
+export declare function giveOpening(served: Served): {
+    opening: number | null;
+};
+/** Lets go of an opening whose window will never reach the table, as no browser started or only a tab did: whether it was the one pending. */
+export declare function releaseOpening(served: Served, opening: unknown): {
+    released: boolean;
+};
+/** A page connects to the events with the opening of its window, when the table opened it: every page hears which window is the newest. */
+export declare function windowConnected(served: Served, url: URL): void;

package/dist/server/page/windows.js

@@ -0,0 +1,45 @@
+/** How long, in milliseconds, an opening given waits for its window to connect before another may open one. */
+export const openingWait = 10_000;
+/** Answers `chesspal` asking to open a window: its opening's number, or none while another opening has not connected yet. */
+export function giveOpening(served) {
+    const windows = windowsOf(served);
+    const now = served.context.now().getTime();
+    if (windows.pending !== undefined && now - windows.pending.at < openingWait) {
+        return { opening: null };
+    }
+    windows.given = Math.max(now, windows.given + 1);
+    windows.pending = { opening: windows.given, at: now };
+    return { opening: windows.given };
+}
+/** Lets go of an opening whose window will never reach the table, as no browser started or only a tab did: whether it was the one pending. */
+export function releaseOpening(served, opening) {
+    const windows = windowsOf(served);
+    const released = windows.pending !== undefined && windows.pending.opening === opening;
+    if (released) {
+        windows.pending = undefined;
+    }
+    return { released };
+}
+/** A page connects to the events with the opening of its window, when the table opened it: every page hears which window is the newest. */
+export function windowConnected(served, url) {
+    const opening = Number(url.searchParams.get("window"));
+    if (served.table === undefined || !Number.isSafeInteger(opening) || opening <= 0) {
+        return;
+    }
+    const windows = windowsOf(served);
+    windows.newest = Math.max(windows.newest, opening);
+    windows.given = Math.max(windows.given, opening);
+    if (windows.pending !== undefined && windows.pending.opening <= opening) {
+        windows.pending = undefined;
+    }
+    tellNewest(served.watchers, windows.newest);
+}
+function windowsOf(served) {
+    served.windows ??= { given: 0, newest: 0 };
+    return served.windows;
+}
+function tellNewest(watchers, newest) {
+    for (const watcher of watchers) {
+        watcher.write(`data: window ${newest}\n\n`);
+    }
+}

package/dist/server/ports/index.d.ts

@@ -0,0 +1 @@
+export { askPage, type BellProbe, bellProbe, chatFolder, type ChatHook, findChatPage, notedFolder, notedPagePorts, pageAt, pageNote, pagePorts, probeOf, probeWait, serverHome, type TableChat, tellChatAtWork } from "./ports.ts";

package/dist/server/ports/index.js

@@ -0,0 +1,2 @@
+// Where a folder's page answers, and how a hook finds its chat's page and tells it the chat is at work: light, for the prompt hook of every message.
+export { askPage, bellProbe, chatFolder, findChatPage, notedFolder, notedPagePorts, pageAt, pageNote, pagePorts, probeOf, probeWait, serverHome, tellChatAtWork } from "./ports.js";

package/dist/server/ports/ports.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Whose page answers at a port, for the hook to find its own: the chat's session, the player's folder, whether a browser has the page open, Chesspal's
+ * version, and whether the table serves it (D-104), with the session and the folder of the chat attached to it, never its own process's.
+ */
+export declare function bellProbe(folder: string, open?: boolean, table?: TableChat): BellProbe;
+/** The chat attached to the table, as its probe says it: its session, null for none or for Codex, and its folder; neither while no chat is attached. */
+export interface TableChat {
+    session: string | null;
+    chat?: string;
+}
+/** What a page says of itself at `/api/bell?probe`. */
+export interface BellProbe {
+    session: string | null;
+    folder: string;
+    open: boolean;
+    version?: string;
+    table?: true;
+    /** The folder of the chat attached to the table. */
+    chat?: string;
+}
+/** What the page at a port of this computer says of itself; undefined when none answers there in `wait`. */
+export declare function pageAt(port: number, wait?: number): Promise<BellProbe | undefined>;
+/**
+ * The ports a folder's page tries first: one in each of a few ranges, by its real path, since Windows may reserve a range and the hook may name the folder
+ * through a link. The hook looks for it there.
+ */
+export declare function pagePorts(folder: string): number[];
+/** The ports noted for a folder's page in the data folder: none when it has no notes or cannot be read. A note may be stale: the probe tells. */
+export declare function notedPagePorts(home: string, folder: string): number[];
+/** The file where a page off its folder's usual ports notes its port in the data folder: `pages/<port>.json`, with the page's folder. */
+export declare function pageNote(home: string, port: number): string;
+/** The folder whose page noted a port; none when no note reads well. */
+export declare function notedFolder(home: string, port: number): string | undefined;
+/** What a hook reads of its host's input to find its chat's page: the chat's session and the folder it runs in. */
+export interface ChatHook {
+    session?: string;
+    cwd?: string;
+}
+/** The page of a hook's chat, in the chat's folder: its port, or why none was found. */
+export type ChatPage = {
+    folder: string;
+    port: number;
+} | {
+    folder: string;
+    port?: undefined;
+    why: string;
+};
+/**
+ * Finds the page of the hook's chat: the one of its session among those of its folder, or the table the chat is attached to (D-104); else the only one,
+ * or the only one a browser has open. Its folder's usual ports first: a page of the chat's session there spares reading the data folder, some 40 ms on
+ * Windows. With `ports` given, only those are tried. Each page has `wait` to say whose it is.
+ */
+export declare function findChatPage(hook: ChatHook, ports?: number[], wait?: number): Promise<ChatPage>;
+/**
+ * Tells the page of the hook's chat that the player's message started its turn (the prompt hook): whether the page heard it. Quick or not at all: each
+ * page has a quarter of a second to answer, and none is asked twice, so that the prompt never waits on a page that is busy or gone.
+ */
+export declare function tellChatAtWork(hook: ChatHook, ports?: number[]): Promise<boolean>;
+/** What the page at a port of this computer answers, once it ends: the body of a 200, none for any other answer or none in `wait`; `refused` when nobody listens there at all. */
+export interface PageAnswer {
+    refused: boolean;
+    text?: string;
+}
+/** Asks the page at a port of this computer, on a connection of its own: one that waits for the bell waits for hours, with no `wait`. */
+export declare function askPage(port: number, path: string, wait?: number): Promise<PageAnswer>;
+/** The page's words for what it says of itself; undefined for anything else. */
+export declare function probeOf(said: string | undefined): BellProbe | undefined;
+/**
+ * The data folder the chat's server is given in its folder's settings, as CHESSPAL_HOME in a playtest: the hook runs in the host's environment, not the
+ * server's (Federico). Claude Code's .mcp.json first, then Codex's config.
+ */
+export declare function serverHome(folder: string): string | undefined;
+/** The chat's folder, where its server started, as a hook finds it: Claude Code names it, and the hook's cwd follows the cd's of the chat. */
+export declare function chatFolder(hook: {
+    cwd?: string;
+}): string;
+/** How long a port may take to say whose page it is: one of this computer answers at once. */
+export declare const probeWait = 1000;

package/dist/server/ports/ports.js

@@ -0,0 +1,222 @@
+// Where a folder's page answers, and how a hook finds its chat's page: on its folder's usual ports, at a port it noted in the data folder, or at the table
+// (D-104). Light on purpose: the prompt hook loads it on every message of the chat.
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { get } from "node:http";
+import { join, resolve } from "node:path";
+import { dataFolder, realPath, samePath, tableFolder } from "../../home/index.js";
+import { version } from "../../version.js";
+/**
+ * Whose page answers at a port, for the hook to find its own: the chat's session, the player's folder, whether a browser has the page open, Chesspal's
+ * version, and whether the table serves it (D-104), with the session and the folder of the chat attached to it, never its own process's.
+ */
+export function bellProbe(folder, open = false, table) {
+    const session = table === undefined ? process.env.CLAUDE_CODE_SESSION_ID ?? null : table.session;
+    return { session, folder: resolve(folder), open, version, ...(table === undefined ? {} : { table: true, ...(table.chat === undefined ? {} : { chat: table.chat }) }) };
+}
+/** What the page at a port of this computer says of itself; undefined when none answers there in `wait`. */
+export async function pageAt(port, wait = probeWait) {
+    return probeOf((await askPage(port, "/api/bell?probe", wait)).text);
+}
+/**
+ * The ports a folder's page tries first: one in each of a few ranges, by its real path, since Windows may reserve a range and the hook may name the folder
+ * through a link. The hook looks for it there.
+ */
+export function pagePorts(folder) {
+    const offset = createHash("sha256").update(realPath(folder).toLowerCase()).digest()[0] % 10;
+    return [5870, 6870, 7870].map((base) => base + portShift() + offset);
+}
+/** The ports noted for a folder's page in the data folder: none when it has no notes or cannot be read. A note may be stale: the probe tells. */
+export function notedPagePorts(home, folder) {
+    let names;
+    try {
+        names = readdirSync(join(home, notesFolder));
+    }
+    catch {
+        return [];
+    }
+    return names.flatMap((name) => {
+        const port = Number(/^(\d+)\.json$/.exec(name)?.[1]);
+        const noted = Number.isInteger(port) ? notedFolder(home, port) : undefined;
+        return noted !== undefined && samePath(noted, folder) ? [port] : [];
+    });
+}
+/** The file where a page off its folder's usual ports notes its port in the data folder: `pages/<port>.json`, with the page's folder. */
+export function pageNote(home, port) {
+    return join(home, notesFolder, `${port}.json`);
+}
+/** The folder whose page noted a port; none when no note reads well. */
+export function notedFolder(home, port) {
+    try {
+        const { folder } = JSON.parse(readFileSync(pageNote(home, port), "utf8"));
+        return typeof folder === "string" ? folder : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Finds the page of the hook's chat: the one of its session among those of its folder, or the table the chat is attached to (D-104); else the only one,
+ * or the only one a browser has open. Its folder's usual ports first: a page of the chat's session there spares reading the data folder, some 40 ms on
+ * Windows. With `ports` given, only those are tried. Each page has `wait` to say whose it is.
+ */
+export async function findChatPage(hook, ports, wait = probeWait) {
+    const folder = chatFolder(hook);
+    const probed = (tried) => Promise.all(tried.map(async (port) => ({ port, said: await pageAt(port, wait) })));
+    const usual = await probed(ports ?? pagePorts(folder));
+    const own = usual.find(({ said }) => hook.session !== undefined && said?.session === hook.session && samePath(said.folder, folder));
+    if (own !== undefined) {
+        return { folder, port: own.port };
+    }
+    // The data folder holds the table's ports and those a page of the folder noted, off its usual ones.
+    const home = ports === undefined ? homeOf(folder) : undefined;
+    const noted = home === undefined ? [] : notedPagePorts(home, folder).filter((port) => !usual.some((one) => one.port === port));
+    const [more, table] = await Promise.all([probed(noted), home === undefined ? undefined : tableOf(home, folder, hook.session, wait)]);
+    const probes = [...usual, ...more];
+    const pages = probes.flatMap(({ port, said }) => (said !== undefined && samePath(said.folder, folder) ? [{ port, said }] : []));
+    // A chat opened in the table's own folder finds the table among the pages of its folder already.
+    const ours = table === undefined || pages.some(({ port }) => port === table.port) ? pages : [...pages, table];
+    const port = chosenPage(ours, hook.session)?.port;
+    if (port !== undefined) {
+        return { folder, port };
+    }
+    const others = probes.flatMap((one) => (one.said === undefined ? [] : [`${one.port} is ${one.said.folder}'s`]));
+    const open = ours.filter(({ said }) => said.open).length;
+    const found = ours.length > 1 ? `${ours.length} pages of it, none of this chat's session, ${open} open in a browser` : "no page of it";
+    return { folder, why: `${found} at ports ${probes.map((one) => one.port).join(", ")}${others.length > 0 ? `; ${others.join(", ")}` : ""}` };
+}
+/**
+ * Tells the page of the hook's chat that the player's message started its turn (the prompt hook): whether the page heard it. Quick or not at all: each
+ * page has a quarter of a second to answer, and none is asked twice, so that the prompt never waits on a page that is busy or gone.
+ */
+export async function tellChatAtWork(hook, ports) {
+    try {
+        const found = await findChatPage(hook, ports, promptWait);
+        return found.port !== undefined && (await askPage(found.port, "/api/bell/prompt", promptWait)).text === "at work";
+    }
+    catch {
+        return false;
+    }
+}
+/** Asks the page at a port of this computer, on a connection of its own: one that waits for the bell waits for hours, with no `wait`. */
+export function askPage(port, path, wait) {
+    return new Promise((done) => {
+        // Node's shared connection ends a request idle for five seconds.
+        const request = get({ host: "127.0.0.1", port, path, agent: false }, (response) => {
+            let text = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => {
+                text += chunk;
+            });
+            response.on("end", () => done(response.statusCode === 200 ? { refused: false, text } : { refused: false }));
+            response.on("error", () => done({ refused: false }));
+        });
+        if (wait !== undefined) {
+            giveUpAfterTurns(request, wait);
+        }
+        request.on("error", (error) => done({ refused: error.code === "ECONNREFUSED" }));
+    });
+}
+/** The page's words for what it says of itself; undefined for anything else. */
+export function probeOf(said) {
+    try {
+        const parsed = said === undefined ? undefined : JSON.parse(said);
+        return parsed === undefined || typeof parsed.folder !== "string" ? undefined : {
+            session: typeof parsed.session === "string" ? parsed.session : null,
+            folder: parsed.folder,
+            open: parsed.open === true,
+            ...(typeof parsed.version === "string" ? { version: parsed.version } : {}),
+            ...(parsed.table === true ? { table: true } : {}),
+            ...(typeof parsed.chat === "string" ? { chat: parsed.chat } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The data folder the chat's server is given in its folder's settings, as CHESSPAL_HOME in a playtest: the hook runs in the host's environment, not the
+ * server's (Federico). Claude Code's .mcp.json first, then Codex's config.
+ */
+export function serverHome(folder) {
+    const chosen = [claudeHome(folder), codexHome(folder)].find((one) => one !== undefined && one.trim() !== "");
+    return chosen === undefined ? undefined : resolve(chosen.trim());
+}
+/** The chat's folder, where its server started, as a hook finds it: Claude Code names it, and the hook's cwd follows the cd's of the chat. */
+export function chatFolder(hook) {
+    return resolve(process.env.CLAUDE_PROJECT_DIR ?? hook.cwd ?? process.cwd());
+}
+/** How long a port may take to say whose page it is: one of this computer answers at once. */
+export const probeWait = 1000;
+// How long a page has to answer the prompt hook, which holds the player's message meanwhile.
+const promptWait = 250;
+// Where the pages off their folder's usual ports note them, in the data folder: `<port>.json`, with the page's folder.
+const notesFolder = "pages";
+/**
+ * CHESSPAL_PORT_SHIFT, for the tests: a multiple of ten under a thousand moves every range of ports by it, so that runs side by side never share one.
+ * Any other value moves nothing.
+ */
+function portShift() {
+    const shift = Number(process.env.CHESSPAL_PORT_SHIFT ?? 0);
+    return Number.isInteger(shift) && shift >= 0 && shift < 1000 && shift % 10 === 0 ? shift : 0;
+}
+/**
+ * The data folder of the chat's server, as the hook finds it; none when it cannot be found. Finding it costs some tens of milliseconds on Windows, the
+ * registry read.
+ */
+function homeOf(folder) {
+    try {
+        return serverHome(folder) ?? dataFolder();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The table of the data folder, when the chat attached to it is the hook's: of its folder, or of its session; none when no table has this chat. */
+async function tableOf(home, folder, session, wait) {
+    const probes = await Promise.all(pagePorts(tableFolder(home)).map(async (port) => ({ port, said: await pageAt(port, wait) })));
+    return probes.find((one) => one.said?.table === true && ((one.said.chat !== undefined && samePath(one.said.chat, folder)) || (session !== undefined && one.said.session === session)));
+}
+/**
+ * The chat's page among those of its folder: the one of its session; else the only one, or the only one a browser has open, where the player plays. Codex
+ * gives the page no session, and a chat closed may leave its page behind for a while.
+ */
+function chosenPage(pages, session) {
+    const open = pages.filter(({ said }) => said.open);
+    return pages.find(({ said }) => session !== undefined && said.session === session) ?? (pages.length === 1 ? pages[0] : open.length === 1 ? open[0] : undefined);
+}
+function claudeHome(folder) {
+    try {
+        const config = JSON.parse(readFileSync(join(folder, ".mcp.json"), "utf8"));
+        const home = config.mcpServers?.chesspal?.env?.CHESSPAL_HOME;
+        return typeof home === "string" ? home : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// The setting as init keeps it in Codex's table: a basic string, whose escapes are JSON's for a path, or a literal one.
+function codexHome(folder) {
+    try {
+        const config = readFileSync(join(folder, ".codex", "config.toml"), "utf8");
+        const [, basic, literal] = /\bCHESSPAL_HOME\s*=\s*(?:("(?:[^"\\]|\\.)*")|'([^']*)')/.exec(config) ?? [];
+        return basic === undefined ? literal : JSON.parse(basic);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Ends a request still unanswered after `wait`, counted in ten turns of this process's clock: after a stall (a busy computer, one waking up), a timer
+ * fires before the answer waiting is read, and a page of this process, or one that answered meanwhile, would be taken for one that does not answer.
+ */
+function giveUpAfterTurns(request, wait) {
+    let turns = 0;
+    const timer = setInterval(() => {
+        turns++;
+        if (turns === 10) {
+            request.destroy();
+        }
+    }, wait / 10);
+    request.on("close", () => clearInterval(timer));
+}

package/dist/server/table/browser.d.ts

@@ -1,6 +1,22 @@
-/** Opens an address in a window of its own, else in a tab of the default browser, without waiting for it: whether a browser started. */
-export declare function openInBrowser(url: string, platform: string): Promise<boolean>;
-/** The address of the window the table opens, marked so that the page sizes it as it opens (page/layout/window.ts). */
-export declare function openedAddress(url: string): string;
-/** Chrome or Edge, where each system installs them: the first there is; none when neither is. */
-export declare function appBrowser(platform: string, env: NodeJS.ProcessEnv, exists?: (path: string) => boolean): string | undefined;
+/** What the search for a browser asks the system: whether a file is there, and what a command prints, nothing when it fails. */
+export interface BrowserSystem {
+    exists: (path: string) => boolean;
+    output: (command: string, args: string[]) => Promise<string>;
+}
+/** How the table's page opened: in a window of its own, marked with its opening; in a tab of the default browser, which is not; or not at all. */
+export type Opened = "window" | "tab" | "none";
+/**
+ * Opens an address in a window of its own, marked with the table's opening, else in a tab of the default browser, without waiting for it: how it opened.
+ * A tab is not marked: a page cannot close a tab it did not open.
+ */
+export declare function openInBrowser(url: string, platform: string, opening?: number): Promise<Opened>;
+/**
+ * The address of the window the table opens, marked so that the page sizes it as it opens, with its opening, so that it closes once a newer window has
+ * opened (page/layout/window.ts).
+ */
+export declare function openedAddress(url: string, opening?: number): string;
+/**
+ * The browser that opens the table's window: the default one when it is a Chromium that takes --app and is where it installs itself, so that the window
+ * opens in the browser the player uses; else Chrome or Edge, the first there is; none when neither is.
+ */
+export declare function appBrowser(platform: string, env: NodeJS.ProcessEnv, system?: BrowserSystem): Promise<string | undefined>;