spoint 0.1.653 → 0.1.655

package/client/core/Weather.js

@@ -35,208 +35,10 @@
 import * as THREE from 'three'
 import { InstancedMesh2 } from '@three.ez/instanced-mesh'
 import { createGrassDecal } from '/src/terrain/GrassDecal.js'
-
-// Streak quad: a thin vertical billboard-ish quad (not a full 3D cylinder -- rain streaks read as a
-// 2D motion-blurred line from any practical viewing angle, matching the cheap-shading discipline
-// Grass.js documents for its own Lambert-lite material). Built once, shared across all instances.
-function makeStreakGeo() {
-  const w = 0.012, h = 0.55 // half-width negligible, tall thin quad in local Y (falls along -Y)
-  const pos = new Float32Array([
-    -w, 0, 0, w, 0, 0, w, -h, 0,
-    -w, 0, 0, w, -h, 0, -w, -h, 0,
-  ])
-  const uv = new Float32Array([0, 1, 1, 1, 1, 0, 0, 1, 1, 0, 0, 0])
-  const g = new THREE.BufferGeometry()
-  g.setAttribute('position', new THREE.BufferAttribute(pos, 3))
-  g.setAttribute('uv', new THREE.BufferAttribute(uv, 2))
-  g.computeBoundingSphere(); g.computeBoundingBox()
-  return g
-}
-
-// Splash ring: a small flat quad billboard, GPU-expanded+faded in the shader from droplet-recycle time
-// (see makeSplashMaterial) rather than real ring geometry -- cheaper than a torus/segmented-ring mesh
-// for a sub-half-second cosmetic pulse.
-function makeSplashGeo() {
-  const s = 0.5
-  const pos = new Float32Array([-s, 0, -s, s, 0, -s, s, 0, s, -s, 0, -s, s, 0, s, -s, 0, s])
-  const uv = new Float32Array([0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1])
-  const g = new THREE.BufferGeometry()
-  g.setAttribute('position', new THREE.BufferAttribute(pos, 3))
-  g.setAttribute('uv', new THREE.BufferAttribute(uv, 2))
-  g.computeBoundingSphere(); g.computeBoundingBox()
-  return g
-}
-
-// Rain streak material: per-instance fall-streak alpha, faces the camera around the vertical axis only
-// (billboarded in Y, matching how real rain is seen -- always "hanging" vertically regardless of view
-// yaw) via a per-instance yaw baked into the instance matrix at spawn (see _respawnDroplet), refreshed
-// only when the camera's OWN yaw changes enough to matter (see update()'s _lastCamYaw gate) rather than
-// every frame -- rain streaks are thin enough that sub-degree billboard error is imperceptible.
-function makeRainMaterial() {
-  const material = new THREE.ShaderMaterial({
-    transparent: true, depthWrite: false, side: THREE.DoubleSide,
-    uniforms: { uColor: { value: new THREE.Color(0.72, 0.78, 0.86) }, uOpacity: { value: 0.35 } },
-    vertexShader: `
-      varying vec2 vUv;
-      varying float vFade;
-      void main() {
-        vUv = uv;
-        // fade the quad edges (uv.x) so the streak reads as a soft line, not a hard-edged rectangle
-        vFade = 1.0 - abs(uv.x * 2.0 - 1.0);
-        vec4 mvPosition = modelViewMatrix * instanceMatrix * vec4(position, 1.0);
-        gl_Position = projectionMatrix * mvPosition;
-      }
-    `,
-    fragmentShader: `
-      uniform vec3 uColor; uniform float uOpacity;
-      varying vec2 vUv; varying float vFade;
-      void main() {
-        float streak = smoothstep(0.0, 0.15, vUv.y) * smoothstep(1.0, 0.85, vUv.y);
-        float a = uOpacity * vFade * (0.3 + 0.7 * streak);
-        if (a < 0.01) discard;
-        gl_FragColor = vec4(uColor, a);
-      }
-    `,
-  })
-  material.customProgramCacheKey = () => 'weather-rain-streak'
-  return material
-}
-
-// Splash material: a soft radial ring that expands + fades over its own per-instance lifetime
-// (uSplashTime holds the SHARED clock value at spawn, per-instance via initUniformsPerInstance --
-// elapsed = uTime - spawnTime, matching Grass.js's windPhase-style per-instance uniform pattern).
-function makeSplashMaterial() {
-  const material = new THREE.ShaderMaterial({
-    transparent: true, depthWrite: false, side: THREE.DoubleSide,
-    uniforms: { uTime: { value: 0 }, uColor: { value: new THREE.Color(0.8, 0.85, 0.92) }, uLifeS: { value: 0.4 } },
-    // instancedmesh2-instanceindex-undeclared-identifier-vegetation-shader: initUniformsPerInstance's
-    // (see the call below) windPhase/spawnTime-style texel-fetch injection needs the instanceIndex
-    // vertex attribute in scope, normally free via THREE's own '#include <batching_pars_vertex>' but
-    // absent from this hand-written ShaderMaterial -- same class of real live GL compile failure as
-    // Grass.js/SSAO.js/Vegetation.js's addShadowLOD sites (ERROR 0:83 'instanceIndex' : undeclared
-    // identifier, caught live via a WebGL2RenderingContext.prototype.compileShader monkeypatch, real
-    // booted server + weather splash particles streamed in during real gameplay, PORT=8250).
-    // '#include <instanced_pars_vertex>' declares instanceIndex + getInstancedMatrix(); the raw
-    // instanceMatrix attribute is a dummy zero-length buffer under InstancedMesh2's always-on
-    // USE_INSTANCING_INDIRECT mode (the real per-instance matrix lives in matricesTexture), so the
-    // pre-existing raw instanceMatrix read below was also silently wrong -- fixed by locally shadowing
-    // it with the real computed matrix.
-    vertexShader: `
-      uniform float uTime, uLifeS;
-      varying vec2 vUv; varying float vAlpha;
-      #include <instanced_pars_vertex>
-      void main() {
-        #ifdef USE_INSTANCING_INDIRECT
-          mat4 instanceMatrix = getInstancedMatrix();
-        #endif
-        vUv = uv;
-        float age = clamp((uTime - spawnTime) / uLifeS, 0.0, 1.0);
-        vAlpha = (1.0 - age) * step(0.0, spawnTime);
-        float scale = mix(0.15, 1.0, age);
-        vec3 p = position * scale;
-        vec4 mvPosition = modelViewMatrix * instanceMatrix * vec4(p, 1.0);
-        gl_Position = projectionMatrix * mvPosition;
-      }
-    `,
-    fragmentShader: `
-      uniform vec3 uColor;
-      varying vec2 vUv; varying float vAlpha;
-      void main() {
-        float d = distance(vUv, vec2(0.5));
-        float ring = smoothstep(0.5, 0.38, d) - smoothstep(0.38, 0.28, d);
-        float a = ring * vAlpha * 0.5;
-        if (a < 0.01) discard;
-        gl_FragColor = vec4(uColor, a);
-      }
-    `,
-  })
-  material.customProgramCacheKey = () => 'weather-splash-ring'
-  return material
-}
-
-// Snow flake quad: a small flat square (not a thin streak like rain -- snow falls slowly enough to read
-// as a soft round dot/blob, not a motion-blurred line), billboarded FULLY toward the camera (both yaw
-// AND pitch, unlike rain's yaw-only vertical hang) since a flat square only reads correctly face-on.
-function makeFlakeGeo() {
-  const s = 0.05
-  const pos = new Float32Array([-s, -s, 0, s, -s, 0, s, s, 0, -s, -s, 0, s, s, 0, -s, s, 0])
-  const uv = new Float32Array([0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1])
-  const g = new THREE.BufferGeometry()
-  g.setAttribute('position', new THREE.BufferAttribute(pos, 3))
-  g.setAttribute('uv', new THREE.BufferAttribute(uv, 2))
-  g.computeBoundingSphere(); g.computeBoundingBox()
-  return g
-}
-
-// Snow flake material: soft radial falloff (round dot, not a hard-edged square), full camera-facing
-// billboard done via the instance quaternion (set once per frame, see update() -- unlike rain's cheap
-// yaw-only refresh, full billboarding is unavoidable for a flat square viewed from any pitch).
-function makeSnowMaterial() {
-  const material = new THREE.ShaderMaterial({
-    transparent: true, depthWrite: false, side: THREE.DoubleSide,
-    uniforms: { uColor: { value: new THREE.Color(0.95, 0.97, 1.0) }, uOpacity: { value: 0.8 } },
-    vertexShader: `
-      varying vec2 vUv;
-      void main() {
-        vUv = uv;
-        vec4 mvPosition = modelViewMatrix * instanceMatrix * vec4(position, 1.0);
-        gl_Position = projectionMatrix * mvPosition;
-      }
-    `,
-    fragmentShader: `
-      uniform vec3 uColor; uniform float uOpacity;
-      varying vec2 vUv;
-      void main() {
-        float d = distance(vUv, vec2(0.5));
-        float a = uOpacity * smoothstep(0.5, 0.15, d);
-        if (a < 0.01) discard;
-        gl_FragColor = vec4(uColor, a);
-      }
-    `,
-  })
-  material.customProgramCacheKey = () => 'weather-snow-flake'
-  return material
-}
-
-// Far billboard-sheet tier material: identical visual language to the near-tier material it mirrors
-// (rain streak or snow flake) but with a distance-based fade baked in (uFadeNear/uFadeFar, per-instance
-// distance computed in the vertex shader from view-space Z) so the far sheet's own outer edge (where its
-// own box wrap would otherwise produce a visible "wall" of particles popping in/out) fades smoothly
-// instead of hard-cutting -- the one extra bit of shader work this cheap tier needs since it deliberately
-// has no per-instance CPU-side fade bookkeeping (see the tier-shape comment above: far tier is Y-fall +
-// wrap ONLY, no per-particle state beyond position).
-function makeFarSheetMaterial(baseColor, opacity, roundDot) {
-  const material = new THREE.ShaderMaterial({
-    transparent: true, depthWrite: false, side: THREE.DoubleSide,
-    uniforms: {
-      uColor: { value: baseColor.clone() }, uOpacity: { value: opacity },
-      uFadeNear: { value: 40 }, uFadeFar: { value: 90 },
-    },
-    vertexShader: `
-      varying vec2 vUv; varying float vDist;
-      void main() {
-        vUv = uv;
-        vec4 mvPosition = modelViewMatrix * instanceMatrix * vec4(position, 1.0);
-        vDist = -mvPosition.z;
-        gl_Position = projectionMatrix * mvPosition;
-      }
-    `,
-    fragmentShader: `
-      uniform vec3 uColor; uniform float uOpacity, uFadeNear, uFadeFar;
-      varying vec2 vUv; varying float vDist;
-      void main() {
-        float shape = ${roundDot ? 'smoothstep(0.5, 0.15, distance(vUv, vec2(0.5)))' : '(smoothstep(0.0, 0.15, vUv.y) * smoothstep(1.0, 0.85, vUv.y) * (1.0 - abs(vUv.x * 2.0 - 1.0)))'};
-        float fadeIn = smoothstep(uFadeNear, uFadeNear + 8.0, vDist);
-        float fadeOut = 1.0 - smoothstep(uFadeFar - 10.0, uFadeFar, vDist);
-        float a = uOpacity * shape * fadeIn * fadeOut;
-        if (a < 0.01) discard;
-        gl_FragColor = vec4(uColor, a);
-      }
-    `,
-  })
-  material.customProgramCacheKey = () => `weather-far-sheet-${roundDot ? 'snow' : 'rain'}`
-  return material
-}
+import {
+  makeStreakGeo, makeSplashGeo, makeRainMaterial, makeSplashMaterial,
+  makeFlakeGeo, makeSnowMaterial, makeFarSheetMaterial
+} from './WeatherMaterials.js'
 
 const _q = new THREE.Quaternion(), _upY = new THREE.Vector3(0, 1, 0)
 const _camPos = new THREE.Vector3(), _camQuat = new THREE.Quaternion()

package/client/core/WeatherMaterials.js

@@ -0,0 +1,208 @@
+// Pure geometry/material factories for Weather.js's rain/snow/splash/far-sheet InstancedMesh2 tiers.
+// No per-instance simulation state -- these build shared geometry buffers and ShaderMaterials once,
+// consumed by createWeather()'s stateful update loop in Weather.js itself.
+
+import * as THREE from 'three'
+
+// Streak quad: a thin vertical billboard-ish quad (not a full 3D cylinder -- rain streaks read as a
+// 2D motion-blurred line from any practical viewing angle, matching the cheap-shading discipline
+// Grass.js documents for its own Lambert-lite material). Built once, shared across all instances.
+export function makeStreakGeo() {
+  const w = 0.012, h = 0.55 // half-width negligible, tall thin quad in local Y (falls along -Y)
+  const pos = new Float32Array([
+    -w, 0, 0, w, 0, 0, w, -h, 0,
+    -w, 0, 0, w, -h, 0, -w, -h, 0,
+  ])
+  const uv = new Float32Array([0, 1, 1, 1, 1, 0, 0, 1, 1, 0, 0, 0])
+  const g = new THREE.BufferGeometry()
+  g.setAttribute('position', new THREE.BufferAttribute(pos, 3))
+  g.setAttribute('uv', new THREE.BufferAttribute(uv, 2))
+  g.computeBoundingSphere(); g.computeBoundingBox()
+  return g
+}
+
+// Splash ring: a small flat quad billboard, GPU-expanded+faded in the shader from droplet-recycle time
+// (see makeSplashMaterial) rather than real ring geometry -- cheaper than a torus/segmented-ring mesh
+// for a sub-half-second cosmetic pulse.
+export function makeSplashGeo() {
+  const s = 0.5
+  const pos = new Float32Array([-s, 0, -s, s, 0, -s, s, 0, s, -s, 0, -s, s, 0, s, -s, 0, s])
+  const uv = new Float32Array([0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1])
+  const g = new THREE.BufferGeometry()
+  g.setAttribute('position', new THREE.BufferAttribute(pos, 3))
+  g.setAttribute('uv', new THREE.BufferAttribute(uv, 2))
+  g.computeBoundingSphere(); g.computeBoundingBox()
+  return g
+}
+
+// Rain streak material: per-instance fall-streak alpha, faces the camera around the vertical axis only
+// (billboarded in Y, matching how real rain is seen -- always "hanging" vertically regardless of view
+// yaw) via a per-instance yaw baked into the instance matrix at spawn (see Weather.js's
+// _respawnDroplet), refreshed only when the camera's OWN yaw changes enough to matter (see update()'s
+// _lastCamYaw gate) rather than every frame -- rain streaks are thin enough that sub-degree billboard
+// error is imperceptible.
+export function makeRainMaterial() {
+  const material = new THREE.ShaderMaterial({
+    transparent: true, depthWrite: false, side: THREE.DoubleSide,
+    uniforms: { uColor: { value: new THREE.Color(0.72, 0.78, 0.86) }, uOpacity: { value: 0.35 } },
+    vertexShader: `
+      varying vec2 vUv;
+      varying float vFade;
+      void main() {
+        vUv = uv;
+        // fade the quad edges (uv.x) so the streak reads as a soft line, not a hard-edged rectangle
+        vFade = 1.0 - abs(uv.x * 2.0 - 1.0);
+        vec4 mvPosition = modelViewMatrix * instanceMatrix * vec4(position, 1.0);
+        gl_Position = projectionMatrix * mvPosition;
+      }
+    `,
+    fragmentShader: `
+      uniform vec3 uColor; uniform float uOpacity;
+      varying vec2 vUv; varying float vFade;
+      void main() {
+        float streak = smoothstep(0.0, 0.15, vUv.y) * smoothstep(1.0, 0.85, vUv.y);
+        float a = uOpacity * vFade * (0.3 + 0.7 * streak);
+        if (a < 0.01) discard;
+        gl_FragColor = vec4(uColor, a);
+      }
+    `,
+  })
+  material.customProgramCacheKey = () => 'weather-rain-streak'
+  return material
+}
+
+// Splash material: a soft radial ring that expands + fades over its own per-instance lifetime
+// (uSplashTime holds the SHARED clock value at spawn, per-instance via initUniformsPerInstance --
+// elapsed = uTime - spawnTime, matching Grass.js's windPhase-style per-instance uniform pattern).
+export function makeSplashMaterial() {
+  const material = new THREE.ShaderMaterial({
+    transparent: true, depthWrite: false, side: THREE.DoubleSide,
+    uniforms: { uTime: { value: 0 }, uColor: { value: new THREE.Color(0.8, 0.85, 0.92) }, uLifeS: { value: 0.4 } },
+    // instancedmesh2-instanceindex-undeclared-identifier-vegetation-shader: initUniformsPerInstance's
+    // (see the call below) windPhase/spawnTime-style texel-fetch injection needs the instanceIndex
+    // vertex attribute in scope, normally free via THREE's own '#include <batching_pars_vertex>' but
+    // absent from this hand-written ShaderMaterial -- same class of real live GL compile failure as
+    // Grass.js/SSAO.js/Vegetation.js's addShadowLOD sites (ERROR 0:83 'instanceIndex' : undeclared
+    // identifier, caught live via a WebGL2RenderingContext.prototype.compileShader monkeypatch, real
+    // booted server + weather splash particles streamed in during real gameplay, PORT=8250).
+    // '#include <instanced_pars_vertex>' declares instanceIndex + getInstancedMatrix(); the raw
+    // instanceMatrix attribute is a dummy zero-length buffer under InstancedMesh2's always-on
+    // USE_INSTANCING_INDIRECT mode (the real per-instance matrix lives in matricesTexture), so the
+    // pre-existing raw instanceMatrix read below was also silently wrong -- fixed by locally shadowing
+    // it with the real computed matrix.
+    vertexShader: `
+      uniform float uTime, uLifeS;
+      varying vec2 vUv; varying float vAlpha;
+      #include <instanced_pars_vertex>
+      void main() {
+        #ifdef USE_INSTANCING_INDIRECT
+          mat4 instanceMatrix = getInstancedMatrix();
+        #endif
+        vUv = uv;
+        float age = clamp((uTime - spawnTime) / uLifeS, 0.0, 1.0);
+        vAlpha = (1.0 - age) * step(0.0, spawnTime);
+        float scale = mix(0.15, 1.0, age);
+        vec3 p = position * scale;
+        vec4 mvPosition = modelViewMatrix * instanceMatrix * vec4(p, 1.0);
+        gl_Position = projectionMatrix * mvPosition;
+      }
+    `,
+    fragmentShader: `
+      uniform vec3 uColor;
+      varying vec2 vUv; varying float vAlpha;
+      void main() {
+        float d = distance(vUv, vec2(0.5));
+        float ring = smoothstep(0.5, 0.38, d) - smoothstep(0.38, 0.28, d);
+        float a = ring * vAlpha * 0.5;
+        if (a < 0.01) discard;
+        gl_FragColor = vec4(uColor, a);
+      }
+    `,
+  })
+  material.customProgramCacheKey = () => 'weather-splash-ring'
+  return material
+}
+
+// Snow flake quad: a small flat square (not a thin streak like rain -- snow falls slowly enough to read
+// as a soft round dot/blob, not a motion-blurred line), billboarded FULLY toward the camera (both yaw
+// AND pitch, unlike rain's yaw-only vertical hang) since a flat square only reads correctly face-on.
+export function makeFlakeGeo() {
+  const s = 0.05
+  const pos = new Float32Array([-s, -s, 0, s, -s, 0, s, s, 0, -s, -s, 0, s, s, 0, -s, s, 0])
+  const uv = new Float32Array([0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1])
+  const g = new THREE.BufferGeometry()
+  g.setAttribute('position', new THREE.BufferAttribute(pos, 3))
+  g.setAttribute('uv', new THREE.BufferAttribute(uv, 2))
+  g.computeBoundingSphere(); g.computeBoundingBox()
+  return g
+}
+
+// Snow flake material: soft radial falloff (round dot, not a hard-edged square), full camera-facing
+// billboard done via the instance quaternion (set once per frame, see Weather.js's update() -- unlike
+// rain's cheap yaw-only refresh, full billboarding is unavoidable for a flat square viewed from any pitch).
+export function makeSnowMaterial() {
+  const material = new THREE.ShaderMaterial({
+    transparent: true, depthWrite: false, side: THREE.DoubleSide,
+    uniforms: { uColor: { value: new THREE.Color(0.95, 0.97, 1.0) }, uOpacity: { value: 0.8 } },
+    vertexShader: `
+      varying vec2 vUv;
+      void main() {
+        vUv = uv;
+        vec4 mvPosition = modelViewMatrix * instanceMatrix * vec4(position, 1.0);
+        gl_Position = projectionMatrix * mvPosition;
+      }
+    `,
+    fragmentShader: `
+      uniform vec3 uColor; uniform float uOpacity;
+      varying vec2 vUv;
+      void main() {
+        float d = distance(vUv, vec2(0.5));
+        float a = uOpacity * smoothstep(0.5, 0.15, d);
+        if (a < 0.01) discard;
+        gl_FragColor = vec4(uColor, a);
+      }
+    `,
+  })
+  material.customProgramCacheKey = () => 'weather-snow-flake'
+  return material
+}
+
+// Far billboard-sheet tier material: identical visual language to the near-tier material it mirrors
+// (rain streak or snow flake) but with a distance-based fade baked in (uFadeNear/uFadeFar, per-instance
+// distance computed in the vertex shader from view-space Z) so the far sheet's own outer edge (where its
+// own box wrap would otherwise produce a visible "wall" of particles popping in/out) fades smoothly
+// instead of hard-cutting -- the one extra bit of shader work this cheap tier needs since it deliberately
+// has no per-instance CPU-side fade bookkeeping (see Weather.js's tier-shape comment: far tier is
+// Y-fall + wrap ONLY, no per-particle state beyond position).
+export function makeFarSheetMaterial(baseColor, opacity, roundDot) {
+  const material = new THREE.ShaderMaterial({
+    transparent: true, depthWrite: false, side: THREE.DoubleSide,
+    uniforms: {
+      uColor: { value: baseColor.clone() }, uOpacity: { value: opacity },
+      uFadeNear: { value: 40 }, uFadeFar: { value: 90 },
+    },
+    vertexShader: `
+      varying vec2 vUv; varying float vDist;
+      void main() {
+        vUv = uv;
+        vec4 mvPosition = modelViewMatrix * instanceMatrix * vec4(position, 1.0);
+        vDist = -mvPosition.z;
+        gl_Position = projectionMatrix * mvPosition;
+      }
+    `,
+    fragmentShader: `
+      uniform vec3 uColor; uniform float uOpacity, uFadeNear, uFadeFar;
+      varying vec2 vUv; varying float vDist;
+      void main() {
+        float shape = ${roundDot ? 'smoothstep(0.5, 0.15, distance(vUv, vec2(0.5)))' : '(smoothstep(0.0, 0.15, vUv.y) * smoothstep(1.0, 0.85, vUv.y) * (1.0 - abs(vUv.x * 2.0 - 1.0)))'};
+        float fadeIn = smoothstep(uFadeNear, uFadeNear + 8.0, vDist);
+        float fadeOut = 1.0 - smoothstep(uFadeFar - 10.0, uFadeFar, vDist);
+        float a = uOpacity * shape * fadeIn * fadeOut;
+        if (a < 0.01) discard;
+        gl_FragColor = vec4(uColor, a);
+      }
+    `,
+  })
+  material.customProgramCacheKey = () => `weather-far-sheet-${roundDot ? 'snow' : 'rain'}`
+  return material
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoint",
-  "version": "0.1.653",
+  "version": "0.1.655",
   "description": "Physics and netcode SDK for multiplayer game servers",
   "type": "module",
   "workspaces": [

package/src/sdk/ServerAPI.js

@@ -1,17 +1,16 @@
 import { createServer as createHttpServer } from 'node:http'
 import { WebSocketServer as WSServer } from 'ws'
-import { MSG } from '../protocol/MessageTypes.js'
 import { SnapshotEncoder } from '../netcode/SnapshotEncoder.js'
 import { createStaticHandler } from './StaticHandler.js'
 import { WebSocketTransport } from '../transport/WebSocketTransport.js'
 import { WebTransportServer } from '../transport/WebTransportServer.js'
 import { createUploadHandler } from './UploadHandler.js'
 import { setupTerrainStreaming } from '../terrain/TerrainPhysics.js'
-import { timingSafeTokenEqual } from './authCompare.js'
-import { renderMetrics } from './Metrics.js'
 import { restoreWorldSnapshot, saveWorldSnapshot } from './WorldPersistence.js'
-import { collectBenchmark } from './PublicBenchmark.js'
-import { validateMessage, KIND_PLACE, KIND_UPDATE, KIND_REMOVE, KIND_CLEAR, KIND_DATASET, KIND_CAMERA } from './FreddieBridge.js'
+import {
+  handleUploadModel, handleDebugLog, handleClientError, handleDebugServer,
+  handleMetrics, handleBenchmark, handleFreddieViz
+} from './ServerAPIRoutes.js'
 
 // Top-down color+height minimap bake-if-missing, keyed by seed (real artifact: apps/world/<worldName>.<seed>.minimap.png
 // + a sibling .json header). Reuses scripts/bake-minimap.mjs's bakeMinimap() directly (pure-Node CPU height+climate
@@ -56,50 +55,6 @@ export async function bakeMinimapIfMissing(worldName, tcfg, opts = {}) {
   console.log(`[minimap] baked ${base}.png (${header.N}x${header.N}, ${(png.length / 1024).toFixed(1)}KB, height ${header.minHeight}..${header.maxHeight}m) in ${Date.now() - t0}ms`)
 }
 
-// Per-IP token bucket for /debug-log: caps sustained log-line volume from any single origin even after
-// the loopback/EDITOR_TOKEN gate passes, so a single misbehaving/malicious client on an allowed origin
-// can't still spam the server console / consume CPU by hammering the endpoint at wire speed.
-const DEBUG_LOG_BUCKET_CAPACITY = 20 // burst allowance, lines
-const DEBUG_LOG_BUCKET_REFILL_PER_SEC = 5 // steady-state cap, lines/sec
-const _debugLogBuckets = new Map() // ip -> { tokens, lastRefillMs }
-
-function debugLogRateLimited(ip) {
-  const now = Date.now()
-  let b = _debugLogBuckets.get(ip)
-  if (!b) { b = { tokens: DEBUG_LOG_BUCKET_CAPACITY, lastRefillMs: now }; _debugLogBuckets.set(ip, b) }
-  const elapsedSec = (now - b.lastRefillMs) / 1000
-  if (elapsedSec > 0) {
-    b.tokens = Math.min(DEBUG_LOG_BUCKET_CAPACITY, b.tokens + elapsedSec * DEBUG_LOG_BUCKET_REFILL_PER_SEC)
-    b.lastRefillMs = now
-  }
-  if (b.tokens < 1) return true // no tokens left -> rate limited
-  b.tokens -= 1
-  return false
-}
-
-// Per-IP token bucket for /client-error: same shape as debugLogRateLimited above, but this
-// endpoint is PUBLIC (real deployed players, not loopback-only dev tooling) so the bucket is the
-// only defense against a hostile or buggy client flooding the server with crash reports -- tighter
-// than the debug-log bucket since a real crash storm (e.g. every connected player hitting the same
-// bug at once) should still log a representative sample, not every single occurrence.
-const CLIENT_ERROR_BUCKET_CAPACITY = 5
-const CLIENT_ERROR_BUCKET_REFILL_PER_SEC = 0.2 // 1 report per 5s steady-state per IP
-const _clientErrorBuckets = new Map() // ip -> { tokens, lastRefillMs }
-
-function clientErrorRateLimited(ip) {
-  const now = Date.now()
-  let b = _clientErrorBuckets.get(ip)
-  if (!b) { b = { tokens: CLIENT_ERROR_BUCKET_CAPACITY, lastRefillMs: now }; _clientErrorBuckets.set(ip, b) }
-  const elapsedSec = (now - b.lastRefillMs) / 1000
-  if (elapsedSec > 0) {
-    b.tokens = Math.min(CLIENT_ERROR_BUCKET_CAPACITY, b.tokens + elapsedSec * CLIENT_ERROR_BUCKET_REFILL_PER_SEC)
-    b.lastRefillMs = now
-  }
-  if (b.tokens < 1) return true
-  b.tokens -= 1
-  return false
-}
-
 export function createServerAPI(ctx) {
   const { config, port, tickRate, staticDirs, appLoader, appRuntime, physics, physicsIntegration, stageLoader } = ctx
   const { tickSystem, playerManager, networkState, lagCompensator, connections, sessions, inspector, emitter, reloadManager, eventBus, eventLog, storage } = ctx
@@ -279,227 +234,13 @@ export function createServerAPI(ctx) {
         })
         const staticHandler = staticDirs.length > 0 ? createStaticHandler(staticDirs, { getWorldInfo }) : null
         const httpHandler = (req, res) => {
-          if (req.method === 'POST' && req.url === '/upload-model') {
-            // EDITOR_TOKEN unset = open (dev default); configured = required via X-Editor-Token header
-            const _tok = process.env.EDITOR_TOKEN
-            if (_tok && !timingSafeTokenEqual(req.headers['x-editor-token'], _tok)) { res.writeHead(403); res.end('forbidden'); return }
-            uploadHandler(req, res); return
-          }
-          if (req.method === 'POST' && req.url === '/debug-log') {
-            // gated: loopback origin is always allowed (local dev console passthrough); a non-loopback
-            // origin must present a valid X-Editor-Token when EDITOR_TOKEN is configured, and is refused
-            // outright when it isn't (an unset EDITOR_TOKEN must not leave this endpoint open to the world).
-            const _remote = req.socket?.remoteAddress || ''
-            const _isLoopback = _remote === '127.0.0.1' || _remote === '::1' || _remote === '::ffff:127.0.0.1'
-            if (!_isLoopback) {
-              const _tok = process.env.EDITOR_TOKEN
-              if (!_tok || !timingSafeTokenEqual(req.headers['x-editor-token'], _tok)) { res.writeHead(403); res.end('forbidden'); return }
-            }
-            // token-bucket rate limit per-IP: caps sustained lines/sec even from an already-authorized origin
-            if (debugLogRateLimited(_remote)) { res.writeHead(429); res.end('rate limited'); return }
-            // size-capped: unbounded body buffering here let any origin exhaust server memory
-            const _DEBUG_LOG_MAX = 256 * 1024
-            let _len = 0, _over = false
-            const chunks = []
-            req.on('data', d => {
-              if (_over) return
-              _len += d.length
-              if (_len > _DEBUG_LOG_MAX) { _over = true; res.writeHead(413); res.end('payload too large'); req.destroy(); return }
-              chunks.push(d)
-            })
-            req.on('end', () => { if (_over) return; try { const d = JSON.parse(Buffer.concat(chunks).toString()); console.log('[browser]', ...d) } catch(_) {}; res.writeHead(200); res.end() })
-            return
-          }
-          if (req.method === 'POST' && req.url === '/client-error') {
-            // PUBLIC, opt-in-only-on-the-CLIENT-side endpoint (client/core/ErrorTelemetry.js) --
-            // unlike /debug-log and /upload-model above, this is intentionally reachable from any
-            // real deployed player, not loopback/EDITOR_TOKEN-gated, since the whole point is to
-            // hear from crashes on machines the operator has no console access to. The gate here is
-            // purely anti-abuse (rate limit + size cap), not an identity/auth check -- the payload
-            // itself carries no PII by construction (see ErrorTelemetry.js's schema comment).
-            const _remote = req.socket?.remoteAddress || ''
-            if (clientErrorRateLimited(_remote)) { res.writeHead(429); res.end('rate limited'); return }
-            const _CLIENT_ERROR_MAX = 16 * 1024 // payload is a small structured JSON object, not a log dump
-            let _len = 0, _over = false
-            const chunks = []
-            req.on('data', d => {
-              if (_over) return
-              _len += d.length
-              if (_len > _CLIENT_ERROR_MAX) { _over = true; res.writeHead(413); res.end('payload too large'); req.destroy(); return }
-              chunks.push(d)
-            })
-            req.on('end', () => {
-              if (_over) return
-              try {
-                const report = JSON.parse(Buffer.concat(chunks).toString())
-                // Structured, one-line-per-report console surface (an operator greps/aggregates
-                // this today; a real dashboard/store is explicitly out of scope for this first
-                // slice -- see the sibling PRD row filed for that). kind/message/stack/url/ua/ts
-                // are the ErrorTelemetry.js schema fields; renderControls/deviceTier are attached
-                // objects, logged inline so `console.log`'s default object formatting keeps them
-                // inspectable rather than flattened into an unreadable string.
-                console.error(`[client-error] ${report.kind || 'error'}: ${String(report.message || '').slice(0, 500)}`,
-                  { url: report.url, ua: report.ua, stack: String(report.stack || '').slice(0, 2000), renderControls: report.renderControls, deviceTier: report.deviceTier, remote: _remote })
-              } catch (_) { /* malformed payload from a hostile/buggy client -- drop silently, still 200 so sendBeacon doesn't retry-storm */ }
-              res.writeHead(200); res.end()
-            })
-            return
-          }
-          if (req.method === 'GET' && req.url === '/debug/server') {
-            // loopback-only: leaks tick/player/entity/session counts + process memory internals
-            const remote = req.socket?.remoteAddress || ''
-            if (remote !== '127.0.0.1' && remote !== '::1' && remote !== '::ffff:127.0.0.1') { res.writeHead(403); res.end('forbidden'); return }
-            const data = JSON.stringify({
-              tick: tickSystem.currentTick,
-              tickRate: ctx.tickRate,
-              players: playerManager.getPlayerCount(),
-              entities: appRuntime.entities.size,
-              connections: connections.getAllStats(),
-              sessions: sessions.getActiveCount(),
-              heap: process.memoryUsage()
-            })
-            res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(data); return
-          }
-          if (req.method === 'GET' && req.url === '/metrics') {
-            // server-scale-prometheus-metrics-endpoint-dashboard: same loopback-only gate as /debug/server
-            // immediately above -- this leaks the identical class of operational internals (tick/player/
-            // entity counts, process memory), just reformatted for Prometheus scrape instead of a one-shot
-            // JSON GET. A Prometheus server itself is expected to run co-located (or reached via an
-            // operator-controlled reverse-proxy/tunnel that terminates on loopback), matching how every
-            // other loopback-gated route in this file is already meant to be consumed.
-            const remote = req.socket?.remoteAddress || ''
-            if (remote !== '127.0.0.1' && remote !== '::1' && remote !== '::ffff:127.0.0.1') { res.writeHead(403); res.end('forbidden'); return }
-            const body = renderMetrics({
-              tick: tickSystem.currentTick,
-              tickRate: ctx.tickRate,
-              players: playerManager.getPlayerCount(),
-              entities: appRuntime.entities.size,
-              sessionCount: sessions.getActiveCount(),
-              uptimeSec: process.uptime(),
-              memoryUsage: () => process.memoryUsage(),
-              // TickHandler.js's onTick.getMetrics() -- see ctx.tickHandlerFn (server.js/WorkerEntry.js
-              // setTickHandler), a stable alias reload-swappable handlerState.fn is mirrored onto so this
-              // route never reaches into reload-internal plumbing directly. Absent (fresh boot before the
-              // first tick, or a handler build that predates this alias) degrades to no tickTiming section
-              // rather than throwing -- /metrics must stay a safe, always-200 operational surface.
-              tickTiming: typeof ctx.tickHandlerFn?.getMetrics === 'function' ? ctx.tickHandlerFn.getMetrics() : null,
-              // RoomDirectory (src/sdk/RoomDirectory.js) is a standalone, opt-in multi-room primitive not
-              // constructed by every boot path -- its own getStatus() doc comment already names this route
-              // as its intended consumer, so a caller that DOES wire one up onto ctx.roomDirectory gets
-              // per-room rows for free with zero further ServerAPI.js changes; every other boot path simply
-              // omits the rooms section (Array.isArray guard in renderMetrics).
-              rooms: typeof ctx.roomDirectory?.getStatus === 'function' ? ctx.roomDirectory.getStatus() : undefined,
-            })
-            res.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' }); res.end(body); return
-          }
-          if (req.method === 'GET' && req.url === '/benchmark') {
-            // Public benchmark endpoint (see PRD rows ugc-platform + ugc-public-benchmark-dashboard):
-            // exposes standardized server performance data as JSON with CORS headers so a static HTML
-            // dashboard page (client/benchmark.html) can consume it from any origin. Deliberately UN-gated
-            // (no loopback/EDITOR_TOKEN check) -- this is a public brag surface, not an operational secret.
-            // The data shape is deliberately high-level (tick stats, player counts, memory, build info) and
-            // carries zero PII, internal IPs, auth tokens, or player-identifying data.
-            try {
-              const data = collectBenchmark(ctx)
-              const json = JSON.stringify(data)
-              res.writeHead(200, {
-                'Content-Type': 'application/json',
-                'Cache-Control': 'no-cache',
-                'Access-Control-Allow-Origin': '*',
-              })
-              res.end(json)
-            } catch (err) {
-              res.writeHead(500, { 'Content-Type': 'application/json' })
-              res.end(JSON.stringify({ error: 'benchmark collection failed', detail: err.message }))
-            }
-            return
-          }
-          if (req.method === 'POST' && req.url === '/freddie/viz') {
-            // FreddieBridge viz endpoint: accepts FreddieBridge messages (JSON), validates them,
-            // and creates/updates/destroys entities in the live world. EDITOR_TOKEN-gated when
-            // configured (same discipline as /upload-model above); an unset EDITOR_TOKEN leaves
-            // this endpoint open (dev default). Rate-limited by body size for safety.
-            const _tok = process.env.EDITOR_TOKEN
-            if (_tok && !timingSafeTokenEqual(req.headers['x-editor-token'], _tok)) { res.writeHead(403); res.end('forbidden'); return }
-            const _FREDDIE_MAX = 256 * 1024
-            let _len = 0, _over = false
-            const chunks = []
-            req.on('data', d => {
-              if (_over) return
-              _len += d.length
-              if (_len > _FREDDIE_MAX) { _over = true; res.writeHead(413); res.end('payload too large'); req.destroy(); return }
-              chunks.push(d)
-            })
-            req.on('end', () => {
-              if (_over) return
-              let body
-              try { body = JSON.parse(Buffer.concat(chunks).toString()) } catch (_) { res.writeHead(400, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'invalid JSON' })); return }
-              // Accept a single message or an array of messages
-              const messages = Array.isArray(body) ? body : [body]
-              const results = []
-              for (const msg of messages) {
-                const v = validateMessage(msg)
-                if (!v.valid) { results.push({ id: msg.id, ok: false, error: 'validation failed', detail: v.errors }); continue }
-                try {
-                  if (msg.kind === KIND_PLACE) {
-                    const p = msg.payload
-                    const entityId = p.entityId
-                    // Remove existing entity with same id if present (idempotent place)
-                    if (appRuntime.entities.has(entityId)) appRuntime.destroyEntity(entityId)
-                    const cfg = {
-                      position: p.position || [0, 0, 0],
-                      scale: p.scale || [1, 1, 1],
-                      custom: {
-                        mesh: p.primitive || 'box',
-                        color: p.color ?? 0xffffff,
-                        emissive: p.emissive ?? 0x000000,
-                        opacity: p.opacity ?? 1,
-                        label: p.label || null,
-                        _freddieSource: msg.source,
-                        _freddieId: entityId,
-                      },
-                      config: {},
-                    }
-                    if (p.primitive === 'model' && p.model) cfg.model = p.model
-                    appRuntime.spawnEntity(entityId, cfg)
-                    results.push({ id: msg.id, ok: true, entityId })
-                  } else if (msg.kind === KIND_UPDATE) {
-                    const p = msg.payload
-                    const e = appRuntime.entities.get(p.entityId)
-                    if (!e) { results.push({ id: msg.id, ok: false, error: 'entity not found', entityId: p.entityId }); continue }
-                    if (p.position) e.position = [...p.position]
-                    if (p.scale) e.scale = [...p.scale]
-                    if (e.custom) {
-                      if (p.color !== undefined) e.custom.color = p.color
-                      if (p.emissive !== undefined) e.custom.emissive = p.emissive
-                      if (p.opacity !== undefined) e.custom.opacity = p.opacity
-                      if (p.label !== undefined) e.custom.label = p.label
-                    }
-                    results.push({ id: msg.id, ok: true, entityId: p.entityId })
-                  } else if (msg.kind === KIND_REMOVE) {
-                    appRuntime.destroyEntity(msg.payload.entityId)
-                    results.push({ id: msg.id, ok: true, entityId: msg.payload.entityId })
-                  } else if (msg.kind === KIND_CLEAR) {
-                    // Remove all entities created by this source
-                    const source = msg.source
-                    const toRemove = []
-                    for (const [id, e] of appRuntime.entities) {
-                      if (e.custom?._freddieSource === source) toRemove.push(id)
-                    }
-                    for (const id of toRemove) appRuntime.destroyEntity(id)
-                    results.push({ id: msg.id, ok: true, removed: toRemove.length })
-                  } else {
-                    results.push({ id: msg.id, ok: false, error: `unhandled kind: ${msg.kind}` })
-                  }
-                } catch (e) {
-                  results.push({ id: msg.id, ok: false, error: e.message })
-                }
-              }
-              res.writeHead(200, { 'Content-Type': 'application/json' })
-              res.end(JSON.stringify(Array.isArray(body) ? results : results[0]))
-            })
-            return
-          }
+          if (req.method === 'POST' && req.url === '/upload-model') { handleUploadModel(req, res, uploadHandler); return }
+          if (req.method === 'POST' && req.url === '/debug-log') { handleDebugLog(req, res); return }
+          if (req.method === 'POST' && req.url === '/client-error') { handleClientError(req, res); return }
+          if (req.method === 'GET' && req.url === '/debug/server') { handleDebugServer(req, res, ctx); return }
+          if (req.method === 'GET' && req.url === '/metrics') { handleMetrics(req, res, ctx); return }
+          if (req.method === 'GET' && req.url === '/benchmark') { handleBenchmark(req, res, ctx); return }
+          if (req.method === 'POST' && req.url === '/freddie/viz') { handleFreddieViz(req, res, appRuntime); return }
           if (staticHandler) {
             Promise.resolve(staticHandler(req, res)).catch(e => {
               console.error('[static] handler error:', e?.message || e)

package/src/sdk/ServerAPIRoutes.js

@@ -0,0 +1,279 @@
+// HTTP route handlers for ServerAPI.js's start(): /upload-model, /debug-log, /client-error,
+// /debug/server, /metrics, /benchmark, /freddie/viz. Split out because start()'s httpHandler
+// closure was the single largest contiguous block in ServerAPI.js -- each handler here is a pure
+// function of (req, res, ctx-derived state), no shared closure with the rest of ServerAPI.js beyond
+// what's passed in explicitly.
+
+import { timingSafeTokenEqual } from './authCompare.js'
+import { renderMetrics } from './Metrics.js'
+import { collectBenchmark } from './PublicBenchmark.js'
+import { validateMessage, KIND_PLACE, KIND_UPDATE, KIND_REMOVE, KIND_CLEAR } from './FreddieBridge.js'
+
+// Per-IP token bucket for /debug-log: caps sustained log-line volume from any single origin even after
+// the loopback/EDITOR_TOKEN gate passes, so a single misbehaving/malicious client on an allowed origin
+// can't still spam the server console / consume CPU by hammering the endpoint at wire speed.
+const DEBUG_LOG_BUCKET_CAPACITY = 20 // burst allowance, lines
+const DEBUG_LOG_BUCKET_REFILL_PER_SEC = 5 // steady-state cap, lines/sec
+const _debugLogBuckets = new Map() // ip -> { tokens, lastRefillMs }
+
+function debugLogRateLimited(ip) {
+  const now = Date.now()
+  let b = _debugLogBuckets.get(ip)
+  if (!b) { b = { tokens: DEBUG_LOG_BUCKET_CAPACITY, lastRefillMs: now }; _debugLogBuckets.set(ip, b) }
+  const elapsedSec = (now - b.lastRefillMs) / 1000
+  if (elapsedSec > 0) {
+    b.tokens = Math.min(DEBUG_LOG_BUCKET_CAPACITY, b.tokens + elapsedSec * DEBUG_LOG_BUCKET_REFILL_PER_SEC)
+    b.lastRefillMs = now
+  }
+  if (b.tokens < 1) return true // no tokens left -> rate limited
+  b.tokens -= 1
+  return false
+}
+
+// Per-IP token bucket for /client-error: same shape as debugLogRateLimited above, but this
+// endpoint is PUBLIC (real deployed players, not loopback-only dev tooling) so the bucket is the
+// only defense against a hostile or buggy client flooding the server with crash reports -- tighter
+// than the debug-log bucket since a real crash storm (e.g. every connected player hitting the same
+// bug at once) should still log a representative sample, not every single occurrence.
+const CLIENT_ERROR_BUCKET_CAPACITY = 5
+const CLIENT_ERROR_BUCKET_REFILL_PER_SEC = 0.2 // 1 report per 5s steady-state per IP
+const _clientErrorBuckets = new Map() // ip -> { tokens, lastRefillMs }
+
+function clientErrorRateLimited(ip) {
+  const now = Date.now()
+  let b = _clientErrorBuckets.get(ip)
+  if (!b) { b = { tokens: CLIENT_ERROR_BUCKET_CAPACITY, lastRefillMs: now }; _clientErrorBuckets.set(ip, b) }
+  const elapsedSec = (now - b.lastRefillMs) / 1000
+  if (elapsedSec > 0) {
+    b.tokens = Math.min(CLIENT_ERROR_BUCKET_CAPACITY, b.tokens + elapsedSec * CLIENT_ERROR_BUCKET_REFILL_PER_SEC)
+    b.lastRefillMs = now
+  }
+  if (b.tokens < 1) return true
+  b.tokens -= 1
+  return false
+}
+
+export function handleUploadModel(req, res, uploadHandler) {
+  const _tok = process.env.EDITOR_TOKEN
+  if (_tok && !timingSafeTokenEqual(req.headers['x-editor-token'], _tok)) { res.writeHead(403); res.end('forbidden'); return }
+  uploadHandler(req, res)
+}
+
+export function handleDebugLog(req, res) {
+  // gated: loopback origin is always allowed (local dev console passthrough); a non-loopback
+  // origin must present a valid X-Editor-Token when EDITOR_TOKEN is configured, and is refused
+  // outright when it isn't (an unset EDITOR_TOKEN must not leave this endpoint open to the world).
+  const _remote = req.socket?.remoteAddress || ''
+  const _isLoopback = _remote === '127.0.0.1' || _remote === '::1' || _remote === '::ffff:127.0.0.1'
+  if (!_isLoopback) {
+    const _tok = process.env.EDITOR_TOKEN
+    if (!_tok || !timingSafeTokenEqual(req.headers['x-editor-token'], _tok)) { res.writeHead(403); res.end('forbidden'); return }
+  }
+  // token-bucket rate limit per-IP: caps sustained lines/sec even from an already-authorized origin
+  if (debugLogRateLimited(_remote)) { res.writeHead(429); res.end('rate limited'); return }
+  // size-capped: unbounded body buffering here let any origin exhaust server memory
+  const _DEBUG_LOG_MAX = 256 * 1024
+  let _len = 0, _over = false
+  const chunks = []
+  req.on('data', d => {
+    if (_over) return
+    _len += d.length
+    if (_len > _DEBUG_LOG_MAX) { _over = true; res.writeHead(413); res.end('payload too large'); req.destroy(); return }
+    chunks.push(d)
+  })
+  req.on('end', () => { if (_over) return; try { const d = JSON.parse(Buffer.concat(chunks).toString()); console.log('[browser]', ...d) } catch(_) {}; res.writeHead(200); res.end() })
+}
+
+export function handleClientError(req, res) {
+  // PUBLIC, opt-in-only-on-the-CLIENT-side endpoint (client/core/ErrorTelemetry.js) --
+  // unlike /debug-log and /upload-model above, this is intentionally reachable from any
+  // real deployed player, not loopback/EDITOR_TOKEN-gated, since the whole point is to
+  // hear from crashes on machines the operator has no console access to. The gate here is
+  // purely anti-abuse (rate limit + size cap), not an identity/auth check -- the payload
+  // itself carries no PII by construction (see ErrorTelemetry.js's schema comment).
+  const _remote = req.socket?.remoteAddress || ''
+  if (clientErrorRateLimited(_remote)) { res.writeHead(429); res.end('rate limited'); return }
+  const _CLIENT_ERROR_MAX = 16 * 1024 // payload is a small structured JSON object, not a log dump
+  let _len = 0, _over = false
+  const chunks = []
+  req.on('data', d => {
+    if (_over) return
+    _len += d.length
+    if (_len > _CLIENT_ERROR_MAX) { _over = true; res.writeHead(413); res.end('payload too large'); req.destroy(); return }
+    chunks.push(d)
+  })
+  req.on('end', () => {
+    if (_over) return
+    try {
+      const report = JSON.parse(Buffer.concat(chunks).toString())
+      // Structured, one-line-per-report console surface (an operator greps/aggregates
+      // this today; a real dashboard/store is explicitly out of scope for this first
+      // slice -- see the sibling PRD row filed for that). kind/message/stack/url/ua/ts
+      // are the ErrorTelemetry.js schema fields; renderControls/deviceTier are attached
+      // objects, logged inline so `console.log`'s default object formatting keeps them
+      // inspectable rather than flattened into an unreadable string.
+      console.error(`[client-error] ${report.kind || 'error'}: ${String(report.message || '').slice(0, 500)}`,
+        { url: report.url, ua: report.ua, stack: String(report.stack || '').slice(0, 2000), renderControls: report.renderControls, deviceTier: report.deviceTier, remote: _remote })
+    } catch (_) { /* malformed payload from a hostile/buggy client -- drop silently, still 200 so sendBeacon doesn't retry-storm */ }
+    res.writeHead(200); res.end()
+  })
+}
+
+export function handleDebugServer(req, res, ctx) {
+  // loopback-only: leaks tick/player/entity/session counts + process memory internals
+  const remote = req.socket?.remoteAddress || ''
+  if (remote !== '127.0.0.1' && remote !== '::1' && remote !== '::ffff:127.0.0.1') { res.writeHead(403); res.end('forbidden'); return }
+  const { tickSystem, playerManager, appRuntime, connections, sessions } = ctx
+  const data = JSON.stringify({
+    tick: tickSystem.currentTick,
+    tickRate: ctx.tickRate,
+    players: playerManager.getPlayerCount(),
+    entities: appRuntime.entities.size,
+    connections: connections.getAllStats(),
+    sessions: sessions.getActiveCount(),
+    heap: process.memoryUsage()
+  })
+  res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(data)
+}
+
+export function handleMetrics(req, res, ctx) {
+  // server-scale-prometheus-metrics-endpoint-dashboard: same loopback-only gate as /debug/server
+  // immediately above -- this leaks the identical class of operational internals (tick/player/
+  // entity counts, process memory), just reformatted for Prometheus scrape instead of a one-shot
+  // JSON GET. A Prometheus server itself is expected to run co-located (or reached via an
+  // operator-controlled reverse-proxy/tunnel that terminates on loopback), matching how every
+  // other loopback-gated route in this file is already meant to be consumed.
+  const remote = req.socket?.remoteAddress || ''
+  if (remote !== '127.0.0.1' && remote !== '::1' && remote !== '::ffff:127.0.0.1') { res.writeHead(403); res.end('forbidden'); return }
+  const { tickSystem, playerManager, appRuntime, sessions } = ctx
+  const body = renderMetrics({
+    tick: tickSystem.currentTick,
+    tickRate: ctx.tickRate,
+    players: playerManager.getPlayerCount(),
+    entities: appRuntime.entities.size,
+    sessionCount: sessions.getActiveCount(),
+    uptimeSec: process.uptime(),
+    memoryUsage: () => process.memoryUsage(),
+    // TickHandler.js's onTick.getMetrics() -- see ctx.tickHandlerFn (server.js/WorkerEntry.js
+    // setTickHandler), a stable alias reload-swappable handlerState.fn is mirrored onto so this
+    // route never reaches into reload-internal plumbing directly. Absent (fresh boot before the
+    // first tick, or a handler build that predates this alias) degrades to no tickTiming section
+    // rather than throwing -- /metrics must stay a safe, always-200 operational surface.
+    tickTiming: typeof ctx.tickHandlerFn?.getMetrics === 'function' ? ctx.tickHandlerFn.getMetrics() : null,
+    // RoomDirectory (src/sdk/RoomDirectory.js) is a standalone, opt-in multi-room primitive not
+    // constructed by every boot path -- its own getStatus() doc comment already names this route
+    // as its intended consumer, so a caller that DOES wire one up onto ctx.roomDirectory gets
+    // per-room rows for free with zero further ServerAPI.js changes; every other boot path simply
+    // omits the rooms section (Array.isArray guard in renderMetrics).
+    rooms: typeof ctx.roomDirectory?.getStatus === 'function' ? ctx.roomDirectory.getStatus() : undefined,
+  })
+  res.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' }); res.end(body)
+}
+
+export function handleBenchmark(req, res, ctx) {
+  // Public benchmark endpoint (see PRD rows ugc-platform + ugc-public-benchmark-dashboard):
+  // exposes standardized server performance data as JSON with CORS headers so a static HTML
+  // dashboard page (client/benchmark.html) can consume it from any origin. Deliberately UN-gated
+  // (no loopback/EDITOR_TOKEN check) -- this is a public brag surface, not an operational secret.
+  // The data shape is deliberately high-level (tick stats, player counts, memory, build info) and
+  // carries zero PII, internal IPs, auth tokens, or player-identifying data.
+  try {
+    const data = collectBenchmark(ctx)
+    const json = JSON.stringify(data)
+    res.writeHead(200, {
+      'Content-Type': 'application/json',
+      'Cache-Control': 'no-cache',
+      'Access-Control-Allow-Origin': '*',
+    })
+    res.end(json)
+  } catch (err) {
+    res.writeHead(500, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'benchmark collection failed', detail: err.message }))
+  }
+}
+
+export function handleFreddieViz(req, res, appRuntime) {
+  // FreddieBridge viz endpoint: accepts FreddieBridge messages (JSON), validates them,
+  // and creates/updates/destroys entities in the live world. EDITOR_TOKEN-gated when
+  // configured (same discipline as /upload-model above); an unset EDITOR_TOKEN leaves
+  // this endpoint open (dev default). Rate-limited by body size for safety.
+  const _tok = process.env.EDITOR_TOKEN
+  if (_tok && !timingSafeTokenEqual(req.headers['x-editor-token'], _tok)) { res.writeHead(403); res.end('forbidden'); return }
+  const _FREDDIE_MAX = 256 * 1024
+  let _len = 0, _over = false
+  const chunks = []
+  req.on('data', d => {
+    if (_over) return
+    _len += d.length
+    if (_len > _FREDDIE_MAX) { _over = true; res.writeHead(413); res.end('payload too large'); req.destroy(); return }
+    chunks.push(d)
+  })
+  req.on('end', () => {
+    if (_over) return
+    let body
+    try { body = JSON.parse(Buffer.concat(chunks).toString()) } catch (_) { res.writeHead(400, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'invalid JSON' })); return }
+    // Accept a single message or an array of messages
+    const messages = Array.isArray(body) ? body : [body]
+    const results = []
+    for (const msg of messages) {
+      const v = validateMessage(msg)
+      if (!v.valid) { results.push({ id: msg.id, ok: false, error: 'validation failed', detail: v.errors }); continue }
+      try {
+        if (msg.kind === KIND_PLACE) {
+          const p = msg.payload
+          const entityId = p.entityId
+          // Remove existing entity with same id if present (idempotent place)
+          if (appRuntime.entities.has(entityId)) appRuntime.destroyEntity(entityId)
+          const cfg = {
+            position: p.position || [0, 0, 0],
+            scale: p.scale || [1, 1, 1],
+            custom: {
+              mesh: p.primitive || 'box',
+              color: p.color ?? 0xffffff,
+              emissive: p.emissive ?? 0x000000,
+              opacity: p.opacity ?? 1,
+              label: p.label || null,
+              _freddieSource: msg.source,
+              _freddieId: entityId,
+            },
+            config: {},
+          }
+          if (p.primitive === 'model' && p.model) cfg.model = p.model
+          appRuntime.spawnEntity(entityId, cfg)
+          results.push({ id: msg.id, ok: true, entityId })
+        } else if (msg.kind === KIND_UPDATE) {
+          const p = msg.payload
+          const e = appRuntime.entities.get(p.entityId)
+          if (!e) { results.push({ id: msg.id, ok: false, error: 'entity not found', entityId: p.entityId }); continue }
+          if (p.position) e.position = [...p.position]
+          if (p.scale) e.scale = [...p.scale]
+          if (e.custom) {
+            if (p.color !== undefined) e.custom.color = p.color
+            if (p.emissive !== undefined) e.custom.emissive = p.emissive
+            if (p.opacity !== undefined) e.custom.opacity = p.opacity
+            if (p.label !== undefined) e.custom.label = p.label
+          }
+          results.push({ id: msg.id, ok: true, entityId: p.entityId })
+        } else if (msg.kind === KIND_REMOVE) {
+          appRuntime.destroyEntity(msg.payload.entityId)
+          results.push({ id: msg.id, ok: true, entityId: msg.payload.entityId })
+        } else if (msg.kind === KIND_CLEAR) {
+          // Remove all entities created by this source
+          const source = msg.source
+          const toRemove = []
+          for (const [id, e] of appRuntime.entities) {
+            if (e.custom?._freddieSource === source) toRemove.push(id)
+          }
+          for (const id of toRemove) appRuntime.destroyEntity(id)
+          results.push({ id: msg.id, ok: true, removed: toRemove.length })
+        } else {
+          results.push({ id: msg.id, ok: false, error: `unhandled kind: ${msg.kind}` })
+        }
+      } catch (e) {
+        results.push({ id: msg.id, ok: false, error: e.message })
+      }
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify(Array.isArray(body) ? results : results[0]))
+  })
+}