@joystyk/session 0.0.0-stage → 0.2.0

package/dist/fixed-step.js

@@ -0,0 +1,280 @@
+import { compact, decode, isRecord, jsonEqual } from "./values.js";
+import { alwaysVisible } from "./ports.js";
+import { createPublisher } from "./publisher.js";
+import { defaultRestoreRng } from "./rngs.js";
+import { replaySimulation } from "./replay.js";
+import { isSeatInfo, loadSave } from "./saves.js";
+import { err, gameError, ok } from "@joystyk/contracts";
+//#region src/fixed-step.ts
+/** Starts a new real-time game. Fails when the config is invalid or `init` refuses it. */
+var createFixedStepRunner = (simulation, options) => {
+	if (options.seats.length === 0 || !options.seats.every((seat, i) => isSeatInfo(seat) && seat.id === i)) return err(gameError("InvalidSeats", "The seats must be numbered 0, 1, 2 and so on."));
+	const config = decode(simulation.schemas.config, options.config, "game setup");
+	if (!config.ok) return config;
+	const rng = (options.restoreRng ?? defaultRestoreRng)(options.seed);
+	const initialized = simulation.init(config.value, rng);
+	if (!initialized.ok) return initialized;
+	return ok(run(simulation, options, {
+		state: initialized.value,
+		rng,
+		tick: 0,
+		seats: options.seats,
+		log: {
+			config: config.value,
+			seed: options.seed,
+			inputs: []
+		}
+	}));
+};
+/**
+* Resumes a checkpoint. When the checkpoint carries a replay that still reproduces it, the
+* replay log continues; otherwise the game resumes without one.
+*/
+var restoreFixedStepRunner = (simulation, save, options) => {
+	const loaded = loadSave(save, options.manifest, simulation.rulesVersion, options.migrations, simulation.schemas.state);
+	if (!loaded.ok) return loaded;
+	const { envelope, state } = loaded.value;
+	const restoreRng = options.restoreRng ?? defaultRestoreRng;
+	if (envelope.tick === void 0) return err(gameError("SaveUnreadable", "This saved game could not be read.", { why: "tick" }));
+	let log = null;
+	const replay = envelope.replay;
+	if (isRecord(replay) && replay["layer"] === 3 && replay["endTick"] === envelope.tick && Array.isArray(replay["inputs"])) {
+		const config = decode(simulation.schemas.config, replay["config"], "saved setup");
+		const inputs = [];
+		let valid = config.ok;
+		for (const entry of replay["inputs"]) {
+			if (!isRecord(entry) || !Number.isInteger(entry["tick"])) {
+				valid = false;
+				break;
+			}
+			const input = decode(simulation.schemas.input, entry["input"], "saved input");
+			if (!input.ok) {
+				valid = false;
+				break;
+			}
+			inputs.push({
+				tick: entry["tick"],
+				input: input.value
+			});
+		}
+		if (valid && config.ok) {
+			const candidate = {
+				...replay,
+				config: config.value,
+				inputs
+			};
+			const replayed = replaySimulation(simulation, candidate, restoreRng);
+			if (replayed.ok && jsonEqual(replayed.value.state, state) && jsonEqual(replayed.value.rng, envelope.rng)) log = {
+				config: config.value,
+				seed: candidate.seed,
+				inputs
+			};
+		}
+	}
+	if (log === null) options.report?.(/* @__PURE__ */ new Error("The checkpoint has no usable replay."), "Restored a checkpoint without its replay.");
+	return ok(run(simulation, options, {
+		state,
+		rng: restoreRng(envelope.rng),
+		tick: envelope.tick,
+		seats: envelope.seats,
+		log
+	}));
+};
+var run = (simulation, options, start) => {
+	const { manifest, frames } = options;
+	const restoreRng = options.restoreRng ?? defaultRestoreRng;
+	const report = options.report ?? (() => {});
+	const visibility = options.visibility ?? alwaysVisible;
+	const stepMs = 1e3 / simulation.stepHz;
+	const maxSteps = Math.max(1, options.maxStepsPerFrame ?? Math.ceil(simulation.stepHz / 10));
+	let state = start.state;
+	let rng = start.rng;
+	let tick = start.tick;
+	const log = start.log;
+	let revision = 0;
+	let notice = null;
+	let hidden = visibility.hidden();
+	let userPaused = options.startPaused ?? false;
+	let broken = false;
+	let disposed = false;
+	let accumulator = 0;
+	let lastFrame = null;
+	let cancelFrame = null;
+	/** Inputs waiting for the next tick, in arrival order. */
+	let queued = [];
+	const finished = () => simulation.outcome(state) !== null;
+	const paused = () => hidden || userPaused;
+	const elapsedMs = () => Math.round(tick * stepMs);
+	const snapshot = (events) => {
+		const outcome = simulation.outcome(state);
+		return {
+			meta: {
+				connection: "local",
+				seat: options.seat === void 0 ? 0 : options.seat,
+				revision,
+				seats: start.seats,
+				outcome: outcome === null ? null : {
+					...outcome,
+					elapsedMs: elapsedMs()
+				},
+				safePoint: simulation.safePoint?.(state) ?? (outcome !== null || paused()),
+				notice
+			},
+			view: simulation.view(state),
+			tick,
+			paused: paused(),
+			events,
+			elapsedMs: elapsedMs()
+		};
+	};
+	const replay = () => log === null ? null : {
+		layer: 3,
+		gameId: manifest.id,
+		rulesVersion: simulation.rulesVersion,
+		config: log.config,
+		seed: log.seed,
+		inputs: log.inputs,
+		endTick: tick
+	};
+	const envelope = () => compact({
+		gameId: manifest.id,
+		build: manifest.versions.build,
+		rulesVersion: simulation.rulesVersion,
+		saveVersion: manifest.versions.save,
+		rng: rng.save(),
+		seats: start.seats,
+		state,
+		tick,
+		elapsedMs: elapsedMs(),
+		replay: replay() ?? void 0
+	});
+	let saving = Promise.resolve();
+	const persist = () => {
+		const store = options.storage;
+		if (store === void 0) return;
+		const save = envelope();
+		saving = saving.then(() => store.write(save)).catch((error) => report(error, "Saving the checkpoint failed."));
+	};
+	const publisher = createPublisher(snapshot([]), {
+		freeze: options.freeze ?? true,
+		report
+	});
+	const publish = (events) => {
+		revision += 1;
+		publisher.publish(snapshot(events));
+	};
+	const running = () => !disposed && !broken && !paused() && !finished();
+	const requestFrame = () => {
+		if (cancelFrame === null && running()) cancelFrame = frames.request(onFrame);
+	};
+	const stopFrames = () => {
+		cancelFrame?.();
+		cancelFrame = null;
+		lastFrame = null;
+		accumulator = 0;
+	};
+	const step = () => {
+		const inputs = queued;
+		queued = [];
+		for (const input of inputs) log?.inputs.push({
+			tick,
+			input
+		});
+		const result = simulation.step(state, inputs, rng);
+		state = result.state;
+		tick += 1;
+		return [...result.events ?? []];
+	};
+	function onFrame(now) {
+		cancelFrame = null;
+		if (!running()) return;
+		if (lastFrame === null) {
+			lastFrame = now;
+			return requestFrame();
+		}
+		accumulator += Math.max(0, now - lastFrame);
+		lastFrame = now;
+		let steps = Math.floor((accumulator + 1e-6) / stepMs);
+		if (steps > maxSteps) {
+			accumulator %= stepMs;
+			steps = maxSteps;
+		} else accumulator = Math.max(0, accumulator - steps * stepMs);
+		const events = [];
+		for (let i = 0; i < steps && !finished(); i += 1) {
+			const savedRng = rng.save();
+			const savedQueue = queued;
+			try {
+				events.push(...step());
+			} catch (error) {
+				rng = restoreRng(savedRng);
+				queued = savedQueue;
+				if (log !== null) log.inputs.splice(log.inputs.length - savedQueue.length);
+				broken = true;
+				report(error, `The simulation threw at tick ${tick}.`);
+				notice = {
+					code: "InternalError",
+					message: "Something went wrong. The game has stopped."
+				};
+				break;
+			}
+		}
+		if (steps > 0 || broken) {
+			if (!broken) notice = null;
+			if (finished() || broken || simulation.checkpoint?.(state, events) === true) persist();
+			publish(events);
+		}
+		requestFrame();
+	}
+	const setPaused = (next) => {
+		const was = paused();
+		if (next.hidden !== void 0) hidden = next.hidden;
+		if (next.user !== void 0) userPaused = next.user;
+		if (was === paused()) return;
+		if (paused()) {
+			stopFrames();
+			persist();
+		} else requestFrame();
+		publish([]);
+	};
+	const stopVisibility = visibility.subscribe((value) => {
+		if (!disposed) setPaused({ hidden: value });
+	});
+	requestFrame();
+	return {
+		get: () => publisher.get(),
+		subscribe: (listener) => publisher.subscribe(listener),
+		dispatch: (raw) => {
+			if (disposed) return;
+			if (!isRecord(raw)) return;
+			if (raw["kind"] === "pause" || raw["kind"] === "resume") return setPaused({ user: raw["kind"] === "pause" });
+			if (raw["kind"] !== "input") return;
+			const reject = (code, message) => {
+				notice = {
+					code,
+					message
+				};
+				publish([]);
+			};
+			if (finished() || broken) return reject("GameOver", "The game is over.");
+			if (paused()) return reject("Paused", "The game is paused.");
+			const input = decode(simulation.schemas.input, raw["input"], "input");
+			if (!input.ok) return reject(input.error.code, input.error.message);
+			queued.push(input.value);
+		},
+		dispose: () => {
+			if (disposed) return;
+			persist();
+			disposed = true;
+			stopFrames();
+			stopVisibility();
+			publisher.close();
+		},
+		alpha: () => Math.min(1, accumulator / stepMs),
+		save: envelope,
+		replay
+	};
+};
+//#endregion
+export { createFixedStepRunner, restoreFixedStepRunner };
+
+//# sourceMappingURL=fixed-step.js.map

package/dist/fixed-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixed-step.js","names":[],"sources":["../src/fixed-step.ts"],"sourcesContent":["// The Layer 3 scheduler: runs a fixed-step simulation against real time. It accumulates\n// frame time, runs as many ticks as that covers (with a cap on catch-up), assigns inputs to\n// the next tick in arrival order, pauses when the page is hidden, and publishes a snapshot\n// at frame cadence. Game time is ticks, so it is deterministic and replayable.\nimport {\n  err,\n  gameError,\n  ok,\n  type FixedStepSimulation,\n  type GameError,\n  type GameSession,\n  type Json,\n  type Migration,\n  type Notice,\n  type Result,\n  type Rng,\n  type RngState,\n  type SaveEnvelope,\n  type SeatId,\n  type SeatInfo,\n  type SimulationReplay,\n  type SimulationSnapshot,\n  type TickInput,\n} from '@joystyk/contracts';\nimport {\n  alwaysVisible,\n  type FrameScheduler,\n  type Reporter,\n  type RngFactory,\n  type SaveStore,\n  type Visibility,\n} from './ports.ts';\nimport { createPublisher } from './publisher.ts';\nimport { replaySimulation } from './replay.ts';\nimport { defaultRestoreRng } from './rngs.ts';\nimport { isSeatInfo, loadSave, type RunnerManifest } from './saves.ts';\nimport { compact, decode, isRecord, jsonEqual } from './values.ts';\n\n/** What the game's UI dispatches to a fixed-step runner. */\nexport type FixedStepInput<Input> =\n  { readonly kind: 'input'; readonly input: Input } | { readonly kind: 'pause' } | { readonly kind: 'resume' };\n\n/** The contract's `SimulationSnapshot` plus the tick events since the last snapshot. */\nexport type FixedStepSnapshot<View, Event> = SimulationSnapshot<View> & {\n  /** One-off events from the ticks since the previous snapshot, for sound and effects. */\n  readonly events: readonly Event[];\n  /** Active play time: ticks × step length, so a pause stops it. */\n  readonly elapsedMs: number;\n};\n\nexport interface FixedStepRunner<Input, View, Event> extends GameSession<\n  FixedStepSnapshot<View, Event>,\n  FixedStepInput<Input>\n> {\n  /**\n   * How far real time has run into the next tick, from 0 up to 1. A renderer may interpolate\n   * between the last two states with it; it never changes the simulation.\n   */\n  alpha(): number;\n  /** A checkpoint of the current tick. */\n  save(): SaveEnvelope;\n  /** The replay log so far, or null after restoring a checkpoint that had none. */\n  replay(): SimulationReplay | null;\n}\n\nexport type FixedStepPorts = {\n  readonly manifest: RunnerManifest;\n  /** Restores the random state. Default: the kit's `restoreRng`. */\n  readonly restoreRng?: RngFactory;\n  readonly frames: FrameScheduler;\n  readonly visibility?: Visibility;\n  /** Checkpoints go here on the simulation's request, pause, hide, outcome and dispose. */\n  readonly storage?: SaveStore;\n  /** The viewer. Default: seat 0. */\n  readonly seat?: SeatId | null;\n  /**\n   * The most ticks one frame may run. After a long stall the rest of the backlog is dropped\n   * instead of freezing the page. Default: a tenth of a second's worth (6 at 60 Hz).\n   */\n  readonly maxStepsPerFrame?: number;\n  /** Start paused, e.g. behind a \"Press to start\" screen. Default false. */\n  readonly startPaused?: boolean;\n  readonly freeze?: boolean;\n  readonly report?: Reporter;\n};\n\nexport type FixedStepOptions = FixedStepPorts & {\n  readonly seats: readonly SeatInfo[];\n  /** Decoded with the simulation's config schema. */\n  readonly config: unknown;\n  readonly seed: RngState;\n};\n\nexport type FixedStepRestoreOptions = FixedStepPorts & {\n  readonly migrations: readonly Migration[];\n};\n\ntype Start<State, Input, Config> = {\n  readonly state: State;\n  readonly rng: Rng;\n  readonly tick: number;\n  readonly seats: readonly SeatInfo[];\n  readonly log: { readonly config: Config; readonly seed: RngState; readonly inputs: TickInput<Input>[] } | null;\n};\n\n/** Starts a new real-time game. Fails when the config is invalid or `init` refuses it. */\nexport const createFixedStepRunner = <\n  State extends Json,\n  Input extends Json,\n  View,\n  Event extends Json,\n  Config extends Json,\n>(\n  simulation: FixedStepSimulation<State, Input, View, Event, Config>,\n  options: FixedStepOptions,\n): Result<FixedStepRunner<Input, View, Event>, GameError> => {\n  if (options.seats.length === 0 || !options.seats.every((seat, i) => isSeatInfo(seat) && seat.id === i)) {\n    return err(gameError('InvalidSeats', 'The seats must be numbered 0, 1, 2 and so on.'));\n  }\n  const config = decode(simulation.schemas.config, options.config, 'game setup');\n  if (!config.ok) return config;\n  const rng = (options.restoreRng ?? defaultRestoreRng)(options.seed);\n  const initialized = simulation.init(config.value, rng);\n  if (!initialized.ok) return initialized;\n  return ok(\n    run(simulation, options, {\n      state: initialized.value,\n      rng,\n      tick: 0,\n      seats: options.seats,\n      log: { config: config.value, seed: options.seed, inputs: [] },\n    }),\n  );\n};\n\n/**\n * Resumes a checkpoint. When the checkpoint carries a replay that still reproduces it, the\n * replay log continues; otherwise the game resumes without one.\n */\nexport const restoreFixedStepRunner = <\n  State extends Json,\n  Input extends Json,\n  View,\n  Event extends Json,\n  Config extends Json,\n>(\n  simulation: FixedStepSimulation<State, Input, View, Event, Config>,\n  save: unknown,\n  options: FixedStepRestoreOptions,\n): Result<FixedStepRunner<Input, View, Event>, GameError> => {\n  const loaded = loadSave(\n    save,\n    options.manifest,\n    simulation.rulesVersion,\n    options.migrations,\n    simulation.schemas.state,\n  );\n  if (!loaded.ok) return loaded;\n  const { envelope, state } = loaded.value;\n  const restoreRng = options.restoreRng ?? defaultRestoreRng;\n  if (envelope.tick === undefined)\n    return err(gameError('SaveUnreadable', 'This saved game could not be read.', { why: 'tick' }));\n  let log: Start<State, Input, Config>['log'] = null;\n  const replay: unknown = envelope.replay;\n  if (\n    isRecord(replay) &&\n    replay['layer'] === 3 &&\n    replay['endTick'] === envelope.tick &&\n    Array.isArray(replay['inputs'])\n  ) {\n    const config = decode(simulation.schemas.config, replay['config'], 'saved setup');\n    const inputs: TickInput<Input>[] = [];\n    let valid = config.ok;\n    for (const entry of replay['inputs'] as unknown[]) {\n      if (!isRecord(entry) || !Number.isInteger(entry['tick'])) {\n        valid = false;\n        break;\n      }\n      const input = decode(simulation.schemas.input, entry['input'], 'saved input');\n      if (!input.ok) {\n        valid = false;\n        break;\n      }\n      inputs.push({ tick: entry['tick'] as number, input: input.value });\n    }\n    if (valid && config.ok) {\n      const candidate = { ...(replay as unknown as SimulationReplay<Input, Config>), config: config.value, inputs };\n      const replayed = replaySimulation(simulation, candidate, restoreRng);\n      if (replayed.ok && jsonEqual(replayed.value.state, state) && jsonEqual(replayed.value.rng, envelope.rng)) {\n        log = { config: config.value, seed: candidate.seed, inputs };\n      }\n    }\n  }\n  if (log === null)\n    options.report?.(new Error('The checkpoint has no usable replay.'), 'Restored a checkpoint without its replay.');\n  return ok(\n    run(simulation, options, { state, rng: restoreRng(envelope.rng), tick: envelope.tick, seats: envelope.seats, log }),\n  );\n};\n\nconst run = <State extends Json, Input extends Json, View, Event extends Json, Config extends Json>(\n  simulation: FixedStepSimulation<State, Input, View, Event, Config>,\n  options: FixedStepPorts,\n  start: Start<State, Input, Config>,\n): FixedStepRunner<Input, View, Event> => {\n  const { manifest, frames } = options;\n  const restoreRng = options.restoreRng ?? defaultRestoreRng;\n  const report: Reporter = options.report ?? (() => {});\n  const visibility = options.visibility ?? alwaysVisible;\n  const stepMs = 1000 / simulation.stepHz;\n  const maxSteps = Math.max(1, options.maxStepsPerFrame ?? Math.ceil(simulation.stepHz / 10));\n\n  let state = start.state;\n  let rng = start.rng;\n  let tick = start.tick;\n  const log = start.log;\n  let revision = 0;\n  let notice: Notice | null = null;\n  let hidden = visibility.hidden();\n  let userPaused = options.startPaused ?? false;\n  let broken = false;\n  let disposed = false;\n  let accumulator = 0;\n  let lastFrame: number | null = null;\n  let cancelFrame: (() => void) | null = null;\n  /** Inputs waiting for the next tick, in arrival order. */\n  let queued: Input[] = [];\n\n  const finished = (): boolean => simulation.outcome(state) !== null;\n  const paused = (): boolean => hidden || userPaused;\n  const elapsedMs = (): number => Math.round(tick * stepMs);\n\n  const snapshot = (events: readonly Event[]): FixedStepSnapshot<View, Event> => {\n    const outcome = simulation.outcome(state);\n    return {\n      meta: {\n        connection: 'local',\n        seat: options.seat === undefined ? 0 : options.seat,\n        revision,\n        seats: start.seats,\n        outcome: outcome === null ? null : { ...outcome, elapsedMs: elapsedMs() },\n        safePoint: simulation.safePoint?.(state) ?? (outcome !== null || paused()),\n        notice,\n      },\n      view: simulation.view(state),\n      tick,\n      paused: paused(),\n      events,\n      elapsedMs: elapsedMs(),\n    };\n  };\n\n  const replay = (): SimulationReplay | null =>\n    log === null\n      ? null\n      : {\n          layer: 3,\n          gameId: manifest.id,\n          rulesVersion: simulation.rulesVersion,\n          config: log.config,\n          seed: log.seed,\n          inputs: log.inputs,\n          endTick: tick,\n        };\n\n  const envelope = (): SaveEnvelope =>\n    compact({\n      gameId: manifest.id,\n      build: manifest.versions.build,\n      rulesVersion: simulation.rulesVersion,\n      saveVersion: manifest.versions.save,\n      rng: rng.save(),\n      seats: start.seats,\n      state,\n      tick,\n      elapsedMs: elapsedMs(),\n      replay: replay() ?? undefined,\n    });\n\n  let saving: Promise<void> = Promise.resolve();\n  const persist = (): void => {\n    const store = options.storage;\n    if (store === undefined) return;\n    const save = envelope();\n    saving = saving\n      .then(() => store.write(save))\n      .catch((error: unknown) => report(error, 'Saving the checkpoint failed.'));\n  };\n\n  const publisher = createPublisher(snapshot([]), { freeze: options.freeze ?? true, report });\n  const publish = (events: readonly Event[]): void => {\n    revision += 1;\n    publisher.publish(snapshot(events));\n  };\n\n  const running = (): boolean => !disposed && !broken && !paused() && !finished();\n\n  const requestFrame = (): void => {\n    if (cancelFrame === null && running()) cancelFrame = frames.request(onFrame);\n  };\n\n  const stopFrames = (): void => {\n    cancelFrame?.();\n    cancelFrame = null;\n    // Resume starts from a fresh frame: hidden or paused time never becomes ticks.\n    lastFrame = null;\n    accumulator = 0;\n  };\n\n  const step = (): Event[] => {\n    const inputs = queued;\n    queued = [];\n    for (const input of inputs) log?.inputs.push({ tick, input });\n    const result = simulation.step(state, inputs, rng);\n    state = result.state;\n    tick += 1;\n    return [...(result.events ?? [])];\n  };\n\n  function onFrame(now: number): void {\n    cancelFrame = null;\n    if (!running()) return;\n    if (lastFrame === null) {\n      lastFrame = now;\n      return requestFrame();\n    }\n    accumulator += Math.max(0, now - lastFrame);\n    lastFrame = now;\n    // A small epsilon keeps 16.666… ms frames from landing a hair short of a tick.\n    let steps = Math.floor((accumulator + 1e-6) / stepMs);\n    if (steps > maxSteps) {\n      // Bounded catch-up: run the cap and drop the backlog, keeping the fraction.\n      accumulator %= stepMs;\n      steps = maxSteps;\n    } else {\n      accumulator = Math.max(0, accumulator - steps * stepMs);\n    }\n    const events: Event[] = [];\n    for (let i = 0; i < steps && !finished(); i += 1) {\n      const savedRng = rng.save();\n      const savedQueue = queued;\n      try {\n        events.push(...step());\n      } catch (error) {\n        // A throwing step is a bug: keep the last good tick and stop.\n        rng = restoreRng(savedRng);\n        queued = savedQueue;\n        if (log !== null) log.inputs.splice(log.inputs.length - savedQueue.length);\n        broken = true;\n        report(error, `The simulation threw at tick ${tick}.`);\n        notice = { code: 'InternalError', message: 'Something went wrong. The game has stopped.' };\n        break;\n      }\n    }\n    if (steps > 0 || broken) {\n      if (!broken) notice = null;\n      if (finished() || broken || simulation.checkpoint?.(state, events) === true) persist();\n      publish(events);\n    }\n    requestFrame();\n  }\n\n  const setPaused = (next: { readonly hidden?: boolean; readonly user?: boolean }): void => {\n    const was = paused();\n    if (next.hidden !== undefined) hidden = next.hidden;\n    if (next.user !== undefined) userPaused = next.user;\n    if (was === paused()) return;\n    if (paused()) {\n      stopFrames();\n      persist();\n    } else {\n      requestFrame();\n    }\n    publish([]);\n  };\n\n  const stopVisibility = visibility.subscribe((value) => {\n    if (!disposed) setPaused({ hidden: value });\n  });\n\n  requestFrame();\n\n  return {\n    get: () => publisher.get(),\n    subscribe: (listener) => publisher.subscribe(listener),\n    dispatch: (raw) => {\n      if (disposed) return;\n      if (!isRecord(raw)) return;\n      if (raw['kind'] === 'pause' || raw['kind'] === 'resume') return setPaused({ user: raw['kind'] === 'pause' });\n      if (raw['kind'] !== 'input') return;\n      const reject = (code: string, message: string): void => {\n        notice = { code, message };\n        publish([]);\n      };\n      if (finished() || broken) return reject('GameOver', 'The game is over.');\n      if (paused()) return reject('Paused', 'The game is paused.');\n      const input = decode(simulation.schemas.input, raw['input'], 'input');\n      if (!input.ok) return reject(input.error.code, input.error.message);\n      // Assigned to the next tick that runs, after everything already queued.\n      queued.push(input.value);\n    },\n    dispose: () => {\n      if (disposed) return;\n      persist();\n      disposed = true;\n      stopFrames();\n      stopVisibility();\n      publisher.close();\n    },\n    alpha: () => Math.min(1, accumulator / stepMs),\n    save: envelope,\n    replay,\n  };\n};\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { alwaysVisible, type AiRunner, type AiTask, type Clock, type FrameScheduler, type JobRunner, type Reporter, type RngFactory, type SaveStore, type Task, type Visibility, } from './ports.js';
+export { createLocalSession, inlineAi, restoreLocalSession, type LocalInput, type LocalMeta, type LocalMode, type LocalPorts, type LocalSession, type LocalSessionOptions, type LocalSnapshot, type RestoreOptions, type UndoBlock, } from './local.js';
+export { createFixedStepRunner, restoreFixedStepRunner, type FixedStepInput, type FixedStepOptions, type FixedStepPorts, type FixedStepRestoreOptions, type FixedStepRunner, type FixedStepSnapshot, } from './fixed-step.js';
+export { createRemoteSession, memoryTokens, reconnectDelay, type RemoteGame, type RemoteInput, type RemoteOffer, type RemoteRoom, type RemoteSession, type RemoteSessionOptions, type RemoteSnapshot, type RemoteSocket, type SocketEvents, type SocketFactory, type TokenStore, } from './remote.js';
+export { replayEngine, replaySimulation } from './replay.js';
+export { loadSave, parseEnvelope, type RunnerManifest } from './saves.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+import { alwaysVisible } from "./ports.js";
+import { replayEngine, replaySimulation } from "./replay.js";
+import { loadSave, parseEnvelope } from "./saves.js";
+import { createFixedStepRunner, restoreFixedStepRunner } from "./fixed-step.js";
+import { createLocalSession, inlineAi, restoreLocalSession } from "./local.js";
+import { createRemoteSession, memoryTokens, reconnectDelay } from "./remote.js";
+export { alwaysVisible, createFixedStepRunner, createLocalSession, createRemoteSession, inlineAi, loadSave, memoryTokens, parseEnvelope, reconnectDelay, replayEngine, replaySimulation, restoreFixedStepRunner, restoreLocalSession };

package/dist/local.d.ts

@@ -0,0 +1,130 @@
+import { type AssistKind, type AssistCounts, type DiscreteEngine, type EngineAi, type EngineReplay, type EngineSnapshot, type GameError, type GameSession, type Json, type Migration, type Result, type RngState, type SaveEnvelope, type SeatChange, type SeatId, type SeatInfo, type SessionMeta } from '@joystyk/contracts';
+import { type AiRunner, type Clock, type JobRunner, type Reporter, type RngFactory, type SaveStore, type Visibility } from './ports.js';
+import { type RunnerManifest } from './saves.js';
+/** The local modes. Rooms (P2P and server) have their own session clients. */
+export type LocalMode = 'solo' | 'ai' | 'pass-and-play' | 'daily';
+/**
+ * What the game's UI dispatches. A command comes from the viewer's seat unless it names one:
+ * in pass-and-play without a hand-off screen it may name any pending human seat, so two
+ * people at one device can make simultaneous moves in either order (gp-o2c); elsewhere a
+ * named seat must be the viewer's. The platform inputs (`resign`, `seat`) may name another
+ * human seat. `reveal` acknowledges the pass-and-play hand-off screen (D-31).
+ */
+export type LocalInput<Command> = {
+    readonly kind: 'command';
+    readonly command: Command;
+    readonly seat?: SeatId;
+} | {
+    readonly kind: 'resign';
+    readonly seat?: SeatId;
+} | {
+    readonly kind: 'seat';
+    readonly seat: SeatId;
+    readonly change: SeatChange;
+} | {
+    readonly kind: 'undo';
+} | {
+    readonly kind: 'reveal';
+} | {
+    readonly kind: 'pause';
+} | {
+    readonly kind: 'resume';
+};
+/** Session metadata plus the undo count and assistance, which results screens show (D-32). */
+export type LocalMeta = SessionMeta & {
+    /** Undos used in this game. The engine never sees undo, so only the runner can count it. */
+    readonly undosUsed: number;
+    /** The kinds of assistance used so far, in `ASSIST_KINDS` order. */
+    readonly assists: readonly AssistKind[];
+    readonly assistCounts: AssistCounts;
+};
+/** Why undo is unavailable right now, as a notice code. */
+export type UndoBlock = 'UndoNotAllowed' | 'HistoryUnavailable' | 'GameOver' | 'UndoLimit' | 'NothingToUndo' | 'UndoBarrier' | 'Paused';
+/** The local runner's snapshot: the contract's `EngineSnapshot` and what local play adds. */
+export type LocalSnapshot<View, Event> = EngineSnapshot<View, Event> & {
+    readonly meta: LocalMeta;
+    readonly mode: LocalMode;
+    /**
+     * Pass-and-play only, for games whose manifest sets `handoff` (D-31): the seat the device
+     * must pass to. While it is set, `meta.seat` is null and `view` is the spectator view, so
+     * nothing private shows; `reveal` ends it. Once the game is over it stays null, and so does
+     * `meta.seat`: the final board is the spectator's view.
+     */
+    readonly handoff: {
+        readonly seat: SeatId;
+        readonly name: string;
+    } | null;
+    readonly undo: {
+        readonly available: boolean;
+        readonly remaining: number | null;
+        readonly blockedBy: UndoBlock | null;
+    };
+    /** AI seats choosing a move right now. */
+    readonly thinking: readonly SeatId[];
+    readonly paused: boolean;
+    /** Active play time when this snapshot was published. For a live stopwatch, call `elapsedMs()`. */
+    readonly elapsedMs: number;
+};
+/** A local session: the contract's `GameSession` plus what the launcher needs for saves. */
+export interface LocalSession<Command, View, Event> extends GameSession<LocalSnapshot<View, Event>, LocalInput<Command>> {
+    /** Active play time right now. */
+    elapsedMs(): number;
+    /** The save envelope for the current position. */
+    save(): SaveEnvelope;
+    /** The replay log so far, or null when the history was lost (a save without a replay). */
+    replay(): EngineReplay | null;
+}
+/** Ports and settings shared by new and restored sessions. */
+export type LocalPorts<View> = {
+    readonly manifest: RunnerManifest;
+    readonly mode: LocalMode;
+    /** Restores the game's random state. Default: the kit's `restoreRng`. */
+    readonly restoreRng?: RngFactory;
+    readonly clock: Clock;
+    /**
+     * The viewer in solo, vs-AI and daily play; default: the first human seat. Null watches
+     * (every seat AI). Pass-and-play ignores it: the viewer follows the seat to act.
+     */
+    readonly seat?: SeatId | null;
+    /**
+     * Seed for the AI's own random source, kept apart from the game's so an AI can't predict
+     * shuffles. Pass a fresh one; the default forks one from the game's random state. A
+     * restored game continues the stream its save recorded (`aiRng`) and ignores this.
+     */
+    readonly aiSeed?: RngState;
+    /** How long the default AI runner waits before choosing, so players can follow. Default 500. */
+    readonly aiDelayMs?: number;
+    /**
+     * Chooses AI moves. Default: the engine's `ai.choose`, inline. Pass `workerAiRunner` when
+     * the manifest declares heavy AI; without one, the runner reports it and runs inline.
+     */
+    readonly ai?: AiRunner<View>;
+    readonly visibility?: Visibility;
+    readonly storage?: SaveStore;
+    readonly jobs?: JobRunner;
+    /** Deep-freeze snapshots. Default true; production builds may pass false. */
+    readonly freeze?: boolean;
+    readonly report?: Reporter;
+};
+export type LocalSessionOptions<View> = LocalPorts<View> & {
+    readonly seats: readonly SeatInfo[];
+    /** Decoded with the engine's config schema. */
+    readonly config: unknown;
+    readonly seed: RngState;
+};
+export type RestoreOptions<View> = LocalPorts<View> & {
+    readonly migrations: readonly Migration[];
+};
+/**
+ * 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`.
+ */
+export declare const inlineAi: <View, Command>(ai: EngineAi<View, Command>, clock: Clock, delayMs: number, restore?: RngFactory) => AiRunner<View>;
+/** Starts a new local game. Fails when the seats or config are invalid or `init` refuses them. */
+export declare const createLocalSession: <State extends Json, Command extends Json, View extends Json, Event extends Json, Config extends Json>(engine: DiscreteEngine<State, Command, View, Event, Config>, options: LocalSessionOptions<View>) => Result<LocalSession<Command, View, Event>, GameError>;
+/**
+ * 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`.
+ */
+export declare const restoreLocalSession: <State extends Json, Command extends Json, View extends Json, Event extends Json, Config extends Json>(engine: DiscreteEngine<State, Command, View, Event, Config>, save: unknown, options: RestoreOptions<View>) => Result<LocalSession<Command, View, Event>, GameError>;