Fix Input Mapping V2 gamepad detection and capture flow - PR_26140_089-fix-input-mapping-v2-gamepad-and-capture-flow

DavidQ · DavidQ · commit 970ef25e4c88 · 2026-05-21T19:45:46.000-04:00
diff --git a/docs/dev/reports/input_mapping_v2_gamepad_capture_flow_report.md b/docs/dev/reports/input_mapping_v2_gamepad_capture_flow_report.md
@@ -0,0 +1,56 @@
+# PR_26140_089 Input Mapping V2 Gamepad and Capture Flow Report
+
+## Scope
+- Fixed Input Mapping V2 gamepad/joystick detection and capture through the existing engine input path (`InputService` + `GamepadInputAdapter`).
+- Kept the tool generic and did not add duplicate input models or hardcoded game-specific behavior.
+- Updated capture flow so Add Action creates an empty mapping tile immediately, independent of capture.
+- Added per-tile action reassignment while preserving captured input deletion.
+- Updated capture controls to stack vertically and fill the available container width.
+- Preserved PR_26140_088 fullscreen layout, 175px by 175px mapping tiles, and external JS/CSS only.
+
+## Implementation Notes
+- `EngineInputSourceService` now refreshes gamepad state from the browser Game Controller API through the engine input service and records actionable WARN details when browser focus, permission, API availability, or timing prevents capture.
+- `ToolStarterApp` listens for `gamepadconnected` and `gamepaddisconnected`, refreshes engine input state, logs connection state, and refreshes the UI.
+- `InputMappingState` now supports empty visible mapping tiles and changing a tile's action after creation without requiring a captured input first.
+- `PreviewPanelControl` renders empty tiles, exposes a `Captured Mappings Action` dropdown per tile, and keeps token-click deletion behavior intact.
+- `inputMappingV2.css` makes the capture buttons a vertical full-width stack while preserving mapping tile dimensions.
+
+## Playwright Impact
+Yes. This PR changes Input Mapping V2 UI controls, gamepad detection/capture behavior, and toolState-facing mapping interactions.
+
+Playwright coverage was updated to validate:
+- connected gamepad detection state with a mocked browser Game Controller API gamepad,
+- actionable WARN logging when gamepad capture is unavailable,
+- stacked full-width capture buttons,
+- Add Action creating a tile without capture,
+- tile action reassignment after creation,
+- captured input token deletion,
+- preserved 175px by 175px mapping tiles and mapping list scroll behavior.
+
+## Validation
+- PASS: targeted syntax/import validation for changed Input Mapping V2 and Playwright files.
+- PASS: external JS/CSS sanity check for Input Mapping V2 HTML.
+- PASS: no legacy `gamepad-button` / `gamepad-axis` source values remain in Input Mapping V2 coverage paths.
+- PASS: focused Playwright validation:
+  `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs -g "launches Input Mapping V2 and captures keyboard mappings|uses header lifecycle controls and launches tools from fixed Workspace Manager V2 tiles"`
+- PASS: `npm run test:workspace-v2` (`60 passed`).
+- PASS: no sample JSON changes.
+- PASS: coverage changed JS guardrail reported no warnings.
+
+Full samples smoke test was not run, per PR scope.
+
+## Manual Validation
+1. Launch Workspace Manager V2 and open Input Mapping V2.
+2. Confirm Capture Keyboard, Capture Mouse, and Capture Gamepad are stacked vertically and fill the capture panel width.
+3. Select an action and click Add Action; confirm an empty 175px by 175px mapping tile appears immediately.
+4. Change the tile's Captured Mappings Action dropdown and confirm the tile/action selection updates.
+5. Capture Keyboard `KeyA`, confirm the token appears, then click the token and confirm it is deleted.
+6. Connect or enable a browser-visible gamepad, focus the page, and confirm Input Sources reports the connected controller; if unavailable, confirm the WARN explains browser focus/permission/API timing.
+
+## Files Changed
+- `tools/input-mapping-v2/js/services/InputMappingState.js`
+- `tools/input-mapping-v2/js/controls/PreviewPanelControl.js`
+- `tools/input-mapping-v2/js/ToolStarterApp.js`
+- `tools/input-mapping-v2/js/services/EngineInputSourceService.js`
+- `tools/input-mapping-v2/styles/inputMappingV2.css`
+- `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
diff --git a/tests/playwright/tools/WorkspaceManagerV2.spec.mjs b/tests/playwright/tools/WorkspaceManagerV2.spec.mjs
@@ -1435,27 +1435,52 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#previewOutput")).toContainText("No inputs captured yet.");
       await expect(page.locator(".input-mapping-v2__mapping-card")).toHaveCount(0);
       expect(await page.locator("#previewOutput").evaluate((node) => getComputedStyle(node).overflowY)).toBe("auto");
-      expect(Math.round((await page.locator("#inputMappingV2CaptureKeyboardButton").boundingBox()).width)).toBe(150);
+      const captureButtonLayout = await page.locator("#captureInputContent").evaluate((content) => {
+        const buttons = [
+          content.querySelector("#inputMappingV2CaptureKeyboardButton"),
+          content.querySelector("#inputMappingV2CaptureMouseButton"),
+          content.querySelector("#inputMappingV2CaptureGamepadButton")
+        ];
+        return buttons.map((button) => {
+          const box = button.getBoundingClientRect();
+          return {
+            left: Math.round(box.left),
+            top: Math.round(box.top),
+            width: Math.round(box.width)
+          };
+        });
+      });
+      expect(captureButtonLayout.every((entry) => entry.width > 250)).toBe(true);
+      expect(new Set(captureButtonLayout.map((entry) => entry.left)).size).toBe(1);
+      expect(captureButtonLayout[1].top).toBeGreaterThan(captureButtonLayout[0].top);
+      expect(captureButtonLayout[2].top).toBeGreaterThan(captureButtonLayout[1].top);
       await page.locator("#inputMappingV2ActionSelect").selectOption("moveLeft");
+      await page.locator("#inputMappingV2AddActionButton").click();
+      await expect(page.locator(".input-mapping-v2__mapping-card")).toHaveCount(1);
+      await expect(page.locator(".input-mapping-v2__empty-token", { hasText: "No inputs captured." })).toHaveCount(1);
+      const emptyMappingTileBox = await page.locator(".input-mapping-v2__mapping-card").first().boundingBox();
+      expect(Math.round(emptyMappingTileBox.width)).toBe(175);
+      expect(Math.round(emptyMappingTileBox.height)).toBe(175);
+      await page.locator(".input-mapping-v2__tile-action-select").first().selectOption("fire");
+      await expect(page.locator(".input-mapping-v2__tile-action-select").first()).toHaveValue("fire");
+      await expect(page.locator("#inputMappingV2ActionSelect")).toHaveValue("fire");
       await page.locator("#inputMappingV2CaptureKeyboardButton").click();
       await expect(page.locator("#inputMappingV2CaptureMessage")).toContainText("Press a keyboard key");
       await page.keyboard.press("KeyA");
       await expect(page.locator(".input-mapping-v2__mapping-card")).toHaveCount(1);
       const mappingTileBox = await page.locator(".input-mapping-v2__mapping-card").first().boundingBox();
       expect(Math.round(mappingTileBox.width)).toBe(175);
       expect(Math.round(mappingTileBox.height)).toBe(175);
-      await expect(page.locator("#previewOutput")).toContainText("Move Left");
       await expect(page.locator("#previewOutput")).toContainText("Keyboard KeyA");
-      await expect(page.locator("#inspectorOutput")).toContainText('"action": "moveLeft"');
+      await expect(page.locator("#inspectorOutput")).toContainText('"action": "fire"');
       await expect(page.locator("#inspectorOutput")).toContainText('"binding": "KeyA"');
       await page.locator(".input-mapping-v2__input-token", { hasText: "Keyboard KeyA" }).click();
       await expect(page.locator(".input-mapping-v2__input-token", { hasText: "Keyboard KeyA" })).toHaveCount(0);
-      await expect(page.locator("#previewOutput")).toContainText("No inputs captured yet.");
+      await expect(page.locator(".input-mapping-v2__empty-token", { hasText: "No inputs captured." })).toHaveCount(1);
       const actionValues = await page.locator("#inputMappingV2ActionSelect option").evaluateAll((options) => options.map((option) => option.value));
       for (const actionValue of actionValues.slice(0, 16)) {
         await page.locator("#inputMappingV2ActionSelect").selectOption(actionValue);
-        await page.locator("#inputMappingV2CaptureKeyboardButton").click();
-        await page.keyboard.press("KeyA");
+        await page.locator("#inputMappingV2AddActionButton").click();
       }
       const mappingListScroll = await page.locator("#previewOutput").evaluate((node) => ({
         clientHeight: node.clientHeight,
@@ -1466,6 +1491,28 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       expect(mappingListScroll.scrollHeight).toBeGreaterThan(mappingListScroll.clientHeight);
       await page.locator("#inputMappingV2CaptureGamepadButton").click();
       await expect(page.locator("#statusLog")).toHaveValue(/WARN Gamepad capture unavailable:/);
+      await expect(page.locator("#statusLog")).toHaveValue(/Click inside this page|browser focus|permission|Gamepad API timing|Hold a button/);
+      await page.evaluate(() => {
+        Object.defineProperty(navigator, "getGamepads", {
+          configurable: true,
+          value: () => [{
+            axes: [0, 0, 0, 0],
+            buttons: [{ pressed: true }, { pressed: false }],
+            connected: true,
+            id: "Mock Flight Stick",
+            index: 0,
+            mapping: "standard",
+            timestamp: 42
+          }]
+        });
+        window.dispatchEvent(new Event("gamepadconnected"));
+      });
+      await expect(page.locator("#inputMappingV2SourceList")).toContainText("1 connected gamepad");
+      await expect(page.locator("#inputMappingV2SourceList")).toContainText("Mock Flight Stick");
+      await page.locator("#inputMappingV2ActionSelect").selectOption("start");
+      await page.locator("#inputMappingV2CaptureGamepadButton").click();
+      await expect(page.locator("#previewOutput")).toContainText("Gamepad 0 Button 0");
+      await expect(page.locator("#inspectorOutput")).toContainText('"source": "gamepad"');
       const asteroidsManifestInputMapping = await page.evaluate(async () => {
         const response = await fetch("/games/Asteroids/game.manifest.json");
         const manifest = await response.json();
diff --git a/tools/input-mapping-v2/js/ToolStarterApp.js b/tools/input-mapping-v2/js/ToolStarterApp.js
@@ -26,6 +26,7 @@ export class ToolStarterApp {
     this.statusLog = statusLog;
     this.window = windowRef;
     this.captureMode = "";
+    this.handleGamepadConnectionChange = this.handleGamepadConnectionChange.bind(this);
     this.handleKeyDown = this.handleKeyDown.bind(this);
     this.handleMouseDown = this.handleMouseDown.bind(this);
   }
@@ -55,10 +56,13 @@ export class ToolStarterApp {
       onCaptureMouse: () => this.startMouseCapture()
     });
     this.engineInputSources.attach();
+    this.window.addEventListener("gamepadconnected", this.handleGamepadConnectionChange);
+    this.window.addEventListener("gamepaddisconnected", this.handleGamepadConnectionChange);
     this.window.addEventListener("keydown", this.handleKeyDown, true);
     this.window.addEventListener("mousedown", this.handleMouseDown, true);
     this.statusLog.mount();
     this.preview.mount({
+      onChangeTileAction: ({ actionId, nextActionId }) => this.changeTileAction(actionId, nextActionId),
       onDeleteBinding: ({ actionId, binding }) => this.deleteBinding(actionId, binding)
     });
     this.refreshActions();
@@ -77,6 +81,12 @@ export class ToolStarterApp {
     this.refreshActions();
   }
 
+  changeTileAction(actionId, nextActionId) {
+    const result = this.state.changeTileAction(actionId, nextActionId);
+    this.statusLog[result.ok ? "ok" : "warn"](result.message);
+    this.refreshActions();
+  }
+
   clearSelectedAction() {
     const result = this.state.clearSelectedAction();
     this.statusLog[result.ok ? "ok" : "warn"](result.message);
@@ -133,6 +143,16 @@ export class ToolStarterApp {
     this.addCapturedInput(result.input);
   }
 
+  handleGamepadConnectionChange() {
+    const status = this.engineInputSources.refreshGamepadState();
+    if (status.warning) {
+      this.statusLog.warn(status.warning);
+    } else {
+      this.statusLog.ok(status.message);
+    }
+    this.refreshActions();
+  }
+
   addCapturedInput(input) {
     const result = this.state.addBindingToSelectedAction(input);
     this.capture.showMessage(result.message);
diff --git a/tools/input-mapping-v2/js/controls/PreviewPanelControl.js b/tools/input-mapping-v2/js/controls/PreviewPanelControl.js
@@ -1,34 +1,62 @@
 export class PreviewPanelControl {
   constructor(output) {
     this.output = output;
+    this.onChangeTileAction = () => {};
     this.onDeleteBinding = () => {};
   }
 
-  mount({ onDeleteBinding }) {
+  mount({ onChangeTileAction, onDeleteBinding }) {
+    this.onChangeTileAction = onChangeTileAction;
     this.onDeleteBinding = onDeleteBinding;
   }
 
   render(actions) {
-    const mappedActions = actions.filter((action) => action.inputs.length > 0);
-    if (!mappedActions.length) {
+    const visibleActions = actions.filter((action) => action.tileVisible || action.inputs.length > 0);
+    if (!visibleActions.length) {
       this.output.replaceChildren(this.createEmptyState());
       return;
     }
-    this.output.replaceChildren(...mappedActions.map((action) => this.createActionCard(action)));
+    this.output.replaceChildren(...visibleActions.map((action) => this.createActionCard(action, actions)));
   }
 
-  createActionCard(action) {
+  createActionCard(action, actions) {
     const card = document.createElement("article");
     card.className = "input-mapping-v2__mapping-card";
 
-    const title = document.createElement("h2");
-    title.textContent = action.label;
+    const actionField = document.createElement("label");
+    actionField.className = "input-mapping-v2__tile-action-field";
+
+    const actionLabel = document.createElement("span");
+    actionLabel.textContent = "Captured Mappings Action";
+
+    const actionSelect = document.createElement("select");
+    actionSelect.className = "input-mapping-v2__tile-action-select";
+    actionSelect.dataset.inputMappingTileActionId = action.id;
+    actionSelect.append(...actions.map((entry) => {
+      const option = document.createElement("option");
+      option.value = entry.id;
+      option.textContent = entry.label;
+      option.selected = entry.id === action.id;
+      return option;
+    }));
+    actionSelect.addEventListener("change", () => {
+      this.onChangeTileAction({ actionId: action.id, nextActionId: actionSelect.value });
+    });
+
+    actionField.append(actionLabel, actionSelect);
 
     const tokens = document.createElement("div");
     tokens.className = "input-mapping-v2__token-list";
-    tokens.append(...action.inputs.map((input) => this.createInputToken(action.id, input)));
+    if (!action.inputs.length) {
+      const empty = document.createElement("span");
+      empty.className = "input-mapping-v2__empty-token";
+      empty.textContent = "No inputs captured.";
+      tokens.append(empty);
+    } else {
+      tokens.append(...action.inputs.map((input) => this.createInputToken(action.id, input)));
+    }
 
-    card.append(title, tokens);
+    card.append(actionField, tokens);
     return card;
   }
 
diff --git a/tools/input-mapping-v2/js/services/EngineInputSourceService.js b/tools/input-mapping-v2/js/services/EngineInputSourceService.js
@@ -11,15 +11,16 @@ export class EngineInputSourceService {
       getGamepads: () => this.readNavigatorGamepads()
     });
     this.gamepadAdapter = new GamepadInputAdapter({ input: this.inputService });
+    this.lastGamepadReadError = "";
   }
 
   attach() {
     this.inputService.attach();
   }
 
   sources() {
-    const gamepads = this.inputService.getGamepads();
-    const gamepadCount = gamepads.length;
+    const status = this.refreshGamepadState();
+    const gamepadCount = status.connectedCount;
     return [
       {
         name: "Keyboard",
@@ -33,12 +34,12 @@ export class EngineInputSourceService {
       },
       {
         name: "Gamepad Buttons",
-        detail: `${gamepadCount} connected gamepad${gamepadCount === 1 ? "" : "s"} detected for button capture.`,
+        detail: status.warning || `${gamepadCount} connected gamepad${gamepadCount === 1 ? "" : "s"} detected for button capture${status.connectedLabels ? `: ${status.connectedLabels}` : "."}`,
         engine: "InputService + GamepadState + GamepadInputAdapter"
       },
       {
         name: "Gamepad Axes",
-        detail: "Analog axes are reported when a connected gamepad axis crosses the capture threshold.",
+        detail: status.warning || "Analog axes are reported when a connected gamepad axis crosses the capture threshold.",
         engine: "GamepadInputAdapter"
       }
     ];
@@ -67,15 +68,21 @@ export class EngineInputSourceService {
     if (typeof this.window.navigator?.getGamepads !== "function") {
       return {
         ok: false,
-        message: "Gamepad capture unavailable: browser Gamepad API is not available in this context."
+        message: "Gamepad capture unavailable: browser Gamepad API is not available in this context. Use a focused browser tab that supports navigator.getGamepads."
+      };
+    }
+    const status = this.refreshGamepadState();
+    if (status.warning) {
+      return {
+        ok: false,
+        message: status.warning
       };
     }
-    this.inputService.update();
     const connectedIndices = this.gamepadAdapter.listConnectedIndices();
     if (!connectedIndices.length) {
       return {
         ok: false,
-        message: "Gamepad capture unavailable: connect a gamepad, press a button or move an axis, then capture again."
+        message: "Gamepad capture unavailable: no connected gamepad is visible. Click inside this page, press any gamepad button to wake or authorize the controller, check browser focus or permission prompts, then try again."
       };
     }
     for (const padIndex of connectedIndices) {
@@ -85,7 +92,7 @@ export class EngineInputSourceService {
         return {
           ok: true,
           input: {
-            source: "gamepad-button",
+            source: "gamepad",
             binding: `Pad${padIndex}:Button${buttonIndex}`,
             label: `Gamepad ${padIndex} Button ${buttonIndex}`,
             engine: "GamepadInputAdapter"
@@ -98,7 +105,7 @@ export class EngineInputSourceService {
         return {
           ok: true,
           input: {
-            source: "gamepad-axis",
+            source: "gamepad",
             binding: `Pad${padIndex}:Axis${axisIndex}${direction}`,
             label: `Gamepad ${padIndex} Axis ${axisIndex} ${direction}`,
             engine: "GamepadInputAdapter"
@@ -108,14 +115,46 @@ export class EngineInputSourceService {
     }
     return {
       ok: false,
-      message: "Gamepad capture unavailable: no pressed button or moved axis was visible from the Gamepad API."
+      message: "Gamepad capture unavailable: a connected gamepad was detected, but no live button or axis value was active. Hold a button or move a stick while pressing Capture Gamepad."
+    };
+  }
+
+  refreshGamepadState() {
+    this.inputService.update();
+    return this.gamepadStatus();
+  }
+
+  gamepadStatus() {
+    const gamepads = this.inputService.getGamepads();
+    const connectedLabels = gamepads
+      .map((gamepad) => `Gamepad ${gamepad.index}${gamepad.id ? ` ${gamepad.id}` : ""}`.trim())
+      .join(", ");
+    if (this.lastGamepadReadError) {
+      return {
+        connectedCount: 0,
+        connectedLabels: "",
+        message: "Gamepad API access blocked.",
+        warning: `Gamepad capture unavailable: browser focus, permission, or Gamepad API timing blocked live gamepad access (${this.lastGamepadReadError}). Click inside this page, press a gamepad button, allow browser permission if prompted, then try again.`
+      };
+    }
+    return {
+      connectedCount: gamepads.length,
+      connectedLabels,
+      message: `${gamepads.length} connected gamepad${gamepads.length === 1 ? "" : "s"} detected${connectedLabels ? `: ${connectedLabels}` : "."}`,
+      warning: ""
     };
   }
 
   readNavigatorGamepads() {
+    this.lastGamepadReadError = "";
     if (typeof this.window.navigator?.getGamepads !== "function") {
       return [];
     }
-    return Array.from(this.window.navigator.getGamepads() || []);
+    try {
+      return Array.from(this.window.navigator.getGamepads() || []);
+    } catch (error) {
+      this.lastGamepadReadError = error?.message || "unknown Gamepad API error";
+      return [];
+    }
   }
 }
diff --git a/tools/input-mapping-v2/js/services/InputMappingState.js b/tools/input-mapping-v2/js/services/InputMappingState.js
diff --git a/tools/input-mapping-v2/styles/inputMappingV2.css b/tools/input-mapping-v2/styles/inputMappingV2.css
