@v12-engine/engine 0.1.1 → 0.4.0

package/dist/session/can.js

@@ -0,0 +1,26 @@
+//#region src/session/can.ts
+/** A session's pace, as `SessionCan.pace`: its own `speed` and `advance` */
+function paceOf(session) {
+	return {
+		get speed() {
+			return session.speed;
+		},
+		set speed(speed) {
+			session.speed = speed;
+		},
+		advance: (ticks) => session.advance(ticks)
+	};
+}
+/** A session's saves, as `SessionCan.saves`: its own `save` and `checkpoint` */
+function savesOf(session) {
+	return {
+		save: () => session.save(),
+		get checkpoint() {
+			return session.checkpoint;
+		}
+	};
+}
+//#endregion
+export { paceOf, savesOf };
+
+//# sourceMappingURL=can.js.map

package/dist/session/can.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"can.js","names":[],"sources":["../../src/session/can.ts"],"sourcesContent":["/**\n * What a session can do besides being a seat (`SessionCan`), made of its own members: what a game played in this page\n * gives, in its thread (`LocalSession`) or in a worker (`WorkerSession`)\n */\nimport type { WorldSave } from '#engine/save'\nimport type { Message } from '#engine/messages'\nimport type { SessionPace, SessionSaves } from './protocol'\n\n/** A session's pace, as `SessionCan.pace`: its own `speed` and `advance` */\nexport function paceOf(session: { speed: number; advance(ticks?: number): void }): SessionPace {\n\treturn {\n\t\tget speed() {\n\t\t\treturn session.speed\n\t\t},\n\t\tset speed(speed: number) {\n\t\t\tsession.speed = speed\n\t\t},\n\t\tadvance: (ticks) => session.advance(ticks)\n\t}\n}\n\n/** A session's saves, as `SessionCan.saves`: its own `save` and `checkpoint` */\nexport function savesOf(session: { save(): Promise<WorldSave>; readonly checkpoint?: { label: Message; save: WorldSave } }): SessionSaves {\n\treturn {\n\t\tsave: () => session.save(),\n\t\tget checkpoint() {\n\t\t\treturn session.checkpoint\n\t\t}\n\t}\n}\n"],"mappings":";;AASA,SAAgB,OAAO,SAAwE;CAC9F,OAAO;EACN,IAAI,QAAQ;GACX,OAAO,QAAQ;EAChB;EACA,IAAI,MAAM,OAAe;GACxB,QAAQ,QAAQ;EACjB;EACA,UAAU,UAAU,QAAQ,QAAQ,KAAK;CAC1C;AACD;;AAGA,SAAgB,QAAQ,SAAkH;CACzI,OAAO;EACN,YAAY,QAAQ,KAAK;EACzB,IAAI,aAAa;GAChB,OAAO,QAAQ;EAChB;CACD;AACD"}

package/dist/session/commandReplay.d.ts

@@ -1,5 +1,5 @@
 import { type Apart } from '#engine/determinism';
-import { type GameModule } from '#engine/game';
+import { type Rules } from '#engine/game';
 import type { Component } from '#engine/components';
 import type { IssuedCommand } from '#engine/commands';
 import type { PlayerId } from '#engine/entity';
@@ -10,7 +10,9 @@ import type { World } from '#engine/world';
  * @beta
  */
 export interface CommandReplay {
+    /** The replay's file format, always 2; another is not read */
     format: 2;
+    /** Marks this replay as one of commands, as opposed to a recording of snapshots */
     kind: 'commands';
     /** The game it is of, by id: a page plays back what it has */
     game: string;
@@ -18,9 +20,11 @@ export interface CommandReplay {
     rules: string;
     /** Whose side it is seen from when played back; any side can be, as all of the game is in it */
     player: PlayerId;
+    /** Ticks per second the game ran at, for the replay to run at again */
     tickRate: number;
     /** The tick it started and ended at */
     from: number;
+    /** The tick the recording ended at */
     to: number;
     /** The world as it was at `from`, as a save (`encodeSave`) */
     start: string;
@@ -48,7 +52,9 @@ export interface CommandReplay {
  * @beta
  */
 export interface CommandRecorder {
+    /** How many ticks have been recorded so far */
     readonly ticks: number;
+    /** Ends the recording and gives back the `CommandReplay` of what was recorded */
     stop(): CommandReplay;
 }
 /**
@@ -74,7 +80,7 @@ export declare function recordCommands(world: World, options: {
  * @beta
  */
 export declare function runReplay(replay: CommandReplay, options: {
-    game: GameModule;
+    rules: Rules;
     to?: number;
     from?: number;
     components?: readonly Component<unknown, unknown>[];

package/dist/session/commandReplay.js

@@ -0,0 +1,293 @@
+import { decodeSave, encodeSave, saveWorld } from "../save.js";
+import { loadWorld } from "../game.js";
+import { SessionHost, connect } from "./remote.js";
+import { saveDifference, worldFingerprint } from "../determinism.js";
+//#region src/session/commandReplay.ts
+/**
+* Replays of commands (determinism D4): a game kept as where it started and what its players told it, tick by tick,
+* and played back by running it again. A world comes out the same from the same start and the same commands (D1–D3),
+* so this is the whole game, from every side, in a few kilobytes where the frames a watcher was sent are megabytes.
+* Its hash every few seconds is kept with it: played back, a hash that differs says the game came apart there (rules
+* changed since, or a system a save does not bring back), and from then it is the game the rules make now
+*/
+/**
+* Records a world from now as its start and the commands given to it from outside a tick (the players', by a
+* session or a server; a computer player's are its system's, which runs again), with its hash every `every` ticks
+* (300, ten seconds at 30 a second, when left out). Starting takes a save of the world, as saving does (it puts the
+* crowd back as a load does)
+*
+* @beta
+*/
+function recordCommands(world, options) {
+	const every = options.every ?? 300;
+	const checkpointEvery = options.checkpoints ?? 0;
+	const checkpoints = [];
+	const from = world.tick;
+	const start = encodeSave(saveWorld(world));
+	const commands = [];
+	const saves = [];
+	const hashes = [];
+	const unwatch = world.watch({
+		command: (command) => void commands.push([world.tick, structuredClone(command)]),
+		saved: () => void saves.push(world.tick),
+		stepped: () => {
+			if ((world.tick - from) % every === 0) hashes.push([world.tick, worldFingerprint(world)]);
+			if (checkpointEvery > 0 && (world.tick - from) % checkpointEvery === 0) checkpoints.push([world.tick, encodeSave(saveWorld(world))]);
+		}
+	});
+	let replay;
+	return {
+		get ticks() {
+			return world.tick - from;
+		},
+		stop() {
+			if (replay) return replay;
+			unwatch();
+			replay = {
+				format: 2,
+				kind: "commands",
+				game: world.registry.game,
+				rules: world.registry.hash,
+				player: options.player,
+				tickRate: world.tickRate,
+				from,
+				to: world.tick,
+				start,
+				commands,
+				saves,
+				hashes,
+				...checkpoints.length && { checkpoints },
+				...world.debugPlayers.size > 0 && { debug: [...world.debugPlayers] }
+			};
+			return replay;
+		}
+	};
+}
+/**
+* A replay of commands run again, to its end or a tick, with no screen: the world as it is then, the first tick whose
+* hash differs from the one kept (none when all were the same), and what differed first at the first checkpoint
+* (`recordCommands`' `checkpoints`) where the world was not the one recorded: the entity and its field
+* (`entities[id 11].pos.x`), and what each held. A replay with no checkpoints says the tick alone. What a test of a
+* replay, and a server checking one, use
+*
+* @beta
+*/
+async function runReplay(replay, options) {
+	const run = await replayRun(replay, options.rules, options.from, options.components);
+	run.stepTo(options.to ?? replay.to);
+	return {
+		world: run.world,
+		apart: run.apart,
+		difference: run.difference
+	};
+}
+/**
+* `components`: those the app kept in the world recorded beside the game's (`CreateWorldOptions.components`: where the
+* screen was played from), without which its saves do not load
+*/
+async function replayRun(replay, game, at = replay.from, components, navigation) {
+	let checkpoint = [replay.from, replay.start];
+	for (const kept of replay.checkpoints ?? []) if (kept[0] <= at && kept[0] > checkpoint[0]) checkpoint = kept;
+	const [startTick, save0] = checkpoint;
+	const world = await loadWorld(decodeSave(save0), {
+		rules: game,
+		anyVersion: true,
+		components,
+		...navigation && { navigation: { builds: navigation } }
+	});
+	for (const player of replay.debug ?? []) world.debugPlayers.add(player);
+	let command = replay.commands.findIndex(([tick]) => tick >= startTick);
+	if (command < 0) command = replay.commands.length;
+	let save = replay.saves.findIndex((tick) => tick > startTick);
+	if (save < 0) save = replay.saves.length;
+	let hash = replay.hashes.findIndex(([tick]) => tick > startTick);
+	if (hash < 0) hash = replay.hashes.length;
+	const ahead = (replay.checkpoints ?? []).filter(([tick]) => tick > startTick);
+	let next = 0;
+	let apart = null;
+	let difference = null;
+	const cameApart = (tick, what) => {
+		if (apart === null) apart = tick;
+		world.log.warn("replay", `The replay comes apart at tick ${tick}${what ?? ""}: the game is played on as these rules play it`, { tick });
+	};
+	return {
+		world,
+		get apart() {
+			return apart;
+		},
+		get difference() {
+			return difference;
+		},
+		stepTo(target, deadline = Infinity) {
+			let steps = 0;
+			while (world.tick < Math.min(target, replay.to) && !world.failure) {
+				if (++steps % 8 === 0 && performance.now() > deadline) return false;
+				while (command < replay.commands.length && replay.commands[command][0] <= world.tick) world.issue(structuredClone(replay.commands[command++][1]));
+				while (save < replay.saves.length && replay.saves[save] <= world.tick) {
+					saveWorld(world);
+					save++;
+				}
+				world.step();
+				while (hash < replay.hashes.length && replay.hashes[hash][0] < world.tick) hash++;
+				if (hash < replay.hashes.length && replay.hashes[hash][0] === world.tick) {
+					if (apart === null && worldFingerprint(world) !== replay.hashes[hash][1]) cameApart(world.tick);
+					hash++;
+				}
+				while (next < ahead.length && ahead[next][0] < world.tick) next++;
+				if (difference === null && next < ahead.length && ahead[next][0] === world.tick) {
+					const now = decodeSave(encodeSave(saveWorld(world, { reseat: false })));
+					const found = saveDifference(decodeSave(ahead[next][1]), now, world.registry);
+					if (found) {
+						difference = {
+							tick: world.tick,
+							...found
+						};
+						cameApart(world.tick, `, first at ${found.path} (${JSON.stringify(found.a)} recorded, ${JSON.stringify(found.b)} now)`);
+					}
+					next++;
+				}
+			}
+			return true;
+		}
+	};
+}
+/**
+* Two ends of a connection in the page, each message given to the other end once what runs now is done (a microtask):
+* in order, with no clock, and never inside the call that sent it
+*/
+function pair() {
+	const end = () => {
+		let handler = () => {};
+		let open = true;
+		const transport = {
+			send: (message) => {
+				if (open) queueMicrotask(() => other(transport).deliver(message));
+			},
+			onMessage: (on) => void (handler = on),
+			onClose: () => {},
+			close: () => void (open = false),
+			deliver: (message) => {
+				if (open) handler(message);
+			}
+		};
+		return transport;
+	};
+	const a = end();
+	const b = end();
+	const other = (one) => one === a ? b : a;
+	return [a, b];
+}
+/** How often a replay being played looks whether its game is due a tick, a second */
+var LOOKS = 30;
+/**
+* Milliseconds of a look a replay being played spends running its game on, at most: what a seek has to catch up on
+* (minute 15 is 27,000 ticks from the start) is run a slice a look, the page drawn between them
+*
+* @beta
+*/
+var REPLAY_SLICE = 12;
+/**
+* Plays a replay of commands as a watcher's session: its world run again, `speed` times as fast, and served to the
+* session as a host serves one who watches (`SessionHost`), from `player`'s side, or `options.player`'s. A moment
+* asked for (`at`, `skipTo`) is run to a slice a look (`REPLAY_SLICE`), from the last checkpoint before it
+* (`recordCommands`' `checkpoints`) where it is behind: going back starts the world again from there, and the session
+* takes it up where it is (`RemoteSession.resume`). `behind` is how many ticks are still to run to it. `apart` is the
+* tick it came apart from the game recorded at, if it did, and `difference` what differed first at the first
+* checkpoint the world was not the one recorded (`runReplay`)
+*
+* @internal
+*/
+function playCommands(replay, options) {
+	let run;
+	let host;
+	let timer;
+	let stopped = false;
+	const within = (tick) => Math.min(Math.max(tick, replay.from), replay.to);
+	let due = within(options.at ?? replay.from);
+	/** The world made again for a moment behind it, while it is made */
+	let going;
+	const watcher = options.player ?? replay.player;
+	/** A host for a world, with the watcher's end of a connection to it: the welcome goes out at once */
+	const serve = (world) => {
+		const [served, watching] = pair();
+		const serving = new SessionHost(world, {
+			sendRate: 10,
+			dropSilentAfter: Infinity
+		});
+		serving.connect(watcher, served, {
+			readOnly: true,
+			observer: true
+		});
+		return {
+			serving,
+			watching
+		};
+	};
+	const made = replayRun(replay, options.rules, due, options.components, options.navigation).then((first) => {
+		run = first;
+		const { serving, watching } = serve(first.world);
+		host = serving;
+		return connect(watching, { rules: options.rules });
+	});
+	/** Back to a moment before the world: made again from the last checkpoint before it, and the session taken there */
+	const rewind = (session, to) => {
+		going = replayRun(replay, options.rules, to, options.components, options.navigation).then((again) => {
+			if (stopped) return again.world.dispose();
+			const { serving, watching } = serve(again.world);
+			const resumed = session.resume(watching);
+			host?.dispose();
+			run?.world.dispose();
+			run = again;
+			host = serving;
+			return resumed;
+		}).catch((error) => run?.world.log.warn("replay", "The replay could not go back", { error: String(error) })).finally(() => going = void 0);
+	};
+	const player = {
+		session: made.then((session) => {
+			if (stopped) return session;
+			let last = performance.now();
+			timer = setInterval(() => {
+				const now = performance.now();
+				const seconds = (now - last) / 1e3;
+				last = now;
+				if (going || !run) return;
+				if (Math.floor(due) < run.world.tick) return rewind(session, Math.floor(due));
+				if (run.world.tick >= Math.floor(due)) due = Math.min(due + seconds * replay.tickRate * player.speed, replay.to);
+				run.stepTo(Math.floor(due), now + 12);
+				host.publish(seconds);
+			}, 1e3 / LOOKS);
+			return session;
+		}),
+		get tick() {
+			return run?.world.tick ?? replay.from;
+		},
+		speed: 1,
+		skipTo(tick) {
+			due = within(tick);
+		},
+		get behind() {
+			if (going) return Math.max(Math.floor(due) - replay.from, 1);
+			return Math.max(Math.floor(due) - (run?.world.tick ?? replay.from), 0);
+		},
+		get ended() {
+			return (run?.world.tick ?? replay.from) >= replay.to;
+		},
+		get apart() {
+			return run?.apart ?? null;
+		},
+		get difference() {
+			return run?.difference ?? null;
+		},
+		stop() {
+			stopped = true;
+			clearInterval(timer);
+			host?.dispose();
+			run?.world.dispose();
+		}
+	};
+	return player;
+}
+//#endregion
+export { REPLAY_SLICE, playCommands, recordCommands, runReplay };
+
+//# sourceMappingURL=commandReplay.js.map

package/dist/session/commandReplay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandReplay.js","names":[],"sources":["../../src/session/commandReplay.ts"],"sourcesContent":["/**\n * Replays of commands (determinism D4): a game kept as where it started and what its players told it, tick by tick,\n * and played back by running it again. A world comes out the same from the same start and the same commands (D1–D3),\n * so this is the whole game, from every side, in a few kilobytes where the frames a watcher was sent are megabytes.\n * Its hash every few seconds is kept with it: played back, a hash that differs says the game came apart there (rules\n * changed since, or a system a save does not bring back), and from then it is the game the rules make now\n */\nimport { decodeSave, encodeSave, saveWorld } from '#engine/save'\nimport { type Apart, saveDifference, worldFingerprint } from '#engine/determinism'\nimport { type Rules, loadWorld } from '#engine/game'\nimport type { NavigationBuilds } from '#engine/navigation/builds'\nimport type { Component } from '#engine/components'\nimport type { IssuedCommand } from '#engine/commands'\nimport type { PlayerId } from '#engine/entity'\nimport type { World } from '#engine/world'\nimport { connect, type RemoteSession, SessionHost, type Transport } from './remote'\n\n/**\n * A game recorded as its start and its commands (`recordGame`'s `kind: 'commands'`), to run again (`playReplay`)\n *\n * @beta\n */\nexport interface CommandReplay {\n\t/** The replay's file format, always 2; another is not read */\n\tformat: 2\n\t/** Marks this replay as one of commands, as opposed to a recording of snapshots */\n\tkind: 'commands'\n\t/** The game it is of, by id: a page plays back what it has */\n\tgame: string\n\t/** The rules it was played with exactly (`registry.hash`): other rules may play it otherwise */\n\trules: string\n\t/** Whose side it is seen from when played back; any side can be, as all of the game is in it */\n\tplayer: PlayerId\n\t/** Ticks per second the game ran at, for the replay to run at again */\n\ttickRate: number\n\t/** The tick it started and ended at */\n\tfrom: number\n\t/** The tick the recording ended at */\n\tto: number\n\t/** The world as it was at `from`, as a save (`encodeSave`) */\n\tstart: string\n\t/** What its players told it, each at the tick it was given at, before that tick ran */\n\tcommands: [tick: number, command: IssuedCommand][]\n\t/** The ticks it was saved at: a save puts the crowd back as a load does (D2), so playing back does it there too */\n\tsaves: number[]\n\t/** The world's fingerprint (`worldFingerprint`) every `every` ticks, to tell where a game played back came apart */\n\thashes: [tick: number, hash: string][]\n\t/**\n\t * The world as it was every so many ticks (`recordCommands`' `checkpoints`), as saves: a replay played from a moment\n\t * starts from the last one before it, not from its start. None in a replay made before there were any @beta\n\t */\n\tcheckpoints?: [tick: number, save: string][]\n\t/**\n\t * The players who could use the debug commands as it was recorded (`World.debugPlayers`, which no save keeps): played\n\t * back, they may again, so a game whose cheats were used (the editor's Play here, its map edits pushed) comes to the\n\t * same. None when left out\n\t */\n\tdebug?: PlayerId[]\n}\n\n/**\n * A game being recorded as its commands\n *\n * @beta\n */\nexport interface CommandRecorder {\n\t/** How many ticks have been recorded so far */\n\treadonly ticks: number\n\t/** Ends the recording and gives back the `CommandReplay` of what was recorded */\n\tstop(): CommandReplay\n}\n\n/**\n * Records a world from now as its start and the commands given to it from outside a tick (the players', by a\n * session or a server; a computer player's are its system's, which runs again), with its hash every `every` ticks\n * (300, ten seconds at 30 a second, when left out). Starting takes a save of the world, as saving does (it puts the\n * crowd back as a load does)\n *\n * @beta\n */\nexport function recordCommands(world: World, options: { player: PlayerId; every?: number; checkpoints?: number }): CommandRecorder {\n\tconst every = options.every ?? 300\n\t// a save of the world every so many ticks, to play from a moment without running all before it: none when not asked\n\t// (a save of a full melee is a megabyte, where the whole replay without is a few hundred kilobytes)\n\tconst checkpointEvery = options.checkpoints ?? 0\n\tconst checkpoints: [tick: number, save: string][] = []\n\tconst from = world.tick\n\t// a save to start from: it puts the crowd back as loading it does, so the two go on the same from here\n\tconst start = encodeSave(saveWorld(world))\n\tconst commands: CommandReplay['commands'] = []\n\tconst saves: number[] = []\n\tconst hashes: CommandReplay['hashes'] = []\n\tconst unwatch = world.watch({\n\t\tcommand: (command) => void commands.push([world.tick, structuredClone(command)]),\n\t\tsaved: () => void saves.push(world.tick),\n\t\tstepped: () => {\n\t\t\tif ((world.tick - from) % every === 0) hashes.push([world.tick, worldFingerprint(world)])\n\t\t\t// taken as a save is: played back, a save is taken at that tick too, so the game goes on the same\n\t\t\tif (checkpointEvery > 0 && (world.tick - from) % checkpointEvery === 0) checkpoints.push([world.tick, encodeSave(saveWorld(world))])\n\t\t}\n\t})\n\tlet replay: CommandReplay | undefined\n\treturn {\n\t\tget ticks() {\n\t\t\treturn world.tick - from\n\t\t},\n\t\tstop() {\n\t\t\tif (replay) return replay\n\t\t\tunwatch()\n\t\t\treplay = {\n\t\t\t\tformat: 2,\n\t\t\t\tkind: 'commands',\n\t\t\t\tgame: world.registry.game,\n\t\t\t\trules: world.registry.hash,\n\t\t\t\tplayer: options.player,\n\t\t\t\ttickRate: world.tickRate,\n\t\t\t\tfrom,\n\t\t\t\tto: world.tick,\n\t\t\t\tstart,\n\t\t\t\tcommands,\n\t\t\t\tsaves,\n\t\t\t\thashes,\n\t\t\t\t...(checkpoints.length && { checkpoints }),\n\t\t\t\t...(world.debugPlayers.size > 0 && { debug: [...world.debugPlayers] })\n\t\t\t}\n\t\t\treturn replay\n\t\t}\n\t}\n}\n\n/**\n * A replay of commands run again, to its end or a tick, with no screen: the world as it is then, the first tick whose\n * hash differs from the one kept (none when all were the same), and what differed first at the first checkpoint\n * (`recordCommands`' `checkpoints`) where the world was not the one recorded: the entity and its field\n * (`entities[id 11].pos.x`), and what each held. A replay with no checkpoints says the tick alone. What a test of a\n * replay, and a server checking one, use\n *\n * @beta\n */\nexport async function runReplay(\n\treplay: CommandReplay,\n\toptions: { rules: Rules; to?: number; from?: number; components?: readonly Component<unknown, unknown>[] }\n): Promise<{ world: World; apart: number | null; difference: Apart | null }> {\n\tconst run = await replayRun(replay, options.rules, options.from, options.components)\n\trun.stepTo(options.to ?? replay.to)\n\treturn { world: run.world, apart: run.apart, difference: run.difference }\n}\n\n/** A replay of commands being run: its world, stepped on to a tick with what the replay says given at each */\ninterface ReplayRun {\n\treadonly world: World\n\t/** The first tick whose hash differed from the replay's, or whose checkpoint did, or null */\n\treadonly apart: number | null\n\t/** What differed first at the first checkpoint the world was not the one recorded at, or null */\n\treadonly difference: Apart | null\n\t/** Runs the world on to a tick, or until `deadline` (`performance.now()`'s) is past: whether it got there */\n\tstepTo(tick: number, deadline?: number): boolean\n}\n\n/**\n * `components`: those the app kept in the world recorded beside the game's (`CreateWorldOptions.components`: where the\n * screen was played from), without which its saves do not load\n */\nasync function replayRun(\n\treplay: CommandReplay,\n\tgame: Rules,\n\tat = replay.from,\n\tcomponents?: readonly Component<unknown, unknown>[],\n\tnavigation?: NavigationBuilds\n): Promise<ReplayRun> {\n\t// from the last checkpoint at or before the moment asked for, else from the start\n\tlet checkpoint: [number, string] = [replay.from, replay.start]\n\tfor (const kept of replay.checkpoints ?? []) if (kept[0] <= at && kept[0] > checkpoint[0]) checkpoint = kept\n\tconst [startTick, save0] = checkpoint\n\tconst world = await loadWorld(decodeSave(save0), { rules: game, anyVersion: true, components, ...(navigation && { navigation: { builds: navigation } }) })\n\t// who could use the debug tools as it was recorded may again: what they did is done the same\n\tfor (const player of replay.debug ?? []) world.debugPlayers.add(player)\n\t// what came before it is in it: the commands given at its tick are still to come (it was taken after the step to it)\n\tlet command = replay.commands.findIndex(([tick]) => tick >= startTick)\n\tif (command < 0) command = replay.commands.length\n\tlet save = replay.saves.findIndex((tick) => tick > startTick)\n\tif (save < 0) save = replay.saves.length\n\tlet hash = replay.hashes.findIndex(([tick]) => tick > startTick)\n\tif (hash < 0) hash = replay.hashes.length\n\t// the checkpoints after the one started from, to compare the whole world with: the hash says when, these say what\n\tconst ahead = (replay.checkpoints ?? []).filter(([tick]) => tick > startTick)\n\tlet next = 0\n\tlet apart: number | null = null\n\tlet difference: Apart | null = null\n\tconst cameApart = (tick: number, what?: string) => {\n\t\tif (apart === null) apart = tick\n\t\tworld.log.warn('replay', `The replay comes apart at tick ${tick}${what ?? ''}: the game is played on as these rules play it`, { tick })\n\t}\n\treturn {\n\t\tworld,\n\t\tget apart() {\n\t\t\treturn apart\n\t\t},\n\t\tget difference() {\n\t\t\treturn difference\n\t\t},\n\t\tstepTo(target, deadline = Infinity) {\n\t\t\tlet steps = 0\n\t\t\twhile (world.tick < Math.min(target, replay.to) && !world.failure) {\n\t\t\t\t// the clock looked at every few steps: a step is a fraction of a millisecond, a look is not free\n\t\t\t\tif (++steps % 8 === 0 && performance.now() > deadline) return false\n\t\t\t\t// what was given before this tick ran, and a save taken then, as they were\n\t\t\t\twhile (command < replay.commands.length && replay.commands[command][0] <= world.tick)\n\t\t\t\t\tworld.issue(structuredClone(replay.commands[command++][1]))\n\t\t\t\twhile (save < replay.saves.length && replay.saves[save] <= world.tick) {\n\t\t\t\t\tsaveWorld(world)\n\t\t\t\t\tsave++\n\t\t\t\t}\n\t\t\t\tworld.step()\n\t\t\t\twhile (hash < replay.hashes.length && replay.hashes[hash][0] < world.tick) hash++\n\t\t\t\tif (hash < replay.hashes.length && replay.hashes[hash][0] === world.tick) {\n\t\t\t\t\tif (apart === null && worldFingerprint(world) !== replay.hashes[hash][1]) cameApart(world.tick)\n\t\t\t\t\thash++\n\t\t\t\t}\n\t\t\t\twhile (next < ahead.length && ahead[next][0] < world.tick) next++\n\t\t\t\tif (difference === null && next < ahead.length && ahead[next][0] === world.tick) {\n\t\t\t\t\t// the world as a file keeps it, beside the one recorded: the first thing they differ in, by entity and field\n\t\t\t\t\tconst now = decodeSave(encodeSave(saveWorld(world, { reseat: false })))\n\t\t\t\t\tconst found = saveDifference(decodeSave(ahead[next][1]), now, world.registry)\n\t\t\t\t\tif (found) {\n\t\t\t\t\t\tdifference = { tick: world.tick, ...found }\n\t\t\t\t\t\tcameApart(world.tick, `, first at ${found.path} (${JSON.stringify(found.a)} recorded, ${JSON.stringify(found.b)} now)`)\n\t\t\t\t\t}\n\t\t\t\t\tnext++\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn true\n\t\t}\n\t}\n}\n\n/**\n * Two ends of a connection in the page, each message given to the other end once what runs now is done (a microtask):\n * in order, with no clock, and never inside the call that sent it\n */\nfunction pair(): [Transport, Transport] {\n\tconst end = () => {\n\t\tlet handler: (message: string) => void = () => {}\n\t\tlet open = true\n\t\tconst transport: Transport & { deliver(message: string): void } = {\n\t\t\tsend: (message) => {\n\t\t\t\tif (open) queueMicrotask(() => other(transport).deliver(message))\n\t\t\t},\n\t\t\tonMessage: (on) => void (handler = on),\n\t\t\tonClose: () => {},\n\t\t\tclose: () => void (open = false),\n\t\t\tdeliver: (message) => {\n\t\t\t\tif (open) handler(message)\n\t\t\t}\n\t\t}\n\t\treturn transport\n\t}\n\tconst a = end()\n\tconst b = end()\n\tconst other = (one: typeof a) => (one === a ? b : a)\n\treturn [a, b]\n}\n\n/** How often a replay being played looks whether its game is due a tick, a second */\nconst LOOKS = 30\n\n/**\n * Milliseconds of a look a replay being played spends running its game on, at most: what a seek has to catch up on\n * (minute 15 is 27,000 ticks from the start) is run a slice a look, the page drawn between them\n *\n * @beta\n */\nexport const REPLAY_SLICE = 12\n\n/**\n * Plays a replay of commands as a watcher's session: its world run again, `speed` times as fast, and served to the\n * session as a host serves one who watches (`SessionHost`), from `player`'s side, or `options.player`'s. A moment\n * asked for (`at`, `skipTo`) is run to a slice a look (`REPLAY_SLICE`), from the last checkpoint before it\n * (`recordCommands`' `checkpoints`) where it is behind: going back starts the world again from there, and the session\n * takes it up where it is (`RemoteSession.resume`). `behind` is how many ticks are still to run to it. `apart` is the\n * tick it came apart from the game recorded at, if it did, and `difference` what differed first at the first\n * checkpoint the world was not the one recorded (`runReplay`)\n *\n * @internal\n */\nexport function playCommands(\n\treplay: CommandReplay,\n\toptions: { rules: Rules; at?: number; player?: PlayerId; components?: readonly Component<unknown, unknown>[]; navigation?: NavigationBuilds }\n): {\n\tsession: Promise<RemoteSession>\n\treadonly tick: number\n\tspeed: number\n\tskipTo(tick: number): void\n\treadonly behind: number\n\treadonly ended: boolean\n\treadonly apart: number | null\n\treadonly difference: Apart | null\n\tstop(): void\n} {\n\tlet run: ReplayRun | undefined\n\tlet host: SessionHost | undefined\n\tlet timer: ReturnType<typeof setInterval> | undefined\n\tlet stopped = false\n\tconst within = (tick: number) => Math.min(Math.max(tick, replay.from), replay.to)\n\tlet due = within(options.at ?? replay.from)\n\t/** The world made again for a moment behind it, while it is made */\n\tlet going: Promise<void> | undefined\n\tconst watcher = options.player ?? replay.player\n\t/** A host for a world, with the watcher's end of a connection to it: the welcome goes out at once */\n\tconst serve = (world: World) => {\n\t\tconst [served, watching] = pair()\n\t\t// its watcher is in this page and answers as the page draws: a seek runs on faster than frames come, and is no line gone silent\n\t\tconst serving = new SessionHost(world, { sendRate: 10, dropSilentAfter: Infinity })\n\t\tserving.connect(watcher, served, { readOnly: true, observer: true })\n\t\treturn { serving, watching }\n\t}\n\tconst made = replayRun(replay, options.rules, due, options.components, options.navigation).then((first) => {\n\t\trun = first\n\t\tconst { serving, watching } = serve(first.world)\n\t\thost = serving\n\t\treturn connect(watching, { rules: options.rules })\n\t})\n\t/** Back to a moment before the world: made again from the last checkpoint before it, and the session taken there */\n\tconst rewind = (session: RemoteSession, to: number) => {\n\t\tgoing = replayRun(replay, options.rules, to, options.components, options.navigation)\n\t\t\t.then((again) => {\n\t\t\t\tif (stopped) return again.world.dispose()\n\t\t\t\tconst { serving, watching } = serve(again.world)\n\t\t\t\t// the welcome is on its way: the session hears it as it takes the new end up\n\t\t\t\tconst resumed = session.resume(watching)\n\t\t\t\thost?.dispose()\n\t\t\t\trun?.world.dispose()\n\t\t\t\trun = again\n\t\t\t\thost = serving\n\t\t\t\treturn resumed\n\t\t\t})\n\t\t\t.catch((error: unknown) => run?.world.log.warn('replay', 'The replay could not go back', { error: String(error) }))\n\t\t\t.finally(() => (going = undefined))\n\t}\n\tconst player = {\n\t\tsession: made.then((session) => {\n\t\t\tif (stopped) return session\n\t\t\tlet last = performance.now()\n\t\t\ttimer = setInterval(() => {\n\t\t\t\tconst now = performance.now()\n\t\t\t\tconst seconds = (now - last) / 1000\n\t\t\t\tlast = now\n\t\t\t\tif (going || !run) return\n\t\t\t\t// a moment behind the world: it is made again for it\n\t\t\t\tif (Math.floor(due) < run.world.tick) return rewind(session, Math.floor(due))\n\t\t\t\t// played on from where it is once it is where it was asked to be; what is still to run, a slice a look\n\t\t\t\tif (run.world.tick >= Math.floor(due)) due = Math.min(due + seconds * replay.tickRate * player.speed, replay.to)\n\t\t\t\trun.stepTo(Math.floor(due), now + REPLAY_SLICE)\n\t\t\t\thost!.publish(seconds)\n\t\t\t}, 1000 / LOOKS)\n\t\t\treturn session\n\t\t}),\n\t\tget tick() {\n\t\t\treturn run?.world.tick ?? replay.from\n\t\t},\n\t\tspeed: 1,\n\t\tskipTo(tick: number) {\n\t\t\tdue = within(tick)\n\t\t},\n\t\tget behind() {\n\t\t\tif (going) return Math.max(Math.floor(due) - replay.from, 1)\n\t\t\treturn Math.max(Math.floor(due) - (run?.world.tick ?? replay.from), 0)\n\t\t},\n\t\tget ended() {\n\t\t\treturn (run?.world.tick ?? replay.from) >= replay.to\n\t\t},\n\t\tget apart() {\n\t\t\treturn run?.apart ?? null\n\t\t},\n\t\tget difference() {\n\t\t\treturn run?.difference ?? null\n\t\t},\n\t\tstop() {\n\t\t\tstopped = true\n\t\t\tclearInterval(timer)\n\t\t\thost?.dispose()\n\t\t\trun?.world.dispose()\n\t\t}\n\t}\n\treturn player\n}\n"],"mappings":"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"}

package/dist/session/debug.js

@@ -0,0 +1,151 @@
+import { isFiniteNumber } from "./protocol.js";
+import { EventLog, inspect, listWorld, setInspected } from "../inspect.js";
+//#region src/session/debug.ts
+/** Ticks between two lists of everything in the world: thousands of trees need not be listed every tick */
+var LIST_EVERY = 10;
+/**
+* The debug tools' view of a world running in the same page. What it hands out is worked out again whenever a
+* snapshot is, and at once when the client asks for something else: a remote one would wait for the answer instead
+*/
+var LocalDebug = class {
+	simulation;
+	inspection = null;
+	world = null;
+	target = null;
+	listedAt = -Infinity;
+	events = new EventLog();
+	constructor(simulation) {
+		this.simulation = simulation;
+	}
+	inspect(target) {
+		this.target = target;
+		this.refresh();
+	}
+	set(path, value) {
+		if (!this.target) return;
+		setInspected(this.simulation, this.target, path, value);
+		this.refresh();
+	}
+	get listing() {
+		return this.world !== null;
+	}
+	set listing(on) {
+		this.listedAt = -Infinity;
+		this.world = on ? listWorld(this.simulation) : null;
+	}
+	get logging() {
+		return this.events.attached;
+	}
+	set logging(on) {
+		if (on === this.logging) return;
+		if (on) this.events.attach(this.simulation);
+		else this.events.detach();
+	}
+	log() {
+		return this.events.entries;
+	}
+	clearLog() {
+		this.events.clear();
+	}
+	/** Works what is handed out again. The session does when a tick went by */
+	refresh() {
+		const world = this.simulation;
+		this.inspection = this.target && inspect(world, this.target);
+		if (this.world && world.tick - this.listedAt >= LIST_EVERY) {
+			this.world = listWorld(world);
+			this.listedAt = world.tick;
+		}
+	}
+	dispose() {
+		this.events.detach();
+	}
+};
+/** What is followed, as the wire says it: an entity, a player or the world, or nothing; anything else is not */
+function targetOf(value) {
+	if (value === null) return null;
+	if (typeof value !== "object") return void 0;
+	const target = value;
+	if (isFiniteNumber(target.entity)) return { entity: target.entity };
+	if (isFiniteNumber(target.player)) return { player: target.player };
+	if (target.world === true) return { world: true };
+}
+/**
+* Does what the debug tools of a screen asked of a world here (`DebugAsk`), each field checked first: it comes from
+* anyone who can send anything
+*/
+function askDebug(view, ask) {
+	const target = targetOf(ask.inspect);
+	if (target !== void 0) view.inspect(target);
+	const set = ask.set;
+	if (set && Array.isArray(set.path) && set.path.every((key) => typeof key === "string" || isFiniteNumber(key)) && (isFiniteNumber(set.value) || typeof set.value === "boolean")) view.set(set.path, set.value);
+	if (typeof ask.listing === "boolean") view.listing = ask.listing;
+	if (typeof ask.logging === "boolean") view.logging = ask.logging;
+	if (ask.clearLog === true) view.clearLog();
+}
+/**
+* The debug tools' view of a world elsewhere, a server's or a worker's: what it asked to follow, said over the wire
+* (`DebugAsk`), and what came back last (`take`)
+*/
+var RemoteDebug = class {
+	ask;
+	inspection = null;
+	world = null;
+	listed = false;
+	logged = false;
+	target = null;
+	events = [];
+	constructor(ask) {
+		this.ask = ask;
+	}
+	inspect(target) {
+		this.target = target;
+		if (!target) this.inspection = null;
+		this.ask({ inspect: target });
+	}
+	/** Asks again for all it follows: of a world it is served from anew (a session resumed, a replay gone back) */
+	askAgain() {
+		if (this.target || this.listed || this.logged) this.ask({
+			inspect: this.target,
+			listing: this.listed,
+			logging: this.logged
+		});
+	}
+	set(path, value) {
+		this.ask({ set: {
+			path,
+			value
+		} });
+	}
+	get listing() {
+		return this.listed;
+	}
+	set listing(on) {
+		this.listed = on;
+		if (!on) this.world = null;
+		this.ask({ listing: on });
+	}
+	get logging() {
+		return this.logged;
+	}
+	set logging(on) {
+		this.logged = on;
+		this.ask({ logging: on });
+	}
+	log() {
+		return this.events;
+	}
+	clearLog() {
+		this.events = [];
+		this.ask({ clearLog: true });
+	}
+	/** What the world's side said of what is followed */
+	take(said) {
+		this.inspection = said.inspection;
+		this.world = this.listed ? said.world : null;
+		if (this.logged) this.events = said.log;
+	}
+};
+//#endregion
+export { LocalDebug, RemoteDebug, askDebug };
+
+//# sourceMappingURL=debug.js.map

package/dist/session/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","names":[],"sources":["../../src/session/debug.ts"],"sourcesContent":["import { EventLog, inspect, type Inspection, type InspectTarget, listWorld, type LoggedEvent, setInspected, type WorldListing } from '#engine/inspect'\nimport type { World } from '#engine/world'\nimport { isFiniteNumber, type SessionDebug } from './protocol'\nimport type { DebugAsk } from './wire'\n\n/** Milliseconds between two words of the debug tools' view of a world elsewhere: a server's, a worker's */\nexport const DEBUG_EVERY = 100\n\n/** Ticks between two lists of everything in the world: thousands of trees need not be listed every tick */\nconst LIST_EVERY = 10\n\n/**\n * The debug tools' view of a world running in the same page. What it hands out is worked out again whenever a\n * snapshot is, and at once when the client asks for something else: a remote one would wait for the answer instead\n */\nexport class LocalDebug implements SessionDebug {\n\tinspection: Inspection | null = null\n\tworld: WorldListing | null = null\n\tprivate target: InspectTarget | null = null\n\tprivate listedAt = -Infinity\n\tprivate readonly events = new EventLog()\n\n\tconstructor(private readonly simulation: World) {}\n\n\tinspect(target: InspectTarget | null): void {\n\t\tthis.target = target\n\t\tthis.refresh()\n\t}\n\n\tset(path: (string | number)[], value: number | boolean): void {\n\t\tif (!this.target) return\n\t\tsetInspected(this.simulation, this.target, path, value)\n\t\tthis.refresh()\n\t}\n\n\tget listing(): boolean {\n\t\treturn this.world !== null\n\t}\n\n\tset listing(on: boolean) {\n\t\tthis.listedAt = -Infinity\n\t\tthis.world = on ? listWorld(this.simulation) : null\n\t}\n\n\tget logging(): boolean {\n\t\treturn this.events.attached\n\t}\n\n\tset logging(on: boolean) {\n\t\tif (on === this.logging) return\n\t\tif (on) this.events.attach(this.simulation)\n\t\telse this.events.detach()\n\t}\n\n\tlog(): readonly LoggedEvent[] {\n\t\treturn this.events.entries\n\t}\n\n\tclearLog(): void {\n\t\tthis.events.clear()\n\t}\n\n\t/** Works what is handed out again. The session does when a tick went by */\n\trefresh(): void {\n\t\tconst world = this.simulation\n\t\tthis.inspection = this.target && inspect(world, this.target)\n\t\tif (this.world && world.tick - this.listedAt >= LIST_EVERY) {\n\t\t\tthis.world = listWorld(world)\n\t\t\tthis.listedAt = world.tick\n\t\t}\n\t}\n\n\tdispose(): void {\n\t\tthis.events.detach()\n\t}\n}\n\n/** What is followed, as the wire says it: an entity, a player or the world, or nothing; anything else is not */\nfunction targetOf(value: unknown): InspectTarget | null | undefined {\n\tif (value === null) return null\n\tif (typeof value !== 'object') return undefined\n\tconst target = value as Record<string, unknown>\n\tif (isFiniteNumber(target.entity)) return { entity: target.entity }\n\tif (isFiniteNumber(target.player)) return { player: target.player }\n\tif (target.world === true) return { world: true }\n\treturn undefined\n}\n\n/**\n * Does what the debug tools of a screen asked of a world here (`DebugAsk`), each field checked first: it comes from\n * anyone who can send anything\n */\nexport function askDebug(view: SessionDebug, ask: Record<string, unknown>): void {\n\tconst target = targetOf(ask.inspect)\n\tif (target !== undefined) view.inspect(target)\n\tconst set = ask.set as { path?: unknown; value?: unknown } | undefined\n\tif (\n\t\tset &&\n\t\tArray.isArray(set.path) &&\n\t\tset.path.every((key) => typeof key === 'string' || isFiniteNumber(key)) &&\n\t\t(isFiniteNumber(set.value) || typeof set.value === 'boolean')\n\t)\n\t\tview.set(set.path as (string | number)[], set.value)\n\tif (typeof ask.listing === 'boolean') view.listing = ask.listing\n\tif (typeof ask.logging === 'boolean') view.logging = ask.logging\n\tif (ask.clearLog === true) view.clearLog()\n}\n\n/**\n * The debug tools' view of a world elsewhere, a server's or a worker's: what it asked to follow, said over the wire\n * (`DebugAsk`), and what came back last (`take`)\n */\nexport class RemoteDebug implements SessionDebug {\n\tinspection: Inspection | null = null\n\tworld: WorldListing | null = null\n\tprivate listed = false\n\tprivate logged = false\n\tprivate target: InspectTarget | null = null\n\tprivate events: readonly LoggedEvent[] = []\n\n\tconstructor(private readonly ask: (ask: DebugAsk) => void) {}\n\n\tinspect(target: InspectTarget | null): void {\n\t\tthis.target = target\n\t\tif (!target) this.inspection = null\n\t\tthis.ask({ inspect: target })\n\t}\n\n\t/** Asks again for all it follows: of a world it is served from anew (a session resumed, a replay gone back) */\n\taskAgain(): void {\n\t\tif (this.target || this.listed || this.logged) this.ask({ inspect: this.target, listing: this.listed, logging: this.logged })\n\t}\n\n\tset(path: (string | number)[], value: number | boolean): void {\n\t\tthis.ask({ set: { path, value } })\n\t}\n\n\tget listing(): boolean {\n\t\treturn this.listed\n\t}\n\n\tset listing(on: boolean) {\n\t\tthis.listed = on\n\t\tif (!on) this.world = null\n\t\tthis.ask({ listing: on })\n\t}\n\n\tget logging(): boolean {\n\t\treturn this.logged\n\t}\n\n\tset logging(on: boolean) {\n\t\tthis.logged = on\n\t\tthis.ask({ logging: on })\n\t}\n\n\tlog(): readonly LoggedEvent[] {\n\t\treturn this.events\n\t}\n\n\tclearLog(): void {\n\t\tthis.events = []\n\t\tthis.ask({ clearLog: true })\n\t}\n\n\t/** What the world's side said of what is followed */\n\ttake(said: { inspection: Inspection | null; world: WorldListing | null; log: readonly LoggedEvent[] }): void {\n\t\tthis.inspection = said.inspection\n\t\tthis.world = this.listed ? said.world : null\n\t\tif (this.logged) this.events = said.log\n\t}\n}\n"],"mappings":"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"}

package/dist/session/delay.js

@@ -0,0 +1,62 @@
+//#region src/session/delay.ts
+/** The tick a message to a player says it brings: of a delta from the head of its text, of the welcome from the frame it carries */
+var tickOf = (message) => {
+	const found = /^\{"type":"delta","tick":(\d+)/.exec(message) ?? (message.startsWith("{\"type\":\"welcome\"") ? /"first":\{"tick":(\d+)/.exec(message) : null);
+	return found ? Number(found[1]) : void 0;
+};
+/** How often what is held is looked at, to send on what is due: a second's tenth is near enough for a delay of seconds */
+var LOOK_EVERY = 100;
+/**
+* The host's end of a watcher's transport, with what goes to the watcher held for `seconds` (see the top of this
+* file). Closing it closes the watcher's, and what is held goes with it
+*
+* @beta
+*/
+function delayed(transport, seconds) {
+	const held = [];
+	let hostHears = () => {};
+	let hostClosed = () => {};
+	const timer = setInterval(() => {
+		const now = performance.now();
+		let due = 0;
+		while (due < held.length && held[due].at <= now) due++;
+		for (const { text } of held.splice(0, due)) transport.send(text);
+	}, LOOK_EVERY);
+	transport.onMessage((text) => {
+		if (text.startsWith("{\"type\":\"ack\"")) return;
+		hostHears(text);
+	});
+	transport.onClose(() => {
+		clearInterval(timer);
+		held.length = 0;
+		hostClosed();
+	});
+	return {
+		send(text) {
+			held.push({
+				at: performance.now() + seconds * 1e3,
+				text
+			});
+			const tick = tickOf(text);
+			if (tick !== void 0) queueMicrotask(() => hostHears(JSON.stringify({
+				type: "ack",
+				tick
+			})));
+		},
+		onMessage(handler) {
+			hostHears = handler;
+		},
+		onClose(handler) {
+			hostClosed = handler;
+		},
+		close() {
+			clearInterval(timer);
+			held.length = 0;
+			transport.close();
+		}
+	};
+}
+//#endregion
+export { delayed };
+
+//# sourceMappingURL=delay.js.map

package/dist/session/delay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.js","names":[],"sources":["../../src/session/delay.ts"],"sourcesContent":["/**\n * A watcher shown the game some seconds behind it (RV86): what the host sends goes on after the delay, so that who\n * watches a game being played cannot tell a side where the other is now. The host is answered at once on the\n * watcher's behalf (`ack`), as one who missed nothing: it goes on making each frame against the one before, and keeps\n * nothing more for the delay; the watcher's own answers are not passed on, as they come late. The rest of what the\n * watcher says (a line, a ping) goes as it is said\n */\nimport type { Transport } from './remote'\n\n/** The tick a message to a player says it brings: of a delta from the head of its text, of the welcome from the frame it carries */\nconst tickOf = (message: string): number | undefined => {\n\tconst found =\n\t\t/^\\{\"type\":\"delta\",\"tick\":(\\d+)/.exec(message) ?? (message.startsWith('{\"type\":\"welcome\"') ? /\"first\":\\{\"tick\":(\\d+)/.exec(message) : null)\n\treturn found ? Number(found[1]) : undefined\n}\n\n/** How often what is held is looked at, to send on what is due: a second's tenth is near enough for a delay of seconds */\nconst LOOK_EVERY = 100\n\n/**\n * The host's end of a watcher's transport, with what goes to the watcher held for `seconds` (see the top of this\n * file). Closing it closes the watcher's, and what is held goes with it\n *\n * @beta\n */\nexport function delayed(transport: Transport, seconds: number): Transport {\n\tconst held: { at: number; text: string }[] = []\n\tlet hostHears: (text: string) => void = () => {}\n\tlet hostClosed: () => void = () => {}\n\tconst timer = setInterval(() => {\n\t\tconst now = performance.now()\n\t\tlet due = 0\n\t\twhile (due < held.length && held[due].at <= now) due++\n\t\tfor (const { text } of held.splice(0, due)) transport.send(text)\n\t}, LOOK_EVERY)\n\ttransport.onMessage((text) => {\n\t\t// the watcher's own answers come late: the host had them at once\n\t\tif (text.startsWith('{\"type\":\"ack\"')) return\n\t\thostHears(text)\n\t})\n\t// one handler on the watcher's end (a server's keeps one): told on to the host's\n\ttransport.onClose(() => {\n\t\tclearInterval(timer)\n\t\theld.length = 0\n\t\thostClosed()\n\t})\n\treturn {\n\t\tsend(text) {\n\t\t\theld.push({ at: performance.now() + seconds * 1000, text })\n\t\t\tconst tick = tickOf(text)\n\t\t\t// answered as one who missed nothing, once what the host does now is done\n\t\t\tif (tick !== undefined) queueMicrotask(() => hostHears(JSON.stringify({ type: 'ack', tick })))\n\t\t},\n\t\tonMessage(handler) {\n\t\t\thostHears = handler\n\t\t},\n\t\tonClose(handler) {\n\t\t\thostClosed = handler\n\t\t},\n\t\tclose() {\n\t\t\tclearInterval(timer)\n\t\t\theld.length = 0\n\t\t\ttransport.close()\n\t\t}\n\t}\n}\n"],"mappings":";;AAUA,IAAM,UAAU,YAAwC;CACvD,MAAM,QACL,iCAAiC,KAAK,OAAO,MAAM,QAAQ,WAAW,uBAAmB,IAAI,yBAAyB,KAAK,OAAO,IAAI;CACvI,OAAO,QAAQ,OAAO,MAAM,EAAE,IAAI,KAAA;AACnC;;AAGA,IAAM,aAAa;;;;;;;AAQnB,SAAgB,QAAQ,WAAsB,SAA4B;CACzE,MAAM,OAAuC,CAAC;CAC9C,IAAI,kBAA0C,CAAC;CAC/C,IAAI,mBAA+B,CAAC;CACpC,MAAM,QAAQ,kBAAkB;EAC/B,MAAM,MAAM,YAAY,IAAI;EAC5B,IAAI,MAAM;EACV,OAAO,MAAM,KAAK,UAAU,KAAK,IAAI,CAAC,MAAM,KAAK;EACjD,KAAK,MAAM,EAAE,UAAU,KAAK,OAAO,GAAG,GAAG,GAAG,UAAU,KAAK,IAAI;CAChE,GAAG,UAAU;CACb,UAAU,WAAW,SAAS;EAE7B,IAAI,KAAK,WAAW,mBAAe,GAAG;EACtC,UAAU,IAAI;CACf,CAAC;CAED,UAAU,cAAc;EACvB,cAAc,KAAK;EACnB,KAAK,SAAS;EACd,WAAW;CACZ,CAAC;CACD,OAAO;EACN,KAAK,MAAM;GACV,KAAK,KAAK;IAAE,IAAI,YAAY,IAAI,IAAI,UAAU;IAAM;GAAK,CAAC;GAC1D,MAAM,OAAO,OAAO,IAAI;GAExB,IAAI,SAAS,KAAA,GAAW,qBAAqB,UAAU,KAAK,UAAU;IAAE,MAAM;IAAO;GAAK,CAAC,CAAC,CAAC;EAC9F;EACA,UAAU,SAAS;GAClB,YAAY;EACb;EACA,QAAQ,SAAS;GAChB,aAAa;EACd;EACA,QAAQ;GACP,cAAc,KAAK;GACnB,KAAK,SAAS;GACd,UAAU,MAAM;EACjB;CACD;AACD"}