Interactive and agent-api control gameplay

[dmigwi]

Summary

This PR introduces the browser-side control architecture needed to support both human keyboard/touch gameplay and API-driven agent gameplay. The existing browser game is now driven through a shared maze-action contract, with separate interactive and agent-api control modes layered on top of the same runtime, traversal, rendering, persistence, and scoring behavior.

What Changed

Maze Control Modes

• Added a shared MazeActionControl interface for browser control modes.
• Added interactive mode for human keyboard and touch input.
• Added agent-api mode for HTTP-driven maze traversal by configured agents.
• Moved shared pause/proceed/wall/restart handling into reusable session-action helpers.
• Kept human-owned session actions available in both modes while limiting agent-owned actions to traversal moves.

Agent API Runtime

• Added an agent polling loop that sends the current maze state to configured agents.

• Supports batched move predictions using the response shape:

  {
    "moves": ["MoveRight", "MoveDown"]
  }

• Replays submitted moves in order and stops on the first invalid move or when the destination is reached.

• Applies score decay based on submitted predictions or fixed mistake decay for malformed responses.

• Disables agents on network/HTTP/timeout failures without applying score decay.

• Moves the game into await-agent state when no enabled agents are available.

Agent Context Payload

• Added structured agent-facing maze state through MazeActionState.
• Includes current cell, destination cell, allowed moves, expected response format, status, score, and traversal history.
• Tracks traversal history as ordered logical cell visits.
• Includes playerName per traversal entry so multiple agents can share the same maze while retaining per-agent movement history.
• Uses { row, col } logical cell coordinates for agent-facing payloads.

Traversal Cleanup

• Added frontend/app/traversal.ts to centralize movement and coordinate logic.
• Shared movement validation between interactive gameplay and agent feedback.
• Added helpers for move deltas, move-action validation, coordinate conversion, traversal history lookup, wall-weight cycling, and total cell calculation.
• Reduced duplicated traversal logic between game runtime and agent context generation.

Persistence Updates

• Persisted round snapshots now include traversal history.
• Added agent configuration storage support.
• Namespaced browser storage by control mode so interactive and agent-api state do not collide.
• Added snapshot version validation and cleanup for incompatible stored rounds.
• Added support for disabling network-failed agents while preserving their saved configuration.

Rendering And UI Behavior

• Added await-agent status rendering for agent-api mode.
• Updated compact navigation messaging for small/touch displays.
• Kept touch controls and keyboard session controls available where appropriate.
• Updated agents.html to initialize the agent-api control mode.
• Updated index.html to initialize the interactive control mode.
• Added mode helpers such as isAgentApiMode() and isInteractiveMode() for clearer status branching.

Maze And Viewport Improvements

• Improved maze dimension selection by preferring less-skewed candidates.
• Added viewport fit classification helpers for too-small length, width, or full-size failures.
• Improved total-cell handling through a reusable helper instead of repeating length * width logic.

Configuration Cleanup

• Reorganized CONFIG into nested sections for runtime, messages, controls, maze, generation, scoring, timing, viewport, storage, and agent API settings.
• Removed unused duplicate navigation messages.
• Centralized runtime defaults and user-facing browser text.
• Embedded ARIA labels directly in HTML where they are static accessibility metadata.

Testing

Added and expanded frontend tests for:

• Interactive control mode
• Agent API control mode
• Agent polling and replay behavior
• Agent network/timeout handling
• Session action routing
• Agent context generation
• Traversal helpers
• Storage and persistence validation
• Rendering states
• Maze generation snapshots
• Viewport and DOM behavior

Current frontend test coverage includes:

• agent-context.test.ts
• control/agent-api.test.ts
• control/agent.test.ts
• control/interactive.test.ts
• control/session-actions.test.ts
• traversal.test.ts
• Expanded game.test.ts, render.test.ts, storage.test.ts, and maze tests

Validation

The following checks pass locally:

CI=true pnpm --config.confirmModulesPurge=false run typecheck:frontend
CI=true pnpm --config.confirmModulesPurge=false run lint:frontend
CI=true pnpm --config.confirmModulesPurge=false run test:frontend

Frontend tests pass with 100 tests across 14 test files.