spoint 0.1.661 → 0.1.663

package/client/core/Vegetation.js

@@ -1,41 +1,6 @@
 // Client visual layer for the ez-tree forest. Reads the SAME deterministic placement as the server (VegPlacement.js) so the visual trunk matches the collided trunk. Per species: one InstancedMesh2 for branches + one for leaves, 3 mesh LODs + a cheap shadow LOD + BVH per-instance frustum culling. window.__veg / window.__vegProfile.
 import * as THREE from 'three'
 import { InstancedMesh2 } from '@three.ez/instanced-mesh'
-import { MeshoptSimplifier } from 'meshoptimizer'
-// '@dgreenheck/ez-tree' is intentionally NOT a static import here (was: `import { Tree } from
-// '@dgreenheck/ez-tree'`). A static top-level import is resolved during ES module GRAPH LINKING,
-// before any module body executes -- a 404/missing-package on this one import poisons the ENTIRE
-// graph rooted at app.js (app.js statically imports Vegetation.js), aborting client boot with zero
-// console output, even from systems that textually import before this one and would otherwise have
-// succeeded (confirmed live: a module-graph reproduction with this exact static-import shape showed
-// sibling static imports before the failing one never evaluate either -- graph linking is atomic,
-// see eztree-fix-live-reproduce-and-verify PRD row for the harness + output).
-// Root cause of the underlying absence: single-writer contention on the shared main checkout's
-// node_modules directory when multiple concurrent worktree sessions run npm-install-adjacent
-// operations against the SAME junction target at once (see scripts/worktree-setup.mjs and
-// AGENTS.md's main-node-modules-missing-ez-tree-package-intermittent history) -- this can still
-// transiently 404 under contention even after worktree-setup.mjs's own torn-install guard, since a
-// junction always resolves LIVE to whatever main's node_modules currently contains at request time.
-// A dynamic import, awaited once and cached, keeps the failure LOCAL to createVegetation() (which
-// already has a per-species try/catch and whose own caller in app.js already .catch()es) instead of
-// poisoning module linking -- the rest of the client (terrain, physics, HUD, netcode, other apps)
-// boots fine and only vegetation degrades to "skipped" with a clear console warning.
-// RESIDUAL RISK (not fully eliminated by this fix): a package going missing/corrupt AFTER this
-// dynamic import has already resolved once per page load (e.g. torn mid-way through THIS page's own
-// boot) is not retried -- the cached rejection/resolution is final for that page session's lifetime,
-// matching how a static import would behave too (a page load either gets a working module graph or
-// it doesn't; there is no live hot-swap of an already-linked/already-resolved import). The dynamic
-// import only prevents the SPECIFIC failure mode of "vegetation being unavailable" from cascading
-// into "nothing at all is available" -- it does not make ez-tree loading retry-resilient within a
-// single page load, and it does nothing for any OTHER package that is statically imported elsewhere
-// in the graph (this fix is scoped to ez-tree, the one package this task's report named; a fully
-// general fix would need every client entry-adjacent static import audited the same way, which is a
-// larger cross-cutting change than this task's reported symptom asked for).
-let _ezTreeModPromise = null
-function loadEzTree() {
-  if (!_ezTreeModPromise) _ezTreeModPromise = import('@dgreenheck/ez-tree')
-  return _ezTreeModPromise
-}
 // streaming-gltf's octahedral impostor (FULL-sphere octahedron - works from any angle, incl ground
 // level; the agargaro vendored lib only implemented HEMI so ground views rendered nothing). Plain
 // Single canonical impostor implementation (packages/streaming-gltf/src/octahedral-impostor-ez.js,
@@ -48,179 +13,17 @@ import { createCachedAnchorField } from '/src/terrain/ClimateCache.js'
 import { createBiomeOverride } from '/src/terrain/BiomeOverride.js'
 import { dbg } from './debug-log.js'
 import { RenderControls } from './RenderControls.js'
+import { loadEzTree, makeWindUniforms, applyWind, awaitMatTextures, capGeo, simplifyGeo, buildSpecies, makeEmptyGeo, TARGET_H } from './VegetationBuild.js'
 
 const _dbgVeg = dbg('vegetation')
 const _occBoxGeo = new THREE.BoxGeometry(1, 1, 1)   // shared, never-rendered proxy geo for occlusion candidates
 const _occBoxMat = new THREE.MeshBasicMaterial()
 
-// species (parity wire-id contract) -> ez-tree preset names; 'Bush' has no exact preset (lib ships 'Bush 1/2/3'), mapped explicitly so a missing preset never silently diverges from the collider table
-const PRESET = {
-  'Oak Large': 'Oak Large', 'Pine Medium': 'Pine Medium', 'Aspen Medium': 'Aspen Medium', 'Ash Medium': 'Ash Medium', 'Bush': 'Bush 1',
-  'Ash Small': 'Ash Small', 'Ash Large': 'Ash Large', 'Aspen Small': 'Aspen Small', 'Aspen Large': 'Aspen Large', 'Bush 2': 'Bush 2',
-  'Bush 3': 'Bush 3', 'Oak Small': 'Oak Small', 'Oak Medium': 'Oak Medium', 'Pine Small': 'Pine Small', 'Pine Large': 'Pine Large',
-}
-
-// target real-world full-tree height (m) per species: ez-tree's native ~100-unit scale mismatches the trunk collider table, LOD cutovers, and impostor size; normalizing makes visual==collider==LOD==impostor size
-const TARGET_H = {
-  'Oak Large': 9, 'Pine Medium': 12, 'Aspen Medium': 9.5, 'Ash Medium': 10, 'Bush': 2.8,
-  'Ash Small': 6.5, 'Ash Large': 13, 'Aspen Small': 6, 'Aspen Large': 13, 'Bush 2': 3.0,
-  'Bush 3': 3.2, 'Oak Small': 5.5, 'Oak Medium': 7, 'Pine Small': 8, 'Pine Large': 16,
-}
-
 const DROP_MARGIN = 64   // metres past the ring before a chunk is dropped (hysteresis)
 
 const _v = new THREE.Vector3(), _q = new THREE.Quaternion(), _camPos = new THREE.Vector3()
 const _vanMat = new THREE.Matrix4(), _vanProj = new THREE.Matrix4(), _vanFrustum = new THREE.Frustum()   // scratch for window.__vegVanishProbe
 
-// shared wind uniform (one per veg system); advancing one .value per frame sways all LODs of all species with zero per-instance JS
-function makeWindUniforms() { return { uVegTime: { value: 0 }, uVegWind: { value: 1 } } }
-
-function _dissolveBoundaryDistanceShaderChunk(boundaries) {
-  const uniforms = boundaries.map((_, i) => `uniform float uVegLodB${i};`).join('\n')
-  const mindist = boundaries.map((_, i) => `_vegDistToB = min(_vegDistToB, abs(_vegCamDist - uVegLodB${i}));`).join('\n      ')
-  return { uniforms, mindist }
-}
-
-const VEG_DISSOLVE_FADE_BAND_M = 3.0
-
-function applyWind(material, wind, lodBoundaries) {
-  const chunk = lodBoundaries && lodBoundaries.length ? _dissolveBoundaryDistanceShaderChunk(lodBoundaries) : null
-  material.onBeforeCompile = (shader) => {
-    shader.uniforms.uVegTime = wind.uVegTime
-    shader.uniforms.uVegWind = wind.uVegWind
-    shader.vertexShader = 'uniform float uVegTime;\nuniform float uVegWind;\n' + shader.vertexShader
-    // windPhase/tint are per-instance uniforms @three.ez declares; its injection runs after this base
-    shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>',
-      '#include <begin_vertex>\n' +
-      'float _wsway = (position.y) * 0.06;\n' +
-      'float _wph = uVegTime * 1.3 + windPhase;\n' +
-      'transformed.x += sin(_wph) * _wsway * uVegWind;\n' +
-      'transformed.z += cos(_wph * 0.8) * _wsway * 0.6 * uVegWind;')
-    // per-instance shade: multiply the lit diffuse by the instance tint (brightness variation).
-    shader.fragmentShader = shader.fragmentShader.replace('#include <color_fragment>',
-      '#include <color_fragment>\n diffuseColor.rgb *= tint;')
-    if (chunk) {
-      lodBoundaries.forEach((d, i) => { shader.uniforms['uVegLodB' + i] = { value: d } })
-      shader.vertexShader = chunk.uniforms + '\nvarying float vVegCamDist;\n' + shader.vertexShader
-      shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>',
-        '#include <begin_vertex>\nvVegCamDist = distance(cameraPosition, (modelMatrix * instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0)).xyz);')
-      shader.fragmentShader = chunk.uniforms + '\nvarying float vVegCamDist;\n' + shader.fragmentShader
-      shader.fragmentShader = shader.fragmentShader.replace('#include <dithering_fragment>',
-        '#include <dithering_fragment>\n' +
-        `float _vegCamDist = vVegCamDist;\n` +
-        `float _vegDistToB = 1e9;\n` +
-        `      ${chunk.mindist}\n` +
-        `float _vegFade = clamp(_vegDistToB / ${VEG_DISSOLVE_FADE_BAND_M.toFixed(1)}, 0.0, 1.0);\n` +
-        'float _vegDither = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));\n' +
-        'if (_vegDither > _vegFade) discard;')
-    }
-  }
-  material.customProgramCacheKey = () => 'vegwind3' + (chunk ? '_fade' + lodBoundaries.join('_') : '')
-  return material
-}
-
-// Must await texture decode before sampling: ez-tree loads bark/leaf maps async, so baking the impostor atlas in the same tick would sample undefined images -> blank atlas.
-async function awaitMatTextures(mats) {
-  const texes = []
-  for (const m of mats) {
-    if (!m) continue
-    for (const k of ['map', 'normalMap', 'roughnessMap', 'aoMap', 'alphaMap', 'bumpMap']) {
-      const t = m[k]; if (t && t.isTexture) texes.push(t)
-    }
-  }
-  await Promise.all(texes.map(async (t) => {
-    const img = t.image
-    try {
-      if (img && typeof img.decode === 'function') { await img.decode(); t.needsUpdate = true; return }
-    } catch (_) {}
-    // fallback: poll until the image has dimensions, ~1s cap
-    for (let i = 0; i < 60; i++) {
-      if (t.image && (t.image.width > 0 || t.image.videoWidth > 0)) { t.needsUpdate = true; return }
-      await new Promise(r => setTimeout(r, 16))
-    }
-  }))
-}
-
-// Caps a geometry to at most maxTris triangles (meshopt); the LOD0 budget bounding the worst near-tree.
-async function capGeo(geo, maxTris) {
-  try {
-    const idx = geo.index ? geo.index.array : null
-    if (!idx) return geo
-    const tris = idx.length / 3
-    if (tris <= maxTris) return geo
-    return await simplifyGeo(geo, maxTris / tris, false)
-  } catch (_) { return geo }
-}
-
-// Meshopt-simplifies to `ratio` of triangles. Must ALWAYS return a NEW distinct geometry object (never the source) -- @three.ez's addLevel reuses the LOD object when geometry===existing, so two LOD levels sharing one object alias one instanceIndex array and stomp each other's drawn slots (a tree vanishing in a band at the cutover).
-async function simplifyGeo(geo, ratio, sloppy) {
-  try {
-    await MeshoptSimplifier.ready
-    const idx = geo.index ? geo.index.array : null
-    const pos = geo.attributes.position.array
-    if (!idx || !pos) return geo.clone()
-    const target = Math.max(12, Math.floor((idx.length / 3) * ratio) * 3)
-    const fn = sloppy && MeshoptSimplifier.simplifySloppy ? 'simplifySloppy' : 'simplify'
-    const args = sloppy ? [idx, pos, 3, target, 0.05] : [idx, pos, 3, target, 0.02, ['Sparse']]
-    const [newIdx] = MeshoptSimplifier[fn](...args)
-    const out = geo.clone()
-    if (newIdx && newIdx.length >= 3) out.setIndex(new THREE.BufferAttribute(newIdx, 1))
-    return out
-  } catch (_) { return geo.clone() }
-}
-
-function buildSpecies(name, Tree) {
-  const tree = new Tree()
-  tree.loadPreset(PRESET[name] || name)
-  const branchGeo = tree.branchesMesh.geometry
-  const leafGeo = tree.leavesMesh.geometry
-  const branchMat = tree.branchesMesh.material
-  const leafMat = tree.leavesMesh.material
-  branchMat.shadowSide = THREE.FrontSide
-  leafMat.alphaTest = Math.max(leafMat.alphaTest || 0, 0.5)   // no-MSAA fallback (A2C needs samples)
-  leafMat.transparent = false
-  leafMat.side = THREE.DoubleSide
-  // Apply depth bias to mesh LOD to match impostor bias, preventing flicker at LOD boundary.
-  // units -8 -> -32 (2026-07-10, live A/B via GL readPixels flicker-score harness against a real
-  // close-range trunk, world ~3-8m from camera): -8 was proven LIVE-INSUFFICIENT -- trunk mesh vs
-  // mapspinner's independently-rendered terrain depth z-fight every single frame at that range
-  // (strict alternation between trunk color and terrain color on 18-23 of 20-24 sampled frames),
-  // even though occlusion/LOD-swap/per-instance-visibility were all confirmed INERT for this exact
-  // symptom (occludedKeys.size===0 always, instancesCount constant, getVisibilityAt always true --
-  // the flicker is a raw GPU depth-test tie-break flip, not a game-logic visibility toggle). A/B
-  // tested -20/-50/-100 all fully eliminated it (0/20 frames changed, vs 18/20 baseline); -32 keeps
-  // a safety margin above the smallest working value without over-biasing.
-  branchMat.polygonOffset = true
-  branchMat.polygonOffsetFactor = -4
-  branchMat.polygonOffsetUnits = -32
-  leafMat.polygonOffset = true
-  leafMat.polygonOffsetFactor = -4
-  leafMat.polygonOffsetUnits = -32
-  // normalize to a real-world height: scale branch+leaf by the same factor so visual size agrees with the trunk collider + LOD + impostor
-  branchGeo.computeBoundingBox(); leafGeo.computeBoundingBox()
-  const minY = Math.min(branchGeo.boundingBox.min.y, leafGeo.boundingBox.min.y)
-  const maxY = Math.max(branchGeo.boundingBox.max.y, leafGeo.boundingBox.max.y)
-  const nativeH = maxY - minY
-  const target = TARGET_H[name] || 9
-  const s = (Number.isFinite(nativeH) && nativeH > 1e-3) ? target / nativeH : 1
-  for (const g of [branchGeo, leafGeo]) {
-    g.scale(s, s, s)
-    g.translate(0, -minY * s, 0)   // drop base to y=0 so the trunk rests on the ground
-    g.computeBoundingBox(); g.computeBoundingSphere()
-  }
-  const bb = branchGeo.boundingBox, lb = leafGeo.boundingBox
-  const width = Math.max(bb.max.x - bb.min.x, bb.max.z - bb.min.z, lb.max.x - lb.min.x, lb.max.z - lb.min.z) || target * 0.7
-  const dims = { width, height: target }
-  return { branchGeo, leafGeo, branchMat, leafMat, tree, dims }
-}
-
-// zero-area geo: the far leaf LOD swaps to this so leaf cards vanish where the impostor takes over (no double-draw)
-function makeEmptyGeo() {
-  const g = new THREE.BufferGeometry()
-  g.setAttribute('position', new THREE.BufferAttribute(new Float32Array(9), 3))
-  g.setIndex([0, 1, 2])
-  return g
-}
 
 export async function createVegetation(opts = {}) {
   const { renderer, scene, frame } = opts

package/client/core/VegetationBuild.js

@@ -0,0 +1,206 @@
+// Species-mesh build helpers for Vegetation.js's createVegetation: ez-tree dynamic loader, wind-sway
+// shader injection, texture-decode/geometry-simplify async helpers, and per-species mesh construction
+// (buildSpecies normalizes ez-tree's native scale to this project's real-world TARGET_H per species,
+// applying the polygonOffset trunk-flicker fix -- see that function's own comment). Split out as
+// Vegetation.js's largest stateless block -- each function here only touches its own module-scoped
+// constants/caches (_ezTreeModPromise, PRESET, TARGET_H), never createVegetation's own closure state
+// (camera/chunk/instance scratch objects stay in Vegetation.js, only used there).
+
+import * as THREE from 'three'
+import { MeshoptSimplifier } from 'meshoptimizer'
+
+let _ezTreeModPromise = null
+function loadEzTree() {
+  if (!_ezTreeModPromise) _ezTreeModPromise = import('@dgreenheck/ez-tree')
+  return _ezTreeModPromise
+}
+// streaming-gltf's octahedral impostor (FULL-sphere octahedron - works from any angle, incl ground
+// level; the agargaro vendored lib only implemented HEMI so ground views rendered nothing). Plain
+// Single canonical impostor implementation (packages/streaming-gltf/src/octahedral-impostor-ez.js,
+// shared with ModelPool's OctahedralImpostorEzTier via the same package import elsewhere -- no more
+// client/vendor duplicate, see AGENTS.md draw-call-audit-impostor-system-unification).
+import { createOctahedralImpostorMaterial, computeObjectBoundingSphere } from 'streaming-gltf/octahedral-impostor-ez'  // full-sphere octahedron (works at ground level, unlike hemi-only variants)
+import { buildSharedImpostorAtlas, createSharedImpostorMesh } from './VegImpostorTier.js'
+import { placementsForChunk, VEG, SPECIES } from '/src/terrain/VegPlacement.js'
+import { createCachedAnchorField } from '/src/terrain/ClimateCache.js'
+import { createBiomeOverride } from '/src/terrain/BiomeOverride.js'
+import { dbg } from './debug-log.js'
+import { RenderControls } from './RenderControls.js'
+
+const _dbgVeg = dbg('vegetation')
+const _occBoxGeo = new THREE.BoxGeometry(1, 1, 1)   // shared, never-rendered proxy geo for occlusion candidates
+const _occBoxMat = new THREE.MeshBasicMaterial()
+
+// species (parity wire-id contract) -> ez-tree preset names; 'Bush' has no exact preset (lib ships 'Bush 1/2/3'), mapped explicitly so a missing preset never silently diverges from the collider table
+const PRESET = {
+  'Oak Large': 'Oak Large', 'Pine Medium': 'Pine Medium', 'Aspen Medium': 'Aspen Medium', 'Ash Medium': 'Ash Medium', 'Bush': 'Bush 1',
+  'Ash Small': 'Ash Small', 'Ash Large': 'Ash Large', 'Aspen Small': 'Aspen Small', 'Aspen Large': 'Aspen Large', 'Bush 2': 'Bush 2',
+  'Bush 3': 'Bush 3', 'Oak Small': 'Oak Small', 'Oak Medium': 'Oak Medium', 'Pine Small': 'Pine Small', 'Pine Large': 'Pine Large',
+}
+
+// target real-world full-tree height (m) per species: ez-tree's native ~100-unit scale mismatches the trunk collider table, LOD cutovers, and impostor size; normalizing makes visual==collider==LOD==impostor size
+const TARGET_H = {
+  'Oak Large': 9, 'Pine Medium': 12, 'Aspen Medium': 9.5, 'Ash Medium': 10, 'Bush': 2.8,
+  'Ash Small': 6.5, 'Ash Large': 13, 'Aspen Small': 6, 'Aspen Large': 13, 'Bush 2': 3.0,
+  'Bush 3': 3.2, 'Oak Small': 5.5, 'Oak Medium': 7, 'Pine Small': 8, 'Pine Large': 16,
+}
+
+const DROP_MARGIN = 64   // metres past the ring before a chunk is dropped (hysteresis)
+
+const _v = new THREE.Vector3(), _q = new THREE.Quaternion(), _camPos = new THREE.Vector3()
+const _vanMat = new THREE.Matrix4(), _vanProj = new THREE.Matrix4(), _vanFrustum = new THREE.Frustum()   // scratch for window.__vegVanishProbe
+
+// shared wind uniform (one per veg system); advancing one .value per frame sways all LODs of all species with zero per-instance JS
+function makeWindUniforms() { return { uVegTime: { value: 0 }, uVegWind: { value: 1 } } }
+
+function _dissolveBoundaryDistanceShaderChunk(boundaries) {
+  const uniforms = boundaries.map((_, i) => `uniform float uVegLodB${i};`).join('\n')
+  const mindist = boundaries.map((_, i) => `_vegDistToB = min(_vegDistToB, abs(_vegCamDist - uVegLodB${i}));`).join('\n      ')
+  return { uniforms, mindist }
+}
+
+const VEG_DISSOLVE_FADE_BAND_M = 3.0
+
+function applyWind(material, wind, lodBoundaries) {
+  const chunk = lodBoundaries && lodBoundaries.length ? _dissolveBoundaryDistanceShaderChunk(lodBoundaries) : null
+  material.onBeforeCompile = (shader) => {
+    shader.uniforms.uVegTime = wind.uVegTime
+    shader.uniforms.uVegWind = wind.uVegWind
+    shader.vertexShader = 'uniform float uVegTime;\nuniform float uVegWind;\n' + shader.vertexShader
+    // windPhase/tint are per-instance uniforms @three.ez declares; its injection runs after this base
+    shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>',
+      '#include <begin_vertex>\n' +
+      'float _wsway = (position.y) * 0.06;\n' +
+      'float _wph = uVegTime * 1.3 + windPhase;\n' +
+      'transformed.x += sin(_wph) * _wsway * uVegWind;\n' +
+      'transformed.z += cos(_wph * 0.8) * _wsway * 0.6 * uVegWind;')
+    // per-instance shade: multiply the lit diffuse by the instance tint (brightness variation).
+    shader.fragmentShader = shader.fragmentShader.replace('#include <color_fragment>',
+      '#include <color_fragment>\n diffuseColor.rgb *= tint;')
+    if (chunk) {
+      lodBoundaries.forEach((d, i) => { shader.uniforms['uVegLodB' + i] = { value: d } })
+      shader.vertexShader = chunk.uniforms + '\nvarying float vVegCamDist;\n' + shader.vertexShader
+      shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>',
+        '#include <begin_vertex>\nvVegCamDist = distance(cameraPosition, (modelMatrix * instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0)).xyz);')
+      shader.fragmentShader = chunk.uniforms + '\nvarying float vVegCamDist;\n' + shader.fragmentShader
+      shader.fragmentShader = shader.fragmentShader.replace('#include <dithering_fragment>',
+        '#include <dithering_fragment>\n' +
+        `float _vegCamDist = vVegCamDist;\n` +
+        `float _vegDistToB = 1e9;\n` +
+        `      ${chunk.mindist}\n` +
+        `float _vegFade = clamp(_vegDistToB / ${VEG_DISSOLVE_FADE_BAND_M.toFixed(1)}, 0.0, 1.0);\n` +
+        'float _vegDither = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));\n' +
+        'if (_vegDither > _vegFade) discard;')
+    }
+  }
+  material.customProgramCacheKey = () => 'vegwind3' + (chunk ? '_fade' + lodBoundaries.join('_') : '')
+  return material
+}
+
+// Must await texture decode before sampling: ez-tree loads bark/leaf maps async, so baking the impostor atlas in the same tick would sample undefined images -> blank atlas.
+async function awaitMatTextures(mats) {
+  const texes = []
+  for (const m of mats) {
+    if (!m) continue
+    for (const k of ['map', 'normalMap', 'roughnessMap', 'aoMap', 'alphaMap', 'bumpMap']) {
+      const t = m[k]; if (t && t.isTexture) texes.push(t)
+    }
+  }
+  await Promise.all(texes.map(async (t) => {
+    const img = t.image
+    try {
+      if (img && typeof img.decode === 'function') { await img.decode(); t.needsUpdate = true; return }
+    } catch (_) {}
+    // fallback: poll until the image has dimensions, ~1s cap
+    for (let i = 0; i < 60; i++) {
+      if (t.image && (t.image.width > 0 || t.image.videoWidth > 0)) { t.needsUpdate = true; return }
+      await new Promise(r => setTimeout(r, 16))
+    }
+  }))
+}
+
+// Caps a geometry to at most maxTris triangles (meshopt); the LOD0 budget bounding the worst near-tree.
+async function capGeo(geo, maxTris) {
+  try {
+    const idx = geo.index ? geo.index.array : null
+    if (!idx) return geo
+    const tris = idx.length / 3
+    if (tris <= maxTris) return geo
+    return await simplifyGeo(geo, maxTris / tris, false)
+  } catch (_) { return geo }
+}
+
+// Meshopt-simplifies to `ratio` of triangles. Must ALWAYS return a NEW distinct geometry object (never the source) -- @three.ez's addLevel reuses the LOD object when geometry===existing, so two LOD levels sharing one object alias one instanceIndex array and stomp each other's drawn slots (a tree vanishing in a band at the cutover).
+async function simplifyGeo(geo, ratio, sloppy) {
+  try {
+    await MeshoptSimplifier.ready
+    const idx = geo.index ? geo.index.array : null
+    const pos = geo.attributes.position.array
+    if (!idx || !pos) return geo.clone()
+    const target = Math.max(12, Math.floor((idx.length / 3) * ratio) * 3)
+    const fn = sloppy && MeshoptSimplifier.simplifySloppy ? 'simplifySloppy' : 'simplify'
+    const args = sloppy ? [idx, pos, 3, target, 0.05] : [idx, pos, 3, target, 0.02, ['Sparse']]
+    const [newIdx] = MeshoptSimplifier[fn](...args)
+    const out = geo.clone()
+    if (newIdx && newIdx.length >= 3) out.setIndex(new THREE.BufferAttribute(newIdx, 1))
+    return out
+  } catch (_) { return geo.clone() }
+}
+
+function buildSpecies(name, Tree) {
+  const tree = new Tree()
+  tree.loadPreset(PRESET[name] || name)
+  const branchGeo = tree.branchesMesh.geometry
+  const leafGeo = tree.leavesMesh.geometry
+  const branchMat = tree.branchesMesh.material
+  const leafMat = tree.leavesMesh.material
+  branchMat.shadowSide = THREE.FrontSide
+  leafMat.alphaTest = Math.max(leafMat.alphaTest || 0, 0.5)   // no-MSAA fallback (A2C needs samples)
+  leafMat.transparent = false
+  leafMat.side = THREE.DoubleSide
+  // Apply depth bias to mesh LOD to match impostor bias, preventing flicker at LOD boundary.
+  // units -8 -> -32 (2026-07-10, live A/B via GL readPixels flicker-score harness against a real
+  // close-range trunk, world ~3-8m from camera): -8 was proven LIVE-INSUFFICIENT -- trunk mesh vs
+  // mapspinner's independently-rendered terrain depth z-fight every single frame at that range
+  // (strict alternation between trunk color and terrain color on 18-23 of 20-24 sampled frames),
+  // even though occlusion/LOD-swap/per-instance-visibility were all confirmed INERT for this exact
+  // symptom (occludedKeys.size===0 always, instancesCount constant, getVisibilityAt always true --
+  // the flicker is a raw GPU depth-test tie-break flip, not a game-logic visibility toggle). A/B
+  // tested -20/-50/-100 all fully eliminated it (0/20 frames changed, vs 18/20 baseline); -32 keeps
+  // a safety margin above the smallest working value without over-biasing.
+  branchMat.polygonOffset = true
+  branchMat.polygonOffsetFactor = -4
+  branchMat.polygonOffsetUnits = -32
+  leafMat.polygonOffset = true
+  leafMat.polygonOffsetFactor = -4
+  leafMat.polygonOffsetUnits = -32
+  // normalize to a real-world height: scale branch+leaf by the same factor so visual size agrees with the trunk collider + LOD + impostor
+  branchGeo.computeBoundingBox(); leafGeo.computeBoundingBox()
+  const minY = Math.min(branchGeo.boundingBox.min.y, leafGeo.boundingBox.min.y)
+  const maxY = Math.max(branchGeo.boundingBox.max.y, leafGeo.boundingBox.max.y)
+  const nativeH = maxY - minY
+  const target = TARGET_H[name] || 9
+  const s = (Number.isFinite(nativeH) && nativeH > 1e-3) ? target / nativeH : 1
+  for (const g of [branchGeo, leafGeo]) {
+    g.scale(s, s, s)
+    g.translate(0, -minY * s, 0)   // drop base to y=0 so the trunk rests on the ground
+    g.computeBoundingBox(); g.computeBoundingSphere()
+  }
+  const bb = branchGeo.boundingBox, lb = leafGeo.boundingBox
+  const width = Math.max(bb.max.x - bb.min.x, bb.max.z - bb.min.z, lb.max.x - lb.min.x, lb.max.z - lb.min.z) || target * 0.7
+  const dims = { width, height: target }
+  return { branchGeo, leafGeo, branchMat, leafMat, tree, dims }
+}
+
+// zero-area geo: the far leaf LOD swaps to this so leaf cards vanish where the impostor takes over (no double-draw)
+function makeEmptyGeo() {
+  const g = new THREE.BufferGeometry()
+  g.setAttribute('position', new THREE.BufferAttribute(new Float32Array(9), 3))
+  g.setIndex([0, 1, 2])
+  return g
+}
+
+export {
+  loadEzTree, makeWindUniforms, applyWind, awaitMatTextures, capGeo, simplifyGeo,
+  buildSpecies, makeEmptyGeo, PRESET, TARGET_H, VEG_DISSOLVE_FADE_BAND_M
+}

package/client/editor/EditorShell.js

@@ -10,180 +10,12 @@ import { createEditorEventLog } from './EditorEventLog.js'
 import { createWorldValidator } from './WorldValidator.js'
 import { createWaypointTimeline } from './WaypointTimeline.js'
 import { showToast, setSceneEntityIds } from './EditPanelDOM.js'
-import { fetchAssetManifest, ASSET_HOST } from './AssetManifest.js'
+import { ASSET_HOST } from './AssetManifest.js'
 import { createWindowController } from './wm/WindowController.js'
-import { setSharedWM, promptText } from './wm/ui.js'
+import { setSharedWM } from './wm/ui.js'
+import { ADD_PRIMITIVES, buildAddMenuItems, buildPropCategoryItems, buildCategoryMenuItems, loadRecent, recordRecent, filterMenuItems, promptName, _ensureWmCSS, _ensureEditorResponsiveCSS, TABS, EDITOR_SHORTCUTS } from './EditorShellMenus.js'
 import { MSG } from '/src/protocol/MessageTypes.js'
 
-const ADD_PRIMITIVES = [
-  { id: 'box-static', label: 'Box' },
-  { id: 'sphere-static', label: 'Sphere' },
-  { id: 'capsule-static', label: 'Capsule' },
-  { id: 'cylinder-static', label: 'Cylinder' }
-]
-
-function buildAddMenuItems(place, openPropSubmenu, scatterState) {
-  const scatterLabel = scatterState && scatterState.on
-    ? '✓ Scatter mode (drag to place many)'
-    : 'Scatter mode (drag to place many)'
-  return [
-    ...(scatterState ? [{ label: scatterLabel, onSelect: () => scatterState.toggle() }] : []),
-    { label: 'Prop...', onSelect: () => openPropSubmenu() },
-    ...ADD_PRIMITIVES.map(p => ({ label: p.label, onSelect: () => place(p.id) }))
-  ]
-}
-
-async function buildPropCategoryItems(onOpenCategory) {
-  try {
-    const manifest = await fetchAssetManifest()
-    const cats = Object.keys(manifest).sort()
-    // editor-place-menu-thumbnails: category glyph is a graceful fallback differentiator for the
-    // category-list level (no per-category thumbnail exists in the manifest -- categories are just
-    // string keys grouping models, see AssetManifest.js/manifest.json shape). Real per-MODEL thumb
-    // images (manifest[cat][i].thumb, a live gh-pages-hosted PNG, confirmed present on every entry)
-    // are wired at the model-row level in buildCategoryMenuItems below.
-    return cats.length
-      ? cats.map(cat => ({ label: `${_categoryGlyph(cat)} ${cat} (${(manifest[cat] || []).length})`, onSelect: () => onOpenCategory(cat, manifest[cat] || []) }))
-      : [{ label: '(no props in catalog)', disabled: true }]
-  } catch (e) {
-    return [{ label: 'Catalog error: ' + e.message, disabled: true }]
-  }
-}
-
-// Coarse category->glyph map (text-only fallback differentiator; the manifest has no per-category
-// icon/image field, only per-model `thumb`). Deliberately small and approximate -- any unmatched
-// category still gets the neutral default glyph rather than nothing.
-const _CATEGORY_GLYPHS = [
-  [/kitchen|appliance|fridge|oven|stove|dish/i, '\u{1F373}'],
-  [/bath|shower|toilet|sink/i, '\u{1F6BF}'],
-  [/car|vehicle|truck|van|bus/i, '\u{1F697}'],
-  [/tree|plant|foliage|flower|grass/i, '\u{1F333}'],
-  [/rock|stone|boulder/i, '\u{1FAA8}'],
-  [/chair|couch|sofa|table|desk|furniture|cabinet/i, '\u{1FA91}'],
-  [/light|lamp/i, '\u{1F4A1}'],
-  [/weapon|gun/i, '\u{1F52B}'],
-  [/airport|container|industrial|barrel|dumpster/i, '\u{1F3ED}'],
-  [/office/i, '\u{1F5C4}️']
-]
-function _categoryGlyph(cat) {
-  for (const [re, glyph] of _CATEGORY_GLYPHS) if (re.test(cat)) return glyph
-  return '\u{1F4E6}' // generic package/prop glyph default
-}
-
-function buildCategoryMenuItems(models, onPlaceModel, onBack) {
-  // _thumb carries the real manifest thumbnail URL (or null) through to the post-render DOM
-  // decoration pass in openAddMenu -- ContextMenu's item shape ({label,onSelect,disabled}) has no
-  // documented custom-render/icon hook (see openAddMenu's own comment), so the extra _thumb key
-  // rides along unused by the kit and is read back out by label-text matching after applyDiff.
-  const items = models.map(m => ({ label: m.name, onSelect: () => onPlaceModel(ASSET_HOST + m.path), _thumb: m.thumb ? ASSET_HOST + m.thumb : null }))
-  return [{ label: '< Back', onSelect: onBack }, ...items]
-}
-
-// --- Add-menu recent-items tracking (editor-add-menu-recent) ---------------------------------
-// localStorage-persisted, keyed by asset url (props) or primitive kind ('box-static' etc).
-// Pure functions (recordRecent/loadRecent) so the list/dedupe/cap logic is exec_js-testable
-// independent of any DOM/menu wiring.
-const RECENT_KEY = 'ds-editor-add-menu-recent'
-const RECENT_MAX = 8
-function loadRecent() {
-  try {
-    const raw = localStorage.getItem(RECENT_KEY)
-    const arr = raw ? JSON.parse(raw) : []
-    return Array.isArray(arr) ? arr.filter(r => r && r.key && r.label) : []
-  } catch (_) { return [] }
-}
-function recordRecent(entry, existing) {
-  // entry: {key, label, kind:'primitive'|'prop', value}. Most-recent-first, deduped by key, capped at RECENT_MAX.
-  const list = (existing || loadRecent()).filter(r => r.key !== entry.key)
-  list.unshift(entry)
-  const capped = list.slice(0, RECENT_MAX)
-  try { localStorage.setItem(RECENT_KEY, JSON.stringify(capped)) } catch (_) {}
-  return capped
-}
-
-// --- Add-menu substring filter (editor-add-menu-search) --------------------------------------
-// Pure: filters a flat item list by substring match on label, case-insensitive.
-function filterMenuItems(items, query) {
-  const q = (query || '').trim().toLowerCase()
-  if (!q) return items
-  return items.filter(it => !it.disabled && (it.label || '').toLowerCase().includes(q))
-}
-
-function promptName(wm, { title, label, placeholder, initial = '' } = {}) {
-  return promptText(wm, {
-    title, label, placeholder, initial,
-    validate: (raw) => {
-      const name = raw.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '')
-      return name ? { ok: true, value: name } : { ok: false, error: (label || 'Name') + ' required' }
-    }
-  })
-}
-
-const TABS = ['Inspector', 'Apps', 'HookFlow', 'Events']
-
-const EDITOR_SHORTCUTS = [
-  { combo: 'G / W', scope: 'gizmo', label: 'Translate (move) gizmo' },
-  { combo: 'R / E', scope: 'gizmo', label: 'Rotate gizmo' },
-  // Alt+S not bare S: bare WASDC drives the fly-camera, would collide with a plain letter shortcut.
-  { combo: 'Alt+S', scope: 'gizmo', label: 'Scale gizmo' },
-  { combo: 'F', scope: 'gizmo', label: 'Frame / focus selected entity' },
-  { combo: 'Delete', scope: 'edit', label: 'Delete selected entity' },
-  { combo: 'mod+Z', scope: 'history', label: 'Undo' },
-  { combo: 'mod+Y', scope: 'history', label: 'Redo' },
-  { combo: 'P', scope: 'editor', label: 'Toggle editor' },
-  { combo: 'Alt+C', scope: 'debug', label: 'Toggle collider debug wireframe' },
-  { combo: 'M', scope: 'nav', label: 'Open lobby' },
-  { combo: 'X', scope: 'gizmo', label: 'Toggle snap-to-grid' },
-  { combo: 'Y', scope: 'gizmo', label: 'Toggle gizmo space (world / local)' },
-  { combo: 'Alt+P', scope: 'gizmo', label: 'Cycle multi-select pivot mode (active / centroid / individual)' },
-  { combo: 'Alt+1..9', scope: 'camera', label: 'Recall camera bookmark N' },
-  { combo: 'Ctrl+Alt+1..9', scope: 'camera', label: 'Save camera bookmark N' },
-  { combo: 'Shift/Ctrl+click', scope: 'select', label: 'Add or remove an entity from multi-select' },
-  { combo: 'Shift/Ctrl+drag (empty space)', scope: 'select', label: 'Marquee box-select entities in view' },
-  { combo: 'Ctrl+drag Y-axis', scope: 'gizmo', label: 'Snap-to-surface while moving (raycasts down, grid-snap off)' },
-  { combo: 'mod+C', scope: 'edit', label: 'Copy selected entity (transform + custom props)' },
-  { combo: 'mod+V', scope: 'edit', label: 'Paste onto the currently-selected entity' },
-  { combo: 'Arrow keys', scope: 'gizmo', label: 'Nudge selected entity on X/Z (grid step or 0.25)' },
-  { combo: 'PageUp / PageDown', scope: 'gizmo', label: 'Nudge selected entity on Y' },
-  { combo: '?', scope: 'editor', label: 'Toggle this shortcuts cheat-sheet' }
-]
-
-let _wmCssInjected = false
-function _ensureWmCSS() {
-  if (_wmCssInjected) return
-  _wmCssInjected = true
-  // Absolute server path, not import.meta.url-relative: import.meta.url of a bundled
-  // app.js resolves to the bundle's own URL (not this source file's real location),
-  // which would silently mis-resolve these hrefs to /wm/*.css instead of
-  // /editor/wm/*.css once client/app.js is bundled by scripts/bundle-client.mjs. The
-  // editor/ directory is a fixed, server-mounted path (client/editor/wm/*.css), so an
-  // absolute reference is both bundling-safe and simpler than a relative one.
-  for (const href of ['/editor/wm/os-token-bridge.css', '/editor/wm/wm.css']) {
-    const l = document.createElement('link')
-    l.rel = 'stylesheet'
-    l.href = href
-    document.head.appendChild(l)
-  }
-}
-
-let _editorRespInjected = false
-function _ensureEditorResponsiveCSS() {
-  if (_editorRespInjected) return
-  _editorRespInjected = true
-  const style = document.createElement('style')
-  style.id = 'ds-editor-responsive'
-  style.textContent = [
-    '.ep-overlay .app-main{padding:0!important}',
-    '.ep-overlay .app,.ep-overlay .app-shell{height:100%}',
-    '.ep-overlay .app-main>*{flex:1;min-height:0}',
-    '.ep-overlay .ds-ep-toolbar{flex-wrap:wrap;row-gap:4px;column-gap:6px}',
-    '@media (pointer:coarse){.ep-overlay .ds-ep-tab,.ep-overlay .ds-ep-toolbar button,.ep-overlay .wm-btn,.ep-overlay .ds-ep-tree-row{min-height:44px}}',
-    '.ds-ep-history-row:hover{background:var(--panel-2,rgba(255,255,255,0.06))}',
-    '.ds-ep-history-row.current:hover{background:var(--accent-bg,rgba(80,160,255,0.24))}'
-  ].join('\n')
-  document.head.appendChild(style)
-}
-
 export function createEditPanel({ onPlace, onPlaceModel, onSave, onSaveWorld, onListWorlds, onGizmoModeChange, onGizmoSpaceChange, onPivotModeChange, onEntitySelect, onGetSource, onGetAppFiles, onDestroyEntity, onCreateApp, onSnapChange, onEventLogQuery, onReparent, onRename, onDuplicate, onLockChange, onHiddenChange, onScatterArm, onAlign, onDistribute, onGroup, isSingleplayer, onFsListTree, onFsGetSource, onFsSave, onFsMkdir, onFsDelete, onFsRename, onJumpToHistory, onAddWaypoint, onReorderWaypoints, onToggleMinimapOverlay, onWireCreate, floatingOrigin, onEdgeRemove, onPlaceBatch, onPlaytestStart, onPlaytestStop, onCommandPalette, onDebugModeChange, onOpenP2PRoom, onOpenFreddieChat } = {}) {
   const overlay = document.createElement('div')
   overlay.className = 'ds-247420 ep-overlay'

package/client/editor/EditorShellMenus.js

@@ -0,0 +1,183 @@
+// Add-menu / prop-category / recent-items / shortcuts-cheatsheet helpers for EditorShell.js's
+// createEditPanel: stateless (module-level RECENT_KEY/RECENT_MAX localStorage cache aside) menu-item
+// builders, name-prompt validation, and one-time CSS injection. Split out as EditorShell.js's largest
+// self-contained block -- none of these touch createEditPanel's own closure state, only their own
+// params/module-level caches/constants.
+
+import { ASSET_HOST, fetchAssetManifest } from './AssetManifest.js'
+import { promptText } from './wm/ui.js'
+
+const ADD_PRIMITIVES = [
+  { id: 'box-static', label: 'Box' },
+  { id: 'sphere-static', label: 'Sphere' },
+  { id: 'capsule-static', label: 'Capsule' },
+  { id: 'cylinder-static', label: 'Cylinder' }
+]
+
+function buildAddMenuItems(place, openPropSubmenu, scatterState) {
+  const scatterLabel = scatterState && scatterState.on
+    ? '✓ Scatter mode (drag to place many)'
+    : 'Scatter mode (drag to place many)'
+  return [
+    ...(scatterState ? [{ label: scatterLabel, onSelect: () => scatterState.toggle() }] : []),
+    { label: 'Prop...', onSelect: () => openPropSubmenu() },
+    ...ADD_PRIMITIVES.map(p => ({ label: p.label, onSelect: () => place(p.id) }))
+  ]
+}
+
+async function buildPropCategoryItems(onOpenCategory) {
+  try {
+    const manifest = await fetchAssetManifest()
+    const cats = Object.keys(manifest).sort()
+    // editor-place-menu-thumbnails: category glyph is a graceful fallback differentiator for the
+    // category-list level (no per-category thumbnail exists in the manifest -- categories are just
+    // string keys grouping models, see AssetManifest.js/manifest.json shape). Real per-MODEL thumb
+    // images (manifest[cat][i].thumb, a live gh-pages-hosted PNG, confirmed present on every entry)
+    // are wired at the model-row level in buildCategoryMenuItems below.
+    return cats.length
+      ? cats.map(cat => ({ label: `${_categoryGlyph(cat)} ${cat} (${(manifest[cat] || []).length})`, onSelect: () => onOpenCategory(cat, manifest[cat] || []) }))
+      : [{ label: '(no props in catalog)', disabled: true }]
+  } catch (e) {
+    return [{ label: 'Catalog error: ' + e.message, disabled: true }]
+  }
+}
+
+// Coarse category->glyph map (text-only fallback differentiator; the manifest has no per-category
+// icon/image field, only per-model `thumb`). Deliberately small and approximate -- any unmatched
+// category still gets the neutral default glyph rather than nothing.
+const _CATEGORY_GLYPHS = [
+  [/kitchen|appliance|fridge|oven|stove|dish/i, '\u{1F373}'],
+  [/bath|shower|toilet|sink/i, '\u{1F6BF}'],
+  [/car|vehicle|truck|van|bus/i, '\u{1F697}'],
+  [/tree|plant|foliage|flower|grass/i, '\u{1F333}'],
+  [/rock|stone|boulder/i, '\u{1FAA8}'],
+  [/chair|couch|sofa|table|desk|furniture|cabinet/i, '\u{1FA91}'],
+  [/light|lamp/i, '\u{1F4A1}'],
+  [/weapon|gun/i, '\u{1F52B}'],
+  [/airport|container|industrial|barrel|dumpster/i, '\u{1F3ED}'],
+  [/office/i, '\u{1F5C4}️']
+]
+function _categoryGlyph(cat) {
+  for (const [re, glyph] of _CATEGORY_GLYPHS) if (re.test(cat)) return glyph
+  return '\u{1F4E6}' // generic package/prop glyph default
+}
+
+function buildCategoryMenuItems(models, onPlaceModel, onBack) {
+  // _thumb carries the real manifest thumbnail URL (or null) through to the post-render DOM
+  // decoration pass in openAddMenu -- ContextMenu's item shape ({label,onSelect,disabled}) has no
+  // documented custom-render/icon hook (see openAddMenu's own comment), so the extra _thumb key
+  // rides along unused by the kit and is read back out by label-text matching after applyDiff.
+  const items = models.map(m => ({ label: m.name, onSelect: () => onPlaceModel(ASSET_HOST + m.path), _thumb: m.thumb ? ASSET_HOST + m.thumb : null }))
+  return [{ label: '< Back', onSelect: onBack }, ...items]
+}
+
+// --- Add-menu recent-items tracking (editor-add-menu-recent) ---------------------------------
+// localStorage-persisted, keyed by asset url (props) or primitive kind ('box-static' etc).
+// Pure functions (recordRecent/loadRecent) so the list/dedupe/cap logic is exec_js-testable
+// independent of any DOM/menu wiring.
+const RECENT_KEY = 'ds-editor-add-menu-recent'
+const RECENT_MAX = 8
+function loadRecent() {
+  try {
+    const raw = localStorage.getItem(RECENT_KEY)
+    const arr = raw ? JSON.parse(raw) : []
+    return Array.isArray(arr) ? arr.filter(r => r && r.key && r.label) : []
+  } catch (_) { return [] }
+}
+function recordRecent(entry, existing) {
+  // entry: {key, label, kind:'primitive'|'prop', value}. Most-recent-first, deduped by key, capped at RECENT_MAX.
+  const list = (existing || loadRecent()).filter(r => r.key !== entry.key)
+  list.unshift(entry)
+  const capped = list.slice(0, RECENT_MAX)
+  try { localStorage.setItem(RECENT_KEY, JSON.stringify(capped)) } catch (_) {}
+  return capped
+}
+
+// --- Add-menu substring filter (editor-add-menu-search) --------------------------------------
+// Pure: filters a flat item list by substring match on label, case-insensitive.
+function filterMenuItems(items, query) {
+  const q = (query || '').trim().toLowerCase()
+  if (!q) return items
+  return items.filter(it => !it.disabled && (it.label || '').toLowerCase().includes(q))
+}
+
+function promptName(wm, { title, label, placeholder, initial = '' } = {}) {
+  return promptText(wm, {
+    title, label, placeholder, initial,
+    validate: (raw) => {
+      const name = raw.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '')
+      return name ? { ok: true, value: name } : { ok: false, error: (label || 'Name') + ' required' }
+    }
+  })
+}
+
+const TABS = ['Inspector', 'Apps', 'HookFlow', 'Events']
+
+const EDITOR_SHORTCUTS = [
+  { combo: 'G / W', scope: 'gizmo', label: 'Translate (move) gizmo' },
+  { combo: 'R / E', scope: 'gizmo', label: 'Rotate gizmo' },
+  // Alt+S not bare S: bare WASDC drives the fly-camera, would collide with a plain letter shortcut.
+  { combo: 'Alt+S', scope: 'gizmo', label: 'Scale gizmo' },
+  { combo: 'F', scope: 'gizmo', label: 'Frame / focus selected entity' },
+  { combo: 'Delete', scope: 'edit', label: 'Delete selected entity' },
+  { combo: 'mod+Z', scope: 'history', label: 'Undo' },
+  { combo: 'mod+Y', scope: 'history', label: 'Redo' },
+  { combo: 'P', scope: 'editor', label: 'Toggle editor' },
+  { combo: 'Alt+C', scope: 'debug', label: 'Toggle collider debug wireframe' },
+  { combo: 'M', scope: 'nav', label: 'Open lobby' },
+  { combo: 'X', scope: 'gizmo', label: 'Toggle snap-to-grid' },
+  { combo: 'Y', scope: 'gizmo', label: 'Toggle gizmo space (world / local)' },
+  { combo: 'Alt+P', scope: 'gizmo', label: 'Cycle multi-select pivot mode (active / centroid / individual)' },
+  { combo: 'Alt+1..9', scope: 'camera', label: 'Recall camera bookmark N' },
+  { combo: 'Ctrl+Alt+1..9', scope: 'camera', label: 'Save camera bookmark N' },
+  { combo: 'Shift/Ctrl+click', scope: 'select', label: 'Add or remove an entity from multi-select' },
+  { combo: 'Shift/Ctrl+drag (empty space)', scope: 'select', label: 'Marquee box-select entities in view' },
+  { combo: 'Ctrl+drag Y-axis', scope: 'gizmo', label: 'Snap-to-surface while moving (raycasts down, grid-snap off)' },
+  { combo: 'mod+C', scope: 'edit', label: 'Copy selected entity (transform + custom props)' },
+  { combo: 'mod+V', scope: 'edit', label: 'Paste onto the currently-selected entity' },
+  { combo: 'Arrow keys', scope: 'gizmo', label: 'Nudge selected entity on X/Z (grid step or 0.25)' },
+  { combo: 'PageUp / PageDown', scope: 'gizmo', label: 'Nudge selected entity on Y' },
+  { combo: '?', scope: 'editor', label: 'Toggle this shortcuts cheat-sheet' }
+]
+
+let _wmCssInjected = false
+function _ensureWmCSS() {
+  if (_wmCssInjected) return
+  _wmCssInjected = true
+  // Absolute server path, not import.meta.url-relative: import.meta.url of a bundled
+  // app.js resolves to the bundle's own URL (not this source file's real location),
+  // which would silently mis-resolve these hrefs to /wm/*.css instead of
+  // /editor/wm/*.css once client/app.js is bundled by scripts/bundle-client.mjs. The
+  // editor/ directory is a fixed, server-mounted path (client/editor/wm/*.css), so an
+  // absolute reference is both bundling-safe and simpler than a relative one.
+  for (const href of ['/editor/wm/os-token-bridge.css', '/editor/wm/wm.css']) {
+    const l = document.createElement('link')
+    l.rel = 'stylesheet'
+    l.href = href
+    document.head.appendChild(l)
+  }
+}
+
+let _editorRespInjected = false
+function _ensureEditorResponsiveCSS() {
+  if (_editorRespInjected) return
+  _editorRespInjected = true
+  const style = document.createElement('style')
+  style.id = 'ds-editor-responsive'
+  style.textContent = [
+    '.ep-overlay .app-main{padding:0!important}',
+    '.ep-overlay .app,.ep-overlay .app-shell{height:100%}',
+    '.ep-overlay .app-main>*{flex:1;min-height:0}',
+    '.ep-overlay .ds-ep-toolbar{flex-wrap:wrap;row-gap:4px;column-gap:6px}',
+    '@media (pointer:coarse){.ep-overlay .ds-ep-tab,.ep-overlay .ds-ep-toolbar button,.ep-overlay .wm-btn,.ep-overlay .ds-ep-tree-row{min-height:44px}}',
+    '.ds-ep-history-row:hover{background:var(--panel-2,rgba(255,255,255,0.06))}',
+    '.ds-ep-history-row.current:hover{background:var(--accent-bg,rgba(80,160,255,0.24))}'
+  ].join('\n')
+  document.head.appendChild(style)
+}
+
+export {
+  ADD_PRIMITIVES, buildAddMenuItems, buildPropCategoryItems, buildCategoryMenuItems,
+  loadRecent, recordRecent, filterMenuItems, promptName,
+  _ensureWmCSS, _ensureEditorResponsiveCSS, TABS, EDITOR_SHORTCUTS
+}

package/package.json

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