spoint 0.1.665 → 0.1.667

package/package.json

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

package/src/apps/AppRuntime.js

@@ -4,18 +4,6 @@ import { EventBus } from './EventBus.js'
 import { createEcsEntityMap } from './EcsEntityMap.js'
 import { mulQuat, rotVec } from '../math.js'
 import { MSG } from '../protocol/MessageTypes.js'
-let _existsSync = null, _resolve = null, _realpathSync = null, _sep = '/'
-try { if (typeof process !== 'undefined' && process.versions?.node) { const fs = await import('node:fs'); const path = await import('node:path'); _existsSync = fs.existsSync; _resolve = path.resolve; _realpathSync = fs.realpathSync; _sep = path.sep } } catch {}
-
-function containedAssetPath(filePath, rootDir) {
-  if (!_realpathSync || !rootDir) return null
-  let rootReal
-  try { rootReal = _realpathSync(rootDir) } catch { return null }
-  const prefix = rootReal.endsWith(_sep) ? rootReal : rootReal + _sep
-  let real
-  try { real = _realpathSync(filePath) } catch { return null }
-  return (real === rootReal || real.startsWith(prefix)) ? real : null
-}
 import { SpatialIndex } from '../spatial/Octree.js'
 import { vecOK } from '../shared/vecGuard.js'
 import { weaponNameToCode } from '../shared/WeaponCodes.js'
@@ -24,58 +12,7 @@ import { mixinTick } from './AppRuntimeTick.js'
 import { installCustomVersion } from './CustomVersion.js'
 import { resolveCCD } from './AppPhysics.js'
 
-// tps-game-ctx-state-buffs-not-iterable: ctx.state (entity._appState) is app-owned internal state, and
-// several shipped apps (apps/tps-game/index.js's buffs/invuln/respawning/ammo/reloading/lastEmoteAt/
-// fallTimers/killStreaks/powerups/playerStats, all constructed as `new Map()` in setup()) store real
-// Map/Set instances in it. A naive `JSON.parse(JSON.stringify(appState))` -- the discipline
-// snapshotGameState/restoreGameState already used for entity.custom, which genuinely IS meant to be
-// plain-JSON/editor-facing -- silently downgrades any Map to `{}` (JSON.stringify(new Map()) is "{}",
-// there is no Map wire type) and any Set to `{}` too. Both restoreGameState (in-process rollback +
-// hot-reload, see rollback-entity-gamestate-snapshot) and WorldPersistence.js's on-disk restart-survival
-// save/restore round-trip appState through this exact path, so EVERY app whose ctx.state holds a Map
-// silently loses it on the next resimulate/restore -- e.g. `for (const [pid,buff] of ctx.state.buffs)`
-// throwing "ctx.state.buffs is not iterable" the next time update() runs after a restore, since
-// ctx.state.buffs is now a plain object, not a Map. Fixed at the root (not per-app defensive guards,
-// which only patch the ONE field a given app happened to notice broke) via a tagged Map/Set-preserving
-// pair, used ONLY for appState (custom stays plain JSON -- editor/wire-format contract, must not
-// silently start carrying non-JSON-safe tags).
-//
-// IMPORTANT split, found live via the WorldPersistence.js on-disk path: snapshotGameState's OWN output
-// must stay a plain-JSON-safe TAGGED shape (never a live Map/Set instance), not a fully round-tripped-
-// back-to-Map value -- WorldPersistence.buildWorldSnapshot takes snapshotGameState's entities verbatim
-// and hands them straight to storage.set (FSAdapter.set does its own unguarded JSON.stringify(value)
-// with no replacer of its own), so a live Map sitting in that structure gets silently flattened to `{}`
-// a SECOND time on the way to disk, exactly reproducing the original bug one level downstream. Tagging
-// at snapshot time (tagAppState) and reviving only at actual restore time (untagAppState, called from
-// restoreGameState) keeps the snapshot object plain-JSON-safe everywhere in between, correct for both
-// the in-process rollback consumer (never itself re-serializes the snapshot) and the on-disk consumer
-// (storage.set's plain JSON.stringify is now a no-op on an already-plain-JSON tree).
-function tagAppState(state) {
-  if (!state) return null
-  const replacer = (key, value) => {
-    if (value instanceof Map) return { __type: 'Map', entries: [...value.entries()] }
-    if (value instanceof Set) return { __type: 'Set', values: [...value.values()] }
-    return value
-  }
-  return JSON.parse(JSON.stringify(state, replacer))
-}
-// Reviving on the way in tolerates EITHER a tagged plain-JSON shape (the normal case: freshly tagged by
-// tagAppState above, or read back off disk after a real storage.get/JSON.parse round trip) OR a
-// snapshot taken BEFORE this fix existed (on-disk, from an old process -- has plain `{}` where a Map
-// used to be, no tag at all) -- reviving that degrades to a plain object, not a fabricated Map, which is
-// the correct honest-degrade behavior for old data rather than a hard requirement on snapshot shape.
-function untagAppState(state) {
-  if (!state) return null
-  const reviver = (key, value) => {
-    if (value && typeof value === 'object' && value.__type === 'Map' && Array.isArray(value.entries)) return new Map(value.entries)
-    if (value && typeof value === 'object' && value.__type === 'Set' && Array.isArray(value.values)) return new Set(value.values)
-    return value
-  }
-  // state may already be a plain-JSON tree (tagAppState's own output, or a fresh JSON.parse off disk) --
-  // stringify-then-parse-with-reviver is the simplest way to apply the reviver uniformly to every nested
-  // level without hand-walking the tree twice for the two different possible input shapes.
-  return JSON.parse(JSON.stringify(state), reviver)
-}
+import { containedAssetPath, tagAppState, untagAppState, _existsSync, _resolve } from './AppRuntimeState.js'
 
 export class AppRuntime {
   constructor(c = {}) {

package/src/apps/AppRuntimeState.js

@@ -0,0 +1,75 @@
+// Stateless entity/app-state helpers for AppRuntime.js: sandboxed asset-path containment check and the
+// Map/Set-preserving tag/untag pair for ctx.state (app-owned internal state that may hold live Map/Set
+// instances -- see tagAppState's own comment for why the naive JSON round-trip snapshotGameState/
+// restoreGameState uses for entity.custom silently drops them). Split out as AppRuntime.js's only
+// pure-function block -- everything else in that file is an AppRuntime instance method reading `this.*`.
+// Node fs/path handles are resolved here too (containedAssetPath needs realpathSync/sep); AppRuntime.js
+// imports the SAME resolved handles for its own resolveAssetPath rather than re-resolving them.
+
+let _existsSync = null, _resolve = null, _realpathSync = null, _sep = '/'
+try { if (typeof process !== 'undefined' && process.versions?.node) { const fs = await import('node:fs'); const path = await import('node:path'); _existsSync = fs.existsSync; _resolve = path.resolve; _realpathSync = fs.realpathSync; _sep = path.sep } } catch {}
+
+function containedAssetPath(filePath, rootDir) {
+  if (!_realpathSync || !rootDir) return null
+  let rootReal
+  try { rootReal = _realpathSync(rootDir) } catch { return null }
+  const prefix = rootReal.endsWith(_sep) ? rootReal : rootReal + _sep
+  let real
+  try { real = _realpathSync(filePath) } catch { return null }
+  return (real === rootReal || real.startsWith(prefix)) ? real : null
+}
+
+// tps-game-ctx-state-buffs-not-iterable: ctx.state (entity._appState) is app-owned internal state, and
+// several shipped apps (apps/tps-game/index.js's buffs/invuln/respawning/ammo/reloading/lastEmoteAt/
+// fallTimers/killStreaks/powerups/playerStats, all constructed as `new Map()` in setup()) store real
+// Map/Set instances in it. A naive `JSON.parse(JSON.stringify(appState))` -- the discipline
+// snapshotGameState/restoreGameState already used for entity.custom, which genuinely IS meant to be
+// plain-JSON/editor-facing -- silently downgrades any Map to `{}` (JSON.stringify(new Map()) is "{}",
+// there is no Map wire type) and any Set to `{}` too. Both restoreGameState (in-process rollback +
+// hot-reload, see rollback-entity-gamestate-snapshot) and WorldPersistence.js's on-disk restart-survival
+// save/restore round-trip appState through this exact path, so EVERY app whose ctx.state holds a Map
+// silently loses it on the next resimulate/restore -- e.g. `for (const [pid,buff] of ctx.state.buffs)`
+// throwing "ctx.state.buffs is not iterable" the next time update() runs after a restore, since
+// ctx.state.buffs is now a plain object, not a Map. Fixed at the root (not per-app defensive guards,
+// which only patch the ONE field a given app happened to notice broke) via a tagged Map/Set-preserving
+// pair, used ONLY for appState (custom stays plain JSON -- editor/wire-format contract, must not
+// silently start carrying non-JSON-safe tags).
+//
+// IMPORTANT split, found live via the WorldPersistence.js on-disk path: snapshotGameState's OWN output
+// must stay a plain-JSON-safe TAGGED shape (never a live Map/Set instance), not a fully round-tripped-
+// back-to-Map value -- WorldPersistence.buildWorldSnapshot takes snapshotGameState's entities verbatim
+// and hands them straight to storage.set (FSAdapter.set does its own unguarded JSON.stringify(value)
+// with no replacer of its own), so a live Map sitting in that structure gets silently flattened to `{}`
+// a SECOND time on the way to disk, exactly reproducing the original bug one level downstream. Tagging
+// at snapshot time (tagAppState) and reviving only at actual restore time (untagAppState, called from
+// restoreGameState) keeps the snapshot object plain-JSON-safe everywhere in between, correct for both
+// the in-process rollback consumer (never itself re-serializes the snapshot) and the on-disk consumer
+// (storage.set's plain JSON.stringify is now a no-op on an already-plain-JSON tree).
+function tagAppState(state) {
+  if (!state) return null
+  const replacer = (key, value) => {
+    if (value instanceof Map) return { __type: 'Map', entries: [...value.entries()] }
+    if (value instanceof Set) return { __type: 'Set', values: [...value.values()] }
+    return value
+  }
+  return JSON.parse(JSON.stringify(state, replacer))
+}
+// Reviving on the way in tolerates EITHER a tagged plain-JSON shape (the normal case: freshly tagged by
+// tagAppState above, or read back off disk after a real storage.get/JSON.parse round trip) OR a
+// snapshot taken BEFORE this fix existed (on-disk, from an old process -- has plain `{}` where a Map
+// used to be, no tag at all) -- reviving that degrades to a plain object, not a fabricated Map, which is
+// the correct honest-degrade behavior for old data rather than a hard requirement on snapshot shape.
+function untagAppState(state) {
+  if (!state) return null
+  const reviver = (key, value) => {
+    if (value && typeof value === 'object' && value.__type === 'Map' && Array.isArray(value.entries)) return new Map(value.entries)
+    if (value && typeof value === 'object' && value.__type === 'Set' && Array.isArray(value.values)) return new Set(value.values)
+    return value
+  }
+  // state may already be a plain-JSON tree (tagAppState's own output, or a fresh JSON.parse off disk) --
+  // stringify-then-parse-with-reviver is the simplest way to apply the reviver uniformly to every nested
+  // level without hand-walking the tree twice for the two different possible input shapes.
+  return JSON.parse(JSON.stringify(state), reviver)
+}
+
+export { containedAssetPath, tagAppState, untagAppState, _existsSync, _resolve, _realpathSync, _sep }

package/src/sdk/EditorHandlers.js

@@ -4,6 +4,7 @@ import { BIOME_PRESETS } from '../terrain/BiomeOverride.js'
 import { createGrassDecal } from '../terrain/GrassDecal.js'
 import { createEditOpLog } from './EditOpLog.js'
 import { createAgentEditServer } from './AgentEditServer.js'
+import { TEXT_EXTS, isTextFile, sanitizeFsError, WORLD_CONFIG_KEYS, serializeEntity, serializeWorld, serializeWorldSource } from './EditorHandlersSerialize.js'
 
 const isNode = typeof process !== 'undefined' && process.versions?.node
 let _fs = null, _path = null, _bakeMinimapIfMissing = null
@@ -46,25 +47,8 @@ const statSync = _fs?.statSync, mkdirSync = _fs?.mkdirSync
 const realpathSync = _fs?.realpathSync
 const unlinkSync = _fs?.unlinkSync, renameSync = _fs?.renameSync, rmSync = _fs?.rmSync
 
-// Extensions read/written as text by the fs-browse panel; anything else is reported binary (size-only, no decode).
-const TEXT_EXTS = new Set(['.js', '.mjs', '.json', '.md', '.txt', '.css', '.html', '.yml', '.yaml', '.svg'])
-function isTextFile(name) {
-  const i = name.lastIndexOf('.')
-  return i >= 0 && TEXT_EXTS.has(name.slice(i).toLowerCase())
-}
 const resolvePath = _path?.resolve || (() => ''), joinPath = _path?.join || (() => ''), dirnamePath = _path?.dirname || (() => ''), pathSep = _path?.sep || '/'
 
-// Node's raw fs error messages embed the server's ABSOLUTE filesystem path (e.g. "ENOENT: ...,
-// mkdir 'C:\dev\spoint\apps\...'" or a null-byte TypeError quoting the full resolved path) -- sending
-// that verbatim to an editor client leaks server directory layout to whatever authored the request.
-// Found live via an adversarial VERIFY-phase sweep (null-byte path, overlong-path ENOENT) against the
-// real server: both errors round-tripped with the absolute apps-root path intact. Strip it down to the
-// operation-relevant leaf (Node error CODE + the client-relative path already known from payload.path)
-// so the client still gets an actionable reason without the server's real directory structure.
-function sanitizeFsError(e, clientRelativePath) {
-  const code = e && e.code ? e.code : (e && e.name) || 'ERROR'
-  return `${code}: operation failed on '${clientRelativePath}'`
-}
 
 // realpath-based containment check: a symlink inside rootDir could otherwise point outside it and let an editor client read/write arbitrary server files
 function containedReal(filePath, rootDir) {
@@ -117,43 +101,6 @@ function containedRealCreateParent(filePath, rootDir) {
   return joinPath(ancestorReal, ...missingSuffix, filePath.slice(dir.length + pathSep.length))
 }
 
-const WORLD_CONFIG_KEYS = ['port', 'tickRate', 'entityTickRate', 'gravity', 'relevanceRadius', 'physicsRadius', 'physicsBodyBudget', 'movement', 'player', 'scene', 'camera', 'animation', 'input', 'spawnPoint', 'spawnPoints', 'playerModel', 'trustedApps']
-
-function serializeEntity(e) {
-  const out = { id: e.id }
-  if (e.model) out.model = e.model
-  out.position = [e.position[0], e.position[1], e.position[2]]
-  const r = e.rotation
-  if (r && !(r[0] === 0 && r[1] === 0 && r[2] === 0 && r[3] === 1)) out.rotation = [r[0], r[1], r[2], r[3]]
-  const s = e.scale
-  if (s && !(s[0] === 1 && s[1] === 1 && s[2] === 1)) out.scale = [s[0], s[1], s[2]]
-  if (e._appName) out.app = e._appName
-  if (e.bodyType && e.bodyType !== 'static') out.bodyType = e.bodyType
-  if (e._config) out.config = e._config
-  if (e.custom) out.custom = e.custom
-  if (e.parent) out.parent = e.parent
-  return out
-}
-
-function serializeWorld(appRuntime, sourceWorldDef) {
-  const def = {}
-  const src = sourceWorldDef || {}
-  for (const k of WORLD_CONFIG_KEYS) if (src[k] !== undefined) def[k] = src[k]
-  const entities = []
-  for (const e of appRuntime.entities.values()) {
-    // Keep any entity carrying authored state: an app, a model, custom props (incl. a primitive's mesh/editorProp
-    // edits), a saved app config, OR a hierarchy parent (a reparented empty anchor). The old filter dropped an
-    // entity that had only a _config or only a parent, silently losing that authoring on save.
-    if (!e._appName && !e.model && !e.custom && !e._config && !e.parent) continue
-    entities.push(serializeEntity(e))
-  }
-  def.entities = entities
-  return def
-}
-
-function serializeWorldSource(def) {
-  return JSON.stringify(def, null, 2)
-}
 
 // In-memory prefab registry, best-effort mirrored to data/prefabs.json when a real filesystem is available
 // (Node server), inert (memory-only, cleared on restart) under the Worker/singleplayer runtime -- mirrors

package/src/sdk/EditorHandlersSerialize.js

@@ -0,0 +1,62 @@
+// Pure entity/world serialization + text-file-extension helpers for EditorHandlers.js's
+// createEditorHandlers: no fs/path dependency, no closure state -- split out as the one genuinely
+// self-contained block in this file (containedReal/containedRealCreateParent/prefab-persistence all
+// depend on the Node-vs-Worker fs handle dance at this file's own top, and stay there).
+
+const TEXT_EXTS = new Set(['.js', '.mjs', '.json', '.md', '.txt', '.css', '.html', '.yml', '.yaml', '.svg'])
+function isTextFile(name) {
+  const i = name.lastIndexOf('.')
+  return i >= 0 && TEXT_EXTS.has(name.slice(i).toLowerCase())
+}
+
+// Node's raw fs error messages embed the server's ABSOLUTE filesystem path (e.g. "ENOENT: ...,
+// mkdir 'C:\dev\spoint\apps\...'" or a null-byte TypeError quoting the full resolved path) -- sending
+// that verbatim to an editor client leaks server directory layout to whatever authored the request.
+// Found live via an adversarial VERIFY-phase sweep (null-byte path, overlong-path ENOENT) against the
+// real server: both errors round-tripped with the absolute apps-root path intact. Strip it down to the
+// operation-relevant leaf (Node error CODE + the client-relative path already known from payload.path)
+// so the client still gets an actionable reason without the server's real directory structure.
+function sanitizeFsError(e, clientRelativePath) {
+  const code = e && e.code ? e.code : (e && e.name) || 'ERROR'
+  return `${code}: operation failed on '${clientRelativePath}'`
+}
+
+const WORLD_CONFIG_KEYS = ['port', 'tickRate', 'entityTickRate', 'gravity', 'relevanceRadius', 'physicsRadius', 'physicsBodyBudget', 'movement', 'player', 'scene', 'camera', 'animation', 'input', 'spawnPoint', 'spawnPoints', 'playerModel', 'trustedApps']
+
+function serializeEntity(e) {
+  const out = { id: e.id }
+  if (e.model) out.model = e.model
+  out.position = [e.position[0], e.position[1], e.position[2]]
+  const r = e.rotation
+  if (r && !(r[0] === 0 && r[1] === 0 && r[2] === 0 && r[3] === 1)) out.rotation = [r[0], r[1], r[2], r[3]]
+  const s = e.scale
+  if (s && !(s[0] === 1 && s[1] === 1 && s[2] === 1)) out.scale = [s[0], s[1], s[2]]
+  if (e._appName) out.app = e._appName
+  if (e.bodyType && e.bodyType !== 'static') out.bodyType = e.bodyType
+  if (e._config) out.config = e._config
+  if (e.custom) out.custom = e.custom
+  if (e.parent) out.parent = e.parent
+  return out
+}
+
+function serializeWorld(appRuntime, sourceWorldDef) {
+  const def = {}
+  const src = sourceWorldDef || {}
+  for (const k of WORLD_CONFIG_KEYS) if (src[k] !== undefined) def[k] = src[k]
+  const entities = []
+  for (const e of appRuntime.entities.values()) {
+    // Keep any entity carrying authored state: an app, a model, custom props (incl. a primitive's mesh/editorProp
+    // edits), a saved app config, OR a hierarchy parent (a reparented empty anchor). The old filter dropped an
+    // entity that had only a _config or only a parent, silently losing that authoring on save.
+    if (!e._appName && !e.model && !e.custom && !e._config && !e.parent) continue
+    entities.push(serializeEntity(e))
+  }
+  def.entities = entities
+  return def
+}
+
+function serializeWorldSource(def) {
+  return JSON.stringify(def, null, 2)
+}
+
+export { TEXT_EXTS, isTextFile, sanitizeFsError, WORLD_CONFIG_KEYS, serializeEntity, serializeWorld, serializeWorldSource }