incanto 0.69.0 → 0.71.0

package/dist/{split-screen-Cg76MCV5.d.ts → split-screen-CIYf1zSf.d.ts}

@@ -1,6 +1,7 @@
-import { Lt as Signal, b as Engine, jt as Node } from "./behavior-rm8vVzu_.js";
-import { c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-B6ugCV1Q.js";
-import { t as LoadSceneOptions } from "./loader-DadV2QCT.js";
+import { Lt as Signal, b as Engine, jt as Node } from "./behavior-Dcz0fr1S.js";
+import { t as DiagnosticSink } from "./diagnostics-Cu85N3tL.js";
+import { a as SceneJson, c as JsonValue, s as JsonObject } from "./rng-Bb-IutXB.js";
+import { t as LoadSceneOptions } from "./loader-8-IHvbKD.js";
 
 //#region src/net/types.d.ts
 type Unsubscribe = () => void;
@@ -117,6 +118,17 @@ interface LocalGameServerOptions {
   * raw `LoopbackHub`.
   */
   server?: ServerClass;
+  /**
+  * Where the preview server reports its own failures.
+  *
+  * It had nowhere to report them, and it is the server every multiplayer game
+  * boots against. A `$roomTick` that THREW went to absolutely nothing —
+  * `enqueue` marks the rejection handled and every shipped pump is
+  * `void local.tick(...)` — so the server-driven match clock stopped forever
+  * with `engine.log` empty and `stats().errors` 0. `createSplitScreen` passes
+  * the first player's engine.
+  */
+  diagnostics?: DiagnosticSink | null;
 }
 /**
 * Run a multiplayer game's REAL agent8-sdk-v2 `Server` class **locally**, in
@@ -165,7 +177,21 @@ declare class LocalGameServer {
   private readonly subColl;
   private readonly subAsset;
   private readonly subMsg;
-  constructor(serverClass?: ServerClass);
+  private diagnostics;
+  /**
+  * Point the server's own failures at a log.
+  *
+  * `createSplitScreen` builds the server BEFORE the engines that will read it,
+  * so the sink arrives after construction. Without one, a `$roomTick` that
+  * throws and a wedged queue are console-only, which is exactly the silence
+  * this reports.
+  */
+  reportTo(sink: DiagnosticSink | null): void;
+  /** Said once per room, so a per-frame pump cannot fill the log. */
+  private readonly reportedTickFailures;
+  /** Said once per stuck call — see `enqueue`. */
+  private readonly reportedSlow;
+  constructor(serverClass?: ServerClass, diagnostics?: DiagnosticSink | null);
   /** A client on this server. Distinct `account` per player (default auto-assigned). */
   createClient(account?: string): LocalGameServerTransport;
   private collectionSnapshot;
@@ -192,6 +218,8 @@ declare class LocalGameServer {
   tick(deltaMS: number): Promise<void>;
   /** @internal Dispatch a remoteFunction (serialized). */
   call(account: string, fn: string, args: unknown[]): Promise<unknown>;
+  /** How long one serialized call may take before the server says it is stuck. */
+  private static readonly SLOW_CALL_MS;
   private enqueue;
   private dispatch;
   private runTick;
@@ -353,6 +381,10 @@ declare class NetworkManager {
   private detachReplication;
   private lastOwner;
   private boundScene;
+  /** The room the BOUND scene declared, so a swap can tell same-room from not. */
+  private declaredRoom;
+  /** Said once: a client that went mute must not also spam the console. */
+  private reportedUnbound;
   static get(engine: Engine): NetworkManager | null;
   static create(engine: Engine, opts?: NetworkManagerOptions): Promise<NetworkManager>;
   private constructor();

package/dist/{split-screen-CauMwu6y.js → split-screen-eULetcg-.js}

@@ -1,8 +1,8 @@
-import { O as Node, V as Signal, k as diagnose, n as loadScene, t as buildNodeJson } from "./loader-DZE7B07H.js";
-import { t as registerCoreNodes, v as Engine } from "./register-mmfugpaQ.js";
+import { n as jsonEquals, t as jsonClone } from "./json-CfTjpvW8.js";
+import { J as Node, Y as diagnose, ct as Signal, d as rebuildOptions, h as loadScene, l as markCloned, m as buildSceneSubtree, p as stripUids, u as markTemplateName } from "./save-slots-Bvuh2p_r.js";
+import { t as registerCoreNodes, v as Engine } from "./register-DuVdzxbq.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { n as jsonEquals, t as jsonClone } from "./json-CwwhxQgb.js";
-import { l as registerNode } from "./registry-CF70EArN.js";
+import { p as registerNode } from "./touch-BnCyPA0G.js";
 //#region src/net/loopback.ts
 /**
 * In-memory multiplayer hub implementing the SAME kernel contract as
@@ -247,7 +247,7 @@ var LoopbackTransport = class {
 * NOT a substitute for the cloud: no isolated-vm sandboxing, no persistence, no
 * rate limits — a faithful FUNCTIONAL emulator for local play and tests.
 */
-var LocalGameServer = class {
+var LocalGameServer = class LocalGameServer {
 	hub = new LoopbackHub();
 	serverClass;
 	/** Each client's current room — binds `$sender.roomId` on later calls. */
@@ -268,8 +268,25 @@ var LocalGameServer = class {
 	subColl = /* @__PURE__ */ new Map();
 	subAsset = /* @__PURE__ */ new Map();
 	subMsg = /* @__PURE__ */ new Map();
-	constructor(serverClass) {
+	diagnostics;
+	/**
+	* Point the server's own failures at a log.
+	*
+	* `createSplitScreen` builds the server BEFORE the engines that will read it,
+	* so the sink arrives after construction. Without one, a `$roomTick` that
+	* throws and a wedged queue are console-only, which is exactly the silence
+	* this reports.
+	*/
+	reportTo(sink) {
+		this.diagnostics = sink;
+	}
+	/** Said once per room, so a per-frame pump cannot fill the log. */
+	reportedTickFailures = /* @__PURE__ */ new Set();
+	/** Said once per stuck call — see `enqueue`. */
+	reportedSlow = /* @__PURE__ */ new Set();
+	constructor(serverClass, diagnostics) {
 		this.serverClass = serverClass;
+		this.diagnostics = diagnostics ?? null;
 	}
 	/** A client on this server. Distinct `account` per player (default auto-assigned). */
 	createClient(account) {
@@ -344,8 +361,18 @@ var LocalGameServer = class {
 	call(account, fn, args) {
 		return this.enqueue(() => this.dispatch(account, fn, args));
 	}
+	/** How long one serialized call may take before the server says it is stuck. */
+	static SLOW_CALL_MS = 5e3;
 	enqueue(run) {
 		const result = this.queue.then(run, run);
+		const timer = setTimeout(() => {
+			const key = "slow";
+			if (this.reportedSlow.has(key)) return;
+			this.reportedSlow.add(key);
+			diagnose(this.diagnostics, "error", `[incanto] preview server: a call has been running for over ${LocalGameServer.SLOW_CALL_MS / 1e3}s and every other client is blocked behind it. LocalGameServer runs one call at a time — look for an await that never settles, or a nested \`\$lock\` on the same key (\$lock is NOT reentrant).`);
+		}, LocalGameServer.SLOW_CALL_MS);
+		timer.unref?.();
+		result.then(() => clearTimeout(timer), () => clearTimeout(timer));
 		this.queue = result.then(() => void 0, () => void 0);
 		return result;
 	}
@@ -374,6 +401,11 @@ var LocalGameServer = class {
 			const restore = this.bindGlobals("", roomId);
 			try {
 				await server.$roomTick.call(server, deltaMS, roomId);
+			} catch (error) {
+				if (!this.reportedTickFailures.has(roomId)) {
+					this.reportedTickFailures.add(roomId);
+					diagnose(this.diagnostics, "error", `[incanto] preview server: $roomTick threw for room '${roomId}' — this room's server-driven state has stopped advancing.`, error);
+				}
 			} finally {
 				restore();
 			}
@@ -508,8 +540,8 @@ var LocalGameServer = class {
 			broadcastToAll: (type, message) => {
 				this.fireMsg(type, message);
 			},
-			sendMessageToUser: (type, acct, message) => {
-				this.fireMsg(type, message, acct);
+			sendMessageToUser: (account, type, message) => {
+				this.fireMsg(type, message, account);
 			}
 		};
 	}
@@ -621,7 +653,7 @@ var LocalGameServer = class {
 					message
 				]);
 			},
-			sendMessageToUser: (_type, _acct, _message) => {}
+			sendMessageToUser: (_account, _type, _message) => {}
 		};
 	}
 	withLock(key, fn) {
@@ -700,7 +732,7 @@ function queryItems(items, options) {
 }
 /** Construct a local preview server. With no `server`, it equals a raw LoopbackHub. */
 function createLocalGameServer(opts = {}) {
-	return new LocalGameServer(opts.server);
+	return new LocalGameServer(opts.server, opts.diagnostics);
 }
 /**
 * A client of a {@link LocalGameServer}. Subscriptions read the shared in-memory
@@ -849,13 +881,17 @@ var NetworkManager = class NetworkManager {
 	detachReplication = null;
 	lastOwner = null;
 	boundScene = null;
+	/** The room the BOUND scene declared, so a swap can tell same-room from not. */
+	declaredRoom = null;
+	/** Said once: a client that went mute must not also spam the console. */
+	reportedUnbound = false;
 	static get(engine) {
 		return managers.get(engine) ?? null;
 	}
 	static async create(engine, opts = {}) {
 		await managers.get(engine)?.dispose();
-		const server = opts.transport ?? await createDefaultTransport(opts.config);
-		await server.connect();
+		const server = opts.transport ?? await createDefaultTransport(opts.config, engine);
+		if (await server.connect() === false) throw new IncantoError("NETWORK_UNAVAILABLE", "The multiplayer transport refused to connect, so this game cannot join a room. Check the server is running and reachable; pass `transport` to use a LocalGameServer or LoopbackTransport instead.");
 		const requested = opts.room ?? engine.scene?.multiplayer?.room ?? "auto";
 		const manager = new NetworkManager(engine, server, await server.remoteFunction("joinRoom", [requested === "auto" ? void 0 : requested], { needResponse: true }), opts.throttleMs ?? 50, opts.keyframeMs ?? DEFAULT_KEYFRAME_MS);
 		managers.set(engine, manager);
@@ -869,6 +905,7 @@ var NetworkManager = class NetworkManager {
 		this.throttleMs = Math.max(30, throttleMs);
 		this.keyframeMs = Math.max(0, keyframeMs);
 		this.boundScene = engine.scene;
+		this.declaredRoom = (engine.scene?.multiplayer)?.room;
 		this.subs.push(server.subscribeRoomState(roomId, (state) => {
 			this.latestRoomState = state;
 			this.roomState.emit(state);
@@ -1017,11 +1054,25 @@ var NetworkManager = class NetworkManager {
 		this.detachReplication?.();
 		for (const off of this.subs) off();
 		await this.server.remoteFunction("leaveRoom", [this.roomId]);
-		managers.delete(this.engine);
+		if (managers.get(this.engine) === this) managers.delete(this.engine);
 	}
 	replicate(dt) {
 		const scene = this.engine.scene;
-		if (!scene || scene !== this.boundScene) return;
+		if (!scene) return;
+		if (scene !== this.boundScene) {
+			const room = scene.multiplayer?.room;
+			if (room === this.declaredRoom) {
+				this.boundScene = scene;
+				this.lastOwner = null;
+				this.lastSent.clear();
+			} else {
+				if (!this.reportedUnbound) {
+					this.reportedUnbound = true;
+					diagnose(this.engine, "error", `[incanto] multiplayer: this client stopped broadcasting — the scene changed to '${scene.name}', which declares room ${JSON.stringify(room ?? null)} and this manager is bound to ${JSON.stringify(this.declaredRoom ?? null)}. Create a new NetworkManager for the new room (incanto-multiplayer.md).`);
+				}
+				return;
+			}
+		}
 		this.sendAccumulator += dt * 1e3;
 		this.aliveMs += dt * 1e3;
 		const owner = findOwnerNode(scene.root, true);
@@ -1052,7 +1103,9 @@ var NetworkManager = class NetworkManager {
 		for (const [key, value] of Object.entries(full)) this.lastSent.set(key, jsonClone(value));
 		this.keyframeAccumulator = 0;
 		this.sendAccumulator = 0;
-		this.setMyState({ sync: full });
+		this.setMyState({ sync: full }).catch((error) => {
+			this.engine._asyncFailed(`${owner.getPath()}: replication to room '${this.roomId}' failed — this client is no longer visible to the others`, error);
+		});
 	}
 };
 /** The single `network.mode === 'owner'` node in a tree, or null. @internal */
@@ -1079,7 +1132,9 @@ function readSyncKey(node, key) {
 	const target = lastDot === -1 ? node : node.getNodeOrNull(key.slice(0, lastDot)) ?? void 0;
 	const prop = lastDot === -1 ? key : key.slice(lastDot + 1);
 	if (!target) return void 0;
-	return target[prop];
+	const value = target[prop];
+	if (value instanceof Set) return [...value];
+	return value;
 }
 /**
 * @internal Applies a replicated flat sync patch (`{'position': …,
@@ -1094,9 +1149,9 @@ function applySyncPatch(root, patch, setProp, onMissingNode) {
 		else onMissingNode?.(key);
 	}
 }
-async function createDefaultTransport(config) {
-	const { createAgent8Server } = await import("./agent8-CvsfVskX.js").then((n) => n.t);
-	return createAgent8Server(config);
+async function createDefaultTransport(config, diagnostics) {
+	const { createAgent8Server } = await import("./agent8-Cfmd3ar_.js").then((n) => n.t);
+	return createAgent8Server(config, diagnostics);
 }
 //#endregion
 //#region src/net/nodes/network-spawner.ts
@@ -1125,7 +1180,19 @@ var NetworkSpawner = class extends Node {
 	static signals = ["spawned", "despawned"];
 	static props = {
 		source: { default: "users" },
-		scene: { default: "" },
+		/**
+		* The key a remote's scene was registered under
+		* (`manager.registerScene(key, json)`).
+		*
+		* REQUIRED, like `Chase.target` and `FollowCamera.target`, and for the same
+		* reason: without one `update` returned every frame, no remote player ever
+		* appeared, and the scene loaded, audited and played clean. A multiplayer
+		* game with nobody in it is worth a load error, not a silent room.
+		*/
+		scene: {
+			default: "",
+			required: true
+		},
 		interpolate: { default: true }
 	};
 	source = "users";
@@ -1136,18 +1203,30 @@ var NetworkSpawner = class extends Node {
 	positionTargets = /* @__PURE__ */ new Map();
 	failedKeys = /* @__PURE__ */ new Set();
 	reported = /* @__PURE__ */ new Set();
+	/** Seconds spent looking for a NetworkManager — see the report in `update`. */
+	waited = 0;
 	update(dt) {
 		const engine = this.tree?.engine;
 		if (!engine) return;
 		const manager = NetworkManager.get(engine);
-		if (!manager || this.scene === "") return;
+		if (!manager) {
+			this.waited += dt;
+			if (this.waited > 2) this.report("there is no multiplayer in this game");
+			return;
+		}
 		const entries = this.currentEntries(manager);
 		for (const [key, state] of Object.entries(entries)) {
 			let instance = this.spawned.get(key);
 			if (!instance) {
 				if (this.failedKeys.has(key)) continue;
 				try {
-					instance = buildNodeJson(manager.resolveScene(this.scene).root);
+					const json = manager.resolveScene(this.scene);
+					instance = buildSceneSubtree({
+						...json,
+						root: stripUids(json.root)
+					}, rebuildOptions(this));
+					markCloned(instance);
+					markTemplateName(instance);
 				} catch (error) {
 					this.failedKeys.add(key);
 					throw error;
@@ -1207,13 +1286,57 @@ var NetworkSpawner = class extends Node {
 			this.positionTargets.set(target, value);
 			return;
 		}
-		target[prop] = value;
+		if (prop === "position" && Array.isArray(target.position)) {
+			this.report(`'position' arrived as ${JSON.stringify(value)} — a node position is a number array`);
+			return;
+		}
+		if (prop === "groups") {
+			if (Array.isArray(value)) {
+				for (const g of value) if (typeof g === "string") target.addToGroup(g);
+			}
+			return;
+		}
+		try {
+			target[prop] = value;
+		} catch (error) {
+			if (!this.reported.has(`prop:${prop}`)) {
+				this.reported.add(`prop:${prop}`);
+				diagnose(this.tree?.engine, "error", `[incanto] NetworkSpawner on '${this.getPath()}': replicated key '${prop}' cannot be written onto a '${target.constructor.typeName ?? "Node"}' — it is a readonly accessor, not a prop. Sync a real prop, or a plain data key of your own.`, error);
+			}
+		}
+	}
+	/**
+	* What the NETWORK last said this node's position is — not where it is drawn.
+	*
+	* A remote copy renders slightly in the past, chasing its target at
+	* ~12.5%/frame. That is the right way to draw one and the wrong way to
+	* COMPARE one: `incanto-multiplay`'s `agrees` rung read the rendered
+	* position, so a late joiner whose interpolation had not converged was
+	* reported as disagreeing with the owner —
+	*
+	*   ✗ late has p1's `position` as [-3.3465…], not [-3.3989…]
+	*
+	* — on both SHIPPED 2D multiplayer examples, which exit 1 today on the plain
+	* documented command. The size of the "disagreement" is the player's speed
+	* times the chase lag, so a faster game fails harder while replicating
+	* perfectly.
+	*
+	* `undefined` when this spawner has no target for that node: it is not one of
+	* ours, or `interpolate` is off, in which case the drawn value IS the
+	* received one.
+	*/
+	replicatedPosition(node) {
+		return this.positionTargets.get(node);
 	}
 	stepInterpolation(dt) {
-		const f = Math.min(1, dt * 8);
+		const real = this.tree?.engine?.unscaledDelta || dt;
+		const f = Math.min(1, real * 8);
 		for (const [target, goal] of this.positionTargets) {
 			const pos = target.position;
-			if (!Array.isArray(pos)) continue;
+			if (!Array.isArray(pos)) {
+				target.position = [...goal];
+				continue;
+			}
 			target.position = pos.map((v, i) => v + ((goal[i] ?? v) - v) * f);
 		}
 	}
@@ -1276,7 +1399,17 @@ async function createSplitScreen(opts) {
 		players.push(player);
 		await opts.setup(player, i);
 	}
-	const disconnect = (players[0]?.engine)?.updated.connect((dt) => void server.tick(Math.min(dt, .05) * 1e3));
+	const first = players[0]?.engine;
+	server.reportTo(first ? { log: {
+		warn: (...p) => first.log.warn(...p),
+		info: (...p) => first.log.info(...p),
+		debug: (...p) => first.log.debug(...p),
+		error: (...p) => {
+			const [head, ...rest] = p;
+			first._asyncFailed(String(head).replace(/^\[incanto\] /, ""), rest[0] ?? "");
+		}
+	} } : null);
+	const disconnect = first?.updated.connect((dt) => void server.tick(Math.min(dt, .05) * 1e3));
 	return {
 		server,
 		players,

package/dist/{sprite-animation-CY-mrr1L.js → sprite-animation-CqR2o3SA.js}

@@ -1,5 +1,6 @@
+import { n as jsonEquals } from "./json-CfTjpvW8.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { n as jsonEquals } from "./json-CwwhxQgb.js";
+import { h as didYouMean } from "./touch-BnCyPA0G.js";
 //#region src/core/particle-presets.ts
 const PARTICLE_PRESETS = {
 	fire: {
@@ -319,16 +320,46 @@ function resolveAnimation(animations, name, owner) {
 		key = entry;
 	}
 }
+/** The whole of a clip definition — anything else in one is a mistake. */
+const DEF_KEYS = [
+	"frames",
+	"fps",
+	"loop"
+];
 /**
-* Every alias resolves — checked once, at ready, rather than on the frame the
-* character first jumps.
+* Every clip and every alias — checked once, at ready, rather than on the frame
+* the character first jumps.
 *
 * A cosmetic map that only fails the moment a state is first entered is the
-* shape of bug that reaches players: the game loads, plays, and dies on a
-* ledge twenty minutes in.
+* shape of bug that reaches players: the game loads, plays, and dies on a ledge
+* twenty minutes in.
+*
+* That was the argument for checking the aliases, and it was only ever applied
+* to them: the clip DEFINITIONS beside them were first read by
+* `resolveAnimation`, which `play()` calls. So a map like
+* `{"walk": {"frame": [0,7], "fps": 10}}` — `frames` misspelled, the likeliest
+* of the mistakes and the quietest, because `frame`, `frameRate`, `speed` and
+* `repeat` are all real fields in the sheet formats people convert from —
+* loaded clean, passed `incanto-check`, and was a hard error the first time the
+* character walked. The one mistake caught at load was `autoplay` naming a clip
+* that does not exist: the name you play was checked, the clip you play was not.
 */
-function validateAnimationAliases(animations, owner) {
-	for (const [name, entry] of Object.entries(animations)) if (typeof entry === "string") resolveAnimation(animations, name, owner);
+function validateAnimations(animations, owner) {
+	for (const [name, entry] of Object.entries(animations)) {
+		if (typeof entry === "string") {
+			resolveAnimation(animations, name, owner);
+			continue;
+		}
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) throw new IncantoError("BAD_FORMAT", `Animation '${name}' on '${owner}' is ${Array.isArray(entry) ? "a list" : `a ${typeof entry}`} — a clip is {"frames": [start, end], "fps": 10} or the name of another clip.`);
+		const def = entry;
+		for (const key of Object.keys(def)) {
+			if (DEF_KEYS.includes(key)) continue;
+			throw new IncantoError("BAD_FORMAT", `Animation '${name}' on '${owner}' has an unknown field "${key}".` + didYouMean(key, DEF_KEYS) + " A clip is {frames, fps, loop} — the rate is \"fps\", not frameRate or speed, and looping is \"loop\": true, not a repeat count.");
+		}
+		if (def.loop !== void 0 && typeof def.loop !== "boolean") throw new IncantoError("BAD_FORMAT", `Animation '${name}' on '${owner}': "loop" is true or false, not ${JSON.stringify(def.loop)}.`);
+		if (def.fps !== void 0 && typeof def.fps !== "number") throw new IncantoError("BAD_FORMAT", `Animation '${name}' on '${owner}': "fps" is a number, not ${JSON.stringify(def.fps)}.`);
+		resolveAnimation(animations, name, owner);
+	}
 }
 /**
 * `[start, end]` is a RANGE; anything else is an explicit list.
@@ -349,4 +380,4 @@ function resolveFrames(frames, name) {
 	return [...frames];
 }
 //#endregion
-export { PARTICLE_PRESETS as a, ParticleSim as i, resolveFrames as n, PARTICLE_PRESET_NAMES as o, validateAnimationAliases as r, applyParticlePreset as s, resolveAnimation as t };
+export { PARTICLE_PRESETS as a, ParticleSim as i, resolveFrames as n, PARTICLE_PRESET_NAMES as o, validateAnimations as r, applyParticlePreset as s, resolveAnimation as t };

package/dist/{src-CYEu-_S9.js → src-_jk0qLsS.js}

@@ -197,23 +197,8 @@ async function preloadSceneAssets(assets, title) {
 	}
 }
 //#endregion
-//#region src/core/uid-gen.ts
-/**
-* The ONE way to mint a node uid: crypto-strength, `n_` + 16 base36 chars
-* (~82 bits). Hand-written uids are forbidden by convention — they break the
-* collision-strength contract and read as fakes next to generated ones.
-*/
-function newUid() {
-	const bytes = new Uint8Array(16);
-	if (globalThis.crypto?.getRandomValues) globalThis.crypto.getRandomValues(bytes);
-	else for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
-	let id = "";
-	for (const b of bytes) id += (b % 36).toString(36);
-	return `n_${id.slice(0, 16)}`;
-}
-//#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.69.0";
+const VERSION = "0.71.0";
 //#endregion
-export { preloadUrls as a, preloadSceneAssets as i, newUid as n, findPath as o, assetUrls as r, gridFromRows as s, VERSION as t };
+export { findPath as a, preloadUrls as i, assetUrls as n, gridFromRows as o, preloadSceneAssets as r, VERSION as t };