feat: complete keyboard flows and stabilize camp focus

scripts/verify-battle-keyboard-command-flow-browser.mjs

@@ -0,0 +1,551 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright';
+import {
+  desktopBrowserContextOptions,
+  desktopBrowserViewport
+} from './desktop-browser-viewport.mjs';
+
+const battleId = 'second-battle-yellow-turban-pursuit';
+const renderer = process.env.VERIFY_BATTLE_KEYBOARD_RENDERER;
+if (!renderer) {
+  for (const requestedRenderer of ['canvas', 'webgl']) {
+    const result = spawnSync(
+      process.execPath,
+      [fileURLToPath(import.meta.url)],
+      {
+        cwd: process.cwd(),
+        env: {
+          ...process.env,
+          VERIFY_BATTLE_KEYBOARD_RENDERER: requestedRenderer
+        },
+        stdio: 'inherit'
+      }
+    );
+    if (result.status !== 0) {
+      process.exit(result.status ?? 1);
+    }
+  }
+  process.exit(0);
+}
+assert(
+  renderer === 'canvas' || renderer === 'webgl',
+  `Unsupported renderer: ${renderer}`
+);
+const baseUrl =
+  process.env.VERIFY_BATTLE_KEYBOARD_URL ??
+  'http://127.0.0.1:41796/heros_web/';
+const targetUrl = withDebugOptions(baseUrl, renderer);
+
+let serverProcess;
+let browser;
+
+try {
+  serverProcess = await ensureLocalServer(targetUrl);
+  browser = await chromium.launch({
+    headless: process.env.VERIFY_BATTLE_KEYBOARD_HEADLESS !== '0'
+  });
+  const context = await browser.newContext(desktopBrowserContextOptions);
+  const page = await context.newPage();
+  page.setDefaultTimeout(30000);
+
+  const pageErrors = [];
+  const consoleErrors = [];
+  page.on('pageerror', (error) => pageErrors.push(error.stack ?? error.message));
+  page.on('console', (message) => {
+    if (message.type() === 'error') {
+      consoleErrors.push(message.text());
+    }
+  });
+
+  await page.goto(targetUrl, {
+    waitUntil: 'domcontentloaded',
+    timeout: 90000
+  });
+  await page.evaluate(() => window.localStorage.clear());
+  await page.reload({
+    waitUntil: 'domcontentloaded',
+    timeout: 90000
+  });
+  await waitForDebugApi(page);
+  await assertDesktopViewport(page);
+  await assertRendererAndBasePath(page, renderer);
+
+  await page.evaluate((requestedBattleId) => {
+    window.__HEROS_DEBUG__?.goToBattle(requestedBattleId);
+  }, battleId);
+  await page.waitForFunction(
+    (requestedBattleId) => {
+      const battle = window.__HEROS_DEBUG__?.battle();
+      return (
+        battle?.battleId === requestedBattleId &&
+        ['deployment', 'idle'].includes(battle.phase) &&
+        battle.mapBackgroundReady === true &&
+        (battle.phase === 'idle' ||
+          ['ready', 'degraded'].includes(battle.combatAssets?.status))
+      );
+    },
+    battleId,
+    { timeout: 90000 }
+  );
+
+  await page.evaluate(() => {
+    const scene = window.__HEROS_GAME__?.scene.getScene('BattleScene');
+    if (scene?.phase === 'deployment') {
+      scene.confirmPreBattleDeployment();
+    }
+  });
+  await page.waitForFunction(
+    (requestedBattleId) => {
+      const battle = window.__HEROS_DEBUG__?.battle();
+      return battle?.battleId === requestedBattleId && battle.phase === 'idle';
+    },
+    battleId,
+    { timeout: 30000 }
+  );
+
+  const fixture = await page.evaluate(async () => {
+    const scene = window.__HEROS_GAME__?.scene.getScene('BattleScene');
+    const units = scene?.debugBattleUnits?.() ?? [];
+    const unit = units.find(
+      (candidate) =>
+        candidate.id === 'liu-bei' &&
+        candidate.faction === 'ally' &&
+        candidate.hp > 0
+    );
+    if (!scene || !unit) {
+      return null;
+    }
+
+    scene.hideBattleEventBanner();
+    scene.hideTurnEndPrompt();
+    scene.hideSaveSlotPanel();
+    scene.hideMapMenu();
+    scene.hideCommandMenu();
+    scene.clearMarkers();
+    scene.activeFaction = 'ally';
+    scene.phase = 'idle';
+    scene.selectedUnit = undefined;
+    scene.pendingMove = undefined;
+    scene.targetingAction = undefined;
+    scene.selectedUsable = undefined;
+    scene.actedUnitIds.clear();
+    units
+      .filter((candidate) => candidate.faction === 'ally' && candidate.hp > 0)
+      .forEach((candidate) => {
+        candidate.hp = candidate.maxHp;
+      });
+    scene.centerCameraOnTile(unit.x, unit.y);
+    scene.selectUnit(unit);
+    await scene.moveSelectedUnit(unit.x, unit.y);
+
+    const recordPointerInput = () => {
+      window.__HEROS_KEYBOARD_COMMAND_QA__.pointerInputCount += 1;
+    };
+    window.__HEROS_KEYBOARD_COMMAND_QA__ = {
+      pointerInputCount: 0,
+      recordPointerInput
+    };
+    window.addEventListener('mousedown', recordPointerInput, true);
+    window.addEventListener('pointerdown', recordPointerInput, true);
+
+    const state = window.__HEROS_DEBUG__?.battle();
+    return {
+      unitId: unit.id,
+      unitTile: { x: unit.x, y: unit.y },
+      pendingMove: state?.pendingMove ?? null,
+      commandMenu: state?.commandMenuKeyboard ?? null
+    };
+  });
+
+  assert(fixture, 'Expected the keyboard command fixture to select Liu Bei.');
+  assert(
+    fixture.pendingMove?.unitId === fixture.unitId,
+    `Expected a preserved pending stay-in-place move: ${JSON.stringify(fixture)}`
+  );
+  assertCommandMenuFocus(fixture.commandMenu, 'command');
+  assert(
+    fixture.commandMenu.items.some(
+      ({ id, available }) => id === 'attack' && available === false
+    ),
+    `Expected the distant attack command to be unavailable for skip QA: ${JSON.stringify(fixture.commandMenu)}`
+  );
+  assert(
+    fixture.commandMenu.items.some(
+      ({ id, available }) => id === 'strategy' && available
+    ),
+    `Expected Liu Bei to have an available strategy: ${JSON.stringify(fixture.commandMenu)}`
+  );
+  assert(
+    fixture.commandMenu.focusedItem.id === 'strategy',
+    `Default focus must skip unavailable attack and land on strategy: ${JSON.stringify(fixture.commandMenu)}`
+  );
+
+  await page.screenshot({
+    path: `dist/verification-battle-keyboard-command-focus-${renderer}.png`,
+    fullPage: true
+  });
+
+  const initialCommandFocus = fixture.commandMenu.focusedItem.id;
+  const availableCommandIds = fixture.commandMenu.items
+    .filter(({ available }) => available)
+    .map(({ id }) => id);
+  const previousCommandId =
+    availableCommandIds[
+      (availableCommandIds.indexOf(initialCommandFocus) -
+        1 +
+        availableCommandIds.length) %
+        availableCommandIds.length
+    ];
+
+  await page.keyboard.press('Shift+Tab');
+  let state = await readBattleState(page);
+  assertCommandMenuFocus(state.commandMenuKeyboard, 'command');
+  assert(
+    state.commandMenuKeyboard.focusedItem.id === previousCommandId,
+    `Shift+Tab must wrap to the previous available command: ${JSON.stringify(state.commandMenuKeyboard)}`
+  );
+
+  await page.keyboard.press('Tab');
+  state = await readBattleState(page);
+  assert(
+    state.commandMenuKeyboard.focusedItem.id === initialCommandFocus,
+    `Tab must wrap back to the initial command without visiting a disabled row: ${JSON.stringify(state.commandMenuKeyboard)}`
+  );
+
+  const visitedCommands = [];
+  for (let index = 0; index < availableCommandIds.length; index += 1) {
+    await page.keyboard.press('Tab');
+    state = await readBattleState(page);
+    assertCommandMenuFocus(state.commandMenuKeyboard, 'command');
+    visitedCommands.push(state.commandMenuKeyboard.focusedItem.id);
+  }
+  assert(
+    visitedCommands.at(-1) === initialCommandFocus &&
+      visitedCommands.every((id) => availableCommandIds.includes(id)),
+    `Command focus must wrap and skip every unavailable row: ${JSON.stringify({
+      availableCommandIds,
+      visitedCommands
+    })}`
+  );
+
+  await focusMenuItem(page, 'strategy');
+  const beforeUsable = await readBattleState(page);
+  await page.keyboard.press('Enter');
+  await page.waitForFunction(() => {
+    const keyboard = window.__HEROS_DEBUG__?.battle()?.commandMenuKeyboard;
+    return keyboard?.visible === true && keyboard.mode === 'usable';
+  });
+
+  state = await readBattleState(page);
+  assertCommandMenuFocus(state.commandMenuKeyboard, 'usable');
+  assert(
+    state.selectedUnitId === fixture.unitId &&
+      state.pendingMove?.unitId === fixture.unitId &&
+      state.commandMenuKeyboard.parentCommand === 'strategy',
+    `Entering the usable menu must preserve unit and pending move: ${JSON.stringify(state)}`
+  );
+  assert(
+    state.commandMenuKeyboard.items.some(({ available }) => !available) &&
+      state.commandMenuKeyboard.focusedItem.available === true,
+    `Usable default focus must skip an unavailable full-HP heal: ${JSON.stringify(state.commandMenuKeyboard)}`
+  );
+  assert(
+    !state.commandMenuKeyboard.items.find(
+      ({ id }) => id === state.commandMenuKeyboard.focusedItem.id
+    )?.available === false,
+    `Usable focus landed on an unavailable item: ${JSON.stringify(state.commandMenuKeyboard)}`
+  );
+
+  await page.keyboard.press('Shift+Tab');
+  state = await readBattleState(page);
+  assertCommandMenuFocus(state.commandMenuKeyboard, 'usable');
+  assert(
+    state.commandMenuKeyboard.focusedItem.available === true,
+    `Usable Shift+Tab must skip unavailable rows: ${JSON.stringify(state.commandMenuKeyboard)}`
+  );
+
+  await page.screenshot({
+    path: `dist/verification-battle-keyboard-usable-focus-${renderer}.png`,
+    fullPage: true
+  });
+
+  await page.keyboard.press('Escape');
+  await page.waitForFunction(() => {
+    const keyboard = window.__HEROS_DEBUG__?.battle()?.commandMenuKeyboard;
+    return (
+      keyboard?.visible === true &&
+      keyboard.mode === 'command' &&
+      keyboard.focusedItem?.id === 'strategy'
+    );
+  });
+  state = await readBattleState(page);
+  assertCommandMenuFocus(state.commandMenuKeyboard, 'command');
+  assert(
+    state.selectedUnitId === fixture.unitId &&
+      state.pendingMove?.unitId === fixture.unitId &&
+      state.pendingMove.toX === beforeUsable.pendingMove.toX &&
+      state.pendingMove.toY === beforeUsable.pendingMove.toY,
+    `Esc must return one level without clearing selection or pending move: ${JSON.stringify(state)}`
+  );
+
+  await focusMenuItem(page, 'wait');
+  await page.keyboard.press('Enter');
+  await page.waitForFunction(
+    (unitId) => {
+      const battle = window.__HEROS_DEBUG__?.battle();
+      return (
+        battle?.commandMenuKeyboard?.visible === false &&
+        battle?.actedUnitIds?.includes(unitId)
+      );
+    },
+    fixture.unitId
+  );
+
+  const completed = await page.evaluate((unitId) => {
+    const state = window.__HEROS_DEBUG__?.battle();
+    const qa = window.__HEROS_KEYBOARD_COMMAND_QA__;
+    if (qa?.recordPointerInput) {
+      window.removeEventListener('mousedown', qa.recordPointerInput, true);
+      window.removeEventListener('pointerdown', qa.recordPointerInput, true);
+    }
+    return {
+      selectedUnitId: state?.selectedUnitId ?? null,
+      pendingMove: state?.pendingMove ?? null,
+      acted: state?.actedUnitIds?.includes(unitId) ?? false,
+      commandMenu: state?.commandMenuKeyboard ?? null,
+      pointerInputCount: qa?.pointerInputCount ?? -1
+    };
+  }, fixture.unitId);
+  assert(
+    completed.acted &&
+      completed.pendingMove === null &&
+      completed.commandMenu?.visible === false,
+    `Keyboard Enter on wait must complete exactly one unit action: ${JSON.stringify(completed)}`
+  );
+  assert(
+    completed.pointerInputCount === 0,
+    `The command action cycle emitted mouse/pointer input after setup: ${JSON.stringify(completed)}`
+  );
+  assert(
+    pageErrors.length === 0,
+    `Unexpected browser errors: ${JSON.stringify(pageErrors.slice(-5))}`
+  );
+  assert(
+    consoleErrors.length === 0,
+    `Unexpected console errors: ${JSON.stringify(consoleErrors.slice(-5))}`
+  );
+
+  console.log(
+    `Verified ${renderer} keyboard-only battle command flow at ${desktopBrowserViewport.width}x${desktopBrowserViewport.height} DPR1 under /heros_web/: ` +
+      'default focus skips disabled commands, Tab and Shift+Tab wrap available rows, Enter opens strategy, ' +
+      'usable focus skips unavailable choices, Esc preserves the selected unit and pending move, and Enter completes wait with zero mouse input.'
+  );
+} finally {
+  await browser?.close();
+  await stopServerProcess(serverProcess);
+}
+
+function withDebugOptions(url, requestedRenderer) {
+  const parsed = new URL(url);
+  parsed.searchParams.set('debug', '1');
+  parsed.searchParams.set('renderer', requestedRenderer);
+  parsed.searchParams.set('debugCombatAssetWatchdogMs', '250');
+  return parsed.toString();
+}
+
+async function focusMenuItem(page, expectedId) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const keyboard = await page.evaluate(
+      () => window.__HEROS_DEBUG__?.battle()?.commandMenuKeyboard
+    );
+    assertCommandMenuFocus(keyboard, keyboard?.mode);
+    if (keyboard.focusedItem.id === expectedId) {
+      return;
+    }
+    const target = keyboard.items.find(({ id }) => id === expectedId);
+    assert(
+      target?.available,
+      `Expected ${expectedId} to be keyboard-selectable: ${JSON.stringify(keyboard)}`
+    );
+    await page.keyboard.press('Tab');
+  }
+  throw new Error(`Could not focus command menu item ${expectedId}.`);
+}
+
+function assertCommandMenuFocus(keyboard, expectedMode) {
+  assert(
+    keyboard?.visible === true &&
+      keyboard.mode === expectedMode &&
+      keyboard.focusedItem?.available === true &&
+      keyboard.focusedItem.bounds &&
+      keyboard.focusedItem.lineWidth >= 3 &&
+      keyboard.focusMarker?.visible === true &&
+      keyboard.focusMarker.text === '▶' &&
+      keyboard.focusMarker.bounds &&
+      boundsInside(keyboard.focusMarker.bounds, keyboard.focusedItem.bounds) &&
+      keyboard.guidance?.text.includes('↑↓/Tab') &&
+      keyboard.guidance.text.includes('Enter') &&
+      keyboard.guidance.text.includes('Esc') &&
+      boundsInsideViewport(keyboard.guidance.bounds),
+    `Expected one visible non-color keyboard focus and on-screen controls guidance: ${JSON.stringify(keyboard)}`
+  );
+  assert(
+    keyboard.items.filter(({ focused }) => focused).length === 1,
+    `Expected exactly one focused menu item: ${JSON.stringify(keyboard)}`
+  );
+}
+
+async function readBattleState(page) {
+  return page.evaluate(() => window.__HEROS_DEBUG__?.battle());
+}
+
+function boundsInside(inner, outer) {
+  return (
+    inner.x >= outer.x - 1 &&
+    inner.y >= outer.y - 1 &&
+    inner.x + inner.width <= outer.x + outer.width + 1 &&
+    inner.y + inner.height <= outer.y + outer.height + 1
+  );
+}
+
+function boundsInsideViewport(bounds) {
+  return (
+    bounds &&
+    bounds.x >= 0 &&
+    bounds.y >= 0 &&
+    bounds.x + bounds.width <= desktopBrowserViewport.width &&
+    bounds.y + bounds.height <= desktopBrowserViewport.height
+  );
+}
+
+async function waitForDebugApi(page) {
+  await page.waitForFunction(
+    () =>
+      Boolean(
+        window.__HEROS_DEBUG__?.activeScenes &&
+          window.__HEROS_DEBUG__?.goToBattle
+      ),
+    undefined,
+    { timeout: 90000 }
+  );
+}
+
+async function assertDesktopViewport(page) {
+  const viewport = await page.evaluate(() => {
+    const canvas = document.querySelector('canvas');
+    return {
+      width: window.innerWidth,
+      height: window.innerHeight,
+      dpr: window.devicePixelRatio,
+      zoom: window.visualViewport?.scale ?? 1,
+      canvas: canvas
+        ? { width: canvas.width, height: canvas.height }
+        : null
+    };
+  });
+  assert(
+    viewport.width === desktopBrowserViewport.width &&
+      viewport.height === desktopBrowserViewport.height &&
+      viewport.dpr === 1 &&
+      viewport.zoom === 1 &&
+      viewport.canvas?.width === desktopBrowserViewport.width &&
+      viewport.canvas?.height === desktopBrowserViewport.height,
+    `Expected explicit 1920x1080 CSS viewport, 100% zoom, and DPR1: ${JSON.stringify(viewport)}`
+  );
+}
+
+async function assertRendererAndBasePath(page, requestedRenderer) {
+  const runtime = await page.evaluate(() => ({
+    pathname: window.location.pathname,
+    rendererType: window.__HEROS_GAME__?.renderer?.type ?? null,
+    rendererName:
+      window.__HEROS_GAME__?.renderer?.constructor?.name ?? null
+  }));
+  const expectedRendererType = requestedRenderer === 'canvas' ? 1 : 2;
+  assert(
+    runtime.pathname === '/heros_web/' &&
+      runtime.rendererType === expectedRendererType,
+    `Expected ${requestedRenderer} under /heros_web/: ${JSON.stringify(runtime)}`
+  );
+}
+
+async function ensureLocalServer(url) {
+  if (await canReach(url)) {
+    return undefined;
+  }
+
+  const parsed = new URL(url);
+  if (!['localhost', '127.0.0.1', '0.0.0.0'].includes(parsed.hostname)) {
+    throw new Error(`No server responded at ${url}`);
+  }
+
+  const stderr = [];
+  const child = spawn(
+    process.execPath,
+    [
+      'node_modules/vite/bin/vite.js',
+      '--host',
+      '127.0.0.1',
+      '--port',
+      parsed.port || '41796',
+      '--strictPort'
+    ],
+    {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    }
+  );
+  child.stderr.on('data', (chunk) => stderr.push(chunk.toString()));
+  child.stdout.on('data', () => {});
+
+  for (let attempt = 0; attempt < 120; attempt += 1) {
+    if (await canReach(url)) {
+      return child;
+    }
+    await delay(250);
+  }
+
+  await stopServerProcess(child);
+  throw new Error(
+    `Vite server did not start at ${url}\n${stderr.join('')}`
+  );
+}
+
+async function canReach(url) {
+  try {
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(1000)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function stopServerProcess(child) {
+  if (!child || child.exitCode !== null) {
+    return;
+  }
+
+  const exited = new Promise((resolve) => {
+    child.once('exit', resolve);
+  });
+  child.kill();
+  await Promise.race([exited, delay(5000)]);
+  if (child.exitCode === null) {
+    child.kill('SIGKILL');
+    await Promise.race([exited, delay(2000)]);
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}