refactor: xstate TickSystem + document xstate preference in CLAUDE.md

- TickSystem: replace running/_reloadLocked booleans with xstate machine
  (stopped→running→paused). pauseForReload/resumeAfterReload use actor.send.
- CLAUDE.md: add xstate preference section documenting when to use xstate
  vs boolean, import patterns (Node/browser/isomorphic), and complete list
  of all 7 xstate-backed systems in the codebase.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lanmower

CLAUDE.md

@@ -368,6 +368,36 @@ After 3 consecutive reload failures, module stops auto-reloading until server re
 
 ---
 
+## xstate Preference
+
+**All state machines in this codebase MUST use xstate.** Any component with 3+ states or non-trivial transitions must use `createMachine`/`createActor` from xstate v5.
+
+### When to use xstate
+- 3+ distinct states with defined transitions
+- States that guard against invalid transitions (e.g., can't RESUME from running)
+- Reconnection/retry logic with backoff
+- UI mode switching (editor gizmo, XR teleport)
+- Per-instance state tracking (reload manager per-module actors)
+
+### When a boolean is sufficient
+- Single on/off flag with no transition logic (e.g., `connected = true/false`)
+- Re-entrancy guard (`_inProgress` protecting a synchronous block)
+- Simple toggle with no guards
+
+### Import pattern
+- **Node.js (server):** `import { createMachine, createActor } from 'xstate'`
+- **Browser (client):** `import { createMachine, createActor } from '/node_modules/xstate/dist/xstate.esm.js'`
+- **Isomorphic (shared):** `const _isNode = typeof process !== 'undefined' && process.versions?.node; const { createMachine, createActor } = await import(_isNode ? 'xstate' : '/node_modules/xstate/dist/xstate.esm.js')`
+
+### xstate-backed systems
+- **App lifecycle** (`apps/_lib/lifecycle.js`): idle→setting_up→ready→error→destroyed
+- **Animation locomotion** (`client/AnimationStateMachine.js`): IdleLoop/WalkLoop/JogFwdLoop/SprintLoop/CrouchIdleLoop/CrouchFwdLoop/JumpLoop/JumpLand/Death
+- **Reconnect** (`src/client/ReconnectManager.js`): idle→connected→waiting→reconnecting→destroyed
+- **Hot reload** (`src/sdk/ReloadManager.js`): per-module watching→debouncing→reloading→disabled
+- **Editor gizmo** (`client/EditorMachine.js`): translate/rotate/scale with drag sub-states
+- **XR teleport fade** (`client/XRWidgets.js`): idle→fadeIn→delay→fadeOut
+- **Tick system** (`src/netcode/TickSystem.js`): stopped→running→paused
+
 ## Misc Engine Details
 
 - **WORLD_DEF strips entities**: `ServerHandlers.onClientConnect()` removes the `entities` array before sending `MSG.WORLD_DEF`. Pattern: `const { entities: _ignored, ...worldDefForClient } = ctx.currentWorldDef`.

src/netcode/TickSystem.js

@@ -1,23 +1,37 @@
+import { createMachine, createActor } from 'xstate'
+
+const machine = createMachine({
+  id: 'tick',
+  initial: 'stopped',
+  states: {
+    stopped: { on: { START: 'running' } },
+    running: { on: { STOP: 'stopped', PAUSE: 'paused' } },
+    paused: { on: { RESUME: 'running', STOP: 'stopped' } }
+  }
+})
+
 export class TickSystem {
   constructor(tickRate = 128) {
     this.tickRate = tickRate
     this.tickDuration = 1000 / tickRate
     this.currentTick = 0
     this.lastTickTime = 0
     this.callbacks = []
-    this.running = false
-    this._reloadLocked = false
+    this._actor = createActor(machine)
+    this._actor.start()
     this._reloadResolve = null
     this._tickInProgress = false
   }
 
+  get running() { return this._actor.getSnapshot().value === 'running' }
+
   onTick(callback) {
     this.callbacks.push(callback)
   }
 
   start() {
     if (this.running) return
-    this.running = true
+    this._actor.send({ type: 'START' })
     this.lastTickTime = Date.now()
     this.loop()
   }
@@ -28,7 +42,8 @@ export class TickSystem {
     let elapsed = now - this.lastTickTime
     let steps = 0
     const maxSteps = 4
-    while (elapsed >= this.tickDuration && !this._reloadLocked && steps < maxSteps) {
+    const isPaused = this._actor.getSnapshot().value === 'paused'
+    while (elapsed >= this.tickDuration && !isPaused && steps < maxSteps) {
       this._tickInProgress = true
       this.currentTick++
       this.lastTickTime += this.tickDuration
@@ -52,17 +67,17 @@ export class TickSystem {
   }
 
   pauseForReload() {
-    this._reloadLocked = true
+    this._actor.send({ type: 'PAUSE' })
     if (!this._tickInProgress) return Promise.resolve()
     return new Promise(resolve => { this._reloadResolve = resolve })
   }
 
   resumeAfterReload() {
-    this._reloadLocked = false
+    this._actor.send({ type: 'RESUME' })
   }
 
   stop() {
-    this.running = false
+    this._actor.send({ type: 'STOP' })
   }
 
   getTick() {