ui/map-renderer: wrap torus camera into the central tile on pan

Even with the zoom-out clamp from cc004f9, panning still let the
user walk the camera centre out of the central tile of the 3×3
wrap layout — they would see the wrap copies one tile out and then
empty space beyond, because the renderer paints exactly nine
copies and nothing further. The fix is the standard torus trick:
treat camera coordinates modulo world dimensions. The toroidal
world looks identical at `(x, y)` and `(x mod W, y mod H)`, so
snapping the centre back into `[0, W) × [0, H)` is invisible to
the user, and the fixed 3×3 layout is then sufficient to cover
infinite pan in any direction.

Implementation:

- `src/map/torus.ts::wrapCameraTorus` — pure helper that returns
  the modulo-wrapped camera (positive remainder; scale preserved).
- `src/map/render.ts` — the torus-mode path now installs a
  `'moved'` listener that runs the wrap, with a re-entry guard
  because `viewport.moveCenter` itself fires the same event the
  listener subscribes to. The `'moved'` event is emitted by
  every `pixi-viewport` plugin that moves the camera (drag,
  wheel, decelerate, snap, pinch — confirmed against the v6
  source) so production drag inertia and wheel-pan both trigger
  the wrap.
- `src/routes/__debug/map/+page.svelte` — adds `setCameraCenter`
  to `__galaxyMap`, with an explicit `viewport.emit('moved')`
  after the programmatic `moveCenter` (the v6 source does not
  emit `'moved'` from `moveCenter`, only plugins do; the manual
  emit matches the user-drag semantics).

Tests:

- `tests/map-torus.test.ts` — Vitest unit coverage for
  `wrapCameraTorus` (in-bounds noop, one tile / many tiles past
  on each axis, negative inputs never return negative, scale
  preserved, right/bottom edge folds to left/top, toroidal-
  congruence invariant).
- `tests/e2e/playground-map.spec.ts` — torus pan regression: push
  the camera to (5.4×W, 7.25×H) through the new debug entry,
  assert the centre lands in the central tile and matches the
  expected `(0.4×W, 0.25×H)` modulo position. Runs across all
  four Playwright projects.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ui/frontend/src/map/index.ts

@@ -33,6 +33,8 @@ export {
 	pivotZoom,
 } from "./no-wrap";
 
+export { wrapCameraTorus } from "./torus";
+
 export { hitTest, type Hit } from "./hit-test";
 
 export {

ui/frontend/src/map/render.ts

@@ -3,10 +3,16 @@
 // Owns the Pixi `Application` lifecycle and a `pixi-viewport` instance
 // configured for the active wrap mode. Torus mode renders nine
 // container copies at offsets {-W, 0, W} × {-H, 0, H}, giving the
-// user a seamless toroidal world. No-wrap mode hides eight of the
-// nine copies and pins the camera with `pixi-viewport`'s `clamp`
-// plugin plus a `moved` listener that recentres the camera when the
-// visible viewport exceeds the world along an axis.
+// user a seamless toroidal world while panning past the edge — and
+// keeps the camera centre snapped into the central tile via a
+// `moved` listener so the fixed 3×3 layout is sufficient for any
+// distance of pan. No-wrap mode hides eight of the nine copies and
+// pins the camera with `pixi-viewport`'s `clamp` plugin plus a
+// `moved` listener that recentres the camera when the visible
+// viewport exceeds the world along an axis. Both modes share a
+// `clampZoom({ minScale })` so the world (origin copy) always fills
+// at least the viewport — without it torus mode would expose all
+// nine copies at once.
 //
 // Hit-test is owned by ./hit-test.ts; this file only exposes the
 // current camera and viewport so callers can run hits.
@@ -16,6 +22,7 @@ import { Viewport as PixiViewport } from "pixi-viewport";
 
 import { hitTest, type Hit } from "./hit-test";
 import { minScaleNoWrap } from "./no-wrap";
+import { wrapCameraTorus } from "./torus";
 import {
 	DARK_THEME,
 	type Camera,
@@ -133,6 +140,31 @@ export async function createRenderer(opts: RendererOptions): Promise<RendererHan
 		);
 	};
 
+	// Reentry guard for the torus wrap handler: `viewport.moveCenter`
+	// fires the same `'moved'` event that triggered the wrap, so a
+	// naive callback would loop forever.
+	let wrappingCamera = false;
+	const wrapTorusCamera = (): void => {
+		if (mode !== "torus" || wrappingCamera) return;
+		const wrapped = wrapCameraTorus(
+			{
+				centerX: viewport.center.x,
+				centerY: viewport.center.y,
+				scale: viewport.scaled,
+			},
+			opts.world,
+		);
+		if (wrapped.centerX === viewport.center.x && wrapped.centerY === viewport.center.y) {
+			return;
+		}
+		wrappingCamera = true;
+		try {
+			viewport.moveCenter(wrapped.centerX, wrapped.centerY);
+		} finally {
+			wrappingCamera = false;
+		}
+	};
+
 	const applyMode = (newMode: WrapMode): void => {
 		mode = newMode;
 		for (let i = 0; i < copies.length; i++) {
@@ -142,6 +174,7 @@ export async function createRenderer(opts: RendererOptions): Promise<RendererHan
 		viewport.plugins.remove("clamp");
 		viewport.plugins.remove("clamp-zoom");
 		viewport.off("moved", enforceCentreWhenLarger);
+		viewport.off("moved", wrapTorusCamera);
 		const minScale = minScaleNoWrap(
 			{ widthPx: viewport.screenWidth, heightPx: viewport.screenHeight },
 			opts.world,
@@ -158,9 +191,16 @@ export async function createRenderer(opts: RendererOptions): Promise<RendererHan
 			viewport.clamp({ direction: "all" });
 			viewport.on("moved", enforceCentreWhenLarger);
 			enforceCentreWhenLarger();
+		} else {
+			// Torus mode keeps free pan: the user can drag in any
+			// direction indefinitely. To keep the fixed 3×3 wrap
+			// layout sufficient, snap the camera back into the
+			// `[0, W) × [0, H)` central tile whenever it walks past
+			// the edge — toroidal coordinates are equivalent modulo
+			// world dimensions, so the user sees no jump.
+			viewport.on("moved", wrapTorusCamera);
+			wrapTorusCamera();
 		}
-		// Torus mode keeps free pan (no `clamp()`); the visible wrap
-		// copies handle the cross-edge case naturally.
 	};
 
 	applyMode(mode);
@@ -195,6 +235,7 @@ export async function createRenderer(opts: RendererOptions): Promise<RendererHan
 		},
 		dispose: () => {
 			viewport.off("moved", enforceCentreWhenLarger);
+			viewport.off("moved", wrapTorusCamera);
 			app.destroy({ removeView: false }, { children: true });
 		},
 	};

ui/frontend/src/map/torus.ts

@@ -0,0 +1,44 @@
+// Camera helpers for toroidal-world (torus) mode.
+//
+// The renderer paints the world into a 3×3 grid of copies offset by
+// `(±W, 0) × (±H, 0)` — those copies are intended to cover the
+// cross-edge slack while the user pans, not to be visible all at
+// once. As soon as the camera centre walks outside the central
+// tile's rectangle `[0, W) × [0, H)`, the user starts seeing the
+// next-tile boundary; one more world width/height of pan and they
+// are at the 3×3 grid edge with empty space beyond.
+//
+// `wrapCameraTorus` snaps the camera back into `[0, W) × [0, H)`
+// modulo the world dimensions. The toroidal world looks identical
+// at `(x, y)` and `(x mod W, y mod H)`, so the snap is invisible to
+// the user, while keeping the 3×3 layout enough to cover infinite
+// pan in any direction.
+
+import type { Camera, World } from "./world";
+
+/**
+ * wrapCameraTorus returns a camera whose centre is reduced modulo
+ * the world dimensions so it lies within `[0, W) × [0, H)`. Camera
+ * scale is preserved. Negative inputs are also handled — the result
+ * is always non-negative.
+ *
+ * The transform is a pure mathematical no-op on the toroidal world:
+ * `(centerX, centerY)` and `(centerX mod W, centerY mod H)` describe
+ * the same toroidal point. Callers use the wrapped camera to keep
+ * the renderer's fixed 3×3 wrap-copy layout sufficient regardless
+ * of how far the user has panned.
+ */
+export function wrapCameraTorus(camera: Camera, world: World): Camera {
+	const W = world.width;
+	const H = world.height;
+	return {
+		centerX: positiveMod(camera.centerX, W),
+		centerY: positiveMod(camera.centerY, H),
+		scale: camera.scale,
+	};
+}
+
+function positiveMod(value: number, modulus: number): number {
+	const r = value % modulus;
+	return r < 0 ? r + modulus : r;
+}

ui/frontend/src/routes/__debug/map/+page.svelte

@@ -15,6 +15,7 @@
 		getMode(): WrapMode;
 		setMode(mode: WrapMode): void;
 		getCamera(): { centerX: number; centerY: number; scale: number };
+		setCameraCenter(centerX: number, centerY: number): void;
 		getViewport(): { widthPx: number; heightPx: number };
 		getBackend(): string;
 		getWorldSize(): { width: number; height: number };
@@ -81,6 +82,20 @@
 					mode = m;
 				},
 				getCamera: () => handle?.getCamera() ?? { centerX: 0, centerY: 0, scale: 1 },
+				setCameraCenter: (cx, cy) => {
+					if (handle === null) return;
+					// `pixi-viewport`'s built-in plugins (drag, wheel,
+					// decelerate, …) emit `'moved'` themselves, but
+					// programmatic `moveCenter` does not. Emit it
+					// manually so the renderer's torus-wrap listener
+					// (and any future per-move callback) sees the
+					// change — matches the semantics of a user drag.
+					handle.viewport.moveCenter(cx, cy);
+					handle.viewport.emit("moved", {
+						viewport: handle.viewport,
+						type: "manual",
+					});
+				},
 				getViewport: () =>
 					handle?.getViewport() ?? { widthPx: 0, heightPx: 0 },
 				getBackend: () => handle?.getBackend() ?? "",