Add Input Mapping V2 haptics and shortcut suppression - PR_26140_104-add-input-mapping-v2-haptics-and-shortcut-suppression

Author: ToolboxAid

docs/dev/reports/input_mapping_v2_haptics_shortcut_suppression_report.md

@@ -0,0 +1,107 @@
+# Input Mapping V2 Haptics + Shortcut Suppression Report
+
+PR: PR_26140_104-add-input-mapping-v2-haptics-and-shortcut-suppression
+
+## Source of Truth
+
+- Read `docs/dev/PROJECT_INSTRUCTIONS.md` before implementation.
+- Active `docs/pr/BUILD_PR.md` is an unrelated Level 18 rebase note, so this report follows the explicit PR104 user request as the current BUILD scope.
+- One PR purpose: add engine-backed game controller haptics support and scoped Input Mapping V2 shortcut suppression.
+
+## Changes
+
+- Added `src/engine/input/GamepadHapticsService.js` as a reusable engine input service for game controller haptics.
+- Uses browser Gamepad API haptics only when available:
+  - `gamepad.vibrationActuator.playEffect("dual-rumble", ...)`.
+  - `gamepad.hapticActuators[].pulse(...)`.
+  - `gamepad.hapticActuators[].playEffect(...)` when present.
+- Does not fake rumble when unsupported; unsupported, unavailable, or blocked haptics return actionable WARN messages.
+- Wired Input Mapping V2 through `EngineInputSourceService` so the tool consumes the engine haptics service rather than owning local haptics runtime logic.
+- Moved haptics UI into the Game Controller device section:
+  - support state per detected controller,
+  - selected-action `Enable Rumble` checkbox,
+  - strength and duration controls,
+  - `Test Rumble` button only for supported controllers.
+- Added scoped `Suppress Shortcuts` checkbox in the Capture accordion header.
+- Suppression is scoped to the Input Mapping V2 workspace root only:
+  - Ctrl/Meta + Wheel is prevented inside the tool area when enabled,
+  - Alt/Ctrl/Meta key browser/page shortcuts are suppressed inside the tool area when enabled where the browser permits,
+  - shortcuts are not suppressed when the checkbox is disabled,
+  - behavior outside the tool area is not suppressed.
+- Preserved `Disable Context` behavior.
+- Preserved capture, combo, gesture, tile selection, and selected-input highlighting behavior.
+- Adjusted combo polling so held game controller input repeats do not overwrite the first captured combo prompt with a duplicate-input warning while waiting for the second input.
+
+## ToolState / Schema
+
+- No schemas changed.
+- No sample JSON changed.
+- Haptics settings are kept UI-local per selected action because the existing Input Mapping V2 tool-local mapping/toolState contract does not expose a compatible action-options field for persisting rumble settings without schema drift.
+
+## Playwright Impact
+
+Playwright impacted: Yes.
+
+Focused Workspace V2 coverage now validates:
+
+- haptics support state is displayed for mocked gamepads,
+- `Test Rumble` calls a mocked supported actuator,
+- unsupported haptics logs an actionable WARN,
+- `Enable Rumble` can be toggled for the selected mapping/action,
+- shortcut suppression checkbox appears,
+- Ctrl + Wheel is prevented inside Input Mapping V2 when enabled,
+- Alt key suppression is applied inside Input Mapping V2 when enabled,
+- shortcuts are not suppressed when the checkbox is disabled,
+- `Disable Context` still works.
+
+## Validation
+
+Passed:
+
+- `node --check src/engine/input/GamepadHapticsService.js`
+- `node --check tools/input-mapping-v2/js/services/EngineInputSourceService.js`
+- `node --check tools/input-mapping-v2/js/ToolStarterApp.js`
+- `node --check tools/input-mapping-v2/js/bootstrap.js`
+- `node --check tools/input-mapping-v2/js/controls/CaptureControl.js`
+- `node --check tools/input-mapping-v2/js/controls/DeviceListControl.js`
+- `node --check tests/input/GamepadHapticsService.test.mjs`
+- `node --check tests/run-tests.mjs`
+- `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `node -e "const module = await import('./src/engine/input/GamepadHapticsService.js'); if (typeof module.default !== 'function') throw new Error('GamepadHapticsService default export missing');"`
+- `node -e "const test = await import('./tests/input/GamepadHapticsService.test.mjs'); await test.run();"`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs -g "Input Mapping V2" --project=playwright --workers=1 --reporter=list` - 2 passed.
+- `npm run test:workspace-v2` - 61 passed.
+- `git diff --check` - passed; Git reported LF-to-CRLF working-copy warnings only.
+- `git status --short -- samples games` - no sample/game JSON changes.
+- `rg "imageDataUrl" tools/input-mapping-v2 src/engine/input tests/input tests/playwright/tools/WorkspaceManagerV2.spec.mjs` - no matches.
+
+Notes:
+
+- An initial full `npm run test:workspace-v2` run reached 60/61 and exposed a duplicate held-gamepad combo polling issue in the updated Input Mapping V2 test path. The app was fixed to ignore silent duplicate gamepad repeats during combo polling, the focused Input Mapping V2 slice passed, and the full suite was rerun successfully with 61/61 passing.
+- Full samples smoke test was skipped by explicit PR instruction.
+- Playwright V8 coverage was produced at `docs/dev/reports/playwright_v8_coverage_report.txt`; `docs/dev/reports/coverage_changed_js_guardrail.txt` reports no changed runtime JS coverage warnings.
+
+## Manual Validation
+
+1. Open Input Mapping V2 in Workspace V2.
+2. Connect or mock a game controller with haptics support.
+3. Confirm the Game Controller device section shows haptics support state and a `Test Rumble` button for supported controllers only.
+4. Select an action tile, enable `Enable Rumble`, adjust strength/duration, and click `Test Rumble`.
+5. Confirm unsupported controllers log a WARN instead of faking rumble.
+6. Enable `Suppress Shortcuts` and verify Ctrl + Wheel does not zoom the page while the pointer is inside Input Mapping V2.
+7. Verify right-click context suppression still follows only the separate `Disable Context` checkbox.
+8. Disable `Suppress Shortcuts` and confirm browser/page shortcuts behave normally again.
+
+## Files Changed
+
+- `src/engine/input/GamepadHapticsService.js`
+- `tests/input/GamepadHapticsService.test.mjs`
+- `tests/run-tests.mjs`
+- `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `tools/input-mapping-v2/index.html`
+- `tools/input-mapping-v2/js/ToolStarterApp.js`
+- `tools/input-mapping-v2/js/bootstrap.js`
+- `tools/input-mapping-v2/js/controls/CaptureControl.js`
+- `tools/input-mapping-v2/js/controls/DeviceListControl.js`
+- `tools/input-mapping-v2/js/services/EngineInputSourceService.js`
+- `tools/input-mapping-v2/styles/inputMappingV2.css`

src/engine/input/GamepadHapticsService.js

@@ -0,0 +1,176 @@
+/*
+Toolbox Aid
+David Quesenberry
+05/22/2026
+GamepadHapticsService.js
+*/
+
+const DEFAULT_DURATION_MS = 80;
+const DEFAULT_STRONG_MAGNITUDE = 0.25;
+const DEFAULT_WEAK_MAGNITUDE = 0.15;
+
+export default class GamepadHapticsService {
+    constructor({ getGamepads = defaultGetGamepads } = {}) {
+        this.getGamepads = getGamepads;
+    }
+
+    getStatusReport() {
+        const read = this.readGamepads();
+        if (!read.ok) {
+            return {
+                apiAvailable: false,
+                gamepads: [],
+                warning: read.message,
+            };
+        }
+
+        return {
+            apiAvailable: true,
+            gamepads: read.gamepads.map((gamepad) => this.createStatus(gamepad)),
+            warning: '',
+        };
+    }
+
+    async testRumble(gamepadIndex, options = {}) {
+        const read = this.readGamepads();
+        if (!read.ok) {
+            return {
+                ok: false,
+                message: `Gamepad rumble unavailable: ${read.message}`,
+            };
+        }
+
+        const selectedIndex = Number(gamepadIndex);
+        const gamepad = read.gamepads.find((candidate) => Number(candidate?.index) === selectedIndex);
+        if (!gamepad) {
+            return {
+                ok: false,
+                message: `Gamepad rumble unavailable: Gamepad ${selectedIndex} is not connected. Click inside this page, press the controller, and try again.`,
+            };
+        }
+
+        const actuator = findHapticActuator(gamepad);
+        if (!actuator) {
+            return {
+                ok: false,
+                message: `Gamepad rumble unavailable: ${gamepadLabel(gamepad)} does not expose GamepadHapticActuator, hapticActuators, or vibrationActuator. Use a browser and controller with haptics support.`,
+            };
+        }
+
+        const settings = normalizeRumbleSettings(options);
+        try {
+            await playHaptics(actuator, settings);
+            return {
+                ok: true,
+                message: `Test rumble sent to ${gamepadLabel(gamepad)}.`,
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                message: `Gamepad rumble unavailable: haptic actuator request failed for ${gamepadLabel(gamepad)} (${error?.message || 'unknown error'}). Try a compatible controller with browser haptics support.`,
+            };
+        }
+    }
+
+    readGamepads() {
+        if (typeof this.getGamepads !== 'function') {
+            return {
+                ok: false,
+                gamepads: [],
+                message: 'Gamepad API provider is not available.',
+            };
+        }
+
+        try {
+            return {
+                ok: true,
+                gamepads: Array.from(this.getGamepads() || []).filter((gamepad) => Boolean(gamepad && gamepad.connected !== false)),
+                message: '',
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                gamepads: [],
+                message: `navigator.getGamepads() failed (${error?.message || 'unknown error'}). Click inside this page, reconnect the controller, and try again.`,
+            };
+        }
+    }
+
+    createStatus(gamepad) {
+        const actuator = findHapticActuator(gamepad);
+        return {
+            actuatorType: actuator?.type ?? '',
+            id: String(gamepad?.id || ''),
+            index: Number.isInteger(Number(gamepad?.index)) ? Number(gamepad.index) : 0,
+            label: gamepadLabel(gamepad),
+            supported: Boolean(actuator),
+        };
+    }
+}
+
+function defaultGetGamepads() {
+    if (typeof navigator === 'undefined' || typeof navigator.getGamepads !== 'function') {
+        return [];
+    }
+    return navigator.getGamepads() ?? [];
+}
+
+function findHapticActuator(gamepad) {
+    const vibrationActuator = gamepad?.vibrationActuator;
+    if (vibrationActuator && typeof vibrationActuator.playEffect === 'function') {
+        return {
+            actuator: vibrationActuator,
+            mode: 'playEffect',
+            type: 'vibrationActuator',
+        };
+    }
+
+    const hapticActuator = Array.isArray(gamepad?.hapticActuators)
+        ? gamepad.hapticActuators.find((actuator) => typeof actuator?.pulse === 'function' || typeof actuator?.playEffect === 'function')
+        : null;
+    if (!hapticActuator) {
+        return null;
+    }
+
+    return {
+        actuator: hapticActuator,
+        mode: typeof hapticActuator.playEffect === 'function' ? 'playEffect' : 'pulse',
+        type: 'hapticActuators',
+    };
+}
+
+async function playHaptics(hapticActuator, settings) {
+    if (hapticActuator.mode === 'playEffect') {
+        await hapticActuator.actuator.playEffect('dual-rumble', {
+            duration: settings.durationMs,
+            strongMagnitude: settings.strongMagnitude,
+            weakMagnitude: settings.weakMagnitude,
+        });
+        return;
+    }
+
+    await hapticActuator.actuator.pulse(Math.max(settings.strongMagnitude, settings.weakMagnitude), settings.durationMs);
+}
+
+function normalizeRumbleSettings(options) {
+    const strength = clampNumber(options.strength, DEFAULT_STRONG_MAGNITUDE, 0, 1);
+    return {
+        durationMs: Math.round(clampNumber(options.durationMs, DEFAULT_DURATION_MS, 20, 2000)),
+        strongMagnitude: strength,
+        weakMagnitude: clampNumber(options.weakMagnitude, Math.min(strength, DEFAULT_WEAK_MAGNITUDE), 0, 1),
+    };
+}
+
+function clampNumber(value, fallback, minimum, maximum) {
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return fallback;
+    }
+    return Math.max(minimum, Math.min(maximum, number));
+}
+
+function gamepadLabel(gamepad) {
+    const index = Number.isInteger(Number(gamepad?.index)) ? Number(gamepad.index) : 0;
+    const id = String(gamepad?.id || '').trim();
+    return `${id || 'Gamepad'} (Gamepad ${index})`;
+}

tests/input/GamepadHapticsService.test.mjs

@@ -0,0 +1,70 @@
+/*
+Toolbox Aid
+David Quesenberry
+05/22/2026
+GamepadHapticsService.test.mjs
+*/
+
+import GamepadHapticsService from '../../src/engine/input/GamepadHapticsService.js';
+
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+
+export async function run() {
+    const calls = [];
+    const service = new GamepadHapticsService({
+        getGamepads: () => [
+            {
+                connected: true,
+                id: 'Supported Vibration Controller',
+                index: 0,
+                vibrationActuator: {
+                    playEffect: async (effect, parameters) => {
+                        calls.push({ effect, parameters, type: 'vibrationActuator' });
+                    },
+                },
+            },
+            {
+                connected: true,
+                hapticActuators: [{
+                    pulse: async (value, duration) => {
+                        calls.push({ duration, type: 'hapticActuators', value });
+                    },
+                }],
+                id: 'Supported Pulse Controller',
+                index: 1,
+            },
+            {
+                connected: true,
+                id: 'No Haptics Controller',
+                index: 2,
+            },
+        ],
+    });
+
+    const status = service.getStatusReport();
+    assert(status.gamepads[0].supported === true, 'vibrationActuator gamepad should report haptics support.');
+    assert(status.gamepads[0].actuatorType === 'vibrationActuator', 'vibrationActuator status should identify the actuator source.');
+    assert(status.gamepads[1].supported === true, 'hapticActuators gamepad should report haptics support.');
+    assert(status.gamepads[1].actuatorType === 'hapticActuators', 'hapticActuators status should identify the actuator source.');
+    assert(status.gamepads[2].supported === false, 'Gamepad without haptic actuators should report unsupported haptics.');
+
+    const vibrationResult = await service.testRumble(0, { durationMs: 120, strength: 0.7 });
+    assert(vibrationResult.ok === true, 'vibrationActuator test rumble should succeed.');
+    assert(calls[0].effect === 'dual-rumble', 'vibrationActuator should use dual-rumble.');
+    assert(calls[0].parameters.duration === 120, 'vibrationActuator should receive duration.');
+    assert(calls[0].parameters.strongMagnitude === 0.7, 'vibrationActuator should receive strong magnitude.');
+
+    const pulseResult = await service.testRumble(1, { durationMs: 90, strength: 0.4 });
+    assert(pulseResult.ok === true, 'hapticActuators pulse test rumble should succeed.');
+    assert(calls[1].type === 'hapticActuators', 'hapticActuators should use pulse when playEffect is unavailable.');
+    assert(calls[1].duration === 90, 'pulse actuator should receive duration.');
+    assert(calls[1].value === 0.4, 'pulse actuator should receive strength.');
+
+    const unsupportedResult = await service.testRumble(2);
+    assert(unsupportedResult.ok === false, 'Unsupported haptics should not fake rumble.');
+    assert(unsupportedResult.message.includes('does not expose'), 'Unsupported haptics should return an actionable message.');
+}