@statelyai/sdk 0.15.0 → 0.16.1

package/README.md

@@ -153,15 +153,14 @@ Resource operations always require a credential.
 
 <!-- createInspector API from src/inspect.ts -->
 
-Stream live actor-system state to the Stately inspector over WebSockets, with support for automatic XState actor adoption and manual actor registration.
+Stream live actor-system state to the hosted Stately inspector. Zero-config
+inspection needs no API key or local relay.
 
 ```ts
 import { createActor } from 'xstate';
 import { createInspector } from '@statelyai/sdk';
 
-const inspector = createInspector({
-  url: 'ws://localhost:4242',
-});
+const inspector = createInspector();
 const { inspect } = inspector;
 
 const actor = createActor(machine, { inspect });
@@ -176,13 +175,35 @@ completed request-scoped runs stay available for inspection.
 
 XState v5 and v6 inspection events normalize to independent actor, event,
 snapshot, and stop observations before crossing the WebSocket protocol.
+`actorId` is system-local; `sessionId` is globally unique.
 Observations captured before the first transport registration replay in order
 after the initial actor-tree baseline. Reconnects use the latest checkpoint.
 In Node, the inspector opens in the default browser automatically. The SDK
-generates a cryptographically random session capability; hosted inspectors open
-without requiring login. The session capability controls access to the live
-session. AI-backed features remain separately authenticated. The Node process
-does not need a Stately API key.
+connects to `wss://sky.stately.ai` and generates a UUID v4 `?r=` room bearer
+capability. Multiple producers and viewers can share that room. Anyone with the
+URL can inspect its data, so keep it private. Hosted replay expires after 24
+hours without activity. Only actor checkpoints and observations are replayed;
+export traffic is live-only, and auth/upload/embed-control messages are rejected.
+AI-backed features remain separately authenticated.
+
+After successful registration, hosted Sky records coarse connection analytics:
+role, normalized browser origin or `unknown`, localhost status, runtime,
+SDK/protocol versions, Cloudflare country, ASN organization, and colo, plus an
+opaque room identifier. The analytics event excludes raw room capabilities, IP
+addresses, actor/session ids, machine names, inspection messages, and payloads.
+Cloudflare operational logs may separately contain the request URL, IP address,
+and request metadata. A source origin can identify a site or customer, so this
+is operational telemetry rather than anonymous data. Pass a self-hosted `url`
+to opt out of Stately-hosted collection.
+
+Set `autoOpen: false`, await `inspector.ready`, and navigate to
+`inspector.inspectorUrl` when a test runner or another process owns the browser.
+`inspectorBaseUrl` targets an inspector UI hosted separately from the WebSocket
+relay. An explicit `url` wins over `STATELY_INSPECT_URL`, which wins over the
+hosted default. See `@statelyai/sdk/protocol` for the versioned message and
+`?r=` query contract. SDK producer registration also reports its SDK version
+and coarse browser, Node, or unknown runtime; it never adds inspection payloads
+to registration metadata.
 
 ### CLI and sync
 
@@ -231,6 +252,22 @@ const embed = createStatelyEmbed({
 });
 ```
 
+For inspection, run your own relay and pass its URL explicitly:
+
+```bash
+npx @statelyai/sdk relay
+```
+
+```ts
+const inspector = createInspector({
+  url: 'ws://localhost:4242',
+  inspectorBaseUrl: 'http://localhost:3000/inspect',
+});
+```
+
+This repository's `packages/sky` is an optional Cloudflare Durable Object
+reference deployment.
+
 Key environment variables for self-hosted deployments:
 
 | Variable                    | Purpose                                           |

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/bin.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { createNodeInspectionRelay } from "./node-relay.mjs";
+
+//#region src/bin.ts
+function readFlag(name, fallback) {
+	const index = process.argv.indexOf(`--${name}`);
+	return index >= 0 ? process.argv[index + 1] ?? fallback : fallback;
+}
+async function main() {
+	const command = process.argv[2];
+	if (command !== "relay") {
+		console.info("Usage: stately-sdk relay [--host 127.0.0.1] [--port 4242]");
+		process.exitCode = command ? 1 : 0;
+		return;
+	}
+	const relay = createNodeInspectionRelay({
+		host: readFlag("host", process.env.STATELY_HOST ?? "127.0.0.1"),
+		port: Number(readFlag("port", process.env.STATELY_PORT ?? "4242")),
+		logger: console
+	});
+	await relay.start();
+	const shutdown = async () => {
+		await relay.stop();
+		process.exit(0);
+	};
+	process.on("SIGINT", () => void shutdown());
+	process.on("SIGTERM", () => void shutdown());
+}
+main().catch((error) => {
+	console.error(error);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/dist/embed.mjs

@@ -1,4 +1,4 @@
-import { a as createPendingExportManager, i as createEventRegistry, n as createPostMessageTransport, o as toInitMessage } from "./transport-D2Ud05yg.mjs";
+import { a as toInitMessage, i as createPendingExportManager, r as createEventRegistry, t as createPostMessageTransport } from "./transport-B_ig9Znn.mjs";
 
 //#region src/embed.ts
 function buildEmbedUrl(options) {

package/dist/index.d.mts

@@ -1,12 +1,12 @@
 import { StatelyApiClientOptions, StatelyApiError, StatelyApiUrlOptions, createStatelyApiClient, createStatelyApiUrl } from "./api.mjs";
 import { _ as serializeJS, c as MachineConfigOptions, d as contextSchemaToTSType, f as eventsSchemaToTSType, g as raw, h as jsonSchemaToTSType, i as CodeGenGraph, l as RawCode, m as graphToXStateTS, o as GraphPatch, p as graphToMachineConfig, t as ActionLocation, u as XStateTSOptions } from "./index-ag6K2iAS.mjs";
 import { C as EventTypeData, S as DigraphNodeConfig, _ as studioMachineConverter, a as StatelyGraphData, b as DigraphConfig, c as StatelyInvoke, d as StudioAction, f as StudioEdge, g as fromStudioMachine, h as StudioNode, i as StatelyGraph, l as StatelyNodeData, m as StudioMachine, o as StatelyGuard, r as StatelyEdgeData, t as StatelyAction, v as toStudioMachine, w as StateNodeJSONData, x as DigraphEdgeConfig, y as DigraphAction } from "./graph-DuOeLGvh.mjs";
-import { CapabilityDeniedCapability, CapabilityDeniedEvent, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, InitOptions, InspectionAction, InspectionSentEvent, InspectionTakenTransition, ProjectEmbedMachine, UploadResult } from "./protocol.mjs";
+import { CapabilityDeniedCapability, CapabilityDeniedEvent, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitOptions, InspectionAction, InspectionSentEvent, InspectionTakenTransition, ProjectEmbedMachine, UploadResult, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
 import { AssetUploadAdapter, AssetUploadContext, AssetUploadRequest, CreateS3AssetUploadAdapterOptions, CreateSupabaseAssetUploadAdapterOptions, S3UploadTarget, SupabaseStorageClient, createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
 import { i as getCredentialToken, n as StatelyCredential, r as createAuthorizationHeader, t as StatelyAuthMode } from "./auth-2Thaw42j.mjs";
 import { AssetConfig, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed } from "./embed.mjs";
-import { _ as createPostMessageTransport, a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as MultiplexedChannelOptions, g as createMultiplexedWebSocketConnection, h as Transport, i as InspectedSnapshot, l as ManualActorOptions, m as MultiplexedWebSocketConnectionOptions, n as CreateInspectorOptions, o as Inspector, p as MultiplexedWebSocketConnection, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector, v as createWebSocketTransport } from "./inspect-DenVP7IE.mjs";
-import { A as Machine, C as StudioMachineRecord, D as VerifyApiKeyResponse, E as UpdateProjectInput, F as ProjectVisibility, I as VerifyResult, L as XStateVersion, M as Project, N as ProjectMachineSummary, O as createStatelyClient, P as ProjectSummary, R as ResourceErrorCode, S as StudioClientOptions, T as UpdateMachineInput, _ as ProjectMachine, a as CreateMachineTemplate, b as StudioApiErrorOptions, c as EnsureProjectInput, d as ExtractedMachine, f as GetMachineOptions, g as ProjectData, h as LegacyUpdateMachineInput, i as CreateMachineInput, j as MachineVersion, k as ExtractedMachines, l as ExtractMachinesInput, m as LegacyProjectVisibility, n as CreateMachineFromDefinitionInput, o as CreateProjectInput, r as CreateMachineFromTemplateInput, s as DEFAULT_STATELY_BASE_URL, t as ConnectedRepo, u as ExtractMachinesResponse, v as RepoType, w as StudioRequestOptions, x as StudioClient, y as StudioApiError } from "./studio-Da5pyxv6.mjs";
+import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, h as createWebSocketTransport, i as InspectedSnapshot, l as ManualActorOptions, m as createPostMessageTransport, n as CreateInspectorOptions, o as Inspector, p as TransportFailure, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-BScvqVcM.mjs";
+import { A as Machine, C as StudioMachineRecord, D as VerifyApiKeyResponse, E as UpdateProjectInput, F as ProjectVisibility, I as VerifyResult, L as XStateVersion, M as Project, N as ProjectMachineSummary, O as createStatelyClient, P as ProjectSummary, R as ResourceErrorCode, S as StudioClientOptions, T as UpdateMachineInput, _ as ProjectMachine, a as CreateMachineTemplate, b as StudioApiErrorOptions, c as EnsureProjectInput, d as ExtractedMachine, f as GetMachineOptions, g as ProjectData, h as LegacyUpdateMachineInput, i as CreateMachineInput, j as MachineVersion, k as ExtractedMachines, l as ExtractMachinesInput, m as LegacyProjectVisibility, n as CreateMachineFromDefinitionInput, o as CreateProjectInput, r as CreateMachineFromTemplateInput, s as DEFAULT_STATELY_BASE_URL, t as ConnectedRepo, u as ExtractMachinesResponse, v as RepoType, w as StudioRequestOptions, x as StudioClient, y as StudioApiError } from "./studio-Bk_u41gu.mjs";
 import { OAuthAuthorizationServerMetadata, OAuthClientRegistrationResponse, OAuthProtectedResourceMetadata, OAuthTokenResponse, PkcePair, buildAuthorizeUrl, createPkcePair, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, refreshToken, registerOAuthClient } from "./oauth.mjs";
 import { PlanSyncOptions, PullSyncResult, PushLocalMachineLinksResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary } from "./sync.mjs";
 import { CreateInspectionRelayOptions, InspectionRelay, InspectionRelayEffect, InspectionRelayPeer, InspectionRelayRole, InspectionRelaySnapshot, createInspectionRelay } from "./relay.mjs";
@@ -32,4 +32,4 @@ declare function findStatelyPragmaAttachments(sourceText: string, fileName?: str
 declare function getStatelyPragma(sourceText: string, fileName?: string, machineIndex?: number): StatelyPragma | undefined;
 declare function upsertStatelyPragma(sourceText: string, id: string, options?: UpsertStatelyPragmaOptions): string;
 //#endregion
-export { type ActionLocation, type AdoptedActor, type AssetConfig, type AssetUploadAdapter, type AssetUploadContext, type AssetUploadRequest, type CapabilityDeniedCapability, type CapabilityDeniedEvent, type CodeGenGraph, type CommentsConfig, type ConnectedRepo, type CreateInspectionRelayOptions, type CreateInspectorOptions, type CreateMachineFromDefinitionInput, type CreateMachineFromTemplateInput, type CreateMachineInput, type CreateMachineTemplate, type CreateProjectInput, type CreateS3AssetUploadAdapterOptions, type CreateSupabaseAssetUploadAdapterOptions, DEFAULT_STATELY_BASE_URL, type DigraphAction, type DigraphConfig, type DigraphEdgeConfig, type DigraphNodeConfig, type EditorCapabilities, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type EnsureProjectInput, type EventTypeData, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type ExtractMachinesInput, type ExtractMachinesResponse, type ExtractedMachine, type ExtractedMachines, type GetMachineOptions, type GraphPatch, INSPECTION_PROTOCOL_VERSION, type InitOptions, type InspectedEvent, type InspectedSnapshot, type InspectedTransition, type InspectionAction, type InspectionRelay, type InspectionRelayEffect, type InspectionRelayPeer, type InspectionRelayRole, type InspectionRelaySnapshot, type InspectionSentEvent, type InspectionTakenTransition, type Inspector, type InspectorEvents, type InspectorInspectionEvent, type LegacyProjectVisibility, type LegacyUpdateMachineInput, type Machine, type MachineConfigOptions, type MachineVersion, type ManualActorOptions, type MultiplexedChannelOptions, type MultiplexedWebSocketConnection, type MultiplexedWebSocketConnectionOptions, type OAuthAuthorizationServerMetadata, type OAuthClientRegistrationResponse, type OAuthProtectedResourceMetadata, type OAuthTokenResponse, type PkcePair, type PlanSyncOptions, type Project, type ProjectData, type ProjectEmbedMachine, type ProjectMachine, type ProjectMachineSummary, type ProjectSummary, type ProjectVisibility, type PullSyncResult, type PushLocalMachineLinksResult, type PushSyncOptions, type PushSyncProjectOptions, type PushSyncResult, RawCode, type RepoType, type ResolvedSyncInput, type ResourceErrorCode, type S3UploadTarget, type StateNodeJSONData, type StatelyAction, type StatelyApiClientOptions, StatelyApiError, type StatelyApiUrlOptions, type StatelyAuthMode, type StatelyCredential, type StatelyEdgeData, type StatelyEmbed, type StatelyEmbedOptions, type StatelyGraph, type StatelyGraphData, type StatelyGuard, type StatelyInvoke, type StatelyNodeData, type StatelyPragma, type StatelyPragmaAttachment, type StudioAction, StudioApiError, type StudioApiErrorOptions, type StudioClient, type StudioClientOptions, type StudioEdge, type StudioMachine, type StudioMachineRecord, type StudioNode, type StudioRequestOptions, type SupabaseStorageClient, type SyncInputFormat, type SyncPlan, type SyncPlanSummary, type Transport, type UpdateMachineInput, type UpdateProjectInput, type UploadResult, type UpsertStatelyPragmaOptions, type VerifyApiKeyResponse, type VerifyResult, type XStateTSOptions, type XStateVersion, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionRelay, createInspector, createMultiplexedWebSocketConnection, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };
+export { type ActionLocation, type AdoptedActor, type AssetConfig, type AssetUploadAdapter, type AssetUploadContext, type AssetUploadRequest, type CapabilityDeniedCapability, type CapabilityDeniedEvent, type CodeGenGraph, type CommentsConfig, type ConnectedRepo, type CreateInspectionRelayOptions, type CreateInspectorOptions, type CreateMachineFromDefinitionInput, type CreateMachineFromTemplateInput, type CreateMachineInput, type CreateMachineTemplate, type CreateProjectInput, type CreateS3AssetUploadAdapterOptions, type CreateSupabaseAssetUploadAdapterOptions, DEFAULT_STATELY_BASE_URL, type DigraphAction, type DigraphConfig, type DigraphEdgeConfig, type DigraphNodeConfig, type EditorCapabilities, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type EnsureProjectInput, type EventTypeData, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type ExtractMachinesInput, type ExtractMachinesResponse, type ExtractedMachine, type ExtractedMachines, type GetMachineOptions, type GraphPatch, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, type InitOptions, type InspectedEvent, type InspectedSnapshot, type InspectedTransition, type InspectionAction, type InspectionRelay, type InspectionRelayEffect, type InspectionRelayPeer, type InspectionRelayRole, type InspectionRelaySnapshot, type InspectionSentEvent, type InspectionTakenTransition, type Inspector, type InspectorEvents, type InspectorInspectionEvent, type LegacyProjectVisibility, type LegacyUpdateMachineInput, type Machine, type MachineConfigOptions, type MachineVersion, type ManualActorOptions, type OAuthAuthorizationServerMetadata, type OAuthClientRegistrationResponse, type OAuthProtectedResourceMetadata, type OAuthTokenResponse, type PkcePair, type PlanSyncOptions, type Project, type ProjectData, type ProjectEmbedMachine, type ProjectMachine, type ProjectMachineSummary, type ProjectSummary, type ProjectVisibility, type PullSyncResult, type PushLocalMachineLinksResult, type PushSyncOptions, type PushSyncProjectOptions, type PushSyncResult, RawCode, type RepoType, type ResolvedSyncInput, type ResourceErrorCode, type S3UploadTarget, type StateNodeJSONData, type StatelyAction, type StatelyApiClientOptions, StatelyApiError, type StatelyApiUrlOptions, type StatelyAuthMode, type StatelyCredential, type StatelyEdgeData, type StatelyEmbed, type StatelyEmbedOptions, type StatelyGraph, type StatelyGraphData, type StatelyGuard, type StatelyInvoke, type StatelyNodeData, type StatelyPragma, type StatelyPragmaAttachment, type StudioAction, StudioApiError, type StudioApiErrorOptions, type StudioClient, type StudioClientOptions, type StudioEdge, type StudioMachine, type StudioMachineRecord, type StudioNode, type StudioRequestOptions, type SupabaseStorageClient, type SyncInputFormat, type SyncPlan, type SyncPlanSummary, type Transport, type TransportFailure, type UpdateMachineInput, type UpdateProjectInput, type UploadResult, type UpsertStatelyPragmaOptions, type VerifyApiKeyResponse, type VerifyResult, type XStateTSOptions, type XStateVersion, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionRelay, createInspectionRoomUrls, createInspector, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getInspectionRoomId, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { n as createPostMessageTransport, r as createWebSocketTransport, t as createMultiplexedWebSocketConnection } from "./transport-D2Ud05yg.mjs";
-import { INSPECTION_PROTOCOL_VERSION } from "./protocol.mjs";
+import { n as createWebSocketTransport, t as createPostMessageTransport } from "./transport-B_ig9Znn.mjs";
+import { INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
 import { createStatelyEmbed } from "./embed.mjs";
 import { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
-import { n as createStatelyInspector, t as createInspector } from "./inspect-DWDTNMEc.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-C3Y_o_Np.mjs";
 import { n as StudioApiError, r as createStatelyClient, t as DEFAULT_STATELY_BASE_URL } from "./studio-txdyJHD7.mjs";
 import { a as RawCode, c as eventsSchemaToTSType, d as jsonSchemaToTSType, f as raw, l as graphToMachineConfig, n as getStatelyPragma, o as contextSchemaToTSType, p as serializeJS, r as upsertStatelyPragma, t as findStatelyPragmaAttachments, u as graphToXStateTS } from "./statelyPragma-Bm9O4XV6.mjs";
 import { createAuthorizationHeader, getCredentialToken } from "./auth.mjs";
@@ -11,4 +11,4 @@ import { StatelyApiError, createStatelyApiClient, createStatelyApiUrl } from "./
 import { fromStudioMachine, studioMachineConverter, toStudioMachine } from "./graph.mjs";
 import { createInspectionRelay } from "./relay.mjs";
 
-export { DEFAULT_STATELY_BASE_URL, INSPECTION_PROTOCOL_VERSION, RawCode, StatelyApiError, StudioApiError, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionRelay, createInspector, createMultiplexedWebSocketConnection, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };
+export { DEFAULT_STATELY_BASE_URL, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, RawCode, StatelyApiError, StudioApiError, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionRelay, createInspectionRoomUrls, createInspector, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getInspectionRoomId, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };

package/dist/{inspect-DenVP7IE.d.mts → inspect-BScvqVcM.d.mts}

@@ -1,12 +1,17 @@
-import { EditorCapabilities, EmbedEventMap, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition, ProtocolMessage } from "./protocol.mjs";
+import { EditorCapabilities, EmbedEventMap, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionClientMetadata, InspectionSentEvent, InspectionTakenTransition, ProtocolMessage } from "./protocol.mjs";
 
 //#region src/transport.d.ts
+interface TransportFailure {
+  code: string;
+  message: string;
+}
 interface Transport {
   send(msg: ProtocolMessage): void;
   onMessage(handler: (msg: ProtocolMessage) => void): () => void;
   destroy(): void;
   readonly ready: boolean;
   onReady(handler: () => void): () => void;
+  onError?(handler: (failure: TransportFailure) => void): () => void;
 }
 interface PostMessageTransportOptions {
   iframe: HTMLIFrameElement;
@@ -17,51 +22,15 @@ interface PostMessageTransportOptions {
 declare function createPostMessageTransport(options: PostMessageTransportOptions): Transport;
 interface WebSocketTransportOptions {
   url: string;
-  role: 'client' | 'viz';
-  sessionId: string;
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
+  role: 'producer' | 'viewer';
+  producerId?: string;
+  metadata?: InspectionClientMetadata;
   /** Reconnect on disconnect. Default true. */
   reconnect?: boolean;
-  /** Max reconnect attempts. Default 10. */
+  /** Max reconnect attempts after the first connection. Default 10. */
   maxReconnectAttempts?: number;
 }
 declare function createWebSocketTransport(options: WebSocketTransportOptions): Transport;
-interface MultiplexedWebSocketConnectionOptions {
-  url: string;
-  role: 'client' | 'viz';
-  /** First (primary) session to register on connect. */
-  sessionId: string;
-  /** Metadata for the primary session. */
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
-  reconnect?: boolean;
-  maxReconnectAttempts?: number;
-}
-interface MultiplexedChannelOptions {
-  /** Session id this channel targets. */
-  sessionId: string;
-  /** Optional metadata for this session. */
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
-}
-interface MultiplexedWebSocketConnection {
-  /** Open a channel for a sessionId. Re-opening an existing session returns the same channel. */
-  openChannel(options: MultiplexedChannelOptions): Transport;
-  /** Close the connection and all its channels. */
-  destroy(): void;
-  /** Whether the underlying WebSocket is connected + the primary session is registered. */
-  readonly ready: boolean;
-  /** Primary session id (first registered). */
-  readonly primarySessionId: string;
-}
-declare function createMultiplexedWebSocketConnection(options: MultiplexedWebSocketConnectionOptions): MultiplexedWebSocketConnection;
 //#endregion
 //#region src/inspect.d.ts
 interface MinimalActorRef {
@@ -93,14 +62,14 @@ interface InspectorInspectionEvent {
   readonly actorRef: unknown;
 }
 interface AdoptedActor {
-  /** `actor.sessionId` from xstate. Unique across the system. */
+  /** Globally unique `actor.sessionId` from xstate. */
+  sessionId: string;
+  /** System-local `actor.id`. */
   actorId: string;
   /** Parent actor's sessionId, or `null` for the root. */
-  parentActorId: string | null;
-  /** Root actor's sessionId (equal to `actorId` for the root). */
-  rootId: string;
-  /** `actor.id` — a human-facing local name. */
-  id: string;
+  parentSessionId: string | null;
+  /** Root actor's sessionId. */
+  rootSessionId: string;
   /** `actor.systemId`, if registered under one. */
   systemId: string | undefined;
   /** Latest serialized snapshot streamed for this actor. */
@@ -112,8 +81,8 @@ interface AdoptedActor {
 }
 /** One observed snapshot, independent of the XState inspection version. */
 interface InspectedSnapshot {
-  actorId: string;
-  sourceActorId: string | null;
+  sessionId: string;
+  sourceSessionId: string | null;
   /** Previously observed snapshot, which may not be the immediate predecessor. */
   previousSnapshot: unknown | null;
   snapshot: unknown;
@@ -127,8 +96,8 @@ interface InspectedSnapshot {
 type InspectedTransition = InspectedSnapshot;
 /** One observed event, independent of whether processing produced a snapshot. */
 interface InspectedEvent {
-  actorId: string;
-  sourceActorId: string | null;
+  sessionId: string;
+  sourceSessionId: string | null;
   event: unknown;
 }
 interface InspectorEvents {
@@ -136,7 +105,7 @@ interface InspectorEvents {
   event: InspectedEvent;
   snapshot: InspectedSnapshot;
   stop: {
-    actorId: string;
+    sessionId: string;
   };
   /** @deprecated Use `actor`. */
   register: AdoptedActor;
@@ -144,7 +113,7 @@ interface InspectorEvents {
   transition: InspectedSnapshot;
   /** @deprecated Use `stop`. */
   stopped: {
-    actorId: string;
+    sessionId: string;
   };
   error: EmbedEventMap['error'];
 }
@@ -161,15 +130,27 @@ interface ManualActorOptions {
   systemId?: string;
 }
 interface CreateInspectorOptions {
-  /** WebSocket URL of the devtools server. Default: `'ws://localhost:4242'`. */
+  /**
+   * WebSocket relay base URL. Defaults to `STATELY_INSPECT_URL`, then
+   * `wss://sky.stately.ai`. Passing this option always wins.
+   */
   url?: string;
+  /** Unguessable inspection room capability. Defaults to a random UUID. */
+  roomId?: string;
+  /** Stable identity for this producer connection. Defaults to a random UUID. */
+  producerId?: string;
+  /**
+   * Inspector UI base URL when hosted separately from the WebSocket relay. The
+   * inspector adds `ws` and `r` query parameters. When omitted, the URL
+   * is derived from the relay URL by replacing `ws` with `http`.
+   */
+  inspectorBaseUrl?: string;
   /** Auto-open browser to visualizer. Default: `true`. */
   autoOpen?: boolean;
   /**
-   * Relay session capability. Defaults to a cryptographically random UUID.
-   * This is the `?session=<id>` value the visualizer connects with. Custom
-   * values used with a hosted relay must be unguessable.
+   * Legacy name for the unguessable room capability.
    */
+  /** @deprecated Use {@link roomId}. */
   sessionId?: string;
   /** Display name for this system in the visualizer. */
   name?: string;
@@ -184,7 +165,9 @@ interface CreateInspectorOptions {
    * `actor.logic.config`. Return `null` for non-machine actors.
    */
   extractMachineConfig?: (actor: any, source?: unknown) => unknown;
-  /** Selected actor id to focus on first. Defaults to the first inspected root. */
+  /** Selected actor session id to focus on first. */
+  selectedSessionId?: string;
+  /** @deprecated Use {@link selectedSessionId}. */
   selectedActorId?: string;
   /** Panel layout forwarded into the system init message. */
   panels?: {
@@ -197,17 +180,26 @@ interface CreateInspectorOptions {
   depth?: number;
   capabilities?: EditorCapabilities;
   /**
-   * Advanced: inject a pre-built transport (e.g. a channel from a
-   * multiplexed connection). When provided, `url`/`name` are ignored and the
-   * inspector shares that transport instead of opening its own WebSocket.
+   * Advanced: inject a pre-built transport. When provided, `url`/`name` are
+   * ignored and no WebSocket or browser URL is created.
    */
   transport?: Transport;
 }
 interface Inspector {
-  /** Snapshot of currently-adopted actors keyed by `actorId`. */
+  /** Snapshot of currently-adopted actors keyed by global `sessionId`. */
   readonly actors: ReadonlyMap<string, AdoptedActor>;
-  /** The relay sessionId this inspector registered under. */
+  /** Unguessable inspection room capability. */
+  readonly roomId: string;
+  /** Complete WebSocket URL for this room. */
+  readonly relayUrl: string | null;
+  /** Identity stamped onto this producer's protocol messages. */
+  readonly producerId: string;
+  /** @deprecated Use {@link roomId}. */
   readonly sessionId: string;
+  /** URL that opens the inspector UI for this live session. */
+  readonly inspectorUrl: string | null;
+  /** Resolves after the first relay registration and initial-state flush. */
+  readonly ready: Promise<void>;
   /**
    * XState `inspect` option callback. Pass directly to `createActor` or another
    * host that creates actors internally.
@@ -251,4 +243,4 @@ declare function createInspector(options?: CreateInspectorOptions): Inspector;
 /** @deprecated Use {@link createInspector}. */
 declare const createStatelyInspector: typeof createInspector;
 //#endregion
-export { createPostMessageTransport as _, InspectedTransition as a, InspectorInspectionEvent as c, createStatelyInspector as d, MultiplexedChannelOptions as f, createMultiplexedWebSocketConnection as g, Transport as h, InspectedSnapshot as i, ManualActorOptions as l, MultiplexedWebSocketConnectionOptions as m, CreateInspectorOptions as n, Inspector as o, MultiplexedWebSocketConnection as p, InspectedEvent as r, InspectorEvents as s, AdoptedActor as t, createInspector as u, createWebSocketTransport as v };
+export { InspectedTransition as a, InspectorInspectionEvent as c, createStatelyInspector as d, Transport as f, createWebSocketTransport as h, InspectedSnapshot as i, ManualActorOptions as l, createPostMessageTransport as m, CreateInspectorOptions as n, Inspector as o, TransportFailure as p, InspectedEvent as r, InspectorEvents as s, AdoptedActor as t, createInspector as u };