@xstate-devtools/adapter 0.1.2 → 0.1.4

package/dist/server.cjs

@@ -0,0 +1,936 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  createServerAdapter: () => createServerAdapter
+});
+module.exports = __toCommonJS(server_exports);
+var import_node_net = require("net");
+
+// src/logging.ts
+function hasProcessEnv() {
+  return typeof process !== "undefined" && typeof process.env !== "undefined";
+}
+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, scope, message, details) {
+  if (!isLoggingEnabled()) return;
+  if (details === void 0) {
+    console[level](`[xstate-devtools:${scope}] ${message}`);
+    return;
+  }
+  console[level](`[xstate-devtools:${scope}] ${message}`, details);
+}
+function debugLog(scope, message, details) {
+  log("debug", scope, message, details);
+}
+function infoLog(scope, message, details) {
+  log("info", scope, message, details);
+}
+function warnLog(scope, message, details) {
+  log("warn", scope, message, details);
+}
+
+// src/sanitize.ts
+var MAX_DEPTH = 10;
+var MAX_STRING_LENGTH = 500;
+var MAX_ARRAY_LENGTH = 100;
+function sanitizeValue(value, depth, seen) {
+  if (depth > MAX_DEPTH) return "[MaxDepth]";
+  if (value === null || value === void 0) 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)}\u2026` : 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 = [];
+    for (const [k, v] of value) {
+      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 = [];
+    for (const v of value) {
+      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.constructor.name}]`;
+  if (typeof Node !== "undefined" && value instanceof Node) {
+    return `[DOMNode: ${value.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(`[\u2026${value.length - MAX_ARRAY_LENGTH} more]`);
+    return result;
+  }
+  if (typeof value === "object") {
+    const result = {};
+    let count = 0;
+    for (const [k, v] of Object.entries(value)) {
+      if (count++ >= MAX_ARRAY_LENGTH) {
+        result["\u2026"] = "[truncated]";
+        break;
+      }
+      result[k] = sanitizeValue(v, depth + 1, seen);
+    }
+    return result;
+  }
+  return String(value);
+}
+function sanitize(value, depth = 0) {
+  return sanitizeValue(value, depth, /* @__PURE__ */ new WeakSet());
+}
+
+// src/serialize.ts
+var MAX_SERIALIZED_NODES = 500;
+var MAX_TRANSITIONS_PER_NODE = 100;
+var MAX_CHILD_STATES = 100;
+var MAX_ACTIONS_PER_TRANSITION = 20;
+var MAX_ENTRY_EXIT_ACTIONS = 20;
+var MAX_INVOKES_PER_NODE = 20;
+function serializeGuard(guard) {
+  if (!guard) return void 0;
+  if (typeof guard === "string") return guard;
+  if (typeof guard === "function") return guard.name || "(inline)";
+  if (typeof guard === "object" && guard !== null) {
+    const g = guard;
+    return g.type ?? g.name ?? "(inline)";
+  }
+  return "(inline)";
+}
+function serializeAction(action) {
+  if (typeof action === "string") return action;
+  if (typeof action === "function") return action.name || "(anonymous)";
+  if (typeof action === "object" && action !== null) {
+    const a = action;
+    return a.type ?? a.name ?? String(action);
+  }
+  return String(action);
+}
+function serializeTransitionList(transitions) {
+  return transitions.slice(0, MAX_TRANSITIONS_PER_NODE).map((t) => ({
+    eventType: t.eventType ?? "",
+    targets: (t.target ?? []).map((n) => 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) {
+  return node.invoke.slice(0, MAX_INVOKES_PER_NODE).map((inv) => ({
+    id: inv.id ?? "(unknown)",
+    src: typeof inv.src === "string" ? inv.src : inv.src?.id ?? inv.src?.name ?? "(inline)"
+  }));
+}
+function serializeNode(node, state) {
+  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 = [];
+  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 ?? void 0,
+    description: node.config?.description ?? void 0
+  };
+}
+function serializeMachine(machine, sourceLocation) {
+  return {
+    id: machine.id,
+    root: serializeNode(machine.root, { seen: /* @__PURE__ */ new WeakSet(), count: 0 }),
+    sourceLocation
+  };
+}
+
+// src/core.ts
+function summarizeMessage(message) {
+  const summary = { 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) {
+  return {
+    type: event?.type,
+    sessionId: event?.actorRef?.sessionId,
+    eventType: event?.type === "@xstate.event" && event?.event && typeof event.event === "object" ? event.event.type : void 0
+  };
+}
+function debugLog2(source, message, details) {
+  debugLog(`${source}:adapter`, message, details);
+}
+function infoLog2(source, message, details) {
+  infoLog(`${source}:adapter`, message, details);
+}
+function warnLog2(source, message, details) {
+  warnLog(`${source}:adapter`, message, details);
+}
+function isLibraryStackFrame(line) {
+  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) {
+  return line.trim().replace(/^at\s+/, "");
+}
+function extractStackFrameLocation(frame) {
+  return frame.match(/\((.*)\)$/)?.[1] ?? frame;
+}
+function isAnonymousOrEvalLocation(location) {
+  const normalized = location.trim().toLowerCase().replace(/^[./\\]+/, "");
+  return normalized === "<anonymous>" || normalized === "anonymous" || normalized === "(anonymous)" || normalized === "eval" || normalized === "<eval>" || normalized === "[native code]";
+}
+function hasFilesystemBackedPath(location) {
+  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, source, options) {
+  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;
+  }
+}
+function getSourceLocationFromStack(stack, source = "web", options) {
+  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 void 0;
+}
+function getSourceLocation(source, options) {
+  try {
+    const oldLimit = Error.stackTraceLimit;
+    Error.stackTraceLimit = 50;
+    const stack = new Error().stack;
+    Error.stackTraceLimit = oldLimit;
+    return getSourceLocationFromStack(stack, source, options);
+  } catch {
+    return void 0;
+  }
+}
+function serializeSnapshot(snapshot) {
+  return {
+    value: snapshot?.value ?? null,
+    context: sanitize(snapshot?.context),
+    status: snapshot?.status ?? "active",
+    error: snapshot?.error ? sanitize(snapshot.error) : void 0
+  };
+}
+function safeSerializeSnapshot(actorRef) {
+  try {
+    return serializeSnapshot(actorRef.getSnapshot());
+  } catch {
+    return { value: null, context: void 0, status: "active" };
+  }
+}
+function getActorDisplayName(actorRef) {
+  const actor = actorRef;
+  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;
+    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 void 0;
+}
+function getNodeInitialChild(node) {
+  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, childValue) {
+  if (child.type === "atomic" || child.type === "final" || child.type === "history") {
+    return child.key;
+  }
+  return { [child.key]: childValue };
+}
+function getDefaultStateValue(node) {
+  if (node.type === "parallel") {
+    const value = {};
+    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) {
+  if (node.type === "atomic" || node.type === "final" || node.type === "history") {
+    return node.key;
+  }
+  return getDefaultStateValue(node);
+}
+function getExistingChildValue(value, childKey) {
+  if (!value || typeof value !== "object") return void 0;
+  return value[childKey];
+}
+function getPathToRoot(target, root) {
+  const path = [];
+  let current = 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, path, currentValue) {
+  const [, ...restPath] = path;
+  if (restPath.length === 0) {
+    if (node.type === "parallel") {
+      const next = {};
+      for (const child2 of Object.values(node.states ?? {})) {
+        next[child2.key] = getExistingChildValue(currentValue, child2.key) ?? getDefaultSelectionValue(child2);
+      }
+      return next;
+    }
+    if (node.type === "compound") {
+      return getDefaultStateValue(node);
+    }
+    return node.key;
+  }
+  const child = restPath[0];
+  if (node.type === "parallel") {
+    const next = {};
+    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, stateNodeId) {
+  const mutableActorRef = actorRef;
+  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();
+  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
+  });
+}
+var SEQ_KEY = "__xstate_devtools_global_seq__";
+function nextSeq() {
+  const g = globalThis;
+  const cur = g[SEQ_KEY] ?? 0;
+  const next = cur + 1;
+  g[SEQ_KEY] = next;
+  return next;
+}
+function createInspector(transport, source, options = {}) {
+  const actorRefs = /* @__PURE__ */ new Map();
+  const actorMachines = /* @__PURE__ */ new Map();
+  const prefix = `${source}:`;
+  const tag = (sessionId) => prefix + sessionId;
+  const tagOptional = (id) => id ? prefix + id : void 0;
+  const stripIfMine = (id) => id.startsWith(prefix) ? id.slice(prefix.length) : null;
+  function checkAndNotifyStop(actorRef) {
+    let snap;
+    try {
+      snap = actorRef.getSnapshot();
+    } catch {
+      return;
+    }
+    if (snap?.status !== "active") {
+      const message = {
+        type: "XSTATE_ACTOR_STOPPED",
+        sessionId: tag(actorRef.sessionId)
+      };
+      debugLog2(source, "actor stopped; notifying transport", summarizeMessage(message));
+      transport.send(message);
+      actorRefs.delete(actorRef.sessionId);
+      actorMachines.delete(actorRef.sessionId);
+    }
+  }
+  const unsubscribe = transport.subscribe((message) => {
+    debugLog2(source, "received message from transport", summarizeMessage(message));
+    if (message.type === "XSTATE_PANEL_CONNECTED") {
+      infoLog2(source, "panel connected; resyncing actors", { actorCount: actorRefs.size });
+      actorRefs.forEach((actorRef, sessionId) => {
+        const machine = actorMachines.get(sessionId) ?? null;
+        const resyncMessage = {
+          type: "XSTATE_ACTOR_REGISTERED",
+          sessionId: tag(sessionId),
+          parentSessionId: tagOptional(actorRef._parent?.sessionId),
+          displayName: getActorDisplayName(actorRef),
+          machine,
+          snapshot: safeSerializeSnapshot(actorRef),
+          globalSeq: nextSeq(),
+          timestamp: Date.now()
+        };
+        debugLog2(source, "resyncing actor", summarizeMessage(resyncMessage));
+        transport.send(resyncMessage);
+      });
+      return;
+    }
+    if (message.type === "XSTATE_DISPATCH") {
+      const local = stripIfMine(message.sessionId);
+      if (local === null) {
+        debugLog2(source, "ignoring dispatch for different source", summarizeMessage(message));
+        return;
+      }
+      const ref = actorRefs.get(local);
+      if (ref) {
+        try {
+          debugLog2(source, "dispatching event to actor", {
+            sessionId: local,
+            eventType: message.event && typeof message.event === "object" && "type" in message.event ? message.event.type : void 0
+          });
+          ref.send(message.event);
+        } catch (e) {
+          warnLog2(source, "dispatch error", { error: e, sessionId: local });
+        }
+      } else {
+        warnLog2(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) {
+        debugLog2(
+          source,
+          "ignoring state activation for different source",
+          summarizeMessage(message)
+        );
+        return;
+      }
+      const ref = actorRefs.get(local);
+      if (!ref) {
+        warnLog2(source, "received state activation for unknown actor", {
+          sessionId: local,
+          knownActors: actorRefs.size
+        });
+        return;
+      }
+      try {
+        debugLog2(source, "setting active state on actor", summarizeMessage(message));
+        setActiveState(ref, message.stateNodeId);
+        const snapshotMessage = {
+          type: "XSTATE_SNAPSHOT",
+          sessionId: tag(local),
+          snapshot: safeSerializeSnapshot(ref),
+          timestamp: Date.now(),
+          globalSeq: nextSeq()
+        };
+        debugLog2(
+          source,
+          "sending snapshot after state activation",
+          summarizeMessage(snapshotMessage)
+        );
+        transport.send(snapshotMessage);
+      } catch (error) {
+        warnLog2(source, "failed to set active state", {
+          error,
+          sessionId: local,
+          stateNodeId: message.stateNodeId
+        });
+      }
+    }
+  });
+  transport.send({ type: "XSTATE_ADAPTER_READY" });
+  infoLog2(source, "inspector created");
+  const inspect = (inspectionEvent) => {
+    debugLog2(source, "inspect callback invoked", summarizeInspectionEvent(inspectionEvent));
+    if (inspectionEvent.type === "@xstate.actor") {
+      const actorRef = inspectionEvent.actorRef;
+      const sessionId = actorRef.sessionId;
+      const actorLogic = actorRef.logic;
+      const machine = actorLogic?.root ? serializeMachine(
+        actorLogic,
+        actorLogic.config?.__xstateDevtoolsSource ?? getSourceLocation(source, options)
+      ) : null;
+      actorRefs.set(sessionId, actorRef);
+      actorMachines.set(sessionId, machine);
+      const notifyStop = () => {
+        if (actorRefs.has(sessionId)) {
+          actorRefs.delete(sessionId);
+          actorMachines.delete(sessionId);
+          const stopMsg = {
+            type: "XSTATE_ACTOR_STOPPED",
+            sessionId: tag(sessionId)
+          };
+          debugLog2(source, "actor stopped; notifying transport", summarizeMessage(stopMsg));
+          transport.send(stopMsg);
+        }
+      };
+      try {
+        actorRef.subscribe({ complete: notifyStop, error: notifyStop });
+      } catch {
+      }
+      const message = {
+        type: "XSTATE_ACTOR_REGISTERED",
+        sessionId: tag(sessionId),
+        parentSessionId: tagOptional(actorRef._parent?.sessionId),
+        displayName: getActorDisplayName(actorRef),
+        machine,
+        snapshot: safeSerializeSnapshot(actorRef),
+        globalSeq: nextSeq(),
+        timestamp: Date.now()
+      };
+      infoLog2(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 = {
+        type: "XSTATE_SNAPSHOT",
+        sessionId: tag(inspectionEvent.actorRef.sessionId),
+        snapshot: serializeSnapshot(inspectionEvent.snapshot),
+        timestamp: Date.now(),
+        globalSeq: nextSeq()
+      };
+      debugLog2(source, "sending snapshot to transport", summarizeMessage(message));
+      transport.send(message);
+      checkAndNotifyStop(inspectionEvent.actorRef);
+    } else if (inspectionEvent.type === "@xstate.event") {
+      const message = {
+        type: "XSTATE_EVENT",
+        sessionId: tag(inspectionEvent.actorRef.sessionId),
+        // sanitize() returns unknown; the inspected event keeps its { type, ... }
+        // shape, so it is a SerializedEvent after deep-sanitizing.
+        event: sanitize(inspectionEvent.event),
+        snapshotAfter: safeSerializeSnapshot(inspectionEvent.actorRef),
+        timestamp: Date.now(),
+        globalSeq: nextSeq()
+      };
+      debugLog2(source, "sending event to transport", summarizeMessage(message));
+      transport.send(message);
+      checkAndNotifyStop(inspectionEvent.actorRef);
+    } else {
+      debugLog2(
+        source,
+        "ignoring unsupported inspection event",
+        summarizeInspectionEvent(inspectionEvent)
+      );
+    }
+  };
+  function dispose() {
+    infoLog2(source, "disposing inspector", { actorCount: actorRefs.size });
+    unsubscribe();
+    actorRefs.clear();
+    actorMachines.clear();
+  }
+  return { inspect, dispose };
+}
+
+// src/server.ts
+function getAvailablePort(start) {
+  return new Promise((resolve, reject) => {
+    const probe = (0, import_node_net.createServer)();
+    probe.unref();
+    probe.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        resolve(getAvailablePort(start + 1));
+      } else {
+        reject(err);
+      }
+    });
+    probe.listen(start, "127.0.0.1", () => {
+      const port = probe.address().port;
+      probe.close(() => resolve(port));
+    });
+  });
+}
+var OPEN_STATE = 1;
+function summarizeMessage2(message) {
+  const summary = { type: message.type };
+  if ("sessionId" in message) summary.sessionId = message.sessionId;
+  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 debugLog3(message, details) {
+  debugLog("server", message, details);
+}
+function infoLog3(message, details) {
+  infoLog("server", message, details);
+}
+function warnLog3(message, details) {
+  warnLog("server", message, details);
+}
+function stringifyOutgoingMessage(message) {
+  const payload = { ...message, __xstateDevtools: true };
+  try {
+    return JSON.stringify(payload);
+  } catch (error) {
+    warnLog3("failed to stringify adapter message; retrying with sanitized payload", {
+      error,
+      message: summarizeMessage2(message)
+    });
+  }
+  try {
+    return JSON.stringify(sanitize(payload));
+  } catch (error) {
+    warnLog3("dropping adapter message that could not be stringified", {
+      error,
+      message: summarizeMessage2(message)
+    });
+    return null;
+  }
+}
+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;
+  infoLog3("createServerAdapter called", { host, port, bufferSize });
+  const key = `__xstate_devtools_server_${port}__`;
+  const cache = globalThis[key];
+  let server;
+  if (cache) {
+    server = cache;
+    infoLog3("reusing cached WebSocket server", {
+      host,
+      port,
+      clientCount: server.clients.size,
+      bufferedMessages: server.buffer.length
+    });
+    if (bufferSize > server.bufferSize) server.bufferSize = bufferSize;
+  } else {
+    const clients = /* @__PURE__ */ new Set();
+    const dispatchHandlers = /* @__PURE__ */ new Set();
+    const buffer = [];
+    let wss = null;
+    let closed = false;
+    let portResolve;
+    let portReject;
+    const portPromise = new Promise((res, rej) => {
+      portResolve = res;
+      portReject = rej;
+    });
+    server = {
+      clients,
+      dispatchHandlers,
+      buffer,
+      bufferSize,
+      activated: false,
+      port: portPromise,
+      close: () => {
+        closed = true;
+        infoLog3("closing WebSocket server", { host, port, clientCount: clients.size });
+        try {
+          wss?.close();
+        } catch {
+        }
+        clients.clear();
+        dispatchHandlers.clear();
+        buffer.length = 0;
+        delete globalThis[key];
+      }
+    };
+    void (async () => {
+      try {
+        const mod = await import("ws");
+        const WSServer = mod.WebSocketServer ?? mod.Server;
+        if (closed) return;
+        const actualPort = await getAvailablePort(port);
+        if (closed) return;
+        wss = new WSServer({ port: actualPort, host });
+        process.env.XSTATE_DEVTOOLS_PORT = String(actualPort);
+        portResolve(actualPort);
+        infoLog3("WebSocket server listening", { host, port: actualPort });
+        wss.on("connection", (ws) => {
+          infoLog3("panel connected to WebSocket server", {
+            host,
+            port,
+            activated: server.activated,
+            bufferedMessages: server.buffer.length
+          });
+          if (!server.activated) {
+            server.activated = true;
+            infoLog3("flushing bootstrap buffer to first panel", {
+              host,
+              port,
+              bufferedMessages: server.buffer.length
+            });
+            for (const payload of server.buffer) {
+              try {
+                ws.send(payload);
+              } catch {
+              }
+            }
+            server.buffer.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);
+              debugLog3("received dispatch from panel", summarizeMessage2(msg));
+              for (const cb of server.dispatchHandlers) cb(msg);
+            } catch (error) {
+              warnLog3("failed to parse panel message", { error });
+            }
+          });
+          ws.on("close", () => {
+            server.clients.delete(ws);
+            infoLog3("panel disconnected from WebSocket server", {
+              host,
+              port,
+              clientCount: server.clients.size
+            });
+          });
+          ws.on("error", (error) => {
+            server.clients.delete(ws);
+            warnLog3("WebSocket client error", { error });
+          });
+        });
+        wss.on("error", (err) => {
+          warnLog3("WS server error", { host, port, message: err.message });
+        });
+      } catch (e) {
+        portReject(e);
+        warnLog3("could not start server adapter \u2014 install `ws` to enable", {
+          host,
+          port,
+          message: e.message
+        });
+      }
+    })();
+    globalThis[key] = server;
+  }
+  const transport = {
+    send(message) {
+      const payload = stringifyOutgoingMessage(message);
+      if (payload === null) return;
+      if (!server.activated) {
+        if (server.buffer.length >= server.bufferSize) server.buffer.shift();
+        server.buffer.push(payload);
+        debugLog3("buffered outgoing adapter message; no panel connected yet", {
+          bufferedMessages: server.buffer.length,
+          message: summarizeMessage2(message)
+        });
+        return;
+      }
+      let sentCount = 0;
+      for (const ws of server.clients) {
+        if (ws.readyState === OPEN_STATE) {
+          try {
+            ws.send(payload);
+            sentCount += 1;
+          } catch {
+          }
+        }
+      }
+      debugLog3("sent adapter message to connected panels", {
+        sentCount,
+        clientCount: server.clients.size,
+        message: summarizeMessage2(message)
+      });
+    },
+    subscribe(handler) {
+      server.dispatchHandlers.add(handler);
+      debugLog3("registered dispatch handler", { handlerCount: server.dispatchHandlers.size });
+      return () => {
+        server.dispatchHandlers.delete(handler);
+        debugLog3("removed dispatch handler", { handlerCount: server.dispatchHandlers.size });
+      };
+    }
+  };
+  const inspector = createInspector(transport, "srv");
+  return { ...inspector, close: server.close, port: server.port };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createServerAdapter
+});
+//# sourceMappingURL=server.cjs.map