lecodes-sdk 0.19.0

package/src/core/InspectorUI.ts

@@ -0,0 +1,212 @@
+// The scene editor's immediate-mode inspector protocol (docs/scene-editor-plan.md, phase 9).
+//
+// Custom editor UI never renders into the editor panel directly — the live data (aspect instances,
+// nodes, `model.anim.clips`, generated meshes) lives in the SCENE WORLD (the compiled bundle), on
+// the other side of the controller. So a custom view is an imgui-style function running in the
+// world: it re-runs on every change/event and emits a WIDGET LIST (plain data); the editor panel is
+// a dumb renderer of that list; user events `{ id, value }` come back and trigger the next run —
+// `ui.button()` returns `true` on the run that consumes the click.
+//
+//   class Road extends Aspect<'road'> {
+//     from: Node | null = null
+//     to: Node | null = null
+//     width = 2
+//     static editor = { rebuild: true }
+//     static inspector(ui: InspectorUI, road: Road) {
+//       ui.auto()                                   // the inferred fields, as usual
+//       if (road.from && road.to) ui.info(`${road.generated.children.length} pieces`)
+//       else ui.warn('Assign both endpoints')
+//       if (ui.button('Shuffle')) road.rebuild()
+//     }
+//   }
+//
+// BINDING RULE: a field whose key is a declared aspect field (a public class field) is DOC-BOUND —
+// the editor persists edits to the scene file through its normal commit/undo path. Any other key is
+// EDITOR STATE — transient, kept on this InspectorUI instance across runs, never written to a file
+// (the animation card's clip choice, a tool's brush size). One vocabulary, two lifetimes.
+
+import type { FieldDescriptor, FieldEditor } from "./fields"
+
+/** One user interaction coming back from the editor panel: the widget's id (+ value for fields). */
+export type InspectorEvent = { id: string, value?: unknown }
+
+export type InspectorFieldWidget = {
+  kind: "field"
+  id: string
+  /** The bound key — an aspect field (doc-bound) or an editor-state key. */
+  key: string
+  label: string
+  editor: FieldEditor | undefined
+  value: unknown
+  /** True = persisted to the scene file by the editor; false = transient editor state. */
+  doc: boolean
+  /** True = emitted by `ui.auto()` — the editor may overlay its syntactic hints (options/node). */
+  auto?: boolean
+  min?: number
+  max?: number
+  step?: number
+  options?: readonly (string | number)[]
+}
+
+export type InspectorWidget =
+  | InspectorFieldWidget
+  | { kind: "button", id: string, label: string }
+  | { kind: "toolButton", id: string, label: string, tool: string }
+  | { kind: "header", id: string, label: string }
+  | { kind: "info" | "warn", id: string, text: string }
+
+type FieldOpts = {
+  label?: string
+  min?: number
+  max?: number
+  step?: number
+  /** Default for EDITOR-STATE keys (doc keys default from the class field). */
+  value?: unknown
+}
+
+/**
+ * The widget builder handed to `static inspector(ui, aspect)` (and to editor windows/tools later).
+ * One instance lives per card and persists across runs — it carries the card's editor state.
+ */
+export class InspectorUI {
+  /** @internal This run's emitted widgets. */
+  _widgets: InspectorWidget[] = []
+  /** @internal Transient editor state (non-doc field keys), kept across runs. */
+  _state: Record<string, unknown> = {}
+  /** @internal The aspect entry's doc props (live reference — the runner keeps it current). */
+  _props: Record<string, unknown> = {}
+  /** @internal Keys that are declared aspect fields → doc-bound. Empty for node/window cards. */
+  _docKeys = new Set<string>()
+  /** @internal Field descriptors for auto() + doc-key defaults (describeFields output). */
+  _fields: FieldDescriptor[] = []
+  /** @internal The unconsumed button event of the current run. */
+  _event: InspectorEvent | null = null
+
+  // ---- fields (each emits one widget AND returns the current value) ---------------------------
+
+  /** Numeric field (min/max/step render as a slider-style scrub range). */
+  number(key: string, opts?: FieldOpts): number {
+    const v = this._field("number", key, opts)
+    return typeof v === "number" ? v : 0
+  }
+  /** Alias of `number` — give it min/max/step and the editor renders a scrubable range. */
+  slider(key: string, opts?: FieldOpts): number { return this.number(key, opts) }
+
+  text(key: string, opts?: FieldOpts): string {
+    const v = this._field("text", key, opts)
+    return typeof v === "string" ? v : ""
+  }
+
+  color(key: string, opts?: FieldOpts): string {
+    const v = this._field("color", key, opts)
+    return typeof v === "string" ? v : "#ffffff"
+  }
+
+  switch(key: string, opts?: FieldOpts): boolean {
+    return this._field("switch", key, opts) === true
+  }
+
+  /** Dropdown — `options` may be computed fresh every run (dynamic lists come free). */
+  select(key: string, options: readonly (string | number)[], opts?: FieldOpts): string | number {
+    const v = this._field("select", key, { ...opts, value: opts?.value ?? options[0] }, options)
+    return (typeof v === "string" || typeof v === "number") && options.includes(v) ? v : options[0]
+  }
+
+  vec2(key: string, opts?: FieldOpts): [number, number] { return this._vec("vec2", key, 2, opts) as [number, number] }
+  vec3(key: string, opts?: FieldOpts): [number, number, number] { return this._vec("vec3", key, 3, opts) as [number, number, number] }
+  vec4(key: string, opts?: FieldOpts): [number, number, number, number] { return this._vec("vec4", key, 4, opts) as [number, number, number, number] }
+
+  /** Scene-node reference (`ref()` fields): name dropdown + pick-in-viewport. Returns the RAW doc
+   *  value (`{ $ref }` marker or null) — read the resolved live node off the aspect instance. */
+  node(key: string, opts?: FieldOpts): unknown {
+    return this._field("node", key, opts)
+  }
+
+  /** Project-asset path (the editor renders a dropdown of the project's GLBs). "" = none picked. */
+  asset(key: string, opts?: FieldOpts): string {
+    const v = this._field("asset", key, { ...opts, value: opts?.value ?? "" })
+    return typeof v === "string" ? v : ""
+  }
+
+  // ---- everything else --------------------------------------------------------------------------
+
+  /** True on the run that consumes this button's click — do the action right there. */
+  button(label: string, opts?: { id?: string }): boolean {
+    const id = opts?.id ?? `b:${label}`
+    this._widgets.push({ kind: "button", id, label })
+    if (this._event?.id === id) {
+      this._event = null
+      return true
+    }
+    return false
+  }
+
+  /** A toggle that activates/deactivates the named viewport tool (`registerEditorTool`). The
+   *  editor owns the active-tool state — the click never round-trips into the scene world. */
+  toolButton(label: string, tool: string): void {
+    this._widgets.push({ kind: "toolButton", id: `t:${tool}`, label, tool })
+  }
+
+  header(label: string): void { this._widgets.push({ kind: "header", id: `h:${label}`, label }) }
+  info(text: string): void { this._widgets.push({ kind: "info", id: `i:${this._widgets.length}`, text }) }
+  warn(text: string): void { this._widgets.push({ kind: "warn", id: `w:${this._widgets.length}`, text }) }
+
+  /** Emit the inferred field widgets (all declared aspect fields, or just the named ones) — the
+   *  zero-ceremony baseline; append custom widgets around it. */
+  auto(...keys: string[]): void {
+    for (const f of this._fields) {
+      if (keys.length > 0 && !keys.includes(f.key)) continue
+      const value = this._props[f.key] !== undefined ? this._props[f.key] : f.value
+      this._widgets.push({
+        kind: "field", id: `f:${f.key}`, key: f.key, label: f.label, editor: f.editor,
+        value, doc: true, auto: true, min: f.min, max: f.max, step: f.step, options: f.options,
+      })
+    }
+  }
+
+  // ---- internals ----------------------------------------------------------------------------
+
+  private _vec(editor: FieldEditor, key: string, size: number, opts?: FieldOpts): number[] {
+    const v = this._field(editor, key, opts)
+    const arr = Array.isArray(v) ? v : []
+    return Array.from({ length: size }, (_, i) => (typeof arr[i] === "number" ? arr[i] as number : 0))
+  }
+
+  private _field(
+    editor: FieldEditor, key: string, opts?: FieldOpts, options?: readonly (string | number)[],
+  ): unknown {
+    const doc = this._docKeys.has(key)
+    const fallback = doc ? this._fields.find((f) => f.key === key)?.value : opts?.value
+    const stored = doc ? this._props[key] : this._state[key]
+    const value = stored !== undefined ? stored : fallback
+    this._widgets.push({
+      kind: "field", id: `f:${key}`, key, label: opts?.label ?? key, editor, value, doc,
+      min: opts?.min, max: opts?.max, step: opts?.step, options,
+    })
+    return value
+  }
+
+  /**
+   * @internal One immediate-mode pass: deliver `event`, run `fn`, return the widget list.
+   * Editor-state field events are applied here; DOC-key field events must be applied by the
+   * caller beforehand (they go through the scene loader's prop machinery — rebuilds, ref
+   * resolution); button events are consumed by the matching `button()` call during the run.
+   * A throwing inspector logs and shows the error as a warn line — it can't take the editor down.
+   */
+  _run(fn: (ui: this) => void, event?: InspectorEvent): InspectorWidget[] {
+    if (event && event.id.startsWith("f:") && !this._docKeys.has(event.id.slice(2))) {
+      this._state[event.id.slice(2)] = event.value
+      event = undefined
+    }
+    this._event = event ?? null
+    this._widgets = []
+    try {
+      fn(this)
+    } catch (e) {
+      console.error("[scene] inspector render failed:", e)
+      this.warn(String((e as Error)?.message ?? e))
+    }
+    this._event = null
+    return this._widgets
+  }
+}

package/src/core/StateMachine.ts

@@ -0,0 +1,308 @@
+// A hierarchical state machine over a plain context object — the one place a game keeps "what am I
+// doing right now": an enemy brain, a weapon (ready → fire → cooldown → reload), a game mode
+// (warmup → round → over), a door. Declarative: the whole machine is ONE table you can read top
+// to bottom, log, and later show in an inspector; the machine knows nothing about aspects, nodes
+// or the network, so it runs wherever its owner ticks it (an `updateFixed` for anything that must
+// match another machine's, `update` for presentation).
+//
+//   const Guard = defineStates<Bot>({
+//     initial: 'patrol',
+//     on: { hit: 'flinch' },                                    // from ANY state
+//     to: { dead: (b) => b.hp <= 0 },                           // checked in every state, first
+//     states: {
+//       patrol: { update: (b, dt) => b.walk(dt), to: { combat: (b) => b.target !== null } },
+//       combat: {
+//         initial: 'engage',
+//         to: { search: (b) => b.lostFor > 4 },                 // leaves whichever child is active
+//         states: {
+//           engage: { update: (b) => b.approach(), to: { shoot: (b) => b.visible && b.dist < 12 } },
+//           shoot:  { enter: (b) => b.fire = true, exit: (b) => b.fire = false, to: { engage: (b) => !b.visible } },
+//         },
+//       },
+//       search: { after: [6, 'patrol'] },                       // a timed transition
+//       flinch: { after: [0.2, '$back'] },                      // '$back' = the state we came from
+//       dead:   { enter: (b) => b.die() },
+//     },
+//   })
+//   const fsm = new StateMachine(Guard, bot)
+//   fsm.step(dt)                    // once per tick: guards (outer states first), then updates
+//   fsm.send('hit')                 // an event: the innermost state that handles it wins
+//   fsm.state                       // 'combat.shoot'   fsm.is('combat') → true
+//   fsm.on('change', (to, from) => console.log(`[fsm] ${from} → ${to}`))
+//
+// Semantics, in order, per `step(dt)`:
+//   1. every active state's clock advances (`t` = seconds in that state);
+//   2. transitions are tested OUTERMOST first — the root's `to` (any-state guards), then each
+//      active state's `to` guards (first true wins) and its `after` timer; a taken transition is
+//      re-tested from the new state (a pass-through state chains), at most 8 hops per step;
+//   3. `update` runs outermost → innermost; an update that RETURNS a state name transitions
+//      there and ends the pass (the states it entered update next step).
+// A transition exits states innermost-first up to the common ancestor and enters the new branch
+// outermost-first, descending into `initial` children; the target state's own name (or an
+// ancestor's) re-enters it. Names resolve relative to the declaring state (siblings, then each
+// ancestor's siblings), or as a dotted path from the root; unknown names throw when the machine is
+// built, so a typo is a startup error, not a silent no-op. `send` looks innermost → outermost
+// (the root's `on` = any state) and returns whether someone handled it.
+
+export type StateGuard<C> = (ctx: C, t: number) => boolean
+export type StateHandler<C> = (ctx: C, ...args: any[]) => string | void
+
+export interface StateDef<C> {
+  /** The child entered by default when this (compound) state is entered. */
+  initial?: string
+  /** Child states — this becomes a compound state; only a leaf is ever "the" state. */
+  states?: Record<string, StateDef<C>>
+  /** Entered (from = the previous leaf's path, '' at start). */
+  enter?: (ctx: C, from: string) => void
+  /** Left (to = the next leaf's path). */
+  exit?: (ctx: C, to: string) => void
+  /** Every step while active, outer states first; `t` = seconds in this state. Return a state name
+   *  to transition. */
+  update?: (ctx: C, dt: number, t: number) => string | void
+  /** Guarded transitions, tested every step before `update` — key = target, first true wins. */
+  to?: Record<string, StateGuard<C>>
+  /** Leave for `target` after `seconds` in this state. */
+  after?: [seconds: number, target: string]
+  /** Event handlers for `send(name, …args)`: a target name, or a function returning one (or nothing). */
+  on?: Record<string, string | StateHandler<C>>
+}
+
+export interface StatesDef<C> {
+  initial: string
+  states: Record<string, StateDef<C>>
+  /** Any-state guards — tested first, in every state. */
+  to?: Record<string, StateGuard<C>>
+  /** Any-state event handlers — the fallback when no active state handles the event. */
+  on?: Record<string, string | StateHandler<C>>
+  /** Any-state update, runs before the active states' own. */
+  update?: (ctx: C, dt: number, t: number) => string | void
+}
+
+export type StateMachineEvents = {
+  /** After a transition completed (both are leaf paths; `from` = '' for the initial entry). */
+  change: (to: string, from: string) => void
+}
+
+/** Identity helper — names the context type once so every callback is typed. */
+export const defineStates = <C>(def: StatesDef<C>): StatesDef<C> => def
+
+const BACK = "$back"
+const MAX_HOPS = 8
+
+interface SNode<C> {
+  name: string
+  path: string
+  def: StateDef<C>
+  parent: SNode<C> | null
+  children: Map<string, SNode<C>>
+  initial: SNode<C> | null
+  depth: number
+  /** seconds in this state (valid while active) */
+  t: number
+  /** resolved `to` targets in declaration order */
+  guards: Array<[SNode<C>, StateGuard<C>]>
+  after: [number, SNode<C> | typeof BACK] | null
+  /** resolution cache for names returned at runtime */
+  resolved: Map<string, SNode<C> | typeof BACK>
+}
+
+export class StateMachine<C> {
+  readonly ctx: C
+  private readonly root: SNode<C>
+  private readonly byPath = new Map<string, SNode<C>>()
+  /** the active branch, root's child (index 0) → leaf */
+  private chain: SNode<C>[] = []
+  private prev: SNode<C> | null = null
+  private listeners: Array<(to: string, from: string) => void> = []
+  private changed = 0
+
+  constructor(def: StatesDef<C>, ctx: C) {
+    this.ctx = ctx
+    this.root = this.build("", "", def as StateDef<C>, null, 0)
+    // second pass: resolve names (every state exists now)
+    for (const n of this.byPath.values()) this.link(n)
+    this.link(this.root)
+    if (!this.root.initial) throw new Error("StateMachine: `initial` is required")
+    this.enterBranch([], this.leafOf(this.root.initial), "")
+  }
+
+  /** The active leaf's path ('combat.shoot'). */
+  get state(): string { return this.chain[this.chain.length - 1]?.path ?? "" }
+  /** The leaf we came from ('' before the first transition). */
+  get previous(): string { return this.prev?.path ?? "" }
+  /** Seconds in the active leaf. */
+  get time(): number { return this.chain[this.chain.length - 1]?.t ?? 0 }
+  /** Every active state's path, outermost first. */
+  get branch(): string[] { return this.chain.map((n) => n.path) }
+
+  /** Is `name` (a state name or dotted path) active — as the leaf OR as one of its ancestors? */
+  is(name: string): boolean {
+    for (const n of this.chain) if (n.name === name || n.path === name) return true
+    return false
+  }
+  /** Seconds in the named active state (0 when it is not active). */
+  timeIn(name: string): number {
+    for (const n of this.chain) if (n.name === name || n.path === name) return n.t
+    return 0
+  }
+
+  /** Force a transition (a spawn, a reset from outside the table). */
+  go(name: string): void {
+    const leaf = this.chain[this.chain.length - 1] ?? this.root
+    this.transition(this.resolve(leaf, name))
+  }
+
+  /** Deliver an event. Innermost active state first, the root's `on` last. True if handled. */
+  send(event: string, ...args: unknown[]): boolean {
+    for (let i = this.chain.length - 1; i >= 0; i--) {
+      const n = this.chain[i]!
+      const h = n.def.on?.[event]
+      if (h === undefined) continue
+      const target = typeof h === "string" ? h : h(this.ctx, ...args)
+      if (typeof target === "string") this.transition(this.resolve(n, target))
+      return true
+    }
+    const h = this.root.def.on?.[event]
+    if (h === undefined) return false
+    const target = typeof h === "string" ? h : h(this.ctx, ...args)
+    if (typeof target === "string") this.transition(this.resolve(this.chain[this.chain.length - 1] ?? this.root, target))
+    return true
+  }
+
+  /** One tick: clocks, guards (outer first, chained), then updates (outer first). */
+  step(dt: number): void {
+    for (const n of this.chain) n.t += dt
+    this.root.t += dt
+    for (let hop = 0; hop < MAX_HOPS; hop++) {
+      const target = this.findTransition()
+      if (target === null) break
+      this.transition(target)
+    }
+    const mark = this.changed
+    const r0 = this.root.def.update?.(this.ctx, dt, this.root.t)
+    if (typeof r0 === "string") { this.transition(this.resolve(this.chain[this.chain.length - 1]!, r0)); return }
+    if (this.changed !== mark) return
+    const chain = this.chain.slice()
+    for (const n of chain) {
+      const r = n.def.update?.(this.ctx, dt, n.t)
+      if (typeof r === "string") { this.transition(this.resolve(n, r)); return }
+      if (this.changed !== mark) return   // an update transitioned through send()/go()
+    }
+  }
+
+  /** Listen for transitions. */
+  on(event: "change", fn: StateMachineEvents["change"]): this { this.listeners.push(fn); return this }
+  off(event: "change", fn: StateMachineEvents["change"]): this {
+    const i = this.listeners.indexOf(fn)
+    if (i >= 0) this.listeners.splice(i, 1)
+    return this
+  }
+
+  // ---- building ----
+  private build(name: string, path: string, def: StateDef<C>, parent: SNode<C> | null, depth: number): SNode<C> {
+    const node: SNode<C> = { name, path, def, parent, children: new Map(), initial: null, depth, t: 0, guards: [], after: null, resolved: new Map() }
+    if (path) this.byPath.set(path, node)
+    if (def.states) {
+      for (const [childName, childDef] of Object.entries(def.states)) {
+        if (childName.includes(".") || childName.startsWith("$")) throw new Error(`StateMachine: bad state name '${childName}'`)
+        node.children.set(childName, this.build(childName, path ? `${path}.${childName}` : childName, childDef, node, depth + 1))
+      }
+      const initial = def.initial ?? Object.keys(def.states)[0]!
+      const child = node.children.get(initial)
+      if (!child) throw new Error(`StateMachine: '${path || "root"}' has no child '${initial}' for initial`)
+      node.initial = child
+    } else if (def.initial) {
+      throw new Error(`StateMachine: '${path}' names an initial child but has no states`)
+    }
+    return node
+  }
+
+  private link(n: SNode<C>): void {
+    if (n.def.to) for (const [target, guard] of Object.entries(n.def.to)) n.guards.push([this.resolveStrict(n, target), guard])
+    if (n.def.after) n.after = [n.def.after[0], this.resolve(n, n.def.after[1])]
+    if (n.def.on) for (const h of Object.values(n.def.on)) if (typeof h === "string") this.resolve(n, h)
+  }
+
+  private resolveStrict(from: SNode<C>, name: string): SNode<C> {
+    const r = this.resolve(from, name)
+    if (r === BACK) throw new Error(`StateMachine: '${BACK}' is not allowed as a guard target of '${from.path}'`)
+    return r
+  }
+
+  /** Relative first (siblings of `from`, then of each ancestor), then a dotted path from the root. */
+  private resolve(from: SNode<C>, name: string): SNode<C> | typeof BACK {
+    const cached = from.resolved.get(name)
+    if (cached) return cached
+    let found: SNode<C> | typeof BACK | undefined
+    if (name === BACK) found = BACK
+    else {
+      for (let n: SNode<C> | null = from; n && !found; n = n.parent) {
+        const scope = n.parent ?? this.root
+        found = scope.children.get(name)
+        if (!found && n === from) found = n.children.get(name)   // a compound state naming its own child
+      }
+      if (!found) found = this.byPath.get(name)
+    }
+    if (!found) throw new Error(`StateMachine: unknown state '${name}' (from '${from.path || "root"}')`)
+    from.resolved.set(name, found)
+    return found
+  }
+
+  // ---- running ----
+  /** Guards never re-enter a state that is already active (a `dead` guard staying true does not
+   *  re-enter `dead` every step) — only an explicit `go()` / event does that. */
+  private findTransition(): SNode<C> | typeof BACK | null {
+    const ctx = this.ctx
+    for (const [target, guard] of this.root.guards) if (!this.active(target) && guard(ctx, this.root.t)) return target
+    for (const n of this.chain) {
+      for (const [target, guard] of n.guards) if (!this.active(target) && guard(ctx, n.t)) return target
+      if (n.after && n.t >= n.after[0] && (n.after[1] === BACK || !this.active(n.after[1]))) return n.after[1]
+    }
+    return null
+  }
+
+  private active(n: SNode<C>): boolean { return this.chain[n.depth - 1] === n }
+
+  private leafOf(n: SNode<C>): SNode<C> {
+    while (n.initial) n = n.initial
+    return n
+  }
+
+  private transition(target: SNode<C> | typeof BACK): void {
+    const current = this.chain[this.chain.length - 1] ?? null
+    let node: SNode<C>
+    if (target === BACK) {
+      if (!this.prev) return
+      node = this.prev
+    } else node = target
+    const leaf = this.leafOf(node)
+    // the new branch (root excluded)
+    const next: SNode<C>[] = []
+    for (let n: SNode<C> | null = leaf; n && n !== this.root; n = n.parent) next.unshift(n)
+    // common prefix; a target that is the current leaf or one of its ancestors re-enters itself
+    let common = 0
+    while (common < this.chain.length && common < next.length && this.chain[common] === next[common]) common++
+    if (node !== this.root && common >= node.depth && this.chain[node.depth - 1] === node) common = node.depth - 1
+    const from = current?.path ?? ""
+    const to = leaf.path
+    for (let i = this.chain.length - 1; i >= common; i--) this.chain[i]!.def.exit?.(this.ctx, to)
+    this.prev = current
+    this.enterBranch(this.chain.slice(0, common), leaf, from, next)
+  }
+
+  private enterBranch(kept: SNode<C>[], leaf: SNode<C>, from: string, next?: SNode<C>[]): void {
+    if (!next) {
+      next = []
+      for (let n: SNode<C> | null = leaf; n && n !== this.root; n = n.parent) next.unshift(n)
+    }
+    this.chain = kept.slice()
+    this.changed++
+    for (let i = kept.length; i < next.length; i++) {
+      const n = next[i]!
+      n.t = 0
+      this.chain.push(n)
+      n.def.enter?.(this.ctx, from)
+    }
+    for (const fn of this.listeners.slice()) fn(leaf.path, from)
+  }
+}

package/src/core/__tests__/stateMachine.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, test } from "bun:test"
+import { StateMachine, defineStates } from "../StateMachine"
+
+type Bot = { hp: number; target: boolean; visible: boolean; dist: number; lost: number; fire: boolean; log: string[] }
+const makeBot = (): Bot => ({ hp: 100, target: false, visible: false, dist: 99, lost: 0, fire: false, log: [] })
+
+const Guard = defineStates<Bot>({
+  initial: "patrol",
+  on: { hit: "flinch" },
+  to: { dead: (b) => b.hp <= 0 },
+  states: {
+    patrol: { enter: (b) => b.log.push("enter patrol"), exit: (b) => b.log.push("exit patrol"), to: { combat: (b) => b.target } },
+    combat: {
+      initial: "engage",
+      enter: (b) => b.log.push("enter combat"),
+      exit: (b) => b.log.push("exit combat"),
+      to: { search: (b) => b.lost > 4 },
+      states: {
+        engage: { enter: (b) => b.log.push("enter engage"), exit: (b) => b.log.push("exit engage"), to: { shoot: (b) => b.visible && b.dist < 12 } },
+        shoot: {
+          enter: (b) => { b.fire = true; b.log.push("enter shoot") },
+          exit: (b) => { b.fire = false; b.log.push("exit shoot") },
+          to: { engage: (b) => !b.visible },
+          on: { hit: (b) => (b.hp < 30 ? "combat.engage" : undefined) },
+        },
+      },
+    },
+    search: { after: [6, "patrol"], enter: (b) => b.log.push("enter search") },
+    flinch: { after: [0.2, "$back"], enter: (b) => b.log.push("enter flinch"), exit: (b) => b.log.push("exit flinch") },
+    dead: { enter: (b) => b.log.push("enter dead") },
+  },
+})
+
+const DT = 1 / 60
+
+describe("StateMachine", () => {
+  test("enters the initial state and follows guards into nested states", () => {
+    const bot = makeBot()
+    const fsm = new StateMachine(Guard, bot)
+    expect(fsm.state).toBe("patrol")
+    expect(bot.log).toEqual(["enter patrol"])
+    fsm.step(DT)
+    expect(fsm.state).toBe("patrol")
+    bot.target = true
+    fsm.step(DT)
+    expect(fsm.state).toBe("combat.engage")
+    expect(bot.log.slice(-3)).toEqual(["exit patrol", "enter combat", "enter engage"])
+    expect(fsm.is("combat")).toBe(true)
+    expect(fsm.is("engage")).toBe(true)
+    expect(fsm.is("patrol")).toBe(false)
+  })
+
+  test("a sibling transition exits and enters only the leaves", () => {
+    const bot = makeBot()
+    const fsm = new StateMachine(Guard, bot)
+    bot.target = true
+    fsm.step(DT)
+    bot.visible = true
+    bot.dist = 5
+    fsm.step(DT)
+    expect(fsm.state).toBe("combat.shoot")
+    expect(bot.fire).toBe(true)
+    expect(bot.log.slice(-2)).toEqual(["exit engage", "enter shoot"])
+  })
+
+  test("events: innermost handler wins, the root's `on` is the fallback, $back restores the previous leaf", () => {
+    const bot = makeBot()
+    const fsm = new StateMachine(Guard, bot)
+    bot.target = true; fsm.step(DT)
+    bot.visible = true; bot.dist = 5; fsm.step(DT)
+    // handled by shoot (returns undefined → stays), the root's handler is NOT consulted
+    expect(fsm.send("hit")).toBe(true)
+    expect(fsm.state).toBe("combat.shoot")
+    bot.hp = 20
+    expect(fsm.send("hit")).toBe(true)
+    expect(fsm.state).toBe("combat.engage")
+    // engage has no handler → root → flinch, leaving combat
+    bot.visible = false
+    fsm.send("hit")
+    expect(fsm.state).toBe("flinch")
+    expect(bot.log.slice(-3)).toEqual(["exit engage", "exit combat", "enter flinch"])
+    for (let i = 0; i < 13; i++) fsm.step(DT)
+    expect(fsm.state).toBe("combat.engage")
+    expect(bot.log.slice(-3)).toEqual(["exit flinch", "enter combat", "enter engage"])
+    expect(fsm.previous).toBe("flinch")
+  })
+
+  test("compound guards, timed transitions, clocks", () => {
+    const bot = makeBot()
+    const fsm = new StateMachine(Guard, bot)
+    bot.target = true; fsm.step(DT)
+    bot.lost = 5
+    fsm.step(DT)
+    expect(fsm.state).toBe("search")
+    bot.target = false; bot.lost = 0
+    for (let i = 0; i < 361; i++) fsm.step(DT)
+    expect(fsm.state).toBe("patrol")
+    expect(fsm.time).toBeLessThan(0.05)
+  })
+
+  test("go() re-enters the current state; guards never re-enter an active state", () => {
+    const bot = makeBot()
+    const fsm = new StateMachine(Guard, bot)
+    bot.log.length = 0
+    fsm.go("patrol")
+    expect(bot.log).toEqual(["exit patrol", "enter patrol"])
+    bot.hp = 0
+    bot.target = true
+    const changes: string[] = []
+    fsm.on("change", (to, from) => changes.push(`${from}>${to}`))
+    fsm.step(DT)   // the any-state `dead` guard beats patrol→combat
+    expect(fsm.state).toBe("dead")
+    fsm.step(DT); fsm.step(DT)
+    expect(changes).toEqual(["patrol>dead"])   // no dead>dead re-entries while the guard stays true
+  })
+
+  test("unknown targets throw when the machine is built", () => {
+    expect(() => new StateMachine(defineStates<{}>({ initial: "a", states: { a: { to: { nowhere: () => true } } } }), {})).toThrow(/unknown state 'nowhere'/)
+    expect(() => new StateMachine(defineStates<{}>({ initial: "zzz", states: { a: {} } }), {})).toThrow()
+  })
+
+  test("pass-through states chain within one step; update may return a target", () => {
+    const chain = new StateMachine(defineStates<{}>({ initial: "a", states: { a: { to: { b: () => true } }, b: { to: { c: () => true } }, c: {} } }), {})
+    chain.step(0)
+    expect(chain.state).toBe("c")
+    const upd = new StateMachine(defineStates<{ n: number }>({ initial: "a", states: { a: { update: (c) => (++c.n >= 3 ? "b" : undefined) }, b: {} } }), { n: 0 })
+    upd.step(0); upd.step(0)
+    expect(upd.state).toBe("a")
+    upd.step(0)
+    expect(upd.state).toBe("b")
+  })
+})