fix(ui): render the Phaser canvas at physical pixels on hi-DPI displays

Phaser 4's ScaleManager never consults devicePixelRatio: in RESIZE mode
the canvas backing store equals the CSS size, so on Retina displays the
whole village — sprite art and every label — rendered at half resolution
and was blur-upscaled by the browser ('sgranato').

Switch to Scale.NONE and size the framebuffer at cssSize * dpr with
scale.zoom = 1/dpr keeping the CSS size logical (input mapping stays
correct because displayScale derives from the canvas bounding rect).
PhaserGame drives resizes via ResizeObserver plus a matchMedia watcher
for DPR-only changes. Camera zoom values now carry the dpr factor, so
VillageScene's max-zoom cap and wheel sensitivity scale with it, and
BootScene lays out in logical coordinates with a dpr-zoomed camera.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: FulAppiOS

client/src/game/PhaserGame.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useRef } from 'react';
 import * as Phaser from 'phaser';
 import { gameConfig } from './config';
+import { applyDprSize, getRenderScale } from './dpr';
 
 export function PhaserGame() {
   const containerRef = useRef<HTMLDivElement>(null);
@@ -10,14 +11,46 @@ export function PhaserGame() {
     if (containerRef.current === null) return;
     if (gameRef.current !== null) return;
 
+    const container = containerRef.current;
+    const renderScale = getRenderScale();
+
     const game = new Phaser.Game({
       ...gameConfig,
-      parent: containerRef.current,
+      parent: container,
+      scale: {
+        ...gameConfig.scale,
+        // Backing store at physical pixels, CSS at logical pixels (zoom).
+        // The container is laid out by the time this effect runs, so its
+        // client size is the real viewport.
+        width: Math.max(1, Math.floor(container.clientWidth * renderScale)),
+        height: Math.max(1, Math.floor(container.clientHeight * renderScale)),
+        zoom: 1 / renderScale,
+      },
     });
 
     gameRef.current = game;
 
+    // Scale.NONE means Phaser no longer tracks the parent — resize manually.
+    const resizeObserver = new ResizeObserver(() => applyDprSize(game, container));
+    resizeObserver.observe(container);
+
+    // ResizeObserver misses DPR-only changes (window dragged between a
+    // Retina and a non-Retina display without the CSS size changing), so
+    // also watch the media query — same technique as text.ts.
+    let dprQuery: MediaQueryList | null = null;
+    const onDprChange = () => {
+      applyDprSize(game, container);
+      watchDpr();
+    };
+    const watchDpr = () => {
+      dprQuery = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+      dprQuery.addEventListener('change', onDprChange, { once: true });
+    };
+    watchDpr();
+
     return () => {
+      resizeObserver.disconnect();
+      dprQuery?.removeEventListener('change', onDprChange);
       game.destroy(true);
       gameRef.current = null;
     };

client/src/game/config.ts

@@ -10,8 +10,12 @@ export const gameConfig: Phaser.Types.Core.GameConfig = {
   // upscale. Both Tiny Swords packs are pixel art, so this is safe for
   // every theme we ship.
   pixelArt: true,
+  // Scale.NONE because RESIZE forces the canvas backing store to CSS pixels,
+  // which on Retina displays renders at half resolution and lets the browser
+  // blur-upscale everything. PhaserGame sizes the canvas at physical pixels
+  // (cssSize * devicePixelRatio) with zoom = 1/dpr instead — see dpr.ts.
   scale: {
-    mode: Phaser.Scale.RESIZE,
+    mode: Phaser.Scale.NONE,
     autoCenter: Phaser.Scale.CENTER_BOTH,
   },
   input: {

client/src/game/dpr.ts

@@ -0,0 +1,43 @@
+import * as Phaser from 'phaser';
+
+/**
+ * Device-pixel-ratio handling for the Phaser canvas.
+ *
+ * Phaser 4 sizes the canvas backing store in CSS pixels and never consults
+ * `window.devicePixelRatio` (ScaleManager has no DPR support). On a Retina
+ * display that leaves the WebGL framebuffer at half the physical resolution
+ * and the browser upscales it, so sprites and especially text look grainy.
+ *
+ * The fix: run the game in `Scale.NONE`, size the backing store at
+ * `cssSize * renderScale` and set `scale.zoom = 1 / renderScale` so the
+ * canvas CSS size stays at logical pixels. Input mapping is unaffected —
+ * ScaleManager derives `displayScale` from the canvas bounding rect.
+ */
+
+/** Backing-store multiplier: the device pixel ratio, clamped to [1, 3] to
+ * keep VRAM bounded on high-density mobile screens. */
+export function getRenderScale(): number {
+  const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
+  return Math.min(Math.max(dpr, 1), 3);
+}
+
+/** The render scale a live game is currently using (the inverse of the
+ * ScaleManager zoom we set in PhaserGame). 1 when no zoom is applied. */
+export function sceneRenderScale(scene: Phaser.Scene): number {
+  const zoom = scene.game.scale.zoom;
+  return zoom > 0 ? 1 / zoom : 1;
+}
+
+/** Resize the game so the backing store matches physical pixels for the
+ * container's current CSS size. Safe to call repeatedly. */
+export function applyDprSize(game: Phaser.Game, container: HTMLElement): void {
+  const scale = getRenderScale();
+  const width = container.clientWidth;
+  const height = container.clientHeight;
+  if (width <= 0 || height <= 0) return;
+
+  if (game.scale.zoom !== 1 / scale) {
+    game.scale.setZoom(1 / scale);
+  }
+  game.scale.resize(Math.floor(width * scale), Math.floor(height * scale));
+}

client/src/game/scenes/BootScene.ts

@@ -4,6 +4,7 @@ import { BUILDING_DEFS } from '../data/building-layout';
 import { addCrispText } from '../text';
 import { getActiveTheme } from '../themes/registry';
 import { groupMissingByCategory } from '../data/asset-diagnostics';
+import { sceneRenderScale } from '../dpr';
 
 
 
@@ -82,15 +83,24 @@ export class BootScene extends Phaser.Scene {
 
     this.cameras.main.setBackgroundColor('#1a1a2e');
 
-    const cx = this.cameras.main.centerX;
-    const cy = this.cameras.main.centerY;
+    // The canvas backing store is at physical pixels (see dpr.ts). Lay the
+    // boot UI out in logical (CSS-pixel) coordinates and zoom the camera by
+    // the render scale, so text keeps its apparent size on Retina displays.
+    const ui = sceneRenderScale(this);
+    const vw = this.scale.width / ui;
+    const vh = this.scale.height / ui;
+    this.cameras.main.setZoom(ui);
+    this.cameras.main.centerOn(vw / 2, vh / 2);
+
+    const cx = vw / 2;
+    const cy = vh / 2;
     const hasMissing = this.missingAssets.length > 0;
 
     // Logo is always rendered the same way — the missing-sprites state just
     // changes the status line underneath and adds a single action button.
     const logo = this.add.image(cx, cy - 40, 'logo').setOrigin(0.5);
-    const maxW = Math.min(this.scale.width * 0.5, 520);
-    const maxH = this.scale.height * 0.55;
+    const maxW = Math.min(vw * 0.5, 520);
+    const maxH = vh * 0.55;
     const scale = Math.min(maxW / logo.width, maxH / logo.height);
     logo.setScale(scale);
 
@@ -106,7 +116,7 @@ export class BootScene extends Phaser.Scene {
         color: '#f0d89a',
         fontFamily: 'monospace',
         align: 'center',
-        wordWrap: { width: Math.min(this.scale.width * 0.8, 640) },
+        wordWrap: { width: Math.min(vw * 0.8, 640) },
       }).setOrigin(0.5);
 
       // Per-category breakdown so the user can tell at a glance whether
@@ -136,7 +146,7 @@ export class BootScene extends Phaser.Scene {
         color: '#8ea0b4',
         fontFamily: 'monospace',
         align: 'left',
-        wordWrap: { width: Math.min(this.scale.width * 0.9, 780) },
+        wordWrap: { width: Math.min(vw * 0.9, 780) },
       }).setOrigin(0.5, 0);
 
       const hintText =
@@ -147,7 +157,7 @@ export class BootScene extends Phaser.Scene {
         color: '#aabbcc',
         fontFamily: 'monospace',
         align: 'center',
-        wordWrap: { width: Math.min(this.scale.width * 0.9, 720) },
+        wordWrap: { width: Math.min(vw * 0.9, 720) },
       }).setOrigin(0.5, 0);
 
       const primary = addCrispText(this, cx, hint.y + hint.displayHeight + 24, '↻  Reload page', {

client/src/game/scenes/VillageScene.ts

@@ -12,6 +12,7 @@ import type { AgentState } from '../../types/agent';
 import type { AssetManifest, MapConfig, BuildingPosition, NpcPlacement } from '../../editor/types/map';
 import { SERVER_URL as API_BASE } from '../../config';
 import { getActiveTheme, rebaseSavedScale } from '../themes/registry';
+import { sceneRenderScale } from '../dpr';
 
 /** Set `cam.zoom` to `newZoom` while keeping the world point currently
  * under screen coordinates (sx, sy) pinned to the same screen spot.
@@ -150,7 +151,7 @@ export class VillageScene extends Phaser.Scene {
     // map is locked to the top-left corner while the viewport scales.
     this.input.on('wheel', (pointer: Phaser.Input.Pointer, _gameObjects: unknown[], _deltaX: number, deltaY: number) => {
       const cam = this.cameras.main;
-      const newZoom = Phaser.Math.Clamp(cam.zoom - deltaY * 0.001, this.minZoom(), 1.5);
+      const newZoom = Phaser.Math.Clamp(cam.zoom - deltaY * 0.001 * sceneRenderScale(this), this.minZoom(), this.maxZoom());
       zoomAroundPointer(cam, pointer.x, pointer.y, newZoom);
     });
 
@@ -167,7 +168,7 @@ export class VillageScene extends Phaser.Scene {
           pinchStartZoom = this.cameras.main.zoom;
         } else {
           const scale = dist / pinchStartDist;
-          const newZoom = Phaser.Math.Clamp(pinchStartZoom * scale, this.minZoom(), 1.5);
+          const newZoom = Phaser.Math.Clamp(pinchStartZoom * scale, this.minZoom(), this.maxZoom());
           const mx = (p1.x + p2.x) / 2;
           const my = (p1.y + p2.y) / 2;
           zoomAroundPointer(this.cameras.main, mx, my, newZoom);
@@ -481,7 +482,15 @@ export class VillageScene extends Phaser.Scene {
     const villageH = 700;
     const zoomX = cam.width / villageW;
     const zoomY = cam.height / villageH;
-    cam.setZoom(Phaser.Math.Clamp(Math.min(zoomX, zoomY) * 0.85, this.minZoom(), 1.5));
+    cam.setZoom(Phaser.Math.Clamp(Math.min(zoomX, zoomY) * 0.85, this.minZoom(), this.maxZoom()));
+  }
+
+  /** Upper zoom bound. 1.5 was tuned for a 1:1 (CSS pixel) framebuffer; the
+   * canvas now renders at physical pixels (see dpr.ts), so camera zoom values
+   * carry an extra devicePixelRatio factor and the cap scales with it to keep
+   * the same apparent maximum magnification. */
+  private maxZoom(): number {
+    return 1.5 * sceneRenderScale(this);
   }
 
   /** Lower zoom bound: the larger of the two viewport/world ratios, so the