@xstate-devtools/adapter 0.1.3 → 0.1.5

package/dist/server.js

@@ -0,0 +1,164 @@
+import {
+  createInspector
+} from "./chunk-QLRTDBT5.js";
+
+// src/server.ts
+var OPEN_STATE = 1;
+function trackLive(server, message) {
+  switch (message.type) {
+    case "XSTATE_ACTOR_REGISTERED":
+      server.liveActors.set(message.sessionId, { reg: message, snapshot: message.snapshot });
+      break;
+    case "XSTATE_SNAPSHOT": {
+      const live = server.liveActors.get(message.sessionId);
+      if (live) {
+        live.snapshot = message.snapshot;
+      }
+      break;
+    }
+    case "XSTATE_EVENT": {
+      const live = server.liveActors.get(message.sessionId);
+      if (live) {
+        live.snapshot = message.snapshotAfter;
+      }
+      break;
+    }
+    case "XSTATE_ACTOR_STOPPED":
+      server.liveActors.delete(message.sessionId);
+      break;
+  }
+}
+function createServerAdapter(options = {}) {
+  const port = options.port ?? (Number(process.env.XSTATE_DEVTOOLS_PORT) || 9301);
+  const host = options.host ?? "127.0.0.1";
+  const bufferSize = options.bufferSize ?? 200;
+  const key = `__xstate_devtools_server_${port}__`;
+  const cache = globalThis[key];
+  let server;
+  if (cache) {
+    server = cache;
+    if (bufferSize > server.bufferSize) server.bufferSize = bufferSize;
+  } else {
+    const clients = /* @__PURE__ */ new Set();
+    const dispatchHandlers = /* @__PURE__ */ new Set();
+    const liveActors = /* @__PURE__ */ new Map();
+    const recentEvents = [];
+    let wss = null;
+    let closed = false;
+    server = {
+      clients,
+      dispatchHandlers,
+      liveActors,
+      recentEvents,
+      bufferSize,
+      activated: false,
+      close: () => {
+        closed = true;
+        try {
+          wss?.close();
+        } catch {
+        }
+        clients.clear();
+        dispatchHandlers.clear();
+        liveActors.clear();
+        recentEvents.length = 0;
+        delete globalThis[key];
+      }
+    };
+    void (async () => {
+      try {
+        const mod = await import("ws");
+        const WSServer = mod.WebSocketServer ?? mod.Server;
+        if (closed) return;
+        wss = new WSServer({ port, host });
+        wss.on("connection", (ws) => {
+          for (const { reg, snapshot } of server.liveActors.values()) {
+            try {
+              ws.send(JSON.stringify({ ...reg, __xstateDevtools: true }));
+            } catch {
+            }
+            if (snapshot !== reg.snapshot) {
+              try {
+                ws.send(JSON.stringify({
+                  type: "XSTATE_SNAPSHOT",
+                  sessionId: reg.sessionId,
+                  snapshot,
+                  timestamp: reg.timestamp,
+                  globalSeq: reg.globalSeq,
+                  __xstateDevtools: true
+                }));
+              } catch {
+              }
+            }
+          }
+          try {
+            ws.send(JSON.stringify({
+              type: "XSTATE_REPLAY_DONE",
+              sessionIds: [...server.liveActors.keys()],
+              __xstateDevtools: true
+            }));
+          } catch {
+          }
+          if (!server.activated) {
+            server.activated = true;
+            for (const payload of server.recentEvents) {
+              try {
+                ws.send(payload);
+              } catch {
+              }
+            }
+            server.recentEvents.length = 0;
+          }
+          server.clients.add(ws);
+          ws.on("message", (raw) => {
+            try {
+              const text = typeof raw === "string" ? raw : raw.toString("utf8");
+              const msg = JSON.parse(text);
+              for (const cb of server.dispatchHandlers) cb(msg);
+            } catch {
+            }
+          });
+          ws.on("close", () => server.clients.delete(ws));
+          ws.on("error", () => server.clients.delete(ws));
+        });
+        wss.on("error", (err) => {
+          console.warn("[xstate-devtools] WS server error:", err.message);
+        });
+      } catch (e) {
+        console.warn(
+          "[xstate-devtools] could not start server adapter \u2014 install `ws` to enable.",
+          e.message
+        );
+      }
+    })();
+    globalThis[key] = server;
+  }
+  const transport = {
+    send(message) {
+      trackLive(server, message);
+      const payload = JSON.stringify({ ...message, __xstateDevtools: true });
+      if (!server.activated && (message.type === "XSTATE_EVENT" || message.type === "XSTATE_SNAPSHOT")) {
+        server.recentEvents.push(payload);
+        if (server.recentEvents.length > server.bufferSize) server.recentEvents.shift();
+      }
+      for (const ws of server.clients) {
+        if (ws.readyState === OPEN_STATE) {
+          try {
+            ws.send(payload);
+          } catch {
+          }
+        }
+      }
+    },
+    subscribe(handler) {
+      server.dispatchHandlers.add(handler);
+      return () => server.dispatchHandlers.delete(handler);
+    }
+  };
+  const inspector = createInspector(transport, "srv");
+  return { ...inspector, close: server.close };
+}
+export {
+  createServerAdapter
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["// Server entrypoint — exposes a WebSocket bridge so the DevTools panel\n// can connect to actors running in Node.\nimport type { ExtensionToPageMessage, PageToExtensionMessage } from '@xstate-devtools/protocol'\nimport { createInspector, type Transport } from './core.js'\n\nexport interface ServerAdapterOptions {\n  /** Port to listen on. Defaults to env XSTATE_DEVTOOLS_PORT or 9301. */\n  port?: number\n  /** Host to bind. Defaults to '127.0.0.1'. */\n  host?: string\n  /** Max events to buffer before the first panel connects. Default 200. */\n  bufferSize?: number\n}\n\ninterface ClientLike {\n  send(data: string): void\n  on(event: string, listener: (...args: unknown[]) => void): void\n  readyState: number\n}\n\nconst OPEN_STATE = 1\n\ntype ActorRegistered = Extract<PageToExtensionMessage, { type: 'XSTATE_ACTOR_REGISTERED' }>\n\ninterface LiveActor {\n  /** The registration message, kept immutable so its snapshot stays the\n   *  registration-time one (the panel's time-travel floor). */\n  reg: ActorRegistered\n  /** Latest snapshot seen for this actor (the registration snapshot until updated). */\n  snapshot: ActorRegistered['snapshot']\n}\n\ninterface CachedServer {\n  clients: Set<ClientLike>\n  dispatchHandlers: Set<(msg: ExtensionToPageMessage) => void>\n  /** Currently-live actors (immutable registration + latest snapshot). */\n  liveActors: Map<string, LiveActor>\n  /** Pre-first-connection event/snapshot backlog, flushed once to the first panel. */\n  recentEvents: string[]\n  bufferSize: number\n  /** Set once the first panel connects and drains the backlog. */\n  activated: boolean\n  close: () => void\n}\n\n/** Track live-actor state so it can be replayed to every connecting panel. */\nfunction trackLive(server: CachedServer, message: PageToExtensionMessage): void {\n  switch (message.type) {\n    case 'XSTATE_ACTOR_REGISTERED':\n      server.liveActors.set(message.sessionId, { reg: message, snapshot: message.snapshot })\n      break\n    case 'XSTATE_SNAPSHOT': {\n      const live = server.liveActors.get(message.sessionId)\n      if (live) { live.snapshot = message.snapshot }\n      break\n    }\n    case 'XSTATE_EVENT': {\n      const live = server.liveActors.get(message.sessionId)\n      if (live) { live.snapshot = message.snapshotAfter }\n      break\n    }\n    case 'XSTATE_ACTOR_STOPPED':\n      server.liveActors.delete(message.sessionId)\n      break\n  }\n}\n\n/**\n * Start a local WebSocket server that the DevTools panel can connect to.\n * Returns the inspector callback. Multiple panels can connect simultaneously.\n *\n * The WS server, connected clients, dispatch handlers, and the live-actor\n * registry are all stashed on globalThis keyed by port. This makes the function\n * idempotent across HMR re-evaluation: subsequent calls reuse the existing\n * server and only register new inspector hooks.\n *\n * Every connecting panel — including a reconnect after the editor/host restarts\n * — is replayed the current set of live actors (with their latest snapshots),\n * so actors registered at boot stay visible across reconnects (not just for\n * the first panel). The pre-connection event backlog, by contrast, is flushed\n * only to the very first panel; replaying it on every reconnect would re-flood\n * the log with stale events.\n */\nexport function createServerAdapter(options: ServerAdapterOptions = {}) {\n  const port = options.port\n    ?? (Number(process.env.XSTATE_DEVTOOLS_PORT) || 9301)\n  const host = options.host ?? '127.0.0.1'\n  const bufferSize = options.bufferSize ?? 200\n\n  const key = `__xstate_devtools_server_${port}__`\n  const cache = (globalThis as Record<string, unknown>)[key] as CachedServer | undefined\n\n  let server: CachedServer\n  if (cache) {\n    server = cache\n    // honour the most recent caller's buffer size if larger\n    if (bufferSize > server.bufferSize) server.bufferSize = bufferSize\n  } else {\n    const clients = new Set<ClientLike>()\n    const dispatchHandlers = new Set<(msg: ExtensionToPageMessage) => void>()\n    const liveActors = new Map<string, LiveActor>()\n    const recentEvents: string[] = []\n    let wss: any = null\n    let closed = false\n\n    server = {\n      clients, dispatchHandlers, liveActors, recentEvents, bufferSize,\n      activated: false,\n      close: () => {\n        closed = true\n        try { wss?.close() } catch { /* noop */ }\n        clients.clear()\n        dispatchHandlers.clear()\n        liveActors.clear()\n        recentEvents.length = 0\n        delete (globalThis as Record<string, unknown>)[key]\n      },\n    }\n\n    // Lazily import ws so this module is import-safe in environments that\n    // never use the server entrypoint (or where ws isn't installed).\n    void (async () => {\n      try {\n        const mod = await import('ws')\n        const WSServer = (mod as any).WebSocketServer ?? (mod as any).Server\n        if (closed) return\n        wss = new WSServer({ port, host })\n        wss.on('connection', (ws: ClientLike) => {\n          // Replay current live actors to every connecting panel, so reconnects\n          // see the current set. Send the immutable registration (carrying the\n          // registration-time snapshot → correct time-travel floor), then a\n          // snapshot update if the actor has advanced since.\n          for (const { reg, snapshot } of server.liveActors.values()) {\n            try { ws.send(JSON.stringify({ ...reg, __xstateDevtools: true })) } catch { /* ignore */ }\n            if (snapshot !== reg.snapshot) {\n              try {\n                ws.send(JSON.stringify({\n                  type: 'XSTATE_SNAPSHOT', sessionId: reg.sessionId, snapshot,\n                  timestamp: reg.timestamp, globalSeq: reg.globalSeq, __xstateDevtools: true,\n                }))\n              } catch { /* ignore */ }\n            }\n          }\n          // Tell the panel the authoritative live set so it can prune actors\n          // from a previous session (reconnect/app-restart) without wiping the\n          // ones we just replayed.\n          try {\n            ws.send(JSON.stringify({\n              type: 'XSTATE_REPLAY_DONE',\n              sessionIds: [...server.liveActors.keys()],\n              __xstateDevtools: true,\n            }))\n          } catch { /* ignore */ }\n          // Flush the pre-connection event backlog once, to the first panel only.\n          if (!server.activated) {\n            server.activated = true\n            for (const payload of server.recentEvents) {\n              try { ws.send(payload) } catch { /* ignore */ }\n            }\n            server.recentEvents.length = 0\n          }\n          server.clients.add(ws)\n          ws.on('message', (raw: unknown) => {\n            try {\n              const text = typeof raw === 'string' ? raw : (raw as Buffer).toString('utf8')\n              const msg = JSON.parse(text) as ExtensionToPageMessage\n              for (const cb of server.dispatchHandlers) cb(msg)\n            } catch {\n              // ignore malformed messages\n            }\n          })\n          ws.on('close', () => server.clients.delete(ws))\n          ws.on('error', () => server.clients.delete(ws))\n        })\n        wss.on('error', (err: Error) => {\n          console.warn('[xstate-devtools] WS server error:', err.message)\n        })\n      } catch (e) {\n        console.warn(\n          '[xstate-devtools] could not start server adapter — install `ws` to enable.',\n          (e as Error).message,\n        )\n      }\n    })()\n\n    ;(globalThis as Record<string, unknown>)[key] = server\n  }\n\n  const transport: Transport = {\n    send(message: PageToExtensionMessage) {\n      // Maintain the live-actor registry so any panel that connects (or\n      // reconnects) later can be replayed the current state.\n      trackLive(server, message)\n      const payload = JSON.stringify({ ...message, __xstateDevtools: true })\n      // Buffer events only until the first panel connects; afterwards the log\n      // streams live and the backlog is no longer replayed (avoids reconnect\n      // re-flooding the log with stale events).\n      if (!server.activated && (message.type === 'XSTATE_EVENT' || message.type === 'XSTATE_SNAPSHOT')) {\n        server.recentEvents.push(payload)\n        if (server.recentEvents.length > server.bufferSize) server.recentEvents.shift()\n      }\n      for (const ws of server.clients) {\n        if (ws.readyState === OPEN_STATE) {\n          try { ws.send(payload) } catch { /* ignore */ }\n        }\n      }\n    },\n    subscribe(handler) {\n      server.dispatchHandlers.add(handler)\n      return () => server.dispatchHandlers.delete(handler)\n    },\n  }\n\n  const inspector = createInspector(transport, 'srv')\n  return { ...inspector, close: server.close }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,21 +1,68 @@
 {
   "name": "@xstate-devtools/adapter",
-  "version": "0.1.3",
+  "version": "0.1.5",
+  "description": "Inspect XState v5 actors from a running app (browser, Node/SSR, or React) and stream them to the XState DevTools / VS Code live debugger.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mjbeswick/xstate-devtools.git",
+    "directory": "packages/adapter"
+  },
+  "keywords": [
+    "xstate",
+    "statechart",
+    "devtools",
+    "inspector",
+    "debugger"
+  ],
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./server": "./src/server.ts",
-    "./react": "./src/react.tsx"
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "development": "./src/server.ts",
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    },
+    "./react": {
+      "development": "./src/react.tsx",
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
   },
   "scripts": {
-    "test": "vitest run"
+    "build": "tsup",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
+    "@xstate/react": "^4.0.0",
+    "react": "^18.0.0 || ^19.0.0",
     "ws": "^8.0.0",
     "xstate": "^5.0.0"
   },
   "peerDependenciesMeta": {
+    "@xstate/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
     "ws": {
       "optional": true
     }
@@ -23,8 +70,10 @@
   "devDependencies": {
     "@types/react": "^18.3.0",
     "@types/ws": "^8.18.1",
+    "@xstate-devtools/protocol": "*",
     "@xstate/react": "^4.1.0",
     "react": "^18.3.0",
+    "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0",
     "ws": "^8.20.0",

package/src/core.test.ts

@@ -1,287 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import { createActor, createMachine } from 'xstate'
-import { createInspector, getSourceLocationFromStack, type Transport } from './core.js'
-
-describe('createInspector', () => {
-  it('sanitizes outbound inspection events before sending them to the transport', () => {
-    const sent: unknown[] = []
-    const transport: Transport = {
-      send(message) {
-        sent.push(message)
-      },
-      subscribe() {
-        return () => {}
-      },
-    }
-
-    const inspector = createInspector(transport, 'srv')
-    const snapshot = { value: 'idle', context: {}, status: 'active' }
-    const actorRef = {
-      sessionId: 'actor-1',
-      getSnapshot: vi.fn(() => snapshot),
-    }
-
-    const event: Record<string, unknown> = { type: 'route.changed' }
-    event.self = event
-    event.handler = function routeHandler() {}
-
-    inspector.inspect({
-      type: '@xstate.event',
-      actorRef,
-      event,
-    })
-
-    const message = sent.find(
-      (candidate): candidate is { type: string; event: Record<string, unknown> } =>
-        typeof candidate === 'object' &&
-        candidate !== null &&
-        'type' in candidate &&
-        (candidate as { type?: string }).type === 'XSTATE_EVENT',
-    )
-
-    expect(message).toBeDefined()
-    expect(message?.event.type).toBe('route.changed')
-    expect(message?.event.handler).toBe('[Function: routeHandler]')
-    expect(message?.event.self).not.toBe(event)
-  })
-
-  it('sets a selected state node as active for machine actors', () => {
-    const sent: unknown[] = []
-    let handler: ((message: Parameters<Transport['subscribe']>[0]) => void) | undefined
-    const transport: Transport = {
-      send(message) {
-        sent.push(message)
-      },
-      subscribe(callback) {
-        handler = callback
-        return () => {}
-      },
-    }
-
-    const inspector = createInspector(transport, 'srv')
-    const actor = createActor(
-      createMachine({
-        id: 'traffic',
-        initial: 'green',
-        states: {
-          green: {},
-          yellow: {},
-          red: {},
-        },
-      }),
-    )
-
-    actor.start()
-    inspector.inspect({ type: '@xstate.actor', actorRef: actor })
-
-    handler?.({
-      type: 'XSTATE_SET_ACTIVE_STATE',
-      sessionId: `srv:${actor.sessionId}`,
-      stateNodeId: 'traffic.red',
-    })
-
-    expect(actor.getSnapshot().value).toBe('red')
-
-    const snapshotMessage = sent.find(
-      (candidate): candidate is { type: string; snapshot: { value: unknown }; sessionId: string } =>
-        typeof candidate === 'object' &&
-        candidate !== null &&
-        'type' in candidate &&
-        (candidate as { type?: string }).type === 'XSTATE_SNAPSHOT' &&
-        'snapshot' in candidate,
-    )
-    expect(snapshotMessage).toBeDefined()
-    expect(snapshotMessage?.sessionId).toBe(`srv:${actor.sessionId}`)
-    expect(snapshotMessage?.snapshot.value).toBe('red')
-  })
-})
-
-describe('getSourceLocationFromStack', () => {
-  it('skips anonymous and node internal frames and returns filesystem frame', () => {
-    const stack = [
-      'Error',
-      '    at getSourceLocation (packages/adapter/src/core.ts:10:1)',
-      '    at inspect (packages/adapter/src/core.ts:20:1)',
-      '    at Map.forEach (<anonymous>)',
-      '    at WebSocket.emit (node:events:508:28)',
-      '    at createMachine (/Users/me/project/app/machine.ts:12:3)',
-    ].join('\n')
-
-    expect(getSourceLocationFromStack(stack)).toBe(
-      'createMachine (/Users/me/project/app/machine.ts:12:3)',
-    )
-  })
-
-  it('accepts vite /@fs/ urls and ignores plain browser urls', () => {
-    const stack = [
-      'Error',
-      '    at getSourceLocation (packages/adapter/src/core.ts:10:1)',
-      '    at inspect (packages/adapter/src/core.ts:20:1)',
-      '    at createMachine (http://localhost:5173/app/machines/auth.machine.ts:12:3)',
-      '    at createMachine (http://localhost:5173/@fs/Users/me/project/app/machine.ts:12:3)',
-    ].join('\n')
-
-    expect(getSourceLocationFromStack(stack)).toBe(
-      'createMachine (http://localhost:5173/@fs/Users/me/project/app/machine.ts:12:3)',
-    )
-  })
-
-  it('maps plain browser app urls when a web source root is configured', () => {
-    const stack = [
-      'Error',
-      '    at getSourceLocation (packages/adapter/src/core.ts:10:1)',
-      '    at inspect (packages/adapter/src/core.ts:20:1)',
-      '    at createMachine (http://localhost:5273/app/machines/auth.machine.ts:12:3)',
-    ].join('\n')
-
-    expect(
-      getSourceLocationFromStack(stack, 'web', {
-        webSourceRoot: '/Users/me/project/packages/example-remix',
-      }),
-    ).toBe(
-      'createMachine (/Users/me/project/packages/example-remix/app/machines/auth.machine.ts:12:3)',
-    )
-  })
-
-  it('returns undefined when no filesystem-backed frame exists', () => {
-    const stack = [
-      'Error',
-      '    at getSourceLocation (packages/adapter/src/core.ts:10:1)',
-      '    at inspect (packages/adapter/src/core.ts:20:1)',
-      '    at Map.forEach (<anonymous>)',
-      '    at WebSocket.emit (node:events:508:28)',
-    ].join('\n')
-
-    expect(getSourceLocationFromStack(stack)).toBeUndefined()
-  })
-
-  // --- Investigation tests for the "source link not appearing" bug ---
-  // These tests simulate the realistic Vite/React/XState browser stack to
-  // pinpoint why sourceLocation is undefined when inspecting machines in the
-  // example app.
-
-  it('skips vite pre-bundled xstate deps and finds user component frame', () => {
-    // In Vite dev mode, XState and @xstate/react are pre-bundled and served at
-    // /node_modules/.vite/deps/*.js, NOT at /node_modules/xstate/ or
-    // /node_modules/@xstate/. isLibraryStackFrame misses these, but they must
-    // still be skipped (via hasFilesystemBackedPath returning false).
-    const stack = [
-      'Error',
-      '    at getSourceLocation (http://localhost:5273/@fs/Users/me/xstate-devtools/packages/adapter/src/core.ts:225:21)',
-      '    at inspect (http://localhost:5273/@fs/Users/me/xstate-devtools/packages/adapter/src/core.ts:576:47)',
-      '    at Actor._sendInspectionEvent (http://localhost:5273/node_modules/.vite/deps/xstate.js:123:45)',
-      '    at new Actor (http://localhost:5273/node_modules/.vite/deps/xstate.js:234:12)',
-      '    at createActor (http://localhost:5273/node_modules/.vite/deps/xstate.js:345:10)',
-      '    at useIdleActorRef (http://localhost:5273/node_modules/.vite/deps/@xstate_react.js:67:23)',
-      '    at useMachine (http://localhost:5273/node_modules/.vite/deps/@xstate_react.js:207:10)',
-      '    at MediaPlayer (http://localhost:5273/app/components/MediaPlayer.tsx:6:43)',
-      '    at renderWithHooks (http://localhost:5273/node_modules/.vite/deps/react-dom_client.js:456:22)',
-    ].join('\n')
-
-    expect(
-      getSourceLocationFromStack(stack, 'web', {
-        webSourceRoot: '/Users/me/xstate-devtools/packages/example-remix',
-      }),
-    ).toBe(
-      'MediaPlayer (/Users/me/xstate-devtools/packages/example-remix/app/components/MediaPlayer.tsx:6:43)',
-    )
-  })
-
-  it('returns undefined for vite pre-bundled stack without webSourceRoot', () => {
-    // Without webSourceRoot, /app/ URLs cannot be remapped to filesystem paths,
-    // so sourceLocation should be undefined and the source link hidden.
-    const stack = [
-      'Error',
-      '    at getSourceLocation (http://localhost:5273/@fs/Users/me/xstate-devtools/packages/adapter/src/core.ts:225:21)',
-      '    at inspect (http://localhost:5273/@fs/Users/me/xstate-devtools/packages/adapter/src/core.ts:576:47)',
-      '    at new Actor (http://localhost:5273/node_modules/.vite/deps/xstate.js:234:12)',
-      '    at useMachine (http://localhost:5273/node_modules/.vite/deps/@xstate_react.js:207:10)',
-      '    at MediaPlayer (http://localhost:5273/app/components/MediaPlayer.tsx:6:43)',
-    ].join('\n')
-
-    // No webSourceRoot: plain /app/ browser URLs have no filesystem mapping.
-    expect(getSourceLocationFromStack(stack, 'web')).toBeUndefined()
-  })
-
-  it('captures real Node.js stack from within a createActor inspect callback', () => {
-    // This test runs in Node.js. It verifies:
-    // 1. @xstate.actor fires synchronously during createActor (user code IS on stack)
-    // 2. getSourceLocationFromStack finds a frame — but in this test environment,
-    //    the test file itself is inside packages/adapter/ so it's filtered out by
-    //    isLibraryStackFrame. The Vitest runner frame (node_modules/@vitest) is
-    //    returned instead, which is the first "non-library" filesystem-backed frame.
-    //    This is expected here; in production the first non-library frame is user
-    //    component code (e.g. app/components/MediaPlayer.tsx).
-    const machine = createMachine({ id: 'src-test', initial: 'idle', states: { idle: {} } })
-
-    let capturedStack: string | undefined
-
-    // createActor synchronously fires @xstate.actor in the Actor constructor.
-    createActor(machine, {
-      inspect(event) {
-        if (event.type === '@xstate.actor') {
-          capturedStack = new Error().stack
-        }
-      },
-    })
-
-    expect(capturedStack).toBeDefined()
-
-    // Confirm @xstate.actor fires synchronously: capturedStack is set immediately.
-    expect(capturedStack).toMatch(/@xstate\.actor|Actor|createActor/)
-
-    const location = getSourceLocationFromStack(capturedStack, 'srv')
-
-    // In this test env, the test file is filtered (it's in /packages/adapter/).
-    // The function returns the Vitest runner frame as the first "non-library" frame.
-    // This exposes a real limitation: the /packages/adapter/ filter also catches
-    // test files. In a real browser, user component files at /app/ are not filtered.
-    expect(location).toBeDefined()
-  })
-
-  it('shows that the test file itself is filtered by isLibraryStackFrame', () => {
-    // This is an explicit documentation of the limitation: any frame inside
-    // packages/adapter/ is treated as a library frame and skipped. This is
-    // correct in production but means test-side assertions about "user code"
-    // in these tests will see Vitest runner frames instead.
-    const testFilePath = '/Users/me/xstate-devtools/packages/adapter/src/core.test.ts'
-    const fakeStack = [
-      'Error',
-      '    at getSourceLocation (/Users/me/xstate-devtools/packages/adapter/src/core.ts:225:21)',
-      '    at inspect (/Users/me/xstate-devtools/packages/adapter/src/core.ts:576:47)',
-      `    at it (/Users/me/xstate-devtools/packages/adapter/src/core.test.ts:200:5)`,
-      '    at runTest (file:///Users/me/xstate-devtools/node_modules/@vitest/runner/dist/index.js:146:14)',
-    ].join('\n')
-
-    // The test file frame is filtered because it contains '/packages/adapter/'
-    // — so the Vitest runner frame is what gets returned.
-    const location = getSourceLocationFromStack(fakeStack, 'srv')
-    expect(location).toMatch(/vitest/)
-    expect(location).not.toContain(testFilePath)
-  })
-
-  it('does not show source link when @xstate.actor fires inside useEffect (deferred start)', () => {
-    // @xstate/react calls actorRef.start() inside React.useEffect, not during
-    // createActor. If inspection fires at start() time instead of createActor
-    // time, the React scheduler is on the stack and user code is NOT present.
-    // This simulates what would happen if start() (not createActor) triggered
-    // the @xstate.actor event.
-    const stack = [
-      'Error',
-      '    at getSourceLocation (http://localhost:5273/@fs/Users/me/xstate-devtools/packages/adapter/src/core.ts:225:21)',
-      '    at inspect (http://localhost:5273/@fs/Users/me/xstate-devtools/packages/adapter/src/core.ts:576:47)',
-      '    at Actor.start (http://localhost:5273/node_modules/.vite/deps/xstate.js:300:8)',
-      '    at useEffect (http://localhost:5273/node_modules/.vite/deps/@xstate_react.js:99:14)',
-      // React scheduler — no user component frame at all
-      '    at commitHookEffectListMount (http://localhost:5273/node_modules/.vite/deps/react-dom_client.js:22728:26)',
-      '    at commitPassiveMountOnFiber (http://localhost:5273/node_modules/.vite/deps/react-dom_client.js:24502:13)',
-    ].join('\n')
-
-    // Without any /app/ user frame, sourceLocation should be undefined.
-    expect(
-      getSourceLocationFromStack(stack, 'web', {
-        webSourceRoot: '/Users/me/xstate-devtools/packages/example-remix',
-      }),
-    ).toBeUndefined()
-  })
-})