@xstate-devtools/adapter 0.1.0

package/src/logging.test.ts

@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { debugLog, infoLog, isLoggingEnabled, warnLog } from './logging.js'
+
+describe('adapter logging', () => {
+  afterEach(() => {
+    delete globalThis.__XSTATE_DEVTOOLS_LOGGING__
+    vi.unstubAllEnvs()
+    vi.restoreAllMocks()
+  })
+
+  it('is disabled by default', () => {
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
+    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {})
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    expect(isLoggingEnabled()).toBe(false)
+
+    debugLog('web:adapter', 'debug message')
+    infoLog('web:adapter', 'info message')
+    warnLog('web:adapter', 'warn message')
+
+    expect(debugSpy).not.toHaveBeenCalled()
+    expect(infoSpy).not.toHaveBeenCalled()
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('can be enabled explicitly', () => {
+    vi.stubEnv('XSTATE_DEVTOOLS_LOGGING', 'true')
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
+
+    expect(isLoggingEnabled()).toBe(true)
+
+    debugLog('web:adapter', 'debug message', { enabled: true })
+
+    expect(debugSpy).toHaveBeenCalledWith('[xstate-devtools:web:adapter] debug message', {
+      enabled: true,
+    })
+  })
+})

package/src/logging.ts

@@ -0,0 +1,40 @@
+type LogLevel = 'debug' | 'info' | 'warn'
+
+declare global {
+  var __XSTATE_DEVTOOLS_LOGGING__: boolean | undefined
+}
+
+function hasProcessEnv() {
+  return typeof process !== 'undefined' && typeof process.env !== 'undefined'
+}
+
+export function isLoggingEnabled() {
+  if (globalThis.__XSTATE_DEVTOOLS_LOGGING__ === true) return true
+  if (!hasProcessEnv()) return false
+
+  const value = process.env.XSTATE_DEVTOOLS_LOGGING
+  return value === '1' || value === 'true'
+}
+
+function log(level: LogLevel, scope: string, message: string, details?: unknown) {
+  if (!isLoggingEnabled()) return
+
+  if (details === undefined) {
+    console[level](`[xstate-devtools:${scope}] ${message}`)
+    return
+  }
+
+  console[level](`[xstate-devtools:${scope}] ${message}`, details)
+}
+
+export function debugLog(scope: string, message: string, details?: unknown) {
+  log('debug', scope, message, details)
+}
+
+export function infoLog(scope: string, message: string, details?: unknown) {
+  log('info', scope, message, details)
+}
+
+export function warnLog(scope: string, message: string, details?: unknown) {
+  log('warn', scope, message, details)
+}

package/src/react.tsx

@@ -0,0 +1,50 @@
+// packages/adapter/src/react.tsx
+
+import { useActorRef as useXStateActorRef, useMachine as useXStateMachine } from '@xstate/react'
+import { createContext, type ReactNode, useContext, useEffect, useRef } from 'react'
+import type { ActorOptions, AnyStateMachine } from 'xstate'
+import { createAdapter } from './index.js'
+
+type AdapterContext = ReturnType<typeof createAdapter> | null
+
+const InspectorContext = createContext<AdapterContext>(null)
+
+export function InspectorProvider({ children }: { children: ReactNode }) {
+  const adapterRef = useRef<ReturnType<typeof createAdapter> | null>(null)
+  if (!adapterRef.current && typeof window !== 'undefined') {
+    adapterRef.current = createAdapter()
+  }
+
+  useEffect(() => {
+    return () => {
+      adapterRef.current?.dispose()
+      adapterRef.current = null
+    }
+  }, [])
+
+  return (
+    <InspectorContext.Provider value={adapterRef.current}>{children}</InspectorContext.Provider>
+  )
+}
+
+export function useInspectedMachine<T extends AnyStateMachine>(
+  machine: T,
+  options?: ActorOptions<T>,
+) {
+  const adapter = useContext(InspectorContext)
+  return useXStateMachine(machine, {
+    ...options,
+    inspect: adapter?.inspect,
+  })
+}
+
+export function useInspectedActorRef<T extends AnyStateMachine>(
+  machine: T,
+  options?: ActorOptions<T>,
+) {
+  const adapter = useContext(InspectorContext)
+  return useXStateActorRef(machine, {
+    ...options,
+    inspect: adapter?.inspect,
+  })
+}

package/src/sanitize.test.ts

@@ -0,0 +1,68 @@
+// packages/adapter/src/sanitize.test.ts
+import { describe, expect, it } from 'vitest'
+import { sanitize } from './sanitize.js'
+
+describe('sanitize', () => {
+  it('passes primitives through unchanged', () => {
+    expect(sanitize(42)).toBe(42)
+    expect(sanitize(true)).toBe(true)
+    expect(sanitize(null)).toBe(null)
+    expect(sanitize('hello')).toBe('hello')
+  })
+
+  it('replaces functions with a descriptor string', () => {
+    expect(sanitize(function myFn() {})).toBe('[Function: myFn]')
+    expect(sanitize(() => {})).toBe('[Function: (anonymous)]')
+  })
+
+  it('truncates long strings', () => {
+    const long = 'x'.repeat(600)
+    const result = sanitize(long) as string
+    expect(result.length).toBeLessThan(520)
+    expect(result.endsWith('…')).toBe(true)
+  })
+
+  it('handles nested objects', () => {
+    const result = sanitize({ a: 1, b: { c: 'hello' } })
+    expect(result).toEqual({ a: 1, b: { c: 'hello' } })
+  })
+
+  it('handles Maps', () => {
+    const m = new Map([['key', 'value']])
+    const result = sanitize(m) as any
+    expect(result.__type).toBe('Map')
+    expect(result.entries).toEqual([['key', 'value']])
+  })
+
+  it('handles actual circular references', () => {
+    const a: any = {}
+    a.self = a
+    expect(() => sanitize(a)).not.toThrow()
+    expect(JSON.stringify(sanitize(a))).toContain('[Circular]')
+  })
+
+  it('handles deep linear nesting', () => {
+    const deep: any = {}
+    let curr = deep
+    for (let i = 0; i < 15; i++) {
+      curr.child = {}
+      curr = curr.child
+    }
+    curr.value = 'bottom'
+    const result = JSON.stringify(sanitize(deep))
+    expect(result).toContain('[MaxDepth]')
+  })
+
+  it('does not duplicate shared objects across branches', () => {
+    const shared = { nested: { value: 'shared' } }
+    const value = {
+      first: shared,
+      second: shared,
+    }
+
+    const result = sanitize(value) as Record<string, unknown>
+
+    expect(result.first).toEqual({ nested: { value: 'shared' } })
+    expect(result.second).toBe('[Circular]')
+  })
+})

package/src/sanitize.ts

@@ -0,0 +1,70 @@
+// packages/adapter/src/sanitize.ts
+
+const MAX_DEPTH = 10
+const MAX_STRING_LENGTH = 500
+const MAX_ARRAY_LENGTH = 100
+
+function sanitizeValue(value: unknown, depth: number, seen: WeakSet<object>): unknown {
+  if (depth > MAX_DEPTH) return '[MaxDepth]'
+  if (value === null || value === undefined) return value
+  if (typeof value === 'boolean' || typeof value === 'number') return value
+  if (typeof value === 'string') {
+    return value.length > MAX_STRING_LENGTH ? `${value.slice(0, MAX_STRING_LENGTH)}…` : value
+  }
+  if (typeof value === 'function') return `[Function: ${value.name || '(anonymous)'}]`
+  if (typeof value === 'symbol') return `[Symbol: ${value.description ?? ''}]`
+  if (typeof value === 'bigint') return `[BigInt: ${value}]`
+  if (value instanceof Error) return { __type: 'Error', name: value.name, message: value.message }
+  if (value instanceof Date) return { __type: 'Date', iso: value.toISOString() }
+  if (value instanceof RegExp) return { __type: 'RegExp', source: value.source, flags: value.flags }
+  if (typeof value === 'object') {
+    if (seen.has(value)) return '[Circular]'
+    seen.add(value)
+  }
+  if (value instanceof Map) {
+    const entries: [unknown, unknown][] = []
+    for (const [k, v] of value as Map<unknown, unknown>) {
+      if (entries.length >= MAX_ARRAY_LENGTH) break
+      entries.push([sanitizeValue(k, depth + 1, seen), sanitizeValue(v, depth + 1, seen)])
+    }
+    return { __type: 'Map', entries }
+  }
+  if (value instanceof Set) {
+    const values: unknown[] = []
+    for (const v of value as Set<unknown>) {
+      if (values.length >= MAX_ARRAY_LENGTH) break
+      values.push(sanitizeValue(v, depth + 1, seen))
+    }
+    return { __type: 'Set', values }
+  }
+  if (value instanceof Promise) return '[Promise]'
+  if (value instanceof WeakMap || value instanceof WeakSet) return '[WeakCollection]'
+  if (ArrayBuffer.isView(value)) return `[TypedArray: ${(value as any).constructor.name}]`
+  // Detect DOM nodes (works in browser and is safe to check)
+  if (typeof Node !== 'undefined' && value instanceof Node) {
+    return `[DOMNode: ${(value as Element).tagName ?? value.nodeName}]`
+  }
+  if (Array.isArray(value)) {
+    const sliced = value.slice(0, MAX_ARRAY_LENGTH)
+    const result = sliced.map((v) => sanitizeValue(v, depth + 1, seen))
+    if (value.length > MAX_ARRAY_LENGTH) result.push(`[…${value.length - MAX_ARRAY_LENGTH} more]`)
+    return result
+  }
+  if (typeof value === 'object') {
+    const result: Record<string, unknown> = {}
+    let count = 0
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (count++ >= MAX_ARRAY_LENGTH) {
+        result['…'] = '[truncated]'
+        break
+      }
+      result[k] = sanitizeValue(v, depth + 1, seen)
+    }
+    return result
+  }
+  return String(value)
+}
+
+export function sanitize(value: unknown, depth = 0): unknown {
+  return sanitizeValue(value, depth, new WeakSet<object>())
+}

package/src/serialize.test.ts

@@ -0,0 +1,170 @@
+// packages/adapter/src/serialize.test.ts
+import { describe, expect, it } from 'vitest'
+import { createMachine, fromPromise, setup } from 'xstate'
+import { serializeMachine } from './serialize.js'
+
+describe('serializeMachine', () => {
+  it('serializes a simple compound machine', () => {
+    const machine = createMachine({
+      id: 'test',
+      initial: 'idle',
+      states: {
+        idle: { on: { START: 'running' } },
+        running: { on: { STOP: 'idle' } },
+      },
+    })
+    const result = serializeMachine(machine)
+    expect(result.id).toBe('test')
+    expect(result.root.type).toBe('compound')
+    expect(result.root.initial).toBe('idle')
+    expect(Object.keys(result.root.states)).toEqual(['idle', 'running'])
+    expect(result.root.states.idle.on).toHaveLength(1)
+    expect(result.root.states.idle.on[0].eventType).toBe('START')
+    expect(result.root.states.idle.on[0].targets).toEqual(['test.running'])
+  })
+
+  it('serializes parallel states', () => {
+    const machine = createMachine({
+      id: 'parallel',
+      type: 'parallel',
+      states: {
+        a: { initial: 'on', states: { on: {}, off: {} } },
+        b: { initial: 'on', states: { on: {}, off: {} } },
+      },
+    })
+    const result = serializeMachine(machine)
+    expect(result.root.type).toBe('parallel')
+    expect(Object.keys(result.root.states)).toEqual(['a', 'b'])
+  })
+
+  it('serializes named guards and actions from setup()', () => {
+    const machine = setup({
+      guards: { isReady: () => true },
+      actions: { doSomething: () => {} },
+    }).createMachine({
+      id: 'guarded',
+      initial: 'idle',
+      states: {
+        idle: {
+          on: {
+            GO: {
+              target: 'active',
+              guard: 'isReady',
+              actions: 'doSomething',
+            },
+          },
+        },
+        active: {},
+      },
+    })
+    const result = serializeMachine(machine)
+    const transition = result.root.states.idle.on[0]
+    expect(transition.guard).toBe('isReady')
+    expect(transition.actions).toEqual(['doSomething'])
+  })
+
+  it('serializes always transitions', () => {
+    const machine = createMachine({
+      id: 'always-test',
+      initial: 'checking',
+      states: {
+        checking: {
+          always: [{ target: 'done' }],
+        },
+        done: {},
+      },
+    })
+    const result = serializeMachine(machine)
+    expect(result.root.states.checking.always).toHaveLength(1)
+    expect(result.root.states.checking.always[0].targets).toContain('always-test.done')
+  })
+
+  it('serializes invoked services', () => {
+    const fetchActor = fromPromise(async () => ({ data: 'ok' }))
+    const machine = setup({
+      actors: { fetchData: fetchActor },
+    }).createMachine({
+      id: 'invoke-test',
+      initial: 'loading',
+      states: {
+        loading: {
+          invoke: {
+            id: 'fetch',
+            src: 'fetchData',
+            onDone: 'done',
+          },
+        },
+        done: {},
+      },
+    })
+    const result = serializeMachine(machine)
+    expect(result.root.states.loading.invoke).toHaveLength(1)
+    expect(result.root.states.loading.invoke[0].id).toBe('fetch')
+    expect(result.root.states.loading.invoke[0].src).toBeTruthy()
+  })
+
+  it('includes sourceLocation when provided', () => {
+    const machine = createMachine({ id: 'm', initial: 'a', states: { a: {} } })
+    const result = serializeMachine(machine, 'src/auth.ts:42')
+    expect(result.sourceLocation).toBe('src/auth.ts:42')
+  })
+
+  it('handles cyclic machine node graphs without recursing forever', () => {
+    const root: any = {
+      id: 'root',
+      key: 'root',
+      type: 'compound',
+      states: {},
+      transitions: new Map(),
+      always: [],
+      entry: [],
+      exit: [],
+      invoke: [],
+    }
+    root.states.self = root
+
+    const result = serializeMachine({ id: 'cyclic', root } as any)
+
+    expect(result.root.id).toBe('root')
+    expect(result.root.states.self.id).toBe('root')
+    expect(result.root.states.self.states).toEqual({})
+  })
+
+  it('caps the number of serialized child states', () => {
+    const states = Object.fromEntries(
+      Array.from({ length: 150 }, (_, index) => [
+        `state${index}`,
+        {
+          id: `machine.state${index}`,
+          key: `state${index}`,
+          type: 'atomic',
+          states: {},
+          transitions: new Map(),
+          always: [],
+          entry: [],
+          exit: [],
+          invoke: [],
+        },
+      ]),
+    )
+
+    const machine = {
+      id: 'bounded',
+      root: {
+        id: 'bounded',
+        key: 'bounded',
+        type: 'compound',
+        states,
+        transitions: new Map(),
+        always: [],
+        entry: [],
+        exit: [],
+        invoke: [],
+      },
+    } as any
+
+    const result = serializeMachine(machine)
+
+    expect(Object.keys(result.root.states)).toHaveLength(100)
+  })
+})

package/src/serialize.ts

@@ -0,0 +1,148 @@
+// packages/adapter/src/serialize.ts
+import type { AnyStateMachine } from 'xstate'
+import type {
+  SerializedInvoke,
+  SerializedMachine,
+  SerializedStateNode,
+  SerializedTransition,
+} from '../../extension/src/shared/types.js'
+
+const MAX_SERIALIZED_NODES = 500
+const MAX_TRANSITIONS_PER_NODE = 100
+const MAX_CHILD_STATES = 100
+const MAX_ACTIONS_PER_TRANSITION = 20
+const MAX_ENTRY_EXIT_ACTIONS = 20
+const MAX_INVOKES_PER_NODE = 20
+
+function serializeGuard(guard: unknown): string | undefined {
+  if (!guard) return undefined
+  if (typeof guard === 'string') return guard
+  if (typeof guard === 'function') return (guard as Function).name || '(inline)'
+  if (typeof guard === 'object' && guard !== null) {
+    const g = guard as any
+    return g.type ?? g.name ?? '(inline)'
+  }
+  return '(inline)'
+}
+
+function serializeAction(action: unknown): string {
+  if (typeof action === 'string') return action
+  if (typeof action === 'function') return (action as Function).name || '(anonymous)'
+  if (typeof action === 'object' && action !== null) {
+    const a = action as any
+    return a.type ?? a.name ?? String(action)
+  }
+  return String(action)
+}
+
+function serializeTransitionList(transitions: any[]): SerializedTransition[] {
+  return transitions.slice(0, MAX_TRANSITIONS_PER_NODE).map((t: any) => ({
+    eventType: t.eventType ?? '',
+    targets: (t.target ?? []).map((n: any) => n?.id ?? String(n)).filter(Boolean),
+    guard: serializeGuard(t.guard),
+    actions: (t.actions ?? [])
+      .slice(0, MAX_ACTIONS_PER_TRANSITION)
+      .map(serializeAction)
+      .filter(Boolean),
+  }))
+}
+
+function serializeInvokes(node: any): SerializedInvoke[] {
+  return (node.invoke as any[]).slice(0, MAX_INVOKES_PER_NODE).map((inv: any) => ({
+    id: inv.id ?? '(unknown)',
+    src: typeof inv.src === 'string' ? inv.src : (inv.src?.id ?? inv.src?.name ?? '(inline)'),
+  }))
+}
+
+interface SerializeState {
+  seen: WeakSet<object>
+  count: number
+}
+
+function serializeNode(node: any, state: SerializeState): SerializedStateNode {
+  if (!node || typeof node !== 'object') {
+    return {
+      id: '(unknown)',
+      key: '(unknown)',
+      type: 'atomic',
+      states: {},
+      on: [],
+      always: [],
+      entry: [],
+      exit: [],
+      invoke: [],
+    }
+  }
+
+  if (state.count >= MAX_SERIALIZED_NODES) {
+    return {
+      id: node.id ?? '(truncated)',
+      key: node.key ?? '(truncated)',
+      type: node.type ?? 'atomic',
+      states: {},
+      on: [],
+      always: [],
+      entry: [],
+      exit: [],
+      invoke: [],
+    }
+  }
+
+  if (state.seen.has(node)) {
+    return {
+      id: node.id ?? '(circular)',
+      key: node.key ?? '(circular)',
+      type: node.type ?? 'atomic',
+      states: {},
+      on: [],
+      always: [],
+      entry: [],
+      exit: [],
+      invoke: [],
+    }
+  }
+
+  state.seen.add(node)
+  state.count += 1
+
+  const allTransitions: SerializedTransition[] = []
+  if (node.transitions instanceof Map) {
+    for (const [, tList] of node.transitions) {
+      if (allTransitions.length >= MAX_TRANSITIONS_PER_NODE) break
+      allTransitions.push(...serializeTransitionList(tList))
+      if (allTransitions.length >= MAX_TRANSITIONS_PER_NODE) {
+        allTransitions.length = MAX_TRANSITIONS_PER_NODE
+        break
+      }
+    }
+  }
+
+  const always = Array.isArray(node.always) ? serializeTransitionList(node.always) : []
+  const childEntries = Object.entries(node.states ?? {}).slice(0, MAX_CHILD_STATES)
+
+  return {
+    id: node.id,
+    key: node.key,
+    type: node.type,
+    initial: node.initial?.target?.[0]?.key,
+    states: Object.fromEntries(childEntries.map(([k, v]) => [k, serializeNode(v, state)])),
+    on: allTransitions,
+    always,
+    entry: (node.entry ?? []).slice(0, MAX_ENTRY_EXIT_ACTIONS).map(serializeAction).filter(Boolean),
+    exit: (node.exit ?? []).slice(0, MAX_ENTRY_EXIT_ACTIONS).map(serializeAction).filter(Boolean),
+    invoke: serializeInvokes(node),
+    sourceLocation: node.config?.__xstateDevtoolsSource ?? undefined,
+    description: node.config?.description ?? undefined,
+  }
+}
+
+export function serializeMachine(
+  machine: AnyStateMachine,
+  sourceLocation?: string,
+): SerializedMachine {
+  return {
+    id: machine.id,
+    root: serializeNode(machine.root, { seen: new WeakSet<object>(), count: 0 }),
+    sourceLocation,
+  }
+}