@simpludify/core 0.1.4 → 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.4";
+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,16 +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 && !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;
 	}
@@ -4898,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();
 	}
@@ -4945,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);
@@ -4987,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() {
@@ -5002,19 +5415,123 @@ 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) => {
 	if (!Number.isFinite(v) || v < 0) throw new EngineError("INVALID_UI", "UI layout overflow");
@@ -5309,6 +5826,18 @@ var ScenePointer = class {
 	lifetime = new Lifetime();
 	events = new EventBus();
 	removeScene;
+	targets;
+	/** @internal Exactly one Scene virtual-input provider shares the existing router. */
+	attachTargets(provider) {
+		if (this.disposed || this.targets) throw new EngineError("INVALID_VIRTUAL_INPUT", "Scene already has virtual input or is disposed");
+		this.targets = provider;
+		return () => {
+			if (this.targets === provider) this.targets = void 0;
+		};
+	}
+	/** @internal */ pickTarget(data) {
+		return this.targets?.disposed ? void 0 : this.targets?.pick(data);
+	}
 	constructor(scene) {
 		this.scene = scene;
 		this.removeScene = scene.onDispose(() => this.dispose());
@@ -5331,6 +5860,7 @@ var ScenePointer = class {
 /** @internal Device-independent routing state; DOM is only an adapter. */
 var PointerRouting = class {
 	released;
+	targetOwners = /* @__PURE__ */ new Map();
 	controlOwners = /* @__PURE__ */ new Map();
 	scrollOwners = /* @__PURE__ */ new Map();
 	suppressed = /* @__PURE__ */ new Set();
@@ -5355,7 +5885,8 @@ var PointerRouting = class {
 			keyboardNodes: this.keys.size,
 			deliveries: this.deliveries,
 			scrollDrags: this.scrollOwners.size,
-			controlDrags: this.controlOwners.size
+			controlDrags: this.controlOwners.size,
+			virtualDrags: this.targetOwners.size
 		};
 	}
 	setScene(channel, ui) {
@@ -5381,6 +5912,14 @@ var PointerRouting = class {
 		}
 	}
 	emit(gesture, type, info) {
+		if (gesture.target) {
+			const phase = type === PointerDown ? "down" : type === PointerMove ? "move" : type === PointerUp ? "up" : type === PointerCancel ? "cancel" : void 0;
+			if (phase) {
+				this.deliveries++;
+				gesture.target.deliver(phase, info);
+			}
+			return;
+		}
 		if (gesture.channel.disposed || gesture.node?.disposed) return;
 		this.deliveries++;
 		(gesture.node?.events ?? gesture.channel.events).emit(type, info);
@@ -5388,7 +5927,7 @@ var PointerRouting = class {
 	inside(g, data) {
 		return Object.freeze({
 			...data,
-			inside: g.scroll && g.ui ? g.ui.containsNode(g.scroll, data.screen.x / g.ui.scale, data.screen.y / g.ui.scale) : g.node ? g.ui?.hitTest(data.screen.x / g.ui.scale, data.screen.y / g.ui.scale) === g.node : data.inside
+			inside: g.target ? g.target.contains(data) : g.scroll && g.ui ? g.ui.containsNode(g.scroll, data.screen.x / g.ui.scale, data.screen.y / g.ui.scale) : g.node ? g.ui?.hitTest(data.screen.x / g.ui.scale, data.screen.y / g.ui.scale) === g.node : data.inside
 		});
 	}
 	down(data) {
@@ -5398,6 +5937,11 @@ var PointerRouting = class {
 		this.suppressed.delete(data.pointerId);
 		const pick = this.ui?.pick(data.screen.x / this.ui.scale, data.screen.y / this.ui.scale);
 		const node = pick?.node, bar = pick?.bar;
+		const target = !node && data.button === 0 ? this.channel.pickTarget(data) : void 0;
+		if (target && this.targetOwners.has(target)) {
+			this.suppressed.add(data.pointerId);
+			return;
+		}
 		if (bar && data.button === 0 && (!bar.enabled || this.scrollOwners.has(bar.node))) {
 			this.suppressed.add(data.pointerId);
 			return node;
@@ -5406,20 +5950,24 @@ var PointerRouting = class {
 			this.suppressed.add(data.pointerId);
 			return node;
 		}
-		if (!node && !data.inside) return;
+		if (!node && !target && !data.inside) return;
 		const g = {
 			channel: this.channel,
 			last: data,
 			primary: data.button === 0,
 			start: data,
 			scale: this.ui?.scale ?? 1,
-			candidates: this.ui?.scrollTargets(data.screen.x / this.ui.scale, data.screen.y / this.ui.scale) ?? [],
+			candidates: !target ? this.ui?.scrollTargets(data.screen.x / this.ui.scale, data.screen.y / this.ui.scale) ?? [] : [],
 			candidateRevisions: [],
 			vx: 0,
 			vy: 0,
 			...node ? {
 				node,
 				ui: this.ui
+			} : {},
+			...target ? {
+				target,
+				targetRevision: target.revision
 			} : {}
 		};
 		g.candidateRevisions = g.candidates.map((n) => n.scrollRevision);
@@ -5441,6 +5989,17 @@ var PointerRouting = class {
 		if (node?.control) g.controlRevision = node.control.revision;
 		this.gestures.set(data.pointerId, g);
 		if (node) g.off = node.onDispose(() => this.cancel(data.pointerId));
+		if (target) {
+			this.targetOwners.set(target, data.pointerId);
+			const off = target.subscribe(() => {
+				if (!target.available || target.revision !== g.targetRevision) this.cancel(data.pointerId);
+			});
+			const disposed = target.onDispose(() => this.cancel(data.pointerId));
+			g.off = () => {
+				off();
+				disposed();
+			};
+		}
 		cleanupAll([
 			() => {
 				const port = node?.control;
@@ -5489,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;
@@ -5498,7 +6062,7 @@ var PointerRouting = class {
 				const dx = Math.abs(data.screen.x - g.start.screen.x), dy = Math.abs(data.screen.y - g.start.screen.y);
 				if (dx >= g.control.style.dragThreshold && dx > dy) g.controlLocked = true;
 			}
-			if (!g.scroll && g.primary && !g.controlLocked) this.claimScroll(g, data);
+			if (!g.target && !g.scroll && g.primary && !g.controlLocked) this.claimScroll(g, data);
 			if (this.gestures.get(data.pointerId) !== g) return;
 			if (g.bar && g.scroll && g.ui) {
 				const bar = canvasScrollbars(g.scroll).find((b) => b.axis === g.bar?.axis);
@@ -5639,6 +6203,7 @@ var PointerRouting = class {
 		g = this.gestures.get(data.pointerId);
 		if (!g) return;
 		this.gestures.delete(data.pointerId);
+		if (g.target) this.targetOwners.delete(g.target);
 		if (g.control) this.controlOwners.delete(g.control);
 		if (g.scroll) {
 			this.scrollOwners.delete(g.scroll);
@@ -5656,7 +6221,7 @@ var PointerRouting = class {
 				if (!g.node || g.node.available) this.emit(g, PointerUp, info);
 			},
 			() => {
-				if (!g.scroll && g.primary && info.inside && (!g.node || g.node.available)) this.emit(g, PointerClick, info);
+				if (!g.target && !g.scroll && g.primary && info.inside && (!g.node || g.node.available)) this.emit(g, PointerClick, info);
 			},
 			() => {
 				if (!g.scroll && g.primary && info.inside && g.node?.available) g.node.activate("pointer");
@@ -5668,6 +6233,7 @@ var PointerRouting = class {
 		const g = this.gestures.get(id);
 		if (!g) return;
 		this.gestures.delete(id);
+		if (g.target) this.targetOwners.delete(g.target);
 		if (g.control) this.controlOwners.delete(g.control);
 		if (g.scroll) {
 			this.scrollOwners.delete(g.scroll);
@@ -5738,6 +6304,10 @@ var PointerRouting = class {
 			...[...this.keys.keys()].map((n) => () => this.releaseKeys(n))
 		], "Pointer release failed");
 	}
+	/** @internal Host focus changes interrupt virtual devices without changing Canvas editing rules. */
+	releaseVirtual() {
+		cleanupAll([...this.gestures].filter(([, g]) => g.target).map(([id]) => () => this.cancel(id)), "Virtual pointer release failed");
+	}
 	dispose() {
 		try {
 			this.reset();
@@ -5753,6 +6323,716 @@ var PointerRouting = class {
 		cleanupAll([...off, () => this.release()], "Pointer routing cleanup failed");
 	}
 };
+// packages/core/src/interaction/virtual-regions.ts
+var VirtualRegions = Object.freeze({
+	/** A shared edge is not an overlap. Use separate rectangles to leave a center gap. */
+	Left: Object.freeze({
+		kind: "rect",
+		x: 0,
+		y: 0,
+		width: .5,
+		height: 1
+	}),
+	Right: Object.freeze({
+		kind: "rect",
+		x: .5,
+		y: 0,
+		width: .5,
+		height: 1
+	})
+});
+/** @internal */
+function virtualFinite(value, field) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new EngineError("INVALID_VIRTUAL_INPUT", `${field} must be finite`);
+	return value;
+}
+/** @internal */
+function virtualBounds(value) {
+	const result = {
+		x: virtualFinite(value.x, "x"),
+		y: virtualFinite(value.y, "y"),
+		width: virtualFinite(value.width, "width"),
+		height: virtualFinite(value.height, "height")
+	};
+	if (result.width < 0 || result.height < 0 || !Number.isFinite(result.x + result.width) || !Number.isFinite(result.y + result.height)) throw new EngineError("INVALID_VIRTUAL_INPUT", "Region extents must be finite and nonnegative");
+	return Object.freeze(result);
+}
+/** @internal */
+function virtualPosition(value, viewport) {
+	const space = value.space ?? "viewport";
+	if (space !== "viewport" && space !== "screen") throw new EngineError("INVALID_VIRTUAL_INPUT", "Unknown virtual coordinate space");
+	const x = virtualFinite(value.x, "position.x"), y = virtualFinite(value.y, "position.y");
+	return Object.freeze(space === "screen" ? {
+		x,
+		y
+	} : {
+		x: virtualFinite(viewport.x + x * viewport.width, "resolved x"),
+		y: virtualFinite(viewport.y + y * viewport.height, "resolved y")
+	});
+}
+/** @internal Copy configuration before retaining it. Predicate functions are deliberately live. */
+function checkedVirtualRegion(region) {
+	if (!region || ![
+		"rect",
+		"circle",
+		"custom"
+	].includes(region.kind)) throw new EngineError("INVALID_VIRTUAL_INPUT", "Unknown activation region");
+	const copy = Object.freeze({ ...region });
+	if (copy.kind === "custom") {
+		if (typeof copy.bounds !== "function" || typeof copy.contains !== "function") throw new EngineError("INVALID_VIRTUAL_INPUT", "Custom regions require bounds and contains");
+	} else resolveVirtualRegion(copy, {
+		x: 0,
+		y: 0,
+		width: 1,
+		height: 1
+	});
+	return copy;
+}
+/** @internal */
+function resolveVirtualRegion(region, viewport) {
+	if (region.kind === "custom") {
+		if (typeof region.bounds !== "function" || typeof region.contains !== "function") throw new EngineError("INVALID_VIRTUAL_INPUT", "Custom regions require bounds and contains functions");
+		return {
+			kind: "custom",
+			bounds: virtualBounds(region.bounds(viewport)),
+			test: region.contains
+		};
+	}
+	const center = virtualPosition(region, viewport);
+	if (region.kind === "rect") {
+		const relative = (region.space ?? "viewport") === "viewport";
+		const width = virtualFinite(region.width, "region.width"), height = virtualFinite(region.height, "region.height");
+		if (width < 0 || height < 0) throw new EngineError("INVALID_VIRTUAL_INPUT", "Region sizes must be nonnegative");
+		return {
+			kind: "rect",
+			bounds: virtualBounds({
+				...center,
+				width: width * (relative ? viewport.width : 1),
+				height: height * (relative ? viewport.height : 1)
+			})
+		};
+	}
+	const radius = virtualFinite(region.radius, "region.radius") * ((region.space ?? "viewport") === "viewport" ? Math.min(viewport.width, viewport.height) : 1);
+	if (radius < 0) throw new EngineError("INVALID_VIRTUAL_INPUT", "Region radius must be nonnegative");
+	return {
+		kind: "circle",
+		center,
+		radius,
+		bounds: virtualBounds({
+			x: center.x - radius,
+			y: center.y - radius,
+			width: radius * 2,
+			height: radius * 2
+		})
+	};
+}
+/** @internal Rectangles are half-open; circles exclude their circumference. */
+function virtualContains(region, point, viewport) {
+	const b = region.bounds;
+	if (point.x < b.x || point.y < b.y || point.x >= b.x + b.width || point.y >= b.y + b.height) return false;
+	if (region.kind === "circle") return Math.hypot(point.x - region.center.x, point.y - region.center.y) < region.radius;
+	if (region.kind === "custom") {
+		const value = region.test(point, viewport);
+		if (typeof value !== "boolean") throw new EngineError("INVALID_VIRTUAL_INPUT", "Custom region predicate must return boolean");
+		return value;
+	}
+	return true;
+}
+/** @internal Exact built-in intersection; custom bounds are conservatively ambiguous. */
+function virtualOverlap(a, b) {
+	const x = a.bounds, y = b.bounds;
+	if (Math.min(x.x + x.width, y.x + y.width) <= Math.max(x.x, y.x) || Math.min(x.y + x.height, y.y + y.height) <= Math.max(x.y, y.y)) return false;
+	if (a.kind === "circle" && b.kind === "circle") return Math.hypot(a.center.x - b.center.x, a.center.y - b.center.y) < a.radius + b.radius;
+	const circle = a.kind === "circle" ? a : b.kind === "circle" ? b : void 0;
+	const rect = a.kind === "circle" ? b : a;
+	if (circle && rect.kind === "rect") {
+		const c = circle.center, r = rect.bounds;
+		return Math.hypot(c.x - Math.max(r.x, Math.min(r.x + r.width, c.x)), c.y - Math.max(r.y, Math.min(r.y + r.height, c.y))) < circle.radius;
+	}
+	return true;
+}
+// packages/core/src/interaction/virtual-control.ts
+var VirtualStickMode = {
+	Fixed: "fixed",
+	Floating: "floating",
+	Follow: "follow"
+};
+var screenPoint$1 = (x, y) => ({
+	space: "screen",
+	x: virtualFinite(x, "screen.x"),
+	y: virtualFinite(y, "screen.y")
+});
+var zero = Object.freeze({
+	x: 0,
+	y: 0
+});
+var Start = defineEvent("VirtualStart");
+var Change = defineEvent("VirtualChange");
+var End = defineEvent("VirtualEnd");
+var Cancel = defineEvent("VirtualCancel");
+var Hold = defineEvent("VirtualHold");
+function flag(value) {
+	if (typeof value !== "boolean") throw new EngineError("INVALID_VIRTUAL_INPUT", "Virtual control flags must be boolean");
+	return value;
+}
+function zone(value) {
+	virtualFinite(value, "deadZone");
+	if (value < 0 || value >= 1) throw new EngineError("INVALID_VIRTUAL_INPUT", "Dead zone must satisfy 0 <= value < 1");
+	return value;
+}
+function mode(value) {
+	if (!Object.values(VirtualStickMode).includes(value)) throw new EngineError("INVALID_VIRTUAL_INPUT", "Unknown virtual stick mode");
+	return value;
+}
+/** @internal Validate before allocating ActionSources or registering a target. */
+function checkVirtualOptions(options) {
+	checkedVirtualRegion(options.region);
+	positive(options.radius ?? 64, "radius");
+	zone(options.deadZone ?? .15);
+	flag(options.enabled ?? true);
+	flag(options.visible ?? true);
+	flag(options.direction ?? false);
+	mode(options.mode ?? VirtualStickMode.Fixed);
+	if (virtualFinite(options.holdDelay ?? .5, "holdDelay") < 0) throw new EngineError("INVALID_VIRTUAL_INPUT", "Hold delay must be nonnegative");
+	if (options.position) {
+		virtualFinite(options.position.x, "position.x");
+		virtualFinite(options.position.y, "position.y");
+		if (options.position.space !== void 0 && options.position.space !== "screen" && options.position.space !== "viewport") throw new EngineError("INVALID_VIRTUAL_INPUT", "Unknown position space");
+	}
+	const color = options.color ?? 6736821;
+	if (!Number.isInteger(color) || color < 0 || color > 16777215) throw new EngineError("INVALID_VIRTUAL_INPUT", "Virtual color must be RGB");
+}
+/** Portable gesture state. Routing, Action composition and rendering retain their existing owners. */
+var VirtualControl = class {
+	kind;
+	host;
+	binding;
+	life = new Lifetime();
+	events = new EventBus();
+	observers = /* @__PURE__ */ new Set();
+	activation;
+	activeFlag;
+	shown;
+	size;
+	deadZoneValue;
+	version = 0;
+	gesture;
+	vector = zero;
+	dragMode;
+	position;
+	holdDelay;
+	color;
+	directional;
+	constructor(kind, options, host, binding) {
+		this.kind = kind;
+		this.host = host;
+		this.binding = binding;
+		checkVirtualOptions(options);
+		this.activation = checkedVirtualRegion(options.region);
+		this.position = options.position ? Object.freeze({ ...options.position }) : void 0;
+		this.activeFlag = options.enabled ?? true;
+		this.shown = options.visible ?? true;
+		this.size = options.radius ?? (kind === "stick" ? 64 : 28);
+		this.deadZoneValue = options.deadZone ?? .15;
+		this.dragMode = mode(options.mode ?? VirtualStickMode.Fixed);
+		this.holdDelay = options.holdDelay ?? .5;
+		this.color = options.color ?? 6736821;
+		this.directional = kind === "stick" || (options.direction ?? false);
+		this.life.onDispose(binding.onDispose(() => this.dispose()));
+	}
+	get disposed() {
+		return this.life.disposed;
+	}
+	get available() {
+		return !this.disposed && this.activeFlag && this.host.available() && this.binding.active();
+	}
+	get revision() {
+		return this.version;
+	}
+	get enabled() {
+		return this.activeFlag;
+	}
+	set enabled(value) {
+		this.alive();
+		const next = flag(value);
+		if (next === this.activeFlag) return;
+		this.activeFlag = next;
+		this.interrupt();
+	}
+	get visible() {
+		return this.shown;
+	}
+	set visible(value) {
+		this.alive();
+		this.shown = flag(value);
+	}
+	get radius() {
+		return this.size;
+	}
+	set radius(value) {
+		this.alive();
+		const next = positive(value, "radius");
+		if (next === this.size) return;
+		this.size = next;
+		this.interrupt();
+	}
+	get deadZone() {
+		return this.deadZoneValue;
+	}
+	set deadZone(value) {
+		this.alive();
+		const next = zone(value);
+		if (next === this.deadZoneValue) return;
+		this.deadZoneValue = next;
+		this.interrupt();
+	}
+	get region() {
+		return this.activation;
+	}
+	set region(value) {
+		this.alive();
+		const next = checkedVirtualRegion(value);
+		this.host.region(this, next);
+		this.activation = next;
+		this.interrupt();
+	}
+	get stickMode() {
+		return this.dragMode;
+	}
+	set stickMode(value) {
+		this.alive();
+		const next = mode(value);
+		if (next === this.dragMode) return;
+		this.dragMode = next;
+		this.interrupt();
+	}
+	get pointerId() {
+		return this.gesture?.last.pointerId;
+	}
+	get pressed() {
+		return this.gesture !== void 0;
+	}
+	get elapsed() {
+		return this.gesture?.elapsed ?? 0;
+	}
+	get direction() {
+		return this.vector;
+	}
+	get center() {
+		const p = this.gesture?.center ?? this.host.center(this);
+		return Object.freeze(screenPoint$1(p.x, p.y));
+	}
+	get knob() {
+		const center = this.center, last = this.gesture?.last.screen;
+		if (!last || !this.directional) return center;
+		const origin = this.kind === "button" ? this.gesture?.origin ?? center : center;
+		const dx = last.x - origin.x, dy = last.y - origin.y, length = Math.hypot(dx, dy);
+		const scale = length > this.size ? this.size / length : 1;
+		return Object.freeze(screenPoint$1(center.x + dx * scale, center.y + dy * scale));
+	}
+	onDispose(callback) {
+		return this.life.onDispose(callback);
+	}
+	/** @internal Geometry/availability invalidation, not a per-frame observer. */
+	subscribe(callback) {
+		this.alive();
+		this.observers.add(callback);
+		return () => {
+			this.observers.delete(callback);
+		};
+	}
+	onStart(callback, owner) {
+		return this.events.on(Start, callback, owner);
+	}
+	onChange(callback, owner) {
+		return this.events.on(Change, callback, owner);
+	}
+	onEnd(callback, owner) {
+		return this.events.on(End, callback, owner);
+	}
+	onCancel(callback, owner) {
+		return this.events.on(Cancel, callback, owner);
+	}
+	onHold(callback, owner) {
+		return this.events.on(Hold, callback, owner);
+	}
+	/** Release/cancel only; the captured physical ID stays suppressed until its release. */
+	cancel() {
+		this.alive();
+		this.interrupt();
+	}
+	/** @internal */
+	invalidate() {
+		this.interrupt();
+	}
+	alive() {
+		if (this.disposed) throw new EngineError("OWNER_DISPOSED", "Virtual control has been disposed");
+	}
+	interrupt() {
+		this.version++;
+		cleanupAll([...[...this.observers], () => {
+			if (this.gesture) this.finish(true);
+			else this.binding.clear();
+		}], "Virtual gesture interruption failed");
+	}
+	contains(data) {
+		return this.host.contains(this, data);
+	}
+	snapshot(g) {
+		return Object.freeze({
+			control: this,
+			pointerId: g.last.pointerId,
+			pointerType: g.last.pointerType,
+			origin: g.origin,
+			position: Object.freeze(screenPoint$1(g.last.screen.x, g.last.screen.y)),
+			center: g.center,
+			direction: this.vector,
+			inside: this.contains(g.last),
+			elapsed: g.elapsed
+		});
+	}
+	update(g) {
+		if (!this.directional) {
+			this.vector = zero;
+			return;
+		}
+		const start = this.kind === "button" ? g.origin : g.center;
+		const dx = g.last.screen.x - start.x, dy = g.last.screen.y - start.y;
+		const length = Math.hypot(dx, dy);
+		if (this.kind === "stick" && this.dragMode === VirtualStickMode.Follow && length > this.size) g.center = Object.freeze(screenPoint$1(g.last.screen.x - dx * this.size / length, g.last.screen.y - dy * this.size / length));
+		const magnitude = Math.min(1, length / this.size);
+		const output = magnitude <= this.deadZoneValue ? 0 : (magnitude - this.deadZoneValue) / (1 - this.deadZoneValue);
+		this.vector = output === 0 ? zero : Object.freeze({
+			x: dx / length * output,
+			y: dy / length * output
+		});
+	}
+	deliver(type, data) {
+		if (type === "cancel") {
+			if (this.gesture?.last.pointerId === data.pointerId) this.finish(true);
+			return;
+		}
+		if (type === "down") {
+			if (!this.available || this.gesture) return;
+			const center = this.kind === "stick" && this.dragMode !== VirtualStickMode.Fixed ? data.screen : this.host.center(this);
+			const g = {
+				last: data,
+				origin: Object.freeze(screenPoint$1(data.screen.x, data.screen.y)),
+				center: Object.freeze(screenPoint$1(center.x, center.y)),
+				elapsed: 0,
+				held: false
+			};
+			this.gesture = g;
+			this.update(g);
+			this.binding.write(this.vector, true);
+			const event = this.snapshot(g);
+			cleanupAll([() => this.events.emit(Start, event), () => {
+				if (this.gesture === g) this.events.emit(Change, event);
+			}], "Virtual start handlers failed");
+			return;
+		}
+		const g = this.gesture;
+		if (!g || g.last.pointerId !== data.pointerId) return;
+		if (!this.available) {
+			this.interrupt();
+			return;
+		}
+		if (data.screen.x !== g.last.screen.x || data.screen.y !== g.last.screen.y) {
+			g.last = data;
+			this.update(g);
+			this.binding.write(this.vector, true);
+			this.events.emit(Change, this.snapshot(g));
+		}
+		if (type === "up" && this.gesture === g) {
+			g.last = data;
+			this.finish(false);
+		}
+	}
+	/** @internal Explicit presentation clock; no browser/OS timer in Core. */
+	advance(seconds) {
+		const g = this.gesture;
+		if (!g) return;
+		if (!this.available) {
+			this.interrupt();
+			return;
+		}
+		g.elapsed += seconds;
+		if (!g.held && g.elapsed >= this.holdDelay) {
+			g.held = true;
+			this.events.emit(Hold, this.snapshot(g));
+		}
+	}
+	finish(cancelled) {
+		const g = this.gesture;
+		if (!g) return;
+		let event;
+		try {
+			event = this.snapshot(g);
+		} finally {
+			this.gesture = void 0;
+			this.vector = zero;
+			this.binding.clear();
+		}
+		this.events.emit(cancelled ? Cancel : End, event);
+	}
+	dispose() {
+		if (this.disposed) return;
+		cleanupAll([
+			() => this.life.dispose(),
+			() => this.interrupt(),
+			() => this.binding.dispose(),
+			() => this.events.dispose(),
+			() => this.observers.clear(),
+			() => this.host.remove(this)
+		], "Virtual control cleanup failed");
+	}
+};
+var VirtualStick = class extends VirtualControl {
+	/** @internal Use VirtualInput.stick. */
+	constructor(options, host, binding) {
+		super("stick", options, host, binding);
+	}
+	get value() {
+		return this.direction;
+	}
+	get mode() {
+		return this.stickMode;
+	}
+	set mode(value) {
+		this.stickMode = value;
+	}
+};
+var VirtualButton = class extends VirtualControl {
+	/** @internal Use VirtualInput.button. */
+	constructor(options, host, binding) {
+		super("button", options, host, binding);
+	}
+	get value() {
+		return this.pressed;
+	}
+	/** Confirmation on normal release, including a drag outside the activation region; never on cancel. */
+	onCommit(callback, owner) {
+		return this.onEnd(callback, owner);
+	}
+};
+// packages/core/src/interaction/virtual-input.ts
+/** Scene-scoped virtual devices; all gameplay values flow through existing ActionSources. */
+var VirtualInput = class {
+	pointer;
+	input;
+	life = new Lifetime();
+	list = Object.freeze([]);
+	regions = /* @__PURE__ */ new Map();
+	anchors = /* @__PURE__ */ new Map();
+	view = Object.freeze({
+		x: 0,
+		y: 0,
+		width: 800,
+		height: 450
+	});
+	active = true;
+	shown = true;
+	dirty = true;
+	host;
+	constructor(pointer, input) {
+		this.pointer = pointer;
+		this.input = input;
+		if (pointer.disposed) throw new EngineError("OWNER_DISPOSED", "Scene pointer has been disposed");
+		this.host = {
+			available: () => !this.disposed && this.active && input.liveInput,
+			center: (control) => this.anchors.get(control) ?? {
+				x: 0,
+				y: 0
+			},
+			contains: (control, data) => {
+				const region = this.regions.get(control);
+				return region ? virtualContains(region, data.screen, this.view) : false;
+			},
+			region: (control, region) => {
+				const regions = this.resolve(this.view, control, region);
+				this.regions = regions;
+				this.anchors = this.centers(regions, this.view);
+				this.dirty = true;
+			},
+			remove: (control) => {
+				this.list = Object.freeze(this.list.filter((c) => c !== control));
+				this.regions.delete(control);
+				this.anchors.delete(control);
+			}
+		};
+		try {
+			this.life.onDispose(pointer.attachTargets(this));
+			this.life.onDispose(input.addAdapter(this));
+			this.life.onDispose(pointer.onDispose(() => this.dispose()));
+		} catch (error) {
+			this.life.dispose();
+			throw error;
+		}
+	}
+	get disposed() {
+		return this.life.disposed;
+	}
+	get controls() {
+		return this.list;
+	}
+	get viewport() {
+		return this.view;
+	}
+	get enabled() {
+		return this.active;
+	}
+	set enabled(value) {
+		this.alive();
+		this.flag(value);
+		if (this.active === value) return;
+		this.active = value;
+		this.reset();
+	}
+	get visible() {
+		return this.shown;
+	}
+	set visible(value) {
+		this.alive();
+		this.flag(value);
+		this.shown = value;
+	}
+	onDispose(callback) {
+		return this.life.onDispose(callback);
+	}
+	flag(value) {
+		if (typeof value !== "boolean") throw new EngineError("INVALID_VIRTUAL_INPUT", "Virtual input flags must be boolean");
+	}
+	alive() {
+		if (this.disposed) throw new EngineError("OWNER_DISPOSED", "Virtual input has been disposed");
+	}
+	validate(controller, action, kind, options) {
+		this.alive();
+		checkVirtualOptions(options);
+		if (!this.input.hasController(controller) || controller.reader(action).scene !== this.pointer.scene || action.kind !== kind) throw new EngineError("INVALID_ACTION", "Virtual input requires a matching Action kind and a controller in its own Scene/InputSystem");
+		const region = resolveVirtualRegion(options.region, this.view);
+		const peers = this.resolve(this.view);
+		for (const control of this.list) {
+			const other = peers.get(control);
+			if (other && control.kind === (kind === "axis2d" ? "stick" : "button") && virtualOverlap(region, other)) throw new EngineError("VIRTUAL_REGION_OVERLAP", "Same-priority virtual activation regions overlap");
+		}
+		if (options.position) virtualPosition(options.position, this.view);
+	}
+	binding(controller, action) {
+		const source = controller.createSource();
+		return {
+			get disposed() {
+				return source.disposed;
+			},
+			onDispose: (callback) => controller.onDispose(callback),
+			clear: () => source.clear(),
+			dispose: () => source.dispose(),
+			active: () => controller.active,
+			write: (direction, pressed) => source.set(action, action.kind === "axis2d" ? direction : pressed)
+		};
+	}
+	stick(controller, action, options) {
+		this.validate(controller, action, "axis2d", options);
+		const binding = this.binding(controller, action);
+		try {
+			return this.add(new VirtualStick(options, this.host, binding));
+		} catch (error) {
+			binding.dispose();
+			throw error;
+		}
+	}
+	button(controller, action, options) {
+		this.validate(controller, action, "button", options);
+		const binding = this.binding(controller, action);
+		try {
+			return this.add(new VirtualButton(options, this.host, binding));
+		} catch (error) {
+			binding.dispose();
+			throw error;
+		}
+	}
+	add(control) {
+		this.list = Object.freeze([...this.list, control]);
+		this.dirty = true;
+		try {
+			this.refresh();
+		} catch (error) {
+			control.dispose();
+			throw error;
+		}
+		return control;
+	}
+	resolve(view, replaced, region) {
+		const result = /* @__PURE__ */ new Map();
+		for (const control of this.list) result.set(control, resolveVirtualRegion(control === replaced && region ? region : control.region, view));
+		for (let i = 0; i < this.list.length; i++) {
+			const a = this.list[i];
+			if (!a) continue;
+			for (let j = i + 1; j < this.list.length; j++) {
+				const b = this.list[j], x = result.get(a), y = b ? result.get(b) : void 0;
+				if (b && x && y && a.kind === b.kind && virtualOverlap(x, y)) throw new EngineError("VIRTUAL_REGION_OVERLAP", "Same-priority virtual activation regions overlap", {
+					first: i,
+					second: j
+				});
+			}
+		}
+		return result;
+	}
+	centers(regions, view) {
+		return new Map([...regions].map(([control, region]) => {
+			const b = region.bounds;
+			return [control, control.position ? virtualPosition(control.position, view) : Object.freeze({
+				x: b.x + b.width / 2,
+				y: b.y + b.height / 2
+			})];
+		}));
+	}
+	/** Resolve after Canvas layout and before routing/rendering. Layout changes cancel active gestures. */
+	refresh(viewport = this.view) {
+		this.alive();
+		const view = virtualBounds(viewport);
+		const resized = Object.keys(view).some((key) => view[key] !== this.view[key]);
+		if (!this.dirty && !resized && !this.list.some((c) => c.region.kind === "custom")) return;
+		const regions = this.resolve(view), centers = this.centers(regions, view);
+		const changed = this.list.filter((c) => resized || JSON.stringify(regions.get(c)) !== JSON.stringify(this.regions.get(c)) || JSON.stringify(centers.get(c)) !== JSON.stringify(this.anchors.get(c)));
+		this.view = view;
+		this.regions = regions;
+		this.anchors = centers;
+		this.dirty = false;
+		cleanupAll(changed.map((c) => () => c.invalidate()), "Virtual layout cancellation failed");
+	}
+	pick(data) {
+		if (this.disposed || !this.active || !this.input.liveInput || data.button !== 0) return;
+		this.refresh();
+		for (const kind of ["button", "stick"]) for (const control of this.list) if (control.kind === kind && control.available && control.contains(data)) return control;
+	}
+	sample() {
+		if (this.disposed) return;
+		this.refresh();
+		cleanupAll(this.list.filter((c) => c.pressed && !c.available).map((c) => () => c.invalidate()), "Virtual availability cancellation failed");
+	}
+	advance(seconds) {
+		this.alive();
+		if (virtualFinite(seconds, "seconds") < 0) throw new EngineError("INVALID_VIRTUAL_INPUT", "Presentation seconds must be nonnegative");
+		cleanupAll(this.list.map((c) => () => {
+			if (!c.disposed) c.advance(seconds);
+		}), "Virtual hold callbacks failed");
+	}
+	reset() {
+		cleanupAll(this.list.map((c) => () => c.invalidate()), "Virtual input reset failed");
+	}
+	dispose() {
+		if (this.disposed) return;
+		cleanupAll([
+			() => this.life.dispose(),
+			...this.list.map((c) => () => c.dispose()),
+			() => {
+				this.regions.clear();
+				this.anchors.clear();
+				this.list = Object.freeze([]);
+			}
+		], "Virtual input cleanup failed");
+	}
+};
 // packages/core/src/runtime/engine.ts
 var Engine = class {
 	input = new InputSystem();
@@ -6320,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.4" || 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()
@@ -8218,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, 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