@simpludify/web 0.1.4 → 0.1.6

package/dist/index.js

@@ -1,5 +1,5 @@
 import "./style.css";
-import { ActionController, Aspect, Camera, CanvasButton as CanvasButton$1, CanvasUI, Engine, EngineError, EventBus, FixedStepRunner, GeometryTilemapLayer, Lifetime, PointerRouting, Renderable, ReplayPlayer, Scene, ScenePointer, SceneState, Shape, TilemapLayer, Transform, canvasControlText, canvasHoverHighlight, canvasOpacity, canvasScrollbars, canvasSliderGeometry, cleanupAll, containsScreenPoint, createViewTransform, defineEvent, imageSize, intersectUI, isKeyCode, positive, screenPoint, screenToWorld, spriteFrameBounds, worldToScreen, wrapCanvasText } from "@simpludify/core";
+import { ActionController, Aspect, Camera, CanvasButton as CanvasButton$1, CanvasUI, Engine, EngineError, EventBus, FixedStepRunner, GamepadAxis, GamepadBindings, GamepadButton, GeometryTilemapLayer, InputCapture, InputCaptureState, InputDevice, Lifetime, MouseButton, PointerRouting, Renderable, ReplayPlayer, Scene, ScenePointer, SceneState, Shape, TilemapLayer, Transform, VirtualInput, canvasControlText, canvasHoverHighlight, canvasOpacity, canvasScrollbars, canvasSliderGeometry, checkedGamepadBindings, cleanupAll, containsScreenPoint, createViewTransform, defineEvent, gamepadDeadZone, gamepadIndex, imageSize, intersectUI, isKeyCode, isMouseButton, positive, screenPoint, screenToWorld, spriteFrameBounds, worldToScreen, wrapCanvasText } from "@simpludify/core";
 import { Application, CanvasTextMetrics, Container, Graphics, Rectangle, RendererType, Sprite, Text, TextStyle, Texture } from "pixi.js";
 export * from "@simpludify/core";
 // packages/web/src/canvas-node.ts
@@ -17,135 +17,6 @@ function CanvasButton(text, click, style = {}) {
 		return click(signal);
 	}, style);
 }
-// packages/web/src/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) },
-		invert: v.invert ?? false,
-		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/web/src/gamepad-layout.ts
 var positions = Object.fromEntries(Object.entries(GamepadButton).map(([name, index]) => [index, name]));
 var faces = Object.freeze({
@@ -230,6 +101,9 @@ var GamepadSource = class {
 	signature;
 	zone;
 	mapping;
+	following;
+	bindingRevision;
+	waiting = /* @__PURE__ */ new Set();
 	constructor(input, controller, options) {
 		this.input = input;
 		this.controller = controller;
@@ -238,7 +112,9 @@ var GamepadSource = class {
 		this.zone = gamepadDeadZone(options.deadZone ?? .15);
 		this.mapping = options.mapping ?? "standard";
 		if (this.mapping !== "standard" && this.mapping !== "raw") throw new EngineError("INVALID_GAMEPAD_BINDING", "Unknown gamepad mapping policy");
-		this.bindings = checkedGamepadBindings(controller.actions, options.bindings);
+		this.following = options.bindings === void 0;
+		this.bindingRevision = controller.bindingRevision;
+		this.bindings = this.following ? this.commonBindings() : checkedGamepadBindings(controller.actions, options.bindings);
 		this.source = controller.createSource();
 		this.life.onDispose(() => this.source.dispose());
 		this.life.onDispose(controller.onDispose(() => this.dispose()));
@@ -277,19 +153,42 @@ var GamepadSource = class {
 	}
 	rebind(bindings) {
 		this.alive();
-		const checked = checkedGamepadBindings(this.controller.actions, bindings);
+		const checked = bindings === void 0 ? this.commonBindings() : checkedGamepadBindings(this.controller.actions, bindings);
 		this.clear();
 		this.bindings = checked;
+		this.following = bindings === void 0;
+		this.bindingRevision = this.controller.bindingRevision;
+	}
+	commonBindings() {
+		return Object.freeze(Object.values(this.controller.actions).flatMap((action) => {
+			const binding = this.controller.getBinding(action).gamepad;
+			return binding ? [Object.freeze([action, binding])] : [];
+		}));
+	}
+	syncBindings() {
+		if (!this.following || this.bindingRevision === this.controller.bindingRevision) return;
+		const next = this.commonBindings();
+		const before = new Map(this.bindings), after = new Map(next);
+		for (const action of /* @__PURE__ */ new Set([...before.keys(), ...after.keys()])) {
+			if (JSON.stringify(before.get(action)) === JSON.stringify(after.get(action))) continue;
+			this.source.resetBinding(action);
+			if (after.has(action)) this.waiting.add(action);
+			else this.waiting.delete(action);
+		}
+		this.bindings = next;
+		this.bindingRevision = this.controller.bindingRevision;
 	}
 	clear() {
 		this.source.clear();
 		this.armed = false;
+		this.waiting.clear();
 	}
 	alive() {
 		if (this.disposed) throw new EngineError("OWNER_DISPOSED", "Gamepad source has been disposed");
 	}
 	/** @internal */ sample(pad, allowed) {
 		if (this.disposed) return;
+		this.syncBindings();
 		if (!allowed || !this.enabled || !this.controller.active || !pad || this.mapping === "standard" && pad.mapping !== "standard") {
 			this.clear();
 			this.signature = void 0;
@@ -310,7 +209,13 @@ var GamepadSource = class {
 			if (next.every(([, value]) => neutral(value))) this.armed = true;
 			return;
 		}
-		for (const [action, value] of next) this.source.set(action, value);
+		for (const [action, value] of next) {
+			if (this.waiting.has(action)) {
+				if (!neutral(value)) continue;
+				this.waiting.delete(action);
+			}
+			this.source.set(action, value);
+		}
 	}
 	/** @internal */ onDispose(callback) {
 		return this.life.onDispose(callback);
@@ -331,6 +236,7 @@ var GamepadInput = class {
 	readable = false;
 	poll;
 	active;
+	observe;
 	constructor(input, options = {}) {
 		this.input = input;
 		this.life.onDispose(() => this.changes.dispose());
@@ -338,6 +244,7 @@ var GamepadInput = class {
 			throw new Error("Gamepad API unavailable");
 		})());
 		this.active = options.active ?? (() => true);
+		this.observe = options.observe;
 		this.life.onDispose(input.addAdapter(this));
 		const events = options.events ?? (typeof window === "undefined" ? void 0 : window), abort = new AbortController();
 		this.life.onDispose(() => abort.abort());
@@ -412,7 +319,8 @@ var GamepadInput = class {
 			axisCount: p.axes.length,
 			inferredLayout: inferredGamepadLayout(p.id)
 		})));
-		const allowed = this.active();
+		this.observe?.(pads);
+		const allowed = this.active() && this.input.liveInput;
 		for (const source of this.sources) if (source.disposed) this.sources.delete(source);
 		else source.sample(pads.get(source.index), allowed);
 		this.publish(listed, wasReadable !== this.readable);
@@ -520,35 +428,286 @@ var BrowserInput = class {
 		this.clear();
 	}
 };
+// packages/web/src/input-capture.ts
+var mouseMasks$1 = [
+	[0, 1],
+	[1, 4],
+	[2, 2],
+	[3, 8],
+	[4, 16]
+];
+/** @internal One Game-owned observer; existing adapters retain gameplay ownership. */
+var InputCaptureManager = class {
+	host;
+	input;
+	scene;
+	releasePointers;
+	report;
+	abort = new AbortController();
+	current;
+	keys = /* @__PURE__ */ new Set();
+	blockedKeys = /* @__PURE__ */ new Set();
+	blockedPointers = /* @__PURE__ */ new Set();
+	blockedAuxiliary = /* @__PURE__ */ new Set();
+	mouseButtons = 0;
+	needsPadSample = false;
+	pads = /* @__PURE__ */ new Map();
+	readyPads = /* @__PURE__ */ new Set();
+	dead = false;
+	constructor(host, input, scene, releasePointers, report) {
+		this.host = host;
+		this.input = input;
+		this.scene = scene;
+		this.releasePointers = releasePointers;
+		this.report = report;
+		const options = {
+			capture: true,
+			signal: this.abort.signal
+		};
+		window.addEventListener("keydown", (event) => this.guard(() => this.keyDown(event)), options);
+		window.addEventListener("keyup", (event) => this.guard(() => {
+			if (isKeyCode(event.code)) {
+				this.keys.delete(event.code);
+				this.blockedKeys.delete(event.code);
+			}
+			this.arm();
+		}), options);
+		for (const kind of [
+			"pointerdown",
+			"pointermove",
+			"pointerup",
+			"pointercancel"
+		]) window.addEventListener(kind, (event) => this.guard(() => this.pointer(event)), options);
+		for (const kind of ["auxclick", "contextmenu"]) window.addEventListener(kind, (event) => {
+			if (this.surface(event.target) && isMouseButton(event.button) && this.blockedAuxiliary.has(event.button)) {
+				this.consume(event);
+				if (kind === "auxclick") this.blockedAuxiliary.delete(event.button);
+			}
+		}, options);
+		window.addEventListener("blur", (event) => {
+			if (event.target === window) this.interrupt();
+		}, options);
+		document.addEventListener("visibilitychange", () => {
+			if (document.hidden) this.interrupt();
+		}, options);
+		host.addEventListener("focusout", (event) => {
+			if (!(event.relatedTarget instanceof Node) || !host.contains(event.relatedTarget) || blocksGameKeyboard(event.relatedTarget)) this.interrupt();
+		}, options);
+		host.addEventListener("focusin", (event) => {
+			if (blocksGameKeyboard(event.target)) this.interrupt();
+		}, options);
+	}
+	start(options = {}) {
+		if (this.dead) throw new EngineError("GAME_DISPOSED", "Capture host has been disposed");
+		if (this.current) throw new EngineError("INPUT_CAPTURE_ACTIVE", "Cancel the active capture before starting another");
+		const scene = this.scene();
+		if (scene.state !== SceneState.Active || document.hidden || !document.hasFocus()) throw new EngineError("INPUT_CAPTURE_UNAVAILABLE", "Capture requires an active Scene and focused visible document");
+		const capture = new InputCapture(options);
+		let release;
+		try {
+			capture.onDispose(scene.onDispose(() => capture.cancel()));
+			capture.onDispose(() => {
+				if (this.current === capture) this.current = void 0;
+				this.pads.clear();
+				this.readyPads.clear();
+				this.needsPadSample = false;
+				release?.();
+			});
+			this.current = capture;
+			this.needsPadSample = capture.devices.includes(InputDevice.Gamepad);
+			for (const key of this.keys) this.blockedKeys.add(key);
+			for (const [button, mask] of mouseMasks$1) if (this.mouseButtons & mask) this.blockedAuxiliary.add(button);
+			this.releasePointers();
+			if (capture.disposed) return capture;
+			release = this.input.suspendLiveInput(() => capture.cancel());
+			if (capture.disposed) {
+				release();
+				return capture;
+			}
+			this.host.focus({ preventScroll: true });
+			this.arm();
+			return capture;
+		} catch (error) {
+			capture.cancel();
+			throw error;
+		}
+	}
+	arm() {
+		const capture = this.current;
+		if (!capture || capture.state !== InputCaptureState.Arming || this.needsPadSample) return;
+		if (capture.devices.includes(InputDevice.Keyboard) && this.keys.size) return;
+		if (capture.devices.includes(InputDevice.Mouse) && this.mouseButtons) return;
+		if (capture.devices.includes(InputDevice.Gamepad) && [...this.pads.values()].some((pad) => (capture.gamepadIndex === void 0 || capture.gamepadIndex === pad.index) && pad.buttons.size)) return;
+		capture.arm();
+	}
+	keyDown(event) {
+		if (event.isComposing || event.keyCode === 229 || !isKeyCode(event.code)) return;
+		const previous = this.keys.has(event.code);
+		this.keys.add(event.code);
+		if (!(event.target instanceof Node) || !this.host.contains(event.target)) return;
+		if (blocksGameKeyboard(event.target)) return;
+		if (event.target instanceof HTMLElement && event.target.closest("button")) return;
+		const capture = this.current;
+		if (!capture && !this.blockedKeys.has(event.code)) return;
+		this.blockedKeys.add(event.code);
+		this.consume(event);
+		if (capture && !previous && !event.repeat) capture.accept({
+			device: InputDevice.Keyboard,
+			code: event.code
+		});
+	}
+	surface(target) {
+		return target === this.host || target instanceof HTMLCanvasElement && target.parentElement === this.host;
+	}
+	pointer(event) {
+		const capture = this.current, mouse = event.pointerType === "mouse", old = this.mouseButtons;
+		if (mouse) this.mouseButtons = event.type === "pointercancel" ? 0 : event.buttons;
+		if (event.type === "pointerdown" && !capture) {
+			this.blockedPointers.delete(event.pointerId);
+			if (isMouseButton(event.button)) this.blockedAuxiliary.delete(event.button);
+		}
+		const blocked = this.blockedPointers.has(event.pointerId);
+		if (capture && this.surface(event.target)) {
+			if (event.type === "pointerdown") this.host.focus({ preventScroll: true });
+			this.blockedPointers.add(event.pointerId);
+			this.consume(event);
+			if (mouse && isMouseButton(event.button)) {
+				const mask = mouseMasks$1.find(([button]) => button === event.button)?.[1] ?? 0;
+				if (event.buttons & mask && !(old & mask)) {
+					this.blockedAuxiliary.add(event.button);
+					capture.accept({
+						device: InputDevice.Mouse,
+						button: event.button
+					});
+				}
+			}
+		} else if (blocked) this.consume(event);
+		if (event.type === "pointerup" || event.type === "pointercancel" || mouse && event.buttons === 0) this.blockedPointers.delete(event.pointerId);
+		this.arm();
+	}
+	/** Same validated gamepad poll as gameplay; no navigator polling in this manager. */
+	sample(pads) {
+		const capture = this.current;
+		if (!capture?.devices.includes(InputDevice.Gamepad)) return;
+		const before = this.pads, first = this.needsPadSample, next = /* @__PURE__ */ new Map();
+		for (const pad of pads.values()) {
+			const buttons = /* @__PURE__ */ new Set();
+			pad.buttons.forEach((button, index) => {
+				if (Number.isFinite(button?.value) && button.value >= .5) buttons.add(index);
+			});
+			const signature = JSON.stringify([
+				pad.id,
+				pad.mapping,
+				pad.buttons.length
+			]);
+			const entry = {
+				index: pad.index,
+				id: pad.id,
+				mapping: pad.mapping,
+				signature,
+				buttons
+			};
+			next.set(pad.index, entry);
+			if (first || before.get(pad.index)?.signature !== signature) this.readyPads.delete(pad.index);
+			if (!buttons.size) this.readyPads.add(pad.index);
+		}
+		for (const index of this.readyPads) if (!next.has(index)) this.readyPads.delete(index);
+		this.pads = next;
+		this.needsPadSample = false;
+		this.arm();
+		if (first || capture.state !== InputCaptureState.Listening) return;
+		for (const pad of [...next.values()].sort((a, b) => a.index - b.index)) {
+			if (!this.readyPads.has(pad.index) || before.get(pad.index)?.signature !== pad.signature) continue;
+			for (const button of pad.buttons) if (!before.get(pad.index)?.buttons.has(button) && capture.accept({
+				device: InputDevice.Gamepad,
+				index: pad.index,
+				id: pad.id,
+				mapping: pad.mapping,
+				button
+			})) return;
+		}
+	}
+	consume(event) {
+		event.preventDefault();
+		event.stopImmediatePropagation();
+	}
+	guard(action) {
+		try {
+			action();
+		} catch (error) {
+			this.report(error);
+		}
+	}
+	interrupt() {
+		this.guard(() => this.current?.cancel());
+		this.keys.clear();
+		this.blockedKeys.clear();
+		this.blockedPointers.clear();
+		this.blockedAuxiliary.clear();
+		this.mouseButtons = 0;
+	}
+	dispose() {
+		if (this.dead) return;
+		this.dead = true;
+		this.abort.abort();
+		this.interrupt();
+	}
+};
 // packages/web/src/pointer.ts
+var mouseMasks = [
+	[MouseButton.Left, 1],
+	[MouseButton.Middle, 4],
+	[MouseButton.Right, 2],
+	[MouseButton.Back, 8],
+	[MouseButton.Forward, 16]
+];
 /** One DOM capture-phase adapter per Game; Pixi federated events never route these widgets. */
 var BrowserPointer = class {
 	host;
 	project;
 	report;
 	flush;
+	input;
 	routing;
 	abort = new AbortController();
-	constructor(host, project, report, flush) {
+	mouse;
+	mouseStates = /* @__PURE__ */ new Map();
+	blockedMouse = /* @__PURE__ */ new Set();
+	auxiliary = /* @__PURE__ */ new Set();
+	offInput;
+	constructor(host, project, report, flush, input) {
 		this.host = host;
 		this.project = project;
 		this.report = report;
 		this.flush = flush;
+		this.input = input;
 		this.routing = new PointerRouting((id) => {
 			if (host.hasPointerCapture(id)) host.releasePointerCapture(id);
 		});
+		this.mouse = input?.createMouseSource();
+		this.offInput = input?.addAdapter({
+			sample: () => {},
+			reset: () => this.resetMouse(),
+			dispose: () => this.dispose()
+		});
 		const options = {
 			signal: this.abort.signal,
 			capture: true
 		};
 		host.addEventListener("pointerdown", (e) => this.guard(() => {
 			if (!this.surface(e.target)) return;
+			if (e.pointerType === "mouse") {
+				this.releaseMouse(e.pointerId);
+				this.blockedMouse.delete(e.pointerId);
+				if (isMouseButton(e.button)) this.auxiliary.delete(e.button);
+			}
 			this.flush();
 			const data = this.data(e);
 			try {
 				host.setPointerCapture(e.pointerId);
 			} catch {}
 			const target = this.routing.down(data);
+			this.updateMouse(e);
 			if (this.routing.has(e.pointerId)) {
 				e.preventDefault();
 				if (target) focusGameSurface(host);
@@ -570,28 +729,78 @@ var BrowserPointer = class {
 		});
 		window.addEventListener("pointermove", (e) => this.guard(() => {
 			if (!this.routing.owns(e.pointerId) && !this.surface(e.target)) {
+				if (e.pointerType === "mouse") this.releaseMouse(e.pointerId);
 				if (this.routing.hasHover(e.pointerId)) this.routing.leave(this.data(e));
 				return;
 			}
 			this.flush();
+			this.updateMouse(e);
 			this.routing.move(this.data(e));
 		}), options);
 		window.addEventListener("pointerup", (e) => this.guard(() => {
+			if (e.pointerType === "mouse") this.releaseMouse(e.pointerId);
 			if (this.routing.owns(e.pointerId)) {
 				e.preventDefault();
 				this.flush();
 				this.routing.up(this.data(e));
 			}
 		}), options);
-		window.addEventListener("pointercancel", (e) => this.guard(() => this.routing.cancel(e.pointerId, false)), options);
-		host.addEventListener("lostpointercapture", (e) => this.guard(() => this.routing.cancel(e.pointerId)), options);
+		window.addEventListener("pointercancel", (e) => this.guard(() => {
+			this.releaseMouse(e.pointerId);
+			this.blockedMouse.delete(e.pointerId);
+			this.routing.cancel(e.pointerId, false);
+		}), options);
+		host.addEventListener("lostpointercapture", (e) => this.guard(() => {
+			this.releaseMouse(e.pointerId);
+			if (e.pointerType === "mouse" && e.buttons !== 0) this.blockedMouse.add(e.pointerId);
+			else this.blockedMouse.delete(e.pointerId);
+			this.routing.cancel(e.pointerId);
+		}), options);
 		host.addEventListener("pointerleave", (e) => this.guard(() => this.routing.leave(this.data(e))), options);
 		window.addEventListener("blur", (event) => {
 			if (event.target === window) this.release();
 		}, options);
+		host.addEventListener("focusout", (event) => this.guard(() => {
+			if (!(event.relatedTarget instanceof Node) || !host.contains(event.relatedTarget) || blocksGameKeyboard(event.relatedTarget)) {
+				this.resetMouse();
+				this.routing.releaseVirtual();
+			}
+		}), options);
 		document.addEventListener("visibilitychange", () => {
 			if (document.hidden) this.release();
 		}, options);
+		for (const kind of ["auxclick", "contextmenu"]) host.addEventListener(kind, (event) => {
+			if (this.surface(event.target) && isMouseButton(event.button) && this.auxiliary.has(event.button) && input?.acceptsMouse(event.button)) {
+				event.preventDefault();
+				if (kind === "auxclick") this.auxiliary.delete(event.button);
+			}
+		}, options);
+	}
+	applyMouse() {
+		let buttons = 0;
+		for (const state of this.mouseStates.values()) buttons |= state;
+		for (const [button, mask] of mouseMasks) this.mouse?.set(button, (buttons & mask) !== 0);
+	}
+	releaseMouse(id) {
+		if (this.mouseStates.delete(id)) this.applyMouse();
+	}
+	updateMouse(event) {
+		if (event.pointerType !== "mouse" || !this.mouse) return;
+		if (event.buttons === 0) this.blockedMouse.delete(event.pointerId);
+		const world = this.routing.worldOwns(event.pointerId) && !this.blockedMouse.has(event.pointerId) && this.input?.liveInput;
+		if (world) this.mouseStates.set(event.pointerId, event.buttons);
+		else this.mouseStates.delete(event.pointerId);
+		if (isMouseButton(event.button)) {
+			if (world && this.input?.acceptsMouse(event.button)) this.auxiliary.add(event.button);
+			else this.auxiliary.delete(event.button);
+		}
+		this.applyMouse();
+	}
+	resetMouse() {
+		for (const id of this.mouseStates.keys()) this.blockedMouse.add(id);
+		this.mouseStates.clear();
+		this.auxiliary.clear();
+		this.mouse?.clear();
 	}
 	surface(target) {
 		return target === this.host || target instanceof HTMLCanvasElement && target.parentElement === this.host;
@@ -617,10 +826,15 @@ var BrowserPointer = class {
 		}
 	}
 	release() {
+		this.resetMouse();
 		this.guard(() => this.routing.release());
 	}
 	dispose() {
 		this.abort.abort();
+		this.offInput?.();
+		this.resetMouse();
+		this.mouse?.dispose();
+		this.blockedMouse.clear();
 		this.guard(() => this.routing.dispose());
 	}
 };
@@ -1907,6 +2121,108 @@ var TilemapVisual = class {
 		], "Tilemap presentation cleanup failed");
 	}
 };
+// packages/web/src/virtual-input-visual.ts
+/** Screen-space presentation only. The existing BrowserPointer is the sole event adapter. */
+var VirtualInputVisual = class {
+	input;
+	release;
+	display = new Container();
+	entries = /* @__PURE__ */ new Map();
+	dead = false;
+	off;
+	constructor(input, release) {
+		this.input = input;
+		this.release = release;
+		this.display.eventMode = "none";
+		this.display.sortableChildren = true;
+		this.display.zIndex = .5;
+		this.off = input.onDispose(() => this.dispose());
+	}
+	get diagnostics() {
+		return {
+			controls: this.entries.size,
+			visible: [...this.entries.values()].filter((e) => e.graphics.visible).length
+		};
+	}
+	update() {
+		if (this.dead) return;
+		const live = new Set(this.input.controls);
+		for (const [control, entry] of this.entries) if (!live.has(control)) {
+			this.entries.delete(control);
+			this.release(entry.graphics);
+		}
+		this.display.visible = this.input.visible;
+		for (const control of live) {
+			let entry = this.entries.get(control);
+			if (!entry) {
+				entry = {
+					graphics: new Graphics(),
+					signature: ""
+				};
+				entry.graphics.zIndex = control.kind === "button" ? 1 : 0;
+				this.entries.set(control, entry);
+				this.display.addChild(entry.graphics);
+			}
+			entry.graphics.visible = control.visible;
+			if (!control.visible || !this.input.visible) continue;
+			const center = control.center, knob = control.knob, radius = control.radius;
+			const signature = JSON.stringify([
+				center,
+				knob,
+				radius,
+				control.color,
+				control.enabled,
+				this.input.enabled,
+				control.pressed,
+				control.kind
+			]);
+			if (signature === entry.signature) continue;
+			entry.signature = signature;
+			const g = entry.graphics;
+			g.clear();
+			g.alpha = control.enabled && this.input.enabled ? 1 : .35;
+			g.circle(center.x, center.y, radius).fill({
+				color: control.color,
+				alpha: .12
+			}).stroke({
+				color: control.color,
+				alpha: .75,
+				width: 2
+			});
+			if (control.kind === "stick") {
+				g.moveTo(center.x, center.y).lineTo(knob.x, knob.y).stroke({
+					color: control.color,
+					alpha: .5,
+					width: 3
+				});
+				g.circle(knob.x, knob.y, radius * .36).fill({
+					color: control.color,
+					alpha: control.pressed ? .85 : .45
+				});
+			} else {
+				if (control.pressed) g.circle(center.x, center.y, radius * .7).fill({
+					color: control.color,
+					alpha: .65
+				});
+				if (control.directional && control.pressed) g.moveTo(center.x, center.y).lineTo(knob.x, knob.y).stroke({
+					color: control.color,
+					width: 4
+				});
+			}
+		}
+	}
+	dispose() {
+		if (this.dead) return;
+		this.dead = true;
+		const entries = [...this.entries.values()];
+		this.entries.clear();
+		cleanupAll([
+			this.off,
+			...entries.map((e) => () => this.release(e.graphics)),
+			() => this.display.destroy({ children: true })
+		], "Virtual input presentation cleanup failed");
+	}
+};
 // packages/web/src/renderer.ts
 var PixiRenderer = class {
 	host;
@@ -1915,6 +2231,46 @@ var PixiRenderer = class {
 	app = new Application();
 	pendingUITextKeys = /* @__PURE__ */ new Set();
 	canvasPresentations = /* @__PURE__ */ new Set();
+	virtualPresentations = /* @__PURE__ */ new Set();
+	get virtualInputDiagnostics() {
+		let controls = 0, visible = 0;
+		for (const visual of this.virtualPresentations) {
+			controls += visual.diagnostics.controls;
+			visible += visual.diagnostics.visible;
+		}
+		return {
+			presentations: this.virtualPresentations.size,
+			controls,
+			visible
+		};
+	}
+	prepareVirtualInput(input) {
+		if (!this.ready || this.dead) throw new EngineError("RENDERER_NOT_READY", "Renderer is not available");
+		const visual = new VirtualInputVisual(input, (graphics) => {
+			const context = graphics.context.uid;
+			graphics.destroy({ context: true });
+			releaseUIGraphics(this.app.renderer, graphics, context);
+		});
+		this.virtualPresentations.add(visual);
+		const off = input.onDispose(() => {
+			this.virtualPresentations.delete(visual);
+		});
+		let disposed = false;
+		return {
+			update: () => {
+				if (disposed || input.disposed) return;
+				if (!visual.display.parent) this.app.stage.addChild(visual.display);
+				visual.update();
+			},
+			dispose: () => {
+				if (disposed) return;
+				disposed = true;
+				off();
+				this.virtualPresentations.delete(visual);
+				visual.dispose();
+			}
+		};
+	}
 	get canvasDiagnostics() {
 		let nodes = 0, visibleNodes = 0, buttons = 0, syncs = 0, textMetrics = 0;
 		for (const p of this.canvasPresentations) {
@@ -2508,6 +2864,10 @@ var PixiRenderer = class {
 		this.scenes.clear();
 		cleanupAll([
 			...scenes.map((scene) => scene.dispose),
+			...[...this.virtualPresentations].map((p) => () => {
+				this.virtualPresentations.delete(p);
+				p.dispose();
+			}),
 			...[...this.canvasPresentations].map((p) => () => {
 				this.canvasPresentations.delete(p);
 				p.dispose();
@@ -2763,8 +3123,44 @@ var Game = class {
 	gamepads;
 	renderer;
 	keyboard;
+	captures;
+	captureInput(options = {}) {
+		this.assertAlive();
+		return this.captures.start(options);
+	}
 	pointers;
 	pointerChannels = /* @__PURE__ */ new WeakMap();
+	virtualInputs = /* @__PURE__ */ new WeakMap();
+	virtualPresentation;
+	get virtualInput() {
+		this.assertAlive();
+		return this.virtualFor(this.engine.scene);
+	}
+	virtualFor(scene) {
+		let input = this.virtualInputs.get(scene);
+		if (!input) {
+			input = new VirtualInput(this.channelFor(scene), this.engine.input);
+			this.virtualInputs.set(scene, input);
+			const owned = input;
+			input.onDispose(() => {
+				if (this.virtualInputs.get(scene) === owned) this.virtualInputs.delete(scene);
+				if (this.engine.scene === scene) {
+					this.virtualPresentation?.dispose();
+					this.virtualPresentation = void 0;
+				}
+			});
+		}
+		return input;
+	}
+	prepareVirtual(scene) {
+		const input = this.virtualInputs.get(scene);
+		if (!input || input.controls.length === 0) return;
+		const renderer = this.renderer;
+		if (!renderer.prepareVirtualInput) throw new EngineError("RENDERER_CAPABILITY", "Renderer does not support virtual input presentation");
+		const presentation = renderer.prepareVirtualInput(input);
+		input.onDispose(() => presentation.dispose());
+		return presentation;
+	}
 	canvas;
 	canvasPresentation;
 	defaultCanvas;
@@ -2874,8 +3270,12 @@ var Game = class {
 			request: (callback) => requestAnimationFrame(callback),
 			cancel: (handle) => cancelAnimationFrame(handle)
 		};
+		this.captures = new InputCaptureManager(this.element, this.engine.input, () => this.engine.scene, () => this.pointers.release(), this.report);
 		this.keyboard = new BrowserInput(this.element, this.engine.input);
-		this.gamepads = new GamepadInput(this.engine.input, { active: () => !document.hidden && document.hasFocus() && this.element.contains(document.activeElement) && !blocksGameKeyboard(document.activeElement) });
+		this.gamepads = new GamepadInput(this.engine.input, {
+			observe: (pads) => this.captures.sample(pads),
+			active: () => !document.hidden && document.hasFocus() && this.element.contains(document.activeElement) && !blocksGameKeyboard(document.activeElement)
+		});
 		this.pointers = new BrowserPointer(this.element, (event) => {
 			const rect = this.element.getBoundingClientRect();
 			if (rect.width <= 0 || rect.height <= 0) throw new EngineError("VIEWPORT_UNAVAILABLE", "Game has no visible bounds");
@@ -2885,7 +3285,7 @@ var Game = class {
 				world: this.screenToWorld(screen),
 				view: this.view
 			};
-		}, this.report, () => this.canvasPresentation?.update(this.width, this.height));
+		}, this.report, () => this.updateProjection(), this.engine.input);
 		document.addEventListener("visibilitychange", () => {
 			this.previousTime = void 0;
 			this.fixed?.reset();
@@ -3040,6 +3440,7 @@ var Game = class {
 			const scene = new Scene(id), nodes = [], controller = new AbortController();
 			let canvas;
 			const pointer = this.channelFor(scene);
+			const virtualFor = () => this.virtualFor(scene);
 			this.staging = scene;
 			scene.onDispose(() => controller.abort());
 			try {
@@ -3055,6 +3456,9 @@ var Game = class {
 					add: (actor) => scene.add(actor),
 					ui: (...items) => nodes.push(...items),
 					pointer,
+					get virtualInput() {
+						return virtualFor();
+					},
 					canvasUI: (root, options) => {
 						if (canvas) throw new EngineError("UI_OWNERSHIP", "A Scene has one Canvas UI root");
 						canvas = new CanvasUI(scene, root, options);
@@ -3093,6 +3497,7 @@ var Game = class {
 	async present(scene, nodes, canvas) {
 		let prepared, ui, committed = false;
 		let canvasPresentation;
+		let virtualPresentation;
 		try {
 			const preparing = this.renderer.prepare(scene);
 			preparing.then((value) => {
@@ -3113,6 +3518,7 @@ var Game = class {
 				canvasPresentation = renderer.prepareCanvasUI(canvas, this.pointers.routing);
 				scene.onDispose(() => canvasPresentation?.dispose());
 			}
+			virtualPresentation = this.prepareVirtual(scene);
 			scene.markReady();
 			this.errorBox.hidden = true;
 			try {
@@ -3123,18 +3529,20 @@ var Game = class {
 				this.report(error);
 			}
 			this.assertAlive();
-			const oldPrepared = this.prepared, oldUI = this.ui, oldCanvas = this.canvasPresentation;
+			const oldPrepared = this.prepared, oldUI = this.ui, oldCanvas = this.canvasPresentation, oldVirtual = this.virtualPresentation;
 			this.prepared = prepared;
 			this.ui = ui;
 			this.canvas = canvas;
 			this.canvasPresentation = canvasPresentation;
+			this.virtualPresentation = virtualPresentation;
 			this.pointers.routing.setScene(this.channelFor(scene), canvas);
 			committed = true;
 			this.element.append(ui.element);
 			for (const cleanup of [
 				() => oldPrepared?.dispose(),
 				() => oldUI?.dispose(),
-				() => oldCanvas?.dispose()
+				() => oldCanvas?.dispose(),
+				() => oldVirtual?.dispose()
 			]) try {
 				cleanup();
 			} catch (error) {
@@ -3150,7 +3558,8 @@ var Game = class {
 			if (!committed) for (const cleanup of [
 				() => prepared?.dispose(),
 				() => ui?.dispose(),
-				() => canvasPresentation?.dispose()
+				() => canvasPresentation?.dispose(),
+				() => virtualPresentation?.dispose()
 			]) try {
 				cleanup();
 			} catch (cleanupError) {
@@ -3262,6 +3671,7 @@ var Game = class {
 			width: this.width,
 			height: this.height
 		};
+		this.virtualInputs.get(this.engine.scene)?.refresh(viewport);
 		const previous = this.projection.viewport;
 		const c = this.camera;
 		if (!this.projectionDirty && previous.x === viewport.x && previous.y === viewport.y && previous.width === viewport.width && previous.height === viewport.height && this.cameraX === c.x && this.cameraY === c.y && this.cameraZoom === c.zoom) return;
@@ -3306,6 +3716,8 @@ var Game = class {
 	}
 	render() {
 		this.updateProjection();
+		this.virtualPresentation ??= this.prepareVirtual(this.engine.scene);
+		this.virtualPresentation?.update();
 		this.prepared?.render(this.projection);
 	}
 	tick = (time) => {
@@ -3319,12 +3731,14 @@ var Game = class {
 			} else {
 				const elapsed = this.previousTime === void 0 ? 0 : Math.max(0, (time - this.previousTime) / 1e3);
 				this.previousTime = time;
+				if (this.virtualInputs.has(this.engine.scene)) this.updateProjection();
 				if (this.playback) this.playback.advance(elapsed, this.options.fixedStep?.maxSteps ?? 8);
 				else if (this.fixed) this.fixed.advance(elapsed);
 				else this.engine.step(Math.min(this.maxDelta, elapsed));
 				if (!this.dead && !this.engine.scene.disposed) this.engine.scene.advancePresentation(Math.min(this.maxDelta, elapsed));
 				if (this.engine.paused) this.canvas?.stopMotion();
 				else this.canvas?.advance(elapsed);
+				this.virtualInputs.get(this.engine.scene)?.advance(Math.min(this.maxDelta, elapsed));
 				if (this.ratio !== (this.options.pixelRatio ?? Math.min(window.devicePixelRatio || 1, 2))) this.resize();
 				this.render();
 			}
@@ -3350,10 +3764,12 @@ var Game = class {
 		for (const cleanup of [
 			() => this.stopReplay(),
 			() => this.staging?.dispose(),
+			() => this.captures.dispose(),
 			() => this.pointers.dispose(),
 			() => this.gamepads.dispose(),
 			() => this.keyboard.dispose(),
 			() => this.canvasPresentation?.dispose(),
+			() => this.virtualPresentation?.dispose(),
 			() => this.canvas?.dispose(),
 			() => this.observer.disconnect(),
 			() => this.ui?.dispose(),
@@ -3371,6 +3787,7 @@ var Game = class {
 		this.staging = void 0;
 		this.canvas = void 0;
 		this.canvasPresentation = void 0;
+		this.virtualPresentation = void 0;
 		this.defaultCanvas = void 0;
 		this.defaultUI.length = 0;
 		this.scenes.clear();