@simpludify/core 0.1.5 → 0.1.6

package/dist/index.js

@@ -1583,7 +1583,7 @@ var RandomManager = class {
 };
 // packages/core/src/foundation/version.ts
 /** Source workspace version; checked against package.json by the build validator. */
-var ENGINE_VERSION = "0.1.5";
+var ENGINE_VERSION = "0.1.6";
 // packages/core/src/scene/actor.ts
 var inputPhase$1 = ComponentPhase.Input;
 var updatePhase$1 = ComponentPhase.Update;
@@ -2814,7 +2814,7 @@ function boxCircle(box, circle, out, tolerance) {
 	out.normalY = nx * box.sin + ny * box.cos;
 	return true;
 }
-function axis(a, b, x, y, out, tolerance) {
+function axis$1(a, b, x, y, out, tolerance) {
 	const distance = (b.x - a.x) * x + (b.y - a.y) * y;
 	const depth = a.hx * Math.abs(a.cos * x + a.sin * y) + a.hy * Math.abs(-a.sin * x + a.cos * y) + (b.hx * Math.abs(b.cos * x + b.sin * y) + b.hy * Math.abs(-b.sin * x + b.cos * y)) - Math.abs(distance);
 	if (depth < -tolerance) return false;
@@ -2845,7 +2845,7 @@ function contactManifold(a, b, out, tolerance = 0) {
 	}
 	if (b.collider.shape === CollisionShape.Circle) return boxCircle(ag, bg, out, tolerance);
 	out.depth = Infinity;
-	return axis(ag, bg, ag.cos, ag.sin, out, tolerance) && axis(ag, bg, -ag.sin, ag.cos, out, tolerance) && axis(ag, bg, bg.cos, bg.sin, out, tolerance) && axis(ag, bg, -bg.sin, bg.cos, out, tolerance);
+	return axis$1(ag, bg, ag.cos, ag.sin, out, tolerance) && axis$1(ag, bg, -ag.sin, ag.cos, out, tolerance) && axis$1(ag, bg, bg.cos, bg.sin, out, tolerance) && axis$1(ag, bg, -bg.sin, bg.cos, out, tolerance);
 }
 // packages/core/src/game/collision-response.ts
 /** Translate along the minimum separation axis, preserving tangential movement intent. */
@@ -4080,6 +4080,135 @@ var TileGeometry = class TileGeometry {
 		for (let dy = -radius; dy <= radius; dy++) for (let dx = Math.max(-radius, -dy - radius); dx <= Math.min(radius, -dy + radius); dx++) yield tile(x + dx, y + dy);
 	}
 };
+// packages/core/src/interaction/gamepad-bindings.ts
+/** Standard mapping physical positions, not product-specific printed labels. */
+var GamepadButton = Object.freeze({
+	South: 0,
+	East: 1,
+	West: 2,
+	North: 3,
+	LeftShoulder: 4,
+	RightShoulder: 5,
+	LeftTrigger: 6,
+	RightTrigger: 7,
+	Select: 8,
+	Start: 9,
+	LeftStick: 10,
+	RightStick: 11,
+	DPadUp: 12,
+	DPadDown: 13,
+	DPadLeft: 14,
+	DPadRight: 15,
+	Home: 16
+});
+var GamepadAxis = Object.freeze({
+	LeftX: 0,
+	LeftY: 1,
+	RightX: 2,
+	RightY: 3
+});
+var axis = (index) => Object.freeze({ axis: index });
+/** Ready-to-use data; game Actions retain application-defined names. */
+var GamepadBindings = Object.freeze({
+	LeftStick: Object.freeze({
+		x: axis(0),
+		y: axis(1)
+	}),
+	RightStick: Object.freeze({
+		x: axis(2),
+		y: axis(3)
+	}),
+	DPad: Object.freeze({
+		x: Object.freeze({
+			negative: Object.freeze([14]),
+			positive: Object.freeze([15])
+		}),
+		y: Object.freeze({
+			negative: Object.freeze([12]),
+			positive: Object.freeze([13])
+		})
+	}),
+	Move: Object.freeze({
+		x: Object.freeze({
+			axis: 0,
+			negative: Object.freeze([14]),
+			positive: Object.freeze([15])
+		}),
+		y: Object.freeze({
+			axis: 1,
+			negative: Object.freeze([12]),
+			positive: Object.freeze([13])
+		})
+	})
+});
+var fail = () => {
+	throw new EngineError("INVALID_GAMEPAD_BINDING", "Invalid gamepad binding");
+};
+function gamepadIndex(value) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) return fail();
+	return value;
+}
+function gamepadDeadZone(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value >= 1) return fail();
+	return value;
+}
+function record(value, keys) {
+	if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((k) => !keys.includes(k))) return fail();
+	return Object.fromEntries(Object.entries(value));
+}
+function axisBinding(value) {
+	const v = record(value, [
+		"axis",
+		"invert",
+		"negative",
+		"positive",
+		"deadZone"
+	]);
+	const indices = (value) => {
+		if (value === void 0) return Object.freeze([]);
+		if (!Array.isArray(value)) return fail();
+		return Object.freeze([...new Set(value.map(gamepadIndex))]);
+	};
+	if (v.invert !== void 0 && typeof v.invert !== "boolean") return fail();
+	return Object.freeze({
+		...v.axis === void 0 ? {} : { axis: gamepadIndex(v.axis) },
+		...v.invert === void 0 ? {} : { invert: v.invert },
+		negative: indices(v.negative),
+		positive: indices(v.positive),
+		...v.deadZone === void 0 ? {} : { deadZone: gamepadDeadZone(v.deadZone) }
+	});
+}
+function checkedGamepadBindings(actions, value) {
+	const v = record(value, Object.keys(actions));
+	return Object.freeze(Object.entries(v).map(([name, binding]) => {
+		if (!Object.hasOwn(actions, name)) return fail();
+		const action = actions[name];
+		if (!action) return fail();
+		let result;
+		if (action.kind === "button") {
+			const b = record(binding, ["buttons"]);
+			if (b.buttons !== void 0 && !Array.isArray(b.buttons)) return fail();
+			result = Object.freeze({ buttons: Object.freeze((b.buttons ?? []).map((item) => {
+				if (typeof item === "number") return gamepadIndex(item);
+				const b = record(item, ["button", "threshold"]), threshold = b.threshold ?? .5;
+				if (typeof threshold !== "number" || !Number.isFinite(threshold) || threshold <= 0 || threshold > 1) return fail();
+				return Object.freeze({
+					button: gamepadIndex(b.button),
+					threshold
+				});
+			})) });
+		} else if (action.kind === "axis1d") result = axisBinding(binding);
+		else {
+			const keys = action.kind === "axis2d" ? ["x", "y"] : [
+				"x",
+				"y",
+				"z"
+			], b = record(binding, keys);
+			result = Object.freeze(Object.fromEntries(keys.map((k) => [k, axisBinding(b[k] ?? {})])));
+		}
+		return Object.freeze([action, result]);
+	}));
+}
 // packages/core/src/interaction/key-code.ts
 /** Physical UI Events code values plus F13–F24; Unidentified is not bindable. */
 var KeyCode = {
@@ -4275,6 +4404,27 @@ function parseKeyCode(value) {
 	if (!isKeyCode(value)) throw new EngineError("INVALID_KEY_CODE", "Unknown physical keyboard code", { value });
 	return value;
 }
+// packages/core/src/interaction/physical-input.ts
+var InputDevice = Object.freeze({
+	Keyboard: "keyboard",
+	Mouse: "mouse",
+	Gamepad: "gamepad"
+});
+/** Standard PointerEvent.button indices; these are not the buttons bit mask. */
+var MouseButton = Object.freeze({
+	Left: 0,
+	Middle: 1,
+	Right: 2,
+	Back: 3,
+	Forward: 4
+});
+function isMouseButton(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 4;
+}
+function parseMouseButton(value) {
+	if (!isMouseButton(value)) throw new EngineError("INVALID_MOUSE_BUTTON", "Expected a standard mouse button index (0–4)");
+	return value;
+}
 // packages/core/src/interaction/action-bindings.ts
 function checkedBinding(action, value) {
 	const record = (v, allowed) => {
@@ -4288,43 +4438,123 @@ function checkedBinding(action, value) {
 		if (!Array.isArray(v)) throw new EngineError("INVALID_BINDING", "Key list must be an array");
 		return Object.freeze([...new Set(v.map(parseKeyCode))]);
 	};
-	const axis = (v) => {
-		const r = record(v ?? {}, ["negative", "positive"]);
+	const mice = (v) => {
+		if (!Array.isArray(v)) throw new EngineError("INVALID_BINDING", "Mouse button list must be an array");
+		return Object.freeze([...new Set(v.map(parseMouseButton))]);
+	};
+	const axis = (v, root = false) => {
+		const r = record(v ?? {}, [
+			"negative",
+			"positive",
+			"mouseNegative",
+			"mousePositive",
+			...root ? ["gamepad"] : []
+		]);
 		return Object.freeze({
 			negative: codes(r.negative),
-			positive: codes(r.positive)
+			positive: codes(r.positive),
+			...r.mouseNegative === void 0 ? {} : { mouseNegative: mice(r.mouseNegative) },
+			...r.mousePositive === void 0 ? {} : { mousePositive: mice(r.mousePositive) }
 		});
 	};
-	if (action.kind === "button") return Object.freeze({ keys: codes(record(value, ["keys"]).keys) });
-	if (action.kind === "axis1d") return axis(value);
-	const r = record(value, action.kind === "axis2d" ? ["x", "y"] : [
+	const r = record(value, action.kind === "button" ? [
+		"keys",
+		"mouse",
+		"gamepad"
+	] : action.kind === "axis1d" ? [
+		"negative",
+		"positive",
+		"mouseNegative",
+		"mousePositive",
+		"gamepad"
+	] : action.kind === "axis2d" ? [
 		"x",
 		"y",
-		"z"
+		"gamepad"
+	] : [
+		"x",
+		"y",
+		"z",
+		"gamepad"
 	]);
-	return Object.freeze(action.kind === "axis2d" ? {
+	let gamepad;
+	if (r.gamepad !== void 0) {
+		const checked = checkedGamepadBindings({ [action.name]: action }, { [action.name]: r.gamepad })[0];
+		if (!checked) throw new EngineError("INVALID_BINDING", "Missing gamepad binding");
+		gamepad = checked[1];
+	}
+	const base = action.kind === "button" ? {
+		keys: codes(r.keys),
+		...r.mouse === void 0 ? {} : { mouse: mice(r.mouse) }
+	} : action.kind === "axis1d" ? axis(value, true) : action.kind === "axis2d" ? {
 		x: axis(r.x),
 		y: axis(r.y)
 	} : {
 		x: axis(r.x),
 		y: axis(r.y),
 		z: axis(r.z)
+	};
+	return Object.freeze({
+		...base,
+		...gamepad === void 0 ? {} : { gamepad }
 	});
 }
 function keyLists(binding, path = "") {
 	const lists = [];
-	for (const [key, value] of Object.entries(binding)) if (Array.isArray(value)) lists.push({
+	for (const [key, value] of Object.entries(binding)) if (key === "keys" || key === "negative" || key === "positive") lists.push({
 		path: path + key,
 		keys: value
 	});
-	else lists.push(...keyLists(value, `${path}${key}.`));
+	else if (key === "x" || key === "y" || key === "z") lists.push(...keyLists(value, `${path}${key}.`));
+	return lists;
+}
+function mouseLists(binding, path = "") {
+	const lists = [];
+	for (const [key, value] of Object.entries(binding)) if (key === "mouse" || key === "mouseNegative" || key === "mousePositive") lists.push({
+		path: path + key,
+		buttons: value
+	});
+	else if (key === "x" || key === "y" || key === "z") lists.push(...mouseLists(value, `${path}${key}.`));
 	return lists;
 }
+function gamepadControls(binding, path = "gamepad") {
+	const result = [];
+	for (const [name, value] of Object.entries(binding)) if (name === "axis" && typeof value === "number") result.push({
+		kind: "axis",
+		index: value,
+		path: `${path}.axis`
+	});
+	else if (name === "buttons" || name === "negative" || name === "positive") for (const item of value) result.push({
+		kind: "button",
+		index: typeof item === "number" ? item : item.button,
+		path: `${path}.${name}`
+	});
+	else if (name === "x" || name === "y" || name === "z") result.push(...gamepadControls(value, `${path}.${name}`));
+	return result;
+}
+function editGamepad(current, patch, remove) {
+	if (Array.isArray(patch)) {
+		const old = Array.isArray(current) ? current : [];
+		const control = (v) => v && typeof v === "object" && "button" in v ? v.button : v;
+		return remove ? old.filter((v) => !patch.some((p) => control(p) === control(v))) : [...new Map([...old, ...patch].map((v) => [JSON.stringify(v), v])).values()];
+	}
+	if (patch && typeof patch === "object") {
+		const result = current && typeof current === "object" ? { ...current } : {};
+		for (const [key, value] of Object.entries(patch)) {
+			const edited = editGamepad(result[key], value, remove);
+			if (edited === void 0) delete result[key];
+			else result[key] = edited;
+		}
+		return result;
+	}
+	return remove ? current === patch ? void 0 : current : patch;
+}
 function editBinding(current, patch, remove) {
 	const result = { ...current };
 	for (const [name, value] of Object.entries(patch)) {
 		const old = current[name];
-		if (Array.isArray(value)) result[name] = remove ? old.filter((k) => !value.includes(k)) : [.../* @__PURE__ */ new Set([...old, ...value])];
+		if (name === "gamepad") result[name] = editGamepad(old, value, remove);
+		else if (Array.isArray(value)) result[name] = remove ? (old ?? []).filter((k) => !value.includes(k)) : [.../* @__PURE__ */ new Set([...old ?? [], ...value])];
 		else result[name] = editBinding(old, value, remove);
 	}
 	return result;
@@ -4522,6 +4752,9 @@ var ActionController = class {
 	bus = new EventBus();
 	keyboardAllowed = true;
 	blockedKeys = /* @__PURE__ */ new Set();
+	mouseAllowed = true;
+	blockedMouse = /* @__PURE__ */ new Set();
+	bindingGeneration = 0;
 	pending = [];
 	transitions = [];
 	constructor(actions, options) {
@@ -4529,6 +4762,8 @@ var ActionController = class {
 		this.options = options;
 		if (options.keyboard !== void 0 && typeof options.keyboard !== "boolean") throw new EngineError("INVALID_VALUE", "Keyboard enabled must be boolean");
 		this.keyboardAllowed = options.keyboard ?? true;
+		if (options.mouse !== void 0 && typeof options.mouse !== "boolean") throw new EngineError("INVALID_VALUE", "Mouse enabled must be boolean");
+		this.mouseAllowed = options.mouse ?? true;
 		for (const action of Object.values(actions)) {
 			const binding = checkedBinding(action, options.bindings && Object.hasOwn(options.bindings, action.name) ? options.bindings[action.name] ?? {} : {});
 			const value = neutral(action);
@@ -4575,6 +4810,24 @@ var ActionController = class {
 	get sourceCount() {
 		return this.sources.size;
 	}
+	get mouseEnabled() {
+		return this.mouseAllowed;
+	}
+	set mouseEnabled(value) {
+		if (this.disposed) throw new EngineError("OWNER_DISPOSED", "Action controller has been disposed");
+		if (typeof value !== "boolean") throw new EngineError("INVALID_VALUE", "Mouse enabled must be boolean");
+		if (value === this.mouseAllowed) return;
+		this.mouseAllowed = value;
+		this.blockedMouse.clear();
+		if (value) {
+			for (const entry of this.entries.values()) for (const list of mouseLists(entry.binding)) for (const button of list.buttons) if (this.options.input.mouseDown(button)) this.blockedMouse.add(button);
+		}
+		for (const action of this.entries.keys()) this.recompute(action);
+	}
+	/** @internal Used by existing host adapters to follow common binding settings. */
+	get bindingRevision() {
+		return this.bindingGeneration;
+	}
 	onDispose(callback) {
 		return this.lifetime.onDispose(callback);
 	}
@@ -4653,13 +4906,13 @@ var ActionController = class {
 		}
 		return source;
 	}
-	/** @internal */ write(source, action, value) {
+	/** @internal */ write(source, action, value, edges = true) {
 		this.options.input.assertWrite(isNeutral(value));
 		this.entry(action);
 		const values = this.sources.get(source);
 		if (!values) throw new EngineError("OWNER_DISPOSED", "Action source has been disposed");
 		values.set(action, value);
-		this.recompute(action);
+		this.recompute(action, edges);
 	}
 	/** @internal */ clearSource(source, remove) {
 		const values = this.sources.get(source);
@@ -4670,11 +4923,11 @@ var ActionController = class {
 		if (!this.disposed) for (const action of actions) this.recompute(action);
 	}
 	keyboard(action) {
-		if (!this.keyboardAllowed) return neutral(action);
 		const binding = this.entry(action).binding;
-		const held = (keys) => keys?.some((k) => !this.blockedKeys.has(k) && this.options.input.keyDown(k)) ?? false;
-		const axis = (b) => Number(held(b?.positive)) - Number(held(b?.negative));
-		if (action.kind === "button") return held(binding.keys);
+		const held = (keys) => this.keyboardAllowed && (keys?.some((k) => !this.blockedKeys.has(k) && this.options.input.keyDown(k)) ?? false);
+		const mouse = (buttons) => this.mouseAllowed && (buttons?.some((b) => !this.blockedMouse.has(b) && this.options.input.mouseDown(b)) ?? false);
+		const axis = (b) => Number(held(b?.positive) || mouse(b?.mousePositive)) - Number(held(b?.negative) || mouse(b?.mouseNegative));
+		if (action.kind === "button") return held(binding.keys) || mouse(binding.mouse);
 		if (action.kind === "axis1d") return axis(binding);
 		const b = binding;
 		return action.kind === "axis2d" ? {
@@ -4727,11 +4980,15 @@ var ActionController = class {
 	}
 	/** @internal */ keyChanged() {
 		for (const key of this.blockedKeys) if (!this.options.input.keyDown(key)) this.blockedKeys.delete(key);
+		for (const button of this.blockedMouse) if (!this.options.input.mouseDown(button)) this.blockedMouse.delete(button);
 		if (this.active || !this.disposed && this.options.scene.inputOwner === this.options.input && (this.options.scene.state === SceneState.Preparing || this.options.scene.state === SceneState.Ready)) for (const action of this.entries.keys()) this.recompute(action);
 	}
 	/** @internal */ accepts(code) {
 		return this.active && this.keyboardAllowed && [...this.entries.values()].some((e) => keyLists(e.binding).some((list) => list.keys.includes(code)));
 	}
+	/** @internal */ acceptsMouse(button) {
+		return this.active && this.mouseAllowed && [...this.entries.values()].some((e) => mouseLists(e.binding).some((list) => list.buttons.includes(button)));
+	}
 	/** @internal */ capture(override) {
 		if (!this.active) return;
 		const tokens = override ? new Map([...this.entries.keys()].map((a) => [a.name, a])) : void 0;
@@ -4773,16 +5030,25 @@ var ActionController = class {
 	/** Clears held contributions and unconsumed edges; no synthetic button release. */
 	reset() {
 		this.blockedKeys.clear();
+		this.blockedMouse.clear();
 		for (const values of this.sources.values()) values.clear();
 		this.pending = [];
 		for (const [action, entry] of this.entries) entry.value = neutral(action);
 	}
+	/** @internal Flush device transitions without destroying explicit program values. */
+	resetPhysical() {
+		this.blockedKeys.clear();
+		this.blockedMouse.clear();
+		this.pending = [];
+		for (const action of this.entries.keys()) this.recompute(action, false);
+	}
 	getBinding(action) {
 		return this.entry(action).binding;
 	}
 	rebind(action, binding) {
 		const checked = checkedBinding(action, binding), entry = this.entry(action);
 		entry.binding = checked;
+		this.bindingGeneration++;
 		this.pending = this.pending.filter((event) => event.action !== action);
 		this.recompute(action, false);
 	}
@@ -4795,7 +5061,13 @@ var ActionController = class {
 	resetBindings(action) {
 		for (const token of action ? [action] : this.entries.keys()) this.rebind(token, this.entry(token).defaults);
 	}
-	conflicts() {
+	conflicts(device = "keyboard") {
+		if (![
+			"keyboard",
+			"mouse",
+			"gamepad",
+			"all"
+		].includes(device)) throw new EngineError("INVALID_BINDING", "Unknown conflict device");
 		const keys = /* @__PURE__ */ new Map();
 		for (const [action, entry] of this.entries) for (const list of keyLists(entry.binding)) for (const key of list.keys) {
 			const group = keys.get(key) ?? [];
@@ -4805,10 +5077,54 @@ var ActionController = class {
 			});
 			keys.set(key, group);
 		}
-		return [...keys].filter(([, bindings]) => bindings.length > 1).map(([key, bindings]) => ({
+		const keyboard = [...keys].filter(([, bindings]) => bindings.length > 1).map(([key, bindings]) => ({
 			key,
 			bindings
 		}));
+		if (device === "keyboard") return keyboard;
+		const mice = /* @__PURE__ */ new Map();
+		const pads = /* @__PURE__ */ new Map();
+		for (const [action, entry] of this.entries) {
+			for (const list of mouseLists(entry.binding)) for (const button of list.buttons) {
+				const uses = mice.get(button) ?? [];
+				uses.push({
+					action,
+					path: list.path
+				});
+				mice.set(button, uses);
+			}
+			const pad = entry.binding.gamepad;
+			if (pad) for (const input of gamepadControls(pad)) {
+				const key = `${input.kind}:${input.index}`;
+				const group = pads.get(key) ?? {
+					kind: input.kind,
+					index: input.index,
+					bindings: []
+				};
+				group.bindings.push({
+					action,
+					path: input.path
+				});
+				pads.set(key, group);
+			}
+		}
+		const mouse = [...mice].filter(([, uses]) => uses.length > 1).map(([button, bindings]) => ({
+			device: "mouse",
+			button,
+			bindings
+		}));
+		const gamepad = [...pads.values()].filter((group) => group.bindings.length > 1).map((group) => ({
+			device: "gamepad",
+			...group
+		}));
+		return device === "mouse" ? mouse : device === "gamepad" ? gamepad : [
+			...keyboard.map((group) => ({
+				device: "keyboard",
+				...group
+			})),
+			...mouse,
+			...gamepad
+		];
 	}
 	exportBindings() {
 		return {
@@ -4847,6 +5163,10 @@ var ActionSource = class extends OwnedInputSource {
 		const checked = checkedActionValue(action, value);
 		if (this.writable(isNeutral(checked))) this.controller.write(this, action, checked);
 	}
+	/** @internal Reset one device binding without synthesizing logical edges. */
+	resetBinding(action) {
+		if (this.writable(true)) this.controller.write(this, action, neutral(action), false);
+	}
 	release(remove) {
 		this.controller.clearSource(this, remove);
 	}
@@ -4869,20 +5189,38 @@ var KeyboardSource = class extends OwnedInputSource {
 		this.input.releaseKeyboard(this, remove);
 	}
 };
+/** Physical mouse contribution; game state is read through ActionController. */
+var MouseSource = class extends OwnedInputSource {
+	input;
+	/** @internal */ constructor(input) {
+		super();
+		this.input = input;
+	}
+	set(button, pressed) {
+		parseMouseButton(button);
+		if (typeof pressed !== "boolean") throw new EngineError("INVALID_VALUE", "Mouse state must be boolean");
+		if (this.writable(!pressed)) this.input.writeMouse(this, button, pressed);
+	}
+	release(remove) {
+		this.input.releaseMouse(this, remove);
+	}
+};
 /** Engine-owned routing and update boundary. No raw game-state/alternate movement API. */
 var InputSystem = class {
 	actions = /* @__PURE__ */ new Set();
 	adapters = /* @__PURE__ */ new Set();
 	keyboards = /* @__PURE__ */ new Map();
+	mice = /* @__PURE__ */ new Map();
+	captureCancel;
 	dead = false;
 	playback = false;
 	frames;
 	/** @internal Device hosts may reject live gestures during Replay playback. */
 	get liveInput() {
-		return !this.dead && !this.playback;
+		return !this.dead && !this.playback && !this.captureCancel;
 	}
 	get sourceCount() {
-		let count = this.keyboards.size;
+		let count = this.keyboards.size + this.mice.size;
 		for (const actions of this.actions) count += actions.sourceCount;
 		return count;
 	}
@@ -4902,10 +5240,19 @@ var InputSystem = class {
 		};
 	}
 	acceptsKey(code) {
-		if (this.playback) return false;
+		if (!this.liveInput) return false;
 		for (const actions of this.actions) if (actions.accepts(code)) return true;
 		return false;
 	}
+	acceptsMouse(button) {
+		if (!this.liveInput) return false;
+		for (const actions of this.actions) if (actions.acceptsMouse(button)) return true;
+		return false;
+	}
+	/** @internal */ mouseDown(button) {
+		for (const buttons of this.mice.values()) if (buttons.has(button)) return true;
+		return false;
+	}
 	notify() {
 		for (const actions of this.actions) actions.keyChanged();
 	}
@@ -4949,10 +5296,42 @@ var InputSystem = class {
 		}
 		return source;
 	}
+	createMouseSource(owner) {
+		if (this.dead || owner?.disposed) throw new EngineError("OWNER_DISPOSED", "Input owner has been disposed");
+		const source = new MouseSource(this);
+		this.mice.set(source, /* @__PURE__ */ new Set());
+		try {
+			if (owner) source.own(owner);
+		} catch (error) {
+			source.dispose();
+			throw error;
+		}
+		return source;
+	}
+	/** @internal */ writeMouse(source, button, pressed) {
+		this.assertWrite(!pressed);
+		const buttons = this.mice.get(source);
+		if (!buttons || this.dead) throw new EngineError("OWNER_DISPOSED", "Input has been disposed");
+		if (this.captureCancel && pressed) return;
+		if (buttons.has(button) === pressed) return;
+		const before = this.mouseDown(button);
+		if (pressed) buttons.add(button);
+		else buttons.delete(button);
+		if (before !== this.mouseDown(button)) this.notify();
+	}
+	/** @internal */ releaseMouse(source, remove) {
+		const buttons = this.mice.get(source);
+		if (!buttons) return;
+		const changed = buttons.size > 0;
+		buttons.clear();
+		if (remove) this.mice.delete(source);
+		if (changed && !this.dead) this.notify();
+	}
 	/** @internal */ writeKey(source, code, pressed) {
 		this.assertWrite(!pressed);
 		const keys = this.keyboards.get(source);
 		if (!keys || this.dead) throw new EngineError("OWNER_DISPOSED", "Input has been disposed");
+		if (this.captureCancel && pressed) return;
 		if (keys.has(code) === pressed) return;
 		const before = this.keyDown(code);
 		if (pressed) keys.add(code);
@@ -4991,11 +5370,41 @@ var InputSystem = class {
 		this.playback = false;
 		this.clear();
 	}
-	clear() {
+	/** @internal Host capture gate. Program ActionSource values remain explicit. */
+	suspendLiveInput(cancel) {
+		if (!this.liveInput) throw new EngineError("INPUT_CAPTURE_UNAVAILABLE", "Live input is unavailable or another capture is active");
+		this.captureCancel = cancel;
+		try {
+			this.resetPhysical();
+		} catch (error) {
+			this.captureCancel = void 0;
+			throw error;
+		}
+		return () => {
+			if (this.captureCancel !== cancel) return;
+			this.captureCancel = void 0;
+			this.resetPhysical();
+		};
+	}
+	resetPhysical() {
 		for (const keys of this.keyboards.values()) keys.clear();
-		cleanupAll([...[...this.actions].map((actions) => () => actions.reset()), ...[...this.adapters].map((adapter) => () => {
+		for (const buttons of this.mice.values()) buttons.clear();
+		cleanupAll([...[...this.adapters].map((adapter) => () => {
 			if (this.adapters.has(adapter)) adapter.reset();
-		})], "Input reset failed");
+		}), ...[...this.actions].map((actions) => () => actions.resetPhysical())], "Physical input reset failed");
+	}
+	clear() {
+		const cancel = this.captureCancel;
+		this.captureCancel = void 0;
+		for (const keys of this.keyboards.values()) keys.clear();
+		for (const buttons of this.mice.values()) buttons.clear();
+		cleanupAll([
+			() => cancel?.(),
+			...[...this.actions].map((actions) => () => actions.reset()),
+			...[...this.adapters].map((adapter) => () => {
+				if (this.adapters.has(adapter)) adapter.reset();
+			})
+		], "Input reset failed");
 	}
 	/** Device diagnostics only; game state is ActionController.snapshot(). */
 	snapshot() {
@@ -5006,18 +5415,122 @@ var InputSystem = class {
 	dispose() {
 		if (this.dead) return;
 		this.dead = true;
+		const cancel = this.captureCancel;
+		this.captureCancel = void 0;
 		try {
 			cleanupAll([
+				() => cancel?.(),
 				...[...this.adapters].map((a) => () => a.dispose()),
 				...[...this.actions].map((a) => () => a.dispose()),
-				...[...this.keyboards.keys()].map((s) => () => s.dispose())
+				...[...this.keyboards.keys()].map((s) => () => s.dispose()),
+				...[...this.mice.keys()].map((s) => () => s.dispose())
 			], "Input cleanup failed");
 		} finally {
 			this.adapters.clear();
 			this.actions.clear();
 			this.keyboards.clear();
+			this.mice.clear();
+		}
+	}
+};
+// packages/core/src/interaction/input-capture.ts
+var InputCaptureState = Object.freeze({
+	Arming: "arming",
+	Listening: "listening",
+	Completed: "completed",
+	Cancelled: "cancelled"
+});
+/** A portable single-input session. Hosts supply neutral arming and physical events. */
+var InputCapture = class {
+	life = new Lifetime();
+	status = InputCaptureState.Arming;
+	devices;
+	gamepadIndex;
+	result;
+	settle = () => {};
+	constructor(options = {}) {
+		if (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some((key) => ![
+			"devices",
+			"gamepadIndex",
+			"owner"
+		].includes(key))) throw new EngineError("INVALID_INPUT_CAPTURE", "Invalid input capture options");
+		const devices = options.devices ?? Object.values(InputDevice);
+		if (!Array.isArray(devices) || !devices.length || devices.some((device) => !Object.values(InputDevice).includes(device))) throw new EngineError("INVALID_INPUT_CAPTURE", "Select at least one known capture device");
+		this.devices = Object.freeze([...new Set(devices)]);
+		this.gamepadIndex = options.gamepadIndex === void 0 ? void 0 : gamepadIndex(options.gamepadIndex);
+		if (options.owner?.disposed) throw new EngineError("OWNER_DISPOSED", "Capture owner has been disposed");
+		this.result = new Promise((resolve) => {
+			this.settle = resolve;
+		});
+		if (options.owner) this.life.onDispose(options.owner.onDispose(() => this.cancel()));
+	}
+	get state() {
+		return this.status;
+	}
+	get disposed() {
+		return this.life.disposed;
+	}
+	onDispose(callback) {
+		return this.life.onDispose(callback);
+	}
+	/** @internal Hosts call only after all eligible preheld buttons/keys are neutral. */
+	arm() {
+		if (this.status === InputCaptureState.Arming) this.status = InputCaptureState.Listening;
+	}
+	/** @internal Offer one fresh physical down, never a repeat or opening gesture. */
+	accept(input) {
+		if (this.status !== InputCaptureState.Listening) return false;
+		if (!input || typeof input !== "object" || !Object.values(InputDevice).includes(input.device)) throw new EngineError("INVALID_INPUT_CAPTURE", "Unknown physical input device");
+		if (!this.devices.includes(input.device)) return false;
+		let descriptor, binding;
+		if (input.device === InputDevice.Keyboard) {
+			const code = parseKeyCode(input.code);
+			descriptor = {
+				device: InputDevice.Keyboard,
+				code
+			};
+			binding = Object.freeze({ keys: Object.freeze([code]) });
+		} else if (input.device === InputDevice.Mouse) {
+			const button = parseMouseButton(input.button);
+			descriptor = {
+				device: InputDevice.Mouse,
+				button
+			};
+			binding = Object.freeze({ mouse: Object.freeze([button]) });
+		} else {
+			const index = gamepadIndex(input.index), button = gamepadIndex(input.button);
+			if (this.gamepadIndex !== void 0 && this.gamepadIndex !== index) return false;
+			if (typeof input.id !== "string" || typeof input.mapping !== "string") throw new EngineError("INVALID_INPUT_CAPTURE", "Gamepad capture requires device facts");
+			descriptor = {
+				device: InputDevice.Gamepad,
+				index,
+				button,
+				id: input.id,
+				mapping: input.mapping
+			};
+			binding = Object.freeze({ gamepad: Object.freeze({ buttons: Object.freeze([button]) }) });
+		}
+		this.finish(InputCaptureState.Completed, Object.freeze({
+			...descriptor,
+			binding
+		}));
+		return true;
+	}
+	finish(state, input) {
+		if (this.disposed) return;
+		this.status = state;
+		try {
+			this.life.dispose();
+		} finally {
+			this.settle(input);
 		}
 	}
+	cancel() {
+		this.finish(InputCaptureState.Cancelled, void 0);
+	}
+	dispose() {
+		this.cancel();
+	}
 };
 // packages/core/src/ui/canvas-layout.ts
 var finite = (v) => {
@@ -5535,6 +6048,11 @@ var PointerRouting = class {
 	owns(id) {
 		return this.gestures.has(id) || this.suppressed.has(id);
 	}
+	/** @internal Mouse bindings observe world ownership without claiming a second gesture. */
+	worldOwns(id) {
+		const gesture = this.gestures.get(id);
+		return Boolean(gesture && !gesture.node && !gesture.target && !gesture.scroll && !gesture.candidates.length);
+	}
 	move(data) {
 		this.validate(data);
 		if (this.suppressed.has(data.pointerId)) return;
@@ -7082,7 +7600,7 @@ var ReplayPlayer = class {
 		this.engine = engine;
 		this.data = parseReplayData(data);
 		this.bound = bindings(engine, options.controllers);
-		if (this.data.engineVersion !== "0.1.5" || engine.random.seed !== this.data.random.seed) throw new EngineError("REPLAY_INCOMPATIBLE", "Engine version or initial seed does not match Replay");
+		if (this.data.engineVersion !== "0.1.6" || engine.random.seed !== this.data.random.seed) throw new EngineError("REPLAY_INCOMPATIBLE", "Engine version or initial seed does not match Replay");
 		if (!compatible(this.bound.map(([id, c]) => ({
 			id,
 			actions: c.schema()
@@ -8980,6 +9498,6 @@ var CanvasUI = class {
 		], "Canvas UI cleanup failed");
 	}
 };
-export { Action, ActionController, ActionMovement, ActionSource, Actor, ActorState, Aspect, BodyType, Camera, CameraFollow, Cancellation, CanvasButton, CanvasCheckbox, CanvasCheckboxNode, CanvasColumn, CanvasHoldButton, CanvasInputNode, CanvasLabel, CanvasNode, CanvasNumberInput, CanvasNumberInputNode, CanvasPanel, CanvasRow, CanvasScroll, CanvasSelect, CanvasSelectNode, CanvasSlider, CanvasSliderNode, CanvasTextEditorNode, CanvasTextInput, CanvasTextInputNode, CanvasUI, Character, CharacterActor, Collider, CollisionBody, CollisionResponse, CollisionShape, CollisionWorld, Component, ComponentPhase, ContactEnter, ContactExit, ContactStay, DEFAULT_RANDOM_STREAM, ENGINE_VERSION, Easing, Engine, EngineError, EventBus, FixedStepRunner, GeometryTilemap, GeometryTilemapLayer, Grid, HexOrientation, InputSystem, KeyCode, KeyboardBindings, KeyboardSource, Lifetime, Motion, PointerCancel, PointerClick, PointerDown, PointerEnter, PointerLeave, PointerMove, PointerRouting, PointerUp, RANDOM_ALGORITHM, RandomManager, RandomStream, Renderable, ReplayPlayer, ReplayRecorder, Scene, ScenePointer, SceneState, Shape, SpriteAnimation, SpriteAnimationState, SpriteFit, SpriteSheet, TileContactEnter, TileContactExit, TileContactStay, TileGeometry, Tilemap, TilemapLayer, Transform, Tween, TweenBinding, TweenPlayback, TweenScheduler, VirtualButton, VirtualControl, VirtualInput, VirtualRegions, VirtualStick, VirtualStickMode, actorTween, canvasControlText, canvasHoverHighlight, canvasNumericRange, canvasNumericValue, canvasOpacity, canvasScrollbars, canvasSliderGeometry, canvasTween, cleanupAll, containsScreenPoint, containsUI, createViewTransform, defaultCanvasStyle, defineActions, defineComponent, defineEvent, deriveStreamSeed, imageSize, intersectUI, isKeyCode, layoutCanvas, nativeSession, parseKeyCode, parseReplayData, positive, screenPoint, screenToPhysical, screenToWorld, scrollbarContains, sliderTween, spriteFrame, spriteFrameBounds, tweenFinite, worldPoint, worldToScreen, wrapCanvasText };
+export { Action, ActionController, ActionMovement, ActionSource, Actor, ActorState, Aspect, BodyType, Camera, CameraFollow, Cancellation, CanvasButton, CanvasCheckbox, CanvasCheckboxNode, CanvasColumn, CanvasHoldButton, CanvasInputNode, CanvasLabel, CanvasNode, CanvasNumberInput, CanvasNumberInputNode, CanvasPanel, CanvasRow, CanvasScroll, CanvasSelect, CanvasSelectNode, CanvasSlider, CanvasSliderNode, CanvasTextEditorNode, CanvasTextInput, CanvasTextInputNode, CanvasUI, Character, CharacterActor, Collider, CollisionBody, CollisionResponse, CollisionShape, CollisionWorld, Component, ComponentPhase, ContactEnter, ContactExit, ContactStay, DEFAULT_RANDOM_STREAM, ENGINE_VERSION, Easing, Engine, EngineError, EventBus, FixedStepRunner, GamepadAxis, GamepadBindings, GamepadButton, GeometryTilemap, GeometryTilemapLayer, Grid, HexOrientation, InputCapture, InputCaptureState, InputDevice, InputSystem, KeyCode, KeyboardBindings, KeyboardSource, Lifetime, Motion, MouseButton, MouseSource, PointerCancel, PointerClick, PointerDown, PointerEnter, PointerLeave, PointerMove, PointerRouting, PointerUp, RANDOM_ALGORITHM, RandomManager, RandomStream, Renderable, ReplayPlayer, ReplayRecorder, Scene, ScenePointer, SceneState, Shape, SpriteAnimation, SpriteAnimationState, SpriteFit, SpriteSheet, TileContactEnter, TileContactExit, TileContactStay, TileGeometry, Tilemap, TilemapLayer, Transform, Tween, TweenBinding, TweenPlayback, TweenScheduler, VirtualButton, VirtualControl, VirtualInput, VirtualRegions, VirtualStick, VirtualStickMode, actorTween, canvasControlText, canvasHoverHighlight, canvasNumericRange, canvasNumericValue, canvasOpacity, canvasScrollbars, canvasSliderGeometry, canvasTween, checkedGamepadBindings, cleanupAll, containsScreenPoint, containsUI, createViewTransform, defaultCanvasStyle, defineActions, defineComponent, defineEvent, deriveStreamSeed, gamepadDeadZone, gamepadIndex, imageSize, intersectUI, isKeyCode, isMouseButton, layoutCanvas, nativeSession, parseKeyCode, parseMouseButton, parseReplayData, positive, screenPoint, screenToPhysical, screenToWorld, scrollbarContains, sliderTween, spriteFrame, spriteFrameBounds, tweenFinite, worldPoint, worldToScreen, wrapCanvasText };
 
 //# sourceMappingURL=index.js.map