@joystyk/session 0.0.0-stage → 0.2.0

package/dist/local.js

@@ -0,0 +1,723 @@
+import { compact, decode, isRecord, jsonClone, jsonEqual } from "./values.js";
+import { alwaysVisible } from "./ports.js";
+import { createPublisher } from "./publisher.js";
+import { advanceAi, aiDecisionSeed, aiRestore, defaultRestoreRng, deriveAiSeed } from "./rngs.js";
+import { applySeatChange, parseEngineInput, rebuild, recordOf, safeApply } from "./replay.js";
+import { isSeatInfo, loadSave } from "./saves.js";
+import { createStopwatch } from "./stopwatch.js";
+import { ASSIST_KINDS, err, gameError, isJson, ok, undoPolicyFor } from "@joystyk/contracts";
+//#region src/local.ts
+var notice = (code, message) => ({
+	code,
+	message
+});
+var UNDO_MESSAGES = {
+	UndoNotAllowed: "This game doesn't allow undo here.",
+	HistoryUnavailable: "Undo is unavailable for this saved game.",
+	GameOver: "The game is over.",
+	UndoLimit: "No undos left.",
+	NothingToUndo: "There is nothing to undo.",
+	UndoBarrier: "That move can't be undone.",
+	Paused: "The game is paused."
+};
+/**
+* The default AI runner: the engine's own `ai.choose`, after a delay on the clock, drawing
+* from the task's stream. `restore` rebuilds it; default: the kit's `restoreRng`.
+*/
+var inlineAi = (ai, clock, delayMs, restore = defaultRestoreRng) => ({ choose: (task) => {
+	let cancel = () => {};
+	return {
+		result: new Promise((resolve, reject) => {
+			cancel = clock.after(delayMs, () => {
+				try {
+					resolve(ai.choose(task.view, task.seat, task.level, restore(task.rng)));
+				} catch (error) {
+					reject(error instanceof Error ? error : new Error(String(error)));
+				}
+			});
+		}),
+		cancel: () => cancel()
+	};
+} });
+/** The kinds in `ASSIST_KINDS` order, each once. */
+var assistList = (used) => ASSIST_KINDS.filter((kind) => used.has(kind));
+var checkSeats = (seats, levels) => {
+	if (seats.length === 0 || !seats.every((seat, i) => isSeatInfo(seat) && seat.id === i)) return gameError("InvalidSeats", "The seats must be numbered 0, 1, 2 and so on.");
+	const unknown = seats.find((seat) => seat.aiLevel !== void 0 && levels !== null && !levels.includes(seat.aiLevel));
+	return unknown === void 0 ? null : gameError("InvalidSeats", "An AI seat names a level the game lacks.", { seat: unknown.id });
+};
+/** Starts a new local game. Fails when the seats or config are invalid or `init` refuses them. */
+var createLocalSession = (engine, options) => {
+	const seatProblem = checkSeats(options.seats, engine.ai?.levels ?? null);
+	if (seatProblem !== null) return err(seatProblem);
+	const config = decode(engine.schemas.config, options.config, "game setup");
+	if (!config.ok) return config;
+	const start = {
+		config: config.value,
+		seats: options.seats,
+		seed: options.seed
+	};
+	const built = rebuild(engine, start, [], options.restoreRng ?? defaultRestoreRng);
+	if (!built.ok) return built;
+	return ok(run(engine, options, {
+		state: built.value.state,
+		rng: built.value.rng,
+		seats: options.seats,
+		history: {
+			...start,
+			records: []
+		},
+		elapsedMs: 0,
+		started: false,
+		undosUsed: 0,
+		assists: [],
+		assistCounts: {},
+		aiRng: null
+	}));
+};
+var restoreHistory = (engine, envelope, state, restoreRng) => {
+	const lost = (why) => err(gameError("HistoryUnavailable", "The saved moves could not be replayed.", { why }));
+	const replay = envelope.replay;
+	if (!isRecord(replay)) return lost("no replay");
+	if (replay["layer"] !== 2 || replay["gameId"] !== envelope.gameId || replay["rulesVersion"] !== engine.rulesVersion) return lost("replay header");
+	const config = decode(engine.schemas.config, replay["config"], "saved setup");
+	if (!config.ok) return config;
+	const seats = replay["seats"];
+	if (!Array.isArray(seats) || checkSeats(seats, null) !== null) return lost("replay seats");
+	const seed = replay["seed"];
+	if (!isRecord(seed) || typeof seed["algorithm"] !== "string" || !Array.isArray(seed["words"])) return lost("replay seed");
+	const rawInputs = replay["inputs"];
+	if (!Array.isArray(rawInputs)) return lost("replay inputs");
+	const inputs = [];
+	for (const raw of rawInputs) {
+		const input = parseEngineInput(raw, engine.schemas.command);
+		if (!input.ok) return input;
+		inputs.push(input.value);
+	}
+	const start = {
+		config: config.value,
+		seats,
+		seed
+	};
+	const rebuilt = rebuild(engine, start, inputs, restoreRng);
+	if (!rebuilt.ok) return rebuilt;
+	if (!jsonEqual(rebuilt.value.state, state) || !jsonEqual(rebuilt.value.rng.save(), envelope.rng)) return lost("replay diverged");
+	return ok({
+		...start,
+		records: [...rebuilt.value.records]
+	});
+};
+/**
+* Resumes a saved game. `save` is whatever storage returned; it is parsed, migrated and
+* validated here. When the save's replay is missing or no longer matches, the game still
+* resumes, without undo or outstanding jobs, and the reason goes to `report`.
+*/
+var restoreLocalSession = (engine, save, options) => {
+	const loaded = loadSave(save, options.manifest, engine.rulesVersion, options.migrations, engine.schemas.state);
+	if (!loaded.ok) return loaded;
+	const { envelope, state } = loaded.value;
+	const seatProblem = checkSeats(envelope.seats, engine.ai?.levels ?? null);
+	if (seatProblem !== null) return err(seatProblem);
+	const restoreRng = options.restoreRng ?? defaultRestoreRng;
+	const history = restoreHistory(engine, envelope, state, restoreRng);
+	if (!history.ok) options.report?.(history.error, "Restored a save without its history.");
+	const assists = new Set(envelope.assists ?? []);
+	const fullRecords = history.ok ? history.value.records : [];
+	const records = fullRecords.slice(Math.max(0, fullRecords.findLastIndex((record) => record.restartsGame)));
+	for (const record of records) if (record.assist !== null) assists.add(record.assist);
+	const replayCounts = {};
+	for (const record of records) if (record.assist !== null) replayCounts[record.assist] = (replayCounts[record.assist] ?? 0) + 1;
+	const assistCounts = {};
+	for (const kind of ASSIST_KINDS) {
+		const count = Math.max(envelope.assistCounts?.[kind] ?? 0, replayCounts[kind] ?? 0, kind === "undo" ? envelope.undosUsed ?? 0 : 0, assists.has(kind) ? 1 : 0);
+		if (count > 0) {
+			assistCounts[kind] = count;
+			assists.add(kind);
+		}
+	}
+	const clockInput = engine.clockStart === "transition" ? records.some((record) => record.startsClock) : records.length > 0;
+	const started = envelope.clockStarted ?? ((envelope.elapsedMs ?? 0) > 0 || clockInput);
+	return ok(run(engine, options, {
+		state,
+		rng: restoreRng(envelope.rng),
+		seats: envelope.seats,
+		history: history.ok ? history.value : null,
+		elapsedMs: envelope.elapsedMs ?? 0,
+		started,
+		undosUsed: envelope.undosUsed ?? 0,
+		assists: assistList(assists),
+		assistCounts,
+		aiRng: envelope.aiRng ?? null
+	}));
+};
+var outstandingJobs = (records) => {
+	const jobs = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		if (record.restartsGame) jobs.clear();
+		if (record.input.kind === "job") jobs.delete(record.input.jobId);
+		for (const job of record.jobs) jobs.set(job.id, job);
+	}
+	return jobs;
+};
+var FAILED = {
+	outcome: {
+		ok: false,
+		reason: "failed"
+	},
+	presentation: null
+};
+var parseJobResult = (raw, spec) => {
+	if (!isRecord(raw)) return FAILED;
+	if (raw["ok"] === false && (raw["reason"] === "timeout" || raw["reason"] === "failed")) return {
+		outcome: {
+			ok: false,
+			reason: raw["reason"]
+		},
+		presentation: null
+	};
+	if (raw["ok"] !== true) return FAILED;
+	const value = decode(spec.result, raw["value"], "job result");
+	if (!value.ok || !isJson(value.value)) return FAILED;
+	const presentation = raw["presentation"];
+	return {
+		outcome: {
+			ok: true,
+			value: value.value
+		},
+		presentation: presentation !== void 0 && isJson(presentation) ? presentation : null
+	};
+};
+var run = (engine, options, start) => {
+	const { manifest, mode, clock } = options;
+	const restoreRng = options.restoreRng ?? defaultRestoreRng;
+	const report = options.report ?? (() => {});
+	const visibility = options.visibility ?? alwaysVisible;
+	const handoffScreen = mode === "pass-and-play" && manifest.handoff;
+	let state = start.state;
+	let rng = start.rng;
+	let seats = start.seats;
+	let history = start.history;
+	let revision = 0;
+	let undosUsed = start.undosUsed;
+	const assists = new Set(start.assists);
+	const assistCounts = { ...start.assistCounts };
+	const undoPolicy = undoPolicyFor(manifest.undo, mode);
+	let currentNotice = null;
+	let presentation = null;
+	let paused = false;
+	let disposed = false;
+	let outstanding = history === null ? /* @__PURE__ */ new Map() : outstandingJobs(history.records);
+	const jobTasks = /* @__PURE__ */ new Map();
+	const aiTasks = /* @__PURE__ */ new Map();
+	const restoreAi = aiRestore(restoreRng);
+	let aiState = start.aiRng ?? options.aiSeed ?? deriveAiSeed(rng.save(), restoreRng);
+	if (manifest.ai?.heavy === true && options.ai === void 0 && engine.ai !== void 0) report(/* @__PURE__ */ new Error(`${manifest.id} declares heavy AI but no worker AI runner was given.`), "Running heavy AI on the main thread.");
+	const aiRunner = options.ai ?? (engine.ai === void 0 ? null : inlineAi(engine.ai, clock, options.aiDelayMs ?? 500, restoreAi));
+	const stopwatch = createStopwatch(clock, {
+		elapsedMs: start.elapsedMs,
+		started: start.started,
+		finished: engine.outcome(state) !== null,
+		hidden: visibility.hidden()
+	});
+	const isHuman = (seat) => seats[seat]?.controller === "human";
+	const firstHuman = () => seats.find((seat) => seat.controller === "human")?.id ?? null;
+	let viewer = mode === "pass-and-play" ? null : options.seat === void 0 ? firstHuman() : options.seat;
+	let handoff = null;
+	let wasHandoffRequired = handoffScreen;
+	/**
+	* Pass-and-play: the viewer follows the human seat to act, through the hand-off screen. At
+	* the outcome a hand-off game shows the spectator's view, so the final board reveals no
+	* hand to whoever holds the device next; an engine whose rules reveal hands at the end
+	* shows them in `viewFor(state, null)`.
+	*/
+	const updateViewer = () => {
+		if (mode !== "pass-and-play") return;
+		if (engine.outcome(state) !== null) {
+			handoff = null;
+			if (handoffScreen) viewer = null;
+			return;
+		}
+		const humans = engine.pending(state).filter(isHuman);
+		const current = handoff ?? viewer;
+		const required = handoffScreen && engine.handoffRequired?.(state) !== false;
+		const enteringPrivate = required && !wasHandoffRequired;
+		wasHandoffRequired = required;
+		if (humans.length === 0) {
+			if (!required && handoff !== null) {
+				handoff = null;
+				viewer = firstHuman();
+			}
+			if (viewer === null && handoff === null && !handoffScreen) viewer = firstHuman();
+			return;
+		}
+		if (current !== null && humans.includes(current) && !enteringPrivate) {
+			if (!required && handoff !== null) {
+				viewer = current;
+				handoff = null;
+			}
+			return;
+		}
+		const after = current ?? -1;
+		const target = enteringPrivate ? Math.min(...humans) : [...humans].sort((a, b) => a - b).find((seat) => seat > after) ?? Math.min(...humans);
+		if (required) {
+			viewer = null;
+			handoff = target;
+		} else {
+			viewer = target;
+			handoff = null;
+		}
+	};
+	const undoPlan = () => {
+		const policy = undoPolicy;
+		if (policy === "none" || mode !== "pass-and-play" && seats.filter((seat) => seat.controller === "human").length > 1) return { block: "UndoNotAllowed" };
+		if (history === null) return { block: "HistoryUnavailable" };
+		if (engine.outcome(state) !== null) return { block: "GameOver" };
+		if (paused) return { block: "Paused" };
+		if (typeof policy === "object" && undosUsed >= policy.limited) return { block: "UndoLimit" };
+		const cut = history.records.findLastIndex((record) => record.input.kind === "command" && record.seatsBefore[record.input.seat]?.controller === "human");
+		if (cut < 0) return { block: "NothingToUndo" };
+		if (history.records.slice(cut).some((record) => record.barrier)) return { block: "UndoBarrier" };
+		return { cut };
+	};
+	const undoState = () => {
+		const plan = undoPlan();
+		const policy = undoPolicy;
+		const remaining = policy === "none" ? 0 : policy === "unlimited" ? null : Math.max(0, policy.limited - undosUsed);
+		return "cut" in plan ? {
+			available: true,
+			remaining,
+			blockedBy: null
+		} : {
+			available: false,
+			remaining,
+			blockedBy: plan.block
+		};
+	};
+	const redact = (beats) => beats.flatMap((beat) => {
+		const event = engine.eventFor(beat.event, viewer);
+		if (event === null) return [];
+		return [beat.state === void 0 ? { event } : {
+			event,
+			view: engine.viewFor(beat.state, viewer)
+		}];
+	});
+	const snapshot = (beats) => {
+		const outcome = engine.outcome(state);
+		const elapsedMs = stopwatch.elapsed();
+		return {
+			meta: {
+				connection: "local",
+				seat: viewer,
+				revision,
+				seats,
+				outcome: outcome === null ? null : {
+					...outcome,
+					elapsedMs,
+					undosUsed,
+					assists: assistList(assists),
+					assistCounts: { ...assistCounts }
+				},
+				safePoint: engine.safePoint?.(state) ?? outcome !== null,
+				notice: currentNotice,
+				undosUsed,
+				assists: assistList(assists),
+				assistCounts: { ...assistCounts }
+			},
+			view: engine.viewFor(state, viewer),
+			beats: redact(beats),
+			pending: engine.pending(state),
+			presentation,
+			mode,
+			handoff: handoff === null ? null : {
+				seat: handoff,
+				name: seats[handoff]?.name ?? ""
+			},
+			undo: undoState(),
+			thinking: [...aiTasks.keys()].sort((a, b) => a - b),
+			paused,
+			elapsedMs
+		};
+	};
+	const replay = () => history === null ? null : {
+		layer: 2,
+		gameId: manifest.id,
+		rulesVersion: engine.rulesVersion,
+		config: history.config,
+		seats: history.seats,
+		seed: history.seed,
+		inputs: history.records.map((record) => record.input)
+	};
+	const envelope = () => compact({
+		gameId: manifest.id,
+		build: manifest.versions.build,
+		rulesVersion: engine.rulesVersion,
+		saveVersion: manifest.versions.save,
+		rng: rng.save(),
+		seats,
+		state,
+		elapsedMs: stopwatch.elapsed(),
+		clockStarted: stopwatch.started(),
+		replay: replay() ?? void 0,
+		aiRng: aiState,
+		undosUsed,
+		assists: assistList(assists),
+		assistCounts: { ...assistCounts }
+	});
+	/** The engine's `worthSaving`; an engine that throws is reported, and the game is saved. */
+	const worthSaving = () => {
+		try {
+			return engine.worthSaving?.(state) ?? true;
+		} catch (error) {
+			report(error, "The engine threw in worthSaving.");
+			return true;
+		}
+	};
+	let saving = Promise.resolve();
+	let slotMayHoldSave = true;
+	/**
+	* Queues a write of the current position; resolves once it has landed (or failed). A
+	* position the engine says isn't worth saving is never written, and a save it replaces
+	* (after an undo back to the start) is cleared, so the launcher offers no "Continue".
+	*/
+	const persist = () => {
+		const store = options.storage;
+		if (store === void 0) return Promise.resolve();
+		if (!worthSaving()) {
+			if (!slotMayHoldSave || store.clear === void 0) return saving;
+			slotMayHoldSave = false;
+			const clear = store.clear.bind(store);
+			saving = saving.then(clear).catch((error) => report(error, "Clearing an untouched save failed."));
+			return saving;
+		}
+		slotMayHoldSave = true;
+		const save = envelope();
+		saving = saving.then(() => store.write(save)).catch((error) => {
+			report(error, "Saving the game failed.");
+			enqueue(() => {
+				currentNotice = notice("SaveFailed", "The game couldn't be saved on this device.");
+				publisher.publish(snapshot([]));
+			});
+		});
+		return saving;
+	};
+	const queue = [];
+	let draining = false;
+	/** Every change runs here, one at a time, so a listener that dispatches never sees a torn state. */
+	const enqueue = (work) => {
+		if (disposed) return;
+		queue.push(work);
+		if (draining) return;
+		draining = true;
+		try {
+			while (queue.length > 0 && !disposed) {
+				const next = queue.shift();
+				try {
+					next();
+				} catch (error) {
+					report(error, "The local session failed to process an input.");
+				}
+			}
+		} finally {
+			draining = false;
+			queue.length = 0;
+		}
+	};
+	const reject = (problem) => {
+		currentNotice = {
+			code: problem.code,
+			message: problem.message
+		};
+		publisher.publish(snapshot([]));
+	};
+	/** Publishes the new position, then saves it, then starts the jobs it requested (rule 1). */
+	const settle = (beats) => {
+		updateViewer();
+		scheduleAi();
+		publisher.publish(snapshot(beats));
+		persist().then(() => enqueue(startJobs));
+	};
+	/** Applies one input. On success it publishes; on failure it returns the engine's error. */
+	const accept = (input, jobPresentation = null) => {
+		const applied = safeApply(engine, state, input, rng, restoreRng);
+		rng = applied.rng;
+		if ("thrown" in applied) report(applied.thrown, "The engine threw in apply.");
+		if (!applied.result.ok) return applied.result.error;
+		const transition = applied.result.value;
+		const record = recordOf(input, transition, seats);
+		if (record.restartsGame) {
+			cancelAi();
+			cancelJobs();
+			outstanding.clear();
+			stopwatch.restart();
+			undosUsed = 0;
+			assists.clear();
+			for (const key of ASSIST_KINDS) delete assistCounts[key];
+		}
+		history?.records.push(record);
+		if (record.assist !== null) {
+			assists.add(record.assist);
+			assistCounts[record.assist] = (assistCounts[record.assist] ?? 0) + 1;
+		}
+		seats = applySeatChange(seats, input);
+		state = transition.state;
+		if (input.kind === "job") outstanding.delete(input.jobId);
+		for (const job of transition.jobs ?? []) outstanding.set(job.id, job);
+		revision += 1;
+		currentNotice = null;
+		presentation = jobPresentation;
+		if (engine.clockStart !== "transition" || record.startsClock) stopwatch.start();
+		if (engine.outcome(state) !== null) stopwatch.finish();
+		settle(transition.beats);
+		return null;
+	};
+	const cancelAi = () => {
+		for (const task of aiTasks.values()) task.cancel();
+		aiTasks.clear();
+	};
+	/** Starts a choice for every pending AI seat whose decision changed; cancels the rest. */
+	const scheduleAi = () => {
+		const wanted = /* @__PURE__ */ new Map();
+		if (!paused && !disposed && aiRunner !== null && engine.outcome(state) === null) for (const seat of engine.pending(state)) {
+			if (seats[seat]?.controller !== "ai") continue;
+			wanted.set(seat, JSON.stringify(engine.decisionKey?.(state, seat) ?? engine.viewFor(state, seat)));
+		}
+		for (const [seat, task] of aiTasks) {
+			if (wanted.get(seat) === task.key) continue;
+			task.cancel();
+			aiTasks.delete(seat);
+		}
+		for (const [seat, key] of wanted) if (!aiTasks.has(seat)) startAi(seat, key);
+	};
+	const aiFailed = (seat, error) => {
+		report(error, `The AI for seat ${seat} failed.`);
+		reject(notice("AiFailed", `${seats[seat]?.name ?? "The computer"} couldn't move.`));
+	};
+	const startAi = (seat, key) => {
+		if (aiRunner === null) return;
+		const view = jsonClone(engine.viewFor(state, seat));
+		const level = seats[seat]?.aiLevel ?? engine.ai?.levels[0] ?? "default";
+		const task = aiRunner.choose({
+			view,
+			seat,
+			level,
+			rng: aiDecisionSeed(aiState, seat, restoreAi)
+		});
+		const entry = {
+			key,
+			cancel: () => task.cancel()
+		};
+		aiTasks.set(seat, entry);
+		task.result.then((raw) => enqueue(() => {
+			if (aiTasks.get(seat) !== entry) return;
+			aiTasks.delete(seat);
+			const command = decode(engine.schemas.command, raw, "AI move");
+			if (!command.ok) return aiFailed(seat, command.error);
+			const before = aiState;
+			aiState = advanceAi(aiState, seats.length, restoreAi);
+			const problem = accept({
+				kind: "command",
+				seat,
+				command: command.value
+			});
+			if (problem !== null) {
+				aiState = before;
+				aiFailed(seat, problem);
+			}
+		}), (error) => enqueue(() => {
+			if (aiTasks.get(seat) !== entry) return;
+			aiTasks.delete(seat);
+			aiFailed(seat, error);
+		}));
+	};
+	const cancelJobs = () => {
+		for (const task of jobTasks.values()) task.cancel();
+		jobTasks.clear();
+	};
+	const startJobs = () => {
+		for (const job of outstanding.values()) if (!jobTasks.has(job.id)) launch(job);
+	};
+	const launch = (job) => {
+		let stopTimer = () => {};
+		let task = null;
+		const entry = { cancel: () => (stopTimer(), task?.cancel()) };
+		jobTasks.set(job.id, entry);
+		const finish = (result) => enqueue(() => {
+			if (jobTasks.get(job.id) !== entry) return;
+			jobTasks.delete(job.id);
+			stopTimer();
+			if (!outstanding.has(job.id)) return;
+			const problem = accept({
+				kind: "job",
+				jobId: job.id,
+				outcome: result.outcome
+			}, result.presentation);
+			if (problem !== null) {
+				outstanding.delete(job.id);
+				report(problem, `The engine rejected the result of job ${job.id}.`);
+			}
+		});
+		const spec = engine.jobs?.[job.kind];
+		const payload = spec === void 0 ? null : decode(spec.payload, job.payload, "job payload");
+		if (spec === void 0 || spec.where === "server" || options.jobs === void 0 || payload === null || !payload.ok) {
+			report(/* @__PURE__ */ new Error(`Job ${job.id} (${job.kind}) can't run locally.`), "Job unavailable.");
+			Promise.resolve().then(() => finish(FAILED));
+			return;
+		}
+		const running = options.jobs.run(job, spec);
+		task = running;
+		stopTimer = clock.after(spec.timeoutMs, () => {
+			running.cancel();
+			finish({
+				outcome: {
+					ok: false,
+					reason: "timeout"
+				},
+				presentation: null
+			});
+		});
+		running.result.then((raw) => finish(parseJobResult(raw, spec)), (error) => {
+			report(error, `Job ${job.id} failed.`);
+			finish(FAILED);
+		});
+	};
+	const gameOver = () => engine.outcome(state) !== null;
+	const undo = () => {
+		const plan = undoPlan();
+		if ("block" in plan) return reject(notice(plan.block, UNDO_MESSAGES[plan.block]));
+		if (history === null) return;
+		const inputs = history.records.slice(0, plan.cut).map((record) => record.input);
+		const rebuilt = rebuild(engine, history, inputs, restoreRng);
+		if (!rebuilt.ok) {
+			report(rebuilt.error, "Undo could not replay the game.");
+			return reject(notice("InternalError", "Undo failed. The game continues from here."));
+		}
+		cancelAi();
+		cancelJobs();
+		state = rebuilt.value.state;
+		rng = rebuilt.value.rng;
+		seats = rebuilt.value.seats;
+		history.records = [...rebuilt.value.records];
+		outstanding = outstandingJobs(history.records);
+		undosUsed += 1;
+		assists.add("undo");
+		assistCounts.undo = undosUsed;
+		revision += 1;
+		currentNotice = null;
+		presentation = null;
+		settle([]);
+	};
+	/**
+	* The seat a command comes from. Without a named seat it is the viewer's. A named seat must
+	* be a person at this device who is pending or has an explicitly authorized untimed side
+	* command: in pass-and-play without a hand-off screen, any such human seat, so simultaneous games such as War take both players' moves in
+	* either order; everywhere else, only the viewer's own seat (gp-o2c).
+	*/
+	const commandSeat = (named, command) => {
+		const watching = () => err(handoff === null ? notice("Spectator", "Watchers cannot move.") : notice("HandoffPending", "Pass the device first."));
+		if (named === void 0) return viewer === null ? watching() : ok(viewer);
+		const notHere = err(notice("InvalidSeat", "That seat isn't played on this device."));
+		if (typeof named !== "number" || seats[named] === void 0 || !isHuman(named)) return notHere;
+		if (mode !== "pass-and-play") return named === viewer ? ok(named) : notHere;
+		if (handoffScreen && named !== viewer) return viewer === null ? watching() : err(notice("HandoffPending", "Pass the device first."));
+		if (gameOver()) return err(notice("GameOver", "The game is over."));
+		if (!engine.pending(state).includes(named) && engine.sideCommand?.(state, named, command) !== true) return err(notice("NotYourTurn", `It isn't ${seats[named]?.name ?? "that seat"}'s turn.`));
+		return ok(named);
+	};
+	const handle = (raw) => {
+		const invalid = notice("InvalidInput", "That action isn't recognized.");
+		if (!isRecord(raw)) return reject(invalid);
+		const kind = raw["kind"];
+		if ((kind === "command" || kind === "resign" || kind === "seat" || kind === "undo") && paused) return reject(notice("Paused", "The game is paused."));
+		switch (kind) {
+			case "command": {
+				const command = decode(engine.schemas.command, raw["command"], "move");
+				if (!command.ok) return reject(command.error);
+				const seat = commandSeat(raw["seat"], command.value);
+				if (!seat.ok) return reject(seat.error);
+				const problem = accept({
+					kind: "command",
+					seat: seat.value,
+					command: command.value
+				});
+				return problem === null ? void 0 : reject(problem);
+			}
+			case "resign":
+			case "seat": {
+				const seat = raw["seat"] === void 0 && kind === "resign" ? viewer : raw["seat"];
+				if (typeof seat !== "number" || seats[seat] === void 0) return reject(notice("InvalidSeat", "Choose a seat first."));
+				if (gameOver()) return reject(notice("GameOver", "The game is over."));
+				let input;
+				if (kind === "resign") {
+					if (!isHuman(seat)) return reject(notice("InvalidSeat", "Only a player can resign."));
+					input = {
+						kind: "resign",
+						seat
+					};
+				} else {
+					const parsed = parseEngineInput({
+						kind: "seat",
+						seat,
+						change: raw["change"]
+					}, engine.schemas.command);
+					if (!parsed.ok) return reject(invalid);
+					input = parsed.value;
+					const change = parsed.value.change;
+					if (change.type === "controller" && change.aiLevel !== void 0 && engine.ai !== void 0 && !engine.ai.levels.includes(change.aiLevel)) return reject(notice("InvalidSeat", "The game doesn't have that AI level."));
+				}
+				const problem = accept(input);
+				return problem === null ? void 0 : reject(problem);
+			}
+			case "undo": return undo();
+			case "reveal":
+				if (handoff === null) return reject(notice("NoHandoff", "There is nothing to reveal."));
+				viewer = handoff;
+				handoff = null;
+				revision += 1;
+				currentNotice = null;
+				return publisher.publish(snapshot([]));
+			case "pause":
+			case "resume":
+				if (paused === (kind === "pause")) return;
+				paused = kind === "pause";
+				stopwatch.setPaused(paused);
+				scheduleAi();
+				publisher.publish(snapshot([]));
+				if (paused) persist();
+				return;
+			default: return reject(invalid);
+		}
+	};
+	updateViewer();
+	scheduleAi();
+	const publisher = createPublisher(snapshot([]), {
+		freeze: options.freeze ?? true,
+		report
+	});
+	const stopVisibility = visibility.subscribe((hidden) => enqueue(() => {
+		stopwatch.setHidden(hidden);
+		if (hidden) persist();
+	}));
+	persist().then(() => enqueue(startJobs));
+	return {
+		get: () => publisher.get(),
+		subscribe: (listener) => publisher.subscribe(listener),
+		dispatch: (input) => enqueue(() => handle(input)),
+		dispose: () => {
+			if (disposed) return;
+			persist();
+			disposed = true;
+			queue.length = 0;
+			cancelAi();
+			cancelJobs();
+			stopVisibility();
+			publisher.close();
+		},
+		elapsedMs: () => stopwatch.elapsed(),
+		save: envelope,
+		replay
+	};
+};
+//#endregion
+export { createLocalSession, inlineAi, restoreLocalSession };
+
+//# sourceMappingURL=local.js.map