incanto 0.50.0 → 0.52.0

package/dist/{loader-DwazzlQb.js → loader-B-Gft32x.js}

@@ -1,6 +1,6 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
-import { c as mergeStaticSignals, i as getNodeSchema, r as createNode, s as mergeStaticProps, t as applySchemaProps } from "./registry-IyWCGe4q.js";
+import { c as mergeStaticSignals, i as getNodeSchema, r as createNode, s as mergeStaticProps, t as applySchemaProps } from "./registry-C7u42TID.js";
 //#region src/core/signal.ts
 var Signal = class {
 	connections = [];
@@ -135,6 +135,36 @@ function createBehavior(name, props) {
 	return behavior;
 }
 //#endregion
+//#region src/core/node-path.ts
+function parseNodePath(path) {
+	if (path === "") throw new IncantoError("BAD_NODE_PATH", "Node path must not be empty.");
+	if (path.startsWith("%")) {
+		const name = path.slice(1);
+		if (name === "" || name.includes("/") || name.includes("%")) throw new IncantoError("BAD_NODE_PATH", `Invalid unique-name path '${path}'. Expected '%NodeName'.`);
+		return {
+			kind: "unique",
+			name
+		};
+	}
+	if (path === ".") return {
+		kind: "relative",
+		segments: []
+	};
+	const absolute = path.startsWith("/");
+	const body = absolute ? path.slice(1) : path;
+	if (body === "" || body.split("/").some((s) => s === "")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. Segments must be non-empty (no leading/trailing/double '/').`);
+	const segments = body.split("/");
+	for (const seg of segments) {
+		if (seg.includes("%")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. '%' is only allowed as a whole-path prefix ('%Name').`);
+		if (seg === ".") throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. '.' is only valid as the whole path — drop the './' prefix.`);
+	}
+	if (absolute && segments.includes("..")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. Absolute paths must not contain '..'.`);
+	return {
+		kind: absolute ? "absolute" : "relative",
+		segments
+	};
+}
+//#endregion
 //#region src/core/diagnostics.ts
 function diagnose(engine, level, ...parts) {
 	engine?.log[level](...parts);
@@ -640,35 +670,344 @@ function effectiveOrder(group, renderOrder, table = ORDER_GROUP_BASE) {
 	return (table[group] ?? 0) + renderOrder;
 }
 //#endregion
-//#region src/core/node-path.ts
-function parseNodePath(path) {
-	if (path === "") throw new IncantoError("BAD_NODE_PATH", "Node path must not be empty.");
-	if (path.startsWith("%")) {
-		const name = path.slice(1);
-		if (name === "" || name.includes("/") || name.includes("%")) throw new IncantoError("BAD_NODE_PATH", `Invalid unique-name path '${path}'. Expected '%NodeName'.`);
+//#region src/core/save.ts
+const memoryStores = /* @__PURE__ */ new Map();
+function createSaveStore(namespace) {
+	const prefix = `incanto:${namespace}:`;
+	const local = storageOrNull();
+	if (!local) {
+		let mem = memoryStores.get(namespace);
+		if (!mem) {
+			mem = /* @__PURE__ */ new Map();
+			memoryStores.set(namespace, mem);
+		}
+		const backing = mem;
 		return {
-			kind: "unique",
-			name
+			get: (key, fallback) => parse(backing.get(key), fallback),
+			set: (key, value) => void backing.set(key, JSON.stringify(value)),
+			remove: (key) => void backing.delete(key),
+			clear: () => backing.clear()
 		};
 	}
-	if (path === ".") return {
-		kind: "relative",
-		segments: []
+	return {
+		get: (key, fallback) => parse(local.getItem(prefix + key) ?? void 0, fallback),
+		set: (key, value) => local.setItem(prefix + key, JSON.stringify(value)),
+		remove: (key) => local.removeItem(prefix + key),
+		clear: () => {
+			const doomed = [];
+			for (let i = 0; i < local.length; i++) {
+				const k = local.key(i);
+				if (k?.startsWith(prefix)) doomed.push(k);
+			}
+			for (const k of doomed) local.removeItem(k);
+		}
 	};
-	const absolute = path.startsWith("/");
-	const body = absolute ? path.slice(1) : path;
-	if (body === "" || body.split("/").some((s) => s === "")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. Segments must be non-empty (no leading/trailing/double '/').`);
-	const segments = body.split("/");
-	for (const seg of segments) {
-		if (seg.includes("%")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. '%' is only allowed as a whole-path prefix ('%Name').`);
-		if (seg === ".") throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. '.' is only valid as the whole path — drop the './' prefix.`);
+}
+function parse(raw, fallback) {
+	if (raw === void 0 || raw === null) return fallback;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return fallback;
+	}
+}
+function storageOrNull() {
+	try {
+		if (typeof localStorage === "undefined") return null;
+		const probe = "__incanto_probe__";
+		localStorage.setItem(probe, "1");
+		localStorage.removeItem(probe);
+		return localStorage;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/core/save-slots.ts
+/**
+* Save slots — "continue where you left off", which no game on this engine could
+* do.
+*
+* `createSaveStore` has been here a long time and `Scene.toJSON()` round-trips a
+* live tree, so two thirds of the work existed. The missing third was that
+* BEHAVIOR state had nowhere to go: `Behavior` declared `onEnterTree`, `onReady`,
+* `onExitTree`, `update` and `fixedUpdate` and nothing for "write yourself down",
+* so `Health.current`, `ScoreKeeper.score` and every quest flag were
+* unrecoverable. Both quest templates this repo ships were RPGs you could not
+* resume.
+*
+* ## What a save is, and what it deliberately is NOT
+*
+* A save is **which scene, plus every behavior's state, keyed by node uid**. It
+* is not a snapshot of the live tree.
+*
+* That is a design decision, not a shortcut. Restoring a live tree by walking
+* paths breaks on this engine specifically:
+*
+* - `Spawner.onReady` DETACHES its prefab template from the tree (see
+*   `SpawnSource.resolveTemplate`), so a captured tree and a freshly booted one
+*   legitimately disagree about which nodes exist, every time.
+*   Every scene with a spawner would report phantom removals.
+* - A spawned enemy carrying its own spawner has already lost ITS template, so
+*   re-adding that subtree runs `onReady` against a node that is not there and
+*   throws — and `onReady` is not quarantined, so it kills the whole load.
+* - Prop deltas cannot be applied with `applySchemaProps`, which resets every
+*   prop to its default before writing.
+*
+* Reloading the scene from source sidesteps all three: the structure comes from
+* the file (which is authoritative and already validated), and the save carries
+* only what the file cannot know. A fresh boot detaches the same templates the
+* captured one did, so there is nothing to reconcile.
+*
+* The cost, stated plainly so nobody discovers it: **spawned enemies and
+* mid-level positions are not restored.** You resume at the scene's start with
+* your stats, inventory, unlocks and quest flags intact. That is what a
+* checkpoint save is, and it is what both quest templates need. A game that
+* wants a position saves it — `serialize()` can return anything.
+*
+* Node uids are the join key because they are the one identifier the engine
+* already promises survives a rename or a reparent.
+*/
+/**
+* The one key in a save that is not a uid: authored nodes the run consumed.
+*
+* A save reloads the scene from its FILE, so every collectible comes back —
+* resume a collect-five-to-win run at four and there are five gems on the map
+* again with your four still banked. No behavior can fix that from the inside:
+* the node that knew is the node that was freed.
+*
+* The engine can answer it without anyone's help. A uid in the scene file that
+* is not in the live tree is a node this run consumed. Spawned clones never
+* carry uids (`duplicateNode` drops them so a template can never mint colliding
+* ids), so the ledger is exactly the authored world — the part the file
+* rebuilds. `n_` prefixes every uid, so `#` can never collide with one.
+*/
+const FREED_KEY = "#freed";
+/**
+* Every behavior in the tree that has something to say, by uid.
+*
+* A behavior with no `serialize` contributes nothing — the hook is optional in
+* exactly the way the other five are, so adding save support to a game is
+* additive and a game that never saves pays nothing.
+*
+* A node with no `uid` is skipped and reported, because state keyed by nothing
+* cannot be given back. The editor assigns a uid to every node it touches; a
+* hand-written scene may not have.
+*/
+function captureBehaviors(root, source) {
+	const state = {};
+	const unaddressable = [];
+	let saveable = 0;
+	const walk = (node) => {
+		const behavior = node.behavior;
+		if (behavior && typeof behavior.serialize === "function") {
+			const value = behavior.serialize();
+			if (value !== void 0) {
+				saveable += 1;
+				if (node.uid) state[node.uid] = value;
+				else unaddressable.push(node.getPath());
+			}
+		}
+		for (const child of node.children) walk(child);
+	};
+	walk(root);
+	if (source !== void 0) {
+		const alive = /* @__PURE__ */ new Set();
+		const mark = (node) => {
+			const leaving = node.tree?._isQueuedFree(node) ?? false;
+			if (node.uid && !leaving) alive.add(node.uid);
+			for (const child of node.children) mark(child);
+		};
+		mark(root);
+		const freed = authoredUids(source).filter((uid) => !alive.has(uid));
+		if (freed.length > 0) state[FREED_KEY] = freed;
 	}
-	if (absolute && segments.includes("..")) throw new IncantoError("BAD_NODE_PATH", `Invalid node path '${path}'. Absolute paths must not contain '..'.`);
 	return {
-		kind: absolute ? "absolute" : "relative",
-		segments
+		state,
+		unaddressable,
+		saveable
 	};
 }
+/** Every uid the scene FILE declares, in document order. */
+function authoredUids(source) {
+	const out = [];
+	const walk = (node) => {
+		if (typeof node !== "object" || node === null) return;
+		const n = node;
+		if (typeof n.uid === "string" && n.uid !== "") out.push(n.uid);
+		if (Array.isArray(n.children)) for (const child of n.children) walk(child);
+	};
+	walk(source.root);
+	return out;
+}
+/**
+* Hand each behavior its state back.
+*
+* Call this AFTER the scene has loaded and `onReady` has run: `onReady` is where
+* a behavior sets its starting values, so restoring first would be overwritten
+* by the fresh start.
+*
+* Never throws on a mismatch. A save from an older build of the game will name
+* uids that no longer exist, and refusing to load it would mean a patch that
+* moves one node deletes everyone's progress. It reports instead.
+*/
+function restoreBehaviors(root, state) {
+	const report = {
+		missing: [],
+		skipped: [],
+		restored: 0,
+		expected: captureBehaviors(root).saveable,
+		freed: 0
+	};
+	for (const [uid, value] of Object.entries(state)) {
+		if (uid === "#freed") {
+			for (const gone of value ?? []) {
+				const node = root.getNodeByUid(gone);
+				if (node) {
+					node.queueFree();
+					report.freed += 1;
+				}
+			}
+			continue;
+		}
+		const node = root.getNodeByUid(uid);
+		if (!node) {
+			report.missing.push(uid);
+			continue;
+		}
+		const behavior = node.behavior;
+		if (!behavior || typeof behavior.deserialize !== "function") {
+			report.skipped.push(uid);
+			continue;
+		}
+		try {
+			behavior.deserialize(value);
+			report.restored += 1;
+		} catch {
+			report.skipped.push(uid);
+		}
+	}
+	return report;
+}
+/** Slot ids, so a "3 save slots" menu is a list and not a naming convention. */
+const INDEX_KEY = "slots";
+/**
+* The slot layer: a named list of saves over the existing store.
+*
+* Slot ids are yours (`'auto'`, `'1'`, `'2'`, `'3'`) — the engine does not
+* decide how many you have or whether one of them autosaves.
+*/
+var SaveSlots = class {
+	store;
+	constructor(namespace = "saves", store) {
+		this.store = store ?? createSaveStore(namespace);
+	}
+	/** Slot ids that have a save, newest first. */
+	list() {
+		const rows = this.store.get(INDEX_KEY, []).map((id) => ({
+			id,
+			slot: this.read(id)
+		})).filter((row) => row.slot !== null);
+		rows.sort((a, b) => b.slot.savedAt - a.slot.savedAt);
+		return rows.map((row) => row.id);
+	}
+	/** Every slot with its contents — what a load menu actually renders. */
+	all() {
+		return this.list().map((id) => ({
+			id,
+			...this.read(id)
+		}));
+	}
+	read(id) {
+		const raw = this.store.get(key(id), null);
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+		const slot = raw;
+		if (typeof slot.scene !== "string" || typeof slot.state !== "object" || slot.state === null) return null;
+		return {
+			scene: slot.scene,
+			state: slot.state,
+			label: typeof slot.label === "string" ? slot.label : "",
+			savedAt: typeof slot.savedAt === "number" ? slot.savedAt : 0,
+			playtime: typeof slot.playtime === "number" ? slot.playtime : 0,
+			data: slot.data ?? {}
+		};
+	}
+	/**
+	* Write a slot.
+	*
+	* `savedAt` is a parameter rather than `Date.now()` so a test can assert an
+	* ordering without sleeping, and so a game that wants server time can use it.
+	*/
+	write(id, slot) {
+		const full = {
+			scene: slot.scene,
+			state: slot.state,
+			label: slot.label ?? "",
+			savedAt: slot.savedAt ?? 0,
+			playtime: slot.playtime ?? 0,
+			data: slot.data ?? {}
+		};
+		this.store.set(key(id), full);
+		const ids = this.store.get(INDEX_KEY, []);
+		if (!ids.includes(id)) this.store.set(INDEX_KEY, [...ids, id]);
+	}
+	remove(id) {
+		this.store.remove(key(id));
+		this.store.set(INDEX_KEY, this.store.get(INDEX_KEY, []).filter((other) => other !== id));
+	}
+	/** Wipe every slot — a "delete all data" button, and test isolation. */
+	clear() {
+		for (const id of this.store.get(INDEX_KEY, [])) this.store.remove(key(id));
+		this.store.set(INDEX_KEY, []);
+	}
+};
+function key(id) {
+	return `slot:${id}`;
+}
+/**
+* Behaviors in this tree that hold state and cannot save it — the audit's
+* question, answerable before a player loses an hour.
+*
+* A behavior with props but no `serialize` is not necessarily wrong (an
+* `Oscillate` derives everything from time), so this reports rather than warns,
+* and the caller decides.
+*/
+function behaviorsWithoutSave(root) {
+	const out = [];
+	const walk = (node) => {
+		const behavior = node.behavior;
+		const name = node.script?.name;
+		if (behavior && typeof name === "string" && typeof behavior.serialize !== "function") {
+			if (Object.keys(behaviorSchema(name)).length > 0) out.push(`${node.getPath()} (${name})`);
+		}
+		for (const child of node.children) walk(child);
+	};
+	walk(root);
+	return out;
+}
+/**
+* Behaviors that DO save, on nodes with no uid to save them under — the state
+* that goes nowhere.
+*
+* `incanto-check` warns about the built-ins it can recognise from the JSON
+* (Health, ScoreKeeper, Collector), but a scene file cannot be asked whether
+* YOUR behavior has a `serialize`. This can: it walks the live tree, so a quest
+* log or a wallet of your own is named too.
+*
+* The pair to read before shipping: `behaviorsWithoutSave` is "did you forget
+* to write serialize", this is "did you forget the uid that makes it count".
+*/
+function savesWithoutUid(root) {
+	const out = [];
+	const walk = (node) => {
+		const behavior = node.behavior;
+		const name = node.script?.name;
+		if (behavior && typeof behavior.serialize === "function" && !node.uid) out.push(`${node.getPath()} (${name ?? "behavior"})`);
+		for (const child of node.children) walk(child);
+	};
+	walk(root);
+	return out;
+}
 //#endregion
 //#region src/core/node.ts
 function validateName(name) {
@@ -1274,6 +1613,16 @@ var SceneTree = class SceneTree {
 	_detachRoot(node) {
 		if (this._root === node) this._root = null;
 	}
+	/**
+	* @internal Is this node already on its way out?
+	*
+	* A save taken from a `collected` handler runs BEFORE the deferred free, so
+	* the pickup that triggered the checkpoint is still in the tree — and came
+	* back on the next run while its score did not.
+	*/
+	_isQueuedFree(node) {
+		return this.freeQueue.has(node);
+	}
 	flushFreeQueue() {
 		if (this.freeQueue.size === 0) return;
 		const items = [...this.freeQueue];
@@ -1681,4 +2030,4 @@ function validateUniqueUids(root) {
 	walk(root);
 }
 //#endregion
-export { getBehavior as C, Signal as E, clearBehaviors as S, registeredBehaviors as T, InputMap as _, SCENE_FORMAT as a, behaviorSchema as b, SceneTree as c, resolveConstants as d, Node as f, resolveOrderGroups as g, effectiveOrder as h, serializeNode as i, CONST_REF_KEY as l, ORDER_GROUP_BASE as m, loadScene as n, computeViewport as o, parseNodePath as p, Scene as r, resolveViewport as s, buildNodeJson as t, isConstRef as u, diagnose as v, registerBehavior as w, behaviorSignals as x, Behavior as y };
+export { registerBehavior as A, diagnose as C, behaviorSignals as D, behaviorSchema as E, Signal as M, clearBehaviors as O, InputMap as S, Behavior as T, savesWithoutUid as _, SCENE_FORMAT as a, effectiveOrder as b, SceneTree as c, resolveConstants as d, Node as f, restoreBehaviors as g, captureBehaviors as h, serializeNode as i, registeredBehaviors as j, getBehavior as k, CONST_REF_KEY as l, behaviorsWithoutSave as m, loadScene as n, computeViewport as o, SaveSlots as p, Scene as r, resolveViewport as s, buildNodeJson as t, isConstRef as u, createSaveStore as v, parseNodePath as w, resolveOrderGroups as x, ORDER_GROUP_BASE as y };

package/dist/{loader-CeyU_bm1.d.ts → loader-B9iTqs27.d.ts}

@@ -1,4 +1,4 @@
-import { P as Scene, b as Engine } from "./behavior-62q0HWBO.js";
+import { P as Scene, b as Engine } from "./behavior-uPEuZrUB.js";
 import { i as SceneJson } from "./schema-CFeioQRE.js";
 
 //#region src/core/scene/loader.d.ts