@joystyk/session 0.0.0-stage → 0.2.0

package/dist/replay.js

@@ -0,0 +1,199 @@
+import { compact, decode, isRecord } from "./values.js";
+import { defaultRestoreRng } from "./rngs.js";
+import { err, gameError, ok } from "@joystyk/contracts";
+//#region src/replay.ts
+var ENGINE_ASSISTS = [
+	"hint",
+	"check",
+	"reveal",
+	"shuffle"
+];
+/** The assistance a transition flagged. Anything but a kind an engine may report is ignored. */
+var assistOf = (transition) => ENGINE_ASSISTS.includes(transition.assist) ? transition.assist : null;
+/** What the runner keeps of one accepted input and its transition. */
+var recordOf = (input, transition, seatsBefore) => ({
+	input,
+	jobs: transition.jobs ?? [],
+	barrier: transition.undoBarrier === true,
+	assist: assistOf(transition),
+	startsClock: transition.startsClock === true,
+	restartsGame: transition.restartsGame === true,
+	seatsBefore
+});
+/** Applies a seat change to the seat list, as the runner shows it in `meta.seats`. */
+var applySeatChange = (seats, input) => {
+	if (input.kind !== "seat" || input.change.type !== "controller") return seats;
+	const { change } = input;
+	return seats.map((seat) => seat.id === input.seat ? compact({
+		id: seat.id,
+		name: change.name,
+		controller: change.controller,
+		aiLevel: change.aiLevel
+	}) : seat);
+};
+/**
+* Calls `apply` the way a runner must: a throw becomes an `EngineThrew` error, and on any
+* failure the random source is restored, so a rejected input never consumes randomness that
+* a replay (which skips rejected inputs) would not.
+*/
+var safeApply = (engine, state, input, rng, restoreRng) => {
+	const before = rng.save();
+	try {
+		const result = engine.apply(state, input, rng);
+		if (result.ok && result.value.restartsGame === true && (input.kind !== "command" || result.value.undoBarrier !== true || engine.outcome(result.value.state) !== null)) return {
+			result: err(gameError("BadRestart", "A new game needs a setup command, an undo barrier and an unfinished state.")),
+			rng: restoreRng(before)
+		};
+		return result.ok ? {
+			result,
+			rng
+		} : {
+			result,
+			rng: restoreRng(before)
+		};
+	} catch (thrown) {
+		return {
+			result: err(gameError("EngineThrew", "Something went wrong. Your last action was not applied.")),
+			rng: restoreRng(before),
+			thrown
+		};
+	}
+};
+/** Runs `init` with the seed, then every input. Any rejection fails the whole replay. */
+var rebuild = (engine, start, inputs, restoreRng) => {
+	let rng = restoreRng(start.seed);
+	let initialized;
+	try {
+		initialized = engine.init(start.config, start.seats, rng);
+	} catch {
+		return err(gameError("EngineThrew", "The game could not be set up."));
+	}
+	if (!initialized.ok) return initialized;
+	let state = initialized.value;
+	let seats = start.seats;
+	const records = [];
+	for (const [index, input] of inputs.entries()) {
+		const applied = safeApply(engine, state, input, rng, restoreRng);
+		rng = applied.rng;
+		if (!applied.result.ok) return err(gameError("ReplayDiverged", "The saved moves no longer replay.", {
+			index,
+			code: applied.result.error.code
+		}));
+		const transition = applied.result.value;
+		records.push(recordOf(input, transition, seats));
+		seats = applySeatChange(seats, input);
+		state = transition.state;
+	}
+	return ok({
+		state,
+		rng,
+		seats,
+		records
+	});
+};
+/**
+* Replays a recorded Layer 2 game and returns its final state and random state. The
+* conformance tests compare these with the recorded game's.
+*/
+var replayEngine = (engine, replay, restoreRng = defaultRestoreRng) => {
+	if (replay.rulesVersion !== engine.rulesVersion) return err(gameError("RulesChanged", "This replay was recorded under different rules."));
+	const rebuilt = rebuild(engine, replay, replay.inputs, restoreRng);
+	if (!rebuilt.ok) return rebuilt;
+	const barriers = rebuilt.value.records.flatMap((record, i) => record.barrier ? [i] : []);
+	return ok({
+		state: rebuilt.value.state,
+		rng: rebuilt.value.rng.save(),
+		barriers
+	});
+};
+/**
+* Replays a recorded Layer 3 game: `init` with the seed, then `step` up to `endTick`, feeding
+* each tick its inputs in array order.
+*/
+var replaySimulation = (simulation, replay, restoreRng = defaultRestoreRng) => {
+	if (replay.rulesVersion !== simulation.rulesVersion) return err(gameError("RulesChanged", "This replay was recorded under different rules."));
+	const rng = restoreRng(replay.seed);
+	const initialized = simulation.init(replay.config, rng);
+	if (!initialized.ok) return initialized;
+	let state = initialized.value;
+	let next = 0;
+	for (let tick = 0; tick < replay.endTick; tick += 1) {
+		const inputs = [];
+		while (next < replay.inputs.length && replay.inputs[next].tick === tick) {
+			inputs.push(replay.inputs[next].input);
+			next += 1;
+		}
+		state = simulation.step(state, inputs, rng).state;
+	}
+	return ok({
+		state,
+		rng: rng.save()
+	});
+};
+var isSeat = (value) => Number.isInteger(value) && value >= 0;
+var parseJobOutcome = (value) => {
+	if (!isRecord(value)) return null;
+	if (value["ok"] === true && Object.hasOwn(value, "value")) return {
+		ok: true,
+		value: value["value"]
+	};
+	if (value["ok"] === false && (value["reason"] === "timeout" || value["reason"] === "failed")) return {
+		ok: false,
+		reason: value["reason"]
+	};
+	return null;
+};
+/** Parses one input from a stored replay; commands go through the engine's schema. */
+var parseEngineInput = (value, command) => {
+	const bad = err(gameError("SaveUnreadable", "This saved game could not be read.", { why: "replay input" }));
+	if (!isRecord(value)) return bad;
+	switch (value["kind"]) {
+		case "command": {
+			if (!isSeat(value["seat"])) return bad;
+			const decoded = decode(command, value["command"], "saved command");
+			return decoded.ok ? ok({
+				kind: "command",
+				seat: value["seat"],
+				command: decoded.value
+			}) : decoded;
+		}
+		case "seat": {
+			const change = value["change"];
+			if (!isSeat(value["seat"]) || !isRecord(change)) return bad;
+			if (change["type"] === "left") return ok({
+				kind: "seat",
+				seat: value["seat"],
+				change: { type: "left" }
+			});
+			if (change["type"] !== "controller" || change["controller"] !== "human" && change["controller"] !== "ai" || typeof change["name"] !== "string" || change["aiLevel"] !== void 0 && typeof change["aiLevel"] !== "string") return bad;
+			return ok({
+				kind: "seat",
+				seat: value["seat"],
+				change: compact({
+					type: "controller",
+					controller: change["controller"],
+					name: change["name"],
+					aiLevel: change["aiLevel"]
+				})
+			});
+		}
+		case "timeout":
+		case "resign": return isSeat(value["seat"]) ? ok({
+			kind: value["kind"],
+			seat: value["seat"]
+		}) : bad;
+		case "job": {
+			const outcome = parseJobOutcome(value["outcome"]);
+			return typeof value["jobId"] === "string" && outcome !== null ? ok({
+				kind: "job",
+				jobId: value["jobId"],
+				outcome
+			}) : bad;
+		}
+		default: return bad;
+	}
+};
+//#endregion
+export { applySeatChange, assistOf, parseEngineInput, rebuild, recordOf, replayEngine, replaySimulation, safeApply };
+
+//# sourceMappingURL=replay.js.map

package/dist/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","names":[],"sources":["../src/replay.ts"],"sourcesContent":["// Replaying a discrete engine or a simulation from its seed. The local runner rebuilds its\n// state this way for undo and restore, and tests use it to prove replay equality.\nimport {\n  err,\n  gameError,\n  ok,\n  type DiscreteEngine,\n  type EngineAssist,\n  type EngineInput,\n  type EngineReplay,\n  type FixedStepSimulation,\n  type GameError,\n  type JobOutcome,\n  type JobRequest,\n  type Json,\n  type Result,\n  type Rng,\n  type RngState,\n  type SeatInfo,\n  type SimulationReplay,\n  type Transition,\n  type Validator,\n} from '@joystyk/contracts';\nimport type { RngFactory } from './ports.ts';\nimport { defaultRestoreRng } from './rngs.ts';\nimport { compact, decode, isRecord } from './values.ts';\n\n/** One accepted input and what its transition reported. */\nexport type InputRecord<Command> = {\n  readonly input: EngineInput<Command>;\n  /** Jobs the transition requested. */\n  readonly jobs: readonly JobRequest[];\n  readonly barrier: boolean;\n  /** The assistance the transition flagged, if any. */\n  readonly assist: EngineAssist | null;\n  /** The transition set `startsClock`. */\n  readonly startsClock: boolean;\n  readonly restartsGame: boolean;\n  /** The seats as they were when the input arrived, to tell human commands from AI ones. */\n  readonly seatsBefore: readonly SeatInfo[];\n};\n\nconst ENGINE_ASSISTS: readonly unknown[] = ['hint', 'check', 'reveal', 'shuffle'];\n\n/** The assistance a transition flagged. Anything but a kind an engine may report is ignored. */\nexport const assistOf = (transition: { readonly assist?: EngineAssist }): EngineAssist | null =>\n  ENGINE_ASSISTS.includes(transition.assist) ? (transition.assist as EngineAssist) : null;\n\n/** What the runner keeps of one accepted input and its transition. */\nexport const recordOf = <Command, State, Event>(\n  input: EngineInput<Command>,\n  transition: Transition<State, Event>,\n  seatsBefore: readonly SeatInfo[],\n): InputRecord<Command> => ({\n  input,\n  jobs: transition.jobs ?? [],\n  barrier: transition.undoBarrier === true,\n  assist: assistOf(transition),\n  startsClock: transition.startsClock === true,\n  restartsGame: transition.restartsGame === true,\n  seatsBefore,\n});\n\n/** Applies a seat change to the seat list, as the runner shows it in `meta.seats`. */\nexport const applySeatChange = <Command>(\n  seats: readonly SeatInfo[],\n  input: EngineInput<Command>,\n): readonly SeatInfo[] => {\n  if (input.kind !== 'seat' || input.change.type !== 'controller') return seats;\n  const { change } = input;\n  return seats.map((seat) =>\n    seat.id === input.seat\n      ? compact({ id: seat.id, name: change.name, controller: change.controller, aiLevel: change.aiLevel })\n      : seat,\n  );\n};\n\n/**\n * Calls `apply` the way a runner must: a throw becomes an `EngineThrew` error, and on any\n * failure the random source is restored, so a rejected input never consumes randomness that\n * a replay (which skips rejected inputs) would not.\n */\nexport const safeApply = <\n  State extends Json,\n  Command extends Json,\n  View extends Json,\n  Event extends Json,\n  Config extends Json,\n>(\n  engine: DiscreteEngine<State, Command, View, Event, Config>,\n  state: State,\n  input: EngineInput<Command>,\n  rng: Rng,\n  restoreRng: RngFactory,\n): { readonly result: Result<Transition<State, Event>>; readonly rng: Rng; readonly thrown?: unknown } => {\n  const before = rng.save();\n  try {\n    const result = engine.apply(state, input, rng);\n    if (\n      result.ok &&\n      result.value.restartsGame === true &&\n      (input.kind !== 'command' || result.value.undoBarrier !== true || engine.outcome(result.value.state) !== null)\n    )\n      return {\n        result: err(\n          gameError('BadRestart', 'A new game needs a setup command, an undo barrier and an unfinished state.'),\n        ),\n        rng: restoreRng(before),\n      };\n    return result.ok ? { result, rng } : { result, rng: restoreRng(before) };\n  } catch (thrown) {\n    return {\n      result: err(gameError('EngineThrew', 'Something went wrong. Your last action was not applied.')),\n      rng: restoreRng(before),\n      thrown,\n    };\n  }\n};\n\nexport type Rebuilt<State, Command> = {\n  readonly state: State;\n  readonly rng: Rng;\n  readonly seats: readonly SeatInfo[];\n  readonly records: readonly InputRecord<Command>[];\n};\n\n/** Runs `init` with the seed, then every input. Any rejection fails the whole replay. */\nexport const rebuild = <\n  State extends Json,\n  Command extends Json,\n  View extends Json,\n  Event extends Json,\n  Config extends Json,\n>(\n  engine: DiscreteEngine<State, Command, View, Event, Config>,\n  start: { readonly config: Config; readonly seats: readonly SeatInfo[]; readonly seed: RngState },\n  inputs: readonly EngineInput<Command>[],\n  restoreRng: RngFactory,\n): Result<Rebuilt<State, Command>, GameError> => {\n  let rng = restoreRng(start.seed);\n  let initialized: Result<State>;\n  try {\n    initialized = engine.init(start.config, start.seats, rng);\n  } catch {\n    return err(gameError('EngineThrew', 'The game could not be set up.'));\n  }\n  if (!initialized.ok) return initialized;\n  let state = initialized.value;\n  let seats = start.seats;\n  const records: InputRecord<Command>[] = [];\n  for (const [index, input] of inputs.entries()) {\n    const applied = safeApply(engine, state, input, rng, restoreRng);\n    rng = applied.rng;\n    if (!applied.result.ok) {\n      return err(\n        gameError('ReplayDiverged', 'The saved moves no longer replay.', { index, code: applied.result.error.code }),\n      );\n    }\n    const transition = applied.result.value;\n    records.push(recordOf(input, transition, seats));\n    seats = applySeatChange(seats, input);\n    state = transition.state;\n  }\n  return ok({ state, rng, seats, records });\n};\n\n/**\n * Replays a recorded Layer 2 game and returns its final state and random state. The\n * conformance tests compare these with the recorded game's.\n */\nexport const replayEngine = <\n  State extends Json,\n  Command extends Json,\n  View extends Json,\n  Event extends Json,\n  Config extends Json,\n>(\n  engine: DiscreteEngine<State, Command, View, Event, Config>,\n  replay: EngineReplay<Command, Config>,\n  restoreRng: RngFactory = defaultRestoreRng,\n): Result<{ readonly state: State; readonly rng: RngState; readonly barriers: readonly number[] }, GameError> => {\n  if (replay.rulesVersion !== engine.rulesVersion) {\n    return err(gameError('RulesChanged', 'This replay was recorded under different rules.'));\n  }\n  const rebuilt = rebuild(engine, replay, replay.inputs, restoreRng);\n  if (!rebuilt.ok) return rebuilt;\n  const barriers = rebuilt.value.records.flatMap((record, i) => (record.barrier ? [i] : []));\n  return ok({ state: rebuilt.value.state, rng: rebuilt.value.rng.save(), barriers });\n};\n\n/**\n * Replays a recorded Layer 3 game: `init` with the seed, then `step` up to `endTick`, feeding\n * each tick its inputs in array order.\n */\nexport const replaySimulation = <State extends Json, Input extends Json, View, Event extends Json, Config extends Json>(\n  simulation: FixedStepSimulation<State, Input, View, Event, Config>,\n  replay: SimulationReplay<Input, Config>,\n  restoreRng: RngFactory = defaultRestoreRng,\n): Result<{ readonly state: State; readonly rng: RngState }, GameError> => {\n  if (replay.rulesVersion !== simulation.rulesVersion) {\n    return err(gameError('RulesChanged', 'This replay was recorded under different rules.'));\n  }\n  const rng = restoreRng(replay.seed);\n  const initialized = simulation.init(replay.config, rng);\n  if (!initialized.ok) return initialized;\n  let state = initialized.value;\n  let next = 0;\n  for (let tick = 0; tick < replay.endTick; tick += 1) {\n    const inputs: Input[] = [];\n    while (next < replay.inputs.length && replay.inputs[next]!.tick === tick) {\n      inputs.push(replay.inputs[next]!.input);\n      next += 1;\n    }\n    state = simulation.step(state, inputs, rng).state;\n  }\n  return ok({ state, rng: rng.save() });\n};\n\nconst isSeat = (value: unknown): value is number => Number.isInteger(value) && (value as number) >= 0;\n\nconst parseJobOutcome = (value: unknown): JobOutcome | null => {\n  if (!isRecord(value)) return null;\n  if (value['ok'] === true && Object.hasOwn(value, 'value')) return { ok: true, value: value['value'] as Json };\n  if (value['ok'] === false && (value['reason'] === 'timeout' || value['reason'] === 'failed')) {\n    return { ok: false, reason: value['reason'] };\n  }\n  return null;\n};\n\n/** Parses one input from a stored replay; commands go through the engine's schema. */\nexport const parseEngineInput = <Command>(\n  value: unknown,\n  command: Validator<Command>,\n): Result<EngineInput<Command>, GameError> => {\n  const bad = err(gameError('SaveUnreadable', 'This saved game could not be read.', { why: 'replay input' }));\n  if (!isRecord(value)) return bad;\n  switch (value['kind']) {\n    case 'command': {\n      if (!isSeat(value['seat'])) return bad;\n      const decoded = decode(command, value['command'], 'saved command');\n      return decoded.ok ? ok({ kind: 'command', seat: value['seat'], command: decoded.value }) : decoded;\n    }\n    case 'seat': {\n      const change = value['change'];\n      if (!isSeat(value['seat']) || !isRecord(change)) return bad;\n      if (change['type'] === 'left') return ok({ kind: 'seat', seat: value['seat'], change: { type: 'left' } });\n      if (\n        change['type'] !== 'controller' ||\n        (change['controller'] !== 'human' && change['controller'] !== 'ai') ||\n        typeof change['name'] !== 'string' ||\n        (change['aiLevel'] !== undefined && typeof change['aiLevel'] !== 'string')\n      ) {\n        return bad;\n      }\n      return ok({\n        kind: 'seat',\n        seat: value['seat'],\n        change: compact({\n          type: 'controller',\n          controller: change['controller'],\n          name: change['name'],\n          aiLevel: change['aiLevel'],\n        }),\n      });\n    }\n    case 'timeout':\n    case 'resign':\n      return isSeat(value['seat']) ? ok({ kind: value['kind'], seat: value['seat'] }) : bad;\n    case 'job': {\n      const outcome = parseJobOutcome(value['outcome']);\n      return typeof value['jobId'] === 'string' && outcome !== null\n        ? ok({ kind: 'job', jobId: value['jobId'], outcome })\n        : bad;\n    }\n    default:\n      return bad;\n  }\n};\n"],"mappings":";;;;AA0CA,IAAM,iBAAqC;CAAC;CAAQ;CAAS;CAAU;AAAS;;AAGhF,IAAa,YAAY,eACvB,eAAe,SAAS,WAAW,MAAM,IAAK,WAAW,SAA0B;;AAGrF,IAAa,YACX,OACA,YACA,iBAC0B;CAC1B;CACA,MAAM,WAAW,QAAQ,CAAC;CAC1B,SAAS,WAAW,gBAAgB;CACpC,QAAQ,SAAS,UAAU;CAC3B,aAAa,WAAW,gBAAgB;CACxC,cAAc,WAAW,iBAAiB;CAC1C;AACF;;AAGA,IAAa,mBACX,OACA,UACwB;CACxB,IAAI,MAAM,SAAS,UAAU,MAAM,OAAO,SAAS,cAAc,OAAO;CACxE,MAAM,EAAE,WAAW;CACnB,OAAO,MAAM,KAAK,SAChB,KAAK,OAAO,MAAM,OACd,QAAQ;EAAE,IAAI,KAAK;EAAI,MAAM,OAAO;EAAM,YAAY,OAAO;EAAY,SAAS,OAAO;CAAQ,CAAC,IAClG,IACN;AACF;;;;;;AAOA,IAAa,aAOX,QACA,OACA,OACA,KACA,eACwG;CACxG,MAAM,SAAS,IAAI,KAAK;CACxB,IAAI;EACF,MAAM,SAAS,OAAO,MAAM,OAAO,OAAO,GAAG;EAC7C,IACE,OAAO,MACP,OAAO,MAAM,iBAAiB,SAC7B,MAAM,SAAS,aAAa,OAAO,MAAM,gBAAgB,QAAQ,OAAO,QAAQ,OAAO,MAAM,KAAK,MAAM,OAEzG,OAAO;GACL,QAAQ,IACN,UAAU,cAAc,4EAA4E,CACtG;GACA,KAAK,WAAW,MAAM;EACxB;EACF,OAAO,OAAO,KAAK;GAAE;GAAQ;EAAI,IAAI;GAAE;GAAQ,KAAK,WAAW,MAAM;EAAE;CACzE,SAAS,QAAQ;EACf,OAAO;GACL,QAAQ,IAAI,UAAU,eAAe,yDAAyD,CAAC;GAC/F,KAAK,WAAW,MAAM;GACtB;EACF;CACF;AACF;;AAUA,IAAa,WAOX,QACA,OACA,QACA,eAC+C;CAC/C,IAAI,MAAM,WAAW,MAAM,IAAI;CAC/B,IAAI;CACJ,IAAI;EACF,cAAc,OAAO,KAAK,MAAM,QAAQ,MAAM,OAAO,GAAG;CAC1D,QAAQ;EACN,OAAO,IAAI,UAAU,eAAe,+BAA+B,CAAC;CACtE;CACA,IAAI,CAAC,YAAY,IAAI,OAAO;CAC5B,IAAI,QAAQ,YAAY;CACxB,IAAI,QAAQ,MAAM;CAClB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,OAAO,UAAU,OAAO,QAAQ,GAAG;EAC7C,MAAM,UAAU,UAAU,QAAQ,OAAO,OAAO,KAAK,UAAU;EAC/D,MAAM,QAAQ;EACd,IAAI,CAAC,QAAQ,OAAO,IAClB,OAAO,IACL,UAAU,kBAAkB,qCAAqC;GAAE;GAAO,MAAM,QAAQ,OAAO,MAAM;EAAK,CAAC,CAC7G;EAEF,MAAM,aAAa,QAAQ,OAAO;EAClC,QAAQ,KAAK,SAAS,OAAO,YAAY,KAAK,CAAC;EAC/C,QAAQ,gBAAgB,OAAO,KAAK;EACpC,QAAQ,WAAW;CACrB;CACA,OAAO,GAAG;EAAE;EAAO;EAAK;EAAO;CAAQ,CAAC;AAC1C;;;;;AAMA,IAAa,gBAOX,QACA,QACA,aAAyB,sBACsF;CAC/G,IAAI,OAAO,iBAAiB,OAAO,cACjC,OAAO,IAAI,UAAU,gBAAgB,iDAAiD,CAAC;CAEzF,MAAM,UAAU,QAAQ,QAAQ,QAAQ,OAAO,QAAQ,UAAU;CACjE,IAAI,CAAC,QAAQ,IAAI,OAAO;CACxB,MAAM,WAAW,QAAQ,MAAM,QAAQ,SAAS,QAAQ,MAAO,OAAO,UAAU,CAAC,CAAC,IAAI,CAAC,CAAE;CACzF,OAAO,GAAG;EAAE,OAAO,QAAQ,MAAM;EAAO,KAAK,QAAQ,MAAM,IAAI,KAAK;EAAG;CAAS,CAAC;AACnF;;;;;AAMA,IAAa,oBACX,YACA,QACA,aAAyB,sBACgD;CACzE,IAAI,OAAO,iBAAiB,WAAW,cACrC,OAAO,IAAI,UAAU,gBAAgB,iDAAiD,CAAC;CAEzF,MAAM,MAAM,WAAW,OAAO,IAAI;CAClC,MAAM,cAAc,WAAW,KAAK,OAAO,QAAQ,GAAG;CACtD,IAAI,CAAC,YAAY,IAAI,OAAO;CAC5B,IAAI,QAAQ,YAAY;CACxB,IAAI,OAAO;CACX,KAAK,IAAI,OAAO,GAAG,OAAO,OAAO,SAAS,QAAQ,GAAG;EACnD,MAAM,SAAkB,CAAC;EACzB,OAAO,OAAO,OAAO,OAAO,UAAU,OAAO,OAAO,KAAK,CAAE,SAAS,MAAM;GACxE,OAAO,KAAK,OAAO,OAAO,KAAK,CAAE,KAAK;GACtC,QAAQ;EACV;EACA,QAAQ,WAAW,KAAK,OAAO,QAAQ,GAAG,CAAC,CAAC;CAC9C;CACA,OAAO,GAAG;EAAE;EAAO,KAAK,IAAI,KAAK;CAAE,CAAC;AACtC;AAEA,IAAM,UAAU,UAAoC,OAAO,UAAU,KAAK,KAAM,SAAoB;AAEpG,IAAM,mBAAmB,UAAsC;CAC7D,IAAI,CAAC,SAAS,KAAK,GAAG,OAAO;CAC7B,IAAI,MAAM,UAAU,QAAQ,OAAO,OAAO,OAAO,OAAO,GAAG,OAAO;EAAE,IAAI;EAAM,OAAO,MAAM;CAAiB;CAC5G,IAAI,MAAM,UAAU,UAAU,MAAM,cAAc,aAAa,MAAM,cAAc,WACjF,OAAO;EAAE,IAAI;EAAO,QAAQ,MAAM;CAAU;CAE9C,OAAO;AACT;;AAGA,IAAa,oBACX,OACA,YAC4C;CAC5C,MAAM,MAAM,IAAI,UAAU,kBAAkB,sCAAsC,EAAE,KAAK,eAAe,CAAC,CAAC;CAC1G,IAAI,CAAC,SAAS,KAAK,GAAG,OAAO;CAC7B,QAAQ,MAAM,SAAd;EACE,KAAK,WAAW;GACd,IAAI,CAAC,OAAO,MAAM,OAAO,GAAG,OAAO;GACnC,MAAM,UAAU,OAAO,SAAS,MAAM,YAAY,eAAe;GACjE,OAAO,QAAQ,KAAK,GAAG;IAAE,MAAM;IAAW,MAAM,MAAM;IAAS,SAAS,QAAQ;GAAM,CAAC,IAAI;EAC7F;EACA,KAAK,QAAQ;GACX,MAAM,SAAS,MAAM;GACrB,IAAI,CAAC,OAAO,MAAM,OAAO,KAAK,CAAC,SAAS,MAAM,GAAG,OAAO;GACxD,IAAI,OAAO,YAAY,QAAQ,OAAO,GAAG;IAAE,MAAM;IAAQ,MAAM,MAAM;IAAS,QAAQ,EAAE,MAAM,OAAO;GAAE,CAAC;GACxG,IACE,OAAO,YAAY,gBAClB,OAAO,kBAAkB,WAAW,OAAO,kBAAkB,QAC9D,OAAO,OAAO,YAAY,YACzB,OAAO,eAAe,KAAA,KAAa,OAAO,OAAO,eAAe,UAEjE,OAAO;GAET,OAAO,GAAG;IACR,MAAM;IACN,MAAM,MAAM;IACZ,QAAQ,QAAQ;KACd,MAAM;KACN,YAAY,OAAO;KACnB,MAAM,OAAO;KACb,SAAS,OAAO;IAClB,CAAC;GACH,CAAC;EACH;EACA,KAAK;EACL,KAAK,UACH,OAAO,OAAO,MAAM,OAAO,IAAI,GAAG;GAAE,MAAM,MAAM;GAAS,MAAM,MAAM;EAAQ,CAAC,IAAI;EACpF,KAAK,OAAO;GACV,MAAM,UAAU,gBAAgB,MAAM,UAAU;GAChD,OAAO,OAAO,MAAM,aAAa,YAAY,YAAY,OACrD,GAAG;IAAE,MAAM;IAAO,OAAO,MAAM;IAAU;GAAQ,CAAC,IAClD;EACN;EACA,SACE,OAAO;CACX;AACF"}

package/dist/rngs.d.ts

@@ -0,0 +1,22 @@
+import type { RngState, SeatId } from '@joystyk/contracts';
+import type { RngFactory } from './ports.js';
+/** The default factory: the kit's SFC32. */
+export declare const defaultRestoreRng: RngFactory;
+/**
+ * Restores a state from the AI stream. Forks are always the kit's SFC32, whatever algorithm
+ * the game's seed names; anything else goes to the game's factory.
+ */
+export declare const aiRestore: (game: RngFactory) => RngFactory;
+/** An AI seed derived from a game's random state: a fork of a copy, so the game's stream doesn't move. */
+export declare const deriveAiSeed: (state: RngState, restore: RngFactory) => RngState;
+/**
+ * The child stream for one decision of `seat`: fork number `seat` of the AI stream's state.
+ * Seats choosing at the same time get different children; a choice that is cancelled and
+ * started again gets the same one, because the stream only moves when a move is accepted.
+ */
+export declare const aiDecisionSeed: (state: RngState, seat: SeatId, restore: RngFactory) => RngState;
+/**
+ * The AI stream after an accepted AI move: one fork per seat, past every child the old state
+ * handed out, so no later decision reuses a child.
+ */
+export declare const advanceAi: (state: RngState, seats: number, restore: RngFactory) => RngState;

package/dist/rngs.js

@@ -0,0 +1,34 @@
+import { SFC32, forkRng, restoreRng } from "@joystyk/kit";
+//#region src/rngs.ts
+/** The default factory: the kit's SFC32. */
+var defaultRestoreRng = restoreRng;
+/**
+* Restores a state from the AI stream. Forks are always the kit's SFC32, whatever algorithm
+* the game's seed names; anything else goes to the game's factory.
+*/
+var aiRestore = (game) => (state) => state.algorithm === SFC32 ? restoreRng(state) : game(state);
+/** An AI seed derived from a game's random state: a fork of a copy, so the game's stream doesn't move. */
+var deriveAiSeed = (state, restore) => forkRng(restore(state)).save();
+/**
+* The child stream for one decision of `seat`: fork number `seat` of the AI stream's state.
+* Seats choosing at the same time get different children; a choice that is cancelled and
+* started again gets the same one, because the stream only moves when a move is accepted.
+*/
+var aiDecisionSeed = (state, seat, restore) => {
+	const parent = restore(state);
+	for (let i = 0; i < seat; i += 1) forkRng(parent);
+	return forkRng(parent).save();
+};
+/**
+* The AI stream after an accepted AI move: one fork per seat, past every child the old state
+* handed out, so no later decision reuses a child.
+*/
+var advanceAi = (state, seats, restore) => {
+	const parent = restore(state);
+	for (let i = 0; i < seats; i += 1) forkRng(parent);
+	return parent.save();
+};
+//#endregion
+export { advanceAi, aiDecisionSeed, aiRestore, defaultRestoreRng, deriveAiSeed };
+
+//# sourceMappingURL=rngs.js.map

package/dist/rngs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rngs.js","names":[],"sources":["../src/rngs.ts"],"sourcesContent":["// The runners' random sources. The game's stream is restored with the factory the caller\n// passes (the kit's `restoreRng` by default). The AI's stream is the platform's own: each AI\n// decision gets a child forked with the kit's `forkRng`, so the stream moves by a fixed\n// amount per accepted AI move however much a search draws, and a worker can receive the\n// child as plain `RngState` (game-contract.md, \"AI: runner-driven or engine-driven\").\nimport type { RngState, SeatId } from '@joystyk/contracts';\nimport { forkRng, restoreRng, SFC32 } from '@joystyk/kit';\nimport type { RngFactory } from './ports.ts';\n\n/** The default factory: the kit's SFC32. */\nexport const defaultRestoreRng: RngFactory = restoreRng;\n\n/**\n * Restores a state from the AI stream. Forks are always the kit's SFC32, whatever algorithm\n * the game's seed names; anything else goes to the game's factory.\n */\nexport const aiRestore =\n  (game: RngFactory): RngFactory =>\n  (state) =>\n    state.algorithm === SFC32 ? restoreRng(state) : game(state);\n\n/** An AI seed derived from a game's random state: a fork of a copy, so the game's stream doesn't move. */\nexport const deriveAiSeed = (state: RngState, restore: RngFactory): RngState => forkRng(restore(state)).save();\n\n/**\n * The child stream for one decision of `seat`: fork number `seat` of the AI stream's state.\n * Seats choosing at the same time get different children; a choice that is cancelled and\n * started again gets the same one, because the stream only moves when a move is accepted.\n */\nexport const aiDecisionSeed = (state: RngState, seat: SeatId, restore: RngFactory): RngState => {\n  const parent = restore(state);\n  for (let i = 0; i < seat; i += 1) forkRng(parent);\n  return forkRng(parent).save();\n};\n\n/**\n * The AI stream after an accepted AI move: one fork per seat, past every child the old state\n * handed out, so no later decision reuses a child.\n */\nexport const advanceAi = (state: RngState, seats: number, restore: RngFactory): RngState => {\n  const parent = restore(state);\n  for (let i = 0; i < seats; i += 1) forkRng(parent);\n  return parent.save();\n};\n"],"mappings":";;;AAUA,IAAa,oBAAgC;;;;;AAM7C,IAAa,aACV,UACA,UACC,MAAM,cAAc,QAAQ,WAAW,KAAK,IAAI,KAAK,KAAK;;AAG9D,IAAa,gBAAgB,OAAiB,YAAkC,QAAQ,QAAQ,KAAK,CAAC,CAAC,CAAC,KAAK;;;;;;AAO7G,IAAa,kBAAkB,OAAiB,MAAc,YAAkC;CAC9F,MAAM,SAAS,QAAQ,KAAK;CAC5B,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,KAAK,GAAG,QAAQ,MAAM;CAChD,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK;AAC9B;;;;;AAMA,IAAa,aAAa,OAAiB,OAAe,YAAkC;CAC1F,MAAM,SAAS,QAAQ,KAAK;CAC5B,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,KAAK,GAAG,QAAQ,MAAM;CACjD,OAAO,OAAO,KAAK;AACrB"}

package/dist/saves.d.ts

@@ -0,0 +1,20 @@
+import { type GameError, type GameManifest, type Json, type Migration, type Result, type SaveEnvelope, type SeatInfo, type Validator } from '@joystyk/contracts';
+/** The parts of a game's manifest a runner reads. `ai` matters only for its `heavy` flag. */
+export type RunnerManifest = Pick<GameManifest, 'id' | 'versions' | 'undo' | 'handoff'> & {
+    readonly ai?: GameManifest['ai'];
+};
+export declare const isSeatInfo: (value: unknown) => value is SeatInfo;
+/** Checks the envelope's shape. The replay is checked by the runner that understands it. */
+export declare const parseEnvelope: (value: unknown) => Result<SaveEnvelope, GameError>;
+/**
+ * Brings a save up to date and validates its state. Fails with `SaveUnreadable`,
+ * `SaveWrongGame`, `RulesChanged` (the rules version differs, so the game can't continue on
+ * this code), a migration error, or `InvalidInput` from the state schema. The launcher
+ * archives the save on any failure.
+ */
+export declare const loadSave: <State>(value: unknown, manifest: RunnerManifest, rulesVersion: number, migrations: readonly Migration[], stateSchema: Validator<State>) => Result<{
+    readonly envelope: SaveEnvelope;
+    readonly state: State;
+}, GameError>;
+/** True when a value is a list of JSON inputs, the least a replay's `inputs` must be. */
+export declare const isJsonList: (value: unknown) => value is readonly Json[];

package/dist/saves.js

@@ -0,0 +1,59 @@
+import { decode, isRecord } from "./values.js";
+import { assistCountsSchema } from "./assistance.js";
+import { ASSIST_KINDS, err, gameError, isJson, ok, runMigrations } from "@joystyk/contracts";
+//#region src/saves.ts
+var unreadable = (why) => gameError("SaveUnreadable", "This saved game could not be read.", { why });
+var isRngState = (value) => isRecord(value) && typeof value["algorithm"] === "string" && Array.isArray(value["words"]) && value["words"].every((word) => typeof word === "number" && Number.isFinite(word));
+var isSeatInfo = (value) => isRecord(value) && Number.isInteger(value["id"]) && typeof value["name"] === "string" && (value["controller"] === "human" || value["controller"] === "ai") && (value["aiLevel"] === void 0 || typeof value["aiLevel"] === "string");
+var isWholeNumber = (value) => Number.isInteger(value) && value >= 0;
+/** Checks the envelope's shape. The replay is checked by the runner that understands it. */
+var parseEnvelope = (value) => {
+	if (!isRecord(value) || !isJson(value)) return err(unreadable("not a JSON object"));
+	if (typeof value["gameId"] !== "string" || typeof value["build"] !== "string") return err(unreadable("game id or build"));
+	if (!isWholeNumber(value["rulesVersion"]) || !isWholeNumber(value["saveVersion"])) return err(unreadable("versions"));
+	if (!isRngState(value["rng"])) return err(unreadable("rng"));
+	const seats = value["seats"];
+	if (!Array.isArray(seats) || !seats.every(isSeatInfo) || seats.some((seat, i) => seat.id !== i)) return err(unreadable("seats"));
+	if (value["daily"] !== void 0 && (!isRecord(value["daily"]) || typeof value["daily"]["puzzleId"] !== "string" || typeof value["daily"]["contentHash"] !== "string")) return err(unreadable("daily"));
+	if (!Object.hasOwn(value, "state")) return err(unreadable("state"));
+	if (value["tick"] !== void 0 && !isWholeNumber(value["tick"])) return err(unreadable("tick"));
+	if (value["elapsedMs"] !== void 0 && !isWholeNumber(value["elapsedMs"])) return err(unreadable("elapsedMs"));
+	if (value["clockStarted"] !== void 0 && typeof value["clockStarted"] !== "boolean") return err(unreadable("clockStarted"));
+	if (value["replay"] !== void 0 && !isRecord(value["replay"])) return err(unreadable("replay"));
+	if (value["aiRng"] !== void 0 && !isRngState(value["aiRng"])) return err(unreadable("aiRng"));
+	if (value["undosUsed"] !== void 0 && !isWholeNumber(value["undosUsed"])) return err(unreadable("undosUsed"));
+	const assists = value["assists"];
+	if (assists !== void 0 && !(Array.isArray(assists) && assists.every((kind) => ASSIST_KINDS.includes(kind)))) return err(unreadable("assists"));
+	if (value["assistCounts"] !== void 0 && !decode(assistCountsSchema, value["assistCounts"], "assistance counts").ok) return err(unreadable("assistCounts"));
+	return ok(value);
+};
+/**
+* Brings a save up to date and validates its state. Fails with `SaveUnreadable`,
+* `SaveWrongGame`, `RulesChanged` (the rules version differs, so the game can't continue on
+* this code), a migration error, or `InvalidInput` from the state schema. The launcher
+* archives the save on any failure.
+*/
+var loadSave = (value, manifest, rulesVersion, migrations, stateSchema) => {
+	const parsed = parseEnvelope(value);
+	if (!parsed.ok) return parsed;
+	const envelope = parsed.value;
+	if (envelope.gameId !== manifest.id) return err(gameError("SaveWrongGame", "This saved game belongs to a different game.", { gameId: envelope.gameId }));
+	if (envelope.rulesVersion !== rulesVersion) return err(gameError("RulesChanged", "This saved game was played under older rules and can no longer continue.", {
+		saved: envelope.rulesVersion,
+		current: rulesVersion
+	}));
+	const migrated = runMigrations(migrations, envelope.state, envelope.saveVersion, manifest.versions.save);
+	if (!migrated.ok) return migrated;
+	const state = decode(stateSchema, migrated.value, "saved state");
+	if (!state.ok) return state;
+	return ok({
+		envelope,
+		state: state.value
+	});
+};
+/** True when a value is a list of JSON inputs, the least a replay's `inputs` must be. */
+var isJsonList = (value) => Array.isArray(value) && isJson(value);
+//#endregion
+export { isJsonList, isSeatInfo, loadSave, parseEnvelope };
+
+//# sourceMappingURL=saves.js.map

package/dist/saves.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saves.js","names":[],"sources":["../src/saves.ts"],"sourcesContent":["// Reading a save from storage: parse the envelope, check it belongs to this game and these\n// rules, run the migration chain, then validate the state (game-contract.md, \"Saves\").\nimport {\n  ASSIST_KINDS,\n  err,\n  gameError,\n  isJson,\n  ok,\n  runMigrations,\n  type GameError,\n  type GameManifest,\n  type Json,\n  type Migration,\n  type Result,\n  type RngState,\n  type SaveEnvelope,\n  type SeatInfo,\n  type Validator,\n} from '@joystyk/contracts';\nimport { decode, isRecord } from './values.ts';\nimport { assistCountsSchema } from './assistance.ts';\n\n/** The parts of a game's manifest a runner reads. `ai` matters only for its `heavy` flag. */\nexport type RunnerManifest = Pick<GameManifest, 'id' | 'versions' | 'undo' | 'handoff'> & {\n  readonly ai?: GameManifest['ai'];\n};\n\nconst unreadable = (why: string): GameError =>\n  gameError('SaveUnreadable', 'This saved game could not be read.', { why });\n\nconst isRngState = (value: unknown): value is RngState =>\n  isRecord(value) &&\n  typeof value['algorithm'] === 'string' &&\n  Array.isArray(value['words']) &&\n  value['words'].every((word) => typeof word === 'number' && Number.isFinite(word));\n\nexport const isSeatInfo = (value: unknown): value is SeatInfo =>\n  isRecord(value) &&\n  Number.isInteger(value['id']) &&\n  typeof value['name'] === 'string' &&\n  (value['controller'] === 'human' || value['controller'] === 'ai') &&\n  (value['aiLevel'] === undefined || typeof value['aiLevel'] === 'string');\n\nconst isWholeNumber = (value: unknown): value is number => Number.isInteger(value) && (value as number) >= 0;\n\n/** Checks the envelope's shape. The replay is checked by the runner that understands it. */\nexport const parseEnvelope = (value: unknown): Result<SaveEnvelope, GameError> => {\n  if (!isRecord(value) || !isJson(value)) return err(unreadable('not a JSON object'));\n  if (typeof value['gameId'] !== 'string' || typeof value['build'] !== 'string')\n    return err(unreadable('game id or build'));\n  if (!isWholeNumber(value['rulesVersion']) || !isWholeNumber(value['saveVersion'])) return err(unreadable('versions'));\n  if (!isRngState(value['rng'])) return err(unreadable('rng'));\n  const seats = value['seats'];\n  if (!Array.isArray(seats) || !seats.every(isSeatInfo) || seats.some((seat, i) => seat.id !== i)) {\n    return err(unreadable('seats'));\n  }\n  if (\n    value['daily'] !== undefined &&\n    (!isRecord(value['daily']) ||\n      typeof value['daily']['puzzleId'] !== 'string' ||\n      typeof value['daily']['contentHash'] !== 'string')\n  )\n    return err(unreadable('daily'));\n  if (!Object.hasOwn(value, 'state')) return err(unreadable('state'));\n  if (value['tick'] !== undefined && !isWholeNumber(value['tick'])) return err(unreadable('tick'));\n  if (value['elapsedMs'] !== undefined && !isWholeNumber(value['elapsedMs'])) return err(unreadable('elapsedMs'));\n  if (value['clockStarted'] !== undefined && typeof value['clockStarted'] !== 'boolean')\n    return err(unreadable('clockStarted'));\n  if (value['replay'] !== undefined && !isRecord(value['replay'])) return err(unreadable('replay'));\n  if (value['aiRng'] !== undefined && !isRngState(value['aiRng'])) return err(unreadable('aiRng'));\n  if (value['undosUsed'] !== undefined && !isWholeNumber(value['undosUsed'])) return err(unreadable('undosUsed'));\n  const assists = value['assists'];\n  if (\n    assists !== undefined &&\n    !(Array.isArray(assists) && assists.every((kind) => (ASSIST_KINDS as readonly unknown[]).includes(kind)))\n  ) {\n    return err(unreadable('assists'));\n  }\n  if (value['assistCounts'] !== undefined && !decode(assistCountsSchema, value['assistCounts'], 'assistance counts').ok)\n    return err(unreadable('assistCounts'));\n  return ok(value as unknown as SaveEnvelope);\n};\n\n/**\n * Brings a save up to date and validates its state. Fails with `SaveUnreadable`,\n * `SaveWrongGame`, `RulesChanged` (the rules version differs, so the game can't continue on\n * this code), a migration error, or `InvalidInput` from the state schema. The launcher\n * archives the save on any failure.\n */\nexport const loadSave = <State>(\n  value: unknown,\n  manifest: RunnerManifest,\n  rulesVersion: number,\n  migrations: readonly Migration[],\n  stateSchema: Validator<State>,\n): Result<{ readonly envelope: SaveEnvelope; readonly state: State }, GameError> => {\n  const parsed = parseEnvelope(value);\n  if (!parsed.ok) return parsed;\n  const envelope = parsed.value;\n  if (envelope.gameId !== manifest.id) {\n    return err(gameError('SaveWrongGame', 'This saved game belongs to a different game.', { gameId: envelope.gameId }));\n  }\n  if (envelope.rulesVersion !== rulesVersion) {\n    return err(\n      gameError('RulesChanged', 'This saved game was played under older rules and can no longer continue.', {\n        saved: envelope.rulesVersion,\n        current: rulesVersion,\n      }),\n    );\n  }\n  const migrated = runMigrations(migrations, envelope.state, envelope.saveVersion, manifest.versions.save);\n  if (!migrated.ok) return migrated;\n  const state = decode(stateSchema, migrated.value, 'saved state');\n  if (!state.ok) return state;\n  return ok({ envelope, state: state.value });\n};\n\n/** True when a value is a list of JSON inputs, the least a replay's `inputs` must be. */\nexport const isJsonList = (value: unknown): value is readonly Json[] => Array.isArray(value) && isJson(value);\n"],"mappings":"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"}

package/dist/stopwatch.d.ts

@@ -0,0 +1,22 @@
+import type { Clock } from './ports.js';
+export type Stopwatch = {
+    /** Milliseconds of active play so far, rounded to a whole number. */
+    elapsed(): number;
+    /** Starts the clock. Later calls do nothing. */
+    start(): void;
+    /** True once `start` was called (or the game was restored with its clock started). */
+    started(): boolean;
+    /** A confirmed new game: clear elapsed time and wait for its first meaningful input. */
+    restart(): void;
+    /** Stops for good (the game is over). */
+    finish(): void;
+    setHidden(hidden: boolean): void;
+    setPaused(paused: boolean): void;
+    running(): boolean;
+};
+export declare const createStopwatch: (clock: Clock, initial: {
+    readonly elapsedMs: number;
+    readonly started: boolean;
+    readonly finished: boolean;
+    readonly hidden: boolean;
+}) => Stopwatch;

package/dist/stopwatch.js

@@ -0,0 +1,51 @@
+//#region src/stopwatch.ts
+var createStopwatch = (clock, initial) => {
+	let banked = initial.elapsedMs;
+	let since = null;
+	let started = initial.started;
+	let finished = initial.finished;
+	let hidden = initial.hidden;
+	let paused = false;
+	const shouldRun = () => started && !finished && !hidden && !paused;
+	const sync = () => {
+		const run = shouldRun();
+		if (run && since === null) since = clock.now();
+		if (!run && since !== null) {
+			banked += Math.max(0, clock.now() - since);
+			since = null;
+		}
+	};
+	sync();
+	return {
+		elapsed: () => Math.round(banked + (since === null ? 0 : Math.max(0, clock.now() - since))),
+		start: () => {
+			started = true;
+			sync();
+		},
+		started: () => started,
+		restart: () => {
+			banked = 0;
+			since = null;
+			started = false;
+			finished = false;
+			sync();
+		},
+		finish: () => {
+			finished = true;
+			sync();
+		},
+		setHidden: (value) => {
+			hidden = value;
+			sync();
+		},
+		setPaused: (value) => {
+			paused = value;
+			sync();
+		},
+		running: () => since !== null
+	};
+};
+//#endregion
+export { createStopwatch };
+
+//# sourceMappingURL=stopwatch.js.map

package/dist/stopwatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stopwatch.js","names":[],"sources":["../src/stopwatch.ts"],"sourcesContent":["// Active play time (game-contract.md, \"Saves\"): it starts at the input that starts the clock\n// (the first accepted one, or the engine's `startsClock` transition), pauses while the page is\n// hidden or the game is paused, and stops at the outcome.\nimport type { Clock } from './ports.ts';\n\nexport type Stopwatch = {\n  /** Milliseconds of active play so far, rounded to a whole number. */\n  elapsed(): number;\n  /** Starts the clock. Later calls do nothing. */\n  start(): void;\n  /** True once `start` was called (or the game was restored with its clock started). */\n  started(): boolean;\n  /** A confirmed new game: clear elapsed time and wait for its first meaningful input. */\n  restart(): void;\n  /** Stops for good (the game is over). */\n  finish(): void;\n  setHidden(hidden: boolean): void;\n  setPaused(paused: boolean): void;\n  running(): boolean;\n};\n\nexport const createStopwatch = (\n  clock: Clock,\n  initial: {\n    readonly elapsedMs: number;\n    readonly started: boolean;\n    readonly finished: boolean;\n    readonly hidden: boolean;\n  },\n): Stopwatch => {\n  let banked = initial.elapsedMs;\n  let since: number | null = null;\n  let started = initial.started;\n  let finished = initial.finished;\n  let hidden = initial.hidden;\n  let paused = false;\n\n  const shouldRun = (): boolean => started && !finished && !hidden && !paused;\n  const sync = (): void => {\n    const run = shouldRun();\n    if (run && since === null) since = clock.now();\n    if (!run && since !== null) {\n      banked += Math.max(0, clock.now() - since);\n      since = null;\n    }\n  };\n  sync();\n\n  return {\n    elapsed: () => Math.round(banked + (since === null ? 0 : Math.max(0, clock.now() - since))),\n    start: () => {\n      started = true;\n      sync();\n    },\n    started: () => started,\n    restart: () => {\n      banked = 0;\n      since = null;\n      started = false;\n      finished = false;\n      sync();\n    },\n    finish: () => {\n      finished = true;\n      sync();\n    },\n    setHidden: (value) => {\n      hidden = value;\n      sync();\n    },\n    setPaused: (value) => {\n      paused = value;\n      sync();\n    },\n    running: () => since !== null,\n  };\n};\n"],"mappings":";AAqBA,IAAa,mBACX,OACA,YAMc;CACd,IAAI,SAAS,QAAQ;CACrB,IAAI,QAAuB;CAC3B,IAAI,UAAU,QAAQ;CACtB,IAAI,WAAW,QAAQ;CACvB,IAAI,SAAS,QAAQ;CACrB,IAAI,SAAS;CAEb,MAAM,kBAA2B,WAAW,CAAC,YAAY,CAAC,UAAU,CAAC;CACrE,MAAM,aAAmB;EACvB,MAAM,MAAM,UAAU;EACtB,IAAI,OAAO,UAAU,MAAM,QAAQ,MAAM,IAAI;EAC7C,IAAI,CAAC,OAAO,UAAU,MAAM;GAC1B,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,IAAI,KAAK;GACzC,QAAQ;EACV;CACF;CACA,KAAK;CAEL,OAAO;EACL,eAAe,KAAK,MAAM,UAAU,UAAU,OAAO,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI,IAAI,KAAK,EAAE;EAC1F,aAAa;GACX,UAAU;GACV,KAAK;EACP;EACA,eAAe;EACf,eAAe;GACb,SAAS;GACT,QAAQ;GACR,UAAU;GACV,WAAW;GACX,KAAK;EACP;EACA,cAAc;GACZ,WAAW;GACX,KAAK;EACP;EACA,YAAY,UAAU;GACpB,SAAS;GACT,KAAK;EACP;EACA,YAAY,UAAU;GACpB,SAAS;GACT,KAAK;EACP;EACA,eAAe,UAAU;CAC3B;AACF"}

package/dist/values.d.ts

@@ -0,0 +1,19 @@
+import { type GameError, type Json, type Result, type Validator } from '@joystyk/contracts';
+/**
+ * Decodes `value` with a Standard Schema. Runners decode on their ordered input path, so the
+ * schema must validate synchronously; an asynchronous schema fails with `AsyncSchema`.
+ */
+export declare const decode: <T>(schema: Validator<T>, value: unknown, what: string) => Result<T, GameError>;
+/**
+ * Freezes plain objects and arrays all the way down, so an accidental mutation throws.
+ * Anything else (typed arrays, class instances in a simulation's view) is left alone:
+ * freezing a typed array with elements throws.
+ */
+export declare const deepFreeze: <T>(value: T) => T;
+/** Deep equality for JSON values, ignoring key order. */
+export declare const jsonEqual: (a: Json | undefined, b: Json | undefined) => boolean;
+/** A deep copy through JSON, as a value would arrive from a worker or a socket. */
+export declare const jsonClone: <T extends Json>(value: T) => T;
+/** Builds an object without the keys whose value is undefined, so it stays JSON. */
+export declare const compact: <T extends Record<string, unknown>>(value: T) => T;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/values.js

@@ -0,0 +1,66 @@
+import { err, gameError, ok } from "@joystyk/contracts";
+//#region src/values.ts
+/**
+* Decodes `value` with a Standard Schema. Runners decode on their ordered input path, so the
+* schema must validate synchronously; an asynchronous schema fails with `AsyncSchema`.
+*/
+var decode = (schema, value, what) => {
+	let result;
+	try {
+		result = schema["~standard"].validate(value);
+	} catch (error) {
+		return err(gameError("InvalidInput", `The ${what} could not be read.`, { reason: String(error) }));
+	}
+	if (result instanceof Promise) {
+		result.catch(() => {});
+		return err(gameError("AsyncSchema", `The ${what} schema must validate synchronously.`));
+	}
+	if (result.issues !== void 0) {
+		const messages = result.issues.map((issue) => issue.message);
+		return err(gameError("InvalidInput", `The ${what} is not valid.`, { issues: messages }));
+	}
+	return ok(result.value);
+};
+var isPlain = (value) => {
+	if (Array.isArray(value)) return true;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+};
+/**
+* Freezes plain objects and arrays all the way down, so an accidental mutation throws.
+* Anything else (typed arrays, class instances in a simulation's view) is left alone:
+* freezing a typed array with elements throws.
+*/
+var deepFreeze = (value) => {
+	if (typeof value !== "object" || value === null || Object.isFrozen(value) || !isPlain(value)) return value;
+	Object.freeze(value);
+	for (const key of Object.keys(value)) deepFreeze(value[key]);
+	return value;
+};
+/** Deep equality for JSON values, ignoring key order. */
+var jsonEqual = (a, b) => {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((item, i) => jsonEqual(item, b[i]));
+	}
+	const ao = a;
+	const bo = b;
+	const keys = Object.keys(ao);
+	if (keys.length !== Object.keys(bo).length) return false;
+	return keys.every((key) => Object.hasOwn(bo, key) && jsonEqual(ao[key], bo[key]));
+};
+/** A deep copy through JSON, as a value would arrive from a worker or a socket. */
+var jsonClone = (value) => JSON.parse(JSON.stringify(value));
+/** Builds an object without the keys whose value is undefined, so it stays JSON. */
+var compact = (value) => {
+	const out = {};
+	for (const [key, item] of Object.entries(value)) if (item !== void 0) out[key] = item;
+	return out;
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+//#endregion
+export { compact, decode, deepFreeze, isRecord, jsonClone, jsonEqual };
+
+//# sourceMappingURL=values.js.map

package/dist/values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.js","names":[],"sources":["../src/values.ts"],"sourcesContent":["// Small value helpers the runners share: schema decoding, deep freezing, JSON equality.\nimport { err, gameError, ok, type GameError, type Json, type Result, type Validator } from '@joystyk/contracts';\n\n/**\n * Decodes `value` with a Standard Schema. Runners decode on their ordered input path, so the\n * schema must validate synchronously; an asynchronous schema fails with `AsyncSchema`.\n */\nexport const decode = <T>(schema: Validator<T>, value: unknown, what: string): Result<T, GameError> => {\n  let result: ReturnType<Validator<T>['~standard']['validate']>;\n  try {\n    result = schema['~standard'].validate(value);\n  } catch (error) {\n    return err(gameError('InvalidInput', `The ${what} could not be read.`, { reason: String(error) }));\n  }\n  if (result instanceof Promise) {\n    // Keep an unhandled rejection from surfacing; the value is rejected either way.\n    result.catch(() => {});\n    return err(gameError('AsyncSchema', `The ${what} schema must validate synchronously.`));\n  }\n  if (result.issues !== undefined) {\n    const messages = result.issues.map((issue) => issue.message);\n    return err(gameError('InvalidInput', `The ${what} is not valid.`, { issues: messages }));\n  }\n  return ok(result.value);\n};\n\nconst isPlain = (value: object): boolean => {\n  if (Array.isArray(value)) return true;\n  const proto: unknown = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n};\n\n/**\n * Freezes plain objects and arrays all the way down, so an accidental mutation throws.\n * Anything else (typed arrays, class instances in a simulation's view) is left alone:\n * freezing a typed array with elements throws.\n */\nexport const deepFreeze = <T>(value: T): T => {\n  if (typeof value !== 'object' || value === null || Object.isFrozen(value) || !isPlain(value)) return value;\n  Object.freeze(value);\n  for (const key of Object.keys(value)) deepFreeze((value as Record<string, unknown>)[key]);\n  return value;\n};\n\n/** Deep equality for JSON values, ignoring key order. */\nexport const jsonEqual = (a: Json | undefined, b: Json | undefined): boolean => {\n  if (a === b) return true;\n  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;\n  if (Array.isArray(a) || Array.isArray(b)) {\n    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;\n    return a.every((item, i) => jsonEqual(item, (b as readonly Json[])[i]));\n  }\n  const ao = a as { readonly [key: string]: Json };\n  const bo = b as { readonly [key: string]: Json };\n  const keys = Object.keys(ao);\n  if (keys.length !== Object.keys(bo).length) return false;\n  return keys.every((key) => Object.hasOwn(bo, key) && jsonEqual(ao[key], bo[key]));\n};\n\n/** A deep copy through JSON, as a value would arrive from a worker or a socket. */\nexport const jsonClone = <T extends Json>(value: T): T => JSON.parse(JSON.stringify(value)) as T;\n\n/** Builds an object without the keys whose value is undefined, so it stays JSON. */\nexport const compact = <T extends Record<string, unknown>>(value: T): T => {\n  const out: Record<string, unknown> = {};\n  for (const [key, item] of Object.entries(value)) if (item !== undefined) out[key] = item;\n  return out as T;\n};\n\nexport const isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n"],"mappings":";;;;;;AAOA,IAAa,UAAa,QAAsB,OAAgB,SAAuC;CACrG,IAAI;CACJ,IAAI;EACF,SAAS,OAAO,YAAY,CAAC,SAAS,KAAK;CAC7C,SAAS,OAAO;EACd,OAAO,IAAI,UAAU,gBAAgB,OAAO,KAAK,sBAAsB,EAAE,QAAQ,OAAO,KAAK,EAAE,CAAC,CAAC;CACnG;CACA,IAAI,kBAAkB,SAAS;EAE7B,OAAO,YAAY,CAAC,CAAC;EACrB,OAAO,IAAI,UAAU,eAAe,OAAO,KAAK,qCAAqC,CAAC;CACxF;CACA,IAAI,OAAO,WAAW,KAAA,GAAW;EAC/B,MAAM,WAAW,OAAO,OAAO,KAAK,UAAU,MAAM,OAAO;EAC3D,OAAO,IAAI,UAAU,gBAAgB,OAAO,KAAK,iBAAiB,EAAE,QAAQ,SAAS,CAAC,CAAC;CACzF;CACA,OAAO,GAAG,OAAO,KAAK;AACxB;AAEA,IAAM,WAAW,UAA2B;CAC1C,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO;CACjC,MAAM,QAAiB,OAAO,eAAe,KAAK;CAClD,OAAO,UAAU,OAAO,aAAa,UAAU;AACjD;;;;;;AAOA,IAAa,cAAiB,UAAgB;CAC5C,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAO,SAAS,KAAK,KAAK,CAAC,QAAQ,KAAK,GAAG,OAAO;CACrG,OAAO,OAAO,KAAK;CACnB,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GAAG,WAAY,MAAkC,IAAI;CACxF,OAAO;AACT;;AAGA,IAAa,aAAa,GAAqB,MAAiC;CAC9E,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,OAAO,MAAM,YAAY,OAAO,MAAM,YAAY,MAAM,QAAQ,MAAM,MAAM,OAAO;CACvF,IAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;EACxC,IAAI,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,OAAO;EAC5E,OAAO,EAAE,OAAO,MAAM,MAAM,UAAU,MAAO,EAAsB,EAAE,CAAC;CACxE;CACA,MAAM,KAAK;CACX,MAAM,KAAK;CACX,MAAM,OAAO,OAAO,KAAK,EAAE;CAC3B,IAAI,KAAK,WAAW,OAAO,KAAK,EAAE,CAAC,CAAC,QAAQ,OAAO;CACnD,OAAO,KAAK,OAAO,QAAQ,OAAO,OAAO,IAAI,GAAG,KAAK,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;AAClF;;AAGA,IAAa,aAA6B,UAAgB,KAAK,MAAM,KAAK,UAAU,KAAK,CAAC;;AAG1F,IAAa,WAA8C,UAAgB;CACzE,MAAM,MAA+B,CAAC;CACtC,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,KAAK,GAAG,IAAI,SAAS,KAAA,GAAW,IAAI,OAAO;CACpF,OAAO;AACT;AAEA,IAAa,YAAY,UACvB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK"}