@xstate-devtools/adapter 0.1.3 → 0.1.4

package/src/index.ts

@@ -1,73 +0,0 @@
-// Browser entrypoint — uses window.postMessage via the extension's injected bridge.
-import type {
-  ExtensionToPageMessage,
-  PageToExtensionMessage,
-} from '../../extension/src/shared/types.js'
-import { createInspector, type InspectorOptions, type Transport } from './core.js'
-import { debugLog, infoLog, warnLog } from './logging.js'
-
-declare global {
-  interface Window {
-    __XSTATE_DEVTOOLS__?: {
-      send: (message: unknown) => void
-    }
-  }
-}
-
-export function createAdapter(options: InspectorOptions = {}) {
-  if (typeof window === 'undefined') {
-    // Non-browser env (SSR/SSG/server) — return a no-op so importing this module is safe.
-    infoLog('web:adapter', 'createAdapter called without window; returning no-op adapter')
-    return { inspect: () => {}, dispose: () => {} }
-  }
-
-  infoLog('web:adapter', 'creating browser adapter', {
-    hookInstalled: Boolean(window.__XSTATE_DEVTOOLS__),
-  })
-
-  let warnedMissingHook = false
-
-  const transport: Transport = {
-    send(message: PageToExtensionMessage) {
-      const payload = { ...message, __xstateDevtools: true as const }
-      debugLog('web:adapter', 'sending message via page hook', {
-        type: message.type,
-        sessionId: 'sessionId' in message ? message.sessionId : undefined,
-      })
-      if (window.__XSTATE_DEVTOOLS__) {
-        window.__XSTATE_DEVTOOLS__.send(payload)
-        return
-      }
-
-      if (!warnedMissingHook) {
-        warnedMissingHook = true
-        warnLog('web:adapter', 'page hook missing; using direct window.postMessage fallback')
-      }
-      // Fallback keeps inspection working if MAIN-world injection is unavailable.
-      window.postMessage(payload, '*')
-    },
-    subscribe(handler) {
-      infoLog('web:adapter', 'subscribing to window messages')
-      const onMessage = (evt: MessageEvent) => {
-        if (evt.source !== window) return
-        const data = evt.data
-        if (!data?.__xstateDevtools) return
-        debugLog('web:adapter', 'received message from window bridge', {
-          type: (data as ExtensionToPageMessage).type,
-          sessionId:
-            'sessionId' in (data as ExtensionToPageMessage)
-              ? (data as ExtensionToPageMessage & { sessionId?: string }).sessionId
-              : undefined,
-        })
-        handler(data as ExtensionToPageMessage)
-      }
-      window.addEventListener('message', onMessage)
-      return () => {
-        infoLog('web:adapter', 'unsubscribing from window messages')
-        window.removeEventListener('message', onMessage)
-      }
-    },
-  }
-
-  return createInspector(transport, 'web', options)
-}

package/src/logging.test.ts

@@ -1,39 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,50 +0,0 @@
-// 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

@@ -1,68 +0,0 @@
-// 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

@@ -1,70 +0,0 @@
-// 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

@@ -1,170 +0,0 @@
-// 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

@@ -1,148 +0,0 @@
-// 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,
-  }
-}