@xstate-devtools/adapter 0.1.0

package/src/core.ts

@@ -0,0 +1,639 @@
+// Transport-agnostic XState inspection core.
+// Browser and server entrypoints supply their own transports.
+import type { AnyActorRef } from 'xstate'
+import type {
+  ExtensionToPageMessage,
+  PageToExtensionMessage,
+  SerializedMachine,
+  SerializedSnapshot,
+} from '../../extension/src/shared/types.js'
+import {
+  debugLog as baseDebugLog,
+  infoLog as baseInfoLog,
+  warnLog as baseWarnLog,
+} from './logging.js'
+import { sanitize } from './sanitize.js'
+import { serializeMachine } from './serialize.js'
+
+export type Source = 'web' | 'srv'
+
+export interface InspectorOptions {
+  /**
+   * Absolute filesystem root for the web app. When provided, web stack frames
+   * like http://localhost:5173/app/... are remapped to <webSourceRoot>/app/...
+   * so VS Code source links can open local files.
+   */
+  webSourceRoot?: string
+}
+
+export interface Transport {
+  /** Send a protocol message outbound (toward the panel). */
+  send: (message: PageToExtensionMessage) => void
+  /** Subscribe to inbound dispatch messages from the panel. Returns a teardown. */
+  subscribe: (handler: (message: ExtensionToPageMessage) => void) => () => void
+}
+
+type StateValue = string | { [key: string]: StateValue }
+
+interface StateNodeLike {
+  id: string
+  key: string
+  type: 'atomic' | 'compound' | 'parallel' | 'final' | 'history' | string
+  parent?: StateNodeLike
+  states?: Record<string, StateNodeLike>
+  initial?: string | { target?: StateNodeLike[] }
+}
+
+interface MachineLike {
+  root: StateNodeLike
+  getStateNodeById: (id: string) => StateNodeLike
+  resolveState: (snapshot: {
+    value: unknown
+    context?: unknown
+    status?: string
+    output?: unknown
+    error?: unknown
+    historyValue?: unknown
+  }) => unknown
+}
+
+interface MutableActorRef extends AnyActorRef {
+  logic?: MachineLike
+  update?: (snapshot: unknown, event: { type: string; stateNodeId: string }) => void
+}
+
+function summarizeMessage(message: ExtensionToPageMessage | PageToExtensionMessage) {
+  const summary: Record<string, unknown> = { type: message.type }
+  if ('sessionId' in message) summary.sessionId = message.sessionId
+  if ('stateNodeId' in message) summary.stateNodeId = message.stateNodeId
+  if ('parentSessionId' in message && message.parentSessionId) {
+    summary.parentSessionId = message.parentSessionId
+  }
+  if ('globalSeq' in message) summary.globalSeq = message.globalSeq
+  if ('timestamp' in message) summary.timestamp = message.timestamp
+  if (
+    'event' in message &&
+    message.event &&
+    typeof message.event === 'object' &&
+    'type' in message.event
+  ) {
+    summary.eventType = message.event.type
+  }
+  return summary
+}
+
+function summarizeInspectionEvent(event: any) {
+  return {
+    type: event?.type,
+    sessionId: event?.actorRef?.sessionId,
+    eventType:
+      event?.type === '@xstate.event' && event?.event && typeof event.event === 'object'
+        ? event.event.type
+        : undefined,
+  }
+}
+
+function debugLog(source: Source, message: string, details?: unknown) {
+  baseDebugLog(`${source}:adapter`, message, details)
+}
+
+function infoLog(source: Source, message: string, details?: unknown) {
+  baseInfoLog(`${source}:adapter`, message, details)
+}
+
+function warnLog(source: Source, message: string, details?: unknown) {
+  baseWarnLog(`${source}:adapter`, message, details)
+}
+
+function isLibraryStackFrame(line: string): boolean {
+  const normalized = line.replace(/\\/g, '/').toLowerCase()
+  return (
+    normalized.includes('/node_modules/xstate/') ||
+    normalized.includes('/node_modules/@xstate/') ||
+    normalized.includes('/@xstate-devtools/adapter/') ||
+    normalized.includes('/packages/adapter/')
+  )
+}
+
+function normalizeStackFrame(line: string): string {
+  return line.trim().replace(/^at\s+/, '')
+}
+
+function extractStackFrameLocation(frame: string): string {
+  return frame.match(/\((.*)\)$/)?.[1] ?? frame
+}
+
+function isAnonymousOrEvalLocation(location: string): boolean {
+  const normalized = location
+    .trim()
+    .toLowerCase()
+    .replace(/^[./\\]+/, '')
+
+  return (
+    normalized === '<anonymous>' ||
+    normalized === 'anonymous' ||
+    normalized === '(anonymous)' ||
+    normalized === 'eval' ||
+    normalized === '<eval>' ||
+    normalized === '[native code]'
+  )
+}
+
+function hasFilesystemBackedPath(location: string): boolean {
+  const trimmed = location.trim()
+  if (!trimmed) return false
+
+  const match = trimmed.match(/^(.*?)(?::\d+)?(?::\d+)?$/)
+  const rawPath = (match?.[1] ?? trimmed).trim()
+  if (!rawPath || isAnonymousOrEvalLocation(rawPath)) return false
+
+  if (/^[a-zA-Z]:[\\/]/.test(rawPath)) return true
+  if (rawPath.startsWith('/') || rawPath.startsWith('./') || rawPath.startsWith('../')) return true
+
+  if (/^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(rawPath)) {
+    try {
+      const url = new URL(rawPath)
+      if (url.protocol === 'file:') return true
+      return url.pathname.startsWith('/@fs/')
+    } catch {
+      return false
+    }
+  }
+
+  return false
+}
+
+function remapWebUrlLocationToFsPath(
+  location: string,
+  source: Source,
+  options?: InspectorOptions,
+): string {
+  if (source !== 'web' || !options?.webSourceRoot) return location
+
+  const match = location.trim().match(/^(.*?)(?::(\d+))?(?::(\d+))?$/)
+  if (!match) return location
+
+  const [, rawPath, line, column] = match
+  if (!rawPath || !/^https?:\/\//.test(rawPath)) return location
+
+  try {
+    const url = new URL(rawPath)
+    const pathname = decodeURIComponent(url.pathname)
+    if (!pathname.startsWith('/app/')) return location
+
+    const root = options.webSourceRoot.replace(/\/+$/, '')
+    const filePath = `${root}${pathname}`
+    const suffix = line ? `:${line}${column ? `:${column}` : ''}` : ''
+    return `${filePath}${suffix}`
+  } catch {
+    return location
+  }
+}
+
+export function getSourceLocationFromStack(
+  stack?: string,
+  source: Source = 'web',
+  options?: InspectorOptions,
+): string | undefined {
+  const lines = stack?.split('\n') ?? []
+
+  for (let i = 0; i < lines.length; i += 1) {
+    if (i <= 2) continue
+
+    const line = lines[i]
+    if (isLibraryStackFrame(line)) continue
+
+    const normalizedFrame = normalizeStackFrame(line)
+    const location = remapWebUrlLocationToFsPath(
+      extractStackFrameLocation(normalizedFrame),
+      source,
+      options,
+    )
+
+    if (!hasFilesystemBackedPath(location)) continue
+
+    const wrapped = normalizedFrame.match(/\((.*)\)$/)
+    if (wrapped) {
+      return normalizedFrame.replace(wrapped[1], location)
+    }
+
+    return location
+  }
+
+  return undefined
+}
+
+function getSourceLocation(source: Source, options?: InspectorOptions): string | undefined {
+  try {
+    const oldLimit = Error.stackTraceLimit
+    Error.stackTraceLimit = 50
+    const stack = new Error().stack
+    Error.stackTraceLimit = oldLimit
+    return getSourceLocationFromStack(stack, source, options)
+  } catch {
+    return undefined
+  }
+}
+
+function serializeSnapshot(snapshot: any): SerializedSnapshot {
+  return {
+    value: snapshot?.value ?? null,
+    context: sanitize(snapshot?.context),
+    status: snapshot?.status ?? 'active',
+    error: snapshot?.error ? sanitize(snapshot.error) : undefined,
+  }
+}
+
+function safeSerializeSnapshot(actorRef: AnyActorRef): SerializedSnapshot {
+  try {
+    return serializeSnapshot(actorRef.getSnapshot())
+  } catch {
+    return { value: null, context: undefined, status: 'active' }
+  }
+}
+
+function getActorDisplayName(actorRef: AnyActorRef): string | undefined {
+  const actor = actorRef as {
+    logic?: { id?: string; src?: unknown; name?: string } | undefined
+    src?: unknown
+  }
+
+  const src = actor.src ?? actor.logic?.src
+  if (typeof src === 'string' && src.length > 0) return src
+  if (typeof actor.logic?.id === 'string' && actor.logic.id.length > 0) return actor.logic.id
+  if (typeof actor.logic?.name === 'string' && actor.logic.name.length > 0) return actor.logic.name
+  if (src && typeof src === 'object') {
+    const namedSrc = src as { id?: string; name?: string }
+    if (typeof namedSrc.id === 'string' && namedSrc.id.length > 0) return namedSrc.id
+    if (typeof namedSrc.name === 'string' && namedSrc.name.length > 0) return namedSrc.name
+  }
+  return undefined
+}
+
+function getNodeInitialChild(node: StateNodeLike): StateNodeLike | null {
+  if (!node.states) return null
+  if (typeof node.initial === 'string') {
+    return node.states[node.initial] ?? null
+  }
+
+  const target = Array.isArray(node.initial?.target) ? node.initial.target[0] : null
+  return target ?? null
+}
+
+function encodeChildValue(child: StateNodeLike, childValue: StateValue): StateValue {
+  if (child.type === 'atomic' || child.type === 'final' || child.type === 'history') {
+    return child.key
+  }
+
+  return { [child.key]: childValue }
+}
+
+function getDefaultStateValue(node: StateNodeLike): StateValue {
+  if (node.type === 'parallel') {
+    const value: Record<string, StateValue> = {}
+    for (const child of Object.values(node.states ?? {})) {
+      value[child.key] = getDefaultSelectionValue(child)
+    }
+    return value
+  }
+
+  const initialChild = getNodeInitialChild(node)
+  if (!initialChild) return {}
+  return encodeChildValue(initialChild, getDefaultStateValue(initialChild))
+}
+
+function getDefaultSelectionValue(node: StateNodeLike): StateValue {
+  if (node.type === 'atomic' || node.type === 'final' || node.type === 'history') {
+    return node.key
+  }
+
+  return getDefaultStateValue(node)
+}
+
+function getExistingChildValue(value: unknown, childKey: string): StateValue | undefined {
+  if (!value || typeof value !== 'object') return undefined
+  return (value as Record<string, StateValue>)[childKey]
+}
+
+function getPathToRoot(target: StateNodeLike, root: StateNodeLike): StateNodeLike[] {
+  const path: StateNodeLike[] = []
+  let current: StateNodeLike | undefined = target
+
+  while (current) {
+    path.unshift(current)
+    if (current.id === root.id) return path
+    current = current.parent
+  }
+
+  throw new Error(`State node '${target.id}' is not part of machine '${root.id}'`)
+}
+
+function buildTargetStateValue(
+  node: StateNodeLike,
+  path: StateNodeLike[],
+  currentValue: unknown,
+): StateValue {
+  const [, ...restPath] = path
+
+  if (restPath.length === 0) {
+    if (node.type === 'parallel') {
+      const next: Record<string, StateValue> = {}
+      for (const child of Object.values(node.states ?? {})) {
+        next[child.key] =
+          getExistingChildValue(currentValue, child.key) ?? getDefaultSelectionValue(child)
+      }
+      return next
+    }
+
+    if (node.type === 'compound') {
+      return getDefaultStateValue(node)
+    }
+
+    return node.key
+  }
+
+  const child = restPath[0]
+  if (node.type === 'parallel') {
+    const next: Record<string, StateValue> = {}
+    for (const sibling of Object.values(node.states ?? {})) {
+      if (sibling.key === child.key) {
+        next[sibling.key] = buildTargetStateValue(
+          sibling,
+          restPath,
+          getExistingChildValue(currentValue, sibling.key),
+        )
+      } else {
+        next[sibling.key] =
+          getExistingChildValue(currentValue, sibling.key) ?? getDefaultSelectionValue(sibling)
+      }
+    }
+    return next
+  }
+
+  const childValue = buildTargetStateValue(
+    child,
+    restPath,
+    getExistingChildValue(currentValue, child.key),
+  )
+  return encodeChildValue(child, childValue)
+}
+
+function setActiveState(actorRef: AnyActorRef, stateNodeId: string): void {
+  const mutableActorRef = actorRef as MutableActorRef
+  const machine = mutableActorRef.logic
+  if (
+    !machine?.getStateNodeById ||
+    !machine.resolveState ||
+    typeof mutableActorRef.update !== 'function'
+  ) {
+    throw new Error('Actor does not expose machine state mutation internals')
+  }
+
+  const currentSnapshot = actorRef.getSnapshot() as {
+    value: unknown
+    context?: unknown
+    status?: string
+    output?: unknown
+    error?: unknown
+    historyValue?: unknown
+  }
+  const targetNode = machine.getStateNodeById(stateNodeId)
+  const path = getPathToRoot(targetNode, machine.root)
+  const targetValue = buildTargetStateValue(machine.root, path, currentSnapshot?.value)
+
+  const nextSnapshot = machine.resolveState({
+    value: targetValue,
+    context: currentSnapshot?.context,
+    status: currentSnapshot?.status,
+    output: currentSnapshot?.output,
+    error: currentSnapshot?.error,
+    historyValue: currentSnapshot?.historyValue,
+  })
+
+  mutableActorRef.update(nextSnapshot, {
+    type: 'xstate.devtools.set-active-state',
+    stateNodeId,
+  })
+}
+
+// Cached on globalThis so HMR re-evaluating this module doesn't reset the
+// monotonic seq counter mid-session. The panel re-numbers messages on ingest
+// to merge multiple sources, but keeping a stable per-process seq still helps
+// when the panel reconnects to an already-running adapter.
+const SEQ_KEY = '__xstate_devtools_global_seq__'
+function nextSeq(): number {
+  const g = globalThis as Record<string, unknown>
+  const cur = (g[SEQ_KEY] as number | undefined) ?? 0
+  const next = cur + 1
+  g[SEQ_KEY] = next
+  return next
+}
+
+export function createInspector(
+  transport: Transport,
+  source: Source,
+  options: InspectorOptions = {},
+) {
+  const actorRefs = new Map<string, AnyActorRef>()
+  const actorMachines = new Map<string, SerializedMachine | null>()
+  const prefix = `${source}:`
+  const tag = (sessionId: string) => prefix + sessionId
+  const tagOptional = (id: string | undefined) => (id ? prefix + id : undefined)
+  const stripIfMine = (id: string): string | null =>
+    id.startsWith(prefix) ? id.slice(prefix.length) : null
+
+  function checkAndNotifyStop(actorRef: AnyActorRef) {
+    let snap: any
+    try {
+      snap = actorRef.getSnapshot()
+    } catch {
+      return
+    }
+    if (snap?.status !== 'active') {
+      const message: PageToExtensionMessage = {
+        type: 'XSTATE_ACTOR_STOPPED',
+        sessionId: tag(actorRef.sessionId),
+      }
+      debugLog(source, 'actor stopped; notifying transport', summarizeMessage(message))
+      transport.send(message)
+      actorRefs.delete(actorRef.sessionId)
+      actorMachines.delete(actorRef.sessionId)
+    }
+  }
+
+  const unsubscribe = transport.subscribe((message) => {
+    debugLog(source, 'received message from transport', summarizeMessage(message))
+    if (message.type === 'XSTATE_PANEL_CONNECTED') {
+      // The devtools panel just connected (or reconnected).  Re-broadcast every
+      // currently-active actor so the panel is never blank because the MV3
+      // service worker was killed between page load and panel open.
+      infoLog(source, 'panel connected; resyncing actors', { actorCount: actorRefs.size })
+      actorRefs.forEach((actorRef, sessionId) => {
+        const machine = actorMachines.get(sessionId) ?? null
+        const resyncMessage: PageToExtensionMessage = {
+          type: 'XSTATE_ACTOR_REGISTERED',
+          sessionId: tag(sessionId),
+          parentSessionId: tagOptional((actorRef as any)._parent?.sessionId),
+          displayName: getActorDisplayName(actorRef),
+          machine,
+          snapshot: safeSerializeSnapshot(actorRef),
+          globalSeq: nextSeq(),
+          timestamp: Date.now(),
+        }
+        debugLog(source, 'resyncing actor', summarizeMessage(resyncMessage))
+        transport.send(resyncMessage)
+      })
+      return
+    }
+    if (message.type === 'XSTATE_DISPATCH') {
+      const local = stripIfMine(message.sessionId)
+      if (local === null) {
+        debugLog(source, 'ignoring dispatch for different source', summarizeMessage(message))
+        return // not for this transport source
+      }
+      const ref = actorRefs.get(local)
+      if (ref) {
+        try {
+          debugLog(source, 'dispatching event to actor', {
+            sessionId: local,
+            eventType:
+              message.event && typeof message.event === 'object' && 'type' in message.event
+                ? message.event.type
+                : undefined,
+          })
+          ref.send(message.event)
+        } catch (e) {
+          warnLog(source, 'dispatch error', { error: e, sessionId: local })
+        }
+      } else {
+        warnLog(source, 'received dispatch for unknown actor', {
+          sessionId: local,
+          knownActors: actorRefs.size,
+        })
+      }
+      return
+    }
+    if (message.type === 'XSTATE_SET_ACTIVE_STATE') {
+      const local = stripIfMine(message.sessionId)
+      if (local === null) {
+        debugLog(
+          source,
+          'ignoring state activation for different source',
+          summarizeMessage(message),
+        )
+        return
+      }
+
+      const ref = actorRefs.get(local)
+      if (!ref) {
+        warnLog(source, 'received state activation for unknown actor', {
+          sessionId: local,
+          knownActors: actorRefs.size,
+        })
+        return
+      }
+
+      try {
+        debugLog(source, 'setting active state on actor', summarizeMessage(message))
+        setActiveState(ref, message.stateNodeId)
+        const snapshotMessage: PageToExtensionMessage = {
+          type: 'XSTATE_SNAPSHOT',
+          sessionId: tag(local),
+          snapshot: safeSerializeSnapshot(ref),
+          timestamp: Date.now(),
+          globalSeq: nextSeq(),
+        }
+        debugLog(
+          source,
+          'sending snapshot after state activation',
+          summarizeMessage(snapshotMessage),
+        )
+        transport.send(snapshotMessage)
+      } catch (error) {
+        warnLog(source, 'failed to set active state', {
+          error,
+          sessionId: local,
+          stateNodeId: message.stateNodeId,
+        })
+      }
+    }
+  })
+
+  // Notify the extension that the adapter is ready
+  transport.send({ type: 'XSTATE_ADAPTER_READY' })
+
+  infoLog(source, 'inspector created')
+
+  const inspect = (inspectionEvent: any) => {
+    debugLog(source, 'inspect callback invoked', summarizeInspectionEvent(inspectionEvent))
+    if (inspectionEvent.type === '@xstate.actor') {
+      const actorRef: AnyActorRef = inspectionEvent.actorRef
+      const sessionId: string = actorRef.sessionId
+      actorRefs.set(sessionId, actorRef)
+
+      const actorLogic = (actorRef as { logic?: unknown }).logic as any
+      const machine = actorLogic?.root
+        ? serializeMachine(
+            actorLogic,
+            actorLogic.config?.__xstateDevtoolsSource ?? getSourceLocation(source, options),
+          )
+        : null
+      actorMachines.set(sessionId, machine)
+
+      const message: PageToExtensionMessage = {
+        type: 'XSTATE_ACTOR_REGISTERED',
+        sessionId: tag(sessionId),
+        parentSessionId: tagOptional((actorRef as any)._parent?.sessionId),
+        displayName: getActorDisplayName(actorRef),
+        machine,
+        snapshot: safeSerializeSnapshot(actorRef),
+        globalSeq: nextSeq(),
+        timestamp: Date.now(),
+      }
+      infoLog(source, 'registering actor with transport', {
+        message: summarizeMessage(message),
+        actorCount: actorRefs.size,
+        hasMachine: machine !== null,
+      })
+      transport.send(message)
+    } else if (inspectionEvent.type === '@xstate.snapshot') {
+      const message: PageToExtensionMessage = {
+        type: 'XSTATE_SNAPSHOT',
+        sessionId: tag(inspectionEvent.actorRef.sessionId),
+        snapshot: serializeSnapshot(inspectionEvent.snapshot),
+        timestamp: Date.now(),
+        globalSeq: nextSeq(),
+      }
+      debugLog(source, 'sending snapshot to transport', summarizeMessage(message))
+      transport.send(message)
+      checkAndNotifyStop(inspectionEvent.actorRef)
+    } else if (inspectionEvent.type === '@xstate.event') {
+      const message: PageToExtensionMessage = {
+        type: 'XSTATE_EVENT',
+        sessionId: tag(inspectionEvent.actorRef.sessionId),
+        event: sanitize(inspectionEvent.event),
+        snapshotAfter: safeSerializeSnapshot(inspectionEvent.actorRef),
+        timestamp: Date.now(),
+        globalSeq: nextSeq(),
+      }
+      debugLog(source, 'sending event to transport', summarizeMessage(message))
+      transport.send(message)
+      checkAndNotifyStop(inspectionEvent.actorRef)
+    } else {
+      debugLog(
+        source,
+        'ignoring unsupported inspection event',
+        summarizeInspectionEvent(inspectionEvent),
+      )
+    }
+  }
+
+  function dispose() {
+    infoLog(source, 'disposing inspector', { actorCount: actorRefs.size })
+    unsubscribe()
+    actorRefs.clear()
+    actorMachines.clear()
+  }
+
+  return { inspect, dispose }
+}

package/src/index.ts

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