@xstate-devtools/adapter 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate-devtools/adapter",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {

package/src/core.ts

@@ -569,44 +569,45 @@ export function createInspector(
     if (inspectionEvent.type === '@xstate.actor') {
       const actorRef: AnyActorRef = inspectionEvent.actorRef
       const sessionId: string = actorRef.sessionId
+
+      // Serialize machine and populate both Maps BEFORE subscribing so that
+      // the Maps are fully consistent if complete()/error() ever fire
+      // synchronously during subscribe() (e.g. an actor that starts in a
+      // final state).  Populating after subscribe introduced a race where
+      // actorMachines.delete() in the callback was a no-op and the subsequent
+      // actorMachines.set() would leak the entry permanently.
+      const actorLogic = (actorRef as { logic?: unknown }).logic as any
+      const machine = actorLogic?.root
+        ? serializeMachine(
+            actorLogic,
+            actorLogic.config?.__xstateDevtoolsSource ?? getSourceLocation(source, options),
+          )
+        : null
       actorRefs.set(sessionId, actorRef)
+      actorMachines.set(sessionId, machine)
 
       // Eagerly remove the actor from both maps when it stops so we don't
       // accumulate strong references to every short-lived actor indefinitely.
       // Without this, actors that stop silently (no further snapshot/event) are
       // only removed by checkAndNotifyStop — which never fires for them.
+      const notifyStop = () => {
+        if (actorRefs.has(sessionId)) {
+          actorRefs.delete(sessionId)
+          actorMachines.delete(sessionId)
+          const stopMsg: PageToExtensionMessage = {
+            type: 'XSTATE_ACTOR_STOPPED',
+            sessionId: tag(sessionId),
+          }
+          debugLog(source, 'actor stopped; notifying transport', summarizeMessage(stopMsg))
+          transport.send(stopMsg)
+        }
+      }
       try {
-        actorRef.subscribe({
-          complete: () => {
-            if (actorRefs.has(sessionId)) {
-              actorRefs.delete(sessionId)
-              actorMachines.delete(sessionId)
-              const stopMsg: PageToExtensionMessage = {
-                type: 'XSTATE_ACTOR_STOPPED',
-                sessionId: tag(sessionId),
-              }
-              debugLog(source, 'actor completed; notifying transport', summarizeMessage(stopMsg))
-              transport.send(stopMsg)
-            }
-          },
-          error: () => {
-            actorRefs.delete(sessionId)
-            actorMachines.delete(sessionId)
-          },
-        })
+        actorRef.subscribe({ complete: notifyStop, error: notifyStop })
       } catch {
         // subscribe is best-effort; older actor implementations may not support it
       }
 
-      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),

package/src/server.ts

@@ -1,5 +1,6 @@
 // Server entrypoint — exposes a WebSocket bridge so the DevTools panel
 // can connect to actors running in Node.
+import { createServer as createTcpServer } from 'node:net'
 import type {
   ExtensionToPageMessage,
   PageToExtensionMessage,
@@ -12,6 +13,28 @@ import {
 } from './logging.js'
 import { sanitize } from './sanitize.js'
 
+/**
+ * Find the lowest TCP port >= `start` that is not currently in use.
+ * Uses a temporary TCP server to probe; the port is released before resolving.
+ */
+function getAvailablePort(start: number): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const probe = createTcpServer()
+    probe.unref()
+    probe.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(getAvailablePort(start + 1))
+      } else {
+        reject(err)
+      }
+    })
+    probe.listen(start, '127.0.0.1', () => {
+      const port = (probe.address() as { port: number }).port
+      probe.close(() => resolve(port))
+    })
+  })
+}
+
 export interface ServerAdapterOptions {
   /** Port to listen on. Defaults to env XSTATE_DEVTOOLS_PORT or 9301. */
   port?: number
@@ -89,6 +112,8 @@ interface CachedServer {
   buffer: string[]
   bufferSize: number
   activated: boolean
+  /** Resolves with the actual TCP port once the WS server is listening. */
+  port: Promise<number>
   close: () => void
 }
 
@@ -132,12 +157,20 @@ export function createServerAdapter(options: ServerAdapterOptions = {}) {
     let wss: any = null
     let closed = false
 
+    let portResolve!: (port: number) => void
+    let portReject!: (err: unknown) => void
+    const portPromise = new Promise<number>((res, rej) => {
+      portResolve = res
+      portReject = rej
+    })
+
     server = {
       clients,
       dispatchHandlers,
       buffer,
       bufferSize,
       activated: false,
+      port: portPromise,
       close: () => {
         closed = true
         infoLog('closing WebSocket server', { host, port, clientCount: clients.size })
@@ -160,8 +193,12 @@ export function createServerAdapter(options: ServerAdapterOptions = {}) {
         const mod = await import('ws')
         const WSServer = (mod as any).WebSocketServer ?? (mod as any).Server
         if (closed) return
-        wss = new WSServer({ port, host })
-        infoLog('WebSocket server listening', { host, port })
+        const actualPort = await getAvailablePort(port)
+        if (closed) return
+        wss = new WSServer({ port: actualPort, host })
+        process.env.XSTATE_DEVTOOLS_PORT = String(actualPort)
+        portResolve(actualPort)
+        infoLog('WebSocket server listening', { host, port: actualPort })
         wss.on('connection', (ws: ClientLike) => {
           infoLog('panel connected to WebSocket server', {
             host,
@@ -214,6 +251,7 @@ export function createServerAdapter(options: ServerAdapterOptions = {}) {
           warnLog('WS server error', { host, port, message: err.message })
         })
       } catch (e) {
+        portReject(e)
         warnLog('could not start server adapter — install `ws` to enable', {
           host,
           port,
@@ -268,5 +306,5 @@ export function createServerAdapter(options: ServerAdapterOptions = {}) {
   }
 
   const inspector = createInspector(transport, 'srv')
-  return { ...inspector, close: server.close }
+  return { ...inspector, close: server.close, port: server.port }
 }