solanapolis 1.0.0

package/src/lib/building-shader.ts

@@ -0,0 +1,253 @@
+import * as THREE from "three";
+
+/**
+ * Find `#include <name>` in the source (with any leading whitespace) and replace
+ * the entire line with the replacement string.
+ */
+function replaceInclude(source: string, name: string, replacement: string): string {
+  const needle = `#include <${name}>`;
+  const idx = source.indexOf(needle);
+  if (idx < 0) return source;
+  let start = idx;
+  while (start > 0 && source[start - 1] !== "\n") start--;
+  return source.substring(0, start) + replacement + "\n" + source.substring(idx + needle.length);
+}
+
+/**
+ * Creates a ShaderMaterial based on Three.js's standard (PBR) shader with
+ * procedural window logic baked in. Uses ShaderMaterial directly instead of
+ * onBeforeCompile to avoid program cache invalidation issues.
+ */
+export function createBuildingMaterial(
+  timeUniform: { value: number },
+  elapsedUniform?: { value: number },
+): THREE.ShaderMaterial {
+  const std = THREE.ShaderLib.standard;
+
+  // Start from the standard PBR shader source
+  let vertexShader = std.vertexShader;
+  let fragmentShader = std.fragmentShader;
+
+  // --- Vertex modifications ---
+  vertexShader = replaceInclude(
+    vertexShader,
+    "common",
+    /* glsl */ `
+      attribute vec3 instanceBuildingColor;
+      attribute float instanceWindowCols;
+      attribute float instanceFillRatio;
+      attribute float instanceLitRatio;
+      attribute float instanceSeed;
+      attribute float instanceFloors;
+      attribute float instanceHighlight;
+      varying vec3 vBuildingColor;
+      varying float vWindowCols, vFillRatio, vLitRatio, vSeed, vFloors;
+      varying float vHighlight;
+      varying vec3 vModelNormal;
+      varying vec2 vFaceUV;
+      #include <common>
+    `,
+  );
+
+  vertexShader = replaceInclude(
+    vertexShader,
+    "begin_vertex",
+    /* glsl */ `
+      #include <begin_vertex>
+      vBuildingColor = instanceBuildingColor;
+      vHighlight = instanceHighlight;
+      vWindowCols = instanceWindowCols;
+      vFillRatio = instanceFillRatio;
+      vLitRatio = instanceLitRatio;
+      vSeed = instanceSeed;
+      vFloors = instanceFloors;
+      vModelNormal = normal;
+      if (abs(normal.x) > 0.5) {
+        vFaceUV = vec2(position.z + 0.5, position.y + 0.5);
+      } else {
+        vFaceUV = vec2(position.x + 0.5, position.y + 0.5);
+      }
+    `,
+  );
+
+  // --- Fragment modifications ---
+  fragmentShader = replaceInclude(
+    fragmentShader,
+    "common",
+    /* glsl */ `
+      uniform float uTime;
+      uniform float uElapsed;
+      varying vec3 vBuildingColor;
+      varying float vWindowCols, vFillRatio, vLitRatio, vSeed, vFloors;
+      varying float vHighlight;
+      varying vec3 vModelNormal;
+      varying vec2 vFaceUV;
+      #include <common>
+    `,
+  );
+
+  fragmentShader = replaceInclude(
+    fragmentShader,
+    "emissivemap_fragment",
+    /* glsl */ `
+      #include <emissivemap_fragment>
+
+      // Time-of-day
+      float timeNow = fract(uTime);
+
+      // Sunset factor: peaks at t=0.50
+      float sunsetFactor = 0.0;
+      if (timeNow >= 0.42 && timeNow < 0.50) {
+        sunsetFactor = (timeNow - 0.42) / 0.08;
+      } else if (timeNow >= 0.50 && timeNow < 0.58) {
+        sunsetFactor = 1.0 - (timeNow - 0.50) / 0.08;
+      }
+
+      // Night factor (scene darkness)
+      float nightFactor = 0.0;
+      if (timeNow >= 0.50 && timeNow < 0.58) {
+        nightFactor = (timeNow - 0.50) / 0.08;
+      } else if (timeNow >= 0.58 && timeNow < 0.92) {
+        nightFactor = 1.0;
+      } else if (timeNow >= 0.92 && timeNow <= 1.0) {
+        nightFactor = 1.0 - (timeNow - 0.92) / 0.08;
+      }
+
+      // Window light factor — starts at sunset (~20%), full at night, ~20% at sunrise, off during day
+      float windowFactor = 0.0;
+      if (timeNow >= 0.42 && timeNow < 0.50) {
+        // During sunset: ramp 0→0.2
+        windowFactor = 0.2 * (timeNow - 0.42) / 0.08;
+      } else if (timeNow >= 0.50 && timeNow < 0.58) {
+        // Sunset→night: ramp 0.2→1.0
+        windowFactor = 0.2 + 0.8 * (timeNow - 0.50) / 0.08;
+      } else if (timeNow >= 0.58 && timeNow < 0.92) {
+        // Full night
+        windowFactor = 1.0;
+      } else if (timeNow >= 0.92 && timeNow <= 1.0) {
+        // Night→sunrise: ramp 1.0→0.2
+        windowFactor = 0.2 + 0.8 * (1.0 - (timeNow - 0.92) / 0.08);
+      } else if (timeNow >= 0.0 && timeNow < 0.08) {
+        // During sunrise: ramp 0.2→0
+        windowFactor = 0.2 * (1.0 - timeNow / 0.08);
+      }
+
+      // Base building color
+      vec3 baseColor = vBuildingColor;
+      vec3 sunsetTint = mix(baseColor, baseColor * vec3(1.2, 0.95, 0.75), sunsetFactor * 0.4);
+
+      // Night: darken overall output
+      float nightDim = mix(1.0, 0.45, nightFactor);
+
+      // 80% emissive / 20% diffuse, dimmed at night
+      diffuseColor.rgb = sunsetTint * 0.2 * nightDim;
+      totalEmissiveRadiance += sunsetTint * 0.8 * nightDim;
+
+      // Hover highlight: subtle additive glow that preserves base color
+      totalEmissiveRadiance += vec3(0.02, 0.02, 0.035) * vHighlight;
+
+      // --- Window logic (side faces only) ---
+      if (abs(vModelNormal.y) < 0.5) {
+        // Unique face index (0-3) so each side has different patterns
+        float faceId = 0.0;
+        if (vModelNormal.x > 0.5) faceId = 1.0;
+        else if (vModelNormal.x < -0.5) faceId = 2.0;
+        else if (vModelNormal.z > 0.5) faceId = 3.0;
+
+        float cols = vWindowCols;
+        float rows = vFloors;
+
+        if (cols > 0.5 && rows > 0.5) {
+          float cellU = fract(vFaceUV.x * cols);
+          float cellV = fract(vFaceUV.y * rows);
+          bool inWindowSlot = cellU > 0.2 && cellU < 0.8 && cellV > 0.2 && cellV < 0.8;
+
+          if (inWindowSlot) {
+            float colIdx = floor(vFaceUV.x * cols);
+            float rowIdx = floor(vFaceUV.y * rows);
+
+            // Hash 1: does window exist? (faceId makes each side unique)
+            float h1 = fract(sin(colIdx * 127.1 + rowIdx * 311.7 + vSeed * 758.5 + faceId * 1731.3) * 43758.5453);
+            bool hasWindow = h1 < vFillRatio;
+
+            if (hasWindow) {
+              // Hash 2: per-window threshold for when it turns on/off
+              float h2 = fract(sin(colIdx * 53.3 + rowIdx * 419.2 + vSeed * 317.9 + faceId * 2137.7) * 29187.3217);
+
+              // Scale lit threshold by windowFactor so windows turn on/off gradually
+              // h2 is uniform 0–1; window is lit when h2 < effectiveRatio
+              // As windowFactor rises 0→1, more windows cross the threshold
+              float effectiveLitRatio = vLitRatio * windowFactor;
+              bool isLit = h2 < effectiveLitRatio;
+
+              if (isLit) {
+                // Per-window brightness & color variation
+                float h3 = fract(sin(colIdx * 173.7 + rowIdx * 239.1 + vSeed * 491.3 + faceId * 863.5) * 15731.4219);
+                float h4 = fract(sin(colIdx * 97.3 + rowIdx * 587.1 + vSeed * 163.7 + faceId * 1279.3) * 38147.2917);
+                float h5 = fract(sin(colIdx * 211.9 + rowIdx * 349.3 + vSeed * 607.1 + faceId * 1013.7) * 21317.7631);
+                float brightness = 0.3 + h3 * 1.0;              // 0.3–1.3 wide range
+
+                // Distinct color categories: warm yellow, cool white, amber, blue-ish
+                vec3 windowColor;
+                if (h4 < 0.35) {
+                  windowColor = vec3(0.9, 0.7, 0.28);           // warm yellow
+                } else if (h4 < 0.55) {
+                  windowColor = vec3(0.75, 0.72, 0.55);         // cool white / fluorescent
+                } else if (h4 < 0.8) {
+                  windowColor = vec3(0.95, 0.55, 0.18);         // deep amber
+                } else {
+                  windowColor = vec3(0.5, 0.6, 0.8);            // bluish TV glow
+                }
+                // Extra per-window jitter on top
+                windowColor *= 0.85 + h5 * 0.3;
+
+                // Slow pulsing — each window at its own speed & phase
+                float pulseSpeed = 0.12 + h3 * 0.28;             // 0.12–0.4 Hz
+                float pulsePhase = h5 * 6.2832;                 // 0–2π offset
+                float pulse = 0.4 + 0.6 * sin(uElapsed * pulseSpeed + pulsePhase);
+                brightness *= pulse;
+
+                totalEmissiveRadiance += windowColor * windowFactor * 1.2 * brightness;
+              } else if (windowFactor > 0.0) {
+                // Dark (unlit) windows at night/twilight
+                float h6 = fract(sin(colIdx * 211.9 + rowIdx * 349.3 + vSeed * 607.1 + faceId * 1013.7) * 21317.7631);
+                float darkVar = 0.2 + h6 * 0.4;                 // 0.2–0.6 wider spread
+                float darkMix = windowFactor;                    // fade dark effect in with night
+                totalEmissiveRadiance *= mix(1.0, darkVar, darkMix);
+                diffuseColor.rgb *= mix(1.0, darkVar, darkMix);
+              } else {
+                // Daytime window variation — glass tint
+                float h7 = fract(sin(colIdx * 131.3 + rowIdx * 277.9 + vSeed * 523.7 + faceId * 947.1) * 18397.5143);
+                float dayVar = 0.55 + h7 * 0.4;                 // 0.55–0.95
+                totalEmissiveRadiance *= dayVar;
+                diffuseColor.rgb *= dayVar;
+              }
+            }
+            // !hasWindow -> normal wall, no modification
+          }
+        }
+      }
+    `,
+  );
+
+  const uniforms = THREE.UniformsUtils.clone(std.uniforms);
+  uniforms.uTime = timeUniform; // direct reference, not cloned
+  uniforms.uElapsed = elapsedUniform ?? { value: 0 };
+  uniforms.roughness.value = 0.85;
+  uniforms.metalness.value = 0.05;
+
+  const material = new THREE.ShaderMaterial({
+    uniforms,
+    vertexShader,
+    fragmentShader,
+    lights: true,
+    fog: true,
+    defines: { STANDARD: "" },
+  });
+
+  // Tell Three.js this behaves like a standard material for rendering purposes
+  // (enables correct light uniform binding)
+  (material as unknown as Record<string, boolean>).isMeshStandardMaterial = true;
+
+  return material;
+}

package/src/lib/car-paths.ts

@@ -0,0 +1,244 @@
+import {
+  BLOCK_SIZE, BLOCK_STRIDE, OFFSET_X, OFFSET_Z,
+  V_ROADS, H_ROADS, PARK_BLOCKS,
+} from "./city-constants";
+
+export interface CarPath {
+  waypoints: { x: number; z: number }[];
+  totalLength: number;
+}
+
+const LANE_OFFSET = 1.5; // right-hand traffic offset from road center
+
+/** Find the nearest V_ROAD index to a given x position */
+function nearestVRoad(x: number): number {
+  let best = 0;
+  let bestDist = Infinity;
+  for (let i = 0; i < V_ROADS.length; i++) {
+    const d = Math.abs(V_ROADS[i] - x);
+    if (d < bestDist) { bestDist = d; best = i; }
+  }
+  return best;
+}
+
+/** Find the nearest H_ROAD index to a given z position */
+function nearestHRoad(z: number): number {
+  let best = 0;
+  let bestDist = Infinity;
+  for (let i = 0; i < H_ROADS.length; i++) {
+    const d = Math.abs(H_ROADS[i] - z);
+    if (d < bestDist) { bestDist = d; best = i; }
+  }
+  return best;
+}
+
+type Direction = "north" | "south" | "east" | "west";
+
+function laneAdjust(
+  roadX: number,
+  roadZ: number,
+  dir: Direction,
+): { x: number; z: number } {
+  // Lane offset to the right of travel direction
+  switch (dir) {
+    case "north": return { x: roadX + LANE_OFFSET, z: roadZ }; // traveling -Z, lane offset +X
+    case "south": return { x: roadX - LANE_OFFSET, z: roadZ }; // traveling +Z, lane offset -X
+    case "east":  return { x: roadX, z: roadZ + LANE_OFFSET }; // traveling +X, lane offset +Z
+    case "west":  return { x: roadX, z: roadZ - LANE_OFFSET }; // traveling -X, lane offset -Z
+  }
+}
+
+function randomDirection(rng: () => number, exclude?: Direction): Direction {
+  const dirs: Direction[] = ["north", "south", "east", "west"];
+  const filtered = exclude ? dirs.filter(d => d !== opposite(exclude)) : dirs;
+  return filtered[Math.floor(rng() * filtered.length)];
+}
+
+function opposite(dir: Direction): Direction {
+  switch (dir) {
+    case "north": return "south";
+    case "south": return "north";
+    case "east": return "west";
+    case "west": return "east";
+  }
+}
+
+function turnOptions(dir: Direction): Direction[] {
+  // straight, left, right (no U-turn)
+  switch (dir) {
+    case "north": return ["north", "west", "east"];
+    case "south": return ["south", "east", "west"];
+    case "east":  return ["east", "north", "south"];
+    case "west":  return ["west", "south", "north"];
+  }
+}
+
+function pickTurn(dir: Direction, rng: () => number): Direction {
+  const opts = turnOptions(dir);
+  const r = rng();
+  if (r < 0.5) return opts[0]; // straight 50%
+  if (r < 0.75) return opts[1]; // left 25%
+  return opts[2]; // right 25%
+}
+
+function nextRoadIndex(current: number, dir: "positive" | "negative", max: number): number | null {
+  const next = dir === "positive" ? current + 1 : current - 1;
+  if (next < 0 || next >= max) return null;
+  return next;
+}
+
+/** Check if a block at (row, col) is a park */
+function isPark(row: number, col: number): boolean {
+  return PARK_BLOCKS.has(`${row},${col}`);
+}
+
+function computeLength(waypoints: { x: number; z: number }[]): number {
+  let len = 0;
+  for (let i = 1; i < waypoints.length; i++) {
+    const dx = waypoints[i].x - waypoints[i - 1].x;
+    const dz = waypoints[i].z - waypoints[i - 1].z;
+    len += Math.sqrt(dx * dx + dz * dz);
+  }
+  return len;
+}
+
+let _rngSeed = 42;
+function defaultRng(): number {
+  _rngSeed = (_rngSeed * 16807 + 0) % 2147483647;
+  return _rngSeed / 2147483647;
+}
+
+/** Generate a path starting near a building at (blockRow, blockCol) */
+export function generatePathFromBuilding(blockRow: number, blockCol: number): CarPath {
+  const rng = defaultRng;
+
+  // Building center
+  const bx = OFFSET_X + blockCol * BLOCK_STRIDE;
+  const bz = OFFSET_Z + blockRow * BLOCK_STRIDE;
+
+  // Find nearest roads
+  const vi = nearestVRoad(bx);
+  const hi = nearestHRoad(bz);
+
+  // Pick whether to start on the vertical or horizontal road
+  const startOnV = rng() < 0.5;
+  let roadIdx: number;
+  let crossIdx: number;
+  let dir: Direction;
+
+  if (startOnV) {
+    roadIdx = vi;
+    crossIdx = hi;
+    dir = rng() < 0.5 ? "north" : "south";
+  } else {
+    roadIdx = hi;
+    crossIdx = vi;
+    dir = rng() < 0.5 ? "east" : "west";
+  }
+
+  return buildPath(roadIdx, crossIdx, startOnV, dir, rng);
+}
+
+/** Generate a random path from a random edge */
+export function generateRandomPath(): CarPath {
+  const rng = defaultRng;
+  const startOnV = rng() < 0.5;
+
+  if (startOnV) {
+    const roadIdx = Math.floor(rng() * V_ROADS.length);
+    const crossIdx = rng() < 0.5 ? 0 : H_ROADS.length - 1;
+    const dir: Direction = crossIdx === 0 ? "south" : "north";
+    return buildPath(roadIdx, crossIdx, true, dir, rng);
+  } else {
+    const roadIdx = Math.floor(rng() * H_ROADS.length);
+    const crossIdx = rng() < 0.5 ? 0 : V_ROADS.length - 1;
+    const dir: Direction = crossIdx === 0 ? "east" : "west";
+    return buildPath(roadIdx, crossIdx, false, dir, rng);
+  }
+}
+
+function buildPath(
+  roadIdx: number,
+  crossIdx: number,
+  onVertical: boolean,
+  dir: Direction,
+  rng: () => number,
+): CarPath {
+  const segments = 6 + Math.floor(rng() * 5); // 6-10 segments
+  const waypoints: { x: number; z: number }[] = [];
+
+  let currentV = onVertical ? roadIdx : crossIdx;
+  let currentH = onVertical ? crossIdx : roadIdx;
+  let currentDir = dir;
+
+  // Starting intersection
+  const startPos = laneAdjust(V_ROADS[currentV], H_ROADS[currentH], currentDir);
+  waypoints.push(startPos);
+
+  for (let seg = 0; seg < segments; seg++) {
+    // Move one block in the current direction
+    let nextV = currentV;
+    let nextH = currentH;
+
+    switch (currentDir) {
+      case "north": nextH = currentH - 1; break;
+      case "south": nextH = currentH + 1; break;
+      case "east":  nextV = currentV + 1; break;
+      case "west":  nextV = currentV - 1; break;
+    }
+
+    // Bounds check
+    if (nextV < 0 || nextV >= V_ROADS.length || nextH < 0 || nextH >= H_ROADS.length) {
+      break;
+    }
+
+    // Add waypoint at next intersection
+    const pos = laneAdjust(V_ROADS[nextV], H_ROADS[nextH], currentDir);
+    waypoints.push(pos);
+
+    currentV = nextV;
+    currentH = nextH;
+
+    // Decide turn at this intersection
+    currentDir = pickTurn(currentDir, rng);
+
+    // If turning, add a second waypoint at the same intersection but with new lane offset
+    if (seg < segments - 1) {
+      const turnPos = laneAdjust(V_ROADS[currentV], H_ROADS[currentH], currentDir);
+      // Only add if it's different (i.e., we turned)
+      if (turnPos.x !== pos.x || turnPos.z !== pos.z) {
+        waypoints.push(turnPos);
+      }
+    }
+  }
+
+  // Need at least 2 waypoints
+  if (waypoints.length < 2) {
+    // Fallback: just go one block
+    const fallbackDir = dir;
+    let fv = onVertical ? roadIdx : crossIdx;
+    let fh = onVertical ? crossIdx : roadIdx;
+    const w1 = laneAdjust(V_ROADS[fv], H_ROADS[fh], fallbackDir);
+    switch (fallbackDir) {
+      case "north": fh--; break;
+      case "south": fh++; break;
+      case "east": fv++; break;
+      case "west": fv--; break;
+    }
+    fv = Math.max(0, Math.min(V_ROADS.length - 1, fv));
+    fh = Math.max(0, Math.min(H_ROADS.length - 1, fh));
+    const w2 = laneAdjust(V_ROADS[fv], H_ROADS[fh], fallbackDir);
+    return { waypoints: [w1, w2], totalLength: computeLength([w1, w2]) };
+  }
+
+  return { waypoints, totalLength: computeLength(waypoints) };
+}
+
+/** Pre-generate a pool of random paths for fallback use */
+export function generatePathPool(count: number): CarPath[] {
+  const pool: CarPath[] = [];
+  for (let i = 0; i < count; i++) {
+    pool.push(generateRandomPath());
+  }
+  return pool;
+}

package/src/lib/car-system.ts

@@ -0,0 +1,182 @@
+import * as THREE from "three";
+import { CarPath } from "./car-paths";
+
+const MAX_CARS = 60;
+
+// Car color palette (8 colors)
+const CAR_COLORS = [
+  new THREE.Color("#e74c3c"), // red
+  new THREE.Color("#3498db"), // blue
+  new THREE.Color("#2ecc71"), // green
+  new THREE.Color("#f1c40f"), // yellow
+  new THREE.Color("#e67e22"), // orange
+  new THREE.Color("#9b59b6"), // purple
+  new THREE.Color("#1abc9c"), // teal
+  new THREE.Color("#ecf0f1"), // white
+];
+
+export interface ActiveCar {
+  slotIndex: number;
+  path: CarPath;
+  progress: number;       // distance traveled in world units
+  speed: number;          // 15-25 world units/sec
+  phase: "fadein" | "driving" | "fadeout" | "dead";
+  phaseTimer: number;
+  color: THREE.Color;
+  // Swap metadata for tooltip
+  walletAddress: string;
+  signature: string;
+  tokenIn: string | null;
+  tokenOut: string | null;
+  amountSol: number | null;
+}
+
+export interface CarPosition {
+  x: number;
+  y: number;
+  z: number;
+  rotY: number;
+  scale: number;
+}
+
+let _colorIdx = 0;
+
+export class CarSystem {
+  cars: (ActiveCar | null)[];
+  private freeSlots: number[];
+
+  constructor() {
+    this.cars = new Array(MAX_CARS).fill(null);
+    this.freeSlots = Array.from({ length: MAX_CARS }, (_, i) => i);
+  }
+
+  get maxCars(): number {
+    return MAX_CARS;
+  }
+
+  spawnCar(
+    path: CarPath,
+    walletAddress: string,
+    signature: string,
+    tokenIn: string | null,
+    tokenOut: string | null,
+    amountSol: number | null,
+  ): boolean {
+    if (this.freeSlots.length === 0) return false;
+    const slot = this.freeSlots.pop()!;
+
+    const color = CAR_COLORS[_colorIdx % CAR_COLORS.length];
+    _colorIdx++;
+
+    this.cars[slot] = {
+      slotIndex: slot,
+      path,
+      progress: 0,
+      speed: 8 + Math.random() * 6, // 8-14
+      phase: "fadein",
+      phaseTimer: 0,
+      color,
+      walletAddress,
+      signature,
+      tokenIn,
+      tokenOut,
+      amountSol,
+    };
+    return true;
+  }
+
+  update(delta: number): void {
+    for (let i = 0; i < MAX_CARS; i++) {
+      const car = this.cars[i];
+      if (!car) continue;
+
+      car.phaseTimer += delta;
+
+      switch (car.phase) {
+        case "fadein":
+          if (car.phaseTimer >= 0.5) {
+            car.phase = "driving";
+            car.phaseTimer = 0;
+          }
+          car.progress += car.speed * delta;
+          break;
+
+        case "driving":
+          car.progress += car.speed * delta;
+          if (car.progress >= car.path.totalLength) {
+            car.phase = "fadeout";
+            car.phaseTimer = 0;
+          }
+          break;
+
+        case "fadeout":
+          if (car.phaseTimer >= 0.5) {
+            car.phase = "dead";
+          }
+          break;
+
+        case "dead":
+          this.cars[i] = null;
+          this.freeSlots.push(i);
+          break;
+      }
+    }
+  }
+
+  /** Get world position, rotation and scale for a car at its current progress */
+  getCarPosition(car: ActiveCar): CarPosition {
+    const { waypoints, totalLength } = car.path;
+    const clampedProgress = Math.min(car.progress, totalLength);
+
+    // Find segment
+    let accumulated = 0;
+    let segIdx = 0;
+    for (let i = 1; i < waypoints.length; i++) {
+      const dx = waypoints[i].x - waypoints[i - 1].x;
+      const dz = waypoints[i].z - waypoints[i - 1].z;
+      const segLen = Math.sqrt(dx * dx + dz * dz);
+      if (accumulated + segLen >= clampedProgress) {
+        segIdx = i - 1;
+        break;
+      }
+      accumulated += segLen;
+      segIdx = i - 1;
+    }
+
+    const wp0 = waypoints[segIdx];
+    const wp1 = waypoints[Math.min(segIdx + 1, waypoints.length - 1)];
+    const dx = wp1.x - wp0.x;
+    const dz = wp1.z - wp0.z;
+    const segLen = Math.sqrt(dx * dx + dz * dz);
+    const t = segLen > 0 ? (clampedProgress - accumulated) / segLen : 0;
+
+    const x = wp0.x + dx * t;
+    const z = wp0.z + dz * t;
+    // Road surface at Y=0.02, car body center above
+    const y = 0.02 + 0.12 + 0.175; // wheel radius + half body height
+
+    // Rotation: face travel direction
+    let rotY = 0;
+    if (Math.abs(dx) > 0.01 || Math.abs(dz) > 0.01) {
+      rotY = Math.atan2(dx, dz);
+    }
+
+    // Scale for fade
+    let scale = 1;
+    if (car.phase === "fadein") {
+      const ft = Math.min(car.phaseTimer / 0.5, 1);
+      scale = 1 - (1 - ft) * (1 - ft); // ease-out
+    } else if (car.phase === "fadeout") {
+      const ft = Math.min(car.phaseTimer / 0.5, 1);
+      scale = 1 - ft * ft; // ease-in
+    } else if (car.phase === "dead") {
+      scale = 0;
+    }
+
+    return { x, y, z, rotY, scale };
+  }
+
+  getCarSwapInfo(slotIndex: number): ActiveCar | null {
+    return this.cars[slotIndex] ?? null;
+  }
+}

package/src/lib/city-constants.ts

@@ -0,0 +1,29 @@
+// Shared grid constants — single source of truth for the city layout.
+// Imported by CityGrid, InstancedBuildings, InstancedHouses, building-math, car-paths, etc.
+
+export const BLOCKS_PER_ROW = 26;
+export const CELL_SIZE = 4;
+export const ROAD_WIDTH = 6;
+export const SIDEWALK_WIDTH = 0.6;
+export const SLOTS_PER_BLOCK = 16; // 4x4 cells per block
+
+export const BLOCK_SIZE = 4 * CELL_SIZE; // 16
+export const BLOCK_STRIDE = BLOCK_SIZE + ROAD_WIDTH; // 22
+export const GRID_WORLD = BLOCKS_PER_ROW * BLOCK_STRIDE; // 572
+
+export const OFFSET_X = -GRID_WORLD / 2 + BLOCK_SIZE / 2 + ROAD_WIDTH / 2;
+export const OFFSET_Z = OFFSET_X;
+
+// Precomputed road center positions (27 vertical, 27 horizontal)
+export const V_ROADS: number[] = Array.from({ length: 27 }, (_, i) =>
+  OFFSET_X - BLOCK_SIZE / 2 - ROAD_WIDTH / 2 + i * BLOCK_STRIDE
+);
+export const H_ROADS: number[] = Array.from({ length: 27 }, (_, i) =>
+  OFFSET_Z - BLOCK_SIZE / 2 - ROAD_WIDTH / 2 + i * BLOCK_STRIDE
+);
+
+// Hardcoded park blocks — matches DB seed
+export const PARK_BLOCKS = new Set([
+  "10,13", "11,13", "13,11", "12,3", "13,3",
+  "8,18", "20,12", "4,10", "18,21", "22,6",
+]);