@lanmower/entrypoint 0.16.0

package/src/client/PhysicsNetworkClient.js

@@ -0,0 +1,171 @@
+import { PredictionEngine } from './PredictionEngine.js'
+import { pack, unpack } from '../protocol/msgpack.js'
+import { MSG } from '../protocol/MessageTypes.js'
+
+export class PhysicsNetworkClient {
+  constructor(config = {}) {
+    this.config = { url: config.url || 'ws://localhost:8080/ws', tickRate: config.tickRate || 128, predictionEnabled: config.predictionEnabled !== false, debug: config.debug || false, ...config }
+    this.ws = null
+    this.playerId = null
+    this.connected = false
+    this._predEngine = null
+    this._playerStates = new Map()
+    this._entityStates = new Map()
+    this.lastSnapshotTick = 0
+    this.currentTick = 0
+    this.state = { players: [], entities: [] }
+    this.heartbeatTimer = null
+    this.callbacks = {
+      onConnect: config.onConnect || (() => {}),
+      onDisconnect: config.onDisconnect || (() => {}),
+      onPlayerJoined: config.onPlayerJoined || (() => {}),
+      onPlayerLeft: config.onPlayerLeft || (() => {}),
+      onEntityAdded: config.onEntityAdded || (() => {}),
+      onEntityRemoved: config.onEntityRemoved || (() => {}),
+      onSnapshot: config.onSnapshot || (() => {}),
+      onRender: config.onRender || (() => {}),
+      onStateUpdate: config.onStateUpdate || (() => {}),
+      onWorldDef: config.onWorldDef || (() => {}),
+      onAppModule: config.onAppModule || (() => {}),
+      onAssetUpdate: config.onAssetUpdate || (() => {}),
+      onAppEvent: config.onAppEvent || (() => {})
+    }
+  }
+
+  async connect() {
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.config.url)
+        this.ws.binaryType = 'arraybuffer'
+        this.ws.onopen = () => this._onOpen(resolve)
+        this.ws.onmessage = (event) => this.onMessage(event.data)
+        this.ws.onclose = () => this._onClose()
+        this.ws.onerror = (error) => this._onError(error, reject)
+      } catch (error) { reject(error) }
+    })
+  }
+
+  _onOpen(resolve) {
+    this.connected = true
+    this._startHeartbeat()
+    this.callbacks.onConnect()
+    resolve()
+  }
+
+  _onClose() {
+    this.connected = false
+    this._stopHeartbeat()
+    this.callbacks.onDisconnect()
+  }
+
+  _onError(error, reject) { reject(error) }
+
+  sendInput(input) {
+    if (!this._isOpen()) return
+    if (this.config.predictionEnabled && this._predEngine) this._predEngine.addInput(input)
+    this.ws.send(pack({ type: MSG.INPUT, payload: { input } }))
+  }
+
+  sendFire(data) {
+    if (!this._isOpen()) return
+    this.ws.send(pack({ type: MSG.APP_EVENT, payload: { type: 'fire', shooterId: this.playerId, ...data } }))
+  }
+
+  _isOpen() { return this.ws && this.ws.readyState === WebSocket.OPEN }
+
+  onMessage(data) {
+    try {
+      const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data
+      const msg = unpack(bytes)
+      this._handleMessage(msg.type, msg.payload || {})
+    } catch (e) { console.error('[client] parse error:', e) }
+  }
+
+  _handleMessage(type, payload) {
+    if (type === MSG.HANDSHAKE_ACK) {
+      this.playerId = payload.playerId
+      this.currentTick = payload.tick
+      this._predEngine = new PredictionEngine(this.config.tickRate)
+      this._predEngine.init(this.playerId)
+    } else if (type === MSG.SNAPSHOT || type === MSG.STATE_CORRECTION) {
+      this._onSnapshot(payload)
+    } else if (type === MSG.PLAYER_LEAVE) {
+      this._playerStates.delete(payload.playerId)
+      this.callbacks.onPlayerLeft(payload.playerId)
+    } else if (type === MSG.WORLD_DEF) {
+      if (payload.movement && this._predEngine) this._predEngine.setMovement(payload.movement)
+      if (payload.gravity && this._predEngine) this._predEngine.setGravity(payload.gravity)
+      this.callbacks.onWorldDef?.(payload)
+    } else if (type === MSG.APP_EVENT) {
+      this.callbacks.onAppEvent?.(payload)
+    } else if (type === MSG.HOT_RELOAD || type === MSG.APP_MODULE || type === MSG.ASSET_UPDATE) {
+      const cb = { [MSG.HOT_RELOAD]: 'onHotReload', [MSG.APP_MODULE]: 'onAppModule', [MSG.ASSET_UPDATE]: 'onAssetUpdate' }[type]
+      this.callbacks[cb]?.(payload)
+    }
+  }
+
+  _onSnapshot(data) {
+    this.lastSnapshotTick = this.currentTick = data.tick || 0
+    for (const p of data.players || []) {
+      const { playerId, state } = this._parsePlayer(p)
+      if (!this._playerStates.has(playerId)) this.callbacks.onPlayerJoined(playerId, state)
+      this._playerStates.set(playerId, state)
+      if (playerId === this.playerId && this.config.predictionEnabled && this._predEngine) {
+        this._predEngine.onServerSnapshot({ players: [state] }, this.currentTick)
+      }
+    }
+    for (const e of data.entities || []) {
+      const { entityId, state } = this._parseEntity(e)
+      if (!this._entityStates.has(entityId)) this.callbacks.onEntityAdded(entityId, state)
+      this._entityStates.set(entityId, state)
+    }
+    this.state.players = Array.from(this._playerStates.values())
+    this.state.entities = Array.from(this._entityStates.values())
+    this.callbacks.onSnapshot(data)
+    this.callbacks.onStateUpdate(this.state)
+    this._render()
+  }
+
+  _parsePlayer(p) {
+    if (Array.isArray(p)) return { playerId: p[0], state: { id: p[0], position: [p[1], p[2], p[3]], rotation: [p[4], p[5], p[6], p[7]], velocity: [p[8], p[9], p[10]], onGround: p[11] === 1, health: p[12], inputSequence: p[13] } }
+    return { playerId: p.id || p.i, state: { id: p.id || p.i, position: p.position || [0, 0, 0], rotation: p.rotation || [0, 0, 0, 1], velocity: p.velocity || [0, 0, 0], onGround: p.onGround ?? false, health: p.health ?? 100 } }
+  }
+
+  _parseEntity(e) {
+    if (Array.isArray(e)) return { entityId: e[0], state: { id: e[0], model: e[1], position: [e[2], e[3], e[4]], rotation: [e[5], e[6], e[7], e[8]], bodyType: e[9], custom: e[10] } }
+    return { entityId: e.id, state: { id: e.id, model: e.model, position: e.position || [0, 0, 0], rotation: e.rotation || [0, 0, 0, 1], bodyType: e.bodyType || 'static', custom: e.custom || null } }
+  }
+
+  _render() {
+    const displayStates = new Map()
+    for (const [playerId, serverState] of this._playerStates) {
+      displayStates.set(playerId, playerId === this.playerId && this.config.predictionEnabled && this._predEngine ? this._predEngine.getDisplayState(this.currentTick, 0) : serverState)
+    }
+    this.callbacks.onRender(displayStates)
+  }
+
+  getLocalState() {
+    return this.config.predictionEnabled && this._predEngine ? this._predEngine.localState : this._playerStates.get(this.playerId)
+  }
+
+  getRemoteState(playerId) { return this._playerStates.get(playerId) }
+  getAllStates() { return new Map(this._playerStates) }
+  getEntity(entityId) { return this._entityStates.get(entityId) }
+  getAllEntities() { return new Map(this._entityStates) }
+
+  disconnect() {
+    this._stopHeartbeat()
+    if (this.ws) this.ws.close()
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat()
+    this.heartbeatTimer = setInterval(() => {
+      if (this._isOpen()) this.ws.send(pack({ type: MSG.HEARTBEAT, payload: {} }))
+    }, 1000)
+  }
+
+  _stopHeartbeat() {
+    if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = null }
+  }
+}

package/src/client/PredictionEngine.js

@@ -0,0 +1,123 @@
+import { ReconciliationEngine } from './ReconciliationEngine.js'
+import { applyMovement, DEFAULT_MOVEMENT } from '../shared/movement.js'
+
+export class PredictionEngine {
+  constructor(tickRate = 128) {
+    this.tickRate = tickRate
+    this.tickDuration = 1000 / tickRate
+    this.localPlayerId = null
+    this.localState = null
+    this.lastServerState = null
+    this.inputHistory = []
+    this.reconciliationEngine = new ReconciliationEngine()
+    this.movement = { ...DEFAULT_MOVEMENT }
+    this.gravityY = -9.81
+  }
+
+  setMovement(m) { Object.assign(this.movement, m) }
+
+  setGravity(g) { if (g && g[1] != null) this.gravityY = g[1] }
+
+  init(playerId, initialState = {}) {
+    this.localPlayerId = playerId
+    this.localState = {
+      id: playerId,
+      position: initialState.position || [0, 0, 0],
+      rotation: initialState.rotation || [0, 0, 0, 1],
+      velocity: initialState.velocity || [0, 0, 0],
+      onGround: true,
+      health: initialState.health || 100
+    }
+    this.lastServerState = JSON.parse(JSON.stringify(this.localState))
+  }
+
+  addInput(input) {
+    this.inputHistory.push({
+      sequence: this.inputHistory.length,
+      data: input,
+      timestamp: Date.now()
+    })
+    if (this.inputHistory.length > 128) {
+      this.inputHistory.shift()
+    }
+    this.predict(input)
+  }
+
+  predict(input) {
+    const dt = this.tickDuration / 1000
+    const state = this.localState
+    applyMovement(state, input, this.movement, dt)
+    state.velocity[1] += this.gravityY * dt
+    state.position[0] += state.velocity[0] * dt
+    state.position[1] += state.velocity[1] * dt
+    state.position[2] += state.velocity[2] * dt
+    if (state.position[1] < 0) {
+      state.position[1] = 0
+      state.velocity[1] = 0
+      state.onGround = true
+    }
+  }
+
+  interpolate(factor) {
+    if (!this.lastServerState || !this.localState) return this.localState
+    return {
+      id: this.localState.id,
+      position: [
+        this.lastServerState.position[0] + (this.localState.position[0] - this.lastServerState.position[0]) * factor,
+        this.lastServerState.position[1] + (this.localState.position[1] - this.lastServerState.position[1]) * factor,
+        this.lastServerState.position[2] + (this.localState.position[2] - this.lastServerState.position[2]) * factor
+      ],
+      rotation: this.localState.rotation,
+      velocity: this.localState.velocity,
+      health: this.localState.health,
+      onGround: this.localState.onGround
+    }
+  }
+
+  extrapolate(ticksAhead = 1) {
+    const extrapolated = JSON.parse(JSON.stringify(this.localState))
+    const dt = (this.tickDuration / 1000) * ticksAhead
+    extrapolated.position[0] += this.localState.velocity[0] * dt
+    extrapolated.position[1] += this.localState.velocity[1] * dt
+    extrapolated.position[2] += this.localState.velocity[2] * dt
+    return extrapolated
+  }
+
+  onServerSnapshot(snapshot, tick) {
+    for (const serverPlayer of snapshot.players) {
+      if (serverPlayer.id === this.localPlayerId) {
+        this.lastServerState = JSON.parse(JSON.stringify(serverPlayer))
+        const reconciliation = this.reconciliationEngine.reconcile(
+          this.lastServerState, this.localState, tick
+        )
+        if (reconciliation.needsCorrection) {
+          this.reconciliationEngine.applyCorrection(this.localState, reconciliation.correction)
+          this.resimulate()
+        }
+      }
+    }
+  }
+
+  resimulate() {
+    const baseState = JSON.parse(JSON.stringify(this.lastServerState))
+    this.localState = baseState
+    for (const input of this.inputHistory) {
+      this.predict(input.data)
+    }
+  }
+
+  getDisplayState(tick, ticksSinceLastSnapshot) {
+    const alpha = (ticksSinceLastSnapshot % 1) / 1
+    return this.interpolate(alpha)
+  }
+
+  getInputHistory() { return this.inputHistory }
+
+  calculateDivergence() {
+    if (!this.lastServerState || !this.localState) return 0
+    const dx = this.localState.position[0] - this.lastServerState.position[0]
+    const dy = this.localState.position[1] - this.lastServerState.position[1]
+    const dz = this.localState.position[2] - this.lastServerState.position[2]
+    return Math.sqrt(dx * dx + dy * dy + dz * dz)
+  }
+}

package/src/client/ReconciliationEngine.js

@@ -0,0 +1,54 @@
+export class ReconciliationEngine {
+  constructor(config = {}) {
+    this.correctionThreshold = config.correctionThreshold || 0.01
+    this.correctionSpeed = config.correctionSpeed || 0.5
+    this.lastReconcileTime = 0
+    this.reconcileInterval = config.reconcileInterval || 100
+  }
+
+  reconcile(serverState, localState, tick) {
+    const now = Date.now()
+    if (now - this.lastReconcileTime < this.reconcileInterval) {
+      return { needsCorrection: false, correction: null }
+    }
+
+    this.lastReconcileTime = now
+
+    const divergence = this.calculateDivergence(serverState, localState)
+
+    if (divergence < this.correctionThreshold) {
+      return { needsCorrection: false, divergence }
+    }
+
+    const correction = this.generateCorrection(serverState, localState)
+    return { needsCorrection: true, correction, divergence }
+  }
+
+  calculateDivergence(serverState, localState) {
+    if (!serverState || !localState) return 0
+
+    const dx = serverState.position[0] - localState.position[0]
+    const dy = serverState.position[1] - localState.position[1]
+    const dz = serverState.position[2] - localState.position[2]
+
+    return Math.sqrt(dx * dx + dy * dy + dz * dz)
+  }
+
+  generateCorrection(serverState, localState) {
+    return {
+      position: [
+        serverState.position[0] * this.correctionSpeed + localState.position[0] * (1 - this.correctionSpeed),
+        serverState.position[1] * this.correctionSpeed + localState.position[1] * (1 - this.correctionSpeed),
+        serverState.position[2] * this.correctionSpeed + localState.position[2] * (1 - this.correctionSpeed)
+      ],
+      velocity: [...serverState.velocity],
+      onGround: serverState.onGround
+    }
+  }
+
+  applyCorrection(localState, correction) {
+    localState.position = correction.position
+    localState.velocity = correction.velocity
+    localState.onGround = correction.onGround
+  }
+}

package/src/connection/ConnectionManager.js

@@ -0,0 +1,133 @@
+import { pack, unpack } from '../protocol/msgpack.js'
+import { isUnreliable } from '../protocol/MessageTypes.js'
+import { EventEmitter } from '../protocol/EventEmitter.js'
+
+export class ConnectionManager extends EventEmitter {
+  constructor(options = {}) {
+    super()
+    this.clients = new Map()
+    this.heartbeatInterval = options.heartbeatInterval || 1000
+    this.heartbeatTimeout = options.heartbeatTimeout || 3000
+    this.timers = new Map()
+  }
+
+  addClient(clientId, transport) {
+    const client = {
+      id: clientId,
+      transport,
+      lastHeartbeat: Date.now(),
+      sessionToken: null,
+      transportType: transport.type || 'websocket'
+    }
+
+    transport.on('message', (data) => {
+      try {
+        client.lastHeartbeat = Date.now()
+        const msg = unpack(data)
+        this.emit('message', clientId, msg)
+      } catch (err) {
+        console.error(`[connection] decode error for ${clientId}:`, err.message)
+      }
+    })
+
+    transport.on('close', () => {
+      this.removeClient(clientId)
+      this.emit('disconnect', clientId, 'closed')
+    })
+
+    transport.on('error', (err) => {
+      console.error(`[connection] transport error for ${clientId}:`, err.message)
+      this.removeClient(clientId)
+      this.emit('disconnect', clientId, 'error')
+    })
+
+    this.clients.set(clientId, client)
+    this._setupHeartbeat(clientId)
+    return client
+  }
+
+  _setupHeartbeat(clientId) {
+    const check = () => {
+      const client = this.clients.get(clientId)
+      if (!client) return
+      const age = Date.now() - client.lastHeartbeat
+      if (age > this.heartbeatTimeout) {
+        this.removeClient(clientId)
+        this.emit('disconnect', clientId, 'timeout')
+        return
+      }
+      const timer = setTimeout(check, this.heartbeatInterval)
+      this.timers.set(`hb-${clientId}`, timer)
+    }
+    const timer = setTimeout(check, this.heartbeatInterval)
+    this.timers.set(`hb-${clientId}`, timer)
+  }
+
+  removeClient(clientId) {
+    const client = this.clients.get(clientId)
+    if (!client) return
+    if (client.transport && client.transport.isOpen) {
+      client.transport.close()
+    }
+    this.clients.delete(clientId)
+    const timer = this.timers.get(`hb-${clientId}`)
+    if (timer) clearTimeout(timer)
+    this.timers.delete(`hb-${clientId}`)
+  }
+
+  getClient(clientId) {
+    return this.clients.get(clientId)
+  }
+
+  send(clientId, type, payload = {}) {
+    const client = this.clients.get(clientId)
+    if (!client || !client.transport.isOpen) return false
+    try {
+      const data = pack({ type, payload })
+      if (isUnreliable(type)) return client.transport.sendUnreliable(data)
+      return client.transport.send(data)
+    } catch (err) {
+      console.error(`[connection] send error to ${clientId}:`, err.message)
+      return false
+    }
+  }
+
+  broadcast(type, payload = {}) {
+    const data = pack({ type, payload })
+    const unreliable = isUnreliable(type)
+    let count = 0
+    for (const client of this.clients.values()) {
+      if (!client.transport.isOpen) continue
+      try {
+        if (unreliable) client.transport.sendUnreliable(data)
+        else client.transport.send(data)
+        count++
+      } catch (err) {
+        console.error(`[connection] broadcast error to ${client.id}:`, err.message)
+      }
+    }
+    return count
+  }
+
+  getAllStats() {
+    return {
+      activeConnections: this.clients.size,
+      clients: Array.from(this.clients.entries()).map(([id, c]) => ({
+        id,
+        transport: c.transportType,
+        sessionToken: c.sessionToken ? '***' : null
+      }))
+    }
+  }
+
+  destroy() {
+    for (const clientId of this.clients.keys()) {
+      this.removeClient(clientId)
+    }
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer)
+    }
+    this.clients.clear()
+    this.timers.clear()
+  }
+}

package/src/connection/QualityMonitor.js

@@ -0,0 +1,46 @@
+export class QualityMonitor {
+  constructor() {
+    this.bytesIn = 0
+    this.bytesOut = 0
+    this.heartbeatsSent = 0
+    this.heartbeatsReceived = 0
+    this.rttSamples = []
+    this.startTime = Date.now()
+  }
+
+  recordBytesIn(count) {
+    this.bytesIn += count
+  }
+
+  recordBytesOut(count) {
+    this.bytesOut += count
+  }
+
+  recordHeartbeatSent() {
+    this.heartbeatsSent++
+  }
+
+  recordHeartbeatReceived() {
+    this.heartbeatsReceived++
+  }
+
+  recordRtt(rtt) {
+    this.rttSamples.push(rtt)
+    if (this.rttSamples.length > 100) this.rttSamples.shift()
+  }
+
+  getStats() {
+    const elapsed = Date.now() - this.startTime
+    const avgRtt = this.rttSamples.length > 0
+      ? this.rttSamples.reduce((a, b) => a + b, 0) / this.rttSamples.length
+      : 0
+    return {
+      bytesIn: this.bytesIn,
+      bytesOut: this.bytesOut,
+      heartbeatsSent: this.heartbeatsSent,
+      heartbeatsReceived: this.heartbeatsReceived,
+      avgRtt,
+      uptime: elapsed
+    }
+  }
+}

package/src/connection/SessionStore.js

@@ -0,0 +1,67 @@
+import { randomBytes } from 'node:crypto'
+
+export class SessionStore {
+  constructor(options = {}) {
+    this.ttl = options.ttl || 30000
+    this.sessions = new Map()
+    this.timers = new Map()
+  }
+
+  create(playerId, state) {
+    const token = randomBytes(16).toString('hex')
+    const session = {
+      token,
+      playerId,
+      state: state ? { ...state } : {},
+      createdAt: Date.now()
+    }
+    this.sessions.set(token, session)
+    this._setupExpire(token)
+    return token
+  }
+
+  update(token, data) {
+    const session = this.sessions.get(token)
+    if (!session) return false
+    if (data.state) Object.assign(session.state, data.state)
+    session.lastUpdated = Date.now()
+    return true
+  }
+
+  get(token) {
+    const session = this.sessions.get(token)
+    if (!session) return null
+    if (Date.now() - session.createdAt > this.ttl) {
+      this.destroy(token)
+      return null
+    }
+    return session
+  }
+
+  _setupExpire(token) {
+    const timer = setTimeout(() => {
+      this.sessions.delete(token)
+      this.timers.delete(token)
+    }, this.ttl)
+    this.timers.set(token, timer)
+  }
+
+  destroy(token) {
+    const timer = this.timers.get(token)
+    if (timer) clearTimeout(timer)
+    this.timers.delete(token)
+    this.sessions.delete(token)
+  }
+
+  getActiveCount() {
+    return this.sessions.size
+  }
+
+  destroyAll() {
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer)
+    }
+    this.timers.clear()
+    this.sessions.clear()
+  }
+}

package/src/debug/CliDebugger.js

@@ -0,0 +1,93 @@
+export class CliDebugger {
+  constructor(prefix = '[spawnpoint]') {
+    this.prefix = prefix
+    this.startTime = Date.now()
+    this.history = []
+  }
+
+  _timestamp() {
+    const elapsed = Date.now() - this.startTime
+    const s = (elapsed / 1000).toFixed(2)
+    return `${s}s`.padStart(8)
+  }
+
+  _formatVec3(v) {
+    if (!v) return '(null)'
+    return `(${v[0].toFixed(2)}, ${v[1].toFixed(2)}, ${v[2].toFixed(2)})`
+  }
+
+  spawn(entity, position) {
+    const msg = `${this.prefix} SPAWN ${String(entity).padEnd(15)} @ ${this._formatVec3(position)}`
+    console.log(`${this._timestamp()} ${msg}`)
+    this.history.push(msg)
+  }
+
+  collision(a, b, position) {
+    const msg = `${this.prefix} COLLISION ${String(a).padEnd(8)} <-> ${String(b).padEnd(8)} @ ${this._formatVec3(position)}`
+    console.log(`${this._timestamp()} ${msg}`)
+    this.history.push(msg)
+  }
+
+  hit(shooter, target, damage) {
+    const msg = `${this.prefix} HIT ${String(shooter).padEnd(10)} -> ${String(target).padEnd(10)} [${damage}hp]`
+    console.log(`${this._timestamp()} ${msg}`)
+    this.history.push(msg)
+  }
+
+  death(entity, damage) {
+    const msg = `${this.prefix} DEATH ${String(entity).padEnd(15)} from ${damage}hp`
+    console.log(`${this._timestamp()} ${msg}`)
+    this.history.push(msg)
+  }
+
+  respawn(entity, position) {
+    const msg = `${this.prefix} RESPAWN ${String(entity).padEnd(10)} @ ${this._formatVec3(position)}`
+    console.log(`${this._timestamp()} ${msg}`)
+    this.history.push(msg)
+  }
+
+  state(entity, key, value) {
+    const v = typeof value === 'object' ? JSON.stringify(value) : String(value)
+    const msg = `${this.prefix} STATE ${String(entity).padEnd(15)} ${key}=${v}`
+    console.log(`${this._timestamp()} ${msg}`)
+  }
+
+  perf(label, ms) {
+    const status = ms < 10 ? '✓' : ms < 20 ? '⚠' : '✗'
+    const msg = `${this.prefix} ${status} ${label.padEnd(20)} ${ms.toFixed(1)}ms`
+    console.log(`${this._timestamp()} ${msg}`)
+  }
+
+  physics(body, pos, vel, health) {
+    const speed = Math.sqrt(vel[0]*vel[0] + vel[1]*vel[1] + vel[2]*vel[2]).toFixed(1)
+    const msg = `${this.prefix} PHY ${String(body).padEnd(10)} pos=${this._formatVec3(pos)} vel=${speed}m/s hp=${health}`
+    console.log(`${this._timestamp()} ${msg}`)
+  }
+
+  error(category, message) {
+    const msg = `${this.prefix} ERROR [${category}] ${message}`
+    console.error(`${this._timestamp()} ${msg}`)
+    this.history.push(msg)
+  }
+
+  section(title) {
+    console.log(`\n${this.prefix} ${'='.repeat(50)}`)
+    console.log(`${this.prefix} ${title}`)
+    console.log(`${this.prefix} ${'='.repeat(50)}\n`)
+  }
+
+  summary(stats = {}) {
+    console.log(`\n${this.prefix} SESSION SUMMARY`)
+    for (const [key, value] of Object.entries(stats)) {
+      console.log(`${this.prefix}   ${key}: ${value}`)
+    }
+  }
+
+  log(message) {
+    const msg = `${this.prefix} ${message}`
+    console.log(`${this._timestamp()} ${msg}`)
+    this.history.push(msg)
+  }
+}
+
+export const cliDebugger = new CliDebugger()