✨ add F3 debug view (Issue #6)

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.

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()