v1.2.0 - mobile support, sound effects, Playwright tests

- Touch controls (D-pad + action strip) for mobile browsers
- Responsive layout scales map/sidebar to narrow viewports
- Touch controls hidden on desktop; press t to toggle or auto-show on true mobile
- Shopkeeper passive until attacked
- Playwright E2E tests: navigation, gameplay, inventory, endgame, mobile (31 tests)
- GitHub Actions CI runs tests before deploying to Pages
- Mute indicator in sidebar
- Changelog screen (V key)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rickboy

.github/workflows/static.yml

@@ -15,7 +15,41 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: "yarn"
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        id: playwright-cache
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ hashFiles('**/yarn.lock') }}
+
+      - name: Install Playwright browsers
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+      - name: Install Playwright deps (cached)
+        if: steps.playwright-cache.outputs.cache-hit == 'true'
+        run: npx playwright install-deps chromium
+
+      - name: Run Playwright tests
+        run: yarn test
+
   deploy:
+    needs: test
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.gitignore

@@ -3,3 +3,5 @@ dist/
 .env
 .env.local
 *.local
+playwright-report/
+test-results/

index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no" />
     <title>webhack</title>
   </head>
   <body>

openspec/changes/mobile-support/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-15

openspec/changes/mobile-support/design.md

@@ -0,0 +1,67 @@
+## Context
+
+WebHack runs in the browser with all input handled via a single `keydown` listener in `useKeyboard` (App.tsx). The game map is rendered as a fixed CSS grid of monospace spans. The sidebar sits to the right. There are no touch handlers and no responsive breakpoints. On mobile, the map overflows, the sidebar is unusable, and no input is possible without a keyboard.
+
+The game state and dispatch interface (`useGame`) are untouched — touch controls simply call `dispatch` and `SoundEngine.play` the same way keyboard handlers do.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Touch input covers all gameplay actions reachable from the keyboard during `playing` phase: 8-directional movement, wait, pickup, inventory, stairs, mute
+- Swipe gestures (4-cardinal + 4-diagonal) as an alternative to D-pad taps
+- Context-sensitive action buttons change per phase (e.g., confirm/cancel in targeting, close in inventory)
+- Inventory screen items are tappable (no need to type the slot letter)
+- Menu screens (main menu, char select, death, victory, high scores, changelog) are fully tappable — existing click handlers already cover most of this
+- Responsive layout works at 320px minimum width
+- Desktop keyboard experience unchanged
+
+**Non-Goals:**
+- Native app or PWA packaging
+- Pinch-to-zoom map
+- Custom virtual keyboard for text entry (player names are hardcoded per class)
+- Gamepad/controller support
+
+## Decisions
+
+### 1. On-screen controls as a React component, not injected CSS
+**Decision**: New `TouchControls` component rendered inside `PlayingLayout`, visible only during touch-relevant phases.
+**Rationale**: Co-located with game UI, gets `dispatch` and `phase` as props, easy to conditionally render. No global event soup.
+**Alternative considered**: CSS-only overlay with pointer events — can't call dispatch, doesn't work.
+
+### 2. D-pad layout: fixed 3×3 grid with centre gap
+**Decision**: 3×3 button grid, 8 directional buttons, centre empty. Rendered as position-fixed overlay at bottom-centre of screen.
+**Rationale**: Familiar gamepad-style layout. Fixed positioning means it stays in place regardless of map scroll.
+**Alternative considered**: Floating buttons scattered around edges — harder to hit consistently.
+
+### 3. Swipe detection on the map canvas, not the whole document
+**Decision**: Attach `touchstart`/`touchend` listeners to the map container div via React `onTouchStart`/`onTouchEnd` props. Threshold: 30px, timeout: 400ms.
+**Rationale**: Avoids interfering with scroll on menu screens. Map area is the natural swipe target.
+**Alternative considered**: Document-level swipe listener — conflicts with browser scroll and overlays.
+
+### 4. Action button strip above D-pad
+**Decision**: Row of labelled icon buttons above the D-pad for: Wait (`.`), Pickup (`,`), Inventory (`i`), Stairs down (`>`), Stairs up (`<`). Secondary strip for: Mute (`M`), Help (`?`).
+**Rationale**: Most common actions need one-tap access. Less common actions (drop, equip, throw, cast) accessible via inventory screen once open.
+**Alternative considered**: Radial menu on long-press — complex to implement, poor discoverability.
+
+### 5. Inventory tap-to-select
+**Decision**: `InventoryPanel` renders each item as a tappable row. On tap, dispatch the appropriate action based on current `awaitingSecondKey` mode, or open a contextual action sheet (equip/use/drop) if no mode is active.
+**Rationale**: Letter-key slot system is the blocker for mobile inventory. Tap rows eliminate it without changing the underlying dispatch actions.
+**Alternative considered**: Expose slot letters as on-screen keyboard — too much screen space.
+
+### 6. Responsive layout: sidebar below map on narrow screens
+**Decision**: CSS media query at 600px. Above: current side-by-side layout. Below: map on top, sidebar as compact horizontal strip below, touch controls overlay on top of everything.
+**Rationale**: Map needs maximum width on mobile. Sidebar info is secondary; compacting it frees vertical space.
+**Alternative considered**: Collapsible sidebar drawer — adds complexity and a tap to access critical info like HP.
+
+### 7. Map tile font scaling
+**Decision**: Use `vw`-based font size on the map grid at narrow viewports so tiles fill the screen width.
+**Rationale**: Fixed `font-size: 14px` makes the 80-column map 1120px wide — wider than any phone. Scaling to viewport makes it playable.
+**Alternative considered**: Horizontal scroll — poor UX on touch, easy to lose position.
+
+## Risks / Trade-offs
+
+- **Map legibility at small sizes** → At 320px wide, 80 columns = 4px per tile. Roguelikes on phones are inherently small. Mitigation: use the smallest readable monospace size (~7-8px) and accept some squinting; the map is still functional.
+- **Touch controls overlap map content** → D-pad sits over bottom portion of map. Mitigation: reserve bottom ~160px of map area with padding so dungeon content isn't permanently hidden.
+- **Diagonal swipe detection is imprecise** → Human swipes are rarely perfectly diagonal. Mitigation: use 22.5° angle buckets (8 directions in 360°) for swipe classification.
+- **Inventory action sheet adds a tap** → Mobile inventory is slower (tap item → tap action) vs desktop (letter key). Acceptable trade-off; no good alternative.
+- **iOS Safari `touchend` quirks** → iOS sometimes fires `click` after `touchend`, causing double-dispatch. Mitigation: call `e.preventDefault()` on touchend handlers.

openspec/changes/mobile-support/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+WebHack is currently keyboard-only, making it unplayable on mobile browsers where no physical keyboard is present. Adding touch controls expands the audience to mobile players without breaking the existing desktop experience.
+
+## What Changes
+
+- Add on-screen virtual D-pad and action button overlay for touch input
+- Add swipe gesture recognition as an alternative movement input
+- Make the game layout responsive so the map and sidebar render usably on small screens
+- Inventory and menu screens must be tappable (letter-key selection replaced with tap-to-select)
+- All existing keyboard shortcuts remain fully functional
+
+## Capabilities
+
+### New Capabilities
+
+- `touch-controls`: On-screen directional pad, action buttons, and swipe gesture input that translate to the same game actions as keyboard keys. Includes contextual button sets (movement in playing phase, confirm/cancel in menus).
+- `responsive-layout`: CSS layout that adapts the game map, sidebar, and overlays to small viewport sizes (≥320px wide). Map tiles scale to fit; sidebar collapses or moves below map on narrow screens.
+
+### Modified Capabilities
+
+- none
+
+## Impact
+
+- `src/App.tsx` — touch event wiring, context-sensitive button rendering
+- `src/components/` — new TouchControls component, updates to Sidebar and screen components for tap interaction
+- `src/index.css` — responsive breakpoints, touch overlay styles, tap-target sizing
+- `src/hooks/useGame.ts` — no changes required (dispatch interface unchanged)
+- No new npm dependencies — use native pointer/touch events

openspec/changes/mobile-support/specs/responsive-layout/spec.md

@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Viewport meta tag
+The HTML document SHALL include a viewport meta tag that disables user scaling and sets initial scale to 1.0, preventing unwanted browser zoom on the game UI.
+
+#### Scenario: Viewport tag present
+- **WHEN** page loads on a mobile browser
+- **THEN** the viewport SHALL be set to device width with no user-scalable zoom
+
+### Requirement: Responsive game layout
+The game layout SHALL adapt to the viewport width. At viewports wider than 600px the existing side-by-side layout (map left, sidebar right) SHALL be preserved. At viewports 600px and below the map SHALL occupy full width and the sidebar SHALL render as a compact horizontal strip below the map.
+
+#### Scenario: Wide layout preserved on desktop
+- **WHEN** viewport width is greater than 600px
+- **THEN** map and sidebar render side by side as currently
+
+#### Scenario: Narrow layout on mobile
+- **WHEN** viewport width is 600px or less
+- **THEN** map occupies full viewport width and sidebar renders below map as a horizontal strip
+
+#### Scenario: Sidebar horizontal strip shows key stats
+- **WHEN** sidebar renders in horizontal strip mode
+- **THEN** it SHALL display at minimum: HP, dungeon level, hunger state, and mute indicator
+
+### Requirement: Map tile font scaling on narrow viewports
+The game map font size SHALL scale so that all 80 columns fit within the viewport width on screens narrower than 800px. The minimum font size SHALL be 7px.
+
+#### Scenario: Map fits on 375px phone
+- **WHEN** viewport width is 375px
+- **THEN** all 80 map columns SHALL be visible without horizontal scrolling
+
+#### Scenario: Font size floor
+- **WHEN** viewport is very narrow (less than 320px)
+- **THEN** font size SHALL NOT drop below 7px
+
+### Requirement: Touch target minimum size
+All interactive buttons in the touch controls overlay SHALL have a minimum tap target size of 44×44px to meet mobile usability standards.
+
+#### Scenario: D-pad buttons are tappable
+- **WHEN** D-pad is rendered on a 375px wide screen
+- **THEN** each directional button SHALL have a touch target of at least 44×44px
+
+#### Scenario: Action buttons are tappable
+- **WHEN** action strip is rendered
+- **THEN** each action button SHALL have a touch target of at least 44×44px
+
+### Requirement: Touch controls do not permanently obscure map content
+The touch control overlay SHALL be positioned such that the active dungeon area above it remains fully visible. The map container SHALL reserve vertical space at the bottom equal to the height of the controls overlay.
+
+#### Scenario: Map content above controls is unobscured
+- **WHEN** touch controls are rendered
+- **THEN** dungeon tiles in the upper portion of the map SHALL be fully visible and not hidden behind controls

openspec/changes/mobile-support/specs/touch-controls/spec.md

@@ -0,0 +1,92 @@
+## ADDED Requirements
+
+### Requirement: On-screen directional pad
+The system SHALL render a 3×3 D-pad overlay during the `playing`, `targeting`, and `awaitingItemKey` phases. The eight directional buttons SHALL dispatch the same `MOVE` actions as keyboard movement keys. The centre cell SHALL be empty.
+
+#### Scenario: D-pad tap moves player
+- **WHEN** user taps a directional button on the D-pad during `playing` phase
+- **THEN** player moves one tile in the corresponding direction, identical to pressing the matching keyboard key
+
+#### Scenario: D-pad not shown on menu screens
+- **WHEN** game phase is `mainMenu`, `charSelect`, `dead`, `victory`, `highScores`, or `changelog`
+- **THEN** D-pad overlay SHALL NOT be rendered
+
+#### Scenario: D-pad visible during targeting
+- **WHEN** game phase is `targeting`
+- **THEN** D-pad SHALL be rendered and tapping a direction moves the targeting cursor
+
+### Requirement: Action button strip
+The system SHALL render a row of labelled action buttons above the D-pad for the most common gameplay actions. The strip SHALL include: Wait, Pickup, Inventory, Stairs Down, Stairs Up, Mute, Help.
+
+#### Scenario: Wait button
+- **WHEN** user taps the Wait button
+- **THEN** system dispatches `WAIT` action, identical to pressing `.`
+
+#### Scenario: Pickup button
+- **WHEN** user taps the Pickup button
+- **THEN** system dispatches `PICKUP` action, identical to pressing `,`
+
+#### Scenario: Inventory button
+- **WHEN** user taps the Inventory button
+- **THEN** system dispatches `OPEN_INVENTORY`, identical to pressing `i`
+
+#### Scenario: Stairs Down button
+- **WHEN** user taps the Stairs Down button
+- **THEN** system dispatches `STAIRS` with direction `down`, identical to pressing `>`
+
+#### Scenario: Stairs Up button
+- **WHEN** user taps the Stairs Up button
+- **THEN** system dispatches `STAIRS` with direction `up`, identical to pressing `<`
+
+#### Scenario: Mute button
+- **WHEN** user taps the Mute button
+- **THEN** mute state toggles, identical to pressing `M`
+
+#### Scenario: Help button
+- **WHEN** user taps the Help button
+- **THEN** help overlay opens, identical to pressing `?`
+
+### Requirement: Swipe gesture movement
+The system SHALL detect swipe gestures on the game map area and translate them to directional movement in `playing` phase. Swipes SHALL support all 8 directions using 45° angle buckets. Minimum swipe distance SHALL be 30px. Maximum swipe duration SHALL be 400ms.
+
+#### Scenario: Cardinal swipe moves player
+- **WHEN** user swipes right on the map area with distance ≥30px within 400ms
+- **THEN** player moves east, identical to pressing `l` or arrow right
+
+#### Scenario: Diagonal swipe moves player
+- **WHEN** user swipes diagonally (e.g. up-right) on the map area
+- **THEN** player moves in the matching diagonal direction (NE)
+
+#### Scenario: Slow swipe ignored
+- **WHEN** user drags finger across map but takes longer than 400ms
+- **THEN** no movement is dispatched
+
+#### Scenario: Short touch ignored
+- **WHEN** user taps map without moving finger 30px
+- **THEN** no movement is dispatched (tap is not a swipe)
+
+### Requirement: Inventory tap-to-select
+The system SHALL make each inventory item row tappable. When no second-key action is pending, tapping an item SHALL present an action sheet with context-appropriate options (Equip/Unequip, Use, Drop). When a second-key action is pending (equip, use, drop, cast), tapping an item SHALL immediately dispatch that action for the tapped item.
+
+#### Scenario: Tap item with no pending action shows action sheet
+- **WHEN** user taps an inventory item and no `awaitingSecondKey` mode is active
+- **THEN** an action sheet appears with relevant options for that item type
+
+#### Scenario: Tap item during equip mode dispatches equip
+- **WHEN** `awaitingSecondKey` is `equip` and user taps an inventory item
+- **THEN** system dispatches `EQUIP` for that item and closes await mode
+
+#### Scenario: Tap item during drop mode dispatches drop
+- **WHEN** `awaitingSecondKey` is `drop` and user taps an inventory item
+- **THEN** system dispatches `DROP` for that item and closes await mode
+
+#### Scenario: Tap item during use mode dispatches use
+- **WHEN** `awaitingSecondKey` is `use` and user taps an inventory item
+- **THEN** system dispatches `USE` for that item and closes await mode
+
+### Requirement: Touch controls prevent default browser behaviour
+All touch event handlers on game controls SHALL call `preventDefault()` to suppress browser scroll, zoom, and double-tap zoom on the game UI.
+
+#### Scenario: No scroll on D-pad touch
+- **WHEN** user touches the D-pad or action buttons
+- **THEN** page SHALL NOT scroll and browser SHALL NOT zoom

openspec/changes/mobile-support/tasks.md

@@ -0,0 +1,50 @@
+## 1. Viewport and Base CSS
+
+- [x] 1.1 Add `<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">` to `index.html`
+- [x] 1.2 Add `touch-action: none` and `-webkit-tap-highlight-color: transparent` to `#game-root` in `index.css`
+- [x] 1.3 Add responsive breakpoint in `index.css` at 600px: map full-width, sidebar becomes horizontal strip below map
+- [x] 1.4 Add map tile font scaling in `index.css` using `vw` units at narrow viewports so 80 columns fit without horizontal scroll (min 7px)
+- [x] 1.5 Reserve bottom padding on map container equal to touch controls overlay height so dungeon content is not permanently hidden
+
+## 2. Responsive Sidebar
+
+- [x] 2.1 In `src/components/Sidebar.tsx` add horizontal strip layout variant for narrow viewports (CSS class or media query): shows HP, depth, hunger, mute indicator in one row
+- [x] 2.2 Verify sidebar horizontal strip renders key stats and does not overflow at 375px width
+
+## 3. TouchControls Component
+
+- [x] 3.1 Create `src/components/TouchControls.tsx` with a 3×3 D-pad grid (8 directional buttons, centre empty)
+- [x] 3.2 Each D-pad button dispatches `MOVE` with the correct direction on `touchend` with `preventDefault()`
+- [x] 3.3 D-pad buttons have minimum 44×44px touch targets
+- [x] 3.4 Add action button strip above D-pad: Wait, Pickup, Inventory, Stairs Down, Stairs Up
+- [x] 3.5 Add secondary action buttons: Mute (toggles mute + updates local state), Help (dispatches `SET_PHASE help`)
+- [x] 3.6 Position TouchControls as `position: fixed` at bottom-centre of screen
+- [x] 3.7 Render TouchControls only during `playing`, `targeting`, and `awaitingItemKey` phases
+- [x] 3.8 During `targeting` phase, D-pad dispatches `SET_TARGET` (move cursor) instead of `MOVE`
+
+## 4. Swipe Gesture Detection
+
+- [x] 4.1 In `src/components/Map.tsx` (or a `useSwipe` hook) attach `onTouchStart` and `onTouchEnd` to the map container div
+- [x] 4.2 On `touchend`, compute dx/dy from start; if distance ≥30px and duration ≤400ms, classify direction using 45° angle buckets (8 directions)
+- [x] 4.3 Dispatch `MOVE` with the classified direction during `playing` phase; call `preventDefault()` on both touch events
+- [x] 4.4 Ignore swipes during non-playing phases (no dispatch)
+
+## 5. Inventory Tap-to-Select
+
+- [x] 5.1 In `src/components/InventoryPanel.tsx` make each item row tappable (add `onClick` handler)
+- [x] 5.2 When `awaitingSecondKey` mode is active (equip/drop/use), tapping an item dispatches the pending action for that item and clears await mode
+- [x] 5.3 When no await mode is active, tapping an item opens a contextual action sheet (small inline div or modal) with relevant options: Equip/Unequip, Use, Drop — each dispatching the correct action on tap
+- [x] 5.4 Action sheet closes on tap-outside or Escape
+
+## 6. Wire TouchControls into App
+
+- [x] 6.1 Import and render `TouchControls` in `PlayingLayout` in `src/App.tsx`, passing `state`, `dispatch`, `muted`, and `setMuted` props
+- [x] 6.2 Pass `phase` and `awaitingSecondKey` to `TouchControls` so it can render context-correct buttons and D-pad behaviour
+
+## 7. Verify
+
+- [ ] 7.1 Test on Chrome mobile emulator at 375×667px: map fits, D-pad works, action buttons work
+- [ ] 7.2 Test on real iOS Safari: no double-dispatch, no scroll bleed, no zoom on tap
+- [ ] 7.3 Test on real Android Chrome: same checks
+- [ ] 7.4 Verify keyboard input still works on desktop after changes
+- [x] 7.5 Confirm `npm run build` passes with no TypeScript errors

openspec/changes/playwright-tests/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-16