📝 update CHANGELOG for Issue #6 debug view

F3 toggles a debug overlay with:
- FPS
- Mouse world/tile coordinates
- Tile type under cursor
- Resources, buildings, crops on hovered tile
- Nisse count broken down by AI state (idle/walking/working/sleeping)
- Active jobs by type (chop/mine/farm)
- Pathfinding visualization: cyan lines + destination highlight
  drawn in world space via DebugSystem

Added DebugSystem to GameScene. VillagerSystem exposes
getActivePaths() for the path visualization. JSDoc added to all
previously undocumented methods in VillagerSystem, WorldSystem,
GameScene, and UIScene.

.claude/settings.local.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(curl:)",
+      "Bash(curl -s \"https://git.zally.dev/api/v1/repos/tekki/nissefolk/issues/1\" -H \"Authorization: token de54ccf9eadd5950a6ea5fa264b6404acdecc732\")",
+      "Bash(python3 -m json.tool)",
+      "Bash(curl -s \"https://git.zally.dev/api/v1/repos/tekki/nissefolk/issues/1/timeline\" -H \"Authorization: token de54ccf9eadd5950a6ea5fa264b6404acdecc732\")",
+      "Bash(curl:*)",
+      "Bash(python3 -c \":*)",
+      "Bash(git checkout:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm run:*)",
+      "Bash(/usr/local/bin/npm run:*)",
+      "Bash(/home/tekki/.nvm/versions/node/v24.14.0/bin/npm run:*)",
+      "Bash(export PATH=\"/home/tekki/.nvm/versions/node/v24.14.0/bin:$PATH\")",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(d.get\\(''''html_url'''', d.get\\(''''message'''',''''''''\\)\\)\\)\")",
+      "Bash(git pull:*)",
+      "Bash(for id:*)",
+      "Bash(do echo:*)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(d.get\\(''''html_url'''',''''''''\\)\\)\")",
+      "Bash(TOKEN=\"de54ccf9eadd5950a6ea5fa264b6404acdecc732\" BASE=\"https://git.zally.dev/api/v1/repos/tekki/nissefolk\" __NEW_LINE_2bc8ebfb809e4939__ for id in 5 6 7 9)",
+      "Bash(TOKEN=\"de54ccf9eadd5950a6ea5fa264b6404acdecc732\")",
+      "Bash(BASE=\"https://git.zally.dev/api/v1/repos/tekki/nissefolk\")",
+      "Bash(__NEW_LINE_5d5fe245d6f316dc__ for:*)",
+      "Bash(do)",
+      "Bash(done)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(d.get\\(''''html_url'''',''''''''\\), d.get\\(''''number'''',''''''''\\), d.get\\(''''message'''',''''''''\\)\\)\")",
+      "Bash(git remote:*)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(d.get\\(''''login'''',''''''''\\), d.get\\(''''message'''',''''''''\\)\\)\")"
+    ]
+  }
+}

CHANGELOG.md

@@ -7,6 +7,9 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Added
+- **F3 Debug View**: toggleable overlay showing FPS, tile type and contents under the cursor, Nisse count by AI state, active jobs by type, and pathfinding visualization (cyan lines in world space)
+
 ### Fixed
 - Nisse now clear the FOREST/ROCK tile after harvesting, opening paths to deeper resources
 - Nisse no longer get stuck idle after depositing items at the stockpile
@@ -20,6 +23,12 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Villagers are now called **Nisse** throughout the UI (panel, controls hint, stockpile display, context menu, spawn message)
 
 ### Added
+- Scroll wheel zooms toward the mouse cursor position (zoom-to-mouse), correctly accounting for Phaser's center-based zoom model
+- Middle mouse button held: pan the camera by dragging
+- Test environment at `/test.html` with `ZoomTestScene` (Phaser default) and `ZoomMouseScene` (zoom-to-mouse) for camera behaviour analysis; file-logging via Vite middleware to `game-test.log`
+
+### Fixed
+- `getCenterWorld()` in `CameraSystem` returned wrong world coordinates at zoom ≠ 1; corrected from `scrollX + width/(2·zoom)` to `scrollX + width/2`
 - Right-click context menu: suppresses browser default, shows Build and Nisse actions in the game world
 - Initial project setup: Phaser 3 + TypeScript + Vite
 - Core scenes: `BootScene`, `GameScene`, `UIScene`

game-test.log

@@ -0,0 +1,5 @@
+{"t":1774091984264,"event":"snapshot","zoom":1,"scrollX":321,"scrollY":562,"vpScreen":{"w":958,"h":475},"vpWorld":{"w":958,"h":475},"vpTiles":{"w":29.938,"h":14.844},"centerWorld":{"x":800,"y":799.5},"mouse":{"screen":{"x":0,"y":0},"world":{"x":0,"y":0}}}
+{"t":1774091986280,"event":"snapshot","zoom":1,"scrollX":321,"scrollY":562,"vpScreen":{"w":958,"h":475},"vpWorld":{"w":958,"h":475},"vpTiles":{"w":29.938,"h":14.844},"centerWorld":{"x":800,"y":799.5},"mouse":{"screen":{"x":288,"y":400},"world":{"x":609,"y":961.5}}}
+{"t":1774091988280,"event":"snapshot","zoom":1,"scrollX":321,"scrollY":562,"vpScreen":{"w":958,"h":475},"vpWorld":{"w":958,"h":475},"vpTiles":{"w":29.938,"h":14.844},"centerWorld":{"x":800,"y":799.5},"mouse":{"screen":{"x":288,"y":400},"world":{"x":609,"y":961.5}}}
+{"t":1774091990281,"event":"snapshot","zoom":1,"scrollX":321,"scrollY":562,"vpScreen":{"w":958,"h":475},"vpWorld":{"w":958,"h":475},"vpTiles":{"w":29.938,"h":14.844},"centerWorld":{"x":800,"y":799.5},"mouse":{"screen":{"x":288,"y":400},"world":{"x":609,"y":961.5}}}
+{"t":1774091992281,"event":"snapshot","zoom":1,"scrollX":321,"scrollY":562,"vpScreen":{"w":958,"h":475},"vpWorld":{"w":958,"h":475},"vpTiles":{"w":29.938,"h":14.844},"centerWorld":{"x":800,"y":799.5},"mouse":{"screen":{"x":288,"y":400},"world":{"x":609,"y":961.5}}}

src/scenes/GameScene.ts

@@ -9,6 +9,7 @@ import { ResourceSystem } from '../systems/ResourceSystem'
 import { BuildingSystem } from '../systems/BuildingSystem'
 import { FarmingSystem } from '../systems/FarmingSystem'
 import { VillagerSystem } from '../systems/VillagerSystem'
+import { DebugSystem } from '../systems/DebugSystem'
 
 export class GameScene extends Phaser.Scene {
   private adapter!: LocalAdapter
@@ -18,11 +19,16 @@ export class GameScene extends Phaser.Scene {
   private buildingSystem!: BuildingSystem
   private farmingSystem!: FarmingSystem
   villagerSystem!: VillagerSystem
+  debugSystem!: DebugSystem
   private autosaveTimer = 0
   private menuOpen = false
 
   constructor() { super({ key: 'Game' }) }
 
+  /**
+   * Initialises all game systems, wires up inter-system events,
+   * launches the UI scene overlay, and starts the autosave timer.
+   */
   create(): void {
     this.adapter = new LocalAdapter()
 
@@ -33,6 +39,7 @@ export class GameScene extends Phaser.Scene {
     this.farmingSystem  = new FarmingSystem(this, this.adapter)
     this.villagerSystem = new VillagerSystem(this, this.adapter, this.worldSystem)
     this.villagerSystem.init(this.resourceSystem, this.farmingSystem)
+    this.debugSystem    = new DebugSystem(this, this.villagerSystem, this.worldSystem)
 
     this.worldSystem.create()
     this.renderPersistentObjects()
@@ -56,6 +63,8 @@ export class GameScene extends Phaser.Scene {
     this.villagerSystem.create()
     this.villagerSystem.onMessage = (msg) => this.events.emit('toast', msg)
 
+    this.debugSystem.create()
+
     // Sync tile changes and building visuals through adapter
     this.adapter.onAction = (action) => {
       if (action.type === 'CHANGE_TILE') {
@@ -74,10 +83,17 @@ export class GameScene extends Phaser.Scene {
     this.events.on('updatePriorities', (villagerId: string, priorities: { chop: number; mine: number; farm: number }) => {
       this.adapter.send({ type: 'UPDATE_PRIORITIES', villagerId, priorities })
     })
+    this.events.on('debugToggle', () => this.debugSystem.toggle())
 
     this.autosaveTimer = AUTOSAVE_INTERVAL
   }
 
+  /**
+   * Main game loop: updates all systems and emits the cameraMoved event for the UI.
+   * Skips system updates while a menu is open.
+   * @param _time  - Total elapsed time (unused)
+   * @param delta  - Frame delta in milliseconds
+   */
   update(_time: number, delta: number): void {
     if (this.menuOpen) return
 
@@ -86,6 +102,7 @@ export class GameScene extends Phaser.Scene {
     this.resourceSystem.update(delta)
     this.farmingSystem.update(delta)
     this.villagerSystem.update(delta)
+    this.debugSystem.update()
 
     this.events.emit('cameraMoved', this.cameraSystem.getCenterTile())
     this.buildingSystem.update()
@@ -119,6 +136,7 @@ export class GameScene extends Phaser.Scene {
     }
   }
 
+  /** Saves game state and destroys all systems cleanly on scene shutdown. */
   shutdown(): void {
     stateManager.save()
     this.worldSystem.destroy()

src/scenes/UIScene.ts

@@ -1,6 +1,7 @@
 import Phaser from 'phaser'
 import type { BuildingType, JobPriorities } from '../types'
 import type { FarmingTool } from '../systems/FarmingSystem'
+import type { DebugData } from '../systems/DebugSystem'
 import { stateManager } from '../StateManager'
 
 const ITEM_ICONS: Record<string, string> = {
@@ -28,9 +29,15 @@ export class UIScene extends Phaser.Scene {
   private contextMenuVisible = false
   private inBuildMode = false
   private inFarmMode = false
+  private debugPanelText!: Phaser.GameObjects.Text
+  private debugActive = false
 
   constructor() { super({ key: 'UI' }) }
 
+  /**
+   * Creates all HUD elements, wires up game scene events, and registers
+   * keyboard shortcuts (B, V, F3, ESC).
+   */
   create(): void {
     this.createStockpilePanel()
     this.createHintText()
@@ -39,6 +46,7 @@ export class UIScene extends Phaser.Scene {
     this.createBuildModeIndicator()
     this.createFarmToolIndicator()
     this.createCoordsDisplay()
+    this.createDebugPanel()
 
     const gameScene = this.scene.get('Game')
     gameScene.events.on('buildModeChanged', (a: boolean, b: BuildingType) => this.onBuildModeChanged(a, b))
@@ -51,6 +59,8 @@ export class UIScene extends Phaser.Scene {
       .on('down', () => gameScene.events.emit('uiRequestBuildMenu'))
     this.input.keyboard!.addKey(Phaser.Input.Keyboard.KeyCodes.V)
       .on('down', () => this.toggleVillagerPanel())
+    this.input.keyboard!.addKey(Phaser.Input.Keyboard.KeyCodes.F3)
+      .on('down', () => this.toggleDebugPanel())
 
     this.scale.on('resize', () => this.repositionUI())
 
@@ -71,14 +81,22 @@ export class UIScene extends Phaser.Scene {
       .on('down', () => this.hideContextMenu())
   }
 
+  /**
+   * Updates the stockpile display, toast fade timer, population count,
+   * and the debug panel each frame.
+   * @param _t    - Total elapsed time (unused)
+   * @param delta - Frame delta in milliseconds
+   */
   update(_t: number, delta: number): void {
     this.updateStockpile()
     this.updateToast(delta)
     this.updatePopText()
+    if (this.debugActive) this.updateDebugPanel()
   }
 
   // ─── Stockpile ────────────────────────────────────────────────────────────
 
+  /** Creates the stockpile panel in the top-right corner with item rows and population count. */
   private createStockpilePanel(): void {
     const x = this.scale.width - 178, y = 10
     this.stockpilePanel = this.add.rectangle(x, y, 168, 165, 0x000000, 0.72).setOrigin(0, 0).setScrollFactor(0).setDepth(100)
@@ -91,6 +109,7 @@ export class UIScene extends Phaser.Scene {
     this.popText = this.add.text(x + 10, y + 145, '👥 Nisse: 0 / 0', { fontSize: '11px', color: '#aaaaaa', fontFamily: 'monospace' }).setScrollFactor(0).setDepth(101)
   }
 
+  /** Refreshes all item quantities and colors in the stockpile panel. */
   private updateStockpile(): void {
     const sp = stateManager.getState().world.stockpile
     for (const [item, t] of this.stockpileTexts) {
@@ -100,6 +119,7 @@ export class UIScene extends Phaser.Scene {
     }
   }
 
+  /** Updates the Nisse population / bed capacity counter. */
   private updatePopText(): void {
     const state = stateManager.getState()
     const beds    = Object.values(state.world.buildings).filter(b => b.kind === 'bed').length
@@ -109,6 +129,7 @@ export class UIScene extends Phaser.Scene {
 
   // ─── Hint ─────────────────────────────────────────────────────────────────
 
+  /** Creates the centered hint text element near the bottom of the screen. */
   private createHintText(): void {
     this.hintText = this.add.text(this.scale.width / 2, this.scale.height - 40, '', {
       fontSize: '14px', color: '#ffff88', fontFamily: 'monospace',
@@ -118,6 +139,7 @@ export class UIScene extends Phaser.Scene {
 
   // ─── Toast ────────────────────────────────────────────────────────────────
 
+  /** Creates the toast notification text element (top center, initially hidden). */
   private createToast(): void {
     this.toastText = this.add.text(this.scale.width / 2, 60, '', {
       fontSize: '15px', color: '#88ff88', fontFamily: 'monospace',
@@ -125,8 +147,16 @@ export class UIScene extends Phaser.Scene {
     }).setOrigin(0.5, 0).setScrollFactor(0).setDepth(102).setAlpha(0)
   }
 
+  /**
+   * Displays a toast message for 2.2 seconds then fades it out.
+   * @param msg - Message to display
+   */
   showToast(msg: string): void { this.toastText.setText(msg).setAlpha(1); this.toastTimer = 2200 }
 
+  /**
+   * Counts down the toast timer and triggers the fade-out tween when it expires.
+   * @param delta - Frame delta in milliseconds
+   */
   private updateToast(delta: number): void {
     if (this.toastTimer <= 0) return
     this.toastTimer -= delta
@@ -135,6 +165,7 @@ export class UIScene extends Phaser.Scene {
 
   // ─── Build Menu ───────────────────────────────────────────────────────────
 
+  /** Creates and hides the build menu with buttons for each available building type. */
   private createBuildMenu(): void {
     this.buildMenuGroup = this.add.group()
     const buildings: { kind: BuildingType; label: string; cost: string }[] = [
@@ -162,12 +193,18 @@ export class UIScene extends Phaser.Scene {
     this.buildMenuGroup.setVisible(false)
   }
 
+  /** Toggles the build menu open or closed. */
   private toggleBuildMenu(): void { this.buildMenuVisible ? this.closeBuildMenu() : this.openBuildMenu() }
+
+  /** Opens the build menu and notifies GameScene that a menu is active. */
   private openBuildMenu():  void { this.buildMenuVisible = true;  this.buildMenuGroup.setVisible(true);  this.scene.get('Game').events.emit('uiMenuOpen') }
+
+  /** Closes the build menu and notifies GameScene that no menu is active. */
   private closeBuildMenu(): void { this.buildMenuVisible = false; this.buildMenuGroup.setVisible(false); this.scene.get('Game').events.emit('uiMenuClose') }
 
   // ─── Villager Panel (V key) ───────────────────────────────────────────────
 
+  /** Toggles the Nisse management panel open or closed. */
   private toggleVillagerPanel(): void {
     if (this.villagerPanelVisible) {
       this.closeVillagerPanel()
@@ -176,18 +213,24 @@ export class UIScene extends Phaser.Scene {
     }
   }
 
+  /** Opens the Nisse panel, builds its contents, and notifies GameScene. */
   private openVillagerPanel(): void {
     this.villagerPanelVisible = true
     this.buildVillagerPanel()
     this.scene.get('Game').events.emit('uiMenuOpen')
   }
 
+  /** Closes and destroys the Nisse panel and notifies GameScene. */
   private closeVillagerPanel(): void {
     this.villagerPanelVisible = false
     this.villagerPanelGroup?.destroy(true)
     this.scene.get('Game').events.emit('uiMenuClose')
   }
 
+  /**
+   * Destroys and rebuilds the Nisse panel from current state.
+   * Shows name, status, energy bar, and job priority buttons per Nisse.
+   */
   private buildVillagerPanel(): void {
     if (this.villagerPanelGroup) this.villagerPanelGroup.destroy(true)
     this.villagerPanelGroup = this.add.group()
@@ -266,9 +309,16 @@ export class UIScene extends Phaser.Scene {
 
   // ─── Build mode indicator ─────────────────────────────────────────────────
 
+  /** Creates the build-mode indicator text in the top-left corner (initially hidden). */
   private createBuildModeIndicator(): void {
     this.buildModeText = this.add.text(10, 10, '', { fontSize: '13px', color: '#ffff00', fontFamily: 'monospace', backgroundColor: '#00000099', padding: { x: 8, y: 4 } }).setScrollFactor(0).setDepth(100).setVisible(false)
   }
+
+  /**
+   * Shows or hides the build-mode indicator based on whether build mode is active.
+   * @param active   - Whether build mode is currently active
+   * @param building - The selected building type
+   */
   private onBuildModeChanged(active: boolean, building: BuildingType): void {
     this.inBuildMode = active
     this.buildModeText.setText(active ? `🏗  BUILD: ${building.toUpperCase()}  [RMB/ESC cancel]` : '').setVisible(active)
@@ -276,9 +326,16 @@ export class UIScene extends Phaser.Scene {
 
   // ─── Farm tool indicator ──────────────────────────────────────────────────
 
+  /** Creates the farm-tool indicator text below the build-mode indicator (initially hidden). */
   private createFarmToolIndicator(): void {
     this.farmToolText = this.add.text(10, 44, '', { fontSize: '13px', color: '#aaffaa', fontFamily: 'monospace', backgroundColor: '#00000099', padding: { x: 8, y: 4 } }).setScrollFactor(0).setDepth(100).setVisible(false)
   }
+
+  /**
+   * Shows or hides the farm-tool indicator and updates the active tool label.
+   * @param tool  - Currently selected farm tool
+   * @param label - Human-readable label for the tool
+   */
   private onFarmToolChanged(tool: FarmingTool, label: string): void {
     this.inFarmMode = tool !== 'none'
     this.farmToolText.setText(tool === 'none' ? '' : `[F] Farm: ${label}  [RMB cancel]`).setVisible(tool !== 'none')
@@ -286,16 +343,88 @@ export class UIScene extends Phaser.Scene {
 
   // ─── Coords + controls ────────────────────────────────────────────────────
 
+  /** Creates the tile-coordinate display and controls hint at the bottom-left. */
   private createCoordsDisplay(): void {
     this.coordsText = this.add.text(10, this.scale.height - 24, '', { fontSize: '11px', color: '#666666', fontFamily: 'monospace' }).setScrollFactor(0).setDepth(100)
-    this.controlsHintText = this.add.text(10, this.scale.height - 42, '[WASD] Pan  [Scroll] Zoom  [F] Farm  [B] Build  [V] Nisse', {
+    this.controlsHintText = this.add.text(10, this.scale.height - 42, '[WASD] Pan  [Scroll] Zoom  [F] Farm  [B] Build  [V] Nisse  [F3] Debug', {
       fontSize: '10px', color: '#444444', fontFamily: 'monospace', backgroundColor: '#00000066', padding: { x: 4, y: 2 }
     }).setScrollFactor(0).setDepth(100)
   }
+
+  /**
+   * Updates the tile-coordinate display when the camera moves.
+   * @param pos - Tile position of the camera center
+   */
   private onCameraMoved(pos: { tileX: number; tileY: number }): void {
     this.coordsText.setText(`Tile: ${pos.tileX}, ${pos.tileY}`)
   }
 
+  // ─── Debug Panel (F3) ─────────────────────────────────────────────────────
+
+  /** Creates the debug panel text object (initially hidden). */
+  private createDebugPanel(): void {
+    this.debugPanelText = this.add.text(10, 80, '', {
+      fontSize: '12px',
+      color: '#cccccc',
+      backgroundColor: '#000000cc',
+      padding: { x: 8, y: 6 },
+      lineSpacing: 2,
+      fontFamily: 'monospace',
+    }).setScrollFactor(0).setDepth(150).setVisible(false)
+  }
+
+  /** Toggles the debug panel and notifies GameScene to toggle the pathfinding overlay. */
+  private toggleDebugPanel(): void {
+    this.debugActive = !this.debugActive
+    this.debugPanelText.setVisible(this.debugActive)
+    this.scene.get('Game').events.emit('debugToggle')
+  }
+
+  /**
+   * Reads current debug data from DebugSystem and updates the panel text.
+   * Called every frame while debug mode is active.
+   */
+  private updateDebugPanel(): void {
+    const gameScene = this.scene.get('Game') as any
+    const debugSystem = gameScene.debugSystem
+    if (!debugSystem?.isActive()) return
+
+    const ptr  = this.input.activePointer
+    const data = debugSystem.getDebugData(ptr) as DebugData
+
+    const resLine   = data.resourcesOnTile.length > 0
+      ? data.resourcesOnTile.map(r => `${r.kind} (hp:${r.hp})`).join(', ')
+      : '—'
+    const bldLine   = data.buildingsOnTile.length > 0 ? data.buildingsOnTile.join(', ') : '—'
+    const cropLine  = data.cropsOnTile.length > 0
+      ? data.cropsOnTile.map(c => `${c.kind} (${c.stage}/${c.maxStage})`).join(', ')
+      : '—'
+    const { idle, walking, working, sleeping } = data.nisseByState
+    const { chop, mine, farm } = data.jobsByType
+
+    this.debugPanelText.setText([
+      '── F3 DEBUG ──────────────────',
+      `FPS:         ${data.fps}`,
+      '',
+      `Mouse world: ${data.mouseWorld.x.toFixed(1)}, ${data.mouseWorld.y.toFixed(1)}`,
+      `Mouse tile:  ${data.mouseTile.tileX}, ${data.mouseTile.tileY}`,
+      `Tile type:   ${data.tileType}`,
+      `Resources:   ${resLine}`,
+      `Buildings:   ${bldLine}`,
+      `Crops:       ${cropLine}`,
+      '',
+      `Nisse: ${data.nisseTotal} total`,
+      `  idle: ${idle}  walking: ${walking}  working: ${working}  sleeping: ${sleeping}`,
+      '',
+      `Jobs active:`,
+      `  chop: ${chop}  mine: ${mine}  farm: ${farm}`,
+      '',
+      `Paths: ${data.activePaths} (cyan lines in world)`,
+      '',
+      '[F3] close',
+    ])
+  }
+
   // ─── Context Menu ─────────────────────────────────────────────────────────
 
   /**

src/systems/CameraSystem.ts

@@ -23,12 +23,23 @@ export class CameraSystem {
   }
   private saveTimer = 0
   private readonly SAVE_TICK = 2000
+  private middlePanActive = false
+  private lastPanX = 0
+  private lastPanY = 0
 
+  /**
+   * @param scene   - The Phaser scene this system belongs to
+   * @param adapter - Network adapter used to persist camera position
+   */
   constructor(scene: Phaser.Scene, adapter: LocalAdapter) {
     this.scene = scene
     this.adapter = adapter
   }
 
+  /**
+   * Initializes the camera: restores saved position, registers keyboard keys,
+   * sets up scroll-wheel zoom-to-mouse, and middle-click pan.
+   */
   create(): void {
     const state = stateManager.getState()
     const cam = this.scene.cameras.main
@@ -49,13 +60,56 @@ export class CameraSystem {
       d:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.D),
     }
 
-    // Scroll wheel zoom
+    // Scroll wheel: zoom-to-mouse.
-    this.scene.input.on('wheel', (_ptr: Phaser.Input.Pointer, _objs: unknown, _dx: number, dy: number) => {
+    // Phaser zooms from the screen center, so the world point under the mouse
-      const zoom = Phaser.Math.Clamp(cam.zoom - Math.sign(dy) * ZOOM_STEP, MIN_ZOOM, MAX_ZOOM)
+    // is corrected by shifting scroll by the mouse offset from center.
-      cam.setZoom(zoom)
+    this.scene.input.on('wheel', (ptr: Phaser.Input.Pointer, _objs: unknown, _dx: number, dy: number) => {
+      const zoomBefore = cam.zoom
+      const newZoom = Phaser.Math.Clamp(zoomBefore - Math.sign(dy) * ZOOM_STEP, MIN_ZOOM, MAX_ZOOM)
+      cam.setZoom(newZoom)
+
+      const factor = 1 / zoomBefore - 1 / newZoom
+      cam.scrollX += (ptr.x - cam.width  / 2) * factor
+      cam.scrollY += (ptr.y - cam.height / 2) * factor
+
+      const worldW = WORLD_TILES * 32
+      const worldH = WORLD_TILES * 32
+      cam.scrollX = Phaser.Math.Clamp(cam.scrollX, 0, worldW - cam.width  / newZoom)
+      cam.scrollY = Phaser.Math.Clamp(cam.scrollY, 0, worldH - cam.height / newZoom)
+    })
+
+    // Middle-click pan: start on button down
+    this.scene.input.on('pointerdown', (ptr: Phaser.Input.Pointer) => {
+      if (ptr.middleButtonDown()) {
+        this.middlePanActive = true
+        this.lastPanX = ptr.x
+        this.lastPanY = ptr.y
+      }
+    })
+
+    // Middle-click pan: move camera while held
+    this.scene.input.on('pointermove', (ptr: Phaser.Input.Pointer) => {
+      if (!this.middlePanActive) return
+      const dx = (ptr.x - this.lastPanX) / cam.zoom
+      const dy = (ptr.y - this.lastPanY) / cam.zoom
+      cam.scrollX -= dx
+      cam.scrollY -= dy
+      this.lastPanX = ptr.x
+      this.lastPanY = ptr.y
+    })
+
+    // Middle-click pan: stop on button release
+    this.scene.input.on('pointerup', (ptr: Phaser.Input.Pointer) => {
+      if (this.middlePanActive && !ptr.middleButtonDown()) {
+        this.middlePanActive = false
+      }
     })
   }
 
+  /**
+   * Moves the camera via keyboard input and periodically saves the position.
+   * @param delta - Frame delta in milliseconds
+   */
   update(delta: number): void {
     const cam = this.scene.cameras.main
     const speed = CAMERA_SPEED * (delta / 1000) / cam.zoom
@@ -73,7 +127,7 @@ export class CameraSystem {
 
     if (dx !== 0 && dy !== 0) { dx *= 0.707; dy *= 0.707 }
 
-    const worldW = WORLD_TILES * 32  // TILE_SIZE hardcoded since WORLD_PX may not exist
+    const worldW = WORLD_TILES * 32
     const worldH = WORLD_TILES * 32
     cam.scrollX = Phaser.Math.Clamp(cam.scrollX + dx, 0, worldW - cam.width / cam.zoom)
     cam.scrollY = Phaser.Math.Clamp(cam.scrollY + dy, 0, worldH - cam.height / cam.zoom)
@@ -90,14 +144,24 @@ export class CameraSystem {
     }
   }
 
+  /**
+   * Returns the world coordinates of the visual camera center.
+   * Phaser zooms from the screen center, so the center world point
+   * is scrollX + screenWidth/2 (independent of zoom level).
+   * @returns World position of the screen center
+   */
   getCenterWorld(): { x: number; y: number } {
     const cam = this.scene.cameras.main
     return {
-      x: cam.scrollX + cam.width / (2 * cam.zoom),
+      x: cam.scrollX + cam.width  / 2,
-      y: cam.scrollY + cam.height / (2 * cam.zoom),
+      y: cam.scrollY + cam.height / 2,
     }
   }
 
+  /**
+   * Returns the tile coordinates of the visual camera center.
+   * @returns Tile position (integer) of the screen center
+   */
   getCenterTile(): { tileX: number; tileY: number } {
     const { x, y } = this.getCenterWorld()
     return { tileX: Math.floor(x / 32), tileY: Math.floor(y / 32) }

src/systems/DebugSystem.ts

@@ -0,0 +1,164 @@
+import Phaser from 'phaser'
+import { TILE_SIZE } from '../config'
+import { TileType } from '../types'
+import { stateManager } from '../StateManager'
+import type { VillagerSystem } from './VillagerSystem'
+import type { WorldSystem } from './WorldSystem'
+
+/** All data collected each frame for the debug panel. */
+export interface DebugData {
+  fps: number
+  mouseWorld: { x: number; y: number }
+  mouseTile:  { tileX: number; tileY: number }
+  tileType:   string
+  resourcesOnTile: Array<{ kind: string; hp: number }>
+  buildingsOnTile: string[]
+  cropsOnTile: Array<{ kind: string; stage: number; maxStage: number }>
+  nisseTotal: number
+  nisseByState: { idle: number; walking: number; working: number; sleeping: number }
+  jobsByType:   { chop: number; mine: number; farm: number }
+  activePaths:  number
+}
+
+/** Human-readable names for TileType enum values. */
+const TILE_NAMES: Record<number, string> = {
+  [TileType.DEEP_WATER]:    'DEEP_WATER',
+  [TileType.SHALLOW_WATER]: 'SHALLOW_WATER',
+  [TileType.SAND]:          'SAND',
+  [TileType.GRASS]:         'GRASS',
+  [TileType.DARK_GRASS]:    'DARK_GRASS',
+  [TileType.FOREST]:        'FOREST',
+  [TileType.ROCK]:          'ROCK',
+  [TileType.FLOOR]:         'FLOOR',
+  [TileType.WALL]:          'WALL',
+  [TileType.TILLED_SOIL]:   'TILLED_SOIL',
+  [TileType.WATERED_SOIL]:  'WATERED_SOIL',
+}
+
+export class DebugSystem {
+  private scene:          Phaser.Scene
+  private villagerSystem: VillagerSystem
+  private worldSystem:    WorldSystem
+  private pathGraphics!:  Phaser.GameObjects.Graphics
+  private active = false
+
+  /**
+   * @param scene          - The Phaser scene this system belongs to
+   * @param villagerSystem - Used to read active paths for visualization
+   * @param worldSystem    - Used to read tile types under the mouse
+   */
+  constructor(scene: Phaser.Scene, villagerSystem: VillagerSystem, worldSystem: WorldSystem) {
+    this.scene          = scene
+    this.villagerSystem = villagerSystem
+    this.worldSystem    = worldSystem
+  }
+
+  /**
+   * Creates the world-space Graphics object used for pathfinding visualization.
+   * Starts hidden until toggled on.
+   */
+  create(): void {
+    this.pathGraphics = this.scene.add.graphics().setDepth(50)
+    this.pathGraphics.setVisible(false)
+  }
+
+  /**
+   * Toggles debug mode on or off.
+   * Shows or hides the pathfinding overlay graphics accordingly.
+   */
+  toggle(): void {
+    this.active = !this.active
+    this.pathGraphics.setVisible(this.active)
+    if (!this.active) this.pathGraphics.clear()
+  }
+
+  /** Returns whether debug mode is currently active. */
+  isActive(): boolean {
+    return this.active
+  }
+
+  /**
+   * Redraws pathfinding lines for all currently walking Nisse.
+   * Should be called every frame while debug mode is active.
+   */
+  update(): void {
+    if (!this.active) return
+    this.pathGraphics.clear()
+
+    const paths = this.villagerSystem.getActivePaths()
+    this.pathGraphics.lineStyle(1, 0x00ffff, 0.65)
+
+    for (const entry of paths) {
+      if (entry.path.length === 0) continue
+      this.pathGraphics.beginPath()
+      this.pathGraphics.moveTo(entry.x, entry.y)
+      for (const step of entry.path) {
+        this.pathGraphics.lineTo(
+          (step.tileX + 0.5) * TILE_SIZE,
+          (step.tileY + 0.5) * TILE_SIZE,
+        )
+      }
+      this.pathGraphics.strokePath()
+
+      // Mark the destination tile
+      const last = entry.path[entry.path.length - 1]
+      this.pathGraphics.fillStyle(0x00ffff, 0.4)
+      this.pathGraphics.fillRect(
+        last.tileX * TILE_SIZE,
+        last.tileY * TILE_SIZE,
+        TILE_SIZE,
+        TILE_SIZE,
+      )
+    }
+  }
+
+  /**
+   * Collects and returns all debug data for the current frame.
+   * Called by UIScene to populate the debug panel.
+   * @param ptr - The active pointer, used to resolve world position
+   * @returns Snapshot of game state for display
+   */
+  getDebugData(ptr: Phaser.Input.Pointer): DebugData {
+    const state   = stateManager.getState()
+    const villagers = Object.values(state.world.villagers)
+    const tileX   = Math.floor(ptr.worldX / TILE_SIZE)
+    const tileY   = Math.floor(ptr.worldY / TILE_SIZE)
+    const tileType = this.worldSystem.getTileType(tileX, tileY)
+
+    const nisseByState = { idle: 0, walking: 0, working: 0, sleeping: 0 }
+    const jobsByType   = { chop: 0, mine: 0, farm: 0 }
+
+    for (const v of villagers) {
+      nisseByState[v.aiState as keyof typeof nisseByState]++
+      if (v.job && (v.aiState === 'working' || v.aiState === 'walking')) {
+        jobsByType[v.job.type as keyof typeof jobsByType]++
+      }
+    }
+
+    const resourcesOnTile = Object.values(state.world.resources)
+      .filter(r => r.tileX === tileX && r.tileY === tileY)
+      .map(r => ({ kind: r.kind, hp: r.hp }))
+
+    const buildingsOnTile = Object.values(state.world.buildings)
+      .filter(b => b.tileX === tileX && b.tileY === tileY)
+      .map(b => b.kind)
+
+    const cropsOnTile = Object.values(state.world.crops)
+      .filter(c => c.tileX === tileX && c.tileY === tileY)
+      .map(c => ({ kind: c.kind, stage: c.stage, maxStage: c.maxStage }))
+
+    return {
+      fps:            Math.round(this.scene.game.loop.actualFps),
+      mouseWorld:     { x: ptr.worldX, y: ptr.worldY },
+      mouseTile:      { tileX, tileY },
+      tileType:       TILE_NAMES[tileType] ?? `UNKNOWN(${tileType})`,
+      resourcesOnTile,
+      buildingsOnTile,
+      cropsOnTile,
+      nisseTotal:     villagers.length,
+      nisseByState,
+      jobsByType,
+      activePaths:    this.villagerSystem.getActivePaths().length,
+    }
+  }
+}

src/systems/VillagerSystem.ts

@@ -36,18 +36,32 @@ export class VillagerSystem {
 
   onMessage?: (msg: string) => void
 
+  /**
+   * @param scene        - The Phaser scene this system belongs to
+   * @param adapter      - Network adapter for dispatching state actions
+   * @param worldSystem  - Used for passability checks during pathfinding
+   */
   constructor(scene: Phaser.Scene, adapter: LocalAdapter, worldSystem: WorldSystem) {
     this.scene = scene
     this.adapter = adapter
     this.worldSystem = worldSystem
   }
 
-  /** Wire in sibling systems after construction */
+  /**
+   * Wires in sibling systems that are not available at construction time.
+   * Must be called before create().
+   * @param resourceSystem - Used to remove harvested resource sprites
+   * @param farmingSystem  - Used to remove harvested crop sprites
+   */
   init(resourceSystem: ResourceSystem, farmingSystem: FarmingSystem): void {
     this.resourceSystem = resourceSystem
     this.farmingSystem  = farmingSystem
   }
 
+  /**
+   * Spawns sprites for all Nisse that exist in the saved state
+   * and re-claims any active job targets.
+   */
   create(): void {
     const state = stateManager.getState()
     for (const v of Object.values(state.world.villagers)) {
@@ -57,6 +71,10 @@ export class VillagerSystem {
     }
   }
 
+  /**
+   * Advances the spawn timer and ticks every Nisse's AI.
+   * @param delta - Frame delta in milliseconds
+   */
   update(delta: number): void {
     this.spawnTimer += delta
     if (this.spawnTimer >= VILLAGER_SPAWN_INTERVAL) {
@@ -72,6 +90,12 @@ export class VillagerSystem {
 
   // ─── Per-villager tick ────────────────────────────────────────────────────
 
+  /**
+   * Dispatches the correct AI tick method based on the villager's current state,
+   * then syncs the sprite, name label, energy bar, and job icon to the state.
+   * @param v     - Villager state from the store
+   * @param delta - Frame delta in milliseconds
+   */
   private tickVillager(v: VillagerState, delta: number): void {
     const rt = this.runtime.get(v.id)
     if (!rt) return
@@ -97,6 +121,14 @@ export class VillagerSystem {
 
   // ─── IDLE ─────────────────────────────────────────────────────────────────
 
+  /**
+   * Handles the idle AI state: hauls items to stockpile if carrying any,
+   * seeks a bed if energy is low, otherwise picks the next job and begins walking.
+   * Applies a cooldown before scanning again if no job is found.
+   * @param v     - Villager state
+   * @param rt    - Villager runtime (sprites, path, timers)
+   * @param delta - Frame delta in milliseconds
+   */
   private tickIdle(v: VillagerState, rt: VillagerRuntime, delta: number): void {
     // Decrement scan timer if cooling down
     if (rt.idleScanTimer > 0) {
@@ -133,6 +165,14 @@ export class VillagerSystem {
 
   // ─── WALKING ──────────────────────────────────────────────────────────────
 
+  /**
+   * Advances the Nisse along its path toward the current destination.
+   * Calls onArrived when the path is exhausted.
+   * Drains energy slowly while walking.
+   * @param v     - Villager state
+   * @param rt    - Villager runtime
+   * @param delta - Frame delta in milliseconds
+   */
   private tickWalking(v: VillagerState, rt: VillagerRuntime, delta: number): void {
     if (rt.path.length === 0) {
       this.onArrived(v, rt)
@@ -161,6 +201,12 @@ export class VillagerSystem {
     ;(v as { energy: number }).energy = Math.max(0, v.energy - delta * 0.0015)
   }
 
+  /**
+   * Called when a Nisse reaches its destination tile.
+   * Transitions to the appropriate next AI state based on destination type.
+   * @param v  - Villager state
+   * @param rt - Villager runtime
+   */
   private onArrived(v: VillagerState, rt: VillagerRuntime): void {
     switch (rt.destination) {
       case 'job':
@@ -186,6 +232,14 @@ export class VillagerSystem {
 
   // ─── WORKING ──────────────────────────────────────────────────────────────
 
+  /**
+   * Counts down the work timer and performs the harvest action on completion.
+   * Handles chop, mine, and farm job types.
+   * Returns the Nisse to idle when done.
+   * @param v     - Villager state
+   * @param rt    - Villager runtime
+   * @param delta - Frame delta in milliseconds
+   */
   private tickWorking(v: VillagerState, rt: VillagerRuntime, delta: number): void {
     rt.workTimer -= delta
     // Wobble while working
@@ -237,6 +291,12 @@ export class VillagerSystem {
 
   // ─── SLEEPING ─────────────────────────────────────────────────────────────
 
+  /**
+   * Restores energy while sleeping. Returns to idle once energy is full.
+   * @param v     - Villager state
+   * @param rt    - Villager runtime
+   * @param delta - Frame delta in milliseconds
+   */
   private tickSleeping(v: VillagerState, rt: VillagerRuntime, delta: number): void {
     ;(v as { energy: number }).energy = Math.min(100, v.energy + delta * 0.04)
     // Gentle bob while sleeping
@@ -249,6 +309,13 @@ export class VillagerSystem {
 
   // ─── Job picking (RimWorld-style priority) ────────────────────────────────
 
+  /**
+   * Selects the best available job for a Nisse based on their priority settings.
+   * Among jobs at the same priority level, the closest one wins.
+   * Returns null if no unclaimed job is available.
+   * @param v - Villager state (used for position and priorities)
+   * @returns The chosen job candidate, or null
+   */
   private pickJob(v: VillagerState): { type: JobType; targetId: string; tileX: number; tileY: number } | null {
     const state = stateManager.getState()
     const p     = v.priorities
@@ -289,6 +356,15 @@ export class VillagerSystem {
 
   // ─── Pathfinding ──────────────────────────────────────────────────────────
 
+  /**
+   * Computes a path from the Nisse's current tile to the target tile and
+   * begins walking. If no path is found, the job is cleared and a cooldown applied.
+   * @param v     - Villager state
+   * @param rt    - Villager runtime
+   * @param tileX - Target tile X
+   * @param tileY - Target tile Y
+   * @param dest  - Semantic destination type (used by onArrived)
+   */
   private beginWalk(v: VillagerState, rt: VillagerRuntime, tileX: number, tileY: number, dest: VillagerRuntime['destination']): void {
     const sx = Math.floor(v.x / TILE_SIZE)
     const sy = Math.floor(v.y / TILE_SIZE)
@@ -310,6 +386,11 @@ export class VillagerSystem {
 
   // ─── Building finders ─────────────────────────────────────────────────────
 
+  /**
+   * Returns the nearest building of the given kind to the Nisse, or null if none exist.
+   * @param v    - Villager state (used as reference position)
+   * @param kind - Building kind to search for
+   */
   private nearestBuilding(v: VillagerState, kind: string): { tileX: number; tileY: number } | null {
     const state = stateManager.getState()
     const hits = Object.values(state.world.buildings).filter(b => b.kind === kind)
@@ -319,6 +400,11 @@ export class VillagerSystem {
     return hits.sort((a, b) => Math.hypot(a.tileX - vx, a.tileY - vy) - Math.hypot(b.tileX - vx, b.tileY - vy))[0]
   }
 
+  /**
+   * Returns the Nisse's assigned bed if it still exists, otherwise the nearest bed.
+   * Returns null if no beds are placed.
+   * @param v - Villager state
+   */
   private findBed(v: VillagerState): { id: string; tileX: number; tileY: number } | null {
     const state = stateManager.getState()
     // Prefer assigned bed
@@ -328,6 +414,10 @@ export class VillagerSystem {
 
   // ─── Spawning ─────────────────────────────────────────────────────────────
 
+  /**
+   * Attempts to spawn a new Nisse if a free bed is available and the
+   * current population is below the bed count.
+   */
   private trySpawn(): void {
     const state   = stateManager.getState()
     const beds    = Object.values(state.world.buildings).filter(b => b.kind === 'bed')
@@ -361,6 +451,11 @@ export class VillagerSystem {
 
   // ─── Sprite management ────────────────────────────────────────────────────
 
+  /**
+   * Creates and registers all runtime objects (sprite, label, energy bar, icon)
+   * for a newly added Nisse.
+   * @param v - Villager state to create sprites for
+   */
   private spawnSprite(v: VillagerState): void {
     const sprite = this.scene.add.image(v.x, v.y, 'villager').setDepth(11)
 
@@ -375,6 +470,14 @@ export class VillagerSystem {
     this.runtime.set(v.id, { sprite, nameLabel, energyBar, jobIcon, path: [], destination: null, workTimer: 0, idleScanTimer: 0 })
   }
 
+  /**
+   * Redraws the energy bar graphic for a Nisse at the given world position.
+   * Color transitions green → orange → red as energy decreases.
+   * @param g      - Graphics object to draw into
+   * @param x      - World X center of the Nisse
+   * @param y      - World Y center of the Nisse
+   * @param energy - Current energy value (0–100)
+   */
   private drawEnergyBar(g: Phaser.GameObjects.Graphics, x: number, y: number, energy: number): void {
     const W = 20, H = 3
     g.clear()
@@ -385,6 +488,12 @@ export class VillagerSystem {
 
   // ─── Public API ───────────────────────────────────────────────────────────
 
+  /**
+   * Returns a short human-readable status string for the given Nisse,
+   * suitable for display in UI panels.
+   * @param villagerId - The Nisse's ID
+   * @returns Status string, or '—' if the Nisse is not found
+   */
   getStatusText(villagerId: string): string {
     const v = stateManager.getState().world.villagers[villagerId]
     if (!v) return '—'
@@ -397,6 +506,28 @@ export class VillagerSystem {
     return '💭 Idle'
   }
 
+  /**
+   * Returns the current world position and remaining path for every Nisse
+   * that is currently in the 'walking' state. Used by DebugSystem for
+   * pathfinding visualization.
+   * @returns Array of path entries, one per walking Nisse
+   */
+  getActivePaths(): Array<{ x: number; y: number; path: Array<{ tileX: number; tileY: number }> }> {
+    const state = stateManager.getState()
+    const result: Array<{ x: number; y: number; path: Array<{ tileX: number; tileY: number }> }> = []
+    for (const v of Object.values(state.world.villagers)) {
+      if (v.aiState !== 'walking') continue
+      const rt = this.runtime.get(v.id)
+      if (!rt) continue
+      result.push({ x: v.x, y: v.y, path: [...rt.path] })
+    }
+    return result
+  }
+
+  /**
+   * Destroys all Nisse sprites and clears the runtime map.
+   * Should be called when the scene shuts down.
+   */
   destroy(): void {
     for (const rt of this.runtime.values()) {
       rt.sprite.destroy(); rt.nameLabel.destroy()

src/systems/WorldSystem.ts

@@ -22,10 +22,15 @@ export class WorldSystem {
   private bgImage!: Phaser.GameObjects.Image
   private builtLayer!: Phaser.Tilemaps.TilemapLayer
 
+  /** @param scene - The Phaser scene this system belongs to */
   constructor(scene: Phaser.Scene) {
     this.scene = scene
   }
 
+  /**
+   * Generates the terrain background canvas from saved tile data,
+   * creates the built-tile tilemap layer, and sets camera bounds.
+   */
   create(): void {
     const state = stateManager.getState()
 
@@ -81,10 +86,18 @@ export class WorldSystem {
     this.scene.cameras.main.setBounds(0, 0, WORLD_TILES * TILE_SIZE, WORLD_TILES * TILE_SIZE)
   }
 
+  /** Returns the built-tile tilemap layer (floor, wall, soil). */
   getLayer(): Phaser.Tilemaps.TilemapLayer {
     return this.builtLayer
   }
 
+  /**
+   * Places or removes a tile on the built layer.
+   * Built tile types are added; natural types remove the built-layer entry.
+   * @param tileX - Tile column
+   * @param tileY - Tile row
+   * @param type  - New tile type to apply
+   */
   setTile(tileX: number, tileY: number, type: TileType): void {
     const BUILT_TILES = new Set([TileType.FLOOR, TileType.WALL, TileType.TILLED_SOIL, TileType.WATERED_SOIL])
     if (BUILT_TILES.has(type)) {
@@ -95,6 +108,12 @@ export class WorldSystem {
     }
   }
 
+  /**
+   * Returns whether the tile at the given coordinates can be walked on.
+   * Out-of-bounds tiles are treated as impassable.
+   * @param tileX - Tile column
+   * @param tileY - Tile row
+   */
   isPassable(tileX: number, tileY: number): boolean {
     if (tileX < 0 || tileY < 0 || tileX >= WORLD_TILES || tileY >= WORLD_TILES) return false
     const state = stateManager.getState()
@@ -102,6 +121,12 @@ export class WorldSystem {
     return !IMPASSABLE.has(tile)
   }
 
+  /**
+   * Converts world pixel coordinates to tile coordinates.
+   * @param worldX - World X in pixels
+   * @param worldY - World Y in pixels
+   * @returns Integer tile position
+   */
   worldToTile(worldX: number, worldY: number): { tileX: number; tileY: number } {
     return {
       tileX: Math.floor(worldX / TILE_SIZE),
@@ -109,6 +134,12 @@ export class WorldSystem {
     }
   }
 
+  /**
+   * Converts tile coordinates to the world pixel center of that tile.
+   * @param tileX - Tile column
+   * @param tileY - Tile row
+   * @returns World pixel center position
+   */
   tileToWorld(tileX: number, tileY: number): { x: number; y: number } {
     return {
       x: tileX * TILE_SIZE + TILE_SIZE / 2,
@@ -116,11 +147,17 @@ export class WorldSystem {
     }
   }
 
+  /**
+   * Returns the tile type at the given tile coordinates from saved state.
+   * @param tileX - Tile column
+   * @param tileY - Tile row
+   */
   getTileType(tileX: number, tileY: number): TileType {
     const state = stateManager.getState()
     return state.world.tiles[tileY * WORLD_TILES + tileX] as TileType
   }
 
+  /** Destroys the tilemap and background image. */
   destroy(): void {
     this.map.destroy()
     this.bgImage.destroy()

src/test/ZoomMouseScene.ts

@@ -0,0 +1,364 @@
+import Phaser from 'phaser'
+import { TILE_SIZE } from '../config'
+
+const GRID_TILES      = 500    // world size in tiles
+const MIN_ZOOM        = 0.25
+const MAX_ZOOM        = 4.0
+const ZOOM_STEP       = 0.1
+const MARKER_EVERY    = 10     // small crosshair every N tiles
+const LABEL_EVERY     = 50     // coordinate label every N tiles
+const CAMERA_SPEED    = 400    // px/s
+const SNAPSHOT_EVERY  = 2000   // ms between periodic log snapshots
+
+/**
+ * Second test scene: zoom-to-mouse behavior.
+ * After each zoom step, scrollX/Y is corrected so the world point
+ * under the mouse stays at the same screen position.
+ *
+ * Formula:
+ *   newScrollX = scrollX + (mouseX - screenW/2) * (1/zoomBefore - 1/zoomAfter)
+ *   newScrollY = scrollY + (mouseY - screenH/2) * (1/zoomBefore - 1/zoomAfter)
+ *
+ * Controls: Scroll wheel to zoom, WASD / Arrow keys to pan, Tab to switch scene.
+ */
+export class ZoomMouseScene extends Phaser.Scene {
+  private logText!: Phaser.GameObjects.Text
+  private hudCamera!: Phaser.Cameras.Scene2D.Camera
+  private worldObjects: Phaser.GameObjects.GameObject[] = []
+  private hudObjects: Phaser.GameObjects.GameObject[] = []
+  private keys!: {
+    up:    Phaser.Input.Keyboard.Key
+    down:  Phaser.Input.Keyboard.Key
+    left:  Phaser.Input.Keyboard.Key
+    right: Phaser.Input.Keyboard.Key
+    w:     Phaser.Input.Keyboard.Key
+    s:     Phaser.Input.Keyboard.Key
+    a:     Phaser.Input.Keyboard.Key
+    d:     Phaser.Input.Keyboard.Key
+    tab:   Phaser.Input.Keyboard.Key
+  }
+  private snapshotTimer = 0
+
+  constructor() {
+    super({ key: 'ZoomMouse' })
+  }
+
+  create(): void {
+    fetch('/api/log', { method: 'DELETE' })
+    this.writeLog('scene_start', { scene: 'ZoomMouse', tileSize: TILE_SIZE, gridTiles: GRID_TILES })
+
+    this.drawGrid()
+    this.setupCamera()
+    this.setupInput()
+    this.createHUD()
+    this.setupCameras()
+  }
+
+  /**
+   * Draws the static world grid into world space.
+   * All objects are registered in worldObjects for HUD-camera exclusion.
+   */
+  private drawGrid(): void {
+    const worldPx = GRID_TILES * TILE_SIZE
+    const g = this.add.graphics()
+    this.worldObjects.push(g)
+
+    g.fillStyle(0x111318)
+    g.fillRect(0, 0, worldPx, worldPx)
+
+    g.lineStyle(1, 0x222233, 0.5)
+    for (let i = 0; i <= GRID_TILES; i++) {
+      const p = i * TILE_SIZE
+      g.lineBetween(p, 0, p, worldPx)
+      g.lineBetween(0, p, worldPx, p)
+    }
+
+    for (let tx = 0; tx <= GRID_TILES; tx += MARKER_EVERY) {
+      for (let ty = 0; ty <= GRID_TILES; ty += MARKER_EVERY) {
+        const px = tx * TILE_SIZE
+        const py = ty * TILE_SIZE
+        const isLabel = tx % LABEL_EVERY === 0 && ty % LABEL_EVERY === 0
+        const color   = isLabel ? 0xffff00 : 0x44aaff
+        const arm     = isLabel ? 10 : 6
+
+        g.lineStyle(1, color, isLabel ? 1.0 : 0.7)
+        g.lineBetween(px - arm, py, px + arm, py)
+        g.lineBetween(px, py - arm, px, py + arm)
+
+        g.fillStyle(color, 1.0)
+        g.fillCircle(px, py, isLabel ? 2.5 : 1.5)
+      }
+    }
+
+    for (let tx = 0; tx <= GRID_TILES; tx += LABEL_EVERY) {
+      for (let ty = 0; ty <= GRID_TILES; ty += LABEL_EVERY) {
+        const label = this.add.text(
+          tx * TILE_SIZE + 4,
+          ty * TILE_SIZE + 4,
+          `${tx},${ty}`,
+          { fontSize: '9px', color: '#aaddff', fontFamily: 'monospace' }
+        ).setDepth(1)
+        this.worldObjects.push(label)
+      }
+    }
+
+    g.lineStyle(2, 0xff8844, 1.0)
+    g.strokeRect(0, 0, worldPx, worldPx)
+  }
+
+  /**
+   * Sets camera bounds and centers the view on the world.
+   */
+  private setupCamera(): void {
+    const cam = this.cameras.main
+    const worldPx = GRID_TILES * TILE_SIZE
+    cam.setBounds(0, 0, worldPx, worldPx)
+    cam.scrollX = worldPx / 2 - cam.width  / 2
+    cam.scrollY = worldPx / 2 - cam.height / 2
+  }
+
+  /**
+   * Registers scroll wheel zoom with mouse-anchor correction and keyboard keys.
+   * After cam.setZoom(), scrollX/Y is adjusted so the world point under the
+   * mouse stays at the same screen position.
+   */
+  private setupInput(): void {
+    const cam = this.cameras.main
+    const kb  = this.input.keyboard!
+
+    this.keys = {
+      up:    kb.addKey(Phaser.Input.Keyboard.KeyCodes.UP),
+      down:  kb.addKey(Phaser.Input.Keyboard.KeyCodes.DOWN),
+      left:  kb.addKey(Phaser.Input.Keyboard.KeyCodes.LEFT),
+      right: kb.addKey(Phaser.Input.Keyboard.KeyCodes.RIGHT),
+      w:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.W),
+      s:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.S),
+      a:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.A),
+      d:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.D),
+      tab:   kb.addKey(Phaser.Input.Keyboard.KeyCodes.TAB),
+    }
+
+    // Prevent Tab from switching browser focus
+    ;(this.keys.tab as unknown as { preventDefault: boolean }).preventDefault = true
+
+    this.keys.tab.on('down', () => {
+      this.scene.start('ZoomTest')
+    })
+
+    this.input.on('wheel', (
+      ptr:   Phaser.Input.Pointer,
+      _objs: unknown,
+      _dx:   number,
+      dy:    number
+    ) => {
+      const zoomBefore    = cam.zoom
+      const scrollXBefore = cam.scrollX
+      const scrollYBefore = cam.scrollY
+
+      const newZoom = Phaser.Math.Clamp(zoomBefore - Math.sign(dy) * ZOOM_STEP, MIN_ZOOM, MAX_ZOOM)
+      cam.setZoom(newZoom)
+
+      // Correct scroll so the world point under the mouse stays fixed.
+      // Phaser zooms from screen center, so the offset from center determines the shift.
+      const cw = cam.width
+      const ch = cam.height
+      const factor = 1 / zoomBefore - 1 / newZoom
+      cam.scrollX += (ptr.x - cw / 2) * factor
+      cam.scrollY += (ptr.y - ch / 2) * factor
+
+      // Clamp to world bounds
+      const worldPx = GRID_TILES * TILE_SIZE
+      cam.scrollX = Phaser.Math.Clamp(cam.scrollX, 0, worldPx - cw / cam.zoom)
+      cam.scrollY = Phaser.Math.Clamp(cam.scrollY, 0, worldPx - ch / cam.zoom)
+
+      setTimeout(() => {
+        this.writeLog('zoom', {
+          direction:      dy > 0 ? 'out' : 'in',
+          zoomBefore:     +zoomBefore.toFixed(4),
+          zoomAfter:      +cam.zoom.toFixed(4),
+          scrollX_before: +scrollXBefore.toFixed(2),
+          scrollY_before: +scrollYBefore.toFixed(2),
+          scrollX_after:  +cam.scrollX.toFixed(2),
+          scrollY_after:  +cam.scrollY.toFixed(2),
+          scrollX_delta:  +(cam.scrollX - scrollXBefore).toFixed(2),
+          scrollY_delta:  +(cam.scrollY - scrollYBefore).toFixed(2),
+          mouseScreen:    { x: +ptr.x.toFixed(1), y: +ptr.y.toFixed(1) },
+          mouseWorld_before: { x: +ptr.worldX.toFixed(2), y: +ptr.worldY.toFixed(2) },
+          centerWorld_after: {
+            x: +(cam.scrollX + cam.width / 2).toFixed(2),
+            y: +(cam.scrollY + cam.height / 2).toFixed(2),
+          },
+          vpTiles_after: {
+            w: +((cam.width  / cam.zoom) / TILE_SIZE).toFixed(3),
+            h: +((cam.height / cam.zoom) / TILE_SIZE).toFixed(3),
+          },
+        })
+      }, 0)
+    })
+  }
+
+  /**
+   * Creates all HUD elements: log overlay and screen-center crosshair.
+   * All objects are registered in hudObjects for main-camera exclusion.
+   */
+  private createHUD(): void {
+    const w = this.scale.width
+    const h = this.scale.height
+
+    const cross = this.add.graphics()
+    const arm = 16
+    cross.lineStyle(1, 0xff2222, 0.9)
+    cross.lineBetween(w / 2 - arm, h / 2, w / 2 + arm, h / 2)
+    cross.lineBetween(w / 2, h / 2 - arm, w / 2, h / 2 + arm)
+    cross.fillStyle(0xff2222, 1.0)
+    cross.fillCircle(w / 2, h / 2, 2)
+    this.hudObjects.push(cross)
+
+    this.logText = this.add.text(10, 10, '', {
+      fontSize: '13px',
+      color: '#e8e8e8',
+      backgroundColor: '#000000bb',
+      padding: { x: 10, y: 8 },
+      lineSpacing: 3,
+      fontFamily: 'monospace',
+    }).setDepth(100)
+    this.hudObjects.push(this.logText)
+  }
+
+  /**
+   * Adds a dedicated HUD camera (zoom=1, no scroll) and separates
+   * world objects from HUD objects so neither camera renders both layers.
+   */
+  private setupCameras(): void {
+    this.hudCamera = this.cameras.add(0, 0, this.scale.width, this.scale.height)
+    this.hudCamera.setScroll(0, 0)
+    this.hudCamera.setZoom(1)
+
+    this.cameras.main.ignore(this.hudObjects)
+    this.hudCamera.ignore(this.worldObjects)
+  }
+
+  update(_time: number, delta: number): void {
+    this.handleKeyboard(delta)
+    this.updateOverlay()
+
+    this.snapshotTimer += delta
+    if (this.snapshotTimer >= SNAPSHOT_EVERY) {
+      this.snapshotTimer = 0
+      this.writeSnapshot()
+    }
+  }
+
+  /**
+   * Moves camera with WASD / arrow keys at CAMERA_SPEED px/s (world space).
+   * @param delta - Frame delta in milliseconds
+   */
+  private handleKeyboard(delta: number): void {
+    const cam     = this.cameras.main
+    const speed   = CAMERA_SPEED * (delta / 1000) / cam.zoom
+    const worldPx = GRID_TILES * TILE_SIZE
+
+    let dx = 0, dy = 0
+    if (this.keys.left.isDown  || this.keys.a.isDown) dx -= speed
+    if (this.keys.right.isDown || this.keys.d.isDown) dx += speed
+    if (this.keys.up.isDown    || this.keys.w.isDown) dy -= speed
+    if (this.keys.down.isDown  || this.keys.s.isDown) dy += speed
+
+    if (dx !== 0 && dy !== 0) { dx *= 0.707; dy *= 0.707 }
+
+    cam.scrollX = Phaser.Math.Clamp(cam.scrollX + dx, 0, worldPx - cam.width  / cam.zoom)
+    cam.scrollY = Phaser.Math.Clamp(cam.scrollY + dy, 0, worldPx - cam.height / cam.zoom)
+  }
+
+  /**
+   * Recomputes and renders all diagnostic values to the HUD overlay each frame.
+   * centerWorld uses the corrected formula: scrollX + screenWidth/2.
+   */
+  private updateOverlay(): void {
+    const cam = this.cameras.main
+    const ptr = this.input.activePointer
+
+    const vpWidthPx     = cam.width  / cam.zoom
+    const vpHeightPx    = cam.height / cam.zoom
+    const vpWidthTiles  = vpWidthPx  / TILE_SIZE
+    const vpHeightTiles = vpHeightPx / TILE_SIZE
+
+    // Phaser zooms from screen center, so visual center = scrollX + screenWidth/2
+    const centerWorldX  = cam.scrollX + cam.width  / 2
+    const centerWorldY  = cam.scrollY + cam.height / 2
+    const centerTileX   = Math.floor(centerWorldX / TILE_SIZE)
+    const centerTileY   = Math.floor(centerWorldY / TILE_SIZE)
+
+    const mouseTileX    = Math.floor(ptr.worldX / TILE_SIZE)
+    const mouseTileY    = Math.floor(ptr.worldY / TILE_SIZE)
+    const renderer      = this.game.renderer.type === Phaser.WEBGL ? 'WebGL' : 'Canvas'
+
+    const lines = [
+      '── ZOOM TEST  [Zoom-to-Mouse] ──',
+      '',
+      `Zoom:              ${cam.zoom.toFixed(4)}`,
+      `scrollX / scrollY: ${cam.scrollX.toFixed(2)} / ${cam.scrollY.toFixed(2)}`,
+      '',
+      `Viewport (screen): ${cam.width} × ${cam.height} px`,
+      `Viewport (world):  ${vpWidthPx.toFixed(2)} × ${vpHeightPx.toFixed(2)} px`,
+      `Viewport (tiles):  ${vpWidthTiles.toFixed(3)} × ${vpHeightTiles.toFixed(3)}`,
+      '',
+      `Center world:      ${centerWorldX.toFixed(2)}, ${centerWorldY.toFixed(2)}`,
+      `Center tile:       ${centerTileX}, ${centerTileY}`,
+      '',
+      `Mouse screen:      ${ptr.x.toFixed(1)}, ${ptr.y.toFixed(1)}`,
+      `Mouse world:       ${ptr.worldX.toFixed(2)}, ${ptr.worldY.toFixed(2)}`,
+      `Mouse tile:        ${mouseTileX}, ${mouseTileY}`,
+      '',
+      `Canvas:            ${this.scale.width} × ${this.scale.height} px`,
+      `TILE_SIZE:         ${TILE_SIZE} px`,
+      `roundPixels:       ${(this.game.renderer.config as Record<string, unknown>)['roundPixels']}`,
+      `Renderer:          ${renderer}`,
+      '',
+      '[Scroll] Zoom   [WASD / ↑↓←→] Pan   [Tab] → Default',
+    ]
+
+    this.logText.setText(lines)
+  }
+
+  /**
+   * Writes a periodic full-state snapshot to the log.
+   */
+  private writeSnapshot(): void {
+    const cam = this.cameras.main
+    const ptr = this.input.activePointer
+    const vpW = cam.width  / cam.zoom
+    const vpH = cam.height / cam.zoom
+
+    this.writeLog('snapshot', {
+      zoom:        +cam.zoom.toFixed(4),
+      scrollX:     +cam.scrollX.toFixed(2),
+      scrollY:     +cam.scrollY.toFixed(2),
+      vpScreen:    { w: cam.width, h: cam.height },
+      vpWorld:     { w: +vpW.toFixed(2), h: +vpH.toFixed(2) },
+      vpTiles:     { w: +((vpW / TILE_SIZE).toFixed(3)), h: +((vpH / TILE_SIZE).toFixed(3)) },
+      centerWorld: {
+        x: +(cam.scrollX + cam.width  / 2).toFixed(2),
+        y: +(cam.scrollY + cam.height / 2).toFixed(2),
+      },
+      mouse: {
+        screen: { x: +ptr.x.toFixed(1), y: +ptr.y.toFixed(1) },
+        world:  { x: +ptr.worldX.toFixed(2), y: +ptr.worldY.toFixed(2) },
+      },
+    })
+  }
+
+  /**
+   * POSTs a structured log entry to the Vite dev server middleware.
+   * @param event - Event type label
+   * @param data  - Payload object to serialize as JSON
+   */
+  private writeLog(event: string, data: Record<string, unknown>): void {
+    const entry = JSON.stringify({ t: Date.now(), event, ...data })
+    fetch('/api/log', {
+      method: 'POST',
+      headers: { 'Content-Type': 'text/plain' },
+      body: entry,
+    }).catch(() => { /* swallow if dev server not running */ })
+  }
+}

src/test/ZoomTestScene.ts

@@ -0,0 +1,352 @@
+import Phaser from 'phaser'
+import { TILE_SIZE } from '../config'
+
+const GRID_TILES      = 500    // world size in tiles
+const MIN_ZOOM        = 0.25
+const MAX_ZOOM        = 4.0
+const ZOOM_STEP       = 0.1
+const MARKER_EVERY    = 10     // small crosshair every N tiles
+const LABEL_EVERY     = 50     // coordinate label every N tiles
+const CAMERA_SPEED    = 400    // px/s
+const SNAPSHOT_EVERY  = 2000   // ms between periodic log snapshots
+
+/**
+ * First test scene: observes pure Phaser default zoom behavior.
+ * No custom scroll compensation — cam.setZoom() only, zoom anchors to camera center.
+ * Logs zoom events and periodic snapshots to /api/log (written to game-test.log).
+ *
+ * Controls: Scroll wheel to zoom, WASD / Arrow keys to pan.
+ */
+export class ZoomTestScene extends Phaser.Scene {
+  private logText!: Phaser.GameObjects.Text
+  private hudCamera!: Phaser.Cameras.Scene2D.Camera
+  private worldObjects: Phaser.GameObjects.GameObject[] = []
+  private hudObjects: Phaser.GameObjects.GameObject[] = []
+  private keys!: {
+    up:    Phaser.Input.Keyboard.Key
+    down:  Phaser.Input.Keyboard.Key
+    left:  Phaser.Input.Keyboard.Key
+    right: Phaser.Input.Keyboard.Key
+    w:     Phaser.Input.Keyboard.Key
+    s:     Phaser.Input.Keyboard.Key
+    a:     Phaser.Input.Keyboard.Key
+    d:     Phaser.Input.Keyboard.Key
+    tab:   Phaser.Input.Keyboard.Key
+  }
+  private snapshotTimer = 0
+
+  constructor() {
+    super({ key: 'ZoomTest' })
+  }
+
+  create(): void {
+    // Clear log file at scene start
+    fetch('/api/log', { method: 'DELETE' })
+    this.writeLog('scene_start', { tileSize: TILE_SIZE, gridTiles: GRID_TILES })
+
+    this.drawGrid()
+    this.setupCamera()
+    this.setupInput()
+    this.createHUD()
+    this.setupCameras()
+  }
+
+  /**
+   * Draws the static world grid into world space.
+   * All objects are registered in worldObjects for HUD-camera exclusion.
+   */
+  private drawGrid(): void {
+    const worldPx = GRID_TILES * TILE_SIZE
+    const g = this.add.graphics()
+    this.worldObjects.push(g)
+
+    // Background fill
+    g.fillStyle(0x111811)
+    g.fillRect(0, 0, worldPx, worldPx)
+
+    // Tile grid lines
+    g.lineStyle(1, 0x223322, 0.5)
+    for (let i = 0; i <= GRID_TILES; i++) {
+      const p = i * TILE_SIZE
+      g.lineBetween(p, 0, p, worldPx)
+      g.lineBetween(0, p, worldPx, p)
+    }
+
+    // Crosshair markers
+    for (let tx = 0; tx <= GRID_TILES; tx += MARKER_EVERY) {
+      for (let ty = 0; ty <= GRID_TILES; ty += MARKER_EVERY) {
+        const px = tx * TILE_SIZE
+        const py = ty * TILE_SIZE
+        const isLabel = tx % LABEL_EVERY === 0 && ty % LABEL_EVERY === 0
+        const color   = isLabel ? 0xffff00 : 0x00ff88
+        const arm     = isLabel ? 10 : 6
+
+        g.lineStyle(1, color, isLabel ? 1.0 : 0.7)
+        g.lineBetween(px - arm, py, px + arm, py)
+        g.lineBetween(px, py - arm, px, py + arm)
+
+        g.fillStyle(color, 1.0)
+        g.fillCircle(px, py, isLabel ? 2.5 : 1.5)
+      }
+    }
+
+    // Coordinate labels at LABEL_EVERY intersections
+    for (let tx = 0; tx <= GRID_TILES; tx += LABEL_EVERY) {
+      for (let ty = 0; ty <= GRID_TILES; ty += LABEL_EVERY) {
+        const label = this.add.text(
+          tx * TILE_SIZE + 4,
+          ty * TILE_SIZE + 4,
+          `${tx},${ty}`,
+          { fontSize: '9px', color: '#ffff88', fontFamily: 'monospace' }
+        ).setDepth(1)
+        this.worldObjects.push(label)
+      }
+    }
+
+    // World border
+    g.lineStyle(2, 0xff4444, 1.0)
+    g.strokeRect(0, 0, worldPx, worldPx)
+  }
+
+  /**
+   * Sets camera bounds and centers the view on the world.
+   */
+  private setupCamera(): void {
+    const cam = this.cameras.main
+    const worldPx = GRID_TILES * TILE_SIZE
+    cam.setBounds(0, 0, worldPx, worldPx)
+    cam.scrollX = worldPx / 2 - cam.width  / 2
+    cam.scrollY = worldPx / 2 - cam.height / 2
+  }
+
+  /**
+   * Registers scroll wheel zoom and stores keyboard key references.
+   * Zoom uses cam.setZoom() only — pure Phaser default, anchors to camera center.
+   * Each zoom event is logged immediately with before/after state.
+   */
+  private setupInput(): void {
+    const cam = this.cameras.main
+    const kb  = this.input.keyboard!
+
+    this.keys = {
+      up:    kb.addKey(Phaser.Input.Keyboard.KeyCodes.UP),
+      down:  kb.addKey(Phaser.Input.Keyboard.KeyCodes.DOWN),
+      left:  kb.addKey(Phaser.Input.Keyboard.KeyCodes.LEFT),
+      right: kb.addKey(Phaser.Input.Keyboard.KeyCodes.RIGHT),
+      w:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.W),
+      s:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.S),
+      a:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.A),
+      d:     kb.addKey(Phaser.Input.Keyboard.KeyCodes.D),
+      tab:   kb.addKey(Phaser.Input.Keyboard.KeyCodes.TAB),
+    }
+
+    ;(this.keys.tab as unknown as { preventDefault: boolean }).preventDefault = true
+    this.keys.tab.on('down', () => {
+      this.scene.start('ZoomMouse')
+    })
+
+    this.input.on('wheel', (
+      ptr:   Phaser.Input.Pointer,
+      _objs: unknown,
+      _dx:   number,
+      dy:    number
+    ) => {
+      const zoomBefore    = cam.zoom
+      const scrollXBefore = cam.scrollX
+      const scrollYBefore = cam.scrollY
+
+      const newZoom = Phaser.Math.Clamp(cam.zoom - Math.sign(dy) * ZOOM_STEP, MIN_ZOOM, MAX_ZOOM)
+      cam.setZoom(newZoom)
+
+      setTimeout(() => {
+        this.writeLog('zoom', {
+          direction:      dy > 0 ? 'out' : 'in',
+          zoomBefore:     +zoomBefore.toFixed(4),
+          zoomAfter:      +cam.zoom.toFixed(4),
+          scrollX_before: +scrollXBefore.toFixed(2),
+          scrollY_before: +scrollYBefore.toFixed(2),
+          scrollX_after:  +cam.scrollX.toFixed(2),
+          scrollY_after:  +cam.scrollY.toFixed(2),
+          scrollX_delta:  +(cam.scrollX - scrollXBefore).toFixed(2),
+          scrollY_delta:  +(cam.scrollY - scrollYBefore).toFixed(2),
+          mouseScreen:    { x: +ptr.x.toFixed(1), y: +ptr.y.toFixed(1) },
+          mouseWorld:     { x: +ptr.worldX.toFixed(2), y: +ptr.worldY.toFixed(2) },
+          centerWorld_after: {
+            x: +(cam.scrollX + (cam.width  / cam.zoom) / 2).toFixed(2),
+            y: +(cam.scrollY + (cam.height / cam.zoom) / 2).toFixed(2),
+          },
+          vpTiles_after: {
+            w: +((cam.width  / cam.zoom) / TILE_SIZE).toFixed(3),
+            h: +((cam.height / cam.zoom) / TILE_SIZE).toFixed(3),
+          },
+        })
+      }, 0)
+    })
+  }
+
+  /**
+   * Creates all HUD elements: log overlay and screen-center crosshair.
+   * All objects are registered in hudObjects for main-camera exclusion.
+   * Uses a dedicated HUD camera (zoom=1, fixed) so elements are never scaled.
+   */
+  private createHUD(): void {
+    const w = this.scale.width
+    const h = this.scale.height
+
+    // Screen-center crosshair (red)
+    const cross = this.add.graphics()
+    const arm = 16
+    cross.lineStyle(1, 0xff2222, 0.9)
+    cross.lineBetween(w / 2 - arm, h / 2, w / 2 + arm, h / 2)
+    cross.lineBetween(w / 2, h / 2 - arm, w / 2, h / 2 + arm)
+    cross.fillStyle(0xff2222, 1.0)
+    cross.fillCircle(w / 2, h / 2, 2)
+    this.hudObjects.push(cross)
+
+    // Log text overlay
+    this.logText = this.add.text(10, 10, '', {
+      fontSize: '13px',
+      color: '#e8e8e8',
+      backgroundColor: '#000000bb',
+      padding: { x: 10, y: 8 },
+      lineSpacing: 3,
+      fontFamily: 'monospace',
+    }).setDepth(100)
+    this.hudObjects.push(this.logText)
+  }
+
+  /**
+   * Adds a dedicated HUD camera (zoom=1, no scroll) and separates
+   * world objects from HUD objects so neither camera renders both layers.
+   */
+  private setupCameras(): void {
+    this.hudCamera = this.cameras.add(0, 0, this.scale.width, this.scale.height)
+    this.hudCamera.setScroll(0, 0)
+    this.hudCamera.setZoom(1)
+
+    this.cameras.main.ignore(this.hudObjects)
+    this.hudCamera.ignore(this.worldObjects)
+  }
+
+  update(_time: number, delta: number): void {
+    this.handleKeyboard(delta)
+    this.updateOverlay()
+
+    this.snapshotTimer += delta
+    if (this.snapshotTimer >= SNAPSHOT_EVERY) {
+      this.snapshotTimer = 0
+      this.writeSnapshot()
+    }
+  }
+
+  /**
+   * Moves camera with WASD / arrow keys at CAMERA_SPEED px/s (world space).
+   * @param delta - Frame delta in milliseconds
+   */
+  private handleKeyboard(delta: number): void {
+    const cam     = this.cameras.main
+    const speed   = CAMERA_SPEED * (delta / 1000) / cam.zoom
+    const worldPx = GRID_TILES * TILE_SIZE
+
+    let dx = 0, dy = 0
+    if (this.keys.left.isDown  || this.keys.a.isDown) dx -= speed
+    if (this.keys.right.isDown || this.keys.d.isDown) dx += speed
+    if (this.keys.up.isDown    || this.keys.w.isDown) dy -= speed
+    if (this.keys.down.isDown  || this.keys.s.isDown) dy += speed
+
+    if (dx !== 0 && dy !== 0) { dx *= 0.707; dy *= 0.707 }
+
+    cam.scrollX = Phaser.Math.Clamp(cam.scrollX + dx, 0, worldPx - cam.width  / cam.zoom)
+    cam.scrollY = Phaser.Math.Clamp(cam.scrollY + dy, 0, worldPx - cam.height / cam.zoom)
+  }
+
+  /**
+   * Recomputes and renders all diagnostic values to the HUD overlay each frame.
+   */
+  private updateOverlay(): void {
+    const cam = this.cameras.main
+    const ptr = this.input.activePointer
+
+    const vpWidthPx     = cam.width  / cam.zoom
+    const vpHeightPx    = cam.height / cam.zoom
+    const vpWidthTiles  = vpWidthPx  / TILE_SIZE
+    const vpHeightTiles = vpHeightPx / TILE_SIZE
+    // Phaser zooms from screen center: visual center = scrollX + screenWidth/2
+    const centerWorldX  = cam.scrollX + cam.width  / 2
+    const centerWorldY  = cam.scrollY + cam.height / 2
+    const mouseTileX    = Math.floor(ptr.worldX / TILE_SIZE)
+    const mouseTileY    = Math.floor(ptr.worldY / TILE_SIZE)
+    const centerTileX   = Math.floor(centerWorldX / TILE_SIZE)
+    const centerTileY   = Math.floor(centerWorldY / TILE_SIZE)
+    const renderer      = this.game.renderer.type === Phaser.WEBGL ? 'WebGL' : 'Canvas'
+
+    const lines = [
+      '── ZOOM TEST  [Phaser default] ──',
+      '',
+      `Zoom:              ${cam.zoom.toFixed(4)}`,
+      `scrollX / scrollY: ${cam.scrollX.toFixed(2)} / ${cam.scrollY.toFixed(2)}`,
+      '',
+      `Viewport (screen): ${cam.width} × ${cam.height} px`,
+      `Viewport (world):  ${vpWidthPx.toFixed(2)} × ${vpHeightPx.toFixed(2)} px`,
+      `Viewport (tiles):  ${vpWidthTiles.toFixed(3)} × ${vpHeightTiles.toFixed(3)}`,
+      '',
+      `Center world:      ${centerWorldX.toFixed(2)}, ${centerWorldY.toFixed(2)}`,
+      `Center tile:       ${centerTileX}, ${centerTileY}`,
+      '',
+      `Mouse screen:      ${ptr.x.toFixed(1)}, ${ptr.y.toFixed(1)}`,
+      `Mouse world:       ${ptr.worldX.toFixed(2)}, ${ptr.worldY.toFixed(2)}`,
+      `Mouse tile:        ${mouseTileX}, ${mouseTileY}`,
+      '',
+      `Canvas:            ${this.scale.width} × ${this.scale.height} px`,
+      `TILE_SIZE:         ${TILE_SIZE} px`,
+      `roundPixels:       ${(this.game.renderer.config as Record<string, unknown>)['roundPixels']}`,
+      `Renderer:          ${renderer}`,
+      '',
+      '[Scroll] Zoom   [WASD / ↑↓←→] Pan   [Tab] → Mouse',
+    ]
+
+    this.logText.setText(lines)
+  }
+
+  /**
+   * Writes a periodic full-state snapshot to the log.
+   */
+  private writeSnapshot(): void {
+    const cam = this.cameras.main
+    const ptr = this.input.activePointer
+    const vpW = cam.width  / cam.zoom
+    const vpH = cam.height / cam.zoom
+
+    this.writeLog('snapshot', {
+      zoom:        +cam.zoom.toFixed(4),
+      scrollX:     +cam.scrollX.toFixed(2),
+      scrollY:     +cam.scrollY.toFixed(2),
+      vpScreen:    { w: cam.width, h: cam.height },
+      vpWorld:     { w: +vpW.toFixed(2), h: +vpH.toFixed(2) },
+      vpTiles:     { w: +((vpW / TILE_SIZE).toFixed(3)), h: +((vpH / TILE_SIZE).toFixed(3)) },
+      centerWorld: {
+        x: +(cam.scrollX + cam.width  / 2).toFixed(2),
+        y: +(cam.scrollY + cam.height / 2).toFixed(2),
+      },
+      mouse: {
+        screen: { x: +ptr.x.toFixed(1), y: +ptr.y.toFixed(1) },
+        world:  { x: +ptr.worldX.toFixed(2), y: +ptr.worldY.toFixed(2) },
+      },
+    })
+  }
+
+  /**
+   * POSTs a structured log entry to the Vite dev server middleware.
+   * Written to game-test.log in the project root.
+   * @param event - Event type label
+   * @param data  - Payload object to serialize as JSON
+   */
+  private writeLog(event: string, data: Record<string, unknown>): void {
+    const entry = JSON.stringify({ t: Date.now(), event, ...data })
+    fetch('/api/log', {
+      method: 'POST',
+      headers: { 'Content-Type': 'text/plain' },
+      body: entry,
+    }).catch(() => { /* swallow if dev server not running */ })
+  }
+}

src/test/main.ts

@@ -0,0 +1,22 @@
+import Phaser from 'phaser'
+import { ZoomTestScene } from './ZoomTestScene'
+import { ZoomMouseScene } from './ZoomMouseScene'
+
+const config: Phaser.Types.Core.GameConfig = {
+  type: Phaser.AUTO,
+  width: window.innerWidth,
+  height: window.innerHeight,
+  backgroundColor: '#0d1a0d',
+  scene: [ZoomTestScene, ZoomMouseScene],
+  scale: {
+    mode: Phaser.Scale.RESIZE,
+    autoCenter: Phaser.Scale.CENTER_BOTH,
+  },
+  render: {
+    pixelArt: false,
+    antialias: true,
+    roundPixels: true,
+  },
+}
+
+new Phaser.Game(config)

test.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Game — Test Scenes</title>
+    <style>
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      body { background: #000; overflow: hidden; display: flex; justify-content: center; align-items: center; height: 100vh; }
+      canvas { display: block; }
+    </style>
+  </head>
+  <body>
+    <script type="module" src="/src/test/main.ts"></script>
+  </body>
+</html>

vite.config.ts

@@ -1,12 +1,47 @@
 import { defineConfig } from 'vite'
+import { resolve } from 'path'
+import fs from 'fs'
+
+const LOG_FILE = resolve(__dirname, 'game-test.log')
 
 export default defineConfig({
   server: {
     port: 3000,
-    host: true
+    host: true,
   },
-  build: {
+  plugins: [
-    outDir: 'dist',
+    {
-    assetsInlineLimit: 0
+      name: 'game-logger',
+      configureServer(server) {
+        server.middlewares.use('/api/log', (req, res) => {
+          if (req.method === 'POST') {
+            let body = ''
+            req.on('data', chunk => { body += chunk })
+            req.on('end', () => {
+              fs.appendFileSync(LOG_FILE, body + '\n', 'utf8')
+              res.writeHead(200)
+              res.end('ok')
+            })
+          } else if (req.method === 'DELETE') {
+            fs.writeFileSync(LOG_FILE, '', 'utf8')
+            res.writeHead(200)
+            res.end('cleared')
+          } else {
+            res.writeHead(405)
+            res.end()
           }
         })
+      },
+    },
+  ],
+  build: {
+    outDir: 'dist',
+    assetsInlineLimit: 0,
+    rollupOptions: {
+      input: {
+        main: resolve(__dirname, 'index.html'),
+        test: resolve(__dirname, 'test.html'),
+      },
+    },
+  },
+})